This is manual.info, produced by makeinfo version 4.8 from manual.texi. START-INFO-DIR-ENTRY * mysql: (mysql). MySQL documentation. END-INFO-DIR-ENTRY  File: manual.info, Node: Top, Next: preface, Prev: (dir), Up: (dir) * Menu: * preface:: Preface and Legal Notices * introduction:: General Information * installing:: Installing and Upgrading MySQL * tutorial:: Tutorial * programs:: MySQL Programs * server-administration:: MySQL Server Administration * security:: Security * backup-and-recovery:: Backup and Recovery * optimization:: Optimization * language-structure:: Language Structure * globalization:: Globalization * data-types:: Data Types * functions:: Functions and Operators * sql-syntax:: SQL Statement Syntax * storage-engines:: Storage Engines * ha-overview:: High Availability and Scalability * replication:: Replication * mysql-cluster:: MySQL Cluster NDB 6.1 - 7.1 * partitioning:: Partitioning * stored-programs-views:: Stored Programs and Views * information-schema:: `INFORMATION_SCHEMA' Tables * connectors-apis:: Connectors and APIs * extending-mysql:: Extending MySQL * mysql-enterprise:: MySQL Enterprise Edition * workbench:: MySQL Workbench * mysql-for-excel:: MySQL for Excel * licenses-third-party:: Licenses for Third-Party Components * faqs:: MySQL 5.1 Frequently Asked Questions * error-handling:: Errors, Error Codes, and Common Problems * news:: MySQL Release Notes * restrictions:: Restrictions and Limits  File: manual.info, Node: preface, Next: introduction, Prev: Top, Up: Top Preface and Legal Notices ************************* This is the Reference Manual for the MySQL Database System, version 5.1, through release 5.1.73. Differences between minor versions of MySQL 5.1 are noted in the present text with reference to release numbers (5.1.X). For license information, see the Legal Notices. This product may contain third-party code. For license information on third-party code, see *Note licenses-third-party::. 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.1 and previous versions. If you are using an earlier release of the MySQL software, please refer to the appropriate manual. For example, `MySQL 5.0 Reference Manual' (http://dev.mysql.com/doc/refman/5.0/en/) covers the 5.0 series of MySQL software releases. If you are using MySQL 5.5, please refer to the `MySQL 5.5 Reference Manual' (http://dev.mysql.com/doc/refman/5.5/en/). *Legal Notices* Copyright (C) 1997, 2013, 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 software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software 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 which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications. 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 without Oracle's express written authorization. Other names may be trademarks of their respective owners. This software and documentation may provide access to or information on 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. 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. This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this material is subject to the terms and conditions of your Oracle Software License and Service Agreement, which has been executed and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle or as specifically provided below. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates. 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. For more information on the terms of this license, or for details on how the MySQL documentation is built and produced, please visit MySQL Contact & Questions (http://dev.mysql.com/contact/). For additional licensing information, including licenses for third-party libraries used by MySQL products, see *Note Top::. For help with using MySQL, please visit either the MySQL Forums (http://forums.mysql.com) or MySQL Mailing Lists (http://lists.mysql.com) where you can discuss your issues with other MySQL users. For additional documentation on MySQL products, including translations of the documentation into other languages, and downloadable versions in variety of formats, including HTML and PDF formats, see the MySQL Documentation Library (http://dev.mysql.com/doc).  File: manual.info, Node: introduction, Next: installing, Prev: preface, Up: Top 1 General Information ********************* * Menu: * manual-info:: About This Manual * manual-conventions:: Typographical and Syntax Conventions * what-is:: Overview of the MySQL Database Management System * mysql-nutshell:: What Is New in MySQL 5.1 * development-history:: MySQL Development History * information-sources:: MySQL Information Sources * bug-reports:: How to Report Bugs or Problems * compatibility:: MySQL Standards Compliance * credits:: Credits 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 *Note features::. * For an overview of new MySQL features, see *Note mysql-nutshell::. For information about the changes in each version, see the Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/). * For installation instructions, see *Note installing::. For information about upgrading MySQL, see *Note upgrading::. * For a tutorial introduction to the MySQL Database Server, see *Note tutorial::. * For information about configuring and administering MySQL Server, see *Note server-administration::. * For information about security in MySQL, see *Note security::. * For information about setting up replication servers, see *Note replication::. * For information about MySQL Enterprise, the commercial MySQL release with advanced features and management tools, see *Note mysql-enterprise::. * For answers to a number of questions that are often asked concerning the MySQL Database Server and its capabilities, see *Note faqs::. * For a history of new features and bugfixes, see the Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/). *Important*: To report problems or bugs, please use the instructions at *Note bug-reports::. If you find a sensitive security bug in MySQL Server, please let us know immediately by sending an email message to . Exception: Support customers should report all problems, including security bugs, to Oracle Support.  File: manual.info, Node: manual-info, Next: manual-conventions, Prev: introduction, Up: introduction 1.1 About This Manual ===================== This is the Reference Manual for the MySQL Database System, version 5.1, through release 5.1.73. Differences between minor versions of MySQL 5.1 are noted in the present text with reference to release numbers (5.1.X). For license information, see the Legal Notices. This product may contain third-party code. For license information on third-party code, see *Note licenses-third-party::. 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.1 and previous versions. If you are using an earlier release of the MySQL software, please refer to the appropriate manual. For example, `MySQL 5.0 Reference Manual' (http://dev.mysql.com/doc/refman/5.0/en/) covers the 5.0 series of MySQL software releases. If you are using MySQL 5.5, please refer to the `MySQL 5.5 Reference Manual' (http://dev.mysql.com/doc/refman/5.5/en/). 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 *Note mailing-lists::, and *Note 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 Paul DuBois, Stefan Hinz, Philip Olson, Daniel Price, Daniel So, and Jon Stephens.  File: manual.info, Node: manual-conventions, Next: what-is, Prev: manual-info, Up: introduction 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 *Note `FLUSH PRIVILEGES': flush. 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 *Note `mysql': mysql. (the MySQL command-line client program) and *Note `mysqld': 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 *Note `mysql': 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 *Note `mysql': 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, *Note `SELECT ... INTO OUTFILE': select. is shorthand for the form of *Note `SELECT': 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  File: manual.info, Node: what-is, Next: mysql-nutshell, Prev: manual-conventions, Up: introduction 1.3 Overview of the MySQL Database Management System ==================================================== * Menu: * what-is-mysql:: What is MySQL? * features:: The Main Features of MySQL * history:: History of MySQL  File: manual.info, Node: what-is-mysql, Next: features, Prev: what-is, Up: what-is 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 Web site (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. You can find a performance comparison of MySQL Server with other database managers on our benchmark page. See *Note mysql-benchmarks::. 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 backends, 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.  File: manual.info, Node: features, Next: history, Prev: what-is-mysql, Up: what-is 1.3.2 The Main Features of MySQL -------------------------------- This section describes some of the important characteristics of the MySQL Database Software. See also *Note development-history::. 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 5.6: MySQL 5.6 in a Nutshell (http://dev.mysql.com/doc/refman/5.6/en/mysql-nutshell.html) * MySQL 5.5: MySQL 5.5 in a Nutshell (http://dev.mysql.com/doc/refman/5.5/en/mysql-nutshell.html) * MySQL 5.1: MySQL 5.1 in a Nutshell (http://dev.mysql.com/doc/refman/5.1/en/mysql-nutshell.html) * MySQL 5.0: MySQL 5.0 in a Nutshell (http://dev.mysql.com/doc/refman/5.0/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 *Note supported-os::. * 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, *Note `FLOAT': floating-point-types, *Note `DOUBLE': floating-point-types, *Note `CHAR': char, *Note `VARCHAR': char, *Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, *Note `TEXT': blob, *Note `BLOB': blob, *Note `DATE': datetime, *Note `TIME': time, *Note `DATETIME': datetime, *Note `TIMESTAMP': datetime, *Note `YEAR': year, *Note `SET': set, *Note `ENUM': enum, and OpenGIS spatial types. See *Note data-types::. * Fixed-length and variable-length string types. * Statements and Functions: * * Full operator and function support in the *Note `SELECT': 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 *Note `DELETE': delete, *Note `INSERT': insert, *Note `REPLACE': replace, and *Note `UPDATE': 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 *Note `SHOW': show. statements that retrieve information about databases, storage engines, tables, and indexes. MySQL 5.0 adds support for the `INFORMATION_SCHEMA' database, implemented according to standard SQL. * An *Note `EXPLAIN': 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 *Note reserved-words::. * 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 (32 before MySQL 4.1.2). Each index may consist of 1 to 16 columns or parts of columns. The maximum index width is 767 bytes for `InnoDB' tables, or 1000 for `MyISAM'; before MySQL 4.1.2, the limit is 500 bytes. An index may use a prefix of a column for *Note `CHAR': char, *Note `VARCHAR': char, *Note `BLOB': blob, or *Note `TEXT': blob. 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 in the NT family (NT, 2000, XP, 2003, or Vista), clients can connect using named pipes if the server is started with the `--enable-named-pipe' option. In MySQL 4.1 and higher, 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 *Note 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 *Note connector-odbc::. * 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 *Note connector-j::. * 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 *Note connector-net::. * Localization: * * The server can provide error messages to clients in many languages. See *Note error-message-language::. * Full support for several different character sets, including `latin1' (cp1252), `german', `big5', `ujis', and more. For example, the Scandinavian characters ``aa'', ``a"'' and ``o"'' are permitted in table and column names. Unicode support is available as of MySQL 4.1. * All data is saved in the chosen character set. * Sorting and comparisons are done according to the chosen character set and collation (using `latin1' and Swedish collation by default). It is possible to change this when the MySQL server is started. 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. * As of MySQL 4.1, the server time zone can be changed dynamically, and individual clients can specify their own time zone. *Note time-zone-support::. * Clients and Tools: * * MySQL includes several client and utility programs. These include both command-line programs such as *Note `mysqldump': mysqldump. and *Note `mysqladmin': mysqladmin, and graphical programs such as *Note MySQL Workbench: 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 *Note `mysqlcheck': mysqlcheck. client. MySQL also includes *Note `myisamchk': myisamchk, a very fast command-line utility for performing these operations on `MyISAM' tables. See *Note programs::. * MySQL programs can be invoked with the `--help' or `-?' option to obtain online assistance.  File: manual.info, Node: history, Prev: features, Up: what-is 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.  File: manual.info, Node: mysql-nutshell, Next: development-history, Prev: what-is, Up: introduction 1.4 What Is New in MySQL 5.1 ============================ This section summarizes what has been added to MySQL 5.1 and what has been deprecated for further use. * Added Features * The following features have been added to MySQL 5.1: * Partitioning This capability enables distributing portions of individual tables across a file system, according to rules which can be set when the table is created. In effect, different portions of a table are stored as separate tables in different locations, but from the user point of view, the partitioned table is still a single table. Syntactically, this implements a number of new extensions to the *Note `CREATE TABLE': create-table, *Note `ALTER TABLE': alter-table, and `EXPLAIN ... SELECT' statements. As of MySQL 5.1.6, queries against partitioned tables can take advantage of _partition pruning_. In some cases, this can result in query execution that is an order of magnitude faster than the same query against a nonpartitioned version of the same table. See *Note partitioning::, for further information on this functionality. (Author: Mikael Ronstro"m) * Row-based replication Replication capabilities in MySQL originally were based on propagation of SQL statements from master to slave. This is called _statement-based replication_. As of MySQL 5.1.5, another basis for replication is available. This is called _row-based replication_. Instead of sending SQL statements to the slave, the master writes events to its binary log that indicate how individual table rows are effected. As of MySQL 5.1.8, a third option is available: _mixed_. This will use statement-based replication by default, and only switch to row-based replication in particular cases. See *Note replication-formats::. (Authors: Lars Thalmann, Guilhem Bichot, Mats Kindahl) * Plugin API MySQL 5.1 adds support for a very flexible plugin API that enables loading and unloading of various components at runtime, without restarting the server. Although the work on this is not finished yet, _plugin full-text parsers_ are a first step in this direction. This permits users to implement their own input filter on the indexed text, enabling full-text search capability on arbitrary data such as PDF files or other document formats. A pre-parser full-text plugin performs the actual parsing and extraction of the text and hands it over to the built-in MySQL full-text search. See *Note plugin-api::. (Author: Sergey Vojtovich) * Event scheduler MySQL Events are tasks that run according to a schedule. 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. See *Note events::. (Author: Andrey Hristov) * Server log tables Before MySQL 5.1, the server writes general query log and slow query log entries to log files. As of MySQL 5.1, the server's logging capabilities for these logs are more flexible. Log entries can be written to log files (as before) or to the `general_log' and `slow_log' tables in the `mysql' database. If logging is enabled, either or both destinations can be selected. The `--log-output' option controls the destination or destinations of log output. See *Note log-destinations::. (Author: Petr Chardin) * Upgrade program The *Note `mysql_upgrade': mysql-upgrade. program (available as of MySQL 5.1.7) checks all existing tables for incompatibilities with the current version of MySQL Server and repairs them if necessary. This program should be run for each MySQL upgrade. See *Note mysql-upgrade::. (Authors: Alexey Botchkov, Mikael Widenius) * MySQL Cluster MySQL Cluster is now released as a separate product, based on MySQL 5.1 but with the addition of the *Note `NDBCLUSTER': mysql-cluster. storage engine. Clustering support is no longer available in mainline MySQL 5.1 releases. MySQL Cluster releases are identified by a 3-part NDB version number; currently, the MySQL Cluster NDB 6.3, MySQL Cluster NDB 7.0, and MySQL Cluster NDB 7.1 release series are available for production use. Some of the changes in MySQL Cluster since MySQL 5.0 are listed here: * MySQL Cluster replication Replication between MySQL Clusters is now supported. It is now also possible to replicate between a MySQL Cluster and a noncluster database. See *Note mysql-cluster-replication::. * MySQL Cluster disk data storage Formerly, the *Note `NDBCLUSTER': mysql-cluster. storage engine was strictly in-memory; now, it is possible to store Cluster data (but not indexes) on disk. This enables MySQL Cluster to scale upward with fewer hardware (RAM) requirements than previously. In addition, the Disk Data implementation includes a new `no-steal' restoration algorithm for fast node restarts when storing very large amounts of data (terabyte range). See *Note mysql-cluster-disk-data::, for more information. * Improved backups for MySQL Cluster A fault arising in a single data node during a Cluster backup no longer causes the entire backup to be aborted, as occurred in previous versions of MySQL Cluster. Many other new features and improvements have been made to the *Note `NDBCLUSTER': mysql-cluster. storage engine in MySQL Cluster NDB 7.0 and MySQL Cluster NDB 7.1; for more information about these, see *Note mysql-cluster-development::. * Backup of tablespaces The *Note `mysqldump': mysqldump. utility now supports an option for dumping tablespaces. Use `-Y' or `--all-tablespaces' to enable this functionality. * Improvements to `INFORMATION_SCHEMA' MySQL 5.1 provides much more information in its metadata database than was available in MySQL 5.0. New tables in the `INFORMATION_SCHEMA' database include *Note `FILES': files-table, *Note `EVENTS': events-table, *Note `PARTITIONS': partitions-table, *Note `PROCESSLIST': processlist-table, *Note `ENGINES': engines-table, and *Note `PLUGINS': plugins-table. * XML functions with XPath support `ExtractValue()' returns the content of a fragment of XML matching a given XPath expression. `UpdateXML()' replaces the element selected from a fragment of XML by an XPath expression supplied by the user with a second XML fragment (also user-supplied), and returns the modified XML. See *Note xml-functions::. (Author: Alexander Barkov) * Load emulator The *Note `mysqlslap': mysqlslap. program is designed to emulate client load for a MySQL server and report the timing of each stage. It works as if multiple clients were accessing the server. See *Note mysqlslap::. (Authors: Patrick Galbraith, Brian Aker) * Deprecated Features * The following constructs are deprecated in MySQL 5.1 and are removed as of MySQL 5.5. Where alternatives are shown, applications should be updated to use them. * The `log_bin_trust_routine_creators' system variable (use `log_bin_trust_function_creators'). * The `table_type' system variable (use `storage_engine'). * The `TYPE' table option to specify the storage engine for *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. (use `ENGINE'). * The `SHOW TABLE TYPES' SQL statement (use *Note `SHOW ENGINES': show-engines.). * The *Note `SHOW INNODB STATUS': show-innodb-status. and `SHOW MUTEX STATUS' SQL statements (use *Note `SHOW ENGINE INNODB STATUS': show-engine. *Note `SHOW ENGINE INNODB MUTEX': show-engine.). * The `SHOW PLUGIN' SQL statement (use *Note `SHOW PLUGINS': show-plugins.). * The `LOAD TABLE ... FROM MASTER' and `LOAD DATA FROM MASTER' SQL statements (use *Note `mysqldump': mysqldump. or *Note `mysqlhotcopy': mysqlhotcopy. to dump tables and *Note `mysql': mysql. to reload dump files). * The *Note `BACKUP TABLE': backup-table. and *Note `RESTORE TABLE': restore-table. SQL statements (use *Note `mysqldump': mysqldump. or *Note `mysqlhotcopy': mysqlhotcopy. to dump tables and *Note `mysql': mysql. to reload dump files). * *Note `TIMESTAMP(N)': datetime. data type: The ability to specify a display width of N (use without N). * The `--master-XXX' server options to set replication parameters (use the *Note `CHANGE MASTER TO': change-master-to. statement instead): `--master-host', `--master-user', `--master-password', `--master-port', `--master-connect-retry', `--master-ssl', `--master-ssl-ca', `--master-ssl-capath', `--master-ssl-cert', `--master-ssl-cipher', `--master-ssl-key'.  File: manual.info, Node: development-history, Next: information-sources, Prev: mysql-nutshell, Up: introduction 1.5 MySQL Development History ============================= This section describes the general MySQL development history, provides an overview about features that have been implemented in previous series and that are new in MySQL 5.1, the release series covered in this manual. The maturity level this release series is general availability. Information about maturity levels can be found in *Note choosing-version::. Before upgrading from one release series to the next, please see the notes in *Note upgrading::. The most requested features and the versions in which they were implemented are summarized in the following table. This table summarizes the most requested MySQL features and the versions in which they were implemented. Feature MySQL Series Unions 4.0 Subqueries 4.1 R-trees 4.1 (for the `MyISAM' storage engine) Stored procedures and 5.0 functions Views 5.0 Cursors 5.0 XA transactions 5.0 Triggers 5.0 and 5.1 Event scheduler 5.1 Partitioning 5.1 Pluggable storage 5.1 engine API Plugin API 5.1 Row-based replication 5.1 Server log tables 5.1 Scalability and 5.1 (with InnoDB Plugin) performance improvements  File: manual.info, Node: information-sources, Next: bug-reports, Prev: development-history, Up: introduction 1.6 MySQL Information Sources ============================= * Menu: * mailing-lists:: MySQL Mailing Lists * forums:: MySQL Community Support at the MySQL Forums * irc:: MySQL Community Support on Internet Relay Chat (IRC) * mysql-enterprise-information:: MySQL Enterprise This section lists sources of additional information that you may find helpful, such as the MySQL mailing lists and user forums, and Internet Relay Chat.  File: manual.info, Node: mailing-lists, Next: forums, Prev: information-sources, Up: information-sources 1.6.1 MySQL Mailing Lists ------------------------- * Menu: * mailing-list-use:: Guidelines for Using the 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 *Note 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. * `' A French mailing list. * `' A Korean mailing list. To subscribe, email `subscribe mysql your@email.address' to this list. * `' 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/'. * `' A Portuguese mailing list. To subscribe, email `subscribe mysql-br your@email.address' to this list. * `' A Spanish mailing list. To subscribe, email `subscribe mysql your@email.address' to this list.  File: manual.info, Node: mailing-list-use, Prev: mailing-lists, Up: mailing-lists 1.6.1.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.  File: manual.info, Node: forums, Next: irc, Prev: mailing-lists, Up: information-sources 1.6.2 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  File: manual.info, Node: irc, Next: mysql-enterprise-information, Prev: forums, Up: information-sources 1.6.3 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. If you are looking for IRC client software to connect to an IRC network, take a look at `xChat' (`http://www.xchat.org/'). X-Chat (GPL licensed) is available for Unix as well as for Windows platforms (a free Windows build of X-Chat is available at `http://www.silverex.org/download/').  File: manual.info, Node: mysql-enterprise-information, Prev: irc, Up: information-sources 1.6.4 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/).  File: manual.info, Node: bug-reports, Next: compatibility, Prev: information-sources, Up: introduction 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 *Note 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 *Note 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 Web site. 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 . 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. *Note 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 *Note 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 *Note connector-odbc-support-bug-report::. If your report includes long query output lines from test cases that you run with the *Note `mysql': mysql. command-line tool, you can make the output more readable by using the `--vertical' option or the `\G' statement terminator. The *Note `EXPLAIN SELECT': explain. 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.0.19). You can find out which version you are running by executing *Note `mysqladmin version': mysqladmin. The *Note `mysqladmin': 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. * 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 *Note `mysqld': mysqld. died, you should also report the statement that crashed *Note `mysqld': mysqld. You can usually get this information by running *Note `mysqld': mysqld. with query logging enabled, and then looking in the log after *Note `mysqld': mysqld. crashes. See *Note 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 *Note `SHOW CREATE PROCEDURE': show-create-procedure. or *Note `SHOW CREATE FUNCTION': 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 *Note `SELECT': select. statements, you should always include the output of `EXPLAIN SELECT ...', and at least the number of rows that the *Note `SELECT': 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 *Note `mysql': 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 mysql> EXPLAIN SELECT ...\G mysql> FLUSH STATUS; mysql> SELECT ...; mysql> SHOW STATUS; * If a bug or problem occurs while running *Note `mysqld': 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 *Note `mysqladmin variables extended-status processlist': mysqladmin. 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 *Note `mysqldump': 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 *Note `mysqld': mysqld. server, as well as the options that you use to run any MySQL client programs. The options to programs such as *Note `mysqld': mysqld. and *Note `mysql': 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 *Note `mysqlaccess': mysqlaccess, the output of *Note `mysqladmin reload': mysqladmin, and all the error messages you get when trying to connect. When you test your privileges, you should first run *Note `mysqlaccess': mysqlaccess. After this, execute *Note `mysqladmin reload version': mysqladmin. and try to connect with the program that gives you trouble. *Note `mysqlaccess': mysqlaccess. can be found in the `bin' directory under your MySQL installation directory. * 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 *Note `CHECK TABLE': 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 *Note `REPAIR TABLE': repair-table. or with *Note `myisamchk': myisamchk. See *Note 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 *Note 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 *Note error-log::. Please include any relevant information from this file in your bug report. Normally *Note `mysqld': mysqld. should _never_ crash a table if nothing killed it in the middle of an update. If you can find the cause of *Note `mysqld': mysqld. dying, it is much easier for us to provide you with a fix for the problem. See *Note 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 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 *Note which-version::.  File: manual.info, Node: compatibility, Next: credits, Prev: bug-reports, Up: introduction 1.8 MySQL Standards Compliance ============================== * Menu: * standards:: What Standards MySQL Follows * sql-mode:: Selecting SQL Modes * ansi-mode:: Running MySQL in ANSI Mode * extensions-to-ansi:: MySQL Extensions to Standard SQL * differences-from-ansi:: MySQL Differences from Standard SQL * constraints:: How MySQL Deals with Constraints 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 *Note `HANDLER': handler. interface is an example of this strategy. See *Note 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. Currently, we are not targeting real-time support, although MySQL replication capabilities offer significant functionality. MySQL supports high-availability database clustering using the *Note `NDBCLUSTER': mysql-cluster. storage engine. See *Note mysql-cluster::. We are implementing XML functionality beginning in MySQL 5.1, which supports most of the W3C XPath standard. See *Note xml-functions::.  File: manual.info, Node: standards, Next: sql-mode, Prev: compatibility, Up: compatibility 1.8.1 What Standards MySQL Follows ---------------------------------- Our aim is to support the full ANSI/ISO SQL standard, but without making concessions to speed and quality of the code. ODBC levels 0 to 3.51.  File: manual.info, Node: sql-mode, Next: ansi-mode, Prev: standards, Up: compatibility 1.8.2 Selecting SQL Modes ------------------------- The MySQL server can operate in different SQL modes, and can apply these modes differentially for different clients. This capability enables each application to tailor the server's operating mode to its own requirements. SQL modes control aspects of server operation such as 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. You can set the default SQL mode by starting *Note `mysqld': mysqld. with the `--sql-mode="MODE_VALUE"' option. You can also change the mode at runtime by setting the `sql_mode' system variable with a *Note `SET [GLOBAL|SESSION] sql_mode='MODE_VALUE'': set-statement. statement. For more information on setting the SQL mode, see *Note server-sql-mode::.  File: manual.info, Node: ansi-mode, Next: extensions-to-ansi, Prev: sql-mode, Up: compatibility 1.8.3 Running MySQL in ANSI Mode -------------------------------- You can tell *Note `mysqld': mysqld. to run in ANSI mode with the `--ansi' startup option. Running the server in ANSI mode is the same as starting it with the following options: --transaction-isolation=SERIALIZABLE --sql-mode=ANSI You can achieve the same effect at runtime by executing 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''. The `--ansi' option affects the SQL mode and also sets the transaction isolation level. Setting the SQL mode to `'ANSI'' has no effect on the isolation level. See *Note server-options::, and *Note sql-mode::.  File: manual.info, Node: extensions-to-ansi, Next: differences-from-ansi, Prev: ansi-mode, Up: compatibility 1.8.4 MySQL Extensions to Standard SQL -------------------------------------- MySQL Server supports some extensions that you probably won't find in other SQL DBMSs. Be warned that if you use them, your code won't 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 `TEMPORARY' keyword in the following comment is executed only by servers from MySQL 3.23.02 or higher: CREATE /*!32302 TEMPORARY */ TABLE t (a INT); 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 *Note 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 *Note `RENAME TABLE': rename-table. or `ALTER TABLE ... RENAME' and let the server rename the files.) Prior to MySQL 5.1.6, database and table names cannot contain path name separator characters (``/'', ``\''). * General language syntax * By default, strings can be enclosed by either ``"'' or ``''', not just by ``'''. (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 *Note `ANALYZE TABLE': analyze-table, *Note `CHECK TABLE': check-table, *Note `OPTIMIZE TABLE': optimize-table, and *Note `REPAIR TABLE': repair-table. statements. * The *Note `CREATE DATABASE': create-database, *Note `DROP DATABASE': drop-database, and *Note `ALTER DATABASE': alter-database. statements. See *Note create-database::, *Note drop-database::, and *Note alter-database::. * The *Note `DO': do. statement. * *Note `EXPLAIN SELECT': explain. to obtain a description of how tables are processed by the query optimizer. * The *Note `FLUSH': flush. and *Note `RESET': reset. statements. * The *Note `SET': set-statement. statement. See *Note set-statement::. * The *Note `SHOW': show. statement. See *Note show::. The information produced by many of the MySQL-specific *Note `SHOW': show. statements can be obtained in more standard fashion by using *Note `SELECT': select. to query `INFORMATION_SCHEMA'. See *Note information-schema::. * Use of *Note `LOAD DATA INFILE': load-data. In many cases, this syntax is compatible with Oracle's *Note `LOAD DATA INFILE': load-data. See *Note load-data::. * Use of *Note `RENAME TABLE': rename-table. See *Note rename-table::. * Use of *Note `REPLACE': replace. instead of *Note `DELETE': delete. plus *Note `INSERT': insert. See *Note replace::. * Use of `CHANGE COL_NAME', `DROP COL_NAME', or *Note `DROP INDEX': drop-index, `IGNORE' or `RENAME' in *Note `ALTER TABLE': alter-table. statements. Use of multiple `ADD', `ALTER', `DROP', or `CHANGE' clauses in an *Note `ALTER TABLE': alter-table. statement. See *Note alter-table::. * Use of index names, indexes on a prefix of a column, and use of `INDEX' or `KEY' in *Note `CREATE TABLE': create-table. statements. See *Note create-table::. * Use of `TEMPORARY' or `IF NOT EXISTS' with *Note `CREATE TABLE': create-table. * Use of `IF EXISTS' with *Note `DROP TABLE': drop-table. and *Note `DROP DATABASE': drop-database. * The capability of dropping multiple tables with a single *Note `DROP TABLE': drop-table. statement. * The `ORDER BY' and `LIMIT' clauses of the *Note `UPDATE': update. and *Note `DELETE': delete. statements. * `INSERT INTO TBL_NAME SET COL_NAME = ...' syntax. * The `DELAYED' clause of the *Note `INSERT': insert. and *Note `REPLACE': replace. statements. * The `LOW_PRIORITY' clause of the *Note `INSERT': insert, *Note `REPLACE': replace, *Note `DELETE': delete, and *Note `UPDATE': update. statements. * Use of `INTO OUTFILE' or `INTO DUMPFILE' in *Note `SELECT': select. statements. See *Note select::. * Options such as `STRAIGHT_JOIN' or `SQL_SMALL_RESULT' in *Note `SELECT': 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 *Note 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 *Note user-variables::. * Data types * The *Note `MEDIUMINT': integer-types, *Note `SET': set, and *Note `ENUM': enum. data types, and the various *Note `BLOB': blob. and *Note `TEXT': blob. 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. If you don't like this, 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 *Note `SELECT': 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 *Note 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 *Note group-by-functions-and-modifiers::.  File: manual.info, Node: differences-from-ansi, Next: constraints, Prev: extensions-to-ansi, Up: compatibility 1.8.5 MySQL Differences from Standard SQL ----------------------------------------- * Menu: * ansi-diff-select-into-table:: `SELECT INTO TABLE' * ansi-diff-update:: `UPDATE' * ansi-diff-transactions:: Transactions and Atomic Operations * ansi-diff-foreign-keys:: Foreign Keys * ansi-diff-comments:: '`--'' as the Start of a Comment 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 *Note `REVOKE': revoke. statement to revoke privileges for a table. For more information, see *Note revoke::. * The `CAST()' function does not support cast to *Note `REAL': floating-point-types. or *Note `BIGINT': integer-types. See *Note cast-functions::.  File: manual.info, Node: ansi-diff-select-into-table, Next: ansi-diff-update, Prev: differences-from-ansi, Up: differences-from-ansi 1.8.5.1 `SELECT INTO TABLE' ........................... MySQL Server doesn't support the `SELECT ... INTO TABLE' Sybase SQL extension. Instead, MySQL Server supports the *Note `INSERT INTO ... SELECT': insert-select. standard SQL syntax, which is basically the same thing. See *Note 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 *Note `SELECT ... INTO OUTFILE': select-into. or *Note `CREATE TABLE ... SELECT': create-table. You can use *Note `SELECT ... INTO': select. with user-defined variables. The same syntax can also be used inside stored routines using cursors and local variables. See *Note select-into::.  File: manual.info, Node: ansi-diff-update, Next: ansi-diff-transactions, Prev: ansi-diff-select-into-table, Up: differences-from-ansi 1.8.5.2 `UPDATE' ................ If you access a column from the table to be updated in an expression, *Note `UPDATE': 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;  File: manual.info, Node: ansi-diff-transactions, Next: ansi-diff-foreign-keys, Prev: ansi-diff-update, Up: differences-from-ansi 1.8.5.3 Transactions and Atomic Operations .......................................... MySQL Server (version 3.23-max and all versions 4.0 and above) supports transactions with the `InnoDB' transactional storage engine. `InnoDB' provides _full_ ACID compliance. See *Note storage-engines::. For information about `InnoDB' differences from standard SQL with regard to treatment of transaction errors, see *Note innodb-error-handling::. The other nontransactional storage engines in MySQL Server (such as `MyISAM') follow a different paradigm for data integrity called `atomic operations.' In transactional terms, `MyISAM' tables effectively always operate in `autocommit = 1' mode. Atomic operations often offer comparable integrity with higher performance. Because MySQL Server supports both paradigms, you can decide whether your applications are best served by the speed of atomic operations or the use of transactional features. This choice can be made on a per-table basis. As noted, the tradeoff for transactional versus nontransactional storage engines lies mostly in performance. Transactional tables have significantly higher memory and disk space requirements, and more CPU overhead. On the other hand, transactional storage engines such as `InnoDB' also offer many significant features. MySQL Server's modular design enables the concurrent use of different storage engines to suit different requirements and deliver optimum performance in all situations. But how do you use the features of MySQL Server to maintain rigorous integrity even with the nontransactional `MyISAM' tables, and how do these features compare with the transactional storage engines? * If your applications are written in a way that is dependent on being able to call *Note `ROLLBACK': commit. rather than *Note `COMMIT': commit. in critical situations, transactions are more convenient. Transactions also ensure that unfinished updates or corrupting activities are not committed to the database; the server is given the opportunity to do an automatic rollback and your database is saved. If you use nontransactional tables, you must resolve potential problems at the application level by including simple checks before updates and by running simple scripts that check the databases for inconsistencies and automatically repair or warn if such an inconsistency occurs. You can normally fix tables perfectly with no data integrity loss just by using the MySQL log or even adding one extra log. * More often than not, critical transactional updates can be rewritten to be atomic. Generally speaking, all integrity problems that transactions solve can be done with *Note `LOCK TABLES': lock-tables. or atomic updates, ensuring that there are no automatic aborts from the server, which is a common problem with transactional database systems. * To be safe with MySQL Server, regardless of whether you use transactional tables, you only need to have backups and have binary logging turned on. When that is true, you can recover from any situation that you could with any other transactional database system. It is always good to have backups, regardless of which database system you use. The transactional paradigm has its advantages and disadvantages. Many users and application developers depend on the ease with which they can code around problems where an abort appears to be necessary, or is necessary. However, even if you are new to the atomic operations paradigm, or more familiar with transactions, do consider the speed benefit that nontransactional tables can offer on the order of three to five times the speed of the fastest and most optimally tuned transactional tables. In situations where integrity is of highest importance, MySQL Server offers transaction-level reliability and integrity even for nontransactional tables. If you lock tables with *Note `LOCK TABLES': lock-tables, all updates stall until integrity checks are made. If you obtain a `READ LOCAL' lock (as opposed to a write lock) for a table that enables concurrent inserts at the end of the table, reads are permitted, as are inserts by other clients. The newly inserted records are not be seen by the client that has the read lock until it releases the lock. With *Note `INSERT DELAYED': insert-delayed, you can write inserts that go into a local queue until the locks are released, without having the client wait for the insert to complete. See *Note concurrent-inserts::, and *Note insert-delayed::. `Atomic,' in the sense that we mean it, is nothing magical. It only means that you can be sure that while each specific update is running, no other user can interfere with it, and there can never be an automatic rollback (which can happen with transactional tables if you are not very careful). MySQL Server also guarantees that there are no dirty reads. Following are some techniques for working with nontransactional tables: * Loops that need transactions normally can be coded with the help of *Note `LOCK TABLES': lock-tables, and you don't need cursors to update records on the fly. * To avoid using *Note `ROLLBACK': commit, you can employ the following strategy: 1. Use *Note `LOCK TABLES': lock-tables. to lock all the tables you want to access. 2. Test the conditions that must be true before performing the update. 3. Update if the conditions are satisfied. 4. Use *Note `UNLOCK TABLES': lock-tables. to release your locks. This is usually a much faster method than using transactions with possible rollbacks, although not always. The only situation this solution doesn't handle is when someone kills the threads in the middle of an update. In that case, all locks are released but some of the updates may not have been executed. * You can also use functions to update records in a single operation. You can get a very efficient application by using the following techniques: * Modify columns relative to their current value. * Update only those columns that actually have changed. For example, when we are updating customer information, we update only the customer data that has changed and test only that none of the changed data, or data that depends on the changed data, has changed compared to the original row. The test for changed data is done with the `WHERE' clause in the *Note `UPDATE': update. statement. If the record wasn't updated, we give the client a message: `Some of the data you have changed has been changed by another user.' Then we show the old row versus the new row in a window so that the user can decide which version of the customer record to use. This gives us something that is similar to column locking but is actually even better because we only update some of the columns, using values that are relative to their current values. This means that typical *Note `UPDATE': update. statements look something like these: UPDATE tablename SET pay_back=pay_back+125; UPDATE customer SET customer_date='current_date', address='new address', phone='new phone', money_owed_to_us=money_owed_to_us-125 WHERE customer_id=id AND address='old address' AND phone='old phone'; This is very efficient and works even if another client has changed the values in the `pay_back' or `money_owed_to_us' columns. * When managing unique identifiers, you can avoid statements such as *Note `LOCK TABLES': lock-tables. or *Note `ROLLBACK': commit. by using an `AUTO_INCREMENT' column and either the `LAST_INSERT_ID()' SQL function or the *Note `mysql_insert_id()': mysql-insert-id. C API function. See *Note information-functions::, and *Note mysql-insert-id::. For situations that require row-level locking, use *Note `InnoDB': innodb-storage-engine. tables. Otherwise, with *Note `MyISAM': myisam-storage-engine. tables, you can use a flag column in the table and do something like the following: UPDATE TBL_NAME SET row_flag=1 WHERE id=ID; MySQL returns `1' for the number of affected rows if the row was found and `row_flag' wasn't `1' in the original row. You can think of this as though MySQL Server changed the preceding statement to: UPDATE TBL_NAME SET row_flag=1 WHERE id=ID AND row_flag <> 1;  File: manual.info, Node: ansi-diff-foreign-keys, Next: ansi-diff-comments, Prev: ansi-diff-transactions, Up: differences-from-ansi 1.8.5.4 Foreign Keys .................... The `InnoDB' storage engine supports checking of foreign key constraints, including `CASCADE', `ON DELETE', and `ON UPDATE'. See *Note innodb-foreign-key-constraints::. For storage engines other than `InnoDB', MySQL Server parses the `FOREIGN KEY' syntax in *Note `CREATE TABLE': create-table. statements, but does not use or store it. In the future, the implementation will be extended to store this information in the table specification file so that it may be retrieved by *Note `mysqldump': mysqldump. and ODBC. At a later stage, foreign key constraints will be implemented for `MyISAM' tables as well. Foreign key enforcement offers several benefits to database developers: * Assuming proper design of the relationships, foreign key constraints make it more difficult for a programmer to introduce an inconsistency into the database. * Centralized checking of constraints by the database server makes it unnecessary to perform these checks on the application side. This eliminates the possibility that different applications may not all check the constraints in the same way. * Using cascading updates and deletes can simplify the application code. * Properly designed foreign key rules aid in documenting relationships between tables. Do keep in mind that these benefits come at the cost of additional overhead for the database server to perform the necessary checks. Additional checking by the server affects performance, which for some applications may be sufficiently undesirable as to be avoided if possible. (Some major commercial applications have coded the foreign key logic at the application level for this reason.) MySQL gives database developers the choice of which approach to use. If you don't need foreign keys and want to avoid the overhead associated with enforcing referential integrity, you can choose another storage engine instead, such as `MyISAM'. (For example, the `MyISAM' storage engine offers very fast performance for applications that perform only *Note `INSERT': insert. and *Note `SELECT': select. operations. In this case, the table has no holes in the middle and the inserts can be performed concurrently with retrievals. See *Note concurrent-inserts::.) If you choose not to take advantage of referential integrity checks, keep the following considerations in mind: * In the absence of server-side foreign key relationship checking, the application itself must handle relationship issues. For example, it must take care to insert rows into tables in the proper order, and to avoid creating orphaned child records. It must also be able to recover from errors that occur in the middle of multiple-record insert operations. * If `ON DELETE' is the only referential integrity capability an application needs, you can achieve a similar effect as of MySQL Server 4.0 by using multiple-table *Note `DELETE': delete. statements to delete rows from many tables with a single statement. See *Note delete::. * A workaround for the lack of `ON DELETE' is to add the appropriate *Note `DELETE': delete. statements to your application when you delete records from a table that has a foreign key. In practice, this is often as quick as using foreign keys and is more portable. Be aware that the use of foreign keys can sometimes lead to problems: * Foreign key support addresses many referential integrity issues, but it is still necessary to design key relationships carefully to avoid circular rules or incorrect combinations of cascading deletes. * It is not uncommon for a DBA to create a topology of relationships that makes it difficult to restore individual tables from a backup. (MySQL alleviates this difficulty by enabling you to temporarily disable foreign key checks when reloading a table that depends on other tables. See *Note innodb-foreign-key-constraints::. As of MySQL 4.1.1, *Note `mysqldump': mysqldump. generates dump files that take advantage of this capability automatically when they are reloaded.) Foreign keys in SQL are used to check and enforce referential integrity, not to join tables. If you want to get results from multiple tables from a *Note `SELECT': select. statement, you do this by performing a join between them: SELECT * FROM t1 INNER JOIN t2 ON t1.id = t2.id; See *Note join::, and *Note example-foreign-keys::. The `FOREIGN KEY' syntax without `ON DELETE ...' is often used by ODBC applications to produce automatic `WHERE' clauses.  File: manual.info, Node: ansi-diff-comments, Prev: ansi-diff-foreign-keys, Up: differences-from-ansi 1.8.5.5 '`--'' 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 *Note comments::. Standard SQL uses ``--'' as a start-comment sequence. MySQL Server uses ``#'' as the start comment character. MySQL Server 3.23.3 and up 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 3.23.3 and newer. Therefore, `credit--1' is safe to use. Another safe feature is that the *Note `mysql': mysql. command-line client ignores lines that start with ``--''. The following information is relevant only if you are running a MySQL version earlier than 3.23.3: If you have an SQL script in a text file that contains ``--'' comments, you should use the *Note `replace': replace-utility. utility as follows to convert the comments to use ``#'' characters before executing the script: shell> replace " --" " #" < text-file-with-funny-comments.sql \ | mysql DB_NAME That is safer than executing the script in the usual way: shell> mysql DB_NAME < text-file-with-funny-comments.sql You can also edit the script file `in place' to change the ``--'' comments to ``#'' comments: shell> replace " --" " #" -- text-file-with-funny-comments.sql Change them back with this command: shell> replace " #" " --" -- text-file-with-funny-comments.sql See *Note replace-utility::.  File: manual.info, Node: constraints, Prev: differences-from-ansi, Up: compatibility 1.8.6 How MySQL Deals with Constraints -------------------------------------- * Menu: * constraint-primary-key:: `PRIMARY KEY' and `UNIQUE' Index Constraints * constraint-foreign-key:: `FOREIGN KEY' Constraints * constraint-invalid-data:: Constraints on Invalid Data * constraint-enum:: `ENUM' and `SET' 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 *Note server-sql-mode::. The following sections describe how MySQL Server handles different types of constraints.  File: manual.info, Node: constraint-primary-key, Next: constraint-foreign-key, Prev: constraints, Up: constraints 1.8.6.1 `PRIMARY KEY' and `UNIQUE' Index Constraints .................................................... Normally, errors occurs for data-change statements (such as *Note `INSERT': insert. or *Note `UPDATE': 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 *Note `INSERT': insert, *Note `UPDATE': 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 (*Note insert::, *Note update::, and so forth). You can get information about the number of rows actually inserted or updated with the *Note `mysql_info()': mysql-info. C API function. You can also use the *Note `SHOW WARNINGS': show-warnings. statement. See *Note mysql-info::, and *Note show-warnings::. Currently, only `InnoDB' tables support foreign keys. See *Note innodb-foreign-key-constraints::.  File: manual.info, Node: constraint-foreign-key, Next: constraint-invalid-data, Prev: constraint-primary-key, Up: constraints 1.8.6.2 `FOREIGN KEY' Constraints ................................. Foreign keys let you cross-reference related data across tables, and foreign key constraints (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_foreign_key_constraint) help keep this spread-out data consistent. MySQL supports `ON UPDATE' and `ON DELETE' foreign key references in *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': 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 *Note `InnoDB': innodb-storage-engine. 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 *Note 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 *Note `INFORMATION_SCHEMA.KEY_COLUMN_USAGE': key-column-usage-table. 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' (http://dev.mysql.com/doc/refman/5.6/en/innodb-sys-foreign-table.html) and `INNODB_SYS_FOREIGN_COLS' (http://dev.mysql.com/doc/refman/5.6/en/innodb-sys-foreign-cols-table.html) tables, in the `INFORMATION_SCHEMA' database. Currently, only `InnoDB' tables support foreign keys. See *Note innodb-foreign-key-constraints::, for information specific to foreign key support in `InnoDB'. * Deviations from SQL Standards * MySQL's 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, *Note `InnoDB': innodb-storage-engine. 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 *Note `InnoDB': innodb-storage-engine. 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, *Note `InnoDB': innodb-storage-engine. 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 how *Note `InnoDB': innodb-storage-engine. foreign keys differ from the SQL standard, see *Note innodb-foreign-key-constraints::.  File: manual.info, Node: constraint-invalid-data, Next: constraint-enum, Prev: constraint-foreign-key, Up: constraints 1.8.6.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 change the server 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 *Note server-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 doesn't start with a number into a numeric column, MySQL Server stores 0. * Invalid values for *Note `ENUM': enum. and *Note `SET': set. columns are handled as described in *Note constraint-enum::. * MySQL enables you to store certain incorrect date values into *Note `DATE': datetime. and *Note `DATETIME': datetime. columns (such as `'2000-02-31'' or `'2000-02-00''). The idea is that it is not the job of the SQL server to validate dates. 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 *Note `INSERT': insert. statements. For multiple-row *Note `INSERT': insert. statements or for *Note `INSERT INTO ... SELECT': insert-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 *Note data-type-defaults::. * If an *Note `INSERT': 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. In MySQL 5.0.2 and up, 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 *Note `INSERT IGNORE': insert. or `UPDATE IGNORE' rather than *Note `INSERT': insert. or *Note `UPDATE': update. without `IGNORE'.  File: manual.info, Node: constraint-enum, Prev: constraint-invalid-data, Up: constraints 1.8.6.4 `ENUM' and `SET' Constraints .................................... *Note `ENUM': enum. and *Note `SET': set. columns provide an efficient way to define columns that can contain only a given set of values. See *Note enum::, and *Note set::. However, before MySQL 5.0.2, *Note `ENUM': enum. and *Note `SET': set. columns do not provide true constraints on entry of invalid data: * *Note `ENUM': enum. columns always have a default value. If you specify no default value, then it is `NULL' for columns that can have `NULL', otherwise it is the first enumeration value in the column definition. * If you insert an incorrect value into an *Note `ENUM': enum. column or if you force a value into an *Note `ENUM': enum. column with `IGNORE', it is set to the reserved enumeration value of `0', which is displayed as an empty string in string context. * If you insert an incorrect value into a *Note `SET': set. column, the incorrect value is ignored. For example, if the column can contain the values `'a'', `'b'', and `'c'', an attempt to assign `'a,x,b,y'' results in a value of `'a,b''. As of MySQL 5.0.2, you can configure the server to use strict SQL mode. See *Note server-sql-mode::. With strict mode enabled, the definition of a *Note `ENUM': enum. or *Note `SET': set. column does act as a constraint on values entered into the column. An error occurs for values that do not satisfy these conditions: * An *Note `ENUM': 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 *Note `ENUM('a','b','c')': enum, values such as `''', `'d'', or `'ax'' are invalid and are rejected. * A *Note `SET': 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 *Note `SET('a','b','c')': set, 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 *Note `INSERT IGNORE': insert. or `UPDATE IGNORE'. In this case, a warning is generated rather than an error. For *Note `ENUM': enum, the value is inserted as the error member (`0'). For *Note `SET': 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''.  File: manual.info, Node: credits, Prev: compatibility, Up: introduction 1.9 Credits =========== * Menu: * contributors:: Contributors to MySQL * documenters-translators:: Documenters and translators * packages:: Packages that support MySQL * tools-used-to-create-mysql:: Tools that were used to create MySQL * supporters:: Supporters of MySQL The following sections list developers, contributors, and supporters that have helped to make MySQL what it is today.  File: manual.info, Node: contributors, Next: documenters-translators, Prev: credits, Up: credits 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 or The initial port to Win32/NT. * Per Eric Olsson For constructive criticism and real testing of the dynamic record format. * Irena Pancirov 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. *Note `mysqladmin': mysqladmin. and *Note `mysql': 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 *Note `mysqldump': 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 *Note `mysqlhotcopy': mysqlhotcopy. * Zarko Mocnik Sorting for Slovenian language. * "TAMITO" The `_MB' character set macros and the ujis and sjis character sets. * Joshua Chamas Base for concurrent insert, extended date syntax, debugging on NT, and answering on the MySQL mailing list. * Yves Carlier *Note `mysqlaccess': mysqlaccess, a program to show the access rights for a user. * Rhys Jones (And GWE Technologies Limited) For one of the early JDBC drivers. * Dr Xiaokun Kelvin ZHU Further development of one of the early JDBC drivers and other MySQL-related Java tools. * James Cooper For setting up a searchable mailing list archive at his site. * Rick Mehalick For `xmysql', a graphical X client for MySQL Server. * Doug Sisk For providing RPM packages of MySQL for Red Hat Linux. * Diemand Alexander V. For providing RPM packages of MySQL for Red Hat Linux-Alpha. * Antoni Pamies Olive For providing RPM versions of a lot of MySQL clients for Intel and SPARC. * Jay Bloodworth For providing RPM versions for MySQL 3.21. * David Sacerdote Ideas for secure checking of DNS host names. * Wei-Jou Chen Some support for Chinese(BIG5) characters. * Wei He A lot of functionality for the Chinese(GBK) character set. * Jan Pazdziora Czech sorting order. * Zeev Suraski `FROM_UNIXTIME()' time formatting, `ENCRYPT()' functions, and `bison' advisor. Active mailing list member. * Luuk de Boer 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 *Note `mysql_setpermission': mysql-setpermission. script. * Alexis Mikhailov User-defined functions (UDFs); *Note `CREATE FUNCTION': create-function. and *Note `DROP FUNCTION': drop-function. * Andreas F. Bobak The `AGGREGATE' extension to user-defined functions. * Ross Wakelin Help to set up InstallShield for MySQL-Win32. * Jethro Wright III The `libmysql.dll' library. * James Pereria Mysqlmanager, a Win32 GUI tool for administering MySQL Servers. * Curt Sampson Porting of MIT-pthreads to NetBSD/Alpha and NetBSD 1.3/i386. * Martin Ramsch Examples in the MySQL Tutorial. * Steve Harvey For making *Note `mysqlaccess': mysqlaccess. more secure. * Konark IA-64 Centre of Persistent Systems Private Limited `http://www.pspl.co.in/konark/'. 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 Mac OS X packages and providing invaluable feedback on how to create Mac 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, , , , Ted Deppner , 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 Irix setup. * Luuk de Boer Benchmark questions. * Tim Sailer `DBD::mysql' questions. * Boyd Lynn Gerber SCO-related questions. * Richard Mehalick `xmysql'-related questions and basic installation questions. * Zeev Suraski Apache module configuration questions (log & auth), PHP-related questions, SQL syntax-related questions and other general questions. * Francesc Guasch General questions. * Jonathan J Smith Questions pertaining to OS-specifics with Linux, SQL syntax, and other things that might need some work. * David Sklar Using MySQL from PHP and Perl. * Alistair MacDonald Is flexible and can handle Linux and perhaps HP-UX. * John Lyon Questions about installing MySQL on Linux systems, using either `.rpm' files or compiling from source. * Lorvid Ltd. Simple billing/license/support/copyright issues. * Patrick Sherrill ODBC and VisualC++ interface questions. * Randy Harmon `DBD', Linux, some SQL syntax questions.  File: manual.info, Node: documenters-translators, Next: packages, Prev: contributors, Up: credits 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. 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 (`http://mysql.hitstar.com/') versions were based. Personal home page at linuxdb.yeah.net (http://linuxdb.yeah.net). * Jay Flaherty Big parts of the Perl `DBI'/`DBD' section in the manual. * Paul Southworth , Ray Loyzaga Proof-reading of the Reference Manual. * Therrien Gilbert , Jean-Marc Pouyot French error messages. * Petr Snajdr, Czech error messages. * Jaroslaw Lewandowski Polish error messages. * Miguel Angel Fernandez Roiz Spanish error messages. * Roy-Magne Mo Norwegian error messages and testing of MySQL 3.21.xx. * Timur I. Bakeyev Russian error messages. * & Filippo Grassilli Italian error messages. * Dirk Munzinger German error messages. * Billik Stefan Slovak error messages. * Stefan Saroiu 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).  File: manual.info, Node: packages, Next: tools-used-to-create-mysql, Prev: documenters-translators, Up: credits 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 For the Perl interface for MySQL Server. * Jochen Wiedmann For maintaining the Perl `DBD::mysql' module. * Eugene Chan 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 For porting iODBC (Unix ODBC). * Xavier Leroy The author of LinuxThreads (used by the MySQL Server on Linux).  File: manual.info, Node: tools-used-to-create-mysql, Next: supporters, Prev: packages, Up: credits 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').  File: manual.info, Node: supporters, Prev: tools-used-to-create-mysql, Up: credits 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 Web site 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 *Note `mysqld': mysqld. version. * FutureQuest The `--skip-show-database' option.  File: manual.info, Node: installing, Next: tutorial, Prev: introduction, Up: Top 2 Installing and Upgrading MySQL ******************************** * Menu: * general-installation-issues:: General Installation Guidance * binary-installation:: Installing MySQL on Unix/Linux Using Generic Binaries * windows-installation:: Installing MySQL on Microsoft Windows * macosx-installation:: Installing MySQL on Mac OS X * linux-installation:: Installing MySQL on Linux * solaris-installation:: Installing MySQL on Solaris and OpenSolaris * aix-installation:: Installing MySQL on IBM AIX * hpux-installation:: Installing MySQL on HP-UX * freebsd-installation:: Installing MySQL on FreeBSD * i5os-installation:: Installing MySQL on i5/OS * source-installation:: Installing MySQL from Source * postinstallation:: Postinstallation Setup and Testing * upgrading-downgrading:: Upgrading or Downgrading MySQL * environment-variables:: Environment Variables * perl-support:: Perl Installation Notes 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 *Note 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, you may wish to read *Note faqs-migration::, which contains answers to some common questions concerning migration issues. If you are migrating from MySQL Enterprise Edition to MySQL Community Server, see *Note downgrading-from-enterprise::. 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: 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. We also provide public access to our current source tree for those who want to see our most recent developments and help us test new code. To determine which version and type of distribution you should use, see *Note which-version::. 3. *Download the distribution that you want to install.* For instructions, see *Note getting-mysql::. To verify the integrity of the distribution, use the instructions in *Note verifying-package-integrity::. 4. *Install the distribution.* To install MySQL from a binary distribution, use the instructions in *Note binary-installation::. To install MySQL from a source distribution or from the current development source tree, use the instructions in *Note source-installation::. 5. *Perform any necessary postinstallation setup.* After installing MySQL, see *Note postinstallation:: for information about making sure the MySQL server is working properly. Also refer to the information provided in *Note default-privileges::. This section describes how to secure the initial MySQL user accounts, _which have no passwords_ until you assign passwords. 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 *Note 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 *Note binary-installation::. For information on building MySQL entirely from the source code distributions or the source code repositories, see *Note 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 *Note linux-installation::. * Solaris and OpenSolaris, including PKG and IPS formats, see *Note solaris-installation::. * IBM AIX, see *Note solaris-installation::. * Hewlett-Packard HP-UX, including the DEPOT package format, see *Note hpux-installation::. * FreeBSD, see *Note freebsd-installation::. * *Microsoft Windows* For instructions on installing MySQL on Microsoft Windows, using either a Zipped binary or an MSI package, see *Note windows-installation::. For information on using the MySQL Server Instance Config Wizard, see *Note mysql-config-wizard::. For details and instructions on building MySQL from source code using Microsoft Visual Studio, see *Note windows-source-build::. * *Mac OS X* For installation on Mac OS X, including using both the binary package and native PKG formats, see *Note macosx-installation::. For information on making use of the MySQL Startup Item to automatically start and stop MySQL, see *Note macosx-installation-startupitem::. For information on the MySQL Preference Pane, see *Note macosx-installation-prefpane::. * *IBM i5/OS* For instructions on installing, starting, and stopping MySQL on i5/OS, see *Note i5os-installation::.  File: manual.info, Node: general-installation-issues, Next: binary-installation, Prev: installing, Up: installing 2.1 General Installation Guidance ================================= * Menu: * supported-os:: Operating Systems Supported by MySQL Community Server * which-version:: Choosing Which MySQL Distribution to Install * getting-mysql:: How to Get MySQL * verifying-package-integrity:: Verifying Package Integrity Using MD5 Checksums or `GnuPG' * installation-layouts:: Installation Layouts * compiler-characteristics:: Compiler-Specific Build Characteristics 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 *Note binary-installation:: or the corresponding section for your platform if available. To build MySQL from source, use the instructions in *Note source-installation::.  File: manual.info, Node: supported-os, Next: which-version, Prev: general-installation-issues, Up: general-installation-issues 2.1.1 Operating Systems Supported by MySQL Community Server ----------------------------------------------------------- This section lists the operating systems on which MySQL Community Server is known to run. *Important*: Oracle Corporation does not necessarily provide official support for all the platforms listed in this section. For information about those platforms that are officially supported, see http://www.mysql.com/support/supportedplatforms/database.html on the MySQL Web site. We use GNU Autoconf, so it is possible to port MySQL to all modern systems that have a C++ compiler and a working implementation of POSIX threads. (Thread support is needed for the server. To compile only the client code, the only requirement is a C++ compiler.) MySQL has been reported to compile successfully on the following systems: * AIX 4.x, 5.x. See *Note aix-installation::. AIX 5.3 should be upgraded to technology level 7 (5300-07). * FreeBSD 5.x and up. See *Note freebsd-installation::. * HP-UX 11.x. See *Note hpux-installation::. * Linux. Builds on all recent Linux distributions based on the 2.6 kernel. See *Note linux-installation::. * Mac OS X. See *Note macosx-installation::. * Solaris 2.8 on SPARC and x86. See *Note solaris-installation::. * Microsoft Windows. See *Note windows-installation::. MySQL has also been known to run on other systems in the past. See *Note general-installation-issues::. Some porting effort might be required for current versions of MySQL on these systems. Not all platforms are equally well-suited for running MySQL. How well a certain platform is suited for a high-load mission-critical MySQL server is determined by the following factors: * General stability of the thread library. A platform may have an excellent reputation otherwise, but MySQL is only as stable as the thread library it calls, even if everything else is perfect. * The capability of the kernel and the thread library to take advantage of symmetric multi-processor (SMP) systems. In other words, when a process creates a thread, it should be possible for that thread to run on a CPU different from the original process. * The capability of the kernel and the thread library to run many threads that acquire and release a mutex over a short critical region frequently without excessive context switches. If the implementation of `pthread_mutex_lock()' is too anxious to yield CPU time, this hurts MySQL tremendously. If this issue is not taken care of, adding extra CPUs actually makes MySQL slower. * General file system stability and performance. * Table size. If your tables are large, performance is affected by the ability of the file system to deal with large files and dealing with them efficiently. * Our level of expertise here at Oracle Corporation with the platform. If we know a platform well, we enable platform-specific optimizations and fixes at compile time. We can also provide advice on configuring your system optimally for MySQL. * The amount of testing we have done internally for similar configurations. * The number of users that have run MySQL successfully on the platform in similar configurations. If this number is high, the likelihood of encountering platform-specific surprises is much smaller.  File: manual.info, Node: which-version, Next: getting-mysql, Prev: supported-os, Up: general-installation-issues 2.1.2 Choosing Which MySQL Distribution to Install -------------------------------------------------- * Menu: * choosing-version:: Choosing Which Version of MySQL to Install * choosing-distribution-format:: Choosing a Distribution Format * many-versions:: How and When Updates Are Released When preparing to install MySQL, you should decide which version to use. MySQL development occurs in several release series, and you can pick the one that best fits your needs. After deciding which version to install, you can choose a distribution format. Releases are available in binary or source format.  File: manual.info, Node: choosing-version, Next: choosing-distribution-format, Prev: which-version, Up: which-version 2.1.2.1 Choosing Which Version of MySQL to Install .................................................. The first decision to make is whether you want to use a production (stable) release or a development release. In the MySQL development process, multiple release series co-exist, each at a different stage of maturity. * Production Releases * * MySQL 5.6: Latest General Availability (Production) release * MySQL 5.5: Previous General Availability (Production) release * MySQL 5.1: Older General Availability (Production) release * MySQL 5.0: Older Production release nearing the end of the product lifecycle MySQL 4.1, 4.0, and 3.23 are old releases that are no longer supported. See http://www.mysql.com/about/legal/lifecycle/ for information about support policies and schedules. Normally, if you are beginning to use MySQL for the first time or trying to port it to some system for which there is no binary distribution, use the most recent General Availability series listed in the preceding descriptions. All MySQL releases, even those from development series, are checked with the MySQL benchmarks and an extensive test suite before being issued. If you are running an older system and want to upgrade, but do not want to take the chance of having a nonseamless upgrade, you should upgrade to the latest version in the same release series you are using (where only the last part of the version number is newer than yours). We have tried to fix only fatal bugs and make only small, relatively `safe' changes to that version. If you want to use new features not present in the production release series, you can use a version from a development series. Be aware that development releases are not as stable as production releases. We do not use a complete code freeze because this prevents us from making bugfixes and other fixes that must be done. We may add small things that should not affect anything that currently works in a production release. Naturally, relevant bugfixes from an earlier series propagate to later series. If you want to use the very latest sources containing all current patches and bugfixes, you can use one of our source code repositories (see *Note installing-development-tree::). These are not `releases' as such, but are available as previews of the code on which future releases are to be based. The naming scheme in MySQL 5.1 uses release names that consist of three numbers and a suffix; for example, *mysql-5.1.29-rc*. The numbers within the release name are interpreted as follows: * The first number (*5*) is the major version and describes the file format. All MySQL 5 releases have the same file format. * The second number (*1*) is the release level. Taken together, the major version and release level constitute the release series number. * The third number (*29*) is the version number within the release series. This is incremented for each new release. Usually you want the latest version for the series you have chosen. For each minor update, the last number in the version string is incremented. When there are major new features or minor incompatibilities with previous versions, the second number in the version string is incremented. When the file format changes, the first number is increased. Release names also include a suffix to indicates 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: * *alpha* indicates that the release is for preview purposes only. Known bugs should be documented in the Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/). Most alpha releases implement new commands and extensions. Active development that may involve major code changes can occur in an alpha release. However, we do conduct testing before issuing a release. * *beta* indicates that the release is appropriate for use with new development. Within beta releases, the features and compatibility should remain consistent. However, beta releases may contain numerous and major unaddressed bugs. All APIs, externally visible structures, and columns for SQL statements will not change during future beta, release candidate, or production releases. * *rc* indicates a Release Candidate. Release candidates are believed to be stable, having passed all of MySQL's internal testing, and with all known fatal runtime bugs fixed. However, the release has not been in widespread use long enough to know for sure that all bugs have been identified. Only minor fixes are added. (A release candidate is what formerly was known as a gamma release.) * If there is no suffix, it indicates that the release is a General Availability (GA) or Production release. GA releases are stable, having successfully passed through all earlier release stages and are believed to be reliable, free of serious bugs, and suitable for use in production systems. Only critical bugfixes are applied to the release. All releases of MySQL are run through our standard tests and benchmarks to ensure that they are relatively safe to use. Because the standard tests are extended over time to check for all previously found bugs, the test suite keeps getting better. All releases have been tested at least with these tools: * An internal test suite The `mysql-test' directory contains an extensive set of test cases. We run these tests for every server binary. See *Note mysql-test-suite::, for more information about this test suite. * The MySQL benchmark suite This suite runs a range of common queries. It is also a test to determine whether the latest batch of optimizations actually made the code faster. See *Note mysql-benchmarks::. We also perform additional integration and nonfunctional testing of the latest MySQL version in our internal production environment. Integration testing is done with different connectors, storage engines, replication modes, backup, partitioning, stored programs, and so forth in various combinations. Additional nonfunctional testing is done in areas of performance, concurrency, stress, high volume, upgrade and downgrade.  File: manual.info, Node: choosing-distribution-format, Next: many-versions, Prev: choosing-version, Up: which-version 2.1.2.2 Choosing a Distribution Format ...................................... After choosing which version of MySQL to install, you should decide whether to use a binary distribution or a source distribution. In most cases, you should probably use a binary distribution, if one exists for your platform. Binary distributions are available in native format for many platforms, such as RPM packages for Linux, DMG packages for Mac OS X, and PKG packages for Solaris. Distributions are also available in more generic formats such as Zip archives or compressed `tar' files. Reasons to choose a binary distribution include the following: * Binary distributions generally are easier to install than source distributions. * To satisfy different user requirements, we provide several servers in binary distributions. *Note `mysqld': mysqld. is an optimized server that is a smaller, faster binary. *Note `mysqld-debug': mysqld. is compiled with debugging support. Each of these servers is compiled from the same source distribution, though with different configuration options. All native MySQL clients can connect to servers from either MySQL version. Under some circumstances, you may be better off installing 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 *Note `mysqld': mysqld. to ensure that features are available that might not be included in the standard binary distributions. Here is a list of the most common extra options that you may want to use to ensure feature availability: * `--with-libwrap' * `--with-named-z-libs' (this is done for some of the binaries) * `--with-debug[=full]' For additional information, see *Note source-configuration-options::. * You want to configure *Note `mysqld': 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 use the latest sources from one of the Bazaar repositories to have access to all current bugfixes. For example, if you have found a bug and reported it to the MySQL development team, the bugfix is committed to the source repository and you can access it there. The bugfix does not appear in a release until a release actually is issued. * You want to read (or modify) the C and C++ code that makes up MySQL. For this purpose, you should get a source distribution, because the source code is always the ultimate manual. * Source distributions contain more tests and examples than binary distributions.  File: manual.info, Node: many-versions, Prev: choosing-distribution-format, Up: which-version 2.1.2.3 How and When Updates Are Released ......................................... MySQL is evolving quite rapidly and we want to share new developments with other MySQL users. We try to produce a new release whenever we have new and useful features that others also seem to have a need for. We also try to help users who request features that are easy to implement. We take note of what our licensed users want, and we especially take note of what our support customers want and try to help them in this regard. No one is _required_ to download a new release. The Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/) help you determine whether the new release has something you really want. We use the following policy when updating MySQL: * Enterprise Server releases are meant to appear every 18 months, supplemented by quarterly service packs and monthly rapid updates. Community Server releases are meant to appear 2 to 3 times per year. * Releases are issued within each series. For each release, the last number in the version is one more than the previous release within the same series. * Binary distributions for some platforms are made by us for major releases. Other people may make binary distributions for other systems, but probably less frequently. * We make fixes available as soon as we have identified and corrected small or noncritical but annoying bugs. The fixes are available in source form immediately from our public Bazaar repositories, and are included in the next release. * If by any chance a security vulnerability or critical bug is found in a release, our policy is to fix it in a new release as soon as possible. (We would like other companies to do this, too!)  File: manual.info, Node: getting-mysql, Next: verifying-package-integrity, Prev: which-version, Up: general-installation-issues 2.1.3 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. To obtain the latest development source, see *Note installing-development-tree::.  File: manual.info, Node: verifying-package-integrity, Next: installation-layouts, Prev: getting-mysql, Up: general-installation-issues 2.1.4 Verifying Package Integrity Using MD5 Checksums or `GnuPG' ---------------------------------------------------------------- * Menu: * verifying-md5-checksum:: Verifying the MD5 Checksum * checking-gpg-signature:: Signature Checking Using `GnuPG' * checking-gpg-signature-windows:: Signature Checking Using `Gpg4win' for Windows * checking-rpm-signature:: Signature Checking Using `RPM' After you have downloaded the MySQL package that suits your needs and before you attempt to install it, you should 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.  File: manual.info, Node: verifying-md5-checksum, Next: checking-gpg-signature, Prev: verifying-package-integrity, Up: verifying-package-integrity 2.1.4.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.1.73-linux-i686.tar.gz aaab65abbec64d5e907dcd41b8699945 mysql-standard-5.1.73-linux-i686.tar.gz shell> md5.exe mysql-installer-community-5.1.73.msi aaab65abbec64d5e907dcd41b8699945 mysql-installer-community-5.1.73.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.  File: manual.info, Node: checking-gpg-signature, Next: checking-gpg-signature-windows, Prev: verifying-md5-checksum, Up: verifying-package-integrity 2.1.4.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 *Note MD5 checksums: verifying-md5-checksum, 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. See `http://www.gnupg.org/' for more information about `GnuPG' and how to obtain and install it on your system. Most Linux distributions ship with `GnuPG' installed by default. For more information about `GnuPG', see `http://www.openpgp.org/'. 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 cut and paste the key directly from the following text: -----BEGIN PGP PUBLIC KEY BLOCK----- Version: PGP Universal 2.9.1 (Build 347) mQGiBD4+owwRBAC14GIfUfCyEDSIePvEW3SAFUdJBtoQHH/nJKZyQT7h9bPlUWC3 RODjQReyCITRrdwyrKUGku2FmeVGwn2u2WmDMNABLnpprWPkBdCk96+OmSLN9brZ fw2vOUgCmYv2hW0hyDHuvYlQA/BThQoADgj8AW6/0Lo7V1W9/8VuHP0gQwCgvzV3 BqOxRznNCRCRxAuAuVztHRcEAJooQK1+iSiunZMYD1WufeXfshc57S/+yeJkegNW hxwR9pRWVArNYJdDRT+rf2RUe3vpquKNQU/hnEIUHJRQqYHo8gTxvxXNQc7fJYLV K2HtkrPbP72vwsEKMYhhr0eKCbtLGfls9krjJ6sBgACyP/Vb7hiPwxh6rDZ7ITnE kYpXBACmWpP8NJTkamEnPCia2ZoOHODANwpUkP43I7jsDmgtobZX9qnrAXw+uNDI QJEXM6FSbi0LLtZciNlYsafwAPEOMDKpMqAK6IyisNtPvaLd8lH0bPAnWqcyefep rv0sxxqUEMcM3o7wwgfN83POkDasDbs3pjwPhxvhz6//62zQJ7Q2TXlTUUwgUmVs ZWFzZSBFbmdpbmVlcmluZyA8bXlzcWwtYnVpbGRAb3NzLm9yYWNsZS5jb20+iGYE ExECACYCGyMGCwkIBwMCBBUCCAMEFgIDAQIeAQIXgAUCTnc+KgUJE/sCFQAKCRCM cY07UHLh9SbMAJ4l1+qBz2BZNSGCZwwA6YbhGPC7FwCgp8z5TzIw4YQuL5NGJ/sy 0oSazqmJASIEEAECAAwFAk53QS4FAwASdQAACgkQlxC4m8pXrXwJ8Qf/be/UO9mq foc2sMyhwMpN4/fdBWwfLkA12FXQDOQMvwH9HsmEjnfUgYKXschZRi+DuHXe1P7l 8G2aQLubhBsQf9ejKvRFTzuWMQkdIq+6Koulxv6ofkCcv3d1xtO2W7nb5yxcpVBP rRfGFGebJvZa58DymCNgyGtAU6AOz4veavNmI2+GIDQsY66+tYDvZ+CxwzdYu+HD V9HmrJfc6deM0mnBn7SRjqzxJPgoTQhihTav6q/R5/2p5NvQ/H84OgS6GjosfGc2 duUDzCP/kheMRKfzuyKCOHQPtJuIj8++gfpHtEU7IDUX1So3c9n0PdpeBvclsDbp RnCNxQWU4mBot7kCDQQ+PqMdEAgA7+GJfxbMdY4wslPnjH9rF4N2qfWsEN/lxaZo JYc3a6M02WCnHl6ahT2/tBK2w1QI4YFteR47gCvtgb6O1JHffOo2HfLmRDRiRjd1 DTCHqeyX7CHhcghj/dNRlW2Z0l5QFEcmV9U0Vhp3aFfWC4Ujfs3LU+hkAWzE7zaD 5cH9J7yv/6xuZVw411x0h4UqsTcWMu0iM1BzELqX1DY7LwoPEb/O9Rkbf4fmLe11 EzIaCa4PqARXQZc4dhSinMt6K3X4BrRsKTfozBu74F47D8Ilbf5vSYHbuE5p/1oI Dznkg/p8kW+3FxuWrycciqFTcNz215yyX39LXFnlLzKUb/F5GwADBQf+Lwqqa8CG rRfsOAJxim63CHfty5mUc5rUSnTslGYEIOCR1BeQauyPZbPDsDD9MZ1ZaSafanFv wFG6Llx9xkU7tzq+vKLoWkm4u5xf3vn55VjnSd1aQ9eQnUcXiL4cnBGoTbOWI39E cyzgslzBdC++MPjcQTcA7p6JUVsP6oAB3FQWg54tuUo0Ec8bsM8b3Ev42LmuQT5N dKHGwHsXTPtl0klk4bQk4OajHsiy1BMahpT27jWjJlMiJc+IWJ0mghkKHt926s/y mfdf5HkdQ1cyvsz5tryVI3Fx78XeSYfQvuuwqp2H139pXGEkg0n6KdUOetdZWhe7 0YGNPw1yjWJT1IhUBBgRAgAMBQJOdz3tBQkT+wG4ABIHZUdQRwABAQkQjHGNO1By 4fUUmwCbBYr2+bBEn/L2BOcnw9Z/QFWuhRMAoKVgCFm5fadQ3Afi+UQlAcOphrnJ =Eto8 -----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 " 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 " 1 new user ID gpg: key 5072E1F5: "MySQL Release Engineering " 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 *Note 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 file `mysql-standard-5.1.73-linux-i686.tar.gz' Signature file `mysql-standard-5.1.73-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.1.73-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 " 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.1.73-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 " 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.  File: manual.info, Node: checking-gpg-signature-windows, Next: checking-rpm-signature, Prev: checking-gpg-signature, Up: verifying-package-integrity 2.1.4.3 Signature Checking Using `Gpg4win' for Windows ...................................................... The *Note 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: Initial screen after loading Kleopatra 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: Finding the MySQL Release Engineering 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' and then press `OK'. FIGURE GOES HERE: Changing the Trust level 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 file `mysql-installer-community-5.1.73.msi' Signature file `mysql-installer-community-5.1.73.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: The Decrypt/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: The Decrypt/Verify Results: Good 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: The Decrypt/Verify Results: Bad The *Note checking-gpg-signature:: section explains why you probably don't see a green `Good signature' result.  File: manual.info, Node: checking-rpm-signature, Prev: checking-gpg-signature-windows, Up: verifying-package-integrity 2.1.4.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.1.73-0.glibc23.i386.rpm MySQL-server-5.1.73-0.glibc23.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.1/en/checking-gpg-signature.html If you need to obtain the MySQL public key, see *Note checking-gpg-signature::.  File: manual.info, Node: installation-layouts, Next: compiler-characteristics, Prev: verifying-package-integrity, Up: general-installation-issues 2.1.5 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. * *Note windows-installation-layout:: * *Note source-installation-layout:: * *Note binary-installation-layout:: * *Note mysql-installation-layout-linuxrpm:: * *Note mysql-installation-layout-macosx::  File: manual.info, Node: compiler-characteristics, Prev: installation-layouts, Up: general-installation-issues 2.1.6 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. * `InnoDB Plugin' is not included.  File: manual.info, Node: binary-installation, Next: windows-installation, Prev: general-installation-issues, Up: installing 2.2 Installing MySQL on Unix/Linux Using Generic Binaries ========================================================= Oracle provides a set of binary distributions of MySQL. These include binary distributions in the form of compressed `tar' files (files with a `.tar.gz' extension) for a number of platforms, as well as binaries in platform-specific package formats for selected platforms. This section covers the installation of MySQL from a compressed `tar' file binary distribution. For other platform-specific package formats, see the other platform-specific sections. For example, for Windows distributions, see *Note windows-installation::. To obtain MySQL, see *Note getting-mysql::. MySQL compressed `tar' file binary distributions have names of the form `mysql-VERSION-OS.tar.gz', where `VERSION' is a number (for example, `5.1.73'), and OS indicates the type of operating system for which the distribution is intended (for example, `pc-linux-i686' or `winx64'). 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/'. *Warning*: If you have previously installed MySQL using your operating system native package management system, such as `yum' or `apt-get', you may experience problems installing using a native binary. Make sure your previous MySQL previous 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 the existence of configuration files such as `/etc/my.cnf' or the `/etc/mysql' directory have been deleted. If you run into problems and need to file a bug report, please use the instructions in *Note bug-reports::. On Unix, 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' Client programs and the *Note `mysqld': mysqld. server `data' Log files, databases `docs' Manual in Info format `man' Unix manual pages `include' Include (header) files `lib' Libraries `scripts' *Note `mysql_install_db': mysql-install-db. `share' Miscellaneous support files, including error messages, sample configuration files, SQL for database installation `sql-bench' Benchmarks Debug versions of the *Note `mysqld': mysqld. binary are available as *Note `mysqld-debug': mysqld. To compile your own debug version of MySQL from a source distribution, use the appropriate configuration options to enable debugging support. For more information on compiling from source, see *Note source-installation::. To install and use a MySQL binary distribution, the basic command sequence looks like this: shell> groupadd mysql shell> useradd -r -g mysql 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> chown -R mysql . shell> chgrp -R mysql . shell> scripts/mysql_install_db --user=mysql shell> chown -R root . shell> chown -R mysql data # Next command is optional shell> cp support-files/my-medium.cnf /etc/my.cnf 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 preceding description for installing a binary distribution follows. *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' (OpenSolaris) command. The procedure does not set up any passwords for MySQL accounts. After following the procedure, proceed to *Note default-privileges::. * Create a `mysql' User and Group * If your system does not already have a user and group for *Note `mysqld': mysqld. to run as, you may need to create one. 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, or they may have different names such as `adduser' and `addgroup'. shell> groupadd mysql shell> useradd -r -g mysql mysql *Note*: Because the user is required only for ownership purposes, not login purposes, the `useradd' command uses the `-r' option to create a user that does not have login permissions to your server host. Omit this option to permit logins for the user (or if your `useradd' does not support the option). * 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 *Note 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. Then create a symbolic link to that directory. `tar' can uncompress and unpack the distribution if it has `z' option support: shell> tar zxvf /PATH/TO/MYSQL-VERSION-OS.tar.gz shell> ln -s FULL-PATH-TO-MYSQL-VERSION-OS mysql The `tar' command creates a directory named `mysql-VERSION-OS'. The `ln' command makes a symbolic link to that directory. This enables you to refer more easily to the installation directory as `/usr/local/mysql'. 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 - * 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 next steps, see *Note 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 *Note default-privileges::.  File: manual.info, Node: windows-installation, Next: macosx-installation, Prev: binary-installation, Up: installing 2.3 Installing MySQL on Microsoft Windows ========================================= * Menu: * windows-installation-layout:: MySQL Installation Layout on Microsoft Windows * windows-choosing-package:: Choosing the Installation Package for Microsoft Windows * windows-using-installer:: Installing MySQL on Microsoft Windows Using an MSI Package * windows-notifier:: MySQL Notifier for Microsoft Windows * mysql-config-wizard:: Using the MySQL Server Instance Config Wizard * windows-install-archive:: Installing MySQL on Microsoft Windows Using a `noinstall' Zip Archive * windows-troubleshooting:: Troubleshooting a Microsoft Windows MySQL Server Installation * windows-upgrading:: Upgrading MySQL Server on Microsoft Windows * windows-postinstallation:: MySQL Server on Microsoft Windows Postinstallation Procedures MySQL for Microsoft Windows is available in a number of different forms. A Microsoft Windows operating system such as Windows 2000, Windows XP, Windows Vista, Windows 7, Windows Server 2003, or Windows Server 2008. Both 32-bit and 64-bit versions are supported. For supported platform information, see http://www.mysql.com/support/supportedplatforms/database.html. In addition to running MySQL as a standard application, you can also run the MySQL server 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 *Note 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'. Once installed, MySQL does not need to be executed using a user with Administrator privileges. For a list of limitations within the Windows version of MySQL, see *Note 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: * If you plan to connect to the MySQL server using ODBC, you need a Connector/ODBC driver. For more information, including installation and configuration instructions, see *Note connector-odbc::. * If you plan to use MySQL server with .NET applications, you need the Connector/Net driver. For more information, including installation and configuration instructions, see *Note connector-net::. MySQL distributions for Windows can be downloaded from `http://dev.mysql.com/downloads/'. See *Note getting-mysql::. MySQL for Windows is available in several distribution formats, detailed below. Generally speaking, you should use a binary distribution that includes an installer. It is simpler to use than the others, and you need no additional tools to get MySQL up and running. The installer for the Windows version of MySQL, combined with a GUI Config Wizard, automatically installs MySQL, creates an option file, starts the server, and secures the default user accounts. * Binary installer distribution. The installable distribution comes packaged as a Microsoft Windows Installer (MSI) package that you can install manually or automatically on your systems. Two formats are available, an essentials package that contains all the files you need to install and configure MySQL, but no additional components, and a complete package that includes MySQL, configuration tools, benchmarks and other components. For more information on the specific differences, see *Note windows-choosing-package:: For instructions on installing MySQL using one of the MSI installation packages, see *Note windows-using-installer::. * Standard binary distribution format packaged as a Zip file containing 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 Zip file, see *Note windows-install-archive::. * The source distribution 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 *Note windows-source-build::. *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 *Note create-table::. * *MySQL and Virus Checking Software* Using 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 mis-identifying the contents of the files as containing spam. This is because of 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') being used to store your MySQL table data. There is usually a system built into the virus scanning software to permit certain directories to be specifically ignored during virus scanning. In addition, by default, MySQL creates temporary files in the standard Windows temporary directory. To prevent the temporary files also being scanned, you should configure a separate temporary directory for MySQL temporary files and add this 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 *Note windows-create-option-file::.  File: manual.info, Node: windows-installation-layout, Next: windows-choosing-package, Prev: windows-installation, Up: windows-installation 2.3.1 MySQL Installation Layout on Microsoft Windows ---------------------------------------------------- For MySQL 5.1 on Windows, the default installation directory is `C:\Program Files\MySQL\MySQL Server 5.1'. Some Windows users prefer to install in `C:\mysql', the directory that formerly was used as the default. However, the layout of the subdirectories remains the same. For MySQL 5.1.23 and earlier, all of the files are located within the parent directory, using the structure shown in the following table. *Installation Layout for Windows Using MySQL 5.1.23 and Earlier* Directory Contents of Directory `bin' Client programs and the *Note `mysqld': mysqld. server `data' Log files, databases `examples' Example programs and scripts `include' Include (header) files `lib' Libraries `scripts' Utility scripts `share' Miscellaneous support files, including error messages, character set files, sample configuration files, SQL for database installation For MySQL 5.1.24 and later, the default location of data directory was changed. The remainder of the directory structure remains the same. *Installation Layout for Microsoft Windows using MySQL 5.1.24 and later* Directory Contents of Directory Notes `bin' Client programs and the *Note `mysqld': mysqld. server `%ALLUSERSPROFILE%\MySQL\MySQLLog files, databases The Windows system Server 5.1\' (Windows XP, Windows Server variable 2003) %ALLUSERSPROFILE% defaults to `C:\Documents and Settings\All Users\Application Data' `%PROGRAMDATA%\MySQL\MySQLLog files, databases (Vista, The Windows system Server 5.1\' Windows 7, Windows Server variable 2008, and newer) %PROGRAMDATA% defaults to `C:\ProgramData' `examples' Example programs and scripts `include' Include (header) files `lib' Libraries `scripts' Utility scripts `share' Miscellaneous support files, including error messages, character set files, sample configuration files, SQL for database installation  File: manual.info, Node: windows-choosing-package, Next: windows-using-installer, Prev: windows-installation-layout, Up: windows-installation 2.3.2 Choosing the Installation Package for Microsoft Windows ------------------------------------------------------------- For MySQL 5.1, there are three installation package formats to choose from when installing MySQL on Windows: *Note*: Using MySQL Installer is the recommended installation method for Microsoft Windows users. The MySQL Server 5.1 release does not include its own MySQL Installer release, but a MySQL Installer version 5.5 and above can optionally install MySQL Server 5.1. Follow the standard Installing MySQL on Microsoft Windows Using MySQL Installer (http://dev.mysql.com/doc/refman/5.5/en/mysql-installer.html) documentation but choose `Custom Install' after executing it. A MySQL Server 5.1 option will be available, and choosing it will cause MySQL Installer to download it for you. *Microsoft Windows MySQL Installation package comparison* Packaging Feature Essentials Complete Zip (No-install) Installer Yes Yes No Directory-only MySQL Server Instance Config Yes Yes No Wizard Test Suite No Yes Yes MySQL Server Yes Yes Yes MySQL Client Programs Yes Yes Yes C Headers/Libraries Yes Yes Yes Embedded Server No Optional Yes Scripts and Examples No Optional Yes In the above table: * _Yes_ indicates that the component is installed by default. * _No_ indicates that the component is not installed or included. * _Optional_ indicates that the component is included with the package, but not installed unless explicitly requested using the Custom installation mode. The workflow for installing using the MSI installer is shown below: FIGURE GOES HERE: Installation Workflow for Windows Using MSI The workflow for installing using the MSI installer is shown below: FIGURE GOES HERE: Installation Workflow for Windows Using Zip *Note*: For the Essentials and Complete packages in the MSI installer, you can select individual components to be installed by using the Custom mode, including disable the components confiurated for installation by default. Full details on the components are suggested uses are provided below for reference: * *Windows Essentials*: This package has a file name similar to `mysql-essential-5.1.73-win32.msi' and is supplied as a Microsoft Installer (MSI) package. The package includes the minimum set of files needed to install MySQL on Windows, including the MySQL Server Instance Config Wizard. This package does not include optional components such as the embedded server, developer headers and libraries or benchmark suite. To install using this package, see *Note windows-using-installer::. * *Windows MSI Installer (Complete)*: This package has a file name similar to `mysql-5.1.73-win32.msi' and contains all files needed for a complete Windows installation, including the MySQL Server Instance Config Wizard. This package includes optional components such as the embedded server and benchmark suite. To install using this package, see *Note windows-using-installer::. * *Without installer*: This package has a file name similar to `mysql-noinstall-5.1.73-win32.zip' and contains all the files found in the Complete install package, with the exception of the MySQL Server Instance Config Wizard. This package does not include an automated installer, and must be manually installed and configured. The Essentials package is recommended for most users. Both the Essentials and Complete distributions are available as an `.msi' file for use with the Windows Installer. The Noinstall distribution is packaged as a Zip archive. To use a Zip archive, you must have a tool that can unpack `.zip' files. When using the MSI installers you can automate the installation process. For more information, see *Note windows-installer-msi-quiet::. To automate the creation of a MySQL instance, see *Note mysql-config-wizard-cmdline::. Your choice of install package affects the installation process you must follow. If you choose to install either an Essentials or Complete install package, see *Note windows-using-installer::. If you choose to install a Noinstall archive, see *Note windows-install-archive::.  File: manual.info, Node: windows-using-installer, Next: windows-notifier, Prev: windows-choosing-package, Up: windows-installation 2.3.3 Installing MySQL on Microsoft Windows Using an MSI Package ---------------------------------------------------------------- * Menu: * windows-install-wizard:: Using the MySQL Installation Wizard for Microsoft Windows * windows-installer-msi-quiet:: Automating MySQL Installation on Microsoft Windows Using the MSI Package * windows-installer-uninstalling:: Removing MySQL When Installed from the MSI Package The MSI package is designed to install and configure MySQL in such a way that you can immediately get started using MySQL. The MySQL Installation Wizard and MySQL Configuration Wizard are available in the Essentials and Complete install packages. They are recommended for most standard MySQL installations. Exceptions include users who need to install multiple instances of MySQL on a single server host and advanced users who want complete control of server configuration. * For information on installing using the GUI MSI installer process, see *Note windows-install-wizard::. * For information on installing using the command line using the MSI package, see *Note windows-installer-msi-quiet::. * If you have previously installed MySQL using the MSI package and want to remove MySQL, see *Note windows-installer-uninstalling::. The workflow sequence for using the installer is shown in the figure below: FIGURE GOES HERE: Installation Workflow for Windows Using MSI Installer *Note*: Microsoft Windows XP and later include a firewall which specifically blocks ports. If you plan on using MySQL through a network port then you should open and create an exception for this port before performing the installation. To check and if necessary add an exception to the firewall settings: 1. First ensure that you are logged in as an Administrator or a user with Administrator privileges. 2. Go to the `Control Panel', and double click the `Windows Firewall' icon. 3. Choose the `Allow a program through Windows Firewall' option and click the `Add port' button. 4. Enter `MySQL' into the `Name' text box and `3306' (or the port of your choice) into the `Port number' text box. 5. Also ensure that the `TCP' protocol radio button is selected. 6. If you wish, you can also limit access to the MySQL server by choosing the `Change scope' button. 7. Confirm your choices by clicking the `OK' button. Additionally, when running the MySQL Installation Wizard on Windows Vista or newer, ensure that you are logged in as a user with administrative rights. *Note*: When using Windows Vista or newer, you may want to disable User Account Control (UAC) before performing the installation. If you do not do so, then MySQL may be identified as a security risk, which will mean that you need to enable MySQL. You can disable the security checking by following these instructions: 1. Open `Control Panel'. 2. Under the `User Accounts and Family Safety', select `Add or remove user accounts.' 3. Click the `Got to the main User Accounts page' link. 4. Click on `Turn User Account Control on or off'. You may be prompted to provide permission to change this setting. Click `Continue'. 5. Deselect or uncheck the check box next to `Use User Account Control (UAC) to help protect your computer'. Click `OK' to save the setting. You will need to restart to complete the process. Click `Restart Now' to reboot the machine and apply the changes. You can then follow the instructions below for installing Windows.  File: manual.info, Node: windows-install-wizard, Next: windows-installer-msi-quiet, Prev: windows-using-installer, Up: windows-using-installer 2.3.3.1 Using the MySQL Installation Wizard for Microsoft Windows ................................................................. * Menu: * mysql-install-wizard-starting:: MySQL Installation Wizard: Downloading and Starting * mysql-install-wizard-install-type:: MySQL Installation Wizard: Choosing an Install Type * mysql-install-wizard-custom-install:: MySQL Installation Wizard: The Custom Install Dialog * mysql-install-wizard-confirmation-dialog:: MySQL Installation Wizard: The Confirmation Dialog * mysql-install-wizard-changes:: MySQL Installation Wizard: Changes Made * mysql-install-wizard-upgrading:: MySQL Installation Wizard: Upgrading MySQL MySQL Installation Wizard is an installer for the MySQL server that uses the latest installer technologies for Microsoft Windows. The MySQL Installation Wizard, in combination with the MySQL Config Wizard, enables a user to install and configure a MySQL server that is ready for use immediately after installation. The MySQL Installation Wizard uses the standard Microsoft Installer Engine (MSI) system is the standard installer for all MySQL server distributions. See *Note mysql-install-wizard-upgrading::, for more information on upgrading from a previous version. If you are upgrading an installation from MySQL 5.1.31 or earlier to MySQL 5.1.32 or later, read the notes provided in *Note mysql-install-wizard-upgrading::. The Microsoft Windows Installer Engine was updated with the release of Windows XP; those using a previous version of Windows can reference this Microsoft Knowledge Base article (http://support.microsoft.com/default.aspx?scid=kb;EN-US;292539) for information on upgrading to the latest version of the Windows Installer Engine. In addition, Microsoft has introduced the WiX (Windows Installer XML) toolkit. This is the first highly acknowledged Open Source project from Microsoft. We have switched to WiX because it is an Open Source project and it enables us to handle the complete Windows installation process in a flexible manner using scripts. Improving the MySQL Installation Wizard depends on the support and feedback of users like you. If you find that the MySQL Installation Wizard is lacking some feature important to you, or if you discover a bug, please report it in our bugs database using the instructions given in *Note bug-reports::.  File: manual.info, Node: mysql-install-wizard-starting, Next: mysql-install-wizard-install-type, Prev: windows-install-wizard, Up: windows-install-wizard 2.3.3.2 MySQL Installation Wizard: Downloading and Starting ........................................................... The MySQL installation packages can be downloaded from `http://dev.mysql.com/downloads/'. If the package you download is contained within a Zip archive, you need to extract the archive first. The process for starting the wizard depends on the contents of the installation package you download. If there is a `setup.exe' file present, double-click it to start the installation process. If there is an `.msi' file present, double-click it to start the installation process.  File: manual.info, Node: mysql-install-wizard-install-type, Next: mysql-install-wizard-custom-install, Prev: mysql-install-wizard-starting, Up: windows-install-wizard 2.3.3.3 MySQL Installation Wizard: Choosing an Install Type ........................................................... There are three installation types available: *Typical*, *Complete*, and *Custom*. The *Typical* installation type installs the MySQL server, the *Note `mysql': mysql. command-line client, and the command-line utilities. The command-line clients and utilities include *Note `mysqldump': mysqldump, *Note `myisamchk': myisamchk, and several other tools to help you manage the MySQL server. The *Complete* installation type installs all components included in the installation package. The full installation package includes components such as the embedded server library, the benchmark suite, support scripts, and documentation. The *Custom* installation type gives you complete control over which packages you wish to install and the installation path that is used. See *Note mysql-install-wizard-custom-install::, for more information on performing a custom install. If you choose the *Typical* or *Complete* installation types and click the `Next' button, you advance to the confirmation screen to verify your choices and begin the installation. If you choose the *Custom* installation type and click the `Next' button, you advance to the custom installation dialog, described in *Note mysql-install-wizard-custom-install::.  File: manual.info, Node: mysql-install-wizard-custom-install, Next: mysql-install-wizard-confirmation-dialog, Prev: mysql-install-wizard-install-type, Up: windows-install-wizard 2.3.3.4 MySQL Installation Wizard: The Custom Install Dialog ............................................................ If you wish to change the installation path or the specific components that are installed by the MySQL Installation Wizard, choose the *Custom* installation type. A tree view on the left side of the custom install dialog lists all available components. Components that are not installed have a red `X' icon; components that are installed have a gray icon. To change whether a component is installed, click that component's icon and choose a new option from the drop-down list that appears. You can change the default installation path by clicking the `Change...' button to the right of the displayed installation path. After choosing your installation components and installation path, click the `Next' button to advance to the confirmation dialog.  File: manual.info, Node: mysql-install-wizard-confirmation-dialog, Next: mysql-install-wizard-changes, Prev: mysql-install-wizard-custom-install, Up: windows-install-wizard 2.3.3.5 MySQL Installation Wizard: The Confirmation Dialog .......................................................... Once you choose an installation type and optionally choose your installation components, you advance to the confirmation dialog. Your installation type and installation path are displayed for you to review. To install MySQL if you are satisfied with your settings, click the `Install' button. To change your settings, click the `Back' button. To exit the MySQL Installation Wizard without installing MySQL, click the `Cancel' button. In MySQL 5.1.47 and earlier, after installation is complete, you have the option of registering with the MySQL web site. Registration gives you access to post in the MySQL forums at forums.mysql.com (http://forums.mysql.com), along with the ability to report bugs at bugs.mysql.com (http://bugs.mysql.com) and to subscribe to our newsletter. The final screen of the installer provides a summary of the installation and gives you the option to launch the MySQL Config Wizard, which you can use to create a configuration file, install the MySQL service, and configure security settings.  File: manual.info, Node: mysql-install-wizard-changes, Next: mysql-install-wizard-upgrading, Prev: mysql-install-wizard-confirmation-dialog, Up: windows-install-wizard 2.3.3.6 MySQL Installation Wizard: Changes Made ............................................... Once you click the `Install' button, the MySQL Installation Wizard begins the installation process and makes certain changes to your system which are described in the sections that follow. *Changes to the Registry* The MySQL Installation Wizard creates one Windows registry key in a typical install situation, located in `HKEY_LOCAL_MACHINE\SOFTWARE\MySQL AB'. For 64-bit Windows, the registry location is `HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\MYSQL AB'. A server version specific entry will be created for each major version of MySQL that you install. The MySQL Installation Wizard creates a key named after the major version of the server that is being installed, such as `MySQL Server 5.1'. It contains two string values, `Location' and `Version'. The `Location' string contains the path to the installation directory. In a default installation it contains `C:\Program Files\MySQL\MySQL Server 5.1\'. The `Version' string contains the release number. For example, for an installation of MySQL Server 5.1.73, the key contains a value of `5.1.73'. These registry keys are used to help external tools identify the installed location of the MySQL server, preventing a complete scan of the hard-disk to determine the installation path of the MySQL server. The registry keys are not required to run the server, and if you install MySQL using the `noinstall' Zip archive, the registry keys are not created. *Changes to the Start Menu* The MySQL Installation Wizard creates a new entry in the Windows `Start' menu under a common MySQL menu heading named after the major version of MySQL that you have installed. For example, if you install MySQL 5.1, the MySQL Installation Wizard creates a `MySQL Server 5.1' section in the `Start' menu. The following entries are created within the new `Start' menu section: * `MySQL Command-Line Client': This is a shortcut to the *Note `mysql': mysql. command-line client and is configured to connect as the `root' user. The shortcut prompts for a `root' user password when you connect. * `MySQL Server Instance Config Wizard': This is a shortcut to the MySQL Config Wizard. Use this shortcut to configure a newly installed server, or to reconfigure an existing server. * `MySQL Documentation': This is a link to the MySQL server documentation that is stored locally in the MySQL server installation directory. This option is not available when the MySQL server is installed using the Essentials installation package. *Changes to the File System* The MySQL Installation Wizard by default installs the MySQL 5.1 server to `C:\PROGRAM FILES\MySQL\MySQL Server 5.1', where PROGRAM FILES is the default location for applications in your system, and 5.1 is the major version of your MySQL server. This is the recommended location for the MySQL server, replacing the former default location `C:\mysql'. By default, all MySQL applications are stored in a common directory at `C:\PROGRAM FILES\MySQL', where PROGRAM FILES is the default location for applications in your Windows installation. A typical MySQL installation on a developer machine might look like this: C:\Program Files\MySQL\MySQL Server 5.1 C:\Program Files\MySQL\MySQL Workbench 5.1 OSS This approach makes it easier to manage and maintain all MySQL applications installed on a particular system. In MySQL 5.1.23 and earlier, the default location for the data files used by MySQL is located within the corresponding MySQL Server installation directory. For MySQL 5.1.24 and later, the default location of the data directory is the `AppData' directory configured for the user that installed the MySQL application.  File: manual.info, Node: mysql-install-wizard-upgrading, Prev: mysql-install-wizard-changes, Up: windows-install-wizard 2.3.3.7 MySQL Installation Wizard: Upgrading MySQL .................................................. The MySQL Installation Wizard can perform server upgrades automatically using the upgrade capabilities of MSI. That means you do not need to remove a previous installation manually before installing a new release. The installer automatically shuts down and removes the previous MySQL service before installing the new version. Automatic upgrades are available only when upgrading between installations that have the same major and minor version numbers. For example, you can upgrade automatically from MySQL 5.1.5 to MySQL 5.1.6, but not from MySQL 5.0 to MySQL 5.1. In MySQL 5.1.32 and later, the `EXE' version of the MSI installer packages were removed. When upgrading an existing MySQL installation from the old EXE based installer to the MSI based installer, please keep the following notes in mind: * The MSI installer will not identify an existing installation that was installed using the old EXE installer. This means that the installer will not stop the existing server, or detect that the existing password is required before installing the new version. To work around this: 1. Stop the current server manually using `net stop' or `mysqladmin shutdown'. 2. Remove the existing installation manually by using the `Add/Remove Programs' control panel. This will keep the existing configuration and data files, as these are not removed automatically. 3. Install the new version of MySQL using the MSI installer. When running the installation, skip updating the security by deselecting the check box on the security screen. 4. Complete the installation, and then start the server again. You should be able to login with your existing user and password credentials. * You can only upgrade the version and release using the MSI installer. For example, you can upgrade an open source installation with an open source installer. You cannot upgrade an open source installation using the enterprise installer. See *Note windows-upgrading::.  File: manual.info, Node: windows-installer-msi-quiet, Next: windows-installer-uninstalling, Prev: windows-install-wizard, Up: windows-using-installer 2.3.3.8 Automating MySQL Installation on Microsoft Windows Using the MSI Package ................................................................................ The Microsoft Installer (MSI) supports a both a _quiet_ and a _passive_ mode that can be used to install MySQL automatically without requiring intervention. You can use this either in scripts to automatically install MySQL or through a terminal connection such as Telnet where you do not have access to the standard Windows user interface. The MSI packages can also be used in combination with Microsoft's Group Policy system (part of Windows Server 2003 and Windows Server 2008) to install MySQL across multiple machines. To install MySQL from one of the MSI packages automatically from the command line (or within a script), you need to use the `msiexec.exe' tool. For example, to perform a quiet installation (which shows no dialog boxes or progress): shell> msiexec /i mysql-5.1.73.msi /quiet The `/i' indicates that you want to perform an installation. The `/quiet' option indicates that you want no interactive elements. To provide a dialog box showing the progress during installation, and the dialog boxes providing information on the installation and registration of MySQL, use `/passive' mode instead of `/quiet': shell> msiexec /i mysql-5.1.73.msi /passive Regardless of the mode of the installation, installing the package in this manner performs a 'Typical' installation, and installs the default components into the standard location. You can also use this method to uninstall MySQL by using the `/uninstall' or `/x' options: shell> msiexec /x mysql-5.1.73.msi /uninstall To install MySQL and configure a MySQL instance from the command line, see *Note mysql-config-wizard-cmdline::. For information on using MSI packages to install software automatically using Group Policy, see How to use Group Policy to remotely install software in Windows Server 2003 (http://support.microsoft.com/kb/816102).  File: manual.info, Node: windows-installer-uninstalling, Prev: windows-installer-msi-quiet, Up: windows-using-installer 2.3.3.9 Removing MySQL When Installed from the MSI Package .......................................................... To uninstall a MySQL where you have used the MSI packages, you must use the `Add/Remove Programs' tool within `Control Panel'. To do this: 1. Right-click the `start' menu and choose `Control Panel'. 2. If the Control Panel is set to category mode (you will see `Pick a category' at the top of the `Control Panel' window), double-click `Add or Remove Programs'. If the Control is set to classic mode, double-click the `Add or Remove Programs' icon. 3. Find MySQL in the list of installed software. MySQL Server is installed against major version numbers (MySQL 5.0, MySQL 5.1, etc.). Select the version that you want to remove and click `Remove'. 4. You will be prompted to confirm the removal. Click `Yes' to remove MySQL. When MySQL is removed using this method, only the installed components are removed. Any database information (including the tables and data), import or export files, log files, and binary logs produced during execution are kept in their configured location. If you try to install MySQL again the information will be retained and you will be prompted to enter the password configured with the original installation. If you want to delete MySQL completely: * Delete the associated data directory. On Windows XP and Windows Server 2003, before MySQL 5.1.24, the default data directory would be located within the MySQL installation directory. On MySQL 5.1.24 and later, the default data directory is the configured AppData directory, which is `C:\Documents and Settings\All Users\Application Data\MySQL' by default. * On Windows 7 and Windows Server 2008, the default data directory location is `C:\ProgramData\Mysql'. *Note*: The `C:\ProgramData' directory is hidden by default. You must change your folder options to view the hidden file. Choose `Organize', `Folder and search options', `Show hidden folders'.  File: manual.info, Node: windows-notifier, Next: mysql-config-wizard, Prev: windows-using-installer, Up: windows-installation 2.3.4 MySQL Notifier for Microsoft Windows ------------------------------------------ * Menu: * windows-notifier-installation:: Remote monitoring set up and installation instructions The MySQL Notifier for Microsoft Windows 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 system tray. The MySQL Notifier for Microsoft Windows also gives quick access to several MySQL GUI tools (such as MySQL Workbench) through its context menu. The MySQL Notifier for Microsoft Windows is installed by MySQL Installer, and (by default) will start-up when Microsoft Windows is started. *Note*: To install, download and execute the MySQL Installer (http://dev.mysql.com/downloads/installer/), be sure the MySQL Notifier for Microsoft Windows product is selected, then proceed with the installation. See the MySQL Installer manual (http://dev.mysql.com/doc/refman/5.5/en/mysql-installer.html) for additional details. For release notes detailing the changes in each release of MySQL Notifier for Microsoft Windows, 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 for Microsoft Windows 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's green if all monitored MySQL Server instances are running, or red 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 `Configure Instance' will load the MySQL Workbench Server Administration window for that particular instance. * If MySQL Workbench is also installed, then the `Configure Instance' and `SQL Editor' options are available for local (but not remote) MySQL instances. * Monitoring of both local and remote MySQL instances. *Note*: Remote monitoring is available since MySQL Notifier for Microsoft Windows 1.1.0. The MySQL Notifier for Microsoft Windows resides in the system tray and provides visual status information for your MySQL Server instances. A green icon is displayed at the top left corner of the tray icon if the current MySQL Server is running, or a red icon if the service is stopped. The MySQL Notifier for Microsoft Windows automatically adds discovered MySQL Services on the local machine, and each service is saved and configurable. By default, the `Automatically add new services whose name contains' option is enabled and set to `mysql'. Related `Notifications Options' include being notified when new services are either discovered or experience status changes, and are also enabled by default. And uninstalling a service will also remove the service from the MySQL Notifier for Microsoft Windows. *Note*: The `Automatically add new services whose name contains' option default changed from ".*mysqld.*" to "mysql" in Notifier 1.1.0. Clicking the system tray icon will reveal several options, as seen in the screenshots below: The Service Instance menu is the main MySQL Notifier for Microsoft Windows window, and enables you to Stop, Start, and Restart the MySQL Server. FIGURE GOES HERE: MySQL Notifier for Microsoft Windows Service Instance menu The `Actions' menu includes several links to external applications (if they are installed), and a a `Refresh Status' option to manually refresh the status of all monitored services (in both local and remote computers) and MySQL instances. *Note*: The main menu will not show the `Actions' menu when there are no services being monitored by MySQL Notifier for Microsoft Windows. *Note*: The `Refresh Status' feature is available since MySQL Notifier for Microsoft Windows 1.1.0. FIGURE GOES HERE: MySQL Notifier for Microsoft Windows Actions menu The `Actions', `Options' menu configures MySQL Notifier for Microsoft Windows and includes options to: * `Use colorful status icons': Enables a colorful style of icons for the tray of the MySQL Notifier for Microsoft Windows. * `Run at Windows Startup': Allows the application to be loaded when Microsoft Windows starts. * `Automatically Check For Updates Every' # Weeks: Checks for a new version of MySQL Notifier for Microsoft Windows, and runs this check every # 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. monitored services, and also filters the list of the Microsoft Windows services for the `Add New Service' dialog. Prior to version 1.1.0, this option was named "Automatically add new services that match this pattern." * `Notify me when a service is automatically added': Will display a balloon notification from the taskbar when a newly discovered service is added to the monitored services list. * `Notify me when a service changes status': Will display a balloon notification from the taskbar when a monitored service changes its status. FIGURE GOES HERE: MySQL Notifier for Microsoft Windows Options menu The `Actions', `Manage Monitored Items' menu enables you to configure the monitored services and MySQL instances. First, with the `Services' tab open: FIGURE GOES HERE: MySQL Notifier for Microsoft Windows Manage Services menu The `Instances' tab is similar: FIGURE GOES HERE: MySQL Notifier for Microsoft Windows Manage Instances menu Adding a service or instance (after clicking `Add' in the `Manage Monitored Items' window) enables you to select a running Microsoft Windows service or instance connection, and configure MySQL Notifier for Microsoft Windows to monitor it. Add a new service or instance by clicking service name from the list, then `OK' to accept. Multiple services and instances may be selected. FIGURE GOES HERE: MySQL Notifier for Microsoft Windows Adding new services And instances: FIGURE GOES HERE: MySQL Notifier for Microsoft Windows Adding new instances *Note*: The `Instances' tab available since MySQL Notifier for Microsoft Windows 1.1.0.  File: manual.info, Node: windows-notifier-installation, Prev: windows-notifier, Up: windows-notifier 2.3.4.1 Remote monitoring set up and installation instructions .............................................................. The MySQL Notifier for Microsoft Windows uses Windows Management Instrumentation (WMI) to manage and monitor services in remote computers running Windows XP or later. This guide explains how it works, and how to set up your system to monitor remote MySQL instances. *Note*: Remote monitoring is available since MySQL Notifier for Microsoft Windows 1.1.0. 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 for Microsoft Windows is using asynchronous notification queries on remote Microsoft Windows hosts as .NET events. These events send an asynchronous callback to the computer running the MySQL Notifier for Microsoft Windows so it knows when a service status has changed on the remote computer. Asynchronous notifications offer the best performance compared to semi-synchronous notifications or synchronous notifications that use timers. Asynchronous notifications 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. FIGURE GOES HERE: MySQL Notifier for Microsoft Windows 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 *Note 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 for Microsoft Windows (Computer A), and multiple remote machines that are being monitored (Computer B). * Computer running MySQL Notifier for Microsoft Windows (Computer A) * 1. 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 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 click `Run as Administrator') . 2. Execute the following command: NETSH firewall add portopening protocol=tcp port=135 name=DCOM_TCP135 3. Add the client application which 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's left panel, click `Allow a program or feature through Windows Firewall'. 3. In the Allowed Programs window, click `Change Settings'. 4. 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). 5. If `MySqlNotifier.exe' is not in the list, click `Allow another program...'. 6. 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'. 7. 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 firewall add allowedprogram program=[YOUR_INSTALL_DIRECTORY]\MySqlNotifier.exe name=MySqlNotifier 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 into the computer running the MySQL Notifier for Microsoft Windows (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 Access Permissions, click `Edit Limits'. 5. In the `Launch 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 Permission' dialog box, click `Add'. 2. In the Select Users, Computers, 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 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 and double-click the `WMI Control'. 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'. 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 firewall set service RemoteAdmin enable 4. Now, be sure the user 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. 5. If the remote computer is running on `Windows XP Professional', make sure that remote logins are not being forcefully changed to the guest account user (also known as `ForceGuest'), which is enabled by default on computers that are not attached to a domain. 1. Click Start, click Run, type `SECPOL.MSC', and then click `OK'. 2. Under the `Local Policies' node, double-click `Security Options'. 3. Select `Network Access: Sharing and security model for local accounts' and save. * 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.  File: manual.info, Node: mysql-config-wizard, Next: windows-install-archive, Prev: windows-notifier, Up: windows-installation 2.3.5 Using the MySQL Server Instance Config Wizard --------------------------------------------------- * Menu: * mysql-config-wizard-starting:: Starting the MySQL Server Instance Config Wizard * mysql-config-wizard-maintenance:: MySQL Server Instance Config Wizard: Choosing a Maintenance Option * mysql-config-wizard-configuration-type:: MySQL Server Instance Config Wizard: Choosing a Configuration Type * mysql-config-wizard-server-type:: MySQL Server Instance Config Wizard: The Server Type Dialog * mysql-config-wizard-database-usage:: MySQL Server Instance Config Wizard: The Database Usage Dialog * mysql-config-wizard-tablespace:: MySQL Server Instance Config Wizard: The InnoDB Tablespace Dialog * mysql-config-wizard-connections:: MySQL Server Instance Config Wizard: The Concurrent Connections Dialog * mysql-config-wizard-networking:: MySQL Server Instance Config Wizard: The Networking and Strict Mode Options Dialog * mysql-config-wizard-character-set:: MySQL Server Instance Config Wizard: The Character Set Dialog * mysql-config-wizard-service:: MySQL Server Instance Config Wizard: The Service Options Dialog * mysql-config-wizard-security:: MySQL Server Instance Config Wizard: The Security Options Dialog * mysql-config-wizard-confirmation:: MySQL Server Instance Config Wizard: The Confirmation Dialog * mysql-config-wizard-cmdline:: MySQL Server Instance Config Wizard: Creating an Instance from the Command Line The MySQL Server Instance Config Wizard helps automate the process of configuring your server. It creates a custom MySQL configuration file (`my.ini' or `my.cnf') by asking you a series of questions and then applying your responses to a template to generate the configuration file that is tuned to your installation. The complete and essential MSI installation packages include the MySQL Server Instance Config Wizard in the MySQL 5.1 server. The MySQL Server Instance Config Wizard is only available for Windows. The workflow sequence for using the MySQL Server Instance Config Wizard is shown in the figure below: FIGURE GOES HERE: MySQL Server Instance Config Wizard Workflow  File: manual.info, Node: mysql-config-wizard-starting, Next: mysql-config-wizard-maintenance, Prev: mysql-config-wizard, Up: mysql-config-wizard 2.3.5.1 Starting the MySQL Server Instance Config Wizard ........................................................ The MySQL Server Instance Config Wizard is normally started as part of the installation process. You should only need to run the MySQL Server Instance Config Wizard again when you need to change the configuration parameters of your server. If you chose not to open a port prior to installing MySQL on Windows Vista or newer, you can choose to use the MySQL Server Instance Config Wizard after installation. However, you must open a port in the Windows Firewall. To do this see the instructions given in *Note mysql-install-wizard-starting::. Rather than opening a port, you also have the option of adding MySQL as a program that bypasses the Windows Firewall. One or the other option is sufficient--you need not do both. Additionally, when running the MySQL Server Config Wizard on Windows Vista or newer, ensure that you are logged in as a user with administrative rights. MySQL Server Instance Config Wizard You can launch the MySQL Config Wizard by clicking the `MySQL Server Instance Config Wizard' entry in the `MySQL' section of the Windows `Start' menu. Alternatively, you can navigate to the `bin' directory of your MySQL installation and launch the `MySQLInstanceConfig.exe' file directly. The MySQL Server Instance Config Wizard places the `my.ini' file in the installation directory for the MySQL server. This helps associate configuration files with particular server instances. To ensure that the MySQL server knows where to look for the `my.ini' file, an argument similar to this is passed to the MySQL server as part of the service installation: --defaults-file="C:\PROGRAM FILES\MYSQL\MYSQL SERVER 5.1\my.ini" Here, C:\PROGRAM FILES\MYSQL\MYSQL SERVER 5.1 is replaced with the installation path to the MySQL Server. The `--defaults-file' option instructs the MySQL server to read the specified file for configuration options when it starts. Apart from making changes to the `my.ini' file by running the MySQL Server Instance Config Wizard again, you can modify it by opening it with a text editor and making any necessary changes. You can also modify the server configuration with the http://www.mysql.com/products/administrator/ utility. For more information about server configuration, see *Note server-options::. MySQL clients and utilities such as the *Note `mysql': mysql. and *Note `mysqldump': mysqldump. command-line clients are not able to locate the `my.ini' file located in the server installation directory. To configure the client and utility applications, create a new `my.ini' file in the Windows installation directory (for example, `C:\WINDOWS'). Under Windows Server 2003, Windows Server 2000, Windows XP, and Windows Vista, MySQL Server Instance Config Wizard will configure MySQL to work as a Windows service. To start and stop MySQL you use the `Services' application that is supplied as part of the Windows Administrator Tools.  File: manual.info, Node: mysql-config-wizard-maintenance, Next: mysql-config-wizard-configuration-type, Prev: mysql-config-wizard-starting, Up: mysql-config-wizard 2.3.5.2 MySQL Server Instance Config Wizard: Choosing a Maintenance Option .......................................................................... If the MySQL Server Instance Config Wizard detects an existing configuration file, you have the option of either reconfiguring your existing server, or removing the server instance by deleting the configuration file and stopping and removing the MySQL service. To reconfigure an existing server, choose the `Re-configure Instance' option and click the `Next' button. Any existing configuration file is not overwritten, but renamed (within the same directory) using a timestamp (Windows) or sequential number (Linux). To remove the existing server instance, choose the `Remove Instance' option and click the `Next' button. If you choose the `Remove Instance' option, you advance to a confirmation window. Click the `Execute' button. The MySQL Server Config Wizard stops and removes the MySQL service, and then deletes the configuration file. The server installation and its `data' folder are not removed. If you choose the `Re-configure Instance' option, you advance to the `Configuration Type' dialog where you can choose the type of installation that you wish to configure.  File: manual.info, Node: mysql-config-wizard-configuration-type, Next: mysql-config-wizard-server-type, Prev: mysql-config-wizard-maintenance, Up: mysql-config-wizard 2.3.5.3 MySQL Server Instance Config Wizard: Choosing a Configuration Type .......................................................................... When you start the MySQL Server Instance Config Wizard for a new MySQL installation, or choose the `Re-configure Instance' option for an existing installation, you advance to the `Configuration Type' dialog. MySQL Server Instance Config Wizard: Configuration Type There are two configuration types available: `Detailed Configuration' and `Standard Configuration'. The `Standard Configuration' option is intended for new users who want to get started with MySQL quickly without having to make many decisions about server configuration. The `Detailed Configuration' option is intended for advanced users who want more fine-grained control over server configuration. If you are new to MySQL and need a server configured as a single-user developer machine, the `Standard Configuration' should suit your needs. Choosing the `Standard Configuration' option causes the MySQL Config Wizard to set all configuration options automatically with the exception of `Service Options' and `Security Options'. The `Standard Configuration' sets options that may be incompatible with systems where there are existing MySQL installations. If you have an existing MySQL installation on your system in addition to the installation you wish to configure, the `Detailed Configuration' option is recommended. To complete the `Standard Configuration', please refer to the sections on `Service Options' and `Security Options' in *Note mysql-config-wizard-service::, and *Note mysql-config-wizard-security::, respectively.  File: manual.info, Node: mysql-config-wizard-server-type, Next: mysql-config-wizard-database-usage, Prev: mysql-config-wizard-configuration-type, Up: mysql-config-wizard 2.3.5.4 MySQL Server Instance Config Wizard: The Server Type Dialog ................................................................... There are three different server types available to choose from. The server type that you choose affects the decisions that the MySQL Server Instance Config Wizard makes with regard to memory, disk, and processor usage. MySQL Server Instance Config Wizard: Server Type * `Developer Machine': Choose this option for a typical desktop workstation where MySQL is intended only for personal use. It is assumed that many other desktop applications are running. The MySQL server is configured to use minimal system resources. * `Server Machine': Choose this option for a server machine where the MySQL server is running alongside other server applications such as FTP, email, and Web servers. The MySQL server is configured to use a moderate portion of the system resources. * `Dedicated MySQL Server Machine': Choose this option for a server machine that is intended to run only the MySQL server. It is assumed that no other applications are running. The MySQL server is configured to use all available system resources. *Note*: By selecting one of the preconfigured configurations, the values and settings of various options in your `my.cnf' or `my.ini' will be altered accordingly. The default values and options as described in the reference manual may therefore be different to the options and values that were created during the execution of the Config Wizard.  File: manual.info, Node: mysql-config-wizard-database-usage, Next: mysql-config-wizard-tablespace, Prev: mysql-config-wizard-server-type, Up: mysql-config-wizard 2.3.5.5 MySQL Server Instance Config Wizard: The Database Usage Dialog ...................................................................... The `Database Usage' dialog enables you to indicate the storage engines that you expect to use when creating MySQL tables. The option you choose determines whether the `InnoDB' storage engine is available and what percentage of the server resources are available to `InnoDB'. MySQL Server Instance Config Wizard: Usage Dialog * `Multifunctional Database': This option enables both the `InnoDB' and `MyISAM' storage engines and divides resources evenly between the two. This option is recommended for users who use both storage engines on a regular basis. * `Transactional Database Only': This option enables both the `InnoDB' and `MyISAM' storage engines, but dedicates most server resources to the `InnoDB' storage engine. This option is recommended for users who use `InnoDB' almost exclusively and make only minimal use of `MyISAM'. * `Non-Transactional Database Only': This option disables the `InnoDB' storage engine completely and dedicates all server resources to the `MyISAM' storage engine. This option is recommended for users who do not use `InnoDB'. The Config Wizard uses a template to generate the server configuration file. The `Database Usage' dialog sets one of the following option strings: Multifunctional Database: MIXED Transactional Database Only: INNODB Non-Transactional Database Only: MYISAM When these options are processed through the default template (my-template.ini) the result is: Multifunctional Database: default-storage-engine=InnoDB _myisam_pct=50 Transactional Database Only: default-storage-engine=InnoDB _myisam_pct=5 Non-Transactional Database Only: default-storage-engine=MyISAM _myisam_pct=100 skip-innodb The `_myisam_pct' value is used to calculate the percentage of resources dedicated to `MyISAM'. The remaining resources are allocated to `InnoDB'.  File: manual.info, Node: mysql-config-wizard-tablespace, Next: mysql-config-wizard-connections, Prev: mysql-config-wizard-database-usage, Up: mysql-config-wizard 2.3.5.6 MySQL Server Instance Config Wizard: The InnoDB Tablespace Dialog ......................................................................... Some users may want to locate the `InnoDB' tablespace files in a different location than the MySQL server data directory. Placing the tablespace files in a separate location can be desirable if your system has a higher capacity or higher performance storage device available, such as a RAID storage system. MySQL Server Instance Config Wizard: InnoDB Data Tablespace To change the default location for the `InnoDB' tablespace files, choose a new drive from the drop-down list of drive letters and choose a new path from the drop-down list of paths. To create a custom path, click the `...' button. If you are modifying the configuration of an existing server, you must click the `Modify' button before you change the path. In this situation you must move the existing tablespace files to the new location manually before starting the server.  File: manual.info, Node: mysql-config-wizard-connections, Next: mysql-config-wizard-networking, Prev: mysql-config-wizard-tablespace, Up: mysql-config-wizard 2.3.5.7 MySQL Server Instance Config Wizard: The Concurrent Connections Dialog .............................................................................. To prevent the server from running out of resources, it is important to limit the number of concurrent connections to the MySQL server that can be established. The `Concurrent Connections' dialog enables you to choose the expected usage of your server, and sets the limit for concurrent connections accordingly. It is also possible to set the concurrent connection limit manually. MySQL Server Instance Config Wizard: Connections * `Decision Support (DSS)/OLAP': Choose this option if your server does not require a large number of concurrent connections. The maximum number of connections is set at 100, with an average of 20 concurrent connections assumed. * `Online Transaction Processing (OLTP)': Choose this option if your server requires a large number of concurrent connections. The maximum number of connections is set at 500. * `Manual Setting': Choose this option to set the maximum number of concurrent connections to the server manually. Choose the number of concurrent connections from the drop-down box provided, or enter the maximum number of connections into the drop-down box if the number you desire is not listed.  File: manual.info, Node: mysql-config-wizard-networking, Next: mysql-config-wizard-character-set, Prev: mysql-config-wizard-connections, Up: mysql-config-wizard 2.3.5.8 MySQL Server Instance Config Wizard: The Networking and Strict Mode Options Dialog .......................................................................................... Use the `Networking Options' dialog to enable or disable TCP/IP networking and to configure the port number that is used to connect to the MySQL server. MySQL Server Instance Config Wizard: Network Configuration TCP/IP networking is enabled by default. To disable TCP/IP networking, uncheck the box next to the `Enable TCP/IP Networking' option. Port 3306 is used by default. To change the port used to access MySQL, choose a new port number from the drop-down box or type a new port number directly into the drop-down box. If the port number you choose is in use, you are prompted to confirm your choice of port number. Set the `Server SQL Mode' to either enable or disable strict mode. Enabling strict mode (default) makes MySQL behave more like other database management systems. _If you run applications that rely on MySQL's old `forgiving' behavior, make sure to either adapt those applications or to disable strict mode._ For more information about strict mode, see *Note server-sql-mode::.  File: manual.info, Node: mysql-config-wizard-character-set, Next: mysql-config-wizard-service, Prev: mysql-config-wizard-networking, Up: mysql-config-wizard 2.3.5.9 MySQL Server Instance Config Wizard: The Character Set Dialog ..................................................................... The MySQL server supports multiple character sets and it is possible to set a default server character set that is applied to all tables, columns, and databases unless overridden. Use the `Character Set' dialog to change the default character set of the MySQL server. MySQL Server Instance Config Wizard: Character Set * `Standard Character Set': Choose this option if you want to use `latin1' as the default server character set. `latin1' is used for English and many Western European languages. * `Best Support For Multilingualism': Choose this option if you want to use `utf8' as the default server character set. This is a Unicode character set that can store characters from many different languages. * `Manual Selected Default Character Set / Collation': Choose this option if you want to pick the server's default character set manually. Choose the desired character set from the provided drop-down list.  File: manual.info, Node: mysql-config-wizard-service, Next: mysql-config-wizard-security, Prev: mysql-config-wizard-character-set, Up: mysql-config-wizard 2.3.5.10 MySQL Server Instance Config Wizard: The Service Options Dialog ........................................................................ On Windows platforms, the MySQL server can be installed as a Windows service. When installed this way, the MySQL server can be started automatically during system startup, and even restarted automatically by Windows in the event of a service failure. The MySQL Server Instance Config Wizard installs the MySQL server as a service by default, using the service name `MySQL'. If you do not wish to install the service, uncheck the box next to the `Install As Windows Service' option. You can change the service name by picking a new service name from the drop-down box provided or by entering a new service name into the drop-down box. *Note*: Service names can include any legal character except forward (`/') or backward (`\') slashes, and must be less than 256 characters long. *Warning*: If you are installing multiple versions of MySQL onto the same machine, you _must_ choose a different service name for each version that you install. If you do not choose a different service for each installed version then the service manager information will be inconsistent and this will cause problems when you try to uninstall a previous version. If you have already installed multiple versions using the same service name, you must manually edit the contents of the `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services' parameters within the Windows registry to update the association of the service name with the correct server version. Typically, when installing multiple versions you create a service name based on the version information. For example, you might install MySQL 5.x as `mysql5', or specific versions such as MySQL 5.1.30 as `mysql50130'. To install the MySQL server as a service but not have it started automatically at startup, uncheck the box next to the `Launch the MySQL Server Automatically' option.  File: manual.info, Node: mysql-config-wizard-security, Next: mysql-config-wizard-confirmation, Prev: mysql-config-wizard-service, Up: mysql-config-wizard 2.3.5.11 MySQL Server Instance Config Wizard: The Security Options Dialog ......................................................................... The content of the security options portion of the MySQL Server Instance Configuration Wizard will depend on whether this is a new installation, or modifying an existing installation. * *Setting the root password for a new installation* _It is strongly recommended that you set a `root' password for your MySQL server_, and the MySQL Server Instance Config Wizard requires by default that you do so. If you do not wish to set a `root' password, uncheck the box next to the `Modify Security Settings' option. *Note*: If you have previously installed MySQL, but not deleted the data directory associated with the previous installation, you may be prompted to provide the current root password. The password will be the one configured with your old data directory. If you do not want to use this data, or do not know the root password, you should cancel the installation, delete the previous installation data, and then restart the installation process. For more information on deleting MySQL data on Microsoft Windows, see *Note windows-installer-uninstalling::. MySQL Server Instance Config Wizard: Security * To set the `root' password, enter the desired password into both the `New root password' and `Confirm' boxes. *Setting the root password for an existing installation* If you are modifying the configuration of an existing configuration, or you are installing an upgrade and the MySQL Server Instance Configuration Wizard has detected an existing MySQL system, then you must enter the existing password for `root' before changing the configuration information. MySQL Server Instance Config Wizard: Security (Existing Installation) If you want to change the current `root' password, enter the desired new password into both the `New root password' and `Confirm' boxes. To permit `root' logins from across the network, check the box next to the `Enable root access from remote machines' option. This decreases the security of your `root' account. To create an anonymous user account, check the box next to the `Create An Anonymous Account' option. Creating an anonymous account can decrease server security and cause login and permission difficulties. For this reason, it is not recommended.  File: manual.info, Node: mysql-config-wizard-confirmation, Next: mysql-config-wizard-cmdline, Prev: mysql-config-wizard-security, Up: mysql-config-wizard 2.3.5.12 MySQL Server Instance Config Wizard: The Confirmation Dialog ..................................................................... The final dialog in the MySQL Server Instance Config Wizard is the `Confirmation Dialog'. To start the configuration process, click the `Execute' button. To return to a previous dialog, click the `Back' button. To exit the MySQL Server Instance Config Wizard without configuring the server, click the `Cancel' button. MySQL Server Instance Config Wizard: Confirmation After you click the `Execute' button, the MySQL Server Instance Config Wizard performs a series of tasks and displays the progress onscreen as the tasks are performed. The MySQL Server Instance Config Wizard first determines configuration file options based on your choices using a template prepared by MySQL developers and engineers. This template is named `my-template.ini' and is located in your server installation directory. The MySQL Config Wizard then writes these options to the corresponding configuration file. If you chose to create a service for the MySQL server, the MySQL Server Instance Config Wizard creates and starts the service. If you are reconfiguring an existing service, the MySQL Server Instance Config Wizard restarts the service to apply your configuration changes. If you chose to set a `root' password, the MySQL Config Wizard connects to the server, sets your new `root' password, and applies any other security settings you may have selected. After the MySQL Server Instance Config Wizard has completed its tasks, it displays a summary. Click the `Finish' button to exit the MySQL Server Config Wizard.  File: manual.info, Node: mysql-config-wizard-cmdline, Prev: mysql-config-wizard-confirmation, Up: mysql-config-wizard 2.3.5.13 MySQL Server Instance Config Wizard: Creating an Instance from the Command Line ........................................................................................ In addition to using the GUI interface to the MySQL Server Instance Config Wizard, you can also create instances automatically from the command line. To use the MySQL Server Instance Config Wizard on the command line, you need to use the `MySQLInstanceConfig.exe' command that is installed with MySQL in the `bin' directory within the installation directory. `MySQLInstanceConfig.exe' takes a number of command-line arguments the set the properties that would normally be selected through the GUI interface, and then creates a new configuration file (`my.ini') by combining these selections with a template configuration file to produce the working configuration file. The main command line options are provided in the table below. Some of the options are required, while some options are optional. *MySQL Server Instance Config Wizard Command Line Options* Option Description Required Parameters `-nPRODUCTNAME'The name of the instance when installed `-pPATH' Path of the base directory for installation. This is equivalent to the directory when using the `basedir' configuration parameter `-vVERSION' The version tag to use for this installation Action to Perform `-i' Install an instance `-r' Remove an instance `-s' Stop an existing instance `-q' Perform the operation quietly `-lFILENAME' Sae the installation progress in a logfile Config File to Use `-tFILENAME' Path to the template config file that will be used to generate the installed configuration file `-cFILENAME' Path to a config file to be generated The `-t' and `-c' options work together to set the configuration parameters for a new instance. The `-t' option specifies the template configuration file to use as the basic configuration, which are then merged with the configuration parameters generated by the MySQL Server Instance Config Wizard into the configuration file specified by the `-c' option. A sample template file, `my-template.ini' is provided in the toplevel MySQL installation directory. The file contains elements are replaced automatically by the MySQL Server Instance Config Wizard during configuration. If you specify a configuration file that already exists, the existing configuration file will be saved in the file with the original, with the date and time added. For example, the `mysql.ini' will be copied to `mysql 2009-10-27 1646.ini.bak'. The parameters that you can specify on the command line are listed in the table below. *MySQL Server Instance Config Wizard Parameters* Parameter Description `ServiceName=$'Specify the name of the service to be created `AddBinToPath={yesSpecifies whether to add the binary | no}' directory of MySQL to the standard `PATH' environment variable `ServerType={DEVELOPMENTSpecify the server type. For more | SERVER | information, see *Note DEDICATED}' mysql-config-wizard-server-type:: `DatabaseType={MIXEDSpecify the default database type. For | INNODB | more information, see *Note MYISAM}' mysql-config-wizard-database-usage:: `ConnectionUsage={DSSSpecify the type of connection support, | OLTP}' this automates the setting for the number of concurrent connections (see the `ConnectionCount' parameter). For more information, see *Note mysql-config-wizard-connections:: `ConnectionCount=#'Specify the number of concurrent connections to support. For more information, see *Note mysql-config-wizard-server-type:: `SkipNetworking={yesSpecify whether network support should be | no}' supported. Specifying `yes' disables network access altogether `Port=#' Specify the network port number to use for network connections. For more information, see *Note mysql-config-wizard-networking:: `StrictMode={yesSpecify whether to use the `strict' SQL | no}' mode. For more information, see *Note mysql-config-wizard-networking:: `Charset=$' Specify the default character set. For more information, see *Note mysql-config-wizard-character-set:: `RootPassword=$'Specify the root password `RootCurrentPassword=$'Specify the current root password then stopping or reconfiguring an existing service *Note*: When specifying options on the command line, you can enclose the entire command-line option and the value you are specifying using double quotation marks. This enables you to use spaces in the options. For example, `"-cC:\mysql.ini"'. The following command installs a MySQL Server 5.1 instance from the directory `C:\Program Files\MySQL\MySQL Server 5.1' using the service name `MySQL51' and setting the root password to 1234. shell> MySQLInstanceConfig.exe -i -q "-lC:\mysql_install_log.txt" » "-nMySQL Server 5.1" "-pC:\Program Files\MySQL\MySQL Server 5.1" -v5.1.73 » "-tmy-template.ini" "-cC:\mytest.ini" ServerType=DEVELOPMENT DatabaseType=MIXED » ConnectionUsage=DSS Port=3311 ServiceName=MySQL51 RootPassword=1234 In the above example, a log file will be generated in `mysql_install_log.txt' containing the information about the instance creation process. The log file generated by the above example is shown below: Welcome to the MySQL Server Instance Configuration Wizard 1.0.16.0 Date: 2009-10-27 17:07:21 Installing service ... Product Name: MySQL Server 5.1 Version: 5.1.73 Installation Path: C:\Program Files\MySQL\MySQL Server 5.1\ Creating configuration file C:\mytest.ini using template my-template.ini. Options: DEVELOPMENT MIXED DSS STRICTMODE Variables: port: 3311 default-character-set: latin1 basedir: "C:/Program Files/MySQL/MySQL Server 5.1/" datadir: "C:/Program Files/MySQL/MySQL Server 5.1/Data/" Creating Windows service entry. Service name: "MySQL51" Parameters: "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqld" --defaults-file="C:\mytest.ini" MySQL51. Windows service MySQL51 installed. When using the command line, the return values in the following table indicate an error performing the specified option. *Return Value from MySQL Server Instance Config Wizard* Value Description 2 Configuration template file cannot be found 3 The Windows service entry cannot be created 4 Could not connect to the Service Control Manager 5 The MySQL service cannot be started 6 The MySQL service cannot be stopped 7 The security settings cannot be applied 8 The configuration file cannot be written 9 The Windows service entry cannot be removed You can perform an installation of MySQL automatically using the MSI package. For more information, see *Note windows-installer-msi-quiet::.  File: manual.info, Node: windows-install-archive, Next: windows-troubleshooting, Prev: mysql-config-wizard, Up: windows-installation 2.3.6 Installing MySQL on Microsoft Windows Using a `noinstall' Zip Archive --------------------------------------------------------------------------- * Menu: * windows-extract-archive:: Extracting the Install Archive * windows-create-option-file:: Creating an Option File * windows-select-server:: Selecting a MySQL Server Type * windows-server-first-start:: Starting MySQL Server on Microsoft Windows for the First Time * windows-start-command-line:: Starting MySQL Server from the Windows Command Line * mysql-installation-windows-path:: Customizing the PATH for MySQL Tools * windows-start-service:: Starting MySQL Server as a Microsoft Windows Service * windows-testing:: Testing The MySQL Server Installation on Microsoft Windows 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 is as follows: 1. Extract the archive to the desired install directory 2. Create an option file 3. Choose a MySQL server type 4. Start the MySQL server 5. Secure the default user accounts This process is described in the sections that follow.  File: manual.info, Node: windows-extract-archive, Next: windows-create-option-file, Prev: windows-install-archive, Up: windows-install-archive 2.3.6.1 Extracting the Install Archive ...................................... To install MySQL manually, do the following: 1. If you are upgrading from a previous version please refer to *Note 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'. The MySQL Installation Wizard installs MySQL under `C:\Program Files\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 *Note windows-create-option-file::. 4. Extract the install archive to the chosen installation location using your preferred Zip archive 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.  File: manual.info, Node: windows-create-option-file, Next: windows-select-server, Prev: windows-extract-archive, Up: windows-install-archive 2.3.6.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.1' and `C:\Program Files\MySQL\MySQL Server 5.1\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 *Note 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. You can also make use of the example option files included with your MySQL distribution; see *Note 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 Note that 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 *Note option-files::. In MySQL 5.1.23 and earlier, the MySQL installer places the data directory directly under the directory where you install MySQL. On MySQL 5.1.24 and later, the data directory is located within the `AppData' directory for the user running MySQL. 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.1\data') to `E:\mydata'. 2. Use a `--datadir' option to specify the new data directory location each time you start the server.  File: manual.info, Node: windows-select-server, Next: windows-server-first-start, Prev: windows-create-option-file, Up: windows-install-archive 2.3.6.3 Selecting a MySQL Server Type ..................................... The following table shows the available servers for Windows in MySQL 5.1.20 and earlier. *`mysqld' binary types for Microsoft Windows up to MySQL 5.1.20* Binary Description *Note Optimized binary with named-pipe support `mysqld-nt': mysqld. *Note Optimized binary without named-pipe support `mysqld': mysqld. *Note Like *Note `mysqld-nt': mysqld, but compiled with full `mysqld-debug':debugging and automatic memory allocation checking mysqld. The following table shows the available servers for Windows in MySQL 5.1.21 and later. *`mysqld' binary types for Microsoft Windows MySQL 5.1.21 and later* Binary Description *Note Optimized binary with named-pipe support `mysqld': mysqld. *Note Like *Note `mysqld': 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 *Note `SHOW ENGINES': show-engines. statement displays which engines a given server supports. All Windows MySQL 5.1 servers have support for symbolic linking of database directories. MySQL supports TCP/IP on all Windows platforms. MySQL servers on Windows support named pipes as indicated in the following list. However, the default is to use TCP/IP regardless of platform. (Named pipes are slower than TCP/IP in many Windows configurations.) Use of named pipes is subject to these conditions: * Named pipes are enabled only 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. * For MySQL 5.1.20 and earlier, named-pipe connections are permitted only by the *Note `mysqld-nt': mysqld. and *Note `mysqld-debug': mysqld. servers. For MySQL 5.1.21 and later, the *Note `mysqld': mysqld. and *Note `mysqld-debug': mysqld. servers both contain support for named-pipe connections. *Note*: Most of the examples in this manual use *Note `mysqld': mysqld. as the server name. If you choose to use a different server, such as *Note `mysqld-nt': mysqld. or *Note `mysqld-debug': mysqld, make the appropriate substitutions in the commands that are shown in the examples.  File: manual.info, Node: windows-server-first-start, Next: windows-start-command-line, Prev: windows-select-server, Up: windows-install-archive 2.3.6.4 Starting MySQL Server on Microsoft Windows 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. The examples in these sections assume that MySQL is installed under the default location of `C:\Program Files\MySQL\MySQL Server 5.1'. 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 *Note 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. To start the server, enter this command: C:\> "C:\Program Files\MySQL\MySQL Server 5.1\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.1.73' 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.1\data' by default). The error log is the file with the `.err' extension. *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 *Note default-privileges::.  File: manual.info, Node: windows-start-command-line, Next: mysql-installation-windows-path, Prev: windows-server-first-start, Up: windows-install-archive 2.3.6.5 Starting MySQL Server 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. To start the *Note `mysqld': 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.1\bin\mysqld" The path to *Note `mysqld': 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.1\bin\mysqladmin" -u root shutdown *Note*: If the MySQL `root' user account has a password, you need to invoke *Note `mysqladmin': mysqladmin. with the `-p' option and supply the password when prompted. This command invokes the MySQL administrative utility *Note `mysqladmin': 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 that users in the MySQL grant system are wholly independent from any login users under Windows. If *Note `mysqld': mysqld. doesn't 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 `C:\Program Files\MySQL\MySQL Server 5.1\data' directory. It is the file with a suffix of `.err'. You can also try to start the server as *Note `mysqld --console': mysqld.; in this case, you may get some useful information on the screen that may help solve the problem. The last option is to start *Note `mysqld': mysqld. with the `--standalone' and `--debug' options. In this case, *Note `mysqld': mysqld. writes a log file `C:\mysqld.trace' that should contain the reason why *Note `mysqld': mysqld. doesn't start. See *Note dbug-package::. Use *Note `mysqld --verbose --help': mysqld. to display all the options that *Note `mysqld': mysqld. supports.  File: manual.info, Node: mysql-installation-windows-path, Next: windows-start-service, Prev: windows-start-command-line, Up: windows-install-archive 2.3.6.6 Customizing the PATH for MySQL Tools ............................................ 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.1\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. 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 *Note `mysql': mysql. client, and all MySQL command-line utilities such as *Note `mysqladmin': mysqladmin. and *Note `mysqldump': 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.  File: manual.info, Node: windows-start-service, Next: windows-testing, Prev: mysql-installation-windows-path, Up: windows-install-archive 2.3.6.7 Starting MySQL Server as a Microsoft 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, and can be managed using the service manager framework. 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. The `Services' utility (the Windows `Service Control Manager') can be found in the Windows Control Panel (under `Administrative Tools' on Windows 2000, XP, 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.1\bin\mysqladmin" -u root shutdown *Note*: If the MySQL `root' user account has a password, you need to invoke *Note `mysqladmin': mysqladmin. with the `-p' option and supply the password when prompted. This command invokes the MySQL administrative utility *Note `mysqladmin': 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 that 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.1\bin\mysqld" --install *Note*: The service-installation command does not start the server. 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. This account is available only for Windows XP or newer. 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 a 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 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.1\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. * Starting the service * Once a MySQL server 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, *Note `mysqld': mysqld. has no access to a console window, so no messages can be seen there. If *Note `mysqld': 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.1\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 *Note `mysqladmin shutdown': mysqladmin. 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.1\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.1\bin\mysqld" --remove If *Note `mysqld': mysqld. is not running as a service, you can start it from the command line. For instructions, see *Note windows-start-command-line::. Please see *Note windows-troubleshooting::, if you encounter difficulties during installation.  File: manual.info, Node: windows-testing, Prev: windows-start-service, Up: windows-install-archive 2.3.6.8 Testing The MySQL Server Installation on Microsoft Windows .................................................................. You can test whether the MySQL server is working by executing any of the following commands: C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqlshow" C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqlshow" -u root mysql C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqladmin" version status proc C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysql" test *Note*: By default, *Note `mysqlshow': mysqlshow. will try to connect using the `ODBC' user. This user is not created by default. You should specify a valid user, or `root' with the right password to check the operation of the server. If *Note `mysqld': mysqld. is slow to respond to TCP/IP connections from client programs, there is probably a problem with your DNS. In this case, start *Note `mysqld': mysqld. with the `--skip-name-resolve' option and use only `localhost' and IP addresses in the `Host' column of the MySQL grant tables. 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. Note that if you have set a password for the `root' account, deleted the anonymous account, or created a new user account, then you must use the appropriate `-u' and `-p' options with the commands shown above to connect with the MySQL Server. See *Note connecting::. For more information about *Note `mysqlshow': mysqlshow, see *Note mysqlshow::.  File: manual.info, Node: windows-troubleshooting, Next: windows-upgrading, Prev: windows-install-archive, Up: windows-installation 2.3.7 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. The purpose of this section is to help you diagnose and correct some of these errors. Your first resource when troubleshooting server issues is the error log (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_data_directory) specified in your `my.ini' file. The default data directory location is `C:\Program Files\MySQL\MySQL Server 5.1\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 *Note error-log::. Another source of information regarding possible errors is the console messages displayed when the MySQL service is starting. Use the `NET START MySQL' command from the command line after installing *Note `mysqld': mysqld. as a service to see any error messages regarding the starting of the MySQL server as a service. See *Note windows-start-service::. The following examples show other common error messages you may 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, you may see these messages: System error 1067 has occurred. Fatal error: Can't open privilege tables: Table 'mysql.host' 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.1' and `C:\Program Files\MySQL\MySQL Server 5.1\data', respectively). This situation may 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, there may be old and new configuration files that 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.1', you need to ensure that the MySQL server is aware of this through the use of a configuration (`my.ini') file. The `my.ini' file needs to be located in your Windows directory, typically `C:\WINDOWS'. You can determine its exact location from the value of the `WINDIR' environment variable by issuing the following command from the command prompt: C:\> echo %WINDIR% 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 `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 Note that 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.1 # 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 *Note 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 *Note 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 Config Wizard, you may see this error: Error: Cannot create Windows service for MySql. Error: 0 This occurs when the Config 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.  File: manual.info, Node: windows-upgrading, Next: windows-postinstallation, Prev: windows-troubleshooting, Up: windows-installation 2.3.8 Upgrading MySQL Server on Microsoft Windows ------------------------------------------------- This section lists some of the steps you should take when upgrading MySQL on Windows. 1. Review *Note upgrading::, for additional information on upgrading MySQL that is not specific to Windows. 2. You should always back up your current MySQL installation before performing an upgrade. See *Note backup-methods::. 3. Download the latest Windows distribution of MySQL from `http://dev.mysql.com/downloads/'. 4. Before upgrading MySQL, you must 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 *Note `mysqladmin': mysqladmin. to stop it. For example, before upgrading from MySQL 5.0 to 5.1, use *Note `mysqladmin': mysqladmin. from MySQL 5.0 as follows: C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqladmin" -u root shutdown *Note*: If the MySQL `root' user account has a password, you need to invoke *Note `mysqladmin': mysqladmin. with the `-p' option and supply the password when prompted. 5. Before upgrading to MySQL 5.1 from a version previous to 4.1.5, or from a version of MySQL installed from a Zip archive to a version of MySQL installed with the MySQL Installation Wizard, you must first manually remove the previous installation and MySQL service (if the server is installed as a service). To remove the MySQL service, use the following command: C:\> C:\mysql\bin\mysqld --remove *Important*: If you do not remove the existing service, the MySQL Installation Wizard may fail to properly install the new MySQL service. 6. When upgrading from MySQL 5.1.23 to MySQL 5.1.24, the change in the default location of the data directory from a directory within the MySQL installation to the `AppData' folder means that you must manually copy the data files from your old installation to the new location. 7. If you are using the MySQL Installation Wizard, start the wizard as described in *Note windows-install-wizard::. 8. If you are installing MySQL from a Zip archive, extract the 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. 9. If you were running MySQL as a Windows service and you had to remove the service earlier in this procedure, reinstall the service. (See *Note windows-start-service::.) 10. Restart the server. For example, use `NET START MySQL' if you run MySQL as a service, or invoke *Note `mysqld': mysqld. directly otherwise. 11. As Administrator, run *Note `mysql_upgrade': 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 *Note mysql-upgrade::. 12. If you encounter errors, see *Note windows-troubleshooting::.  File: manual.info, Node: windows-postinstallation, Prev: windows-upgrading, Up: windows-installation 2.3.9 MySQL Server on Microsoft Windows Postinstallation Procedures ------------------------------------------------------------------- On Windows, you need not create the data directory and the grant tables. MySQL Windows distributions include the grant tables with a set of preinitialized accounts in the `mysql' database under the data directory. Regarding passwords, if you installed MySQL using the Windows Installation Wizard, you may have already assigned passwords to the accounts. (See *Note windows-install-wizard::.) Otherwise, use the password-assignment procedure given in *Note default-privileges::. Before setting up 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 *Note windows-server-first-start::), and then issue the following commands to verify that you can retrieve information from the server. You may need to specify directory different from `C:\mysql\bin' on the command line. If you used the Windows Installation Wizard, the default directory is `C:\Program Files\MySQL\MySQL Server 5.1', and the *Note `mysql': mysql. and *Note `mysqlshow': mysqlshow. client programs are in `C:\Program Files\MySQL\MySQL Server 5.1\bin'. See *Note windows-install-wizard::, for more information. Use *Note `mysqlshow': mysqlshow. to see what databases exist: C:\> C:\mysql\bin\mysqlshow +--------------------+ | Databases | +--------------------+ | information_schema | | mysql | | test | +--------------------+ The list of installed databases may vary, but will always include the minimum of `mysql' and `information_schema'. In most cases, the `test' database will also be installed automatically. The preceding command (and commands for other MySQL programs such as *Note `mysql': 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 using the MSI packages and used the MySQL Server Instance Config Wizard, then 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 will also need to use the `-u root' and `-p' options if you have already secured the initial MySQL accounts.) With `-p', you will be prompted for the `root' password. For example: C:\> C:\mysql\bin\mysqlshow -u root -p Enter password: (ENTER ROOT PASSWORD HERE) +--------------------+ | Databases | +--------------------+ | information_schema | | mysql | | test | +--------------------+ If you specify a database name, *Note `mysqlshow': mysqlshow. displays a list of the tables within the database: C:\> C:\mysql\bin\mysqlshow mysql Database: mysql +---------------------------+ | Tables | +---------------------------+ | columns_priv | | db | | event | | func | | help_category | | help_keyword | | help_relation | | help_topic | | host | | plugin | | proc | | procs_priv | | servers | | tables_priv | | time_zone | | time_zone_leap_second | | time_zone_name | | time_zone_transition | | time_zone_transition_type | | user | +---------------------------+ Use the *Note `mysql': mysql. program to select information from a table in the `mysql' database: C:\> C:\mysql\bin\mysql -e "SELECT Host,Db,User FROM mysql.db" +------+--------+------+ | host | db | user | +------+--------+------+ | % | test | | | % | test_% | | +------+--------+------+ For more information about *Note `mysqlshow': mysqlshow. and *Note `mysql': mysql, see *Note mysqlshow::, and *Note mysql::. If you are running a version of Windows that supports services, you can set up the MySQL server to run automatically when Windows starts. See *Note windows-start-service::.  File: manual.info, Node: macosx-installation, Next: linux-installation, Prev: windows-installation, Up: installing 2.4 Installing MySQL on Mac OS X ================================ * Menu: * macosx-installation-notes:: General Notes on Installing MySQL on Mac OS X * macosx-installation-pkg:: Installing MySQL on Mac OS X Using Native Packages * macosx-installation-startupitem:: Installing the MySQL Startup Item * macosx-installation-prefpane:: Installing and Using the MySQL Preference Pane * macosx-installation-server:: Using the Bundled MySQL on Mac OS X Server MySQL for Mac OS X is available in a number of different forms: * Native Package Installer format, which uses the native Mac OS X installer to walk you through the installation of MySQL. For more information, see *Note macosx-installation-pkg::. You can use the package installer with Mac OS X 10.3 and later, and the package is available for both PowerPC and Intel architectures, and 32-bit and 64-bit architectures. There is no Universal Binary available using the package installation method. The user you use to perform the installation must have administrator privileges. * Tar package format, 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, *Note binary-installation::.You can use the package installer with Mac OS X 10.3 and later, and available for both PowerPC and Intel architectures, and both 32-bit and 64-bit architectures. A Universal Binary, incorporating both Power PC and Intel architectures and 32-bit and 64-bit binaries is available. In addition to the core installation, the Package Installer also includes *Note macosx-installation-startupitem:: and *Note macosx-installation-prefpane::, both of which simplify the management of your installation. * Mac OS X server includes a version of MySQL as standard. If you want to use a more recent version than that supplied with the Mac OS X server release, you can make use of the package or tar formats. For more information on using the MySQL bundled with Mac OS X, see *Note macosx-installation-server::. For additional information on using MySQL on Mac OS X, see *Note macosx-installation-notes::.  File: manual.info, Node: macosx-installation-notes, Next: macosx-installation-pkg, Prev: macosx-installation, Up: macosx-installation 2.4.1 General Notes on Installing MySQL on Mac OS X --------------------------------------------------- You should keep the following issues and notes in mind: * The default location for the MySQL Unix socket is different on Mac OS X and Mac OS X Server depending on the installation type you chose. The following table shows the default locations by installation type. *MySQL Unix Socket Locations on Mac OS X by Installation Type* Installation Type Socket Location Package Installer `/tmp/mysql.sock' from MySQL Tarball from MySQL `/tmp/mysql.sock' MySQL Bundled with `/var/mysql/mysql.sock' Mac OS X Server To prevent issues, you should either change the configuration of the socket used within your application (for example, changing `php.ini'), or you should configure the socket location using a MySQL configuration file and the `socket' option. For more information, see *Note server-options::. * You may need (or want) to create a specific `mysql' user to own the MySQL directory and data. On Mac OS X 10.4 and lower you can do this by using the `Netinfo Manager' application, located within the `Utilities' folder within the `Applications' folder. On Mac OS X 10.5 and later you can do this through the `Directory Utility'. From Mac OS X 10.5 and later (including Mac OS X Server 10.5) the `mysql' 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. * Due to a bug in the Mac OS X package installer, you may see this error message in the destination disk selection dialog: You cannot install this software on this disk. (null) If this error occurs, click the `Go Back' button once to return to the previous screen. Then click `Continue' to advance to the destination disk selection again, and you should be able to choose the destination disk correctly. We have reported this bug to Apple and it is investigating this problem. * If you get an `insecure startup item disabled' error when MySQL launches, use the following procedure. Adjust the pathnames appropriately for your system. 1. Modify the `mysql.script' using this command (enter it on a single line): shell> sudo /Applications/TextEdit.app/Contents/MacOS/TextEdit /usr/local/mysql/support-files/mysql.server 2. Locate the option file that defines the `basedir' value and modify it to contain these lines: basedir=/usr/local/mysql datadir=/usr/local/mysql/data In the `/Library/StartupItems/MySQLCOM/' directory, make the following group ID changes from `staff' to `wheel': shell> sudo chgrp wheel MySQLCOM StartupParameters.plist 3. Start the server from System Preferences or Terminal.app. * 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. * You might want to add aliases to your shell's resource file to make it easier to access commonly used programs such as *Note `mysql': mysql. and *Note `mysqladmin': 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 *Note 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'.  File: manual.info, Node: macosx-installation-pkg, Next: macosx-installation-startupitem, Prev: macosx-installation-notes, Up: macosx-installation 2.4.2 Installing MySQL on Mac OS X Using Native Packages -------------------------------------------------------- You can install MySQL on Mac OS X 10.3.x (`Panther') or newer using a Mac OS X binary package in DMG format instead of the binary tarball distribution. Please note that older versions of Mac OS X (for example, 10.1.x or 10.2.x) are _not_ supported by this package. 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 Mac OS X Server) or *Note `mysqladmin shutdown': mysqladmin. on the command line. When installing from the package version, you should also install the MySQL Preference Pane, which will enable you to control the startup and execution of your MySQL server from System Preferences. For more information, see *Note macosx-installation-prefpane::. 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.1.39-osx10.5-x86_64.pkg' installs MySQL into `/usr/local/mysql-5.1.39-osx10.5-x86_64 '. The following table shows the layout of the installation directory. *MySQL Installation Layout on Mac OS X* Directory Contents of Directory `bin' Client programs and the *Note `mysqld': mysqld. server `data' Log files, databases `docs' Manual in Info format `include' Include (header) files `lib' Libraries `man' Unix manual pages `mysql-test' MySQL test suite `scripts' *Note `mysql_install_db': mysql-install-db. `share' Miscellaneous support files, including error messages, sample configuration files, SQL for database installation `sql-bench' Benchmarks `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. 1. Download and open the MySQL package installer, which is provided on a disk image (`.dmg') that includes the main MySQL installation package, the `MySQLStartupItem.pkg' installation package, and the `MySQL.prefPane'. Double-click the disk image to open it. 2. Double-click the MySQL installer package. It will be named according to the version of MySQL you have downloaded. For example, if you have downloaded MySQL 5.1.39, double-click `mysql-5.1.39-osx10.5-x86.pkg'. 3. You will be presented with the opening installer dialog. Click `Continue' to begin installation. MySQL Package Installer: Step 1 4. A copy of the installation instructions and other important information relevant to this installation are displayed. Click `Continue' . 5. If you have downloaded the community version of MySQL, you will be shown a copy of the relevant GNU General Public License. Click `Continue' . 6. Select the drive you want to use to install the MySQL Startup Item. The drive must have a valid, bootable, Mac OS X operating system installed. Click `Continue'. MySQL Package Installer: Step 4 7. You will be asked to confirm the details of the installation, including the space required for the installation. To change the drive on which the startup item is installed, click either `Go Back' or `Change Install Location...'. To install the startup item, click `Install'. 8. Once the installation has been completed successfully, you will be shown an `Install Succeeded' message. For convenience, you may also want to install the startup item and preference pane. See *Note macosx-installation-startupitem::, and *Note macosx-installation-prefpane::.  File: manual.info, Node: macosx-installation-startupitem, Next: macosx-installation-prefpane, Prev: macosx-installation-pkg, Up: macosx-installation 2.4.3 Installing the MySQL Startup Item --------------------------------------- The MySQL Installation Package includes a startup item that can be used to automatically start and stop MySQL. To install the MySQL Startup Item: 1. Download and open the MySQL package installer, which is provided on a disk image (`.dmg') that includes the main MySQL installation package, the `MySQLStartupItem.pkg' installation package, and the `MySQL.prefPane'. Double-click the disk image to open it. 2. Double-click the `MySQLStartItem.pkg' file to start the installation process. 3. You will be presented with the `Install MySQL Startup Item' dialog. MySQL Startup Item Installer: Step 1 Click `Continue' to continue the installation process. 4. A copy of the installation instructions and other important information relevant to this installation are displayed. Click `Continue' . 5. Select the drive you want to use to install the MySQL Startup Item. The drive must have a valid, bootable, Mac OS X operating system installed. Click `Continue'. MySQL Startup Item Installer: Step 3 6. You will be asked to confirm the details of the installation. To change the drive on which the startup item is installed, click either `Go Back' or `Change Install Location...'. To install the startup item, click `Install'. 7. Once the installation has been completed successfully, you will be shown an `Install Succeeded' message. MySQL Startup Item Installer: Step 5 The Startup Item for MySQL is installed into `/Library/StartupItems/MySQLCOM'. The Startup Item installation adds a variable `MYSQLCOM=-YES-' to the system configuration file `/etc/hostconfig'. If you want to disable the automatic startup of MySQL, change this variable to `MYSQLCOM=-NO-'. After the installation, you can start and stop MySQL by running the following commands in a terminal window. You must have administrator privileges to perform these tasks, and you may be prompted for your password. If you have installed the Startup Item, use this command to start the server: shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM start If you have installed the Startup Item, use this command to stop the server: shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM stop  File: manual.info, Node: macosx-installation-prefpane, Next: macosx-installation-server, Prev: macosx-installation-startupitem, Up: macosx-installation 2.4.4 Installing and Using the MySQL Preference Pane ---------------------------------------------------- The MySQL Package installer disk image also includes a custom MySQL Preference Pane that enables you to start, stop, and control automated startup during boot of your MySQL installation. To install the MySQL Preference Pane: 1. Download and open the MySQL package installer package, which is provided on a disk image (`.dmg') that includes the main MySQL installation package, the `MySQLStartupItem.pkg' installation package, and the `MySQL.prefPane'. Double-click the disk image to open it. 2. Double-click the `MySQL.prefPane'. The MySQL System Preferences will open. 3. If this is the first time you have installed the preference pane, you will be asked to confirm installation and whether you want to install the preference pane for all users, or only the current user. To install the preference pane for all users you will need administrator privileges. If necessary, you will be prompted for the username and password for a user with administrator privileges. 4. If you already have the MySQL Preference Pane installed, you will be asked to confirm whether you want to overwrite the existing MySQL Preference Pane. *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 `Other' section of the preference panes list. MySQL Preference Pane 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 MySQL 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 MySQL 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.  File: manual.info, Node: macosx-installation-server, Prev: macosx-installation-prefpane, Up: macosx-installation 2.4.5 Using the Bundled MySQL on Mac OS X Server ------------------------------------------------ If you are running Mac OS X Server, a version of MySQL should already be installed. The following table shows the versions of MySQL that ship with Mac OS X Server versions. *MySQL Versions Preinstalled with Mac OS X Server* Mac OS X Server MySQL Version Version 10.2-10.2.2 3.23.51 10.2.3-10.2.6 3.23.53 10.3 4.0.14 10.3.2 4.0.16 10.4.0 4.1.10a 10.5.0 5.0.45 10.6.0 5.0.82 The following table shows the installation layout of MySQL on Mac OS X Server. *MySQL Directory Layout for Preinstalled MySQL Installations on Mac OS X Server* Directory Contents of Directory `/usr/bin' Client programs `/var/mysql' Log files, databases `/usr/libexec' The *Note `mysqld': mysqld. server `/usr/share/man' Unix manual pages `/usr/share/mysql/mysql-test'MySQL test suite `/usr/share/mysql' Miscellaneous support files, including error messages, character set files, sample configuration files, SQL for database installation `/var/mysql/mysql.sock' Location of the MySQL Unix socket * Additional Resources * * For more information on managing the bundled MySQL instance in Mac OS X Server 10.5, see Mac OS X Server: Web Technologies Administration For Version 10.5 Leopard (http://images.apple.com/server/macosx/docs/Web_Technologies_Admin_v10.5.pdf). * For more information on managing the bundled MySQL instance in Mac OS X Server 10.6, see Mac OS X Server: Web Technologies Administration Version 10.6 Snow Leopard (http://manuals.info.apple.com/en_US/WebTech_v10.6.pdf). * The MySQL server bundled with Mac OS X Server does not include the MySQL client libraries and header files required to access and use MySQL from a third-party driver, such as Perl DBI or PHP. For more information on obtaining and installing MySQL libraries, see Mac OS X Server version 10.5: MySQL libraries available for download (http://support.apple.com/kb/TA25017). Alternatively, you can ignore the bundled MySQL server and install MySQL from the package or tarball installation.  File: manual.info, Node: linux-installation, Next: solaris-installation, Prev: macosx-installation, Up: installing 2.5 Installing MySQL on Linux ============================= * Menu: * linux-installation-rpm:: Installing MySQL on Linux Using RPM Packages * linux-installation-native:: Installing MySQL on Linux Using Native Package Managers Linux supports a number of different solutions for installing MySQL. The recommended method is to use one of the distributions from Oracle. If you choose this method, there are several options available: * Installing from a generic binary package in `.tar.gz' format. See *Note binary-installation:: for more information. * Extracting and compiling MySQL from a source distribution. For detailed instructions, see *Note source-installation::. * Installing using a precompiled RPM package. For more information, see *Note linux-installation-rpm::. As an alternative, you can use the native package manager within your Linux distribution to automatically download and install MySQL for you. Native package installations can take of the download and dependencies required to run MySQL, but the MySQL version will often be some versions behind the currently available release. You will also normally be unable to install development releases, as these are not usually made available in the native repository. For more information on using the native package installers, see *Note 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, *Note `mysql.server': 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 *Note automatic-start::.  File: manual.info, Node: linux-installation-rpm, Next: linux-installation-native, Prev: linux-installation, Up: linux-installation 2.5.1 Installing MySQL on Linux Using RPM Packages -------------------------------------------------- The recommended way to install MySQL on RPM-based Linux distributions is by using the RPM packages. The RPMs that we provide to the community should work on all versions of Linux that support RPM packages and use `glibc' 2.3. To obtain RPM packages, see *Note getting-mysql::. For non-RPM Linux distributions, you can install MySQL using a `.tar.gz' package. See *Note binary-installation::. Installations created from our Linux RPM distributions result in files under the system directories shown in the following table. *MySQL Installation Layout for Linux RPM Packages* Directory Contents of Directory `/usr/bin' Client programs and scripts `/usr/sbin' The *Note `mysqld': mysqld. server `/var/lib/mysql' Log files, databases `/usr/share/info' Manual in Info format `/usr/share/man' Unix manual pages `/usr/include/mysql' Include (header) files `/usr/lib/mysql' Libraries `/usr/share/mysql' Miscellaneous support files, including error messages, character set files, sample configuration files, SQL for database installation `/usr/share/sql-bench' Benchmarks *Note*: RPM distributions of MySQL are also provided by other vendors. Be aware that they may differ from those built by us 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. Because of these differences, RPM packages built by us check whether such RPMs built by other vendors are installed. If so, the RPM does not install and produces a message explaining this. In most cases, you need to install only the `MySQL-server' and `MySQL-client' packages to get a functional MySQL installation. The other packages are not required for a standard installation. RPMs for MySQL Cluster Beginning with MySQL 5.1.24, standard MySQL server RPMs built by MySQL no longer provide support for the *Note `NDBCLUSTER': mysql-cluster. storage engine. MySQL Cluster users should check the MySQL Cluster Downloads page at http://dev.mysql.com/downloads/cluster/ for RPMs that should work with most Linux distributions for both of these release series. *Important*: When upgrading a MySQL Cluster RPM installation, you must upgrade _all_ installed RPMs, including the `Server' and `Client' RPMs. For more information about installing MySQL Cluster from RPMs, see *Note mysql-cluster-install-linux-rpm::. For upgrades, if your installation was originally produced by installing multiple RPM packages, it is best to 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. The RPM packages shown in the following list are available. The names shown here use a suffix of `.glibc23.i386.rpm', but particular packages can have different suffixes, described later. * `MySQL-server-VERSION.glibc23.i386.rpm' The MySQL server. You need this unless you only want to connect to a MySQL server running on another machine. * `MySQL-client-VERSION.glibc23.i386.rpm' The standard MySQL client programs. You probably always want to install this package. * `MySQL-devel-VERSION.glibc23.i386.rpm' The libraries and include files that are needed if to compile other MySQL clients, such as the Perl modules. Install this RPM if you intend to compile C API applications. * `MySQL-debuginfo-VERSION.glibc23.i386.rpm' This package contains debugging information. It is specific to Red Hat Enterprise Linux. `debuginfo' RPMs are never needed to use MySQL software; this is true both for the server and for client programs. However, they contain additional information that might be needed by a debugger to analyze a crash. * `MySQL-shared-VERSION.glibc23.i386.rpm' This package contains the shared libraries (`libmysqlclient.so*') that certain languages and applications need to dynamically load and use MySQL. It contains single-threaded and thread-safe libraries. Install this RPM if you intend to compile or run C API applications that depend on the shared client library. If you install this package, do not install the `MySQL-shared-compat' package. * `MySQL-shared-compat-VERSION.glibc23.i386.rpm' This package includes the shared libraries for older releases, up to the current release. It contains single-threaded and thread-safe libraries. Install this package instead of `MySQL-shared' if you have applications installed that are dynamically linked against older versions of MySQL but you want to upgrade to the current version without breaking the library dependencies. * `MySQL-shared-compat-advanced-gpl-VERSION.glibc23.i386.rpm', `MySQL-shared-compat-advanced-VERSION.glibc23.i386.rpm' These are like the `MySQL-shared-compat' package, but are for the `MySQL Enterprise Server - Advanced Edition' products. Install these packages rather than the normal `MySQL-shared-compat' package if you want to included shared client libraries for older MySQL versions. * `MySQL-embedded-VERSION.glibc23.i386.rpm' The embedded MySQL server library. * `MySQL-ndb-management-VERSION.glibc23.i386.rpm', `MySQL-ndb-storage-VERSION.glibc23.i386.rpm', `MySQL-ndb-tools-VERSION.glibc23.i386.rpm', `MySQL-ndb-extra-VERSION.glibc23.i386.rpm' Packages that contain additional files for MySQL Cluster installations. *Note*: The `MySQL-ndb-tools' RPM requires a working installation of perl. Prior to MySQL 5.1.18, the `DBI' and `HTML::Template' packages were also required. See *Note perl-support::, and *Note mysql-cluster-programs-ndb-size-pl::, for more information. * `MySQL-test-VERSION.glibc23.i386.rpm' This package includes the MySQL test suite. * `MySQL-VERSION.src.rpm' This contains the source code for all of the previous packages. It can also be used to rebuild the RPMs on other architectures (for example, Alpha or SPARC). The suffix of RPM package names (following the VERSION value) has the following syntax: .PLATFORM.CPU.rpm The PLATFORM and CPU values indicate the type of system for which the package is built. PLATFORM indicates the platform and CPU indicates the processor type or family. All packages are dynamically linked against `glibc' 2.3. The PLATFORM value indicates whether the package is platform independent or intended for a specific platform, as shown in the following table. *MySQL Linux Installation Packages* PLATFORM Value Intended Use `glibc23' Platform independent, should run on any Linux distribution that supports `glibc' 2.3 `rhel4', `rhel5' Red Hat Enterprise Linux 4 or 5 `sles10', `sles11' SuSE Linux Enterprise Server 10 or 11 In MySQL 5.1, only `glibc23' packages are available currently. The CPU value indicates the processor type or family for which the package is built. *MySQL Installation Packages for Linux CPU Identifiers* CPU Value Intended Processor Type or Family `i386', `i586', Pentium processor or better, 32 bit `i686' `x86_64' 64-bit x86 processor `ia64' Itanium (IA-64) processor To see all files in an RPM package (for example, a `MySQL-server' RPM), run a command like this: shell> rpm -qpl MySQL-server-VERSION.glibc23.i386.rpm To perform a standard minimal installation, install the server and client RPMs: shell> rpm -i MySQL-server-VERSION.glibc23.i386.rpm shell> rpm -i MySQL-client-VERSION.glibc23.i386.rpm To install only the client programs, install just the client RPM: shell> rpm -i MySQL-client-VERSION.glibc23.i386.rpm RPM provides a feature to verify the integrity and authenticity of packages before installing them. To learn more about this feature, see *Note verifying-package-integrity::. The server RPM places data under the `/var/lib/mysql' directory. The RPM also creates a login account for a user named `mysql' (if one does not exist) to use for running the MySQL server, and creates the appropriate entries in `/etc/init.d/' to start the server automatically at boot time. (This means that if you have performed a previous installation and have made changes to its startup script, you may want to make a copy of the script so that you do not lose it when you install a newer RPM.) See *Note automatic-start::, for more information on how MySQL can be started automatically on system startup. In MySQL 5.1.49 and later, during an upgrade installation using the RPM packages, if the MySQL server is running when the upgrade occurs, the MySQL server is stopped, the upgrade occurs, and the MySQL server is restarted. If the MySQL server is not already running when the RPM upgrade occurs, the MySQL server is not started at the end of the installation. If something goes wrong, you can find more information in the binary installation section. See *Note binary-installation::. *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 *Note postinstallation::. During RPM installation, a user named `mysql' and a group named `mysql' are created on the system. This is done using the `useradd', `groupadd', and `usermod' commands. Those commands require appropriate administrative privileges, which is required for locally managed users and groups (as listed in the `/etc/passwd' and `/etc/group' files) by the RPM installation process being run by `root'. If you log in as the `mysql' user, you may find that MySQL displays `Invalid (old?) table or database name' errors that mention `.mysqlgui', `lost+found', `.mysqlgui', `.bash_history', `.fonts.cache-1', `.lesshst', `.mysql_history', `.profile', `.viminfo', and similar files created by MySQL or operating system utilities. You can safely ignore these error messages or remove the files or directories that cause them if you do not need them. For nonlocal user management (LDAP, NIS, and so forth), the administrative tools may require additional authentication (such as a password), and will fail if the installing user does not provide this authentication. Even if they fail, the RPM installation will not abort but succeed, and this is intentional. If they failed, some of the intended transfer of ownership may be missing, and it is recommended that the system administrator then manually ensures some appropriate user and group exists and manually transfers ownership following the actions in the RPM spec file.  File: manual.info, Node: linux-installation-native, Prev: linux-installation-rpm, Up: linux-installation 2.5.2 Installing MySQL on Linux Using Native Package Managers ------------------------------------------------------------- Many Linux distributions include a version of the MySQL server, client tools, and development components into the standard package management system built into distributions such as Fedora, Debian, Ubuntu, and Gentoo. This section provides basic instructions for installing MySQL using these systems. *Important*: Native package installations can take care of the download and dependencies required to run MySQL, but the MySQL version will often be some way behind the currently available release. You will also normally be unable to install development releases, as these are not usually made available in the native repository. Distribution specific instructions are shown below: * *Red Hat Linux, Fedora, CentOS* 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 *Note `mysql_secure_installation': mysql-secure-installation. to set the root passwords on your server. * *Debian, Ubuntu, Kubuntu* On Debian and related distributions, there are two packages, `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. 100825 11:46:15 InnoDB: Started; log sequence number 0 46409 100825 11:46:15 InnoDB: Starting shutdown... 100825 11:46:17 InnoDB: Shutdown completed; log sequence number 0 46409 100825 11:46:17 [Warning] Forcing shutdown of 1 plugins * 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. * *Gentoo Linux* As a source-based distribution, installing MySQL on Gentoo involves downloading the source, patching the Gentoo specifics, and then compiling the MySQL server and installing it. This process is handled automatically by the `emerge' command. Depending on the version of MySQL that you want to install, you may need to unmask the specific version that you want for your chosen platform. The MySQL server and client tools are provided within a single package, `dev-db/mysql'. You can obtain a list of the versions available to install by looking at the portage directory for the package: root-shell> ls /usr/portage/dev-db/mysql/mysql-5.1* mysql-5.1.39-r1.ebuild mysql-5.1.44-r1.ebuild mysql-5.1.44-r2.ebuild mysql-5.1.44-r3.ebuild mysql-5.1.44.ebuild mysql-5.1.45-r1.ebuild mysql-5.1.45.ebuild mysql-5.1.46.ebuild To install a specific MySQL version, you must specify the entire atom. For example: root-shell> emerge =dev-db/mysql-5.1.46 A simpler alternative is to use the `virtual/mysql-5.1' package, which will install the latest version: root-shell> emerge =virtual/mysql-5.1 If the package is masked (because it is not tested or certified for the current platform), use the `ACCEPT_KEYWORDS' environment variable. For example: root-shell> ACCEPT_KEYWORDS="~x86" emerge =virtual/mysql-5.1 After installation, you should create a new database using *Note `mysql_install_db': mysql-install-db, and set the password for the root user on MySQL. You can use the configuration interface to set the password and create the initial database: root-shell> emerge --config =dev-db/mysql-5.1.46 A sample configuration file will have been created for you in `/etc/mysql/my.cnf', and an init script will have been created in `/etc/init.d/mysql'. To enable MySQL to start automatically at the normal (default) run levels, you can use: root-shell> rc-update add mysql default  File: manual.info, Node: solaris-installation, Next: aix-installation, Prev: linux-installation, Up: installing 2.6 Installing MySQL on Solaris and OpenSolaris =============================================== * Menu: * solaris-installation-pkg:: Installing MySQL on Solaris Using a Solaris PKG * solaris-installation-opensolaris:: Installing MySQL on OpenSolaris Using IPS MySQL on Solaris and OpenSolaris is available in a number of different formats. * For information on installing using the native Solaris PKG format, see *Note solaris-installation-pkg::. * On OpenSolaris, the standard package repositories include MySQL packages specially built for OpenSolaris that include entries for the Service Management Framework (SMF) to enable control of the installation using the SMF administration commands. For more information, see *Note solaris-installation-opensolaris::. * To use a standard `tar' binary installation, use the notes provided in *Note 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. * For information on installing MySQL on Solaris or OpenSolaris using a source distribution, first check the Solaris advice, *Note solaris-installation-source::. For detailed instructions on installing from source, see *Note source-installation::. To obtain a binary MySQL distribution for Solaris in tarball or PKG format, `http://dev.mysql.com/downloads/mysql/5.1.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 mysql * If you install MySQL using a binary tarball distribution on Solaris, you may run into trouble even before you get the MySQL distribution unpacked, as the Solaris `tar' cannot handle long file names. This means that you may see errors when you try to unpack MySQL. If this occurs, you must use GNU `tar' (`gtar') to unpack the distribution. In Solaris 10 and OpenSolaris `gtar' is normally located in `/usr/sfw/bin/gtar', but may not be included in the default path definition. * When using Solaris 10 for x86_64, 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 *Note `mysqld': 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.  File: manual.info, Node: solaris-installation-pkg, Next: solaris-installation-opensolaris, Prev: solaris-installation, Up: solaris-installation 2.6.1 Installing MySQL on Solaris Using a Solaris PKG ----------------------------------------------------- You can install MySQL on Solaris and OpenSolaris using a binary package using the native Solaris PKG format instead of the binary tarball distribution. To use this package, download the corresponding `mysql-VERSION-solaris10-PLATFORM.pkg.gz' file, then uncompress it. For example: shell> gunzip mysql-5.1.73-solaris10-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.1.73-solaris10-x86_64.pkg The following packages are available: 1 mysql MySQL Community Server (GPL) (i86pc) 5.1.73 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 *Note `mysql_secure_installation': 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.1.73-solaris10-x86_64.pkg shell> mysqld_safe & shell> mysql_upgrade You should check the notes in *Note upgrading-downgrading:: before performing any upgrade.  File: manual.info, Node: solaris-installation-opensolaris, Prev: solaris-installation-pkg, Up: solaris-installation 2.6.2 Installing MySQL on OpenSolaris Using IPS ----------------------------------------------- OpenSolaris includes standard packages for MySQL in the core repository. The MySQL packages are based on a specific release of MySQL and updated periodically. For the latest release you must use either the native Solaris PKG, `tar', or source installations. The native OpenSolaris packages include SMF files so that you can easily control your MySQL installation, including automatic startup and recovery, using the native service management tools. To install MySQL on OpenSolaris, use the `pkg' command. You will need to be logged in as root, or use the `pfexec' tool, as shown in the example below: shell> pfexec pkg install SUNWmysql51 The package set installs three individual packages, `SUNWmysql51lib', which contains the MySQL client libraries; `SUNWmysql51r' which contains the root components, including SMF and configuration files; and `SUNWmysql51u' which contains the scripts, binary tools and other files. You can install these packages individually if you only need the corresponding components. The MySQL files are installed into `/usr/mysql' which symbolic links for the sub directories (`bin', `lib', etc.) to a version specific directory. For MySQL 5.1, the full installation is located in `/usr/mysql/5.1'. The default data directory is `/var/mysql/5.1/data'. The configuration file is installed in `/etc/mysql/5.1/my.cnf'. This layout permits multiple versions of MySQL to be installed, without overwriting the data and binaries from other versions. Once installed, you must run *Note `mysql_install_db': mysql-install-db. to initialize the database, and use the *Note `mysql_secure_installation': mysql-secure-installation. to secure your installation. * Using SMF to manage your MySQL installation * Once installed, you can start and stop your MySQL server using the installed SMF configuration. The service name is `mysql', or if you have multiple versions installed, you should use the full version name, for example `mysql:version_51'. To start and enable MySQL to be started at boot time: shell> svcadm enable mysql To disable MySQL from starting during boot time, and shut the MySQL server down if it is running, use: shell> svcadm disable mysql To restart MySQL, for example after a configuration file changes, use the `restart' option: shell> svcadm restart mysql You can also use SMF to configure the data directory and enable full 64-bit mode. For example, to set the data directory used by MySQL: shell> svccfg svc:> select mysql:version_51 svc:/application/database/mysql:version_51> setprop mysql/data=/data0/mysql By default, the 32-bit binaries are used. To enable the 64-bit server on 64-bit platforms, set the `enable_64bit' parameter. For example: svc:/application/database/mysql:version_51> setprop mysql/enable_64bit=1 You need to refresh the SMF after settings these options: shell> svcadm refresh mysql  File: manual.info, Node: aix-installation, Next: hpux-installation, Prev: solaris-installation, Up: installing 2.7 Installing MySQL on IBM AIX =============================== * Menu: * aix-installation-general:: General Notes on Installing MySQL on AIX MySQL for IBM AIX is available in a number of different forms: * Using a binary tarball distribution provided at `http://dev.mysql.com/downloads/'. Please read the *Note general notes on AIX installation: aix-installation-general. before continuing. For more information on binary installations, see *Note binary-installation::. * Using a source tarball and compiling MySQL. Please read the *Note general notes on AIX installation: aix-installation-general. before continuing. You should also check the instructions on *Note building on AIX from source: aix-installation-source. For general information on building from source, see *Note source-installation::.  File: manual.info, Node: aix-installation-general, Prev: aix-installation, Up: aix-installation 2.7.1 General Notes on Installing MySQL on AIX ---------------------------------------------- General notes on using MySQL on IBM AIX: * If you have problems with threads on AIX 5.3, you should upgrade AIX 5.3 to technology level 7 (5300-07).  File: manual.info, Node: hpux-installation, Next: freebsd-installation, Prev: aix-installation, Up: installing 2.8 Installing MySQL on HP-UX ============================= * Menu: * hpux-installation-general:: General Notes on Installing MySQL on HP-UX * hpux-installation-depot:: Installing MySQL on HP-UX Using DEPOT Packages MySQL for HP-UX is available in a number of different forms: * Using a DEPOT distribution provided at `http://dev.mysql.com/downloads/'. Please read the *Note general notes on HP-UX installation: hpux-installation-general. before continuing. For more information on DEPOT installations, see *Note hpux-installation-depot::. * Using a binary tarball distribution provided at `http://dev.mysql.com/downloads/'. Please read the *Note general notes on HP-UX installation: hpux-installation-general. before continuing. For more information on binary installations, see *Note binary-installation::. * Using a source tarball and compiling MySQL. Please read the *Note general notes on HP-UX installation: hpux-installation-general. before continuing. You should also check the instructions on *Note building on HP-UX from source: hpux-installation-source. For general information on building from source, see *Note source-installation::.  File: manual.info, Node: hpux-installation-general, Next: hpux-installation-depot, Prev: hpux-installation, Up: hpux-installation 2.8.1 General Notes on Installing MySQL on HP-UX ------------------------------------------------ Some additional notes on installing and using MySQL on HP-UX: * If you install MySQL using a binary tarball distribution on HP-UX, you may run into trouble even before you get the MySQL distribution unpacked, as the HP-UX `tar' cannot handle long file names. This means that you may see errors when you try to unpack MySQL. If this occurs, you must use GNU `tar' (`gtar') to unpack the distribution. * Because of some critical bugs in the standard HP-UX libraries, you should install the following patches before trying to run MySQL on HP-UX 11.0: PHKL_22840 Streams cumulative PHNE_22397 ARPA cumulative This solves the problem of getting `EWOULDBLOCK' from `recv()' and `EBADF' from `accept()' in threaded applications.  File: manual.info, Node: hpux-installation-depot, Prev: hpux-installation-general, Up: hpux-installation 2.8.2 Installing MySQL on HP-UX Using DEPOT Packages ---------------------------------------------------- The HP-UX DEPOT format packages can be installed using the `swinstall' command. You should install the `ncurses' and `zlib' libraries before installing the MySQL DEPOT package. You can use the free software `depothelper' tool to install these packages and any dependencies for you automatically. To install using the MySQL DEPOT packages, follow this guide: 1. Download the MySQL DEPOT package from `http://dev.mysql.com/downloads/'. You must uncompress the package before installation: root-shell> gunzip mysql-5.1.48-hpux11.31-ia64-64bit.depot.gz 2. Install the DEPOT package using `swinstall': root-shell> swinstall -s MYSQL-5.1.49-HPUX11.31-IA64-64BIT.DEPOT MySQL will be installed into a directory matching the depot package name, within `/usr/local'. For convenience, you may want to create a symbolic link to the installed directory, for example: root-shell> ln -s mysql-5.1.49-hpux11.31-ia64-64bit mysql 3. Your package is now installed. You should complete the configuration of MySQL by creating a user and group: root-shell> /usr/sbin/groupadd mysql root-shell> /usr/sbin/useradd -g mysql -d /var/lib/mysql/ -s /bin/false mysql 4. Create the standard database using the new user/group you have created, and set the permissions: root-shell> cd /usr/local/ root-shell> scripts/mysql_install_db --user=mysql root-shell> chown -R root . root-shell> chown -R mysql data 5. Finally, secure your new installation by setting the root passwords, and then start your MySQL server using the `mysql' user: root-shell> mysql_secure_installation root-shell> mysqld_safe --user=mysql &  File: manual.info, Node: freebsd-installation, Next: i5os-installation, Prev: hpux-installation, Up: installing 2.9 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 *Note binary-installation::. The easiest (and preferred) way to install MySQL is to use the *Note `mysql-server': 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/mysql51-server # make ... # cd /usr/ports/databases/mysql51-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/mysql51-server # make deinstall ... # cd /usr/ports/databases/mysql51-client # make deinstall ... * If you get problems with the current date in MySQL, setting the `TZ' variable should help. See *Note environment-variables::.  File: manual.info, Node: i5os-installation, Next: source-installation, Prev: freebsd-installation, Up: installing 2.10 Installing MySQL on i5/OS ============================== The i5/OS POWER MySQL package was created in cooperation with IBM. MySQL works within the Portable Application Solution Environment (PASE) on the System i series of hardware and will also provide database services for the Zend Core for i5/OS. MySQL for i5/OS is provided both as a `tar' file and as a save file (`.savf') package that can be downloaded and installed directly without any additional installation steps required. To install MySQL using the `tar' file, see *Note binary-installation::. MySQL is only supported on i5/OS V5R4 or later releases. The i5/OS PASE must be installed for MySQL to operate. You must be able to login as a user in `*SECOFR' class. You should the installation notes and tips for i5/OS before starting installation. See i5/OS Installation Notes. *Before Installation:* *Note*: The installation package will use an existing configuration if you have previously installed MySQL (which is identified by looking for the file `/etc/my.cnf'). The values for the data directory (`DATADIR') and owner of the MySQL files (`USRPRF') specified during the installation will be ignored, and the values determined from the `/etc/my.cnf' will be used instead. If you want to change these parameters during a new install, you should temporarily rename `/etc/my.cnf', install MySQL using the new parameters you want to use, and then merge your previous `/etc/my.cnf' configuration settings with the new `/etc/my.cnf' file that is created during installation. * You must have a user profile with PASE with suitable privileges. The user should be within the `*SECOFR' class, such as the `QSECOFR' user ID. You can use the `WRKUSRPRF' command to check your user profile. * For network connections to MySQL, you must have TCP/IP enabled. You should also check the following: * Ensure that a name has defined for the system. Run the Configure TCP/IP (`CFGTCP') command and select option 12 (Change TCP/IP domain information) to display this setting. Make sure that a value is listed in the Host name field. * Make sure that the system has a loopback entry which represents the `localhost' or `127.0.0.1'. * Ensure that the IP address of the IBM i machine is mapped correctly to the host name. To install MySQL on i5/OS, follow these steps: 1. On the System i machine, create a save file that will be used to receive the downloaded installation save file. The file should be located within the General Purpose Library (`QGPL'): CRTSAVF FILE(QGPL/MYSQLINST) TESXT('MySQL Save file') 2. Download the MySQL installation save file in 32-bit (`mysql-5.1.73-i5os-power-32bit.savf') or 64-bit (`mysql-5.1.73-i5os-power-64bit.savf') from MySQL Downloads (http://dev.mysql.com/downloads/). 3. You need to FTP the downloaded `.savf' file directly into the `QGPL/MYSQLINST' file on the System i server. You can do this through FTP using the following steps after logging in to the System i machine: ftp> bin ftp> cd qgpl ftp> put mysql-5.1.73-i5os-power.savf mysqlinst 4. Log into the System i server using a user in the `*SECOFR' class, such as the `QSECOFR' user ID. 5. You need to restore the installation library stored in the `.savf' save file: RSTLIB MYSQLINST DEV(*SAVF) SAVF(QGPL/MYSQLINST) MBROPT(*ALL) ALWOBJDIF(*ALL) *Note*: You can ignore the security changes-type message at the bottom of the installation panel. 6. Once you have finished restoring the `MYSQLINST' library, check that all the necessary objects for installation are on the system by using the Display Library (`DSPLIB') command: DSPLIB LIB(MYSQLINST) 7. You need to execute the installation command, `MYSQLINST/INSMYSQL'. You can specify three parameter settings during installation: * `DIR('/QOPENSYS/USR/LOCAL/MYSQL')' sets the installation location for the MySQL files. The directory will be created if it does not already exist. * `DATADIR('/QOPENSYS/USR/LOCAL/MYSQL/DATA')' sets the location of the directory that will be used to store the database files and binary logs. The default setting is `/QOpenSys/usr/local/mysql/data'. Note that if the installer detects an existing installation (due to the existence of `/etc/my.cnf'), then the existing setting will be used instead of the default. * `USRPRF(MYSQL)' sets the user profile that will own the files that are installed. The profile will be created if it does not already exist. *Note*: You should choose an appropriate user for using the MySQL server installation. The user will be used whenever you need to do any administration on the MySQL server. Once you have set the appropriate parameters, you can begin the installation. The installation copies all the necessary files into a directory matching the `DIR' configuration value; sets the ownership on those files, sets up the MySQL environment and creates the MySQL configuration file (in `/etc/my.cnf') completing all the steps in a typical binary installation process automatically. If this is a new installation of MySQL, or if the installer detects that this is a new version (because the `/etc/my.cnf' file does not exist), then the initial core MySQL databases will also be created during installation. Once the installation has been completed, you will get a notice advising you to set the password for the root user. For more information, *Note postinstallation::. 8. Once the installation has completed, you can delete the installation file: DLTLIB LIB(MYSQLINST) *Upgrading an existing MySQL instance* You need to execute the upgrade command, `MYSQLINST/UPGMYSQL'. *Note*: You cannot use `MYSQLINST/UPGMYSQL' to upgrade between major versions of MySQL (for example from 5.0 to 5.1). For information and advice on migrating between major versions you can use the advice provided in *Note upgrading-from-previous-series::. You must specify 6 parameters to perform an upgrade: * `DIR('/QOpenSys/usr/local/')': Sets the installation location for the MySQL files. The directory will be created if it does not already exist. This is the directory that the MySQL server will be installed into, inside a directory with a name matching the version and release. For example, if installing MySQL 5.1.73 with the `DIR' set to `/QOpenSys/usr/local/' would result in `/QOpenSys/usr/local/mysql-5.1.73-i5os-power64' and a symbolic link to this directory will be created in `/QOpenSys/usr/local/mysql'. * `DATADIR('/QOpenSys/mysql/data')': Sets the location of the directory that will be upgraded. * `USRPRF('MYSQL')': Sets the user profile that will own the files that are installed. The profile will be created if it does not already exist; if it is created as part of the upgrade process, it will be disabled initially. You may wish to enable this user profile so that it can be used to start the MySQL server later. It is best practice to use the one previously created during the first installation. * `MYSQLUSR('root user')': Any user account in the current MySQL server with `SUPER' privileges. * `PASSWORD('root user password')': The password for the above account. This is necessary as the upgrade starts the MySQL server to upgrade the tables and the password is need to be able to shutdown the MySQL server. * `CURINST('path to previous install')': The full path to the installation that is being upgraded. For example an installation in `/QOpenSys/usr/local/' will be `/QOpenSys/usr/local/mysql-5.1.73-i5os-power64'. Failure to specify this option may result in corruption of your existing data files. For example: MYSQLINST/UPGMYSQL DIR('/QOPENSYS/USR/LOCAL/') DATADIR('/QOPENSYS/MYSQL/DATA') » USERPRF(MYSQL) MYSQLUSR('ROOT') PASSWORD('ROOT') CURINST('/QOPENSYS/USR/LOCAL/MYSQL-5.1.73-I5OS-POWER64') You should receive a Program Message indicating `UPGRADE SUCCESSFUL!' upon completion or an error message if there is a problem.You can view the upgrade programs progression and the error in the text file `upgrade.log' in the installation directory. *To start MySQL*: 1. Log into the System i server using the user profile create or specified during installation. By default, this is `MYSQL'. *Note*: You should start *Note `mysqld_safe': mysqld-safe. using a user that in the PASE environment has the id=0 (the equivalent of the standard Unix `root' user). If you do not use a user with this ID then the system will be unable to change the user when executing *Note `mysqld': mysqld. as set using `--user' option. If this happens, *Note `mysqld': mysqld. may be unable to read the files located within the MySQL data directory and the execution will fail. 2. Enter the PASE environment using `call qp2term'. 3. Start the MySQL server by changing to the installation directory and running *Note `mysqld_safe': mysqld-safe, specifying the user name used to install the server. The installer conveniently installs a symbolic link to the installation directory (`mysql-5.0.42-i5os-power-32bit') as `/opt/mysql/mysql': > cd /opt/mysql/mysql > bin/mysqld_safe --user=mysql & You should see a message similar to the following: Starting mysqld daemon with databases » from /opt/mysql/mysql-enterprise-5.0.42-i5os-power-32bit/data If you are having problems starting MySQL server, see *Note starting-server::. *To stop MySQL*: 1. Log into the System i server using the user profile create or specified during installation. By default, this is `MYSQL'. 2. Enter the PASE environment using `call qp2term'. 3. Stop the MySQL server by changing into the installation directory and running *Note `mysqladmin': mysqladmin, specifying the user name used to install the server: > cd /opt/mysql/mysql > bin/mysqladmin -u root shutdown If the session that you started and stopped MySQL are the same, you may get the log output from `mysqld': STOPPING server from pid file » /opt/mysql/mysql-enterprise-5.0.42-i5os-power-32bit/data/I5DBX.RCHLAND.IBM.COM.pid 070718 10:34:20 mysqld ended If the sessions used to start and stop MySQL are different, you will not receive any confirmation of the shutdown. _Note and tips_ * A problem has been identified with the installation process on DBCS systems. If you are having problems install MySQL on a DBCS system, you need to change your job's coded character set identifier (`CSSID') to 37 (`EBCDIC') before executing the install command, `INSMYSQL'. To do this, determine your existing `CSSID' (using `DSPJOB' and selecting option 2), execute `CHGJOB CSSID(37)', run `INSMYSQL' to install MySQL and then execute `CHGJOB' again with your original `CSSID.' * If you want to use the Perl scripts that are included with MySQL, you need to download the iSeries Tools for Developers (5799-PTL). See `http://www-03.ibm.com/servers/enable/site/porting/tools/'.  File: manual.info, Node: source-installation, Next: postinstallation, Prev: i5os-installation, Up: installing 2.11 Installing MySQL from Source ================================= * Menu: * source-installation-layout:: MySQL Layout for Source Installation * installing-source-distribution:: Installing MySQL Using a Standard Source Distribution * installing-development-tree:: Installing MySQL Using a Development Source Tree * source-configuration-options:: MySQL Source-Configuration Options * compilation-problems:: Dealing with Problems Compiling MySQL * compile-and-link-options:: Compiling and Linking an Optimized `mysqld' Server * windows-source-build:: Installing MySQL from Source on Windows * solaris-installation-source:: Notes on Installing MySQL on Solaris from Source * aix-installation-source:: Notes on Installing MySQL on AIX from Source * hpux-installation-source:: Notes on Installing MySQL on HP-UX 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 *Note supported-os::. Before you proceed with an installation from source, check whether we produce 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 *Note binary-installation::. To obtain a source distribution for MySQL, see *Note getting-mysql::. MySQL source 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.1.73'. To perform a MySQL installation using the source code: * To build MySQL from source on Unix-like systems, including Linux, commercial Unix, BSD, Mac OS X and others using a `.tar.gz' or RPM-based source code distribution, see *Note installing-source-distribution::. * To build MySQL from source on Windows (Windows XP or newer required), see *Note windows-source-build::. * For information on building from one of our development trees, see *Note installing-development-tree::. * For information on using the `configure' command to specify the source build parameters, including links to platform specific parameters that you might need, see *Note source-configuration-options::. To install MySQL from source, your system must have the following tools: * GNU `gunzip' to uncompress the distribution and a reasonable `tar' to unpack it (if you use a `.tar.gz' distribution), or `WinZip' or another tool that can read `.zip' files (if you use a `.zip' distribution). 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/'. * A working ANSI C++ compiler. GCC 3.4.6 or later, Sun Studio 10 or later, Visual Studio 2005 or later, and many current vendor-supplied compilers are known to work. * 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 newer. It may already be available on your system as `gmake'. GNU `make' is available from `http://www.gnu.org/software/make/'. * `libtool' 1.5, available from `http://www.gnu.org/software/libtool/'. 1.5.24 or later is recommended. If you run into problems and need to file a bug report, please use the instructions in *Note bug-reports::.  File: manual.info, Node: source-installation-layout, Next: installing-source-distribution, Prev: source-installation, Up: source-installation 2.11.1 MySQL Layout for Source Installation ------------------------------------------- By default, when you install MySQL after compiling it from a source distribution, the installation step installs files under `/usr/local'. Components are installed in the directories shown in the following table. To configure particular installation locations, use the options described at *Note source-configuration-options::. *MySQL Layout for Installation from Source* Directory Contents of Directory `bin' Client programs and scripts `include/mysql' Include (header) files `Docs' Manual in Info format `man' Unix manual pages `lib/mysql' Libraries `libexec' The *Note `mysqld': mysqld. server `share/mysql' Miscellaneous support files, including error messages, sample configuration files, SQL for database installation `sql-bench' Benchmarks `var' Log files, databases Within its installation directory, the layout of a source installation differs from that of a binary installation in the following ways: * The *Note `mysqld': mysqld. server is installed in the `libexec' directory rather than in the `bin' directory. * The data directory is `var' rather than `data'. * *Note `mysql_install_db': mysql-install-db. is installed in the `bin' directory rather than in the `scripts' directory. * The header file and library directories are `include/mysql' and `lib/mysql' rather than `include' and `lib'.  File: manual.info, Node: installing-source-distribution, Next: installing-development-tree, Prev: source-installation-layout, Up: source-installation 2.11.2 Installing MySQL Using a Standard Source Distribution ------------------------------------------------------------ To install MySQL from source, first configure, build, and install from a source package. Then follow the same postinstallation setup sequence as for a binary installation. 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 *Note linux-installation-rpm::. The sequence for installation from a compressed `tar' file source distribution is similar to the process for installing from a generic binary distribution that is detailed in *Note binary-installation::. For a MySQL `.tar.gz' source distribution, the basic installation command sequence looks like this: # Preconfiguration setup shell> groupadd mysql shell> useradd -g mysql mysql # Beginning of source-build specific instructions shell> tar zxvf mysql-VERSION.tar.gz shell> cd mysql-VERSION shell> ./configure --prefix=/usr/local/mysql shell> make shell> make install # End of source-build specific instructions # Postinstallation setup shell> cd /usr/local/mysql shell> chown -R mysql . shell> chgrp -R mysql . shell> bin/mysql_install_db --user=mysql shell> chown -R root . shell> chown -R mysql var # Next command is optional shell> cp support-files/my-medium.cnf /etc/my.cnf 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. Perform the following steps as the `mysql' user, except as noted. *Note*: The procedure shown here does not set up any passwords for MySQL accounts. After following the procedure, proceed to *Note postinstallation::, for postinstallation setup and testing. 1. 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 *Note binary-installation::. 2. Pick the directory under which you want to unpack the distribution and change location into it. 3. Obtain a distribution file using the instructions in *Note getting-mysql::. 4. Unpack the distribution into the current directory. `tar' can uncompress and unpack the distribution if it has `z' option support: shell> tar zxvf /PATH/TO/MYSQL-VERSION.tar.gz This command creates a directory named `mysql-VERSION'. If your `tar' does not have `z' option support, use `gunzip' to unpack the distribution and `tar' to unpack it: shell> gunzip < /PATH/TO/MYSQL-VERSION.tar.gz | tar xvf - 5. Change location into the top-level directory of the unpacked distribution: shell> cd mysql-VERSION 6. Configure the source directory: shell> ./configure --prefix=/usr/local/mysql When you run `configure', you might want to specify other options. For example, if you need to debug *Note `mysqld': mysqld. or a MySQL client, run `configure' with the `--with-debug' option, and then recompile and link your clients with the new client library. See *Note porting::. Run `./configure --help' for a list of options. *Note source-configuration-options::, discusses some of the more useful options. If `configure' fails and you are going to send mail to a MySQL mailing list to ask for assistance, please include any lines from `config.log' that you think can help solve the problem. Also include the last couple of lines of output from `configure'. To file a bug report, please use the instructions in *Note bug-reports::. 7. Compile the source distribution: shell> make Use `gmake' instead on systems where you are using GNU `make' and it has been installed as `gmake'. If the compile fails, see *Note compilation-problems::, for help. 8. Install the distribution: shell> make install You might need to run this command as `root'. The remainder of the installation process, including setting up the configuration file, creating the core databases, and starting the MySQL server, are identical to the remainder of the process as shown in Generic Binary Install. After everything has been installed, test the distribution. To start the MySQL server, use the following command: shell> /usr/local/mysql/bin/mysqld_safe --user=mysql & If you run the command as `root', you should use the `--user' option as shown. The option value is the name of the login account that you created in the first step to use for running the server. If you run the *Note `mysqld_safe': mysqld-safe. command while logged in as that user, you can omit the `--user' option. 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). For more information about *Note `mysqld_safe': mysqld-safe, see *Note mysqld-safe::. To make it more convenient to invoke programs installed in `/usr/local/mysql/bin', you can add that directory to your `PATH' environment variable setting. That enables you to run a program by typing only its name, not its entire path name. See *Note setting-environment-variables::. *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 *Note postinstallation::.  File: manual.info, Node: installing-development-tree, Next: source-configuration-options, Prev: installing-source-distribution, Up: source-installation 2.11.3 Installing MySQL Using a Development Source Tree ------------------------------------------------------- This section discusses how to install MySQL from the latest development source code. Development trees have not necessarily received the same level of testing as standard release distributions, so this installation method is usually required only if you need the most recent code changes. Do not use a development tree for production systems. If your goal is simply to get MySQL up and running on your system, you should use a standard release distribution (either a binary or source distribution). See *Note getting-mysql::. To obtain the source tree, you must have Bazaar installed. The Bazaar VCS Web site (http://bazaar-vcs.org) has instructions for downloading and installing Bazaar on different platforms. Bazaar is supported on any platform that supports Python, and is therefore compatible with any Linux, Unix, Windows, or Mac OS X host. MySQL development projects are hosted on Launchpad (http://launchpad.net/). MySQL projects, including MySQL Server, MySQL Workbench, and others are available from the Oracle/MySQL Engineering (http://launchpad.net/~mysql) page. For the repositories related only to MySQL Server, see the MySQL Server (http://launchpad.net/mysql-server) page. To build under Unix/Linux, you must have the following tools installed: * 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 newer. It may already be available on your system as `gmake'. GNU `make' is available from `http://www.gnu.org/software/make/'. * `autoconf' 2.58 (or newer), available from `http://www.gnu.org/software/autoconf/'. * `automake' 1.8.1, available from `http://www.gnu.org/software/automake/'. * `libtool' 1.5, available from `http://www.gnu.org/software/libtool/'. 1.5.24 or later is recommended. * `m4', available from `http://www.gnu.org/software/m4/'. * `bison', available from `http://www.gnu.org/software/bison/'. You should use the latest version of `bison' where possible. Versions 1.75 and 2.1 are known to work. There have been reported problems with `bison' 1.875. If you experience problems, upgrade to a later, rather than earlier, version. To build under Windows you must have Microsoft Visual C++ 2005 Express Edition, Visual Studio .Net 2003 (7.1), or Visual Studio 2005 (8.0) compiler system. Once the necessary tools are installed, create a local branch of the MySQL development tree on your machine using this procedure: 1. To obtain a copy of the MySQL source code, you must create a new Bazaar branch. If you do not already have a Bazaar repository directory set up, you must initialize a new directory: shell> mkdir mysql-server shell> bzr init-repo --trees mysql-server This is a one-time operation. 2. Assuming that you have an initialized repository directory, you can branch from the public MySQL server repositories to create a local source tree. To create a branch of a specific version: shell> cd mysql-server shell> bzr branch lp:mysql-server/5.1 mysql-5.1 This is a one-time operation per source tree. You can branch the source trees for several versions of MySQL under the `mysql-server' directory. 3. The initial download will take some time to complete, depending on the speed of your connection. Please be patient. Once you have downloaded the first tree, additional trees should take significantly less time to download. 4. When building from the Bazaar branch, you may want to create a copy of your active branch so that you can make configuration and other changes without affecting the original branch contents. You can achieve this by branching from the original branch: shell> bzr branch mysql-5.1 mysql-5.1-build 5. To obtain changes made after you have set up the branch initially, update it using the `pull' option periodically. Use this command in the top-level directory of the local copy: shell> bzr pull To examine the changeset comments for the tree, use the `log' option to `bzr': shell> bzr log You can also browse changesets, comments, and source code online at the Launchpad MySQL Server (http://launchpad.net/mysql-server) page. If you see diffs (changes) or code that you have a question about, do not hesitate to send email to the MySQL `internals' mailing list. See *Note mailing-lists::. If you think you have a better idea on how to do something, send an email message to the list with a patch. After you have the local branch, you can build MySQL server from the source code. On Windows, the build process is different from Unix/Linux: see *Note windows-source-build::. On Unix/Linux, use the `autoconf' system to create the `configure' script so that you can configure the build environment before building. The following example shows the typical commands required to build MySQL from a source tree. 1. Change location to the top-level directory of the source tree; replace `mysql-5.1' with the appropriate directory name. shell> cd mysql-5.1 2. Prepare the source tree for configuration. Prior to MySQL 5.1.12, you must separately configure the `InnoDB' storage engine. Run the following command from the main source directory: shell> (cd storage/innobase; autoreconf --force --install) You can omit the previous command for MySQL 5.1.12 and later, or if you do not require `InnoDB' support. Prepare the remainder of the source tree: shell> autoreconf --force --install As an alternative to the preceding `autoreconf' command, you can use `BUILD/autorun.sh', which acts as a shortcut for the following sequence of commands: shell> aclocal; autoheader shell> libtoolize --automake --force shell> automake --force --add-missing; autoconf If you get some strange errors during this stage, verify that you have the correct version of `libtool' installed. 3. Configure the source tree and compile MySQL: shell> ./configure # Add your favorite options here shell> make For a description of some `configure' options, see *Note source-configuration-options::. A collection of configuration scripts is located in the `BUILD/' subdirectory. For example, you may find it more convenient to use the `BUILD/compile-pentium-debug' script than the preceding set of shell commands. To compile on a different architecture, modify the script by removing flags that are Pentium-specific, or use another script that may be more appropriate. These scripts are provided on an `as-is' basis. They are not supported and their contents may change from release to release. 4. When the build is done, run `make install'. Be careful with this 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 `./configure' with values for the `--prefix', `--with-tcp-port', and `--with-unix-socket-path' options different from those used by your production server. For additional information about preventing multiple servers from interfering with each other, see *Note multiple-servers::. 5. Play hard with your new installation. For example, try to make new features crash. Start by running `make test'. See *Note mysql-test-suite::. 6. If you have gotten to the `make' stage, but the distribution does not compile, please enter the problem into our bugs database using the instructions given in *Note 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.  File: manual.info, Node: source-configuration-options, Next: compilation-problems, Prev: installing-development-tree, Up: source-installation 2.11.4 MySQL Source-Configuration Options ----------------------------------------- The `configure' script provides a great deal of control over how you configure a MySQL source distribution. Typically, you do this using options on the `configure' command line. For a full list of options supported by `configure', run this command: shell> ./configure --help You can also affect `configure' using certain environment variables. See *Note environment-variables::. The following table shows the available `configure' options. *MySQL Source-Configuration Option Reference (`configure')* Formats Description Default IntroducedRemoved `--bindir=DIR' User executables `EPREFIX/bin' `--build=BUILD' Configure for `guessed' building on BUILD `--cache-file=FILE' Cache test results in `disabled' FILE `-C' Alias for `' `-cache-file=config.cache' `--config-cache' `--datadir=DIR' Read-only `PREFIX/share' architecture-independent data `--disable-FEATURE' Do not include FEATURE `' `--disable-community-features'Disable additional `' 5.1.28 features provided by the community `--disable-dependency-tracking'Disable dependency `' tracking `--disable-grant-options'Disable GRANT options `' `--disable-largefile' Omit support for `' large files `--disable-libtool-lock'Disable libtool lock `' `--disable-thread-safe-client'Compile the client `' 5.1.7 without threads `--enable-FEATURE' Enable FEATURE `' `--enable-assembler' Use assembler `' versions of some string functions if available `--enable-debug-sync' Compile in Debug Sync `' 5.1.41 facility `--enable-dependency-tracking'Do not reject slow `' dependency extractors `--enable-fast-install'Optimize for fast `yes' installation `--enable-local-infile'Enable LOCAL for LOAD `disabled' DATA INFILE `--enable-profiling' Build a version with `' 5.1.24 query profiling code `--enable-shared' Build shared libraries `yes' `--enable-static' Build static libraries `yes' `--enable-thread-safe-client'Compile the client `' 5.1.6 with threads `--exec-prefix=EPREFIX'Install `' architecture-dependent files in EPREFIX `-h' Display this help and `' exit `--help' `--help=short' Display options specific to this package `--help=recursive' Display the short help of all the included packages `--host=HOST' Cross-compile to `' build programs to run on HOST `--includedir=DIR' C header files `PREFIX/include' `--infodir=DIR' Info documentation `PREFIX/info' `--libdir=DIR' Object code libraries `EPREFIX/lib' `--libexecdir=DIR' Program executables `EPREFIX/libexec' `--localstatedir=DIR' Modifiable `PREFIX/var' single-machine data `--mandir=DIR' man documentation `PREFIX/man' `-n' Do not create output `' files `--no-create' `--oldincludedir=DIR' C header files for `/usr/include' non-gcc `--prefix=PREFIX' Install `' architecture-independent files in PREFIX `--program-prefix=PREFIX'Prepend PREFIX to `' installed program names `--program-suffix=SUFFIX'Append SUFFIX to `' installed program names `--program-transform-name=PROGRAM'run sed PROGRAM on `' installed program names `-q' Do not print `' `checking...' messages `--quiet' `--sbindir=DIR' System administrative `EPREFIX/sbin' executables `--sharedstatedir=DIR' Modifiable `PREFIX/com' architecture-independent data `--srcdir=DIR' Find the sources in `configure DIR directory or ..' `--sysconfdir=DIR' Read-only `PREFIX/etc' single-machine data `--target=TARGET' Configure for `' building compilers for TARGET `-V' Display version `' information and exit `--version' `--with-PACKAGE' Use PACKAGE `' `--with-archive-storage-engine'Enable the Archive `no' 5.1.9 Storage Engine `--with-atomic-ops' Implement atomic `' 5.1.12 operations using pthread rwlocks or atomic CPU instructions for multi-processor `--with-berkeley-db' Use BerkeleyDB `no' 5.1.11 located in DIR `--with-berkeley-db-includes'Find Berkeley DB `' 5.1.11 headers in DIR `--with-berkeley-db-libs'Find Berkeley DB `' 5.1.11 libraries in DIR `--with-big-tables' Support tables with `' more than 4 G rows even on 32 bit platforms `--with-blackhole-storage-engine'Enable the Blackhole `no' 5.1.9 Storage Engine `--with-charset' Default character set `' `--with-client-ldflags'Extra linking `' arguments for clients `--with-collation' Default collation `' `--with-comment' Comment about `' compilation environment `--with-csv-storage-engine'Enable the CSV `yes' 5.1.9 Storage Engine `--with-darwin-mwcc' Use Metrowerks `' CodeWarrior wrappers on OS X/Darwin `--with-debug' Add debug code `' 5.1.7 `--with-debug=full' Add debug code (adds memory checker, very slow) `--with-embedded-privilege-control'Build parts to check `' user's privileges (only affects embedded library) `--with-embedded-server'Build the embedded `' server `--with-error-inject' Enable error `' 5.1.11 injection in MySQL Server `--with-example-storage-engine'Enable the Example `no' 5.1.9 Storage Engine `--with-extra-charsets'Use charsets in `' addition to default `--with-fast-mutexes' Compile with fast `enabled' 5.1.5 mutexes `--with-federated-storage-engine'Enable federated `no' 5.1.3 5.1.9 storage engine `--with-gnu-ld' Assume the C compiler `no' uses GNU ld `--with-innodb' Enable innobase `no' 5.1.3 5.1.9 storage engine `--with-lib-ccflags' Extra CC options for `' libraries `--with-libwrap=DIR' Compile in libwrap `' (tcp_wrappers) support `--with-low-memory' Try to use less `' memory to compile to avoid memory limitations `--with-machine-type' Set the machine type, `' like "powerpc" `--with-max-indexes=N' Sets the maximum `64' number of indexes per table `--with-mysqld-ldflags'Extra linking `' arguments for mysqld `--with-mysqld-libs' Extra libraries to `' link with for mysqld `--with-mysqld-user' What user the mysqld `' daemon shall be run as `--with-mysqlmanager' Build the `Build if mysqlmanager binary server is built' `--with-named-curses-libs'Use specified curses `' libraries `--with-named-thread-libs'Use specified thread `' libraries `--with-ndb-ccflags' Extra CC options for `' ndb compile `--with-ndb-docs' Include the NDB `' Cluster ndbapi and mgmapi documentation `--with-ndb-port' Port for NDB Cluster `' management server `--with-ndb-port-base' Port for NDB Cluster `' management server `--with-ndb-sci=DIR' Provide MySQL with a `' custom location of sci library `--with-ndb-test' Include the NDB `' Cluster ndbapi test programs `--with-ndbcluster' Include the NDB `no' 5.1.9 Cluster table handler `--with-openssl=DIR' Include the OpenSSL `' 5.1.9 support `--with-openssl-includes'Find OpenSSL headers `' 5.1.9 in DIR `--with-openssl-libs' Find OpenSSL `' 5.1.9 libraries in DIR `--with-other-libc=DIR'Link against libc and `' other standard libraries installed in the specified nonstandard location `--with-pic' Try to use only `Use both' PIC/non-PIC objects `--with-plugin-PLUGIN' Forces the named `' 5.1.11 plugin to be linked into mysqld statically `--with-plugins' Plugins to include in `none' 5.1.11 mysqld `--with-pstack' Use the pstack `' 5.1.54 backtrace library `--with-pthread' Force use of pthread `' library `--with-row-based-replication'Include row-based `' 5.1.5 5.1.6 replication `--with-server-suffix' Append value to the `' version string `--with-ssl=DIR' Include SSL support `' 5.1.11 `--with-system-type' Set the system type, `' like "sun-solaris10" `--with-tags' Include additional `automatic' configurations `--with-tcp-port' Which port to use for `3306' MySQL services `--with-unix-socket-path'Where to put the `' unix-domain socket `--with-yassl' Include the yaSSL `' 5.1.9 support `--with-zlib-dir=no|bundled|DIR'Provide MySQL with a `' custom location of compression library `--without-PACKAGE' Do not use PACKAGE `' `--without-bench' Skip building of the `' 5.1.11 benchmark suite `--without-debug' Build a production `' 5.1.6 version without debugging code `--without-docs' Skip building of the `' documentation `--without-extra-tools'Skip building `' 5.1.9 utilities in the tools directory `--without-geometry' Do not build `' geometry-related parts `--without-libedit' Use system libedit `' instead of bundled copy `--without-man' Skip building of the `' man pages `--without-ndb-binlog' Disable ndb binlog `' 5.1.6 `--without-ndb-debug' Disable special ndb `' debug features `--without-plugin-PLUGIN'Exclude PLUGIN `' 5.1.11 `--without-query-cache'Do not build query `' cache `--without-readline' Use system readline `' instead of bundled copy `--without-row-based-replication'Don't include `' 5.1.7 5.1.14 row-based replication `--without-server' Only build the client `' `--without-uca' Skip building of the `' national Unicode collations If you are using a version of `gcc' recent enough to understand the `-fno-exceptions' option, it is _very important_ that you use this option. Otherwise, you may compile a binary that crashes randomly. Also use `-felide-constructors' and `-fno-rtti' along with `-fno-exceptions'. When in doubt, do the following: CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors \ -fno-exceptions -fno-rtti" ./configure \ --prefix=/usr/local/mysql --enable-assembler \ --with-mysqld-ldflags=-all-static On most systems, this gives you a fast and stable binary. When compiling from source, you should also be aware of any platform specific considerations that may influence and impact the build process. Knowing and applying this information will help to ensure you get the best performance and most stable binary for your chosen platform. For more information, use the following sections: * *Note aix-installation-source:: * *Note hpux-installation-source:: * *Note solaris-installation-source:: Some of the `configure' options available are described here. For options that may be of use if you have difficulties building MySQL, see *Note compilation-problems::. Many options configure compile-time defaults that can be overridden at server startup. For example, the `--prefix', `--with-tcp-port', and `with-unix-socket-path' 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 *Note `mysqld': mysqld. * To compile just the MySQL client libraries and client programs and not the server, use the `--without-server' option: shell> ./configure --without-server If you have no C++ compiler, some client programs such as *Note `mysql': mysql. cannot be compiled because they require C++. In this case, you can remove the code in `configure' that tests for the C++ compiler and then run `./configure' with the `--without-server' option. The compile step should still try to build all clients, but you can ignore any warnings about files such as `mysql.cc'. (If `make' stops, try `make -k' to tell it to continue with the rest of the build even if errors occur.) * To build the embedded MySQL library (`libmysqld.a'), use the `--with-embedded-server' option. * To place your log files and database directories elsewhere than under `/usr/local/var', use a `configure' command something like one of these: shell> ./configure --prefix=/usr/local/mysql shell> ./configure --prefix=/usr/local \ --localstatedir=/usr/local/mysql/data The first command changes the installation prefix so that everything is installed under `/usr/local/mysql' rather than the default of `/usr/local'. The second command preserves the default installation prefix, but overrides the default location for database directories (normally `/usr/local/var') and changes it to `/usr/local/mysql/data'. You can also specify the installation directory and data directory locations at server startup time by using the `--basedir' and `--datadir' options. These can be given on the command line or in an MySQL option file, although it is more common to use an option file. See *Note option-files::. * The `--with-tcp-port' option specifies the port number on which the server listens for TCP/IP connections. The default is port 3306. To listen on a different port, use a `configure' command like this: shell> ./configure --with-tcp-port=3307 * On Unix, if you want the MySQL socket file location to be somewhere other than the default location (normally in the directory `/tmp' or `/var/run'), use a `configure' command like this: shell> ./configure \ --with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock The socket file name must be an absolute path name. You can also change the location of `mysql.sock' at server startup by using a MySQL option file. See *Note problems-with-mysql-sock::. * To compile statically linked programs (for example, to make a binary distribution, to get better performance, or to work around problems with some Red Hat Linux distributions), run `configure' like this: shell> ./configure --with-client-ldflags=-all-static \ --with-mysqld-ldflags=-all-static * If you are using `gcc' and do not have `libg++' or `libstdc++' installed, you can tell `configure' to use `gcc' as your C++ compiler: shell> CC=gcc CXX=gcc ./configure When you use `gcc' as your C++ compiler, it does not attempt to link in `libg++' or `libstdc++'. This may be a good thing to do even if you have those libraries installed. Some versions of them have caused strange problems for MySQL users in the past. In most cases, you can get a reasonably optimized MySQL binary by using the following options on the `configure' line: --prefix=/usr/local/mysql --enable-assembler \ --with-mysqld-ldflags=-all-static The full `configure' line would, in other words, be something like the following for all recent `gcc' versions: CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \ -felide-constructors -fno-exceptions -fno-rtti" ./configure \ --prefix=/usr/local/mysql --enable-assembler \ --with-mysqld-ldflags=-all-static The binaries we provide on the MySQL Web site at `http://dev.mysql.com/downloads/' are all compiled with full optimization and should work well for most users. See *Note binary-installation::. * If the build fails and produces errors about your compiler or linker not being able to create the shared library `libmysqlclient.so.N' (where N is a version number), you can work around this problem by giving the `--disable-shared' option to `configure'. In this case, `configure' does not build a shared `libmysqlclient.so.N' library. * By default, MySQL uses the `latin1' (cp1252 West European) character set. To change the default set, use the `--with-charset' option: shell> ./configure --with-charset=CHARSET CHARSET 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'. (Additional character sets might be available. Check the output from `./configure --help' for the current list.) The default collation may also be specified. MySQL uses the `latin1_swedish_ci' collation by default. To change this, use the `--with-collation' option: shell> ./configure --with-collation=COLLATION To change both the character set and the collation, use both the `--with-charset' and `--with-collation' options. The collation must be a legal collation for the character set. (Use the *Note `SHOW COLLATION': show-collation. statement to determine which collations are available for each character set.) With the `configure' option `--with-extra-charsets=LIST', you can define which additional character sets should be compiled into the server. LIST is one of the following: * A list of character set names separated by spaces * `complex' to include all character sets that can't be dynamically loaded * `all' to include all character sets into the binaries Clients that want to convert characters between the server and the client should use the `SET NAMES' statement. See *Note charset-connection::. * To configure MySQL with debugging code, use the `--with-debug' option: shell> ./configure --with-debug This causes a safe memory allocator to be included that can find some errors and that provides output about what is happening. See *Note porting::. As of MySQL 5.1.12, using `--with-debug' 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. * To cause the Debug Sync facility to be compiled into the server, use the `--enable-debug-sync' option. This facility is used for testing and debugging. When compiled in, Debug Sync is disabled by default at runtime. To enable it, start *Note `mysqld': 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. Debug Sync is also compiled in if you configure with the `--with-debug' option (which implies `--enable-debug-sync'), unless you also use the `--disable-debug-sync' 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). The `--enable-debug-sync' and `--disable-debug-sync' options were added in MySQL 5.1.41. * If your client programs are using threads, you must compile a thread-safe version of the MySQL client library with the `--enable-thread-safe-client' configure option. This creates a `libmysqlclient_r' library with which you should link your threaded applications. See *Note c-api-threaded-clients::. * 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-dir=no|bundled|DIR' option provides control over compression library support. The value `no' explicitly disables compression support. `bundled' causes the `zlib' library bundled in the MySQL sources to be used. A DIR path name specifies the directory in which to find the compression library sources. * It is possible to build MySQL with large table support using the `--with-big-tables' option. This option causes the variables that store table row counts to be declared as `unsigned long long' rather than `unsigned long'. This enables tables to hold up to approximately 1.844E+19 ((2^32)^2) rows rather than 2^32 (~4.295E+09) rows. Previously it was necessary to pass `-DBIG_TABLES' to the compiler manually in order to enable this feature. * Run `configure' with the `--disable-grant-options' option to cause the `--bootstrap', `--skip-grant-tables', and `--init-file' options for *Note `mysqld': mysqld. to be disabled. For Windows, the `configure.js' script recognizes the `DISABLE_GRANT_OPTIONS' flag, which has the same effect. The capability is available as of MySQL 5.1.15. * This option allows MySQL Community Server features to be enabled. Additional options may be required for individual features, such as `--enable-profiling' to enable statement profiling. This option was added in MySQL 5.1.24. It is enabled by default as of MySQL 5.1.28; to disable it, use `--disable-community-features'. * When given with `--enable-community-features', the `--enable-profiling' option enables the statement profiling capability exposed by the *Note `SHOW PROFILE': show-profile. and *Note `SHOW PROFILES': show-profiles. statements. (See *Note show-profiles::.) This option was added in MySQL 5.1.24. It is enabled by default as of MySQL 5.1.28; to disable it, use `--disable-profiling'. * See *Note general-installation-issues::, for options that pertain to particular operating systems. * See *Note configuring-for-ssl::, for options that pertain to configuring MySQL to support secure (encrypted) connections. * Several `configure' options apply to plugin selection and building: --with-plugins=PLUGIN[,PLUGIN]... --with-plugins=GROUP --with-plugin-PLUGIN --without-plugin-PLUGIN PLUGIN is an individual plugin name such as `csv' or `archive'. As shorthand, GROUP is a configuration group name such as `none' (select no plugins) or `all' (select all plugins). You can build a plugin as static (compiled into the server) or dynamic (built as a dynamic library that must be installed using the *Note `INSTALL PLUGIN': install-plugin. statement or the `--plugin-load' option before it can be used). Some plugins might not support static or dynamic build. `configure --help' shows the following information pertaining to plugins: * The plugin-related options * The names of all available plugins * For each plugin, a description of its purpose, which build types it supports (static or dynamic), and which plugin groups it is a part of. `--with-plugins' can take a list of one or more plugin names separated by commas, or a plugin group name. The named plugins are configured to be built as static plugins. `--with-plugin-PLUGIN' configures the given plugin to be built as a static plugin. `--without-plugin-PLUGIN' disables the given plugin from being built. If a plugin is named both with a `--with' and `--without' option, the result is undefined. For any plugin that is not explicitly selected or disabled, it is selected to be built dynamically if it supports dynamic build, and not built if it does not support dynamic build. (Thus, in the case that no plugin options are given, all plugins that support dynamic build are selected to be built as dynamic plugins. Plugins that do not support dynamic build are not built.)  File: manual.info, Node: compilation-problems, Next: compile-and-link-options, Prev: source-configuration-options, Up: source-installation 2.11.5 Dealing with Problems Compiling MySQL -------------------------------------------- All MySQL programs compile cleanly for us with no warnings on Solaris or Linux using `gcc'. On other systems, warnings may occur due to differences in system include files. For other problems, check the following list. The solution to many problems involves reconfiguring. If you do need to reconfigure, take note of the following: * If `configure' is run after it has previously been run, it may use information that was gathered during its previous invocation. This information is stored in `config.cache'. When `configure' 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 `configure', 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 configuration information or object files from being used, run these commands before re-running `configure': shell> rm config.cache shell> make clean Alternatively, you can run `make distclean'. The following list describes some of the problems that have been found to occur most often when compiling MySQL: * If you get errors such as the ones shown here when compiling `sql_yacc.cc', you probably have run out of memory or swap space: Internal compiler error: program cc1plus got fatal signal 11 Out of virtual memory Virtual memory exhausted The problem is that `gcc' requires a huge amount of memory to compile `sql_yacc.cc' with inline functions. Try running `configure' with the `--with-low-memory' option: shell> ./configure --with-low-memory This option causes `-fno-inline' to be added to the compile line if you are using `gcc' and `-O0' if you are using something else. You should try the `--with-low-memory' option even if you have so much memory and swap space that you think you can't possibly have run out. This problem has been observed to occur even on systems with generous hardware configurations, and the `--with-low-memory' option usually fixes it. * By default, `configure' picks `c++' as the compiler name and GNU `c++' links with `-lg++'. If you are using `gcc', that behavior can cause problems during configuration such as this: configure: error: installation or configuration problem: C++ compiler cannot create executables. You might also observe problems during compilation related to `g++', `libg++', or `libstdc++'. One cause of these problems is that you may not have `g++', or you may have `g++' but not `libg++', or `libstdc++'. Take a look at the `config.log' file. It should contain the exact reason why your C++ compiler did not work. To work around these problems, you can use `gcc' as your C++ compiler. Try setting the environment variable `CXX' to `"gcc -O3"'. For example: shell> CXX="gcc -O3" ./configure This works because `gcc' compiles C++ source files as well as `g++' does, but does not link in `libg++' or `libstdc++' by default. Another way to fix these problems is to install `g++', `libg++', and `libstdc++'. However, do not use `libg++' or `libstdc++' with MySQL because this only increases the binary size of *Note `mysqld': mysqld. without providing any benefits. Some versions of these libraries have also caused strange problems for MySQL users in the past. * To define flags to be used by your C or C++ compilers, specify them using the `CFLAGS' and `CXXFLAGS' environment variables. You can also specify the compiler names this way using `CC' and `CXX'. For example: shell> CC=gcc shell> CFLAGS=-O3 shell> CXX=gcc shell> CXXFLAGS=-O3 shell> export CC CFLAGS CXX CXXFLAGS To see what flags you might need to specify, invoke *Note `mysql_config': mysql-config. with the `--cflags' option. * If you get errors such as those shown here when compiling *Note `mysqld': mysqld, `configure' did not correctly detect the type of the last argument to `accept()', `getsockname()', or `getpeername()': cxx: Error: mysqld.cc, line 645: In this statement, the referenced type of the pointer value ''length'' is ''unsigned long'', which is not compatible with ''int''. new_sock = accept(sock, (struct sockaddr *)&cAddr, &length); To fix this, edit the `config.h' file (which is generated by `configure'). Look for these lines: /* Define as the base type of the last arg to accept */ #define SOCKET_SIZE_TYPE XXX Change `XXX' to `size_t' or `int', depending on your operating system. (You must do this each time you run `configure' because `configure' regenerates `config.h'.) * 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 `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'. * On Debian Linux 3.0, you need to install `gawk' instead of the default `mawk'. * If you get a compilation error on Linux (for example, SuSE Linux 8.1 or Red Hat Linux 7.3) similar to the following one, you probably do not have `g++' installed: libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from incompatible pointer type libmysql.c:1329: too few arguments to function `gethostbyname_r' libmysql.c:1329: warning: assignment makes pointer from integer without a cast make[2]: *** [libmysql.lo] Error 1 By default, the `configure' script attempts to determine the correct number of arguments by using `g++' (the GNU C++ compiler). This test yields incorrect results if `g++' is not installed. There are two ways to work around this problem: * Make sure that the GNU C++ `g++' is installed. On some Linux distributions, the required package is called `gpp'; on others, it is named `gcc-c++'. * Use `gcc' as your C++ compiler by setting the `CXX' environment variable to `gcc': export CXX="gcc" You must run `configure' again after making either of those changes. For information about acquiring or updating tools, see the system requirements in *Note source-installation::.  File: manual.info, Node: compile-and-link-options, Next: windows-source-build, Prev: compilation-problems, Up: source-installation 2.11.6 Compiling and Linking an Optimized `mysqld' Server --------------------------------------------------------- Most of the following tests were performed on Linux with the MySQL benchmarks, but they should give some indication for other operating systems and workloads. You obtain the fastest executables when you link with `-static'. By using better compiler and compilation options, you can obtain a 10% to 30% speed increase in applications. This is particularly important if you compile the MySQL server yourself. When we tested both the Cygnus CodeFusion and Fujitsu compilers, neither was sufficiently bug-free to enable MySQL to be compiled with optimizations enabled. The standard MySQL binary distributions are compiled with support for all character sets. When you compile MySQL yourself, include support only for the character sets that you are going to use. This is controlled by the `--with-charset' option to `configure'. Here is a list of some measurements that we have made: * If you link dynamically (without `-static'), the result is 13% slower on Linux. Note that you still can use a dynamically linked MySQL library for your client applications. It is the server that is most critical for performance. * For a connection from a client to a server running on the same host, if you connect using TCP/IP rather than a Unix socket file, performance is 7.5% slower. (On Unix, if you connect to the host name `localhost', MySQL uses a socket file by default.) * For TCP/IP connections from a client to a server, connecting to a remote server on another host is 8% to 11% slower than connecting to a server on the same host, even for connections faster than 100Mb/s Ethernet. * When running our benchmark tests using secure connections (all data encrypted with internal SSL support) performance was 55% slower than with unencrypted connections. * On a Sun UltraSPARC-IIe, a server compiled with Forte 5.0 is 4% faster than one compiled with `gcc' 3.2. * On a Sun UltraSPARC-IIe, a server compiled with Forte 5.0 is 4% faster in 32-bit mode than in 64-bit mode. * Compiling on Linux-x86 using `gcc' without frame pointers (`-fomit-frame-pointer' or `-fomit-frame-pointer -ffixed-ebp') makes *Note `mysqld': mysqld. 1% to 4% faster.  File: manual.info, Node: windows-source-build, Next: solaris-installation-source, Prev: compile-and-link-options, Up: source-installation 2.11.7 Installing MySQL from Source on Windows ---------------------------------------------- These instructions describe how to build binaries from source for MySQL 5.1 on Windows. Instructions are provided for building binaries from a standard source distribution or from the Bazaar tree that contains the latest development source. *Note*: The instructions here are strictly for users who want to test MySQL on Microsoft Windows from the latest source distribution or from the Bazaar tree. For production use, we do not advise using a MySQL server built by yourself from source. Normally, it is best to use precompiled binary distributions of MySQL that are built specifically for optimal performance on Windows by Oracle Corporation. Instructions for installing binary distributions are available in *Note windows-installation::. To build MySQL on Windows from source, you must satisfy the following system, compiler, and resource requirements: * Windows 2000, Windows XP, or newer version. Windows Vista is supported when using Visual Studio 2005 provided you have installed the following updates: * Microsoft Visual Studio 2005 Professional Edition - ENU Service Pack 1 (KB926601) (http://support.microsoft.com/?kbid=926601) * Security Update for Microsoft Visual Studio 2005 Professional Edition - ENU (KB937061) (http://support.microsoft.com/?kbid=937061) * Update for Microsoft Visual Studio 2005 Professional Edition - ENU (KB932232) (http://support.microsoft.com/?kbid=932232) * `CMake', which can be downloaded from `http://www.cmake.org'. After installing, modify your `PATH' environment variable to include the directory where `cmake' is located. * Microsoft Visual C++ 2005 Express Edition, Visual Studio .Net 2003 (7.1), or Visual Studio 2005 (8.0) compiler system. * If you are using Visual C++ 2005 Express Edition, you must also install an appropriate Platform SDK. More information and links to downloads for various Windows platforms is available from `http://www.microsoft.com/downloads/details.aspx?familyid=0baf2b35-c656-4969-ace8-e4c0c0716adb'. * If you are compiling from a Bazaar tree or making changes to the parser, you need `bison' for Windows, which can be downloaded from `http://gnuwin32.sourceforge.net/packages/bison.htm'. Download the package labeled `Complete package, excluding sources'. After installing the package, modify your `PATH' environment variable to include the directory where `bison' is located. *Note*: On Windows, the default location for `bison' is the `C:\Program Files\GnuWin32' directory. Some utilities, including `m4', may fail to find `bison' because of the space in the directory name. You can resolve this by installing into a directory that does not contain a space; for example `C:\GnuWin32'. * Cygwin might be necessary if you want to run the test script or package the compiled binaries and support files into a Zip archive. (Cygwin is needed only to test or package the distribution, not to build it.) Cygwin is available from `http://cygwin.com'. * 3GB to 5GB of disk space. You also need a MySQL source distribution for Windows, which can be obtained two ways: * Obtain a source distribution packaged by Oracle Corporation. These are available from `http://dev.mysql.com/downloads/'. * Package a source distribution yourself from the latest Bazaar developer source tree. For instructions on pulling the latest source files, see *Note installing-development-tree::. If you find something not working as expected, or you have suggestions about ways to improve the current build process on Windows, please send a message to the `win32' mailing list. See *Note mailing-lists::. *Note*: To compile from the source code on Windows you must use the standard source distribution (for example, `mysql-5.1.73.zip') or `mysql-5.1.73.tar.gz'). You build from the same distribution as used to build MySQL on Unix, Linux and other platforms. Do _not_ use the Windows Source distributions as they do not contain the necessary configuration script and other files. Follow this procedure to build MySQL: 1. If you are installing from a packaged source distribution, create a work directory (for example, `C:\workdir'), and unpack the source distribution there using `WinZip' or another Windows tool that can read `.zip' files. This directory is the work directory in the following instructions. *Note*: Commands that are located in the `win' directory should be executed from the top-level source directory. Do not change location into the `win' directory, as the commands will not execute correctly. 2. Start a command shell. If you have not configured the `PATH' and other environment variables for all command shells, you may be able to start a command shell from the `Start Menu' within the Windows Visual Studio menu that contains the necessary environment changes. 3. Within the command shell, navigate to the work directory and run the following command: C:\workdir>win\configure.js OPTIONS If you have associated the `.js' file extension with an application such as a text editor, then you may need to use the following command to force `configure.js' to be executed as a script: C:\workdir>cscript win\configure.js OPTIONS These options are available for `configure.js': * `WITH_INNOBASE_STORAGE_ENGINE': Enable the *Note `InnoDB': innodb-storage-engine. storage engine. * `WITH_PARTITION_STORAGE_ENGINE': Enable user-defined partitioning. * `WITH_ARCHIVE_STORAGE_ENGINE': Enable the *Note `ARCHIVE': archive-storage-engine. storage engine. * `WITH_BLACKHOLE_STORAGE_ENGINE': Enable the *Note `BLACKHOLE': blackhole-storage-engine. storage engine. * `WITH_EXAMPLE_STORAGE_ENGINE': Enable the *Note `EXAMPLE': example-storage-engine. storage engine. * `WITH_FEDERATED_STORAGE_ENGINE': Enable the *Note `FEDERATED': federated-storage-engine. storage engine. * `WITH_NDBCLUSTER_STORAGE_ENGINE': Enable the *Note `NDBCLUSTER': mysql-cluster. storage engine in the MySQL server; cause binaries for the MySQL Cluster management and data node, management client, and other programs to be built. This option is supported only in MySQL Cluster NDB 7.0 and later (*Note `NDBCLUSTER': mysql-cluster. storage engine versions 6.4.0 and later) using the MySQL Cluster sources. It cannot be used to enable clustering support in other MySQL source trees or distributions. * `MYSQL_SERVER_SUFFIX=SUFFIX': Server suffix, default none. * `COMPILATION_COMMENT=COMMENT': Server comment, default "Source distribution". * `MYSQL_TCP_PORT=PORT': Server port, default 3306. * `DISABLE_GRANT_OPTIONS': Disables the `--bootstrap', `--skip-grant-tables', and `--init-file' options for *Note `mysqld': mysqld. This option is available as of MySQL 5.1.15. For example (type the command on one line): C:\workdir>win\configure.js WITH_INNOBASE_STORAGE_ENGINE WITH_PARTITION_STORAGE_ENGINE MYSQL_SERVER_SUFFIX=-pro 4. From the work directory, execute the `win\build-vs9.bat' (Windows Visual Studio 2008), `win\build-vs8.bat' (Windows Visual Studio 2005), or `win\build-vs71.bat' (Windows Visual Studio 2003) script, depending on the version of Visual Studio you have installed. The script invokes `CMake', which generates the `mysql.sln' solution file. You can also use the corresponding 64-bit file (for example `win\build-vs8_x64.bat' or `win\build-vs9_x64.bat') to build the 64-bit version of MySQL. However, you cannot build the 64-bit version with Visual Studio Express Edition. You must use Visual Studio 2005 (8.0) or higher. 5. From the work directory, open the generated `mysql.sln' file with Visual Studio and select the proper configuration using the `Configuration' menu. The menu provides `Debug', `Release', `RelwithDebInfo', `MinRelInfo' options. Then select `Solution' > `Build' to build the solution. Remember the configuration that you use in this step. It is important later when you run the test script because that script needs to know which configuration you used. 6. Test the server. The server built using the preceding instructions expects that the MySQL base directory and data directory are `C:\mysql' and `C:\mysql\data' by default. If you want to test your server using the source tree root directory and its data directory as the base directory and data directory, you need to tell the server their path names. You can either do this on the command line with the `--basedir' and `--datadir' options, or by placing appropriate options in an option file. (See *Note option-files::.) If you have an existing data directory elsewhere that you want to use, you can specify its path name instead. When the server is running in standalone fashion or as a service based on your configuration, try to connect to it from the *Note `mysql': mysql. interactive command-line utility. You can also run the standard test script, `mysql-test-run.pl'. This script is written in Perl, so you'll need either Cygwin or ActiveState Perl to run it. You may also need to install the modules required by the script. To run the test script, change location into the `mysql-test' directory under the work directory, set the `MTR_VS_CONFIG' environment variable to the configuration you selected earlier (or use the `--vs-config' option), and invoke `mysql-test-run.pl'. For example (using Cygwin and the `bash' shell): shell> `cd mysql-test' shell> `export MTR_VS_CONFIG=debug' shell> `./mysql-test-run.pl --force --timer' shell> `./mysql-test-run.pl --force --timer --ps-protocol' When you are satisfied that the programs you have built are working correctly, stop the server. Now you can install the distribution. One way to do this is to use the *Note `make_win_bin_dist': make-win-bin-dist. script in the `scripts' directory of the MySQL source distribution (see *Note make-win-bin-dist::). This is a shell script, so you must have Cygwin installed if you want to use it. It creates a Zip archive of the built executables and support files that you can unpack in the location at which you want to install MySQL. It is also possible to install MySQL by copying directories and files directly: 1. Create the directories where you want to install MySQL. For example, to install into `C:\mysql', use these commands: C:\> mkdir C:\mysql C:\> mkdir C:\mysql\bin C:\> mkdir C:\mysql\data C:\> mkdir C:\mysql\share C:\> mkdir C:\mysql\scripts If you want to compile other clients and link them to MySQL, you should also create several additional directories: C:\> mkdir C:\mysql\include C:\> mkdir C:\mysql\lib C:\> mkdir C:\mysql\lib\debug C:\> mkdir C:\mysql\lib\opt If you want to benchmark MySQL, create this directory: C:\> mkdir C:\mysql\sql-bench Benchmarking requires Perl support for MySQL. See *Note perl-support::. 2. From the work directory, copy into the `C:\mysql' directory the following files and directories: C:\> cd \workdir C:\workdir> mkdir C:\mysql C:\workdir> mkdir C:\mysql\bin C:\workdir> copy client\Release\*.exe C:\mysql\bin C:\workdir> copy sql\Release\mysqld.exe C:\mysql\bin\mysqld.exe C:\workdir> xcopy scripts\*.* C:\mysql\scripts /E C:\workdir> xcopy share\*.* C:\mysql\share /E If you want to compile other clients and link them to MySQL, you should also copy several libraries and header files: C:\workdir> copy lib\Release\mysqlclient.lib C:\mysql\lib\debug C:\workdir> copy lib\Release\libmysql.* C:\mysql\lib\debug C:\workdir> copy lib\Release\zlib.* C:\mysql\lib\debug C:\workdir> copy lib\Release\mysqlclient.lib C:\mysql\lib\opt C:\workdir> copy lib\Release\libmysql.* C:\mysql\lib\opt C:\workdir> copy lib\Release\zlib.* C:\mysql\lib\opt C:\workdir> copy include\*.h C:\mysql\include C:\workdir> copy libmysql\libmysql.def C:\mysql\include *Note*: If you have compiled a Debug solution, rather than a Release solution, install it by replacing `Release' with `Debug' in the source file names just shown. If you want to benchmark MySQL, you should also do this: C:\workdir> xcopy sql-bench\*.* C:\mysql\bench /E After installation, set up and start the server in the same way as for binary Windows distributions. This includes creating the system tables by running *Note `mysql_install_db': mysql-install-db. For more information, see *Note windows-installation::.  File: manual.info, Node: solaris-installation-source, Next: aix-installation-source, Prev: windows-source-build, Up: source-installation 2.11.8 Notes on Installing MySQL on Solaris from Source ------------------------------------------------------- When building MySQL on Solaris you can use either the Sun Studio or GNU cc compilers. For more information on specific notes and environments, use the following hints. * When building you should ensure that your `PATH' variable includes the necessary tools, including `ar' for building libraries. Some tools are located in `/usr/ccs/bin'. * When running `configure', you should specify the C and C++ compiler explicitly to ensure that the right C compiler combination is used: CC=gcc CXX=g++ ./configure * For detailed information on performance tuning your MySQL installation for Solaris, you can use the information from Krish Shankar (http://blogs.sun.com/krishs/entry/sun_studio_compiler_options_for) and the Sun Solaris MySQL Performance Tuning (http://developers.sun.com/solaris/articles/mysql_perf_tune.html) pages. * If you have an UltraSPARC system, you can get 4% better performance by adding `-mcpu=v8 -Wa,-xarch=v8plusa' to the `CFLAGS' and `CXXFLAGS' environment variables. * If you have Sun's Forte 5.00 (or newer) or Sun Studio compiler, you can run `configure' like this: CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \ CXX=CC CXXFLAGS="-noex -mt" \ ./configure --prefix=/usr/local/mysql --enable-assembler * To create a 64-bit SPARC binary with Sun's Forte or Sun Studio compiler, use the following configuration options: CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \ CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \ ./configure --prefix=/usr/local/mysql --enable-assembler To create a 64-bit Solaris binary using `gcc', add `-m64' to `CFLAGS' and `CXXFLAGS' and remove `--enable-assembler' from the `configure' line. In the MySQL benchmarks, we obtained a 4% speed increase on UltraSPARC when using Forte 5.0 in 32-bit mode, as compared to using `gcc' 3.2 with the `-mcpu' flag. If you create a 64-bit *Note `mysqld': mysqld. binary, it is 4% slower than the 32-bit binary, but can handle more threads and memory. * If you get a problem with `fdatasync' or `sched_yield', you can fix this by adding `LIBS=-lrt' to the `configure' line * Solaris does not provide static versions of all system libraries (`libpthreads' and `libdl'), so you cannot compile MySQL with `--static'. If you try to do so, you get one of the following errors: ld: fatal: library -ldl: not found undefined reference to `dlopen' cannot find -lrt * If you link your own MySQL client programs, you may see the following error at runtime: ld.so.1: fatal: libmysqlclient.so.#: open failed: No such file or directory To avoid this problem, use one of the following methods: * Use the `crle' tool to add the directory containing the `libmysqlclient' library file to the list of standard library directories. You need administrator privileges to do this. Make sure you update the library information, rather than replace it with the new path. For example, the following command adds the directory to the list of standard directories searched for libraries. crle -u -l /usr/local/mysql/lib For 64-bit libraries, add the `-64' option: crle -64 -u -l /usr/local/mysql/lib * Link clients with the `-Wl,r/full/path/to/libmysqlclient.so' flag rather than with `-Lpath'). * Copy `libmysqlclient.so' to `/usr/lib'. * Add the path name of the directory where `libmysqlclient.so' is located to the `LD_RUN_PATH' environment variable before running your client. * If you have problems with `configure' trying to link with `-lz' when you do not have `zlib' installed, you have two options: * If you want to be able to use the compressed communication protocol, obtain and install `zlib' from `ftp.gnu.org'. * To build without `zlib', run `configure' with the `--with-named-z-libs=no' option when building MySQL. * If you are using `gcc' and have problems with loading user-defined functions (UDFs) into MySQL, try adding `-lgcc' to the link line for the UDF.  File: manual.info, Node: aix-installation-source, Next: hpux-installation-source, Prev: solaris-installation-source, Up: source-installation 2.11.9 Notes on Installing MySQL on AIX from Source --------------------------------------------------- General notes on building MySQL from source on IBM AIX: * Automatic `xlC' detection is missing from Autoconf, so a number of variables need to be set before running `configure'. The following example uses the IBM compiler: export CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 " export CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192" export CFLAGS="-I /usr/local/include" export LDFLAGS="-L /usr/local/lib" export CPPFLAGS=$CFLAGS export CXXFLAGS=$CFLAGS ./configure --prefix=/usr/local \ --localstatedir=/var/mysql \ --sbindir='/usr/local/bin' \ --libexecdir='/usr/local/bin' \ --enable-thread-safe-client \ --enable-large-files The preceding options are used to compile the MySQL distribution that can be found at `http://www-frec.bull.com/'. * If you change the `-O3' to `-O2' in the preceding `configure' line, you must also remove the `-qstrict' option. This is a limitation in the IBM C compiler. * If you compile MySQL with `gcc', you _must_ use the `-fno-exceptions' flag because the exception handling in `gcc' is not thread-safe. There are also some known problems with IBM's assembler that may cause it to generate bad code when used with `gcc'. * If you have problems with signals (MySQL dies unexpectedly under high load), you may have found an OS bug with threads and signals. In this case, you can tell MySQL not to use signals by configuring as follows: CFLAGS=-DDONT_USE_THR_ALARM CXX=gcc \ CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti \ -DDONT_USE_THR_ALARM" \ ./configure --prefix=/usr/local/mysql --with-debug \ --with-low-memory This does not affect the performance of MySQL, but has the side effect that you cannot kill clients that are `sleeping' on a connection with *Note `mysqladmin kill': mysqladmin. or *Note `mysqladmin shutdown': mysqladmin. Instead, the client dies when it issues its next command. * On some versions of AIX, linking with `libbind.a' makes `getservbyname()' dump core. This is an AIX bug and should be reported to IBM.  File: manual.info, Node: hpux-installation-source, Prev: aix-installation-source, Up: source-installation 2.11.10 Notes on Installing MySQL on HP-UX from Source ------------------------------------------------------ General notes on compiling MySQL on HP-UX. * If you are using HP-UX compiler, you can use the following command (which has been tested with `cc' B.11.11.04): CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure \ --with-extra-character-set=complex You can ignore any errors of the following type: aCC: warning 901: unknown option: `-3': use +help for online documentation * If you get the following error from `configure', verify that you do not have the path to the K&R compiler before the path to the HP-UX C and C++ compiler: checking for cc option to accept ANSI C... no configure: error: MySQL requires an ANSI C compiler (and a C++ compiler). Try gcc. See the Installation chapter in the Reference Manual. * Another reason for compile failure is that you did not define the `+DD64' flags as just described.  File: manual.info, Node: postinstallation, Next: upgrading-downgrading, Prev: source-installation, Up: installing 2.12 Postinstallation Setup and Testing ======================================= * Menu: * unix-postinstallation:: Unix Postinstallation Procedures * default-privileges:: Securing the Initial MySQL Accounts This section discusses post-installation items for Unix systems. If you are using Windows, see *Note windows-postinstallation::. After installing MySQL, there are some items that you should address. For example: * You should initialize the data directory and create the MySQL grant tables, as describe in *Note unix-postinstallation::. * An important security concern is that the initial accounts in the grant tables have no passwords. You should assign passwords to prevent unauthorized access to the MySQL server. For instructions, see *Note default-privileges::. * Optionally, you can create time zone tables to enable recognition of named time zones. For instructions, see *Note mysql-tzinfo-to-sql::. * If you have trouble getting the server to start, see *Note starting-server::. * When you are ready to create additional user accounts, you can find information on the MySQL access control system and account management in *Note privilege-system::, and *Note user-account-management::.  File: manual.info, Node: unix-postinstallation, Next: default-privileges, Prev: postinstallation, Up: postinstallation 2.12.1 Unix Postinstallation Procedures --------------------------------------- * Menu: * mysql-install-db-problems:: Problems Running `mysql_install_db' * automatic-start:: Starting and Stopping MySQL Automatically * starting-server:: Starting and Troubleshooting the MySQL Server After installing MySQL on Unix, you must initialize the grant tables, start the server, and make sure that the server works satisfactorily. You may also wish to arrange for the server to be started and stopped automatically when your system starts and stops. You should also assign passwords to the accounts in the grant tables. On Unix, the grant tables are set up by the *Note `mysql_install_db': mysql-install-db. program. For some installation methods, this program is run for you automatically if an existing database cannot be found. * If you install MySQL on Linux using RPM distributions, the server RPM runs *Note `mysql_install_db': mysql-install-db. * Using the native packaging system on many platforms, including Debian Linux, Ubuntu Linux, Gentoo Linux and others, the *Note `mysql_install_db': mysql-install-db. command is run for you. * If you install MySQL on Mac OS X using a DMG distribution, the installer runs *Note `mysql_install_db': mysql-install-db. For other platforms and installation types, including generic binary and source installs, you will need to run *Note `mysql_install_db': mysql-install-db. yourself. The following procedure describes how to initialize the grant tables (if that has not previously been done) and start the server. It also suggests some commands that you can use to test whether the server is accessible and working properly. For information about starting and stopping the server automatically, see *Note automatic-start::. After you complete the procedure and have the server running, you should assign passwords to the accounts created by *Note `mysql_install_db': mysql-install-db. and perhaps restrict access to test databases. For instructions, see *Note default-privileges::. In the examples shown here, the server runs 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 *Note binary-installation::. 1. Change location into the top-level directory of your MySQL installation, represented here by BASEDIR: shell> cd BASEDIR BASEDIR is the installation directory for your MySQL instance. It is likely to be something like `/usr/local/mysql' or `/usr/local'. The following steps assume that you have changed location to this directory. You will find several files and subdirectories in the BASEDIR directory. The most important for installation purposes are the `bin' and `scripts' subdirectories: * The `bin' directory contains client programs and the server. You should add the full path name of this directory to your `PATH' environment variable so that your shell finds the MySQL programs properly. See *Note environment-variables::. For some distribution types, *Note `mysqld': mysqld. is installed in the `libexec' directory. * The `scripts' directory contains the *Note `mysql_install_db': mysql-install-db. script used to initialize the `mysql' database containing the grant tables that store the server access permissions. For some distribution types, *Note `mysql_install_db': mysql-install-db. is installed in the `bin' directory. 2. If necessary, ensure that the distribution contents are accessible to `mysql'. If you installed the distribution as `mysql', no further action is required. If you installed the distribution as `root', its contents will be owned by `root'. Change its ownership to `mysql' by executing the following commands as `root' in the installation directory. The first command changes the owner attribute of the files to the `mysql' user. The second changes the group attribute to the `mysql' group. shell> chown -R mysql . shell> chgrp -R mysql . 3. If necessary, run the *Note `mysql_install_db': mysql-install-db. program to set up the initial MySQL grant tables containing the privileges that determine how users are permitted to connect to the server. You will need to do this if you used a distribution type for which the installation procedure does not run the program for you. Typically, *Note `mysql_install_db': mysql-install-db. needs to be run only the first time you install MySQL, so you can skip this step if you are upgrading an existing installation, However, *Note `mysql_install_db': mysql-install-db. does not overwrite any existing privilege tables, so it should be safe to run in any circumstances. The exact location of *Note `mysql_install_db': mysql-install-db. depends on the layout for your given installation. To initialize the grant tables, use one of the following commands, depending on whether *Note `mysql_install_db': mysql-install-db. is located in the `bin' or `scripts' directory: shell> scripts/mysql_install_db --user=mysql shell> bin/mysql_install_db --user=mysql It might be necessary to specify other options such as `--basedir' or `--datadir' if *Note `mysql_install_db': mysql-install-db. does not identify the correct locations for the installation directory or data directory. For example: shell> scripts/mysql_install_db --user=mysql \ --basedir=/opt/mysql/mysql \ --datadir=/opt/mysql/mysql/data The *Note `mysql_install_db': mysql-install-db. script creates the server's data directory with `mysql' as the owner. Under the data directory, it creates directories for the `mysql' database that holds the grant tables and the `test' database that you can use to test MySQL. The script also creates privilege table entries for `root' and anonymous-user accounts. The accounts have no passwords initially. *Note default-privileges::, describes the initial privileges. Briefly, these privileges permit the MySQL `root' user to do anything, and permit anybody to create or use databases with a name of `test' or starting with `test_'. See *Note privilege-system::, for a complete listing and description of the grant tables. 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 if you run *Note `mysql_install_db': mysql-install-db. as `root', include the `--user' option as shown. Otherwise, you should execute the script while logged in as `mysql', in which case you can omit the `--user' option from the command. If you do not want to have the `test' database, you can remove it after starting the server, using the instructions in *Note default-privileges::. If you have trouble with *Note `mysql_install_db': mysql-install-db. at this point, see *Note mysql-install-db-problems::. 4. Most of the MySQL installation can be owned by `root' if you like. The exception is that the data directory must be owned by `mysql'. To accomplish this, run the following commands as `root' in the installation directory. For some distribution types, the data directory might be named `var' rather than `data'; adjust the second command accordingly. shell> chown -R root . shell> chown -R mysql data 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 *Note `SELECT ... INTO DUMPFILE': select-into. This can be prevented by making `plugin_dir' read only to the server or by setting `--secure-file-priv' to a directory where *Note `SELECT': select. writes can be made safely. 6. If you installed MySQL using a source distribution, you may want to optionally copy one of the provided configuration files from the `support-files' directory into your `/etc' directory. There are different sample configuration files for different use cases, server types, and CPU and RAM configurations. If you want to use one of these standard files, you should copy it to `/etc/my.cnf', or `/etc/mysql/my.cnf' and edit and check the configuration before starting your MySQL server for the first time. If you do not copy one of the standard configuration files, the MySQL server will be started with the default settings. If you want MySQL to start automatically when you boot your machine, you can copy `support-files/mysql.server' to the location where your system has its startup files. More information can be found in the `mysql.server' script itself, and in *Note automatic-start::. 7. Start the MySQL server: shell> bin/mysqld_safe --user=mysql & It is important that the MySQL server be run using an unprivileged (non-`root') login account. To ensure this if you run *Note `mysqld_safe': mysqld-safe. as `root', include the `--user' option as shown. Otherwise, you should execute the script 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 *Note 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 you neglected to create the grant tables by running *Note `mysql_install_db': mysql-install-db. before proceeding to this step, the following message appears in the error log file when you start the server: mysqld: Can't find file: 'host.frm' This error also occurs if you run *Note `mysql_install_db': mysql-install-db. as `root' without the `--user' option. Remove the `data' directory and run *Note `mysql_install_db': mysql-install-db. with the `--user' option as described previously. If you have other problems starting the server, see *Note starting-server::. For more information about *Note `mysqld_safe': mysqld-safe, see *Note mysqld-safe::. 8. Use *Note `mysqladmin': 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 The output from *Note `mysqladmin version': mysqladmin. 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.1.73, for pc-linux-gnu on i686 ... Server version 5.1.73 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 *Note `mysqladmin': mysqladmin, invoke it with the `--help' option. 9. Verify that you can shut down the server: shell> bin/mysqladmin -u root shutdown 10. Verify that you can start the server again. Do this by using *Note `mysqld_safe': mysqld-safe. or by invoking *Note `mysqld': mysqld. directly. For example: shell> bin/mysqld_safe --user=mysql & If *Note `mysqld_safe': mysqld-safe. fails, see *Note starting-server::. 11. Run some simple tests to verify that you can retrieve information from the server. The output should be similar to what is shown here: shell> bin/mysqlshow +--------------------+ | Databases | +--------------------+ | information_schema | | mysql | | test | +--------------------+ shell> bin/mysqlshow mysql Database: mysql +---------------------------+ | Tables | +---------------------------+ | columns_priv | | db | | event | | func | | help_category | | help_keyword | | help_relation | | help_topic | | host | | plugin | | proc | | procs_priv | | servers | | tables_priv | | time_zone | | time_zone_leap_second | | time_zone_name | | time_zone_transition | | time_zone_transition_type | | user | +---------------------------+ shell> bin/mysql -e "SELECT Host,Db,User FROM db" mysql +------+--------+------+ | host | db | user | +------+--------+------+ | % | test | | | % | test_% | | +------+--------+------+ 12. There is a benchmark suite in the `sql-bench' directory (under the MySQL installation directory) that you can use to compare how MySQL performs on different platforms. The benchmark suite is written in Perl. It requires the Perl DBI module that provides a database-independent interface to the various databases, and some other additional Perl modules: DBI DBD::mysql Data::Dumper Data::ShowTable These modules can be obtained from CPAN (`http://www.cpan.org/'). See also *Note perl-installation::. The `sql-bench/Results' directory contains the results from many runs against different databases and platforms. To run all tests, execute these commands: shell> cd sql-bench shell> perl run-all-tests If you do not have the `sql-bench' directory, you probably installed MySQL using RPM files other than the source RPM. (The source RPM includes the `sql-bench' benchmark directory.) In this case, you must first install the benchmark suite before you can use it. There are separate benchmark RPM files named `mysql-bench-VERSION.i386.rpm' that contain benchmark code and data. If you have a source distribution, there are also tests in its `tests' subdirectory that you can run. For example, to run `auto_increment.tst', execute this command from the top-level directory of your source distribution: shell> mysql -vvf test < ./tests/auto_increment.tst The expected result of the test can be found in the `./tests/auto_increment.res' file. 13. At this point, you should have the server running. However, none of the initial MySQL accounts have a password, and the server permits permissive access to test databases. To tighten security, follow the instructions in *Note default-privileges::. The MySQL 5.1 installation procedure creates time zone tables in the `mysql' database but does not populate them. To do so, use the instructions in *Note time-zone-support::. To make it more convenient to invoke programs installed in the `bin' directory under the installation directory, you can add that directory to your `PATH' environment variable setting. That enables you to run a program by typing only its name, not its entire path name. See *Note setting-environment-variables::. You can set up new accounts using the `bin/mysql_setpermission' script if you install the `DBI' and `DBD::mysql' Perl modules. See *Note mysql-setpermission::. For Perl module installation instructions, see *Note perl-support::. If you would like to use *Note `mysqlaccess': mysqlaccess. and have the MySQL distribution in some nonstandard location, you must change the location where *Note `mysqlaccess': mysqlaccess. expects to find the *Note `mysql': mysql. client. Edit the `bin/mysqlaccess' script at approximately line 18. Search for a line that looks like this: $MYSQL = '/usr/local/bin/mysql'; # path to mysql executable Change the path to reflect the location where *Note `mysql': mysql. actually is stored on your system. If you do not do this, a `Broken pipe' error will occur when you run *Note `mysqlaccess': mysqlaccess.  File: manual.info, Node: mysql-install-db-problems, Next: automatic-start, Prev: unix-postinstallation, Up: unix-postinstallation 2.12.1.1 Problems Running `mysql_install_db' ............................................ The purpose of the *Note `mysql_install_db': mysql-install-db. script is to generate new MySQL privilege tables. It does not overwrite existing MySQL privilege tables, and it does not affect any other data. If you want to re-create your privilege tables, first stop the *Note `mysqld': mysqld. server if it is running. Then rename the `mysql' directory under the data directory to save it, and then run *Note `mysql_install_db': mysql-install-db. Suppose that your current directory is the MySQL installation directory and that *Note `mysql_install_db': mysql-install-db. is located in the `bin' directory and the data directory is named `data'. To rename the `mysql' database and re-run *Note `mysql_install_db': mysql-install-db, use these commands. shell> mv data/mysql data/mysql.old shell> scripts/mysql_install_db --user=mysql When you run *Note `mysql_install_db': mysql-install-db, you might encounter the following problems: * **Note `mysql_install_db': mysql-install-db. fails to install the grant tables* You may find that *Note `mysql_install_db': 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 *Note `mysqld': mysqld. did not start. If you do not understand what happened, include the log when you post a bug report. See *Note bug-reports::. * *There is a *Note `mysqld': 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 *Note `mysql_install_db': mysql-install-db. at all because it needs to be run only once (when you install MySQL the first time). * *Installing a second *Note `mysqld': 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 *Note 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 `TMP_DIR' environment variable, if it has been set, an error occurs when you run *Note `mysql_install_db': mysql-install-db. or the *Note `mysqld': mysqld. server. You can specify different locations for the temporary directory and Unix socket file by executing these commands prior to starting *Note `mysql_install_db': mysql-install-db. or *Note `mysqld': 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 *Note `mysql_install_db': mysql-install-db. and start the server with these commands: shell> scripts/mysql_install_db --user=mysql shell> bin/mysqld_safe --user=mysql & If *Note `mysql_install_db': mysql-install-db. is located in the `bin' directory, modify the first command to `bin/mysql_install_db'. See *Note problems-with-mysql-sock::, and *Note environment-variables::. There are some alternatives to running the *Note `mysql_install_db': mysql-install-db. script provided in the MySQL distribution: * If you want the initial privileges to be different from the standard defaults, you can modify *Note `mysql_install_db': mysql-install-db. before you run it. However, it is preferable to use *Note `GRANT': grant. and *Note `REVOKE': revoke. to change the privileges _after_ the grant tables have been set up. In other words, you can run *Note `mysql_install_db': 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 *Note `GRANT': grant. and *Note `REVOKE': revoke. statements. If you want to install MySQL on several machines with the same privileges, you can put the *Note `GRANT': grant. and *Note `REVOKE': revoke. statements in a file and execute the file as a script using `mysql' after running *Note `mysql_install_db': mysql-install-db. For example: shell> scripts/mysql_install_db --user=mysql shell> bin/mysql -u root < your_script_file By doing this, you can avoid having to issue 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 *Note `GRANT': grant. and *Note `REVOKE': revoke. and have made so many modifications after running *Note `mysql_install_db': mysql-install-db. that you want to wipe out the tables and start over. To re-create the grant tables, remove all the `.frm', `.MYI', and `.MYD' files in the `mysql' database directory. Then run the *Note `mysql_install_db': mysql-install-db. script again. * You can start *Note `mysqld': mysqld. manually using the `--skip-grant-tables' option and add the privilege information yourself using *Note `mysql': mysql.: shell> bin/mysqld_safe --user=mysql --skip-grant-tables & shell> bin/mysql mysql From *Note `mysql': mysql, manually execute the SQL commands contained in *Note `mysql_install_db': mysql-install-db. Make sure that you run *Note `mysqladmin flush-privileges': mysqladmin. or *Note `mysqladmin reload': mysqladmin. afterward to tell the server to reload the grant tables. Note that by not using *Note `mysql_install_db': mysql-install-db, you not only have to populate the grant tables manually, you also have to create them first.  File: manual.info, Node: automatic-start, Next: starting-server, Prev: mysql-install-db-problems, Up: unix-postinstallation 2.12.1.2 Starting and Stopping MySQL Automatically .................................................. Generally, you start the *Note `mysqld': mysqld. server in one of these ways: * Invoke *Note `mysqld': mysqld. directly. This works on any platform. * Invoke *Note `mysqld_safe': mysqld-safe, which tries to determine the proper options for *Note `mysqld': mysqld. and then runs it with those options. This script is used on Unix and Unix-like systems. See *Note mysqld-safe::. * Invoke *Note `mysql.server': mysql-server. This script is used primarily at system startup and shutdown on systems that use System V-style run directories (that is, `/etc/init.d' and run-level specific directories), where it usually is installed under the name `mysql'. The *Note `mysql.server': mysql-server. script starts the server by invoking *Note `mysqld_safe': mysqld-safe. See *Note mysql-server::. * On Mac OS X, install a separate MySQL Startup Item package to enable the automatic startup of MySQL on system startup. The Startup Item starts the server by invoking *Note `mysql.server': mysql-server. See *Note macosx-installation-startupitem::, for details. A MySQL Preference Pane also provides control for starting and stopping MySQL through the System Preferences, see *Note macosx-installation-prefpane::. * Use the Solaris/OpenSolaris service management framework (SMF) system to initiate and control MySQL startup. For more information, see *Note solaris-installation-opensolaris::. The *Note `mysqld_safe': mysqld-safe. and *Note `mysql.server': mysql-server. scripts, Solaris/OpenSolaris SMF, and the Mac OS X Startup Item (or MySQL Preference Pane) can be used to start the server manually, or automatically at system startup time. *Note `mysql.server': mysql-server. and the Startup Item also can be used to stop the server. To start or stop the server manually using the *Note `mysql.server': mysql-server. script, invoke it with `start' or `stop' arguments: shell> mysql.server start shell> mysql.server stop Before *Note `mysql.server': mysql-server. starts the server, it changes location to the MySQL installation directory, and then invokes *Note `mysqld_safe': mysqld-safe. If you want the server to run as some specific user, add an appropriate `user' option to the `[mysqld]' group of the `/etc/my.cnf' option file, as shown later in this section. (It is possible that you will need to edit *Note `mysql.server': 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 *Note `mysqld_safe': mysqld-safe. If you do this, your modified version of *Note `mysql.server': mysql-server. may be overwritten if you upgrade MySQL in the future, so you should make a copy of your edited version that you can reinstall.) *Note `mysql.server stop': mysql-server. stops the server by sending a signal to it. You can also stop the server manually by executing *Note `mysqladmin shutdown': mysqladmin. To start and stop MySQL automatically on your server, you need to 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 *Note `mysql.server': mysql-server. script may be installed in the `/etc/init.d' directory with the name `mysql'. See *Note linux-installation-rpm::, for more information on the Linux RPM packages. Some vendors provide RPM packages that install a startup script under a different name such as *Note `mysqld': mysqld. If you install MySQL from a source distribution or using a binary distribution format that does not install *Note `mysql.server': mysql-server. automatically, you can install it manually. The script can be found in the `support-files' directory under the MySQL installation directory or in a MySQL source tree. To install *Note `mysql.server': mysql-server. manually, copy it to the `/etc/init.d' directory with the name *Note `mysql': mysql, and then make it executable. Do this by changing location into the appropriate directory where *Note `mysql.server': mysql-server. is located and executing these commands: shell> cp mysql.server /etc/init.d/mysql shell> chmod +x /etc/init.d/mysql *Note*: Older Red Hat systems use the `/etc/rc.d/init.d' directory rather than `/etc/init.d'. Adjust the preceding commands accordingly. Alternatively, first create `/etc/init.d' as a symbolic link that points to `/etc/rc.d/init.d': shell> cd /etc shell> ln -s rc.d/init.d . 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 *Note `mysql': mysql. script: shell> chkconfig --level 345 mysql on On FreeBSD, startup scripts generally should go in `/usr/local/etc/rc.d/'. The `rc(8)' manual page states that scripts in this directory are executed only if their basename matches the `*.sh' shell file name pattern. Any other files or directories present within the directory are silently ignored. In other words, on FreeBSD, you should install the `mysql.server' script as `/usr/local/etc/rc.d/mysql.server.sh' to enable automatic startup. 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, you could 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. You can add options for *Note `mysql.server': mysql-server. in a global `/etc/my.cnf' file. A typical `/etc/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 *Note `mysql.server': mysql-server. script supports the following options: `basedir', `datadir', and `pid-file'. If specified, they _must_ be placed in an option file, not on the command line. *Note `mysql.server': mysql-server. supports only `start' and `stop' as command-line arguments. The following table shows which option groups the server and each startup script read from option files. *MySQL Startup scripts and supported server option groups* Script Option Groups *Note `[mysqld]', `[server]', `[mysqld-MAJOR_VERSION]' `mysqld': mysqld. *Note `[mysqld]', `[server]', `[mysqld_safe]' `mysqld_safe': mysqld-safe. *Note `[mysqld]', `[mysql.server]', `[server]' `mysql.server': mysql-server. `[mysqld-MAJOR_VERSION]' means that groups with names like `[mysqld-5.0]' and `[mysqld-5.1]' are read by servers having versions 5.0.x, 5.1.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, *Note `mysql.server': mysql-server. also reads the `[mysql_server]' group and *Note `mysqld_safe': mysqld-safe. also reads the `[safe_mysqld]' group. However, you should update your option files to use the `[mysql.server]' and `[mysqld_safe]' groups instead when using MySQL 5.1. For more information on MySQL configuration files and their structure and contents, see *Note option-files::.  File: manual.info, Node: starting-server, Prev: automatic-start, Up: unix-postinstallation 2.12.1.3 Starting and Troubleshooting the MySQL Server ...................................................... This section provides troubleshooting suggestions for problems starting the server on Unix. If you are using Windows, see *Note 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. * Specify any special options needed by the storage engines you are using. * Make sure that the server knows where to find the data directory. * Make sure that the server can access the data directory. The ownership and permissions of the data directory and its contents must be set such that the server can read and modify them. * Verify that the network interfaces the server wants to use are available. Some storage engines have options that control their behavior. 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', *Note `NDB': mysql-cluster.), be sure that you have them configured the way you want before starting the server: If you are using `InnoDB' tables, see *Note innodb-configuration::. If you are using MySQL Cluster, see *Note mysql-cluster-configuration::. Storage engines will use default option values if you specify none, but it is recommended that you review the available options and specify explicit values for those for which the defaults are not appropriate for your installation. When the *Note `mysqld': mysqld. server starts, it changes location to the data 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 data directory location is hardwired in when the server is compiled. This is where the server looks for the data directory by default. If the data directory is located somewhere else on your system, the server will not work properly. You can determine what the default path settings are by invoking *Note `mysqld': mysqld. with the `--verbose' and `--help' options. If the default locations do not match the MySQL installation layout on your system, you can override them by specifying options to *Note `mysqld': mysqld. or *Note `mysqld_safe': mysqld-safe. on the command line or in an option file. To specify the location of the data directory explicitly, use the `--datadir' option. However, normally you can tell *Note `mysqld': mysqld. the location of the base directory under which MySQL is installed and it looks for the data directory there. You can do this with the `--basedir' option. To check the effect of specifying path options, invoke *Note `mysqld': mysqld. with those options followed by the `--verbose' and `--help' options. For example, if you change location into the directory where *Note `mysqld': 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 *Note `mysqld': 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. If you get `Errcode 13' (which means `Permission denied') when starting *Note `mysqld': 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. On Unix, 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 If it possible that even with correct ownership, MySQL may 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, you may need to reconfigure that software to enable *Note `mysqld': mysqld. to access the directories it uses during normal operation. If the server fails to start up correctly, check the error log. Log files are located in the data directory (typically `C:\Program Files\MySQL\MySQL Server 5.1\data' on Windows, `/usr/local/mysql/data' for a Unix binary distribution, and `/usr/local/var' for a Unix 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. On Unix, you can use `tail' to display them: shell> tail HOST_NAME.err shell> tail HOST_NAME.log The error log should contain information that indicates why the server could not start. If either of the following errors occur, it means that some other program (perhaps another *Note `mysqld': mysqld. server) is using the TCP/IP port or Unix socket file that *Note `mysqld': 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 *Note `mysqld': mysqld. server running. If so, shut down the server before starting *Note `mysqld': 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 *Note multiple-servers::.) If no other server is running, try to 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 *Note `mysqld': mysqld. is trying to use. You will need to track down what program this is and disable it, or else tell *Note `mysqld': mysqld. to listen to a different port with the `--port' option. In this case, you will also need to specify the 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, you should make sure that you have an entry in `/etc/hosts' that looks like this: 127.0.0.1 localhost If you cannot get *Note `mysqld': mysqld. to start, you can try to make a trace file to find the problem by using the `--debug' option. See *Note dbug-package::.  File: manual.info, Node: default-privileges, Prev: unix-postinstallation, Up: postinstallation 2.12.2 Securing the Initial MySQL Accounts ------------------------------------------ Part of the MySQL installation process is to set up the `mysql' database that contains the grant tables: * Windows distributions contain preinitialized grant tables. * On Unix, the *Note `mysql_install_db': mysql-install-db. program populates the grant tables. Some installation methods run this program for you. Others require that you execute it manually. For details, see *Note unix-postinstallation::. The `mysql.user' grant table defines the initial MySQL user accounts and their access privileges: * Some accounts have the user name `root'. These are superuser accounts that have all privileges and can do anything. The initial `root' account passwords are empty, so 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' or the IP address `127.0.0.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', or the actual host name or IP address. 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 the `127.0.0.1' account is useful in that case. * Some accounts are for anonymous users. 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'. The account has no global privileges. (Before MySQL 5.1.16, it has all global privileges, just like the `root' accounts.) * 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. To display which accounts exist in the `mysql.user' table and check whether their passwords are empty, use the following statement: mysql> SELECT User, Host, Password FROM mysql.user; +------+--------------------+----------+ | User | Host | Password | +------+--------------------+----------+ | root | localhost | | | root | myhost.example.com | | | root | 127.0.0.1 | | | | localhost | | | | myhost.example.com | | +------+--------------------+----------+ This output indicates that there are several `root' and anonymous-user accounts, none of which have passwords. The output might differ on your system, but the presence of accounts with empty passwords means that your MySQL installation is unprotected until you do something about it: * You should assign a password to each MySQL `root' account. * If you want to prevent clients from connecting as anonymous users without a password, you should either assign a password to each anonymous account or else remove the accounts. In addition, the `mysql.db' table contains rows that permit all accounts to access the `test' 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 the `root' accounts, then for the anonymous accounts. The instructions also cover how to remove the anonymous accounts, should you prefer not to permit anonymous access at all, and describe how to remove permissive access to test databases. Replace NEWPWD 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 preceding *Note `SELECT': select. statement. For the output shown, HOST_NAME is `myhost.example.com'. *Note*: For additional information about setting passwords, see *Note assigning-passwords::. If you forget your `root' password after setting it, see *Note resetting-permissions::. 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. To set up additional accounts, see *Note adding-users::. * Assigning `root' Account Passwords * The `root' account passwords can be set several ways. The following discussion demonstrates three methods: * Use the *Note `SET PASSWORD': set-password. statement * Use the *Note `UPDATE': update. statement * Use the *Note `mysqladmin': mysqladmin. command-line client program To assign passwords using *Note `SET PASSWORD': set-password, connect to the server as `root' and issue a *Note `SET PASSWORD': set-password. statement for each `root' account listed in the `mysql.user' table. Be sure to encrypt the password using the `PASSWORD()' function. For Windows, do this: shell> mysql -u root mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('NEWPWD'); mysql> SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('NEWPWD'); mysql> SET PASSWORD FOR 'root'@'%' = PASSWORD('NEWPWD'); The last statement is unnecessary if the `mysql.user' table has no `root' account with a host value of `%'. For Unix, do this: shell> mysql -u root mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('NEWPWD'); mysql> SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('NEWPWD'); mysql> SET PASSWORD FOR 'root'@'HOST_NAME' = PASSWORD('NEWPWD'); You can also use a single statement that assigns a password to all `root' accounts by using *Note `UPDATE': update. to modify the `mysql.user' table directly. This method works on any platform: shell> mysql -u root mysql> UPDATE mysql.user SET Password = PASSWORD('NEWPWD') -> WHERE User = 'root'; mysql> FLUSH PRIVILEGES; The *Note `FLUSH': flush. statement causes the server to reread the grant tables. Without it, the password change remains unnoticed by the server until you restart it. To assign passwords to the `root' accounts using *Note `mysqladmin': mysqladmin, execute the following commands: shell> mysqladmin -u root password "NEWPWD" shell> mysqladmin -u root -h HOST_NAME password "NEWPWD" Those commands apply both to Windows and to Unix. The double quotation marks around the password are not always necessary, but you should use them if the password contains spaces or other characters that are special to your command interpreter. The *Note `mysqladmin': mysqladmin. method of setting the `root' account passwords does not work for the `'root'@'127.0.0.1'' account. Use the *Note `SET PASSWORD': set-password. method shown earlier. After the `root' passwords have been set, you must supply the appropriate password whenever you connect as `root' to the server. For example, to shut down the server with *Note `mysqladmin': mysqladmin, use this command: shell> mysqladmin -u root -p shutdown Enter password: (ENTER ROOT PASSWORD HERE) * Assigning Anonymous Account Passwords * The *Note `mysql': mysql. commands in the following instructions include a `-p' option based on the assumption that you have set the `root' account passwords using the preceding instructions and must specify that password when connecting to the server. To assign passwords to the anonymous accounts, connect to the server as `root', then use either *Note `SET PASSWORD': set-password. or *Note `UPDATE': update. Be sure to encrypt the password using the `PASSWORD()' function. To use *Note `SET PASSWORD': set-password. on Windows, do this: shell> mysql -u root -p Enter password: (ENTER ROOT PASSWORD HERE) mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('NEWPWD'); To use *Note `SET PASSWORD': set-password. on Unix, do this: shell> mysql -u root -p Enter password: (ENTER ROOT PASSWORD HERE) mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('NEWPWD'); mysql> SET PASSWORD FOR ''@'HOST_NAME' = PASSWORD('NEWPWD'); To set the anonymous-user account passwords with a single *Note `UPDATE': update. statement, do this (on any platform): shell> mysql -u root -p Enter password: (ENTER ROOT PASSWORD HERE) mysql> UPDATE mysql.user SET Password = PASSWORD('NEWPWD') -> WHERE User = ''; mysql> FLUSH PRIVILEGES; The *Note `FLUSH': flush. statement causes the server to reread the grant tables. Without it, the password change remains unnoticed by the server until you restart it. * Removing Anonymous Accounts * If you prefer to remove any anonymous accounts rather than assigning them passwords, do so as follows on Windows: shell> mysql -u root -p Enter password: (ENTER ROOT PASSWORD HERE) mysql> DROP USER ''@'localhost'; On Unix, remove the anonymous accounts like this: shell> mysql -u root -p Enter password: (ENTER ROOT PASSWORD HERE) mysql> DROP USER ''@'localhost'; mysql> DROP USER ''@'HOST_NAME'; * Securing Test Databases * By default, the `mysql.db' table contains 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 *Note `FLUSH': 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 do not want the database to exist at all, drop it: mysql> DROP DATABASE test; *Note*: On Windows, you can also perform the process described in this section using the Configuration Wizard (see *Note mysql-config-wizard-security::). On all platforms, the MySQL distribution includes *Note `mysql_secure_installation': mysql-secure-installation, a command-line utility that automates much of the process of securing a MySQL installation.  File: manual.info, Node: upgrading-downgrading, Next: environment-variables, Prev: postinstallation, Up: installing 2.13 Upgrading or Downgrading MySQL =================================== * Menu: * upgrading:: Upgrading MySQL * downgrading:: Downgrading MySQL * checking-table-incompatibilities:: Checking Whether Tables or Indexes Must Be Rebuilt * rebuilding-tables:: Rebuilding or Repairing Tables or Indexes * copying-databases:: Copying MySQL Databases to Another Machine  File: manual.info, Node: upgrading, Next: downgrading, Prev: upgrading-downgrading, Up: upgrading-downgrading 2.13.1 Upgrading MySQL ---------------------- * Menu: * upgrading-from-previous-series:: Upgrading from MySQL 5.0 to 5.1 As a general rule, to upgrade from one release series to another, go to the next series rather than skipping a series. To upgrade from a release series previous to MySQL 5.0, upgrade to each successive release series in turn until you have reached MySQL 5.0, and then proceed with the upgrade to MySQL 5.1. For example, if you currently are running MySQL 4.1 and wish to upgrade to a newer series, upgrade to MySQL 5.0 first before upgrading to 5.1, and so forth. For information on upgrading to MySQL 5.0, see the `MySQL 5.0 Reference Manual'; for earlier releases, see the `MySQL 3.23, 4.0, 4.1 Reference Manual'. If you perform a binary (in-place) upgrade without dumping and reloading tables, you cannot upgrade directly from MySQL 4.1 to 5.1. This occurs due to an incompatible change in the `MyISAM' table index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and repair all `MyISAM' tables (see *Note rebuilding-tables::). Then upgrade from MySQL 5.0 to 5.1 and check and repair your tables. To upgrade from MySQL 5.0 to 5.1, use the items in the following checklist as a guide: * Before any upgrade, back up your databases, including the `mysql' database that contains the grant tables. See *Note backup-methods::. * Read _all_ the notes in *Note upgrading-from-previous-series::. These notes enable you to identify upgrade issues that apply to your current MySQL installation. Some incompatibilities discussed in that section require your attention _before_ upgrading. Others should be dealt with _after_ upgrading. * Read the Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/) as well, which provide information about features that are new in MySQL 5.1 or differ from those found in MySQL 5.0. * After upgrading to a new version of MySQL, run *Note `mysql_upgrade': mysql-upgrade. (see *Note mysql-upgrade::). This program checks your tables, and attempts to repair them if necessary. It also updates your grant tables to make sure that they have the current structure so that you can take advantage of any new capabilities. (Some releases of MySQL introduce changes to the structure of the grant tables to add new privileges or features.) *Note `mysql_upgrade': mysql-upgrade. does not upgrade the contents of the help tables. For upgrade instructions, see *Note server-side-help-support::. * If you run MySQL Server on Windows, see *Note windows-upgrading::. * If you use replication, see *Note replication-upgrade::, for information on upgrading your replication setup. * If you use `InnoDB', consider setting `innodb_fast_shutdown' to 0 before shutting down and upgrading your server. When you set `innodb_fast_shutdown' to 0, `InnoDB' does a slow shutdown, a full purge and an insert buffer merge before shutting down, which ensures that all data files are fully prepared in case the upgrade process modifies the file format. * If you upgrade an installation originally produced by installing multiple RPM packages, it is best to 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. * As of MySQL 5.1.9, the `mysqld-max' server is included in binary distributions. There is no separate MySQL-Max distribution. As of MySQL 5.1.12, there is no `mysqld-max' server at all in binary distributions. They contain a server that includes the features previously included in `mysqld-max'. * 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 *Note `DROP FUNCTION': drop-function. to drop the UDF, and then use *Note `CREATE FUNCTION': 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 *Note function-resolution::, for the rules describing how the server interprets references to different kinds of functions. For upgrades between versions of a MySQL release series that has reached General Availability status, you can move the MySQL format files and data files between different versions on systems with the same architecture. For upgrades to a version of a MySQL release series that is in development status, that is not necessarily true. Use of development releases is at your own risk. If you are cautious about using new versions, you can always rename your old *Note `mysqld': mysqld. before installing a newer one. For example, if you are using a version of MySQL 5.0 and want to upgrade to 5.1, rename your current server from *Note `mysqld': mysqld. to `mysqld-5.0'. If your new *Note `mysqld': mysqld. then does something unexpected, you can simply shut it down and restart with your old *Note `mysqld': mysqld. If problems occur, such as that the new *Note `mysqld': mysqld. server does not start or that you cannot connect without a password, 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, *Note `mysqld --print-defaults': mysqld.). 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, you should 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 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. It is a good idea to rebuild and reinstall the Perl `DBD::mysql' module whenever you install a new release of MySQL. The same applies to other MySQL interfaces as well, such as PHP `mysql' extensions and the Python `MySQLdb' module.  File: manual.info, Node: upgrading-from-previous-series, Prev: upgrading, Up: upgrading 2.13.1.1 Upgrading from MySQL 5.0 to 5.1 ........................................ *After upgrading a 5.0 installation to 5.0.10 or above*, it is _necessary_ to upgrade your grant tables. Otherwise, creating stored procedures and functions might not work. To perform this upgrade, run *Note `mysql_upgrade': mysql-upgrade. *Note*: It is good practice to back up your data before installing any new version of software. Although MySQL works very hard to ensure a high level of quality, you should protect your data by making a backup. To upgrade to 5.1 from any previous version, MySQL recommends that you dump your tables with *Note `mysqldump': mysqldump. before upgrading and reload the dump file after upgrading. Use the `--all-databases' option to include all databases in the dump. If your databases include stored programs, use the `--routines' and `--events' options as well. If you perform a binary (in-place) upgrade without dumping and reloading tables, you cannot upgrade directly from MySQL 4.1 to 5.1. This occurs due to an incompatible change in the `MyISAM' table index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and repair all `MyISAM' tables (see *Note rebuilding-tables::). Then upgrade from MySQL 5.0 to 5.1 and check and repair your tables. In general, you should do the following when upgrading from MySQL 5.0 to 5.1: * Read _all_ the items in these sections to see whether any of them might affect your applications: * *Note upgrading::, has general update information. * The items in the change lists provided later in this section enable you to identify upgrade issues that apply to your current MySQL installation. Some incompatibilities discussed there require your attention _before_ upgrading. Others should be dealt with _after_ upgrading. * The MySQL 5.1 Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/) describe significant new features you can use in 5.1 or that differ from those found in MySQL 5.0. Some of these changes may result in incompatibilities. Note particularly any changes that are marked *Known issue* or *Incompatible change*. These incompatibilities with earlier versions of MySQL 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 *Note `CHECK TABLE': check-table. or *Note `REPAIR TABLE': repair-table. For dump and reload instructions, see *Note rebuilding-tables::. Any procedure that involves *Note `REPAIR TABLE': 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 *Note repair-table::. * Before upgrading to a new version of MySQL, *Note checking-table-incompatibilities::, to see whether changes to table formats or to character sets or collations were made between your current version of MySQL and the version to which you are upgrading. If so and these changes result in an incompatibility between MySQL versions, you will need to upgrade the affected tables using the instructions in *Note rebuilding-tables::. * After upgrading to a new version of MySQL, run *Note `mysql_upgrade': mysql-upgrade. (see *Note mysql-upgrade::). This program checks your tables, and attempts to repair them if necessary. It also updates your grant tables to make sure that they have the current structure so that you can take advantage of any new capabilities. (Some releases of MySQL introduce changes to the structure of the grant tables to add new privileges or features.) *Note `mysql_upgrade': mysql-upgrade. does not upgrade the contents of the help tables. For upgrade instructions, see *Note server-side-help-support::. * If you run MySQL Server on Windows, see *Note windows-upgrading::. * If you use replication, see *Note replication-upgrade::, for information on upgrading your replication setup. 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. The following lists describe changes that may affect applications and that you should watch out for when upgrading from MySQL 5.0 to 5.1. * Configuration Changes * * Before MySQL 5.1.11, to build MySQL from source with SSL support enabled, you would invoke `configure' with either the `--with-openssl' or `--with-yassl' option. In MySQL 5.1.11, those options both have been replaced by the `--with-ssl' option. By default, `--with-ssl' causes the bundled yaSSL library to be used. To select OpenSSL instead, give the option as `--with-ssl=PATH', where PATH is the directory where the OpenSSL header files and libraries are located. * Server Changes * * *Known issue*: As of MySQL 5.1.70, for new installations, the `url' columns in the `mysql' datatbase help tables are now created as type *Note `TEXT': blob. to accommodate longer URLs. For upgrades, *Note `mysql_upgrade': mysql-upgrade. does _not_ update the columns. Modify them manually using these statements: ALTER TABLE mysql.help_category MODIFY url TEXT NOT NULL; ALTER TABLE mysql.help_topic MODIFY url TEXT NOT NULL; * *Known issue*: *Note `mysql_upgrade': mysql-upgrade. attempts to to upgrade tables that are incompatible with the current version of MySQL. (It invokes *Note `mysqlcheck': mysqlcheck. to check tables and, if necessary, repair them.) However this can fail for storage engines that do not support REPAIR TABLE, such as *Note `InnoDB': innodb-storage-engine, and leave tables in a nonupgradable state. To work around this problem, use *Note `ALTER TABLE TBL_NAME ENGINE=InnoDB': alter-table. to perform a `null' alter operation that rebuilds the table. * *Known issue*: After a binary upgrade to MySQL 5.1 from a MySQL 5.0 installation that contains *Note `ARCHIVE': archive-storage-engine. tables: * Before MySQL 5.1.42, accessing those tables will cause the server to crash, even if you have run *Note `mysql_upgrade': mysql-upgrade. or *Note `CHECK TABLE ... FOR UPGRADE': check-table. * As of MySQL 5.1.42, the server will not open 5.0 *Note `ARCHIVE': archive-storage-engine. tables at all. In either case, the solution is to use *Note `mysqldump': mysqldump. to dump all 5.0 *Note `ARCHIVE': archive-storage-engine. tables before upgrading, and reload them into MySQL 5.1 after upgrading. This problem is fixed in MySQL 5.6.4: The server can open *Note `ARCHIVE': archive-storage-engine. tables created in MySQL 5.0. However, it remains the recommended upgrade procedure to dump 5.0 *Note `ARCHIVE': archive-storage-engine. tables before upgrading and reload them after upgrading. * *Known issue*: The fix for Bug #23491 introduced a problem with *Note `SHOW CREATE VIEW': show-create-view, which is used by *Note `mysqldump': mysqldump. This causes an incompatibility when upgrading from versions affected by that bug fix (MySQL 5.0.40 through 5.0.43, MySQL 5.1.18 through 5.1.19): If you use *Note `mysqldump': mysqldump. before upgrading from an affected version and reload the data after upgrading to a higher version, you must drop and recreate your views. * *Known issue*: Dumps performed by using *Note `mysqldump': mysqldump. to generate a dump file before the upgrade and reloading the file after upgrading are subject to the following problem: Before MySQL 5.0.40, *Note `mysqldump': mysqldump. displays `SPATIAL' index definitions using prefix lengths for the indexed columns. These prefix lengths are accepted in MySQL 5.0, but not as of MySQL 5.1. If you use *Note `mysqldump': mysqldump. from versions of MySQL older than 5.0.40, any table containing `SPATIAL' indexes will cause an error when the dump file is reloaded into MySQL 5.1 or higher. For example, a table definition might look like this when dumped in MySQL 5.0: CREATE TABLE `t` ( `g` geometry NOT NULL, SPATIAL KEY `g` (`g`(32)) ) ENGINE=MyISAM DEFAULT CHARSET=latin1 The `SPATIAL' index definition will not be accepted in MySQL 5.1. To work around this, edit the dump file to remove the prefix: CREATE TABLE `t` ( `g` geometry NOT NULL, SPATIAL KEY `g` (`g`) ) ENGINE=MyISAM DEFAULT CHARSET=latin1 Dump files can be large, so it may be preferable to dump table definitions and data separately to make it easier to edit the definitions: shell> mysqldump --no-data OTHER_ARGS > definitions.sql shell> mysqldump --no-create-info OTHER_ARGS > data.sql Then edit `definitions.sql' before reloading `definitions.sql' and `data.sql', in that order. If you upgrade to a version of MySQL 5.0 higher than 5.0.40 before upgrading to MySQL 5.1, this problem does not occur. * *Known issue*: Before MySQL 5.1.30, the *Note `CHECK TABLE ... FOR UPGRADE': check-table. statement did not check for incompatible collation changes made in MySQL 5.1.24. (This also affects *Note `mysqlcheck': mysqlcheck. and *Note `mysql_upgrade': mysql-upgrade, which cause that statement to be executed.) Prior to the fix made in 5.1.30, a binary upgrade (performed without dumping tables with *Note `mysqldump': mysqldump. before the upgrade and reloading the dump file after the upgrade) would corrupt tables. After the fix, *Note `CHECK TABLE ... FOR UPGRADE': check-table. properly detects the problem and warns about tables that need repair. However, the fix is not backward compatible and can result in a downgrading problem under these circumstances: 1. Perform a binary upgrade to a version of MySQL that includes the fix. 2. Run *Note `CHECK TABLE ... FOR UPGRADE': check-table. (or *Note `mysqlcheck': mysqlcheck. or *Note `mysql_upgrade': mysql-upgrade.) to upgrade tables. 3. Perform a binary downgrade to a version of MySQL that does not include the fix. The solution is to dump tables with *Note `mysqldump': mysqldump. before the downgrade and reload the dump file after the downgrade. Alternatively, drop and recreate affected indexes. * *Known issue*: MySQL introduces encoding for table names that have non-ASCII characters (see *Note identifier-mapping::). After a binary upgrade from MySQL 5.0 to 5.1 or higher, the server recognizes names that have non-ASCII characters and adds a `#mysql50#' prefix to them. As of MySQL 5.1.31, *Note `mysql_upgrade': mysql-upgrade. encodes these names by executing the following command: mysqlcheck --all-databases --check-upgrade --fix-db-names --fix-table-names Prior to MySQL 5.1.31, *Note `mysql_upgrade': mysql-upgrade. does not execute this command, so you should execute it manually if you have database or table names that contain nonalphanumeric characters. Prior to MySQL 5.1.23, the *Note `mysqlcheck': mysqlcheck. command does not perform the name encoding for views. To work around this problem, drop each affected view and recreate it. *Note `mysqlcheck': 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 *Note `mysqldump': mysqldump. to dump them before upgrading to MySQL 5.1, and then reload the dump file after upgrading. * *Known issue*: When upgrading from MySQL 5.0 to versions of 5.1 prior to 5.1.23, running *Note `mysqlcheck': mysqlcheck. (or *Note `mysql_upgrade': mysql-upgrade, which runs *Note `mysqlcheck': mysqlcheck.) to upgrade tables fails for names that must be written as quoted identifiers. To work around this problem, rename each affected table to a name that does not require quoting: RENAME TABLE `tab``le_a` TO table_a; RENAME TABLE `table b` TO table_b; After renaming the tables, run the *Note `mysql_upgrade': mysql-upgrade. program. Then rename the tables back to their original names: RENAME TABLE table_a TO `tab``le_a`; RENAME TABLE table_b TO `table b`; * *Known issue*: In connection with view creation, the server created `arc' directories inside database directories and maintained useless copies of `.frm' files there. Creation and renaming procedures of those copies as well as creation of `arc' directories has been discontinued in MySQL 5.1.29. This change does cause a problem when downgrading to older server versions which manifests itself under these circumstances: 1. Create a view `v_orig' in MySQL 5.1.29 or higher. 2. Rename the view to `v_new' and then back to `v_orig'. 3. Downgrade to an older 5.1.x server and run *Note `mysql_upgrade': mysql-upgrade. 4. Try to rename `v_orig' to `v_new' again. This operation fails. As a workaround to avoid this problem, use either of these approaches: * Dump your data using *Note `mysqldump': mysqldump. before downgrading and reload the dump file after downgrading. * Instead of renaming a view after the downgrade, drop it and recreate it. * *Incompatible change*: Character set or collation changes may require table indexes to be rebuilt. In MySQL 5.1, these occurred in versions 5.1.21, 5.1.23, and 5.1.24. For details, see *Note checking-table-incompatibilities::. * *Incompatible change*: As of MySQL 5.5.6, handling of *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select. statements has been changed for the case that the destination table already exists: * Previously, for *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select, MySQL produced a warning that the table exists, but inserted the rows and wrote the statement to the binary log anyway. By contrast, *Note `CREATE TABLE ... SELECT': create-table-select. (without `IF NOT EXISTS') failed with an error, but MySQL inserted no rows and did not write the statement to the binary log. * MySQL now handles both statements the same way when the destination table exists, in that neither statement inserts rows or is written to the binary log. The difference between them is that MySQL produces a warning when `IF NOT EXISTS' is present and an error when it is not. This change in handling of `IF NOT EXISTS' results in an incompatibility for statement-based replication from a MySQL 5.1 master with the original behavior and a MySQL 5.5 slave with the new behavior. Suppose that *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select. is executed on the master and the destination table exists. The result is that rows are inserted on the master but not on the slave. (Row-based replication does not have this problem.) To address this issue, statement-based binary logging for *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select. is changed in MySQL 5.1 as of 5.1.51: * If the destination table does not exist, there is no change: The statement is logged as is. * If the destination table does exist, the statement is logged as the equivalent pair of *Note `CREATE TABLE IF NOT EXISTS': create-table-select. and *Note `INSERT ... SELECT': insert-select. statements. (If the *Note `SELECT': select. in the original statement is preceded by `IGNORE' or *Note `REPLACE': replace, the *Note `INSERT': insert. becomes *Note `INSERT IGNORE': insert. or *Note `REPLACE': replace, respectively.) This change provides forward compatibility for statement-based replication from MySQL 5.1 to 5.5 because when the destination table exists, the rows will be inserted on both the master and slave. To take advantage of this compatibility measure, the 5.1 server must be at least 5.1.51 and the 5.5 server must be at least 5.5.6. To upgrade an existing 5.1-to-5.5 replication scenario, upgrade the master first to 5.1.51 or higher. Note that this differs from the usual replication upgrade advice of upgrading the slave first. A workaround for applications that wish to achieve the original effect (rows inserted regardless of whether the destination table exists) is to use *Note `CREATE TABLE IF NOT EXISTS': create-table-select. and *Note `INSERT ... SELECT': insert-select. statements rather than *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select. statements. Along with the change just described, the following related change was made: Previously, if an existing view was named as the destination table for *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select, rows were inserted into the underlying base table and the statement was written to the binary log. As of MySQL 5.1.51 and 5.5.6, nothing is inserted or logged. * *Incompatible change*: Prior to MySQL 5.1.51, if you flushed the logs using *Note `FLUSH LOGS': flush. or *Note `mysqladmin flush-logs': mysqladmin. and *Note `mysqld': mysqld. was writing the error log to a file (for example, if it was started with the `--log-error' option), it renames the current log file with the suffix `-old', then created a new empty log file. This had the problem that a second log-flushing operation thus caused the original error log file to be lost unless you saved it under a different name. For example, you could use the following commands to save the file: shell> mysqladmin flush-logs shell> mv HOST_NAME.err-old BACKUP-DIRECTORY To avoid the preceding file-loss problem, no renaming occurs as of MySQL 5.1.51; the server merely closes and reopens the log file. To rename the file, you can do so manually before flushing. Then flushing the logs reopens a new file with the original file name. For example, you can rename the file and create a new one using the following commands: shell> mv HOST_NAME.err HOST_NAME.err-old shell> mysqladmin flush-logs shell> mv HOST_NAME.err-old BACKUP-DIRECTORY * *Incompatible change*: MySQL 5.1 implements support for a plugin API that enables the loading and unloading of components at runtime, without restarting the server. *Note plugin-api::. The plugin API requires the `mysql.plugin' table. After upgrading from an older version of MySQL, you should run the *Note `mysql_upgrade': mysql-upgrade. command to create this table. See *Note mysql-upgrade::. Plugins are installed in the directory named by the `plugin_dir' system variable. This variable also controls the location from which the server loads user-defined functions (UDFs), which is a change from earlier versions of MySQL. That is, all UDF library files now must be installed in the plugin directory. When upgrading from an older version of MySQL, you must migrate your UDF files to the plugin directory. * *Incompatible change*: The `table_cache' system variable has been renamed to `table_open_cache'. Any scripts that refer to `table_cache' must be updated to use the new name. * *Incompatible change*: In MySQL 5.1.36, options for loading plugins such as pluggable storage engines were changed from boolean to tristate format. The implementations overlap, but if you previously used options of the form `--PLUGIN_NAME=0' or `--PLUGIN_NAME=1', you should instead use `--PLUGIN_NAME=OFF' or `--PLUGIN_NAME=ON', respectively. For details, see *Note server-plugin-loading::. * *Incompatible change*: From MySQL 5.1.24 to 5.1.31, the *Note `UPDATE': update. statement was changed such that assigning `NULL' to a `NOT NULL' column caused an error even when strict SQL mode was not enabled. The original behavior before MySQL 5.1.24 was that such assignments caused an error only in strict SQL mode, and otherwise set the column to the implicit default value for the column data type and generated a warning. (For information about implicit default values, see *Note data-type-defaults::.) The change caused compatibility problems for applications that relied on the original behavior. It also caused replication problems between servers that had the original behavior and those that did not, for applications that assigned `NULL' to `NOT NULL' columns in *Note `UPDATE': update. statements without strict SQL mode enabled. The change was reverted in MySQL 5.1.32 so that *Note `UPDATE': update. again had the original behavior. Problems can still occur if you replicate between servers that have the modified *Note `UPDATE': update. behavior and those that do not. * *Incompatible change*: As of MySQL 5.1.29, the default binary logging mode has been changed from `MIXED' to `STATEMENT' for compatibility with MySQL 5.0. * *Incompatible change*: In MySQL 5.1.25, a change was made to the way that the server handles prepared statements. This affects prepared statements processed at the SQL level (using the *Note `PREPARE': prepare. statement) and those processed using the binary client/server protocol (using the *Note `mysql_stmt_prepare()': mysql-stmt-prepare. C API function). Previously, changes to metadata of tables or views referred to in a prepared statement could cause a server crash when the statement was next executed, or perhaps an error at execute time with a crash occurring later. For example, this could happen after dropping a table and recreating it with a different definition. Now 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. Metadata changes occur for DDL statements such as those that create, drop, alter, rename, or truncate tables, or that analyze, optimize, or repair tables. Repreparation 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 *Note `FLUSH TABLES': flush. Repreparation is automatic, but to the extent that it occurs, performance of prepared statements is diminished. Table content changes (for example, with *Note `INSERT': insert. or *Note `UPDATE': update.) do not cause repreparation, nor do *Note `SELECT': select. statements. An incompatibility with previous versions of MySQL is that a prepared statement may now return a different set of columns or different column types from one execution to the next. For example, if the prepared statement is `SELECT * FROM t1', altering `t1' to contain a different number of columns causes the next execution to return a number of columns different from the previous execution. Older versions of the client library cannot handle this change in behavior. For applications that use prepared statements with the new server, an upgrade to the new client library is strongly recommended. Along with this change to statement repreparation, the default value of the `table_definition_cache' system variable has been increased from 128 to 256. The purpose of this increase is to lessen the chance that prepared statements will need repreparation due to referred-to tables/views having been flushed from the cache to make room for new entries. A new status variable, `Com_stmt_reprepare', has been introduced to track the number of repreparations. * *Incompatible change*: The `-', `*', and `/' operators and the functions `POW()' and `EXP()' could misbehave when used with floating-point numbers. Previously they might return `+INF', `-INF', or `NaN' in cases of numeric overflow (including that caused by division by zero) or when invalid arguments were used. As of MySQL 5.1.24, `NULL' is returned in all such cases. * *Incompatible change*: As of MySQL 5.1.23, within a stored routine, it is no longer permissible to declare a cursor for a *Note `SHOW': show. or *Note `DESCRIBE': describe. statement. This happened to work in some instances, but is no longer supported. In many cases, a workaround for this change is to use the cursor with a *Note `SELECT': select. query to read from an `INFORMATION_SCHEMA' table that produces the same information as the *Note `SHOW': show. statement. * *Incompatible change*: *Note `SHOW CREATE VIEW': 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. As of MySQL 5.1.23, aliases for column names in *Note `CREATE VIEW': 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 *Note `SHOW CREATE VIEW': show-create-view. fail if any column alias exceeds 64 characters. This can cause problems for replication or loading dump files. For additional information and workarounds, see *Note view-restrictions::. * *Incompatible change*: Several issues were identified for stored programs (stored procedures and functions, triggers, and events) and views containing non-ASCII symbols. These issues involved conversion errors due to incomplete character set information when translating these objects to and from stored format. To address these problems, the representation for these objects was changed in MySQL 5.1.21. However, the fixes affect _all_ stored programs and views. (For example, you will see warnings about `no creation context.') To avoid warnings from the server about the use of old definitions from any release prior to 5.1.21, you should dump stored programs and views with *Note `mysqldump': mysqldump. after upgrading to 5.1.21 or higher, and then reload them to recreate them with new definitions. Invoke *Note `mysqldump': mysqldump. with a `--default-character-set' option that names the non-ASCII character set that was used for the definitions when the objects were originally created, and the `--routines', `--events', and `--triggers' options to dump stored program definitions. Upgrading for triggers in particular must be handled carefully, for two reasons: * The output from *Note `mysqldump': mysqldump. does not contain a *Note `DROP TRIGGER': drop-trigger. statement preceding each *Note `CREATE TRIGGER': create-trigger. statement, so reloading the dump file will fail to re-create the triggers unless you manually drop them after generating the dump file and before reloading it. * If you are upgrading from a very old version of MySQL 5.0 (before 5.0.10), the trigger upgrade procedure is different because triggers for those versions were created using a different namespace (trigger names had to be unique per table, rather than per schema as is true now). For instructions on upgrading triggers from old 5.0 versions, see Upgrading from MySQL 4.1 to 5.0 (http://dev.mysql.com/doc/refman/5.0/en/upgrading-from-previous-series.html). Assuming that you are upgrading from MySQL 5.0.10 to 5.1.20 to MySQL 5.1.21 or later, use the following procedure to upgrade your triggers: * Use *Note `mysqldump': mysqldump. to generate a dump file that contains the trigger definitions: mysqldump --triggers --no-create-db --no-data --no-create-info --all-databases > triggers.sql You might need to add options to specify connection parameters, such as `--user' or `--password'. Also, if you are updating from a version of MySQL 5.1 older than 5.1.21, you may need to include a `--default-character-set' option that specifies the non-ASCII character set that was used for the definitions when the triggers were originally created. Otherwise, invoke *Note `mysqldump': mysqldump. with exactly the preceding options to avoid generating a dump file that will not have the intended effect when reloaded. For example, if you omit the `--no-create-db' option, your databases will be removed and recreated with no contents when you reload the dump file. * Drop existing triggers. To see which triggers exist, use this statement: SELECT TRIGGER_SCHEMA, EVENT_OBJECT_TABLE, TRIGGER_NAME FROM INFORMATION_SCHEMA.TRIGGERS; To generate `DROP TRIGGERS' statements for the triggers, use this statement: SELECT CONCAT('DROP TRIGGER ', TRIGGER_SCHEMA, '.', TRIGGER_NAME, ';') FROM INFORMATION_SCHEMA.TRIGGERS INTO OUTFILE '/tmp/drop_triggers.sql'; The statement uses `INTO OUTFILE', so you must have the `FILE' privilege. The file will be created on the server host. Use a different file name if you like. To be 100% safe, inspect the trigger definitions in the `drop_triggers.sql' file, and perhaps make a backup of the file. Then execute the statements in the file: mysql --force < /tmp/drop_triggers.sql * Recreate the triggers by reloading the dump file created earlier: mysql --force < triggers.sql * *Incompatible change*: As of MySQL 5.1.20, *Note `mysqld_safe': mysqld-safe. supports error logging to `syslog' on systems that support the `logger' command. The new `--syslog' and `--skip-syslog' options can be used instead of the `--log-error' option to control logging behavior, as described in *Note mysqld-safe::. In 5.1.21 and up, the default is `--skip-syslog', which is compatible with the default behavior of writing an error log file for releases prior to 5.1.20. *In 5.1.20 _only_, the following conditions apply*: 1) The default is to use `syslog', which is not compatible with releases prior to 5.1.20. 2) Logging to `syslog' may fail to operate correctly in some cases. For these reasons, avoid using MySQL 5.1.20. * *Incompatible change*: As of MySQL 5.1.18, the plugin interface and its handling of system variables was changed. Command-line options such as `--skip-innodb' now cause an error if `InnoDB' is not built-in or plugin-loaded. You should use `--loose-skip-innodb' if you do not want any error even if `InnoDB' is not available. The `--loose' prefix modifier should be used for all command-line options where you are uncertain whether the plugin exists and when you want the operation to proceed even if the option is necessarily ignored due to the absence of the plugin. (For a description of how `--loose' works, see *Note command-line-options::.) * *Incompatible change*: As of MySQL 5.1.15, `InnoDB' rolls back only the last statement on a transaction timeout. A new option, `--innodb_rollback_on_timeout', causes `InnoDB' to abort and roll back the entire transaction if a transaction timeout occurs (the same behavior as in MySQL 4.1). * *Incompatible change*: As of MySQL 5.1.15, the following conditions apply to enabling the `read_only' system variable: * If you attempt to enable `read_only' while you have any explicit locks (acquired with *Note `LOCK TABLES': lock-tables. or have a pending transaction, an error will occur. * If other clients hold explicit table locks or have pending transactions, the attempt to enable `read_only' blocks 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. * `read_only' can be enabled while you hold a global read lock (acquired with *Note `FLUSH TABLES WITH READ LOCK': flush.) because that does not involve table locks. Previously, the attempt to enable `read_only' would return immediately even if explicit locks or transactions were pending, so some data changes could occur for statements executing in the server at the same time. * *Incompatible change*: The number of function names affected by `IGNORE_SPACE' was reduced significantly in MySQL 5.1.13, from about 200 to about 30. (For details about `IGNORE_SPACE', see *Note function-resolution::.) This change improves the consistency of parser operation. However, it also introduces the possibility of incompatibility for old SQL code that relies on the following conditions: * `IGNORE_SPACE' is disabled. * The presence or absence of whitespace following a function name is used to distinguish between a built-in function and stored function that have the same name (for example, `PI()' versus `PI ()'). For functions that are no longer affected by `IGNORE_SPACE' as of MySQL 5.1.13, that strategy no longer works. Either of the following approaches can be used if you have code that is subject to the preceding incompatibility: * If a stored function has a name that conflicts with a built-in function, refer to the stored function with a schema name qualifier, regardless of whether whitespace is present. For example, write `SCHEMA_NAME.PI()' or `SCHEMA_NAME.PI ()'. * Alternatively, rename the stored function to use a nonconflicting name and change invocations of the function to use the new name. * *Incompatible change*: For `utf8' columns, the full-text parser incorrectly considered several nonword punctuation and whitespace characters as word characters, causing some searches to return incorrect results. The fix involves a change to the full-text parser in MySQL 5.1.12, so as of 5.1.12, any tables that have `FULLTEXT' indexes on `utf8' columns must be repaired with *Note `REPAIR TABLE': repair-table.: REPAIR TABLE TBL_NAME QUICK; * *Incompatible change*: Storage engines can be pluggable at runtime, so the distinction between disabled and invalid storage engines no longer applies. As of MySQL 5.1.12, this affects the `NO_ENGINE_SUBSTITUTION' SQL mode, as described in *Note server-sql-mode::. * *Incompatible change*: The structure of `FULLTEXT' indexes has been changed in MySQL 5.1.6. After upgrading to MySQL 5.1.6 or greater, any tables that have `FULLTEXT' indexes must be repaired with *Note `REPAIR TABLE': repair-table.: REPAIR TABLE TBL_NAME QUICK; * *Incompatible change*: In MySQL 5.1.6, when log tables were implemented, the default log destination for the general query and slow query log was `TABLE'. As of MySQL 5.1.21, this default has been changed to `FILE', which is compatible with MySQL 5.0, but incompatible with earlier releases of MySQL 5.1. If you are upgrading from MySQL 5.0 to 5.1.21 or higher, no logging option changes should be necessary. However, if you are upgrading from 5.1.6 through 5.1.20 to 5.1.21 or higher and were using `TABLE' logging, use the `--log-output=TABLE' option explicitly to preserve your server's table-logging behavior. * *Incompatible change*: In very old versions of MySQL (prior to 4.1), the *Note `TIMESTAMP': datetime. data type supported a display width, which was silently ignored beginning with MySQL 4.1. This is deprecated in MySQL 5.1, and removed altogether in MySQL 5.5. These changes in behavior can lead to two problem scenarios when trying to use *Note `TIMESTAMP(N)': datetime. columns with a MySQL 5.5 or later server: * When importing a dump file (for example, one created using *Note `mysqldump': mysqldump.) created in a MySQL 5.0 or earlier server into a server from a newer release series, a *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. statement containing *Note `TIMESTAMP(N)': datetime. causes the import to fail with a syntax error. To fix this problem, edit the dump file in a text editor to replace any instances of *Note `TIMESTAMP(N)': datetime. with *Note `TIMESTAMP': datetime. prior to importing the file. Be sure to use a plain text editor for this, and not a word processor; otherwise, the result is almost certain to be unusable for importing into the MySQL server. * When trying replicate any *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. statement containing *Note `TIMESTAMP(N)': datetime. from a master MySQL server that supports the *Note `TIMESTAMP(N)': datetime. syntax to a MySQL 5.5.3 or newer slave, the statement causes replication to fail. Similarly, when you try to restore from a binary log written by a server that supports *Note `TIMESTAMP(N)': datetime. to a MySQL 5.5.3 or newer server, any *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. statement containing *Note `TIMESTAMP(N)': datetime. causes the backup to fail. This holds true regardless of the logging format. It may be possible to fix such issues using a hex editor, by replacing any width arguments used with *Note `TIMESTAMP': datetime, and the parentheses containing them, with space characters (hexadecimal `20'). Be sure to use a programmer's binary hex editor and not a regular text editor or word processor for this; otherwise, the result is almost certain to be a corrupted binary log file. To guard against accidental corruption of the binary log, you should always work on a copy of the file rather than the original. You should try to handle potential issues of these types proactively by updating with *Note `ALTER TABLE': alter-table. any *Note `TIMESTAMP(N)': datetime. columns in your databases so that they use *Note `TIMESTAMP': datetime. instead, before performing any upgrades. * *Incompatible change*: For *Note `ENUM': enum. columns that had enumeration values containing commas, the commas were mapped to `0xff' internally. However, this rendered the commas indistinguishable from true `0xff' characters in the values. This no longer occurs. However, the fix requires that you dump and reload any tables that have *Note `ENUM': enum. columns containing true `0xff' in their values: Dump the tables using *Note `mysqldump': mysqldump. with the current server before upgrading from a version of MySQL 5.1 older than 5.1.15 to version 5.1.15 or newer. * As of MySQL 5.1.12, the `lc_time_names' system 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. See *Note locale-support::. * As of MySQL 5.1.9, *Note `mysqld_safe': mysqld-safe. no longer implicitly invokes `mysqld-max' if it exists. Instead, it invokes *Note `mysqld': mysqld. unless a `--mysqld' or `--mysqld-version' option is given to specify another server explicitly. If you previously relied on the implicit invocation of `mysqld-max', you should use an appropriate option now. As of MySQL 5.1.12, there is no longer any separate `mysqld-max' server, so no change should be necessary. * SQL Changes * * *Known issue*: Prior to MySQL 5.1.17, the parser accepted invalid code in SQL condition handlers, leading to server crashes or unexpected execution behavior in stored programs. Specifically, the parser permitted a condition handler to refer to labels for blocks that enclose the handler declaration. This was incorrect because block label scope does not include the code for handlers declared within the labeled block. As of 5.1.17, the parser rejects this invalid construct, but if you perform a binary upgrade (without dumping and reloading your databases), existing handlers that contain the construct still are invalid and should be rewritten _even if they appear to function as you expect._ To find affected handlers, use *Note `mysqldump': mysqldump. to dump all stored procedures and functions, triggers, and events. Then attempt to reload them into an upgraded server. Handlers that contain illegal label references will be rejected. For more information about condition handlers and writing them to avoid invalid jumps, see *Note declare-handler::. * *Incompatible change*: The parser accepted statements that contained `/* ... */' that were not properly closed with `*/', such as `SELECT 1 /* + 2'. As of MySQL 5.1.23, statements that contain unclosed `/*'-comments now are rejected with a syntax error. This fix has the potential to cause incompatibilities. Because of Bug #26302, which caused the trailing `*/' to be truncated from comments in views, stored routines, triggers, and events, it is possible that objects of those types may have been stored with definitions that now will be rejected as syntactically invalid. Such objects should be dropped and re-created so that their definitions do not contain truncated comments. * *Incompatible change*: Multiple-table *Note `DELETE': delete. statements containing ambiguous aliases could have unintended side effects such as deleting rows from the wrong table. Examples: DELETE FROM t1 AS a2 USING t1 AS a1 INNER JOIN t2 AS a2; DELETE t1 AS a2 FROM t1 AS a1 INNER JOIN t2 AS a2; To avoid ambiguity, declaration of aliases other than in the TABLE_REFERENCES part of the statement should be avoided: DELETE FROM t1 USING t1 AS a1 INNER JOIN t2 AS a2; DELETE t1 FROM t1 AS a1 INNER JOIN t2 AS a2; As of MySQL 5.1.23, alias declarations outside the TABLE_REFERENCES part of the statement are disallowed for the `USING' variant of multiple-table *Note `DELETE': delete. syntax. (In MySQL 5.5, alias declarations outside TABLE_REFERENCES are disallowed for all multiple-table *Note `DELETE': delete. statements.) Statements containing aliases that are no longer permitted must be rewritten. * *Incompatible change*: As of MySQL 5.1.8, `TYPE = ENGINE_NAME' is still accepted as a synonym for the `ENGINE = ENGINE_NAME' table option but generates a warning. You should note that this option is not available in MySQL 5.1.7, and *is removed altogether in MySQL 5.5 and produces a syntax error*. `TYPE' has been deprecated since MySQL 4.0. * *Incompatible change*: MySQL 5.1.6 introduces the `TRIGGER' privilege. Previously, the `SUPER' privilege was needed to create or drop triggers. Now those operations require the `TRIGGER' privilege. This is a security improvement because you no longer need to grant users the `SUPER' privilege to enable them to create triggers. However, the requirement that the account named in a trigger's `DEFINER' clause must have the `SUPER' privilege has changed to a requirement for the `TRIGGER' privilege. When upgrading from a previous version of MySQL 5.0 or 5.1 to MySQL 5.1.6 or newer, be sure to update your grant tables by running *Note `mysql_upgrade': mysql-upgrade. This will assign the `TRIGGER' privilege to all accounts that had the `SUPER' privilege. If you fail to update the grant tables, triggers may fail when activated. After updating the grant tables, you can revoke the `SUPER' privilege from those accounts that no longer otherwise require it. * Some keywords may be reserved in MySQL 5.1 that were not reserved in MySQL 5.0. See *Note reserved-words::. * The *Note `BACKUP TABLE': backup-table, and *Note `RESTORE TABLE': restore-table. statements are deprecated. *Note `mysqldump': mysqldump. or *Note `mysqlhotcopy': mysqlhotcopy. can be used as alternatives. * The *Note `LOAD DATA FROM MASTER': load-data-from-master. and *Note `LOAD TABLE FROM MASTER': load-table-from-master. statements are deprecated. See *Note load-data-from-master::, for recommended alternatives. * The *Note `INSTALL PLUGIN': install-plugin. and *Note `UNINSTALL PLUGIN': uninstall-plugin. statements that are used for the plugin API are new. So is the `WITH PARSER' clause for `FULLTEXT' index creation that associates a parser plugin with a full-text index. *Note plugin-api::. * C API Changes * * *Incompatible change*: As of MySQL 5.1.7, the *Note `mysql_stmt_attr_get()': mysql-stmt-attr-get. C API function returns a boolean rather than an unsigned int for `STMT_ATTR_UPDATE_MAX_LENGTH'. (Bug #16144)  File: manual.info, Node: downgrading, Next: checking-table-incompatibilities, Prev: upgrading, Up: upgrading-downgrading 2.13.2 Downgrading MySQL ------------------------ * Menu: * downgrading-to-previous-series:: Downgrading to MySQL 5.0 * downgrading-from-enterprise:: Downgrading from MySQL Enterprise Edition to MySQL Community Server This section describes what you should do to downgrade to an older MySQL version in the unlikely case that the previous version worked better than the new one. It is always a good idea to make a backup beforehand, in case a downgrade fails and leaves the instance in an unusable state. To downgrade between General Availability (GA) status versions within the same release series, typically you just install the new binaries on top of the old ones and do not make any changes to the databases. Downgrades between pre-GA development releases (or from a GA release to a development release) within the same release series are not supported and you may encounter issues. The following items form a checklist of things you should do whenever you perform a downgrade: * Read the upgrading section for the release series from which you are downgrading to be sure that it does not have any features you really need. See *Note upgrading::. * If there is a downgrading section for that version, you should read that as well. * To see which new features were added between the version to which you are downgrading and your current version, see the Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/). * Check *Note checking-table-incompatibilities::, to see whether changes to table formats or to character sets or collations were made between your current version of MySQL and the version to which you are downgrading. If so and these changes result in an incompatibility between MySQL versions, you will need to downgrade the affected tables using the instructions in *Note rebuilding-tables::. In most cases, you can move the MySQL format files and data files between different GA versions on the same architecture as long as you stay within versions for the same release series of MySQL. If you downgrade from one release series to another, there may be incompatibilities in table storage formats. In this case, use *Note `mysqldump': mysqldump. to dump your tables before downgrading. After downgrading, reload the dump file using *Note `mysql': mysql. or *Note `mysqlimport': mysqlimport. to re-create your tables. For examples, see *Note 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 *Note `mysqldump': 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. It might also be the case that system tables in the `mysql' database have changed and that downgrading introduces some loss of functionality or requires some adjustments. Here are some examples: * Trigger creation requires the `TRIGGER' privilege as of MySQL 5.1. In MySQL 5.0, there is no `TRIGGER' privilege and `SUPER' is required instead. If you downgrade from MySQL 5.1 to 5.0, you will need to give the `SUPER' privilege to those accounts that had the `TRIGGER' privilege in 5.1. * Triggers were added in MySQL 5.0, so if you downgrade from 5.0 to 4.1, you cannot use triggers at all. * The `mysql.proc.comment' column definition changed between MySQL 5.1 and 5.5. After a downgrade from 5.5 to 5.1, this table is seen as corrupt and in need of repair. To workaround this problem, execute *Note `mysql_upgrade': mysql-upgrade. from the version of MySQL to which you downgraded.  File: manual.info, Node: downgrading-to-previous-series, Next: downgrading-from-enterprise, Prev: downgrading, Up: downgrading 2.13.2.1 Downgrading to MySQL 5.0 ................................. When downgrading to MySQL 5.0 from MySQL 5.1, you should keep in mind the following issues relating to features found in MySQL 5.1, but not in MySQL 5.0: * Partitioning MySQL 5.0 does not support user-defined partitioning. If a table was created as a partitioned table in 5.1 (or if an table created in a previous version of MySQL was altered to include partitions after an upgrade to 5.1), the table is accessible after downgrade only if you do one of the following: * Export the table using *Note `mysqldump': mysqldump. and then drop it in MySQL 5.1; import the table again following the downgrade to MySQL 5.0. * Prior to the downgrade, remove the table's partitioning using `ALTER TABLE TABLE_NAME REMOVE PARTITIONING'. * Event Scheduler MySQL 5.0 does not support scheduled events. If your databases contain scheduled event definitions, you should prevent them from being dumped when you use *Note `mysqldump': mysqldump. by using the `--skip-events' option. (See *Note mysqldump::.) * Stored routines MySQL 5.1.21 added a number of new columns to the `mysql.proc' table in which stored routine definitions are stored. If you are downgrading from MySQL 5.1.21 or later to MySQL 5.0, you cannot import the MySQL 5.1 routine definitions into MySQL 5.0.46 or earlier using the dump of `mysql.proc' created by *Note `mysqldump': mysqldump. (such as when using the `--all-databases' option). Instead, you should run *Note `mysqldump `--routines'': mysqldump. prior to performing the downgrade and run the stored routines DDL statements following the downgrade. See Bug #11986, Bug #30029, and Bug #30660, for more information. * Triggers Trigger creation requires the `TRIGGER' privilege as of MySQL 5.1. In MySQL 5.0, there is no `TRIGGER' privilege and `SUPER' is required instead. If you downgrade from MySQL 5.1 to 5.0, you will need to give the `SUPER' privilege to those accounts that had the `TRIGGER' privilege in 5.1.  File: manual.info, Node: downgrading-from-enterprise, Prev: downgrading-to-previous-series, Up: downgrading 2.13.2.2 Downgrading from MySQL Enterprise Edition to MySQL Community Server ............................................................................ This section describes the steps required to downgrade from MySQL Enterprise Edition to MySQL Community Edition. This can be done at any time, and is required at the expiration of a MySQL Enterprise Edition subscription if you wish to continue using MySQL Server. When you perform such a downgrade, all commercially licensed components of the MySQL Enterprise Edition subscription must be uninstalled. These components and related considerations are described in the rest of this section. *Note*: The issues described in this section are in addition to any that may be encountered as a result of any upgrade or downgrade of the MySQL Server version (such as between MySQL 5.1 and 5.0). Information about upgrading and downgrading between MySQL release series can be found elsewhere in this chapter; see *Note upgrading::, and *Note downgrading::. MySQL Enterprise Database Server All commercial versions of MySQL Database Server must be uninstalled. Commercially licensed extensions All commercially licensed MySQL Enterprise Database Server extensions must be uninstalled, including the _MySQL High Availability_ extension. Following uninstallation of this extension, automated failover is no longer available. MySQL Enterprise Backup MySQL Enterprise Backup must be uninstalled. Uninstalling this application has the effects listed here: * Automated backup scripts no longer work. * Existing backup images taken with MySQL Enterprise Backup can no longer be used for recovery. * Third-party integration with multimedia systems such as NetBackup, Tivoli, and Oracle Secure Backup no longer works. MySQL Enterprise Monitor, MySQL Query Analyzer, agents MySQL Enterprise Monitor, MySQL Query Analyzer, and all server-side agents must be uninstalled. Uninstalling these applications and agents has the following effects: * Automated SNMP and SMTP alerts no longer work. * All historical MySQL, OS monitoring, query, and performance metrics as well as all trending data are lost. * All environment-specific monitoring templates, custom advisors, graphs and scripts are also lost.  File: manual.info, Node: checking-table-incompatibilities, Next: rebuilding-tables, Prev: downgrading, Up: upgrading-downgrading 2.13.3 Checking Whether Tables or Indexes Must Be Rebuilt --------------------------------------------------------- A binary upgrade or downgrade is one that installs one version of MySQL `in place' over an existing version, without dumping and reloading tables: 1. Stop the server for the existing version if it is running. 2. Install a different version of MySQL. This is an upgrade if the new version is higher than the original version, a downgrade if the version is lower. 3. Start the server for the new version. In many cases, the tables from the previous version of MySQL can be used without problem by the new version. However, sometimes changes occur that require tables or table indexes to be rebuilt, as described in this section. If you have tables that are affected by any of the issues described here, rebuild the tables or indexes as necessary using the instructions given in *Note rebuilding-tables::. * Table Incompatibilities * After a binary upgrade to MySQL 5.1 from a MySQL 5.0 installation that contains *Note `ARCHIVE': archive-storage-engine. tables: * Before MySQL 5.1.42, accessing those tables will cause the server to crash, even if you have run *Note `mysql_upgrade': mysql-upgrade. or *Note `CHECK TABLE ... FOR UPGRADE': check-table. * As of MySQL 5.1.42, the server will not open 5.0 *Note `ARCHIVE': archive-storage-engine. tables at all. In either case, the solution is to use *Note `mysqldump': mysqldump. to dump all 5.0 *Note `ARCHIVE': archive-storage-engine. tables before upgrading, and reload them into MySQL 5.1 after upgrading. This problem is fixed in MySQL 5.6.4: The server can open *Note `ARCHIVE': archive-storage-engine. tables created in MySQL 5.0. However, it remains the recommended upgrade procedure to dump 5.0 *Note `ARCHIVE': archive-storage-engine. tables before upgrading and reload them after upgrading. * Index Incompatibilities * If you perform a binary upgrade without dumping and reloading tables, you cannot upgrade directly from MySQL 4.1 to 5.1 or higher. This occurs due to an incompatible change in the `MyISAM' table index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and repair all `MyISAM' tables. Then upgrade from MySQL 5.0 to 5.1 and check and repair your tables. Modifications to the handling of character sets or collations might change the character sort order, which causes the ordering of entries in any index that uses an affected character set or collation to be incorrect. Such changes result in several possible problems: * Comparison results that differ from previous results * Inability to find some index values due to misordered index entries * Misordered `ORDER BY' results * Tables that *Note `CHECK TABLE': check-table. reports as being in need of repair The solution to these problems is to rebuild any indexes that use an affected character set or collation, either by dropping and re-creating the indexes, or by dumping and reloading the entire table. In some cases, it is possible to alter affected columns to use a different collation. For information about rebuilding indexes, see *Note rebuilding-tables::. To check whether a table has indexes that must be rebuilt, consult the following list. It indicates which versions of MySQL introduced character set or collation changes that require indexes to be rebuilt. Each entry indicates the version in which the change occurred and the character sets or collations that the change affects. If the change is associated with a particular bug report, the bug number is given. The list applies both for binary upgrades and downgrades. For example, Bug #27877 was fixed in MySQL 5.1.24, so it applies to upgrades from versions older than 5.1.24 to 5.1.24 or newer, and to downgrades from 5.1.24 or newer to versions older than 5.1.24. In many cases, you can use *Note `CHECK TABLE ... FOR UPGRADE': check-table. to identify tables for which index rebuilding is required. It will report this message: Table upgrade required. Please do "REPAIR TABLE `tbl_name`" or dump/reload to fix it! In these cases, you can also use *Note `mysqlcheck --check-upgrade': mysqlcheck. or *Note `mysql_upgrade': mysql-upgrade, which execute *Note `CHECK TABLE': check-table. However, the use of *Note `CHECK TABLE': check-table. applies only after upgrades, not downgrades. Also, *Note `CHECK TABLE': check-table. is not applicable to all storage engines. For details about which storage engines *Note `CHECK TABLE': check-table. supports, see *Note check-table::. These changes cause index rebuilding to be necessary: * MySQL 5.1.24 (Bug #27877) Affects indexes that use the `utf8_general_ci' or `ucs2_general_ci' collation for columns that contain `'ss'' LATIN SMALL LETTER SHARP S (German). The bug fix corrected an error in the original collations but introduced an incompatibility such that `'ss'' compares equal to characters with which it previously compared different. Affected tables can be detected by *Note `CHECK TABLE ... FOR UPGRADE': check-table. as of MySQL 5.1.30 (see Bug #40053). A workaround for this issue is implemented as of MySQL 5.1.62, 5.5.21, and 5.6.5. The workaround involves altering affected columns to use the `utf8_general_mysql500_ci' and `ucs2_general_mysql500_ci' collations, which preserve the original pre-5.1.24 ordering of `utf8_general_ci' and `ucs2_general_ci'. * MySQL 5.0.48, 5.1.23 (Bug #27562) Affects indexes that use the `ascii_general_ci' collation for columns that contain any of these characters: `'`'' GRAVE ACCENT, `'['' LEFT SQUARE BRACKET, `'\'' REVERSE SOLIDUS, `']'' RIGHT SQUARE BRACKET, `'~'' TILDE Affected tables can be detected by *Note `CHECK TABLE ... FOR UPGRADE': check-table. as of MySQL 5.1.29 (see Bug #39585). * MySQL 5.0.48, 5.1.21 (Bug #29461) Affects indexes for columns that use any of these character sets: `eucjpms', `euc_kr', `gb2312', `latin7', `macce', `ujis' Affected tables can be detected by *Note `CHECK TABLE ... FOR UPGRADE': check-table. as of MySQL 5.1.29 (see Bug #39585).  File: manual.info, Node: rebuilding-tables, Next: copying-databases, Prev: checking-table-incompatibilities, Up: upgrading-downgrading 2.13.4 Rebuilding or Repairing Tables or Indexes ------------------------------------------------ This section describes how to rebuild a table. This can be necessitated by changes to MySQL such as how data types are handled or changes to character set handling. 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. (For examples, see *Note checking-table-incompatibilities::.) It might also be that a table repair or upgrade should be done as indicated by a table check operation such as that performed by `CHECK TABLE', *Note `mysqlcheck': mysqlcheck, or *Note `mysql_upgrade': mysql-upgrade. Methods for rebuilding a table include dumping and reloading it, or using *Note `ALTER TABLE': alter-table. or *Note `REPAIR TABLE': repair-table. *Note*: 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. To rebuild a table by dumping and reloading it, use *Note `mysqldump': mysqldump. to create a dump file and *Note `mysql': mysql. to reload the file: shell> mysqldump DB_NAME t1 > dump.sql shell> mysql DB_NAME < dump.sql To rebuild all the tables in a single database, specify the database name without any following table name: shell> mysqldump DB_NAME > dump.sql shell> mysql DB_NAME < dump.sql To rebuild all tables in all databases, use the `--all-databases' option: shell> mysqldump --all-databases > dump.sql shell> mysql < dump.sql To rebuild a table with *Note `ALTER TABLE': alter-table, use a `null' alteration; that is, an *Note `ALTER TABLE': alter-table. statement that `changes' the table to use the storage engine that it already has. For example, if `t1' is a `MyISAM' table, use this statement: mysql> ALTER TABLE t1 ENGINE = MyISAM; If you are not sure which storage engine to specify in the *Note `ALTER TABLE': alter-table. statement, use *Note `SHOW CREATE TABLE': show-create-table. to display the table definition. If you must rebuild a table because a table checking operation indicates that the table is corrupt or needs an upgrade, you can use *Note `REPAIR TABLE': repair-table. if that statement supports the table's storage engine. For example, to repair a `MyISAM' table, use this statement: mysql> REPAIR TABLE t1; For storage engines such as `InnoDB' that *Note `REPAIR TABLE': repair-table. does not support, use *Note `mysqldump': mysqldump. to create a dump file and *Note `mysql': mysql. to reload the file, as described earlier. For specifics about which storage engines *Note `REPAIR TABLE': repair-table. supports, see *Note repair-table::. *Note `mysqlcheck --repair': mysqlcheck. provides command-line access to the *Note `REPAIR TABLE': 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: shell> mysqlcheck --repair --databases DB_NAME ... shell> mysqlcheck --repair --all-databases For incompatibilities introduced in MySQL 5.1.24 by the fix for Bug #27877 that corrected the `utf8_general_ci' and `ucs2_general_ci' collations, a workaround is implemented as of MySQL 5.1.62, 5.5.21, and 5.6.5. Upgrade to one of those versions, then convert each affected table using one of the following methods. In each case, the workaround altering affected columns to use the `utf8_general_mysql500_ci' and `ucs2_general_mysql500_ci' collations, which preserve the original pre-5.1.24 ordering of `utf8_general_ci' and `ucs2_general_ci'. * To convert an affected table after a binary upgrade that leaves the table files in place, alter the table to use the new collation. Suppose that the table `t1' contains one or more problematic `utf8' columns. To convert the table at the table level, use a statement like this: ALTER TABLE t1 CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_mysql500_ci; To apply the change on a column-specific basis, use a statement like this (be sure to repeat the column definition as originally specified except for the `COLLATE' clause): ALTER TABLE t1 MODIFY c1 CHAR(N) CHARACTER SET utf8 COLLATE utf8_general_mysql500_ci; * To upgrade the table using a dump and reload procedure, dump the table using *Note `mysqldump': mysqldump, modify the *Note `CREATE TABLE': create-table. statement in the dump file to use the new collation, and reload the table. After making the appropriate changes, *Note `CHECK TABLE': check-table. should report no error.  File: manual.info, Node: copying-databases, Prev: rebuilding-tables, Up: upgrading-downgrading 2.13.5 Copying MySQL Databases to Another Machine ------------------------------------------------- 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 *Note myisam-storage-engine::. In cases where you need to transfer databases between different architectures, you can use *Note `mysqldump': 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 *Note `mysql': mysql. client. Use *Note `mysqldump --help': mysqldump. 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: shell> mysqladmin -h 'OTHER_HOSTNAME' create DB_NAME shell> 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: shell> mysqladmin create DB_NAME shell> 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: shell> mysqldump --quick DB_NAME | gzip > DB_NAME.gz Transfer the file containing the database contents to the target machine and run these commands there: shell> mysqladmin create DB_NAME shell> gunzip < DB_NAME.gz | mysql DB_NAME You can also use *Note `mysqldump': mysqldump. and *Note `mysqlimport': mysqlimport. to transfer the database. For large tables, this is much faster than simply using *Note `mysqldump': mysqldump. In the following commands, DUMPDIR represents the full path name of the directory you use to store the output from *Note `mysqldump': mysqldump. First, create the directory for the output files and dump the database: shell> mkdir DUMPDIR shell> 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: shell> mysqladmin create DB_NAME # create database shell> cat DUMPDIR/*.sql | mysql DB_NAME # create tables in database shell> 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 *Note `mysqladmin flush-privileges': mysqladmin. so that the server reloads the grant table information.  File: manual.info, Node: environment-variables, Next: perl-support, Prev: upgrading-downgrading, Up: installing 2.14 Environment Variables ========================== This section lists all the environment variables that are used directly or indirectly by MySQL. Most of these can also be found in other places in this manual. Note that any 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 *Note option-files::. To set an environment variable within `sh', `ksh', `bash', or `zsh' shells you can use the following commands: shell> ENVVAR=VALUE shell> export ENVVAR The `export' is required if you want other sub-commands to inherit that value during execution. On more recent shells you can combine the export and setting processes, like this: shell> export set ENVVAR=VALUE For the `csh', or `tcsh' shells, use the `setenv' command: shell> setenv ENVVAR VALUE Within the Windows Command Prompt use the *Note `set': set. command to specify the value of a variable: shell> set ENVVAR=VALUE On Unix, Linux, Mac OS X, and Windows, the *Note `set': set. command without parameters will display the list of currently set variables. *MySQL Related Environment Variables* Variable Description `CXX' The name of your C++ compiler (for running `configure'). `CC' The name of your C compiler (for running `configure'). `CFLAGS' Flags for your C compiler (for running `configure'). `CXXFLAGS' Flags for your C++ compiler (for running `configure'). `DBI_USER' The default user name for Perl DBI. `DBI_TRACE' Trace options for Perl DBI. `HOME' The default path for the *Note `mysql': mysql. history file is `$HOME/.mysql_history'. `LD_RUN_PATH' Used to specify the location of `libmysqlclient.so'. `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 *Note `mysql': mysql. history file. If this variable is set, its value overrides the default for `$HOME/.mysql_history'. `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 *Note `mysql': mysql. command-line client. `MYSQL_PS1' The command prompt to use in the *Note `mysql': mysql. command-line client. `MYSQL_PWD' The default password when connecting to *Note `mysqld': mysqld. Note that using this is insecure. See *Note password-security-user::. `MYSQL_TCP_PORT' The default TCP/IP port number. `MYSQL_UNIX_PORT' The default Unix socket file name; used for connections to `localhost'. `PATH' Used by the shell to find MySQL programs. `TMPDIR' The directory where temporary files are created. `TZ' This should be set to your local time zone. See *Note 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 and NetWare when connecting to *Note `mysqld': mysqld. For information about the *Note `mysql': mysql. history file, see *Note mysql-logging::. The `UMASK' and `UMASK_DIR' variables, despite their names, are used as modes, not masks: * If `UMASK' is set, *Note `mysqld': 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, *Note `mysqld': 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. MySQL assumes that the value for `UMASK' or `UMASK_DIR' is in octal if it starts with a zero.  File: manual.info, Node: perl-support, Prev: environment-variables, Up: installing 2.15 Perl Installation Notes ============================ * Menu: * perl-installation:: Installing Perl on Unix * activestate-perl:: Installing ActiveState Perl on Windows * perl-support-problems:: Problems Using the Perl `DBI'/`DBD' Interface 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. Perl, and the `DBD::MySQL' module for `DBI' must be installed if you want to run the MySQL benchmark scripts; see *Note mysql-benchmarks::. They are also required for the MySQL Cluster *Note `ndb_size.pl': mysql-cluster-programs-ndb-size-pl. utility; see *Note mysql-cluster-programs-ndb-size-pl::. *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.1.  File: manual.info, Node: perl-installation, Next: activestate-perl, Prev: perl-support, Up: perl-support 2.15.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://servers.digitaldaze.com/extensions/perl/modules.html#modules' Look under the heading `Installing New Modules that Require Locally Installed Modules.'  File: manual.info, Node: activestate-perl, Next: perl-support-problems, Prev: perl-installation, Up: perl-support 2.15.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 newer. 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";  File: manual.info, Node: perl-support-problems, Prev: activestate-perl, Up: perl-support 2.15.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'. You may see the following error from `DBD::mysql' when you run the tests: t/00base............install_driver(mysql) failed: Can't load '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql: ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: uncompress at /usr/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169. This means that you need to include the `-lz' compression library on the link line. That can be done by changing the following line in the file `lib/DBD/mysql/Install.pm': $sysliblist .= " -lm"; Change that line to: $sysliblist .= " -lm -lz"; After this, you _must_ run `make realclean' and then proceed with the installation from the beginning.  File: manual.info, Node: tutorial, Next: programs, Prev: installing, Up: Top 3 Tutorial ********** * Menu: * connecting-disconnecting:: Connecting to and Disconnecting from the Server * entering-queries:: Entering Queries * database-use:: Creating and Using a Database * getting-information:: Getting Information About Databases and Tables * batch-mode:: Using `mysql' in Batch Mode * examples:: Examples of Common Queries * apache:: Using MySQL with Apache This chapter provides a tutorial introduction to MySQL by showing how to use the *Note `mysql': mysql. client program to create and use a simple database. *Note `mysql': 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. *Note `mysql': mysql. may also be used in batch mode: you place your queries in a file beforehand, then tell *Note `mysql': mysql. to execute the contents of the file. Both ways of using *Note `mysql': mysql. are covered here. To see a list of options provided by *Note `mysql': mysql, invoke it with the `--help' option: shell> mysql --help This chapter assumes that *Note `mysql': 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 *Note 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.  File: manual.info, Node: connecting-disconnecting, Next: entering-queries, Prev: tutorial, Up: tutorial 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 *Note `mysql': 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 *Note `mysql': 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.1.73-standard Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> The `mysql>' prompt tells you that *Note `mysql': mysql. is ready for you to enter commands. 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 *Note installing:: that is appropriate to your operating system. For help with other problems often encountered when trying to log in, see *Note 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 *Note `mysql': 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.  File: manual.info, Node: entering-queries, Next: database-use, Prev: connecting-disconnecting, Up: tutorial 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 commands, using several queries you can try out to familiarize yourself with how *Note `mysql': mysql. works. Here is a simple command 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.1.2-alpha-log | 2005-10-11 | +-----------------+--------------+ 1 row in set (0.01 sec) mysql> This query illustrates several things about *Note `mysql': mysql.: * A command 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 command, *Note `mysql': 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 command. * *Note `mysql': 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), *Note `mysql': mysql. labels the column using the expression itself. * *Note `mysql': 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 *Note `mysql': 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.1.2-alpha-log | +-----------------+ 1 row in set (0.00 sec) +---------------------+ | NOW() | +---------------------+ | 2005-10-11 15:15:00 | +---------------------+ 1 row in set (0.00 sec) A command need not be given all on a single line, so lengthy commands that require several lines are not a problem. *Note `mysql': 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, *Note `mysql': 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 | 2005-10-11 | +---------------+--------------+ 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 *Note `mysql': 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 *Note `mysql': mysql. is waiting for. If you decide you do not want to execute a command 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 *Note `mysql': mysql. is ready for a new command. The following table shows each of the prompts you may see and summarizes what they mean about the state that *Note `mysql': mysql. is in. This table lists MySQL prompts and describes the meaning of each. Prompt Meaning `mysql>'Ready for new command. `->' Waiting for next line of multiple-line command. `'>' 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 command on a single line, but forget the terminating semicolon. In this case, *Note `mysql': 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 *Note `mysql': 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 *Note `mysql': 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 *Note `mysql': 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 *Note `SELECT': 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 *Note `mysql': 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 command. However, you cannot just type `\c' in this case, because *Note `mysql': mysql. interprets it as part of the string that it is collecting. Instead, enter the closing quote character (so *Note `mysql': 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 *Note `mysql': mysql. is ready for a new command. 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 *Note `mysql': 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 command.  File: manual.info, Node: database-use, Next: getting-information, Prev: entering-queries, Up: tutorial 3.3 Creating and Using a Database ================================= * Menu: * creating-database:: Creating and Selecting a Database * creating-tables:: Creating a Table * loading-tables:: Loading Data into a Table * retrieving-data:: Retrieving Information from a Table Once you know how to enter commands, 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 Web site. It is available in both compressed `tar' file and Zip formats at `http://dev.mysql.com/doc/'. Use the *Note `SHOW': 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; *Note `SHOW DATABASES': show-databases. does not show databases that you have no privileges for if you do not have the *Note `SHOW DATABASES': show-databases. privilege. See *Note show-databases::. If the `test' database exists, try to access it: mysql> USE test Database changed *Note `USE': use, like `QUIT', does not require a semicolon. (You can terminate such statements with a semicolon if you like; it does no harm.) The *Note `USE': 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 command 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.  File: manual.info, Node: creating-database, Next: creating-tables, Prev: database-use, Up: database-use 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 'monty'@'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 *Note privilege-system::. Creating a database does not select it for use; you must do that explicitly. To make `menagerie' the current database, use this command: 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 *Note `mysql': mysql. session. You can do this by issuing a *Note `USE': use. statement as shown in the example. Alternatively, you can select the database on the command line when you invoke *Note `mysql': 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 `-pmypassword', not as `-p mypassword'). 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 *Note `SELECT': select. `DATABASE()'.  File: manual.info, Node: creating-tables, Next: loading-tables, Prev: creating-database, Up: database-use 3.3.2 Creating a Table ---------------------- Creating the database is the easy part, but at this point it is empty, as *Note `SHOW TABLES': 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 *Note `CREATE TABLE': 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); *Note `VARCHAR': char. 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 *Note `ALTER TABLE': 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 *Note `DATE': datetime. data type for the `birth' and `death' columns is a fairly obvious choice. Once you have created a table, *Note `SHOW TABLES': 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 *Note `DESCRIBE': 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 *Note `DESCRIBE': 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 *Note data-types::.  File: manual.info, Node: loading-tables, Next: retrieving-data, Prev: creating-tables, Up: database-use 3.3.3 Loading Data into a Table ------------------------------- After creating your table, you need to populate it. The *Note `LOAD DATA': load-data. and *Note `INSERT': 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.) This table illustrates the example of `pet records' mentioned in the preceding text. 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 *Note `CREATE TABLE': 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 *Note `LOAD DATA': 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 *Note load-data-local::, for information on how to change this. When you want to add new records one at a time, the *Note `INSERT': 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 *Note `CREATE TABLE': create-table. statement. Suppose that Diane gets a new hamster named `Puffball.' You could add a new record using an *Note `INSERT': 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 *Note `INSERT': insert, you can insert `NULL' directly to represent a missing value. You do not use `\N' like you do with *Note `LOAD DATA': 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 *Note `INSERT': insert. statements rather than a single *Note `LOAD DATA': load-data. statement.  File: manual.info, Node: retrieving-data, Prev: loading-tables, Up: database-use 3.3.4 Retrieving Information from a Table ----------------------------------------- * Menu: * selecting-all:: Selecting All Data * selecting-rows:: Selecting Particular Rows * selecting-columns:: Selecting Particular Columns * sorting-rows:: Sorting Rows * date-calculations:: Date Calculations * working-with-null:: Working with `NULL' Values * pattern-matching:: Pattern Matching * counting-rows:: Counting Rows * multiple-tables:: Using More Than one Table The *Note `SELECT': 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.  File: manual.info, Node: selecting-all, Next: selecting-rows, Prev: retrieving-data, Up: retrieving-data 3.3.4.1 Selecting All Data .......................... The simplest form of *Note `SELECT': 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 *Note `SELECT': 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 *Note `DELETE': delete. and *Note `LOAD DATA': load-data.: mysql> DELETE FROM pet; mysql> LOAD DATA LOCAL INFILE '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 *Note `UPDATE': update. statement: mysql> UPDATE pet SET birth = '1989-08-31' WHERE name = 'Bowser'; The *Note `UPDATE': update. changes only the record in question and does not require you to reload the table.  File: manual.info, Node: selecting-rows, Next: selecting-columns, Prev: selecting-all, Up: retrieving-data 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 *Note `SELECT': 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 | +-------+--------+---------+------+------------+-------+  File: manual.info, Node: selecting-columns, Next: sorting-rows, Prev: selecting-rows, Up: retrieving-data 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 | +--------+---------+------------+  File: manual.info, Node: sorting-rows, Next: date-calculations, Prev: selecting-columns, Up: retrieving-data 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.  File: manual.info, Node: date-calculations, Next: working-with-null, Prev: sorting-rows, Up: retrieving-data 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 *Note 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').  File: manual.info, Node: working-with-null, Next: pattern-matching, Prev: date-calculations, Up: retrieving-data 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 *Note problems-with-null::.  File: manual.info, Node: pattern-matching, Next: counting-rows, Prev: working-with-null, Up: retrieving-data 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. You 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 `REGEXP' 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 | +--------+--------+---------+------+------------+------------+ If you really want 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: mysql> 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 like it would be if you used 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 | +-------+--------+---------+------+------------+-------+ *Note regexp::, provides more information about the syntax for regular expressions.  File: manual.info, Node: counting-rows, Next: multiple-tables, Prev: pattern-matching, Up: retrieving-data 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): Mixing of GROUP columns (MIN(),MAX(),COUNT()...) with no GROUP columns is illegal if there is no GROUP BY clause * 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 indeterminate. 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 *Note group-by-extensions::.  File: manual.info, Node: multiple-tables, Prev: counting-rows, Up: retrieving-data 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 *Note `CREATE TABLE': 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. This table represents `pet record' data that will appear in a tab delimited text file, as described in the preceding text. 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, -> (YEAR(date)-YEAR(birth)) - (RIGHT(date,5) 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.  File: manual.info, Node: getting-information, Next: batch-mode, Prev: database-use, Up: tutorial 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 *Note `SHOW DATABASES': 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 command: 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 *Note show-tables::, for more information. If you want to find out about the structure of a table, the *Note `DESCRIBE': 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 *Note `DESCRIBE': describe. See *Note describe::, for more information. You can obtain the *Note `CREATE TABLE': create-table. statement necessary to create an existing table using the *Note `SHOW CREATE TABLE': show-create-table. statement. See *Note show-create-table::. If you have indexes on a table, `SHOW INDEX FROM TBL_NAME' produces information about them. See *Note show-index::, for more about this statement.  File: manual.info, Node: batch-mode, Next: examples, Prev: getting-information, Up: tutorial 3.5 Using `mysql' in Batch Mode =============================== In the previous sections, you used *Note `mysql': mysql. interactively to enter queries and view the results. You can also run *Note `mysql': mysql. in batch mode. To do this, put the commands you want to run in a file, then tell *Note `mysql': mysql. to read its input from the file: shell> mysql < BATCH-FILE If you are running *Note `mysql': 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 *Note `mysql': 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're developing a query, particularly for multiple-line commands or multiple-statement sequences of commands. If you make a mistake, you don't have to retype everything. Just edit your script to correct the error, then tell *Note `mysql': 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 commands. * 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 *Note `mysql': mysql. in batch mode than when you use it interactively. For example, the output of `SELECT DISTINCT species FROM pet' looks like this when *Note `mysql': 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 commands that are executed, use `mysql -vvv'. You can also use scripts from the *Note `mysql': mysql. prompt by using the `source' command or `\.' command: mysql> source FILENAME; mysql> \. FILENAME See *Note mysql-batch-commands::, for more information.  File: manual.info, Node: examples, Next: apache, Prev: batch-mode, Up: tutorial 3.6 Examples of Common Queries ============================== * Menu: * example-maximum-column:: The Maximum Value for a Column * example-maximum-row:: The Row Holding the Maximum of a Certain Column * example-maximum-column-group:: Maximum of Column per Group * example-maximum-column-group-row:: The Rows Holding the Group-wise Maximum of a Certain Column * example-user-variables:: Using User-Defined Variables * example-foreign-keys:: Using Foreign Keys * searching-on-two-keys:: Searching on Two Keys * calculating-days:: Calculating Visits Per Day * example-auto-increment:: Using `AUTO_INCREMENT' 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 *Note `mysql': 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 | +---------+--------+-------+  File: manual.info, Node: example-maximum-column, Next: example-maximum-row, Prev: examples, Up: examples 3.6.1 The Maximum Value for a Column ------------------------------------ `What is the highest item number?' SELECT MAX(article) AS article FROM shop; +---------+ | article | +---------+ | 4 | +---------+  File: manual.info, Node: example-maximum-row, Next: example-maximum-column-group, Prev: example-maximum-column, Up: examples 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.  File: manual.info, Node: example-maximum-column-group, Next: example-maximum-column-group-row, Prev: example-maximum-row, Up: examples 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 | +---------+-------+  File: manual.info, Node: example-maximum-column-group-row, Next: example-user-variables, Prev: example-maximum-column-group, Up: examples 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 *Note 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 *Note join::.  File: manual.info, Node: example-user-variables, Next: example-foreign-keys, Prev: example-maximum-column-group-row, Up: examples 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 *Note 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 *Note sql-syntax-prepared-statements::, for more information.  File: manual.info, Node: example-foreign-keys, Next: searching-on-two-keys, Prev: example-user-variables, Up: examples 3.6.6 Using Foreign Keys ------------------------ In MySQL, `InnoDB' tables support checking of foreign key constraints. See *Note innodb-storage-engine::, and *Note 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 *Note `SHOW CREATE TABLE': show-create-table. or *Note `DESCRIBE': 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.  File: manual.info, Node: searching-on-two-keys, Next: calculating-days, Prev: example-foreign-keys, Up: examples 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 *Note index-merge-optimization::. You can also solve the problem efficiently by using a *Note `UNION': union. that combines the output of two separate *Note `SELECT': select. statements. See *Note union::. Each *Note `SELECT': 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';  File: manual.info, Node: calculating-days, Next: example-auto-increment, Prev: searching-on-two-keys, Up: examples 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< ALTER TABLE tbl AUTO_INCREMENT = 100; * InnoDB Notes * For `InnoDB' tables, be careful if you modify the column containing the auto-increment value in the middle of a sequence of *Note `INSERT': insert. statements. For example, if you use an *Note `UPDATE': update. statement to put a new, larger value in the auto-increment column, a subsequent *Note `INSERT': insert. could encounter a `Duplicate entry' error. The test whether an auto-increment value is already present occurs if you do a *Note `DELETE': delete. followed by more *Note `INSERT': insert. statements, or when you *Note `COMMIT': commit. the transaction, but not after an *Note `UPDATE': update. statement. * 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. * Further Reading * More information about `AUTO_INCREMENT' is available here: * How to assign the `AUTO_INCREMENT' attribute to a column: *Note create-table::, and *Note alter-table::. * How `AUTO_INCREMENT' behaves depending on the `NO_AUTO_VALUE_ON_ZERO' SQL mode: *Note server-sql-mode::. * How to use the `LAST_INSERT_ID()' function to find the row that contains the most recent `AUTO_INCREMENT' value: *Note information-functions::. * Setting the `AUTO_INCREMENT' value to be used: *Note server-system-variables::. * `AUTO_INCREMENT' and replication: *Note replication-features-auto-increment::. * Server-system variables related to `AUTO_INCREMENT' (`auto_increment_increment' and `auto_increment_offset') that can be used for replication: *Note server-system-variables::.  File: manual.info, Node: apache, Prev: examples, Up: tutorial 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.  File: manual.info, Node: programs, Next: server-administration, Prev: tutorial, Up: Top 4 MySQL Programs **************** * Menu: * programs-overview:: Overview of MySQL Programs * programs-using:: Using MySQL Programs * programs-server:: MySQL Server and Server-Startup Programs * programs-installation:: MySQL Installation-Related Programs * programs-client:: MySQL Client Programs * programs-admin-utils:: MySQL Administrative and Utility Programs * programs-development:: MySQL Program Development Utilities * programs-miscellaneous:: Miscellaneous 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.  File: manual.info, Node: programs-overview, Next: programs-using, Prev: programs, Up: programs 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 MySQL Cluster programs. Each program's description indicates its invocation syntax and the options that it supports. *Note mysql-cluster::, describes programs specific to MySQL 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 *Note 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 *Note `mysql --help': mysql. You can override default option values for MySQL programs by specifying options on the command line or in an option file. See *Note programs-using::, for general information on invoking programs and specifying program options. The MySQL server, *Note `mysqld': 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: * *Note `mysqld': mysqld. The SQL daemon (that is, the MySQL server). To use client programs, *Note `mysqld': mysqld. must be running, because clients gain access to databases by connecting to the server. See *Note mysqld::. * *Note `mysqld_safe': mysqld-safe. A server startup script. *Note `mysqld_safe': mysqld-safe. attempts to start *Note `mysqld': mysqld. See *Note mysqld-safe::. * *Note `mysql.server': 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 *Note `mysqld_safe': mysqld-safe. to start the MySQL server. See *Note mysql-server::. * *Note `mysqld_multi': mysqld-multi. A server startup script that can start or stop multiple servers installed on the system. See *Note mysqld-multi::. An alternative to *Note `mysqld_multi': mysqld-multi. is `mysqlmanager', the MySQL Instance Manager. See *Note instance-manager::. There are several programs that perform setup operations during MySQL installation or upgrading: * *Note `comp_err': comp-err. This program is used during the MySQL build/installation process. It compiles error message files from the error source files. See *Note comp-err::. * `make_binary_distribution' This program makes a binary release of a compiled MySQL. This could be sent by FTP to `/pub/mysql/upload/' on `ftp.mysql.com' for the convenience of other MySQL users. * *Note `make_win_bin_dist': make-win-bin-dist. This program is used on Windows. It packages a MySQL distribution for installation after the source distribution has been built. See *Note make-win-bin-dist::. * *Note `mysql_fix_privilege_tables': mysql-fix-privilege-tables. This program is used after a MySQL upgrade operation. It updates the grant tables with any changes that have been made in newer versions of MySQL. See *Note mysql-fix-privilege-tables::. Note: As of MySQL 5.1.7, this program has been superseded by *Note `mysql_upgrade': mysql-upgrade. and should no longer be used. * *Note `mysql_install_db': mysql-install-db. This script creates the MySQL database and initializes the grant tables with default privileges. It is usually executed only once, when first installing MySQL on a system. See *Note mysql-install-db::, *Note unix-postinstallation::, and *Note mysql-install-db::. * *Note `mysql_secure_installation': mysql-secure-installation. This program enables you to improve the security of your MySQL installation. SQL. See *Note mysql-secure-installation::. * *Note `mysql_tzinfo_to_sql': 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). SQL. See *Note mysql-tzinfo-to-sql::. * *Note `mysql_upgrade': 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 *Note mysql-upgrade::. MySQL client programs: * *Note `mysql': mysql. The command-line tool for interactively entering SQL statements or executing them from a file in batch mode. See *Note mysql::. * *Note `mysqladmin': 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. *Note `mysqladmin': mysqladmin. can also be used to retrieve version, process, and status information from the server. See *Note mysqladmin::. * *Note `mysqlcheck': mysqlcheck. A table-maintenance client that checks, repairs, analyzes, and optimizes tables. See *Note mysqlcheck::. * *Note `mysqldump': mysqldump. A client that dumps a MySQL database into a file as SQL, text, or XML. See *Note mysqldump::. * *Note `mysqlimport': mysqlimport. A client that imports text files into their respective tables using *Note `LOAD DATA INFILE': load-data. See *Note mysqlimport::. * *Note `mysqlshow': mysqlshow. A client that displays information about databases, tables, columns, and indexes. See *Note mysqlshow::. * *Note `mysqlslap': 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 *Note mysqlslap::. MySQL administrative and utility programs: * *Note `innochecksum': innochecksum. An offline `InnoDB' offline file checksum utility. See *Note innochecksum::. * *Note `myisam_ftdump': myisam-ftdump. A utility that displays information about full-text indexes in `MyISAM' tables. See *Note myisam-ftdump::. * *Note `myisamchk': myisamchk. A utility to describe, check, optimize, and repair `MyISAM' tables. See *Note myisamchk::. * *Note `myisamlog': myisamlog. A utility that processes the contents of a `MyISAM' log file. See *Note myisamlog::. * *Note `myisampack': myisampack. A utility that compresses `MyISAM' tables to produce smaller read-only tables. See *Note myisampack::. * *Note `mysqlaccess': mysqlaccess. A script that checks the access privileges for a host name, user name, and database combination. See *Note mysqlaccess::. * *Note `mysqlbinlog': 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 *Note mysqlbinlog::. * *Note `mysqldumpslow': mysqldumpslow. A utility to read and summarize the contents of a slow query log. See *Note mysqldumpslow::. * *Note `mysqlhotcopy': mysqlhotcopy. A utility that quickly makes backups of `MyISAM' tables while the server is running. See *Note mysqlhotcopy::. * `mysqlmanager' The MySQL Instance Manager, a program for monitoring and managing MySQL servers. See *Note instance-manager::. *Important*: MySQL Instance Manager has been deprecated and is removed in MySQL 5.5. * *Note `mysql_convert_table_format': mysql-convert-table-format. A utility that converts tables in a database to use a given storage engine. See *Note mysql-convert-table-format::. * *Note `mysql_find_rows': mysql-find-rows. A utility that reads files containing SQL statements (such as update logs) and extracts statements that match a given regular expression. See *Note mysql-find-rows::. * *Note `mysql_fix_extensions': mysql-fix-extensions. A utility that converts the extensions for `MyISAM' table files to lowercase. This can be useful after transferring the files from a system with case-insensitive file names to a system with case-sensitive file names. See *Note mysql-fix-extensions::. * *Note `mysql_setpermission': mysql-setpermission. A utility for interactively setting permissions in the MySQL grant tables. See *Note mysql-setpermission::. * *Note `mysql_waitpid': mysql-waitpid. A utility that kills the process with a given process ID. See *Note mysql-waitpid::. * *Note `mysql_zap': mysql-zap. A utility that kills processes that match a pattern. See *Note mysql-zap::. MySQL program-development utilities: * *Note `msql2mysql': msql2mysql. A shell script that converts `mSQL' programs to MySQL. It doesn't handle every case, but it gives a good start when converting. See *Note msql2mysql::. * *Note `mysql_config': mysql-config. A shell script that produces the option values needed when compiling MySQL programs. See *Note mysql-config::. * *Note `my_print_defaults': my-print-defaults. A utility that shows which options are present in option groups of option files. See *Note my-print-defaults::. * *Note `resolve_stack_dump': resolve-stack-dump. A utility program that resolves a numeric stack trace dump to symbols. See *Note resolve-stack-dump::. Miscellaneous utilities: * *Note `perror': perror. A utility that displays the meaning of system or MySQL error codes. See *Note perror::. * *Note `replace': replace-utility. A utility program that performs string replacement in the input text. See *Note replace-utility::. * *Note `resolveip': resolveip. A utility program that resolves a host name to an IP address or vice versa. See *Note resolveip::. Oracle Corporation also provides the *Note MySQL Workbench: 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 *Note MySQL Notifier for Microsoft Windows: windows-notifier. and *Note MySQL for Excel: mysql-for-excel. MySQL client programs that communicate with the server using the MySQL client/server library use the following environment variables. This table describes environment variables used by MySQL client programs that communicate with the server using the MySQL client/server library. 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 *Note environment-variables::. Use of `MYSQL_PWD' is insecure. See *Note password-security-user::.  File: manual.info, Node: programs-using, Next: programs-server, Prev: programs-overview, Up: programs 4.2 Using MySQL Programs ======================== * Menu: * invoking-programs:: Invoking MySQL Programs * connecting:: Connecting to the MySQL Server * program-options:: Specifying Program Options * setting-environment-variables:: Setting Environment Variables  File: manual.info, Node: invoking-programs, Next: connecting, Prev: programs-using, Up: programs-using 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 *Note program-options::. Nonoption arguments (arguments with no leading dash) provide additional information to the program. For example, the *Note `mysql': 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 *Note 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 *Note `mysql': mysql. is installed in `/usr/local/mysql/bin', you can run the program by invoking it as *Note `mysql': 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 *Note 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.  File: manual.info, Node: connecting, Next: program-options, Prev: invoking-programs, Up: programs-using 4.2.2 Connecting to the MySQL Server ------------------------------------ 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 *Note `mysql': mysql. client program, but the principles apply to other clients such as *Note `mysqldump': mysqldump, *Note `mysqladmin': mysqladmin, or *Note `mysqlshow': mysqlshow. This command invokes *Note `mysql': 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 *Note `mysql': mysql, the first nonoption argument is taken as the name of the default database. If there is no such option, *Note `mysql': 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=mypass mydb shell> mysql -h localhost -u myname -pmypass 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 *Note 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. 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: * `--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. This table lists permissible `--protocol' option values, the connection protocol for each value, and the platforms on which each value may be used. `--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 *Note ssl-options::. * `--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 *Note option-files::, discusses option files further. * You can specify some connection parameters using environment variables. The host can be specified for *Note `mysql': mysql. using `MYSQL_HOST'. The MySQL user name can be specified using `USER' (this is for Windows and NetWare only). The password can be specified using `MYSQL_PWD', although this is insecure; see *Note password-security-user::. For a list of variables, see *Note environment-variables::.  File: manual.info, Node: program-options, Next: setting-environment-variables, Prev: connecting, Up: programs-using 4.2.3 Specifying Program Options -------------------------------- * Menu: * command-line-options:: Using Options on the Command Line * option-modifiers:: Program Option Modifiers * option-files:: Using Option Files * option-file-options:: Command-Line Options that Affect Option-File Handling * program-variables:: Using Options to Set Program Variables * option-defaults-equals:: Option Defaults, Options Expecting Values, and the `=' Sign 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 *Note 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 *Note 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 *Note `mysql': 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 *Note `mysql': 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 reading 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. An option can be specified by writing it in full or as any unambiguous prefix. For example, the `--compress' option can be given to *Note `mysqldump': mysqldump. as `--compr', but not as `--comp' because the latter is ambiguous: shell> mysqldump --comp mysqldump: ambiguous option '--comp' (compatible, compress) Be aware that the use of option prefixes can cause problems in the event that new options are implemented for a program. A prefix that is unambiguous now might become ambiguous in the future.  File: manual.info, Node: command-line-options, Next: option-modifiers, Prev: program-options, Up: program-options 4.2.3.1 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 *Note `mysql': mysql. to use a password value of `test', but specifies no default database. The second instructs *Note `mysql': 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 *Note `mysqladmin': mysqladmin. to ping the server 1024 times, sleeping 10 seconds between each ping: mysql> mysqladmin --count=1K --sleep=10 ping 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 *Note `mysql': mysql. to pass SQL statements to the server. When this option is used, *Note `mysql': 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: mysql> 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 that the long form (`--execute') is followed by an equal 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.1.5-alpha-log | +-----------------+ +---------------------+ | NOW() | +---------------------+ | 2006-01-05 21:19:04 | +---------------------+ The `--execute' or `-e' option may also be used to pass commands in an analogous fashion to the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. management client for MySQL Cluster. See *Note mysql-cluster-install-shutdown-restart::, for an example.  File: manual.info, Node: option-modifiers, Next: option-files, Prev: command-line-options, Up: program-options 4.2.3.2 Program Option Modifiers ................................ Some options are `boolean' and control behavior that can be turned on or off. For example, the *Note `mysql': 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 *Note `mysql': 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 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 '--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. *Note `mysqld': mysqld. enables a limit to be placed on how large client programs can set dynamic system variables. To do this, use a `--maximum' prefix with the variable name. For example, `--maximum-query_cache_size=4M' prevents any client from making the query cache size larger than 4MB.  File: manual.info, Node: option-files, Next: option-file-options, Prev: option-modifiers, Up: program-options 4.2.3.3 Using Option Files .......................... Most MySQL programs can read startup options from option files (also 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. For the MySQL server, MySQL provides a number of *Note preconfigured option files: server-configuration-defaults. To determine whether a program reads option files, invoke it with the `--help' option. (For *Note `mysqld': 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*: Option files used with MySQL Cluster programs are covered in *Note mysql-cluster-configuration::. On Windows, MySQL programs read startup options from the following files, in the specified order (top items are used first). This table lists file names on Windows operating systems where MySQL programs read startup options. The purpose of each file is described. File Name Purpose ``%PROGRAMDATA%'\MySQL\MySQLGlobal options Server 5.1\my.ini', ``%PROGRAMDATA%'\MySQL\MySQL Server 5.1\my.cnf' ``%WINDIR%'\my.ini', Global options ``%WINDIR%'\my.cnf' `C:\my.ini', Global options `C:\my.cnf' `INSTALLDIR\my.ini', Global options `INSTALLDIR\my.cnf' `defaults-extra-file' The file specified with `--defaults-extra-file=PATH', if any `%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'. You can determine its exact location from the value of the `WINDIR' environment variable using the following command: C:\> echo %WINDIR% INSTALLDIR represents the MySQL installation directory. This is typically `C:\PROGRAMDIR\MySQL\MySQL 5.1 Server' where PROGRAMDIR represents the programs directory (usually `Program Files' on English-language versions of Windows), when MySQL 5.1 has been installed using the installation and configuration wizards. See *Note mysql-config-wizard-starting::. On Unix, Linux and Mac OS X, MySQL programs read startup options from the following files, in the specified order (top items are used first). This table lists file names on Unix, Linux and Mac OS X operating systems where MySQL programs read startup options. The purpose of each file is described. File Name Purpose `/etc/my.cnf' Global options `/etc/mysql/my.cnf' Global options (as of MySQL 5.1.15) `SYSCONFDIR/my.cnf' Global options `$MYSQL_HOME/my.cnf' Server-specific options `defaults-extra-file' The file specified with `--defaults-extra-file=PATH', if any `~/.my.cnf' User-specific options `~' represents the current user's home directory (the value of `$HOME'). SYSCONFDIR represents the directory specified with the `--sysconfdir' option to `configure' when MySQL was built. By default, this is the `etc' directory located under the compiled-in installation directory. This location is used as of MySQL 5.1.10. (From 5.1.10 to 5.1.22, it was read last, after `~/.my.cnf'.) `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 *Note `mysqld_safe': mysqld-safe. program, *Note `mysqld_safe': mysqld-safe. attempts to set `MYSQL_HOME' as follows: * Let BASEDIR and DATADIR represent the path names of the MySQL base directory and data directory, respectively. * If there is a `my.cnf' file in DATADIR but not in BASEDIR, *Note `mysqld_safe': mysqld-safe. sets `MYSQL_HOME' to DATADIR. * Otherwise, if `MYSQL_HOME' is not set and there is no `my.cnf' file in DATADIR, *Note `mysqld_safe': mysqld-safe. sets `MYSQL_HOME' to BASEDIR. In MySQL 5.1, use of DATADIR as the location for `my.cnf' is deprecated. Typically, DATADIR is `/usr/local/mysql/data' for a binary installation or `/usr/local/var' for a source installation. Note that this is the data directory location that was specified at configuration time, not the one specified with the `--datadir' option when *Note `mysqld': mysqld. starts. Use of `--datadir' at runtime has no effect on where the server looks for option files, because it looks for them before processing any options. MySQL looks for option files in the order just described and reads any that exist. If an option file that you want to use does not exist, create it with a plain text editor. If multiple instances of a given option are found, the last instance takes precedence. There is one exception: For *Note `mysqld': 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. *Note*: On Unix platforms, MySQL ignores configuration files that are world-writable. This is intentional as a security measure. 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. The syntax for specifying options in an option file is similar to command-line syntax (see *Note 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. You can optionally enclose the value 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. The escaping rules in option files are: * If a backslash is followed by a valid escape sequence character, the sequence is converted to the character represented by the sequence. For example, ``\s'' is converted to a space. * If a backslash is not followed by a valid escape sequence character, it 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 *Note 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.1' in an option file. This can be done several ways. Some examples: basedir="C:\Program Files\MySQL\MySQL Server 5.1" basedir="C:\\Program Files\\MySQL\\MySQL Server 5.1" basedir="C:/Program Files/MySQL/MySQL Server 5.1" basedir=C:\\Program\sFiles\\MySQL\\MySQL\sServer\s5.1 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 *Note `mysqld': mysqld. server and the *Note `mysql': mysql. client program, respectively. The `[client]' option group is read by all client programs (but _not_ by *Note `mysqld': mysqld.). This enables you to specify options that apply to all clients. For example, `[client]' is the perfect group to use to specify the password that you use to connect to the server. (But make sure that the option file is readable and writable only by yourself, so that other people cannot find out 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. 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 The preceding option file uses `VAR_NAME=VALUE' syntax for the lines that set the `key_buffer_size' and `max_allowed_packet' variables. 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 [mysqlhotcopy] interactive-timeout If you want to create option groups that should be read by *Note `mysqld': mysqld. servers from a specific MySQL release series only, you can do this by using groups with names of `[mysqld-5.0]', `[mysqld-5.1]', and so forth. The following group indicates that the `--new' option should be used only by MySQL servers with 5.1.x version numbers: [mysqld-5.1] new 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 There is no guarantee about the order in which the option files in the directory will be read. *Note*: Currently, 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 *Note `mysqld': mysqld, only the `[mysqld]' group in `/home/mydir/myopt.cnf' is used. If the file is processed by *Note `mysqladmin': 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.  File: manual.info, Node: option-file-options, Next: program-variables, Prev: option-files, Up: program-options 4.2.3.4 Command-Line Options that Affect Option-File Handling ............................................................. Most MySQL programs that support option files handle the following options. They affect option-file handling, so 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' or `--defaults-extra-file'. * On Windows, if the server is started with the `--defaults-file' and `--install' options, `--install' must be first. See *Note windows-start-service::. When specifying file names, you should 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. If the file does not exist or is otherwise inaccessible, the program exits with an error. FILE_NAME is the full path name to the file. * `--defaults-file=FILE_NAME' Use only the given option file. If the file does not exist or is otherwise inaccessible, the program exits with an error. FILE_NAME is the full path name to the file. * `--defaults-group-suffix=STR' If this option is given, the program reads not only its usual option groups, but also groups with the usual names and a suffix of STR. For example, the *Note `mysql': mysql. client normally reads the `[client]' and `[mysql]' groups. If the `--defaults-group-suffix=_other' option is given, *Note `mysql': mysql. also reads the `[client_other]' and `[mysql_other]' groups. * `--no-defaults' Do not read any option files. If a program does not start because it is reading unknown options from an option file, `--no-defaults' can be used to prevent the program from reading them. * `--print-defaults' Print the program name and all options that it gets from option files.  File: manual.info, Node: program-variables, Next: option-defaults-equals, Prev: option-file-options, Up: program-options 4.2.3.5 Using Options to Set Program Variables .............................................. Many MySQL programs have internal variables that can be set at runtime using the *Note `SET': set-statement. statement. See *Note set-statement::, and *Note 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, *Note `mysql': mysql. has a `max_allowed_packet' variable that controls the maximum size of its communication buffer. To set the `max_allowed_packet' variable for *Note `mysql': 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 *Note `mysql': 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 *Note `SET': set-statement. at runtime. On the other hand, with *Note `SET': set-statement. 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*: Before MySQL 4.0.2, the only syntax for setting program variables was `--set-variable=OPTION=VALUE' (or `set-variable=OPTION=VALUE' in option files). Underscores cannot be given as dashes, and the variable name must be specified in full. This syntax still is recognized, but is deprecated and is removed in MySQL 5.5.  File: manual.info, Node: option-defaults-equals, Prev: program-variables, Up: program-options 4.2.3.6 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 equal sign is not required, and so the following is also valid: shell> mysql --host tonfisk --user jon In both cases, the *Note `mysql': 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.1.73 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, *Note `mysql': 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 *Note `mysql': 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 equal 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 *Note `mysqld_safe': 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 080111 22:53:32 InnoDB: Started; log sequence number 0 46409 `/usr/local/mysql/libexec/mysqld: Too many arguments (first extra is 'my-errors'). Use --verbose --help to get a list of available options' 080111 22:53:32 `[ERROR] Aborting' 080111 22:53:32 InnoDB: Starting shutdown... 080111 22:53:34 InnoDB: Shutdown completed; log sequence number 0 46409 080111 22:53:34 [Note] /usr/local/mysql/libexec/mysqld: Shutdown complete 080111 22:53:34 mysqld_safe mysqld from pid file /usr/local/mysql/var/tonfisk.pid ended Because the `--log-error' option supplies a default value, you must use an equal 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 *Note `mysql': 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 equal sign is not assumed. Suppose the `my.cnf' file is as shown here: [mysql] user jon Trying to start *Note `mysql': 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.1.73 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 equal 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.1.73 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)  File: manual.info, Node: setting-environment-variables, Prev: program-options, Up: programs-using 4.2.4 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. *Note 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 or NetWare, 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.  File: manual.info, Node: programs-server, Next: programs-installation, Prev: programs-using, Up: programs 4.3 MySQL Server and Server-Startup Programs ============================================ * Menu: * mysqld:: `mysqld' --- The MySQL Server * mysqld-safe:: `mysqld_safe' --- MySQL Server Startup Script * mysql-server:: `mysql.server' --- MySQL Server Startup Script * mysqld-multi:: `mysqld_multi' --- Manage Multiple MySQL Servers This section describes *Note `mysqld': mysqld, the MySQL server, and several programs that are used to start the server.  File: manual.info, Node: mysqld, Next: mysqld-safe, Prev: programs-server, Up: programs-server 4.3.1 `mysqld' -- The MySQL Server ---------------------------------- *Note `mysqld': 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. When MySQL server starts, it listens for network connections from client programs and manages access to databases on behalf of those clients. The *Note `mysqld': 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 *Note mysqld-server::. For information about installing MySQL and setting up the initial configuration, see *Note installing::.  File: manual.info, Node: mysqld-safe, Next: mysql-server, Prev: mysqld, Up: programs-server 4.3.2 `mysqld_safe' -- MySQL Server Startup Script -------------------------------------------------- *Note `mysqld_safe': mysqld-safe. is the recommended way to start a *Note `mysqld': mysqld. server on Unix and NetWare. *Note `mysqld_safe': mysqld-safe. adds some safety features such as restarting the server when an error occurs and logging runtime information to an error log file. Descriptions of error logging and NetWare-specific behaviors are given later in this section. *Note*: In MySQL 5.1.20 (only), the default error logging behavior with *Note `mysqld_safe': mysqld-safe. is to write errors to `syslog' on systems that support the `logger' program. This differs from the default behavior of writing an error log file for other versions. *In 5.1.20, logging to `syslog' may fail to operate correctly in some cases; if so, use `--skip-syslog' to use the default log file or `--log-error=FILE_NAME' to specify a log file name explicitly.* *Note `mysqld_safe': mysqld-safe. tries to start an executable named *Note `mysqld': 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 *Note `mysqld_safe': mysqld-safe. You can also use `--ledir' to indicate the directory where *Note `mysqld_safe': mysqld-safe. should look for the server. Many of the options to *Note `mysqld_safe': mysqld-safe. are the same as the options to *Note `mysqld': mysqld. See *Note server-options::. Options unknown to *Note `mysqld_safe': mysqld-safe. are passed to *Note `mysqld': 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 *Note option-files::. *Note `mysqld_safe': 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, *Note `mysqld_safe': mysqld-safe. will find and use the `--log-error' option: [mysqld] log-error=error.log For backward compatibility, *Note `mysqld_safe': mysqld-safe. also reads `[safe_mysqld]' sections, although you should rename such sections to `[mysqld_safe]' in MySQL 5.1 installations. *Note `mysqld_safe': mysqld-safe. supports the options in the following list. It also reads option files and supports the options for processing them described at *Note option-file-options::. *`mysqld_safe' Options* Format Option File Description Introduced -autoclose autoclose On NetWare, mysqld_safe provides a screen presence -basedir=pathbasedir The path to the MySQL installation directory -core-file-size=sizecore-file-sizeThe size of the core file that mysqld should be able to create -datadir=pathdatadir The path to the data directory -defaults-extra-file=pathdefaults-extra-fileThe name of an option file to be read in addition to the usual option files -defaults-file=file_namedefaults-fileThe name of an option file to be read instead of the usual option files -help Display a help message and exit -ledir=path ledir Use this option to indicate the path name to the directory where the server is located -log-error=file_namelog-error Write the error log to the given file -mysqld=prog_namemysqld The name of the server program (in the ledir directory) that you want to start -mysqld-version=suffixmysqld-versionThis option is similar to the -mysqld option, but you specify only the suffix for the server program name -nice=prioritynice Use the nice program to set the server's scheduling priority to the given value -no-defaultsno-defaults Do not read any option files -open-files-limit=countopen-files-limitThe number of files that mysqld should be able to open -pid-file=file_namepid-file=file_nameThe path name of the process ID file -port=numberport The port number that the server should use when listening for TCP/IP connections -skip-kill-mysqldskip-kill-mysqldDo not try to kill stray mysqld processes -skip-syslogskip-syslog Do not write error messages 5.1.20 to syslog; use error log file -socket=pathsocket The Unix socket file that the server should use when listening for local connections -syslog syslog Write error messages to 5.1.20 syslog -syslog-tag=tagsyslog-tag Tag suffix for messages 5.1.21 written to syslog -timezone=timezonetimezone Set the TZ time zone environment variable to the given option value -user={user_name|user_id}user Run the mysqld server as the user having the name user_name or the numeric user ID user_id * `--help' Display a help message and exit. * `--autoclose' (NetWare only) On NetWare, *Note `mysqld_safe': mysqld-safe. provides a screen presence. When you unload (shut down) the *Note `mysqld_safe': mysqld-safe. NLM, the screen does not by default go away. Instead, it prompts for user input: ** If you want NetWare to close the screen automatically instead, use the `--autoclose' option to *Note `mysqld_safe': mysqld-safe. * `--basedir=PATH' The path to the MySQL installation directory. * `--core-file-size=SIZE' The size of the core file that *Note `mysqld': mysqld. should be able to create. The option value is passed to `ulimit -c'. * `--datadir=PATH' The path to the data directory. * `--defaults-extra-file=PATH' The name of an option file to be read in addition to the usual option files. This must be the first option on the command line if it is used. If the file does not exist or is otherwise inaccessible, the server will exit with an error. * `--defaults-file=FILE_NAME' The name of an option file to be read instead of the usual option files. This must be the first option on the command line if it is used. * `--ledir=PATH' If *Note `mysqld_safe': mysqld-safe. cannot find the server, use this option to indicate the path name to the directory where the server is located. * `--log-error=FILE_NAME' Write the error log to the given file. See *Note error-log::. * `--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 *Note `mysqld_safe': mysqld-safe. cannot find the server, use the `--ledir' option to indicate the path name to the directory where the server is located. * `--mysqld-version=SUFFIX' This option is similar to the `--mysqld' option, but you specify only the suffix for the server program name. The basename is assumed to be *Note `mysqld': mysqld. For example, if you use `--mysqld-version=debug', *Note `mysqld_safe': mysqld-safe. starts the *Note `mysqld-debug': mysqld. program in the `ledir' directory. If the argument to `--mysqld-version' is empty, *Note `mysqld_safe': mysqld-safe. uses *Note `mysqld': mysqld. in the `ledir' directory. * `--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. This must be the first option on the command line if it is used. * `--open-files-limit=COUNT' The number of files that *Note `mysqld': mysqld. should be able to open. The option value is passed to `ulimit -n'. Note that you need to start *Note `mysqld_safe': mysqld-safe. as `root' for this to work properly! * `--pid-file=FILE_NAME' The path name of the process ID file. * `--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 *Note `mysqld': 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. These options were added in MySQL 5.1.20. When `syslog' is used, the `daemon.err' syslog priority/facility is used for all log messages. * `--syslog-tag=TAG' For logging to `syslog', messages from *Note `mysqld_safe': mysqld-safe. and *Note `mysqld': mysqld. are written with a tag of `mysqld_safe' and `mysqld', respectively. To specify a suffix for the tag, use `--syslog-tag=TAG', which modifies the tags to be `mysqld_safe-TAG' and `mysqld-TAG'. This option was added in MySQL 5.1.21. * `--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 *Note `mysqld': 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 *Note `mysqld_safe': 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 *Note `mysqld_safe': 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 *Note installation-layouts::.) *Note `mysqld_safe': 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 *Note `mysqld_safe': mysqld-safe. is invoked). For binary distributions, *Note `mysqld_safe': 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 *Note `mysqld_safe': 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, *Note `mysqld_safe': 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 *Note `mysqld_safe': 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 *Note `mysqld_safe': mysqld-safe. from the MySQL installation directory: shell> cd MYSQL_INSTALLATION_DIRECTORY shell> bin/mysqld_safe & If *Note `mysqld_safe': mysqld-safe. fails, even when invoked from the MySQL installation directory, you can specify the `--ledir' and `--datadir' options to indicate the directories in which the server and databases are located on your system. When you use *Note `mysqld_safe': mysqld-safe. to start *Note `mysqld': mysqld, *Note `mysqld_safe': mysqld-safe. arranges for error (and notice) messages from itself and from *Note `mysqld': mysqld. to go to the same destination. As of MySQL 5.1.20, there are several *Note `mysqld_safe': mysqld-safe. options for controlling the destination of these messages: * `--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. * `--log-error=FILE_NAME': Write error messages to the named error file. If none of these options is given, the default is `--skip-syslog'. *Note*: In MySQL 5.1.20 _only_, the default is `--syslog'. This differs from logging behavior for other versions of MySQL, for which the default is to write messages to the default error log file. If `--syslog' and `--log-error' are both given, a warning is issued and `--log-error' takes precedence. When *Note `mysqld_safe': 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'. Before MySQL 5.1.20, error logging is controlled only with the `--log-error' option. If it is given, messages go to the named error file. Otherwise, messages go to the default error file. Normally, you should not edit the *Note `mysqld_safe': mysqld-safe. script. Instead, configure *Note `mysqld_safe': mysqld-safe. by using command-line options or options in the `[mysqld_safe]' section of a `my.cnf' option file. In rare cases, it might be necessary to edit *Note `mysqld_safe': mysqld-safe. to get it to start the server properly. However, if you do this, your modified version of *Note `mysqld_safe': mysqld-safe. might be overwritten if you upgrade MySQL in the future, so you should make a copy of your edited version that you can reinstall. On NetWare, *Note `mysqld_safe': mysqld-safe. is a NetWare Loadable Module (NLM) that is ported from the original Unix shell script. It starts the server as follows: 1. Runs a number of system and option checks. 2. Runs a check on `MyISAM' tables. 3. Provides a screen presence for the MySQL server. 4. Starts *Note `mysqld': mysqld, monitors it, and restarts it if it terminates in error. 5. Sends error messages from *Note `mysqld': mysqld. to the `HOST_NAME.err' file in the data directory. 6. Sends *Note `mysqld_safe': mysqld-safe. screen output to the `HOST_NAME.safe' file in the data directory.  File: manual.info, Node: mysql-server, Next: mysqld-multi, Prev: mysqld-safe, Up: programs-server 4.3.3 `mysql.server' -- MySQL Server Startup Script --------------------------------------------------- MySQL distributions on Unix include a script named *Note `mysql.server': mysql-server. 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 Mac OS X Startup Item for MySQL. *Note `mysql.server': mysql-server. can be found in the `support-files' directory under your MySQL installation directory or in a MySQL source distribution. If you use the Linux server RPM package (`MySQL-server-VERSION.rpm'), the *Note `mysql.server': mysql-server. script will be installed in the `/etc/init.d' directory with the name `mysql'. You need not install it manually. See *Note linux-installation-rpm::, for more information on the Linux RPM packages. Some vendors provide RPM packages that install a startup script under a different name such as *Note `mysqld': mysqld. If you install MySQL from a source distribution or using a binary distribution format that does not install *Note `mysql.server': mysql-server. automatically, you can install it manually. Instructions are provided in *Note automatic-start::. *Note `mysql.server': mysql-server. reads options from the `[mysql.server]' and `[mysqld]' sections of option files. For backward compatibility, it also reads `[mysql_server]' sections, although you should rename such sections to `[mysql.server]' when using MySQL 5.1. *Note `mysql.server': mysql-server. supports the following options. * `--basedir=PATH' The path to the MySQL installation directory. * `--datadir=PATH' 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. * `--service-startup-timeout=FILE_NAME' How long in seconds to wait for confirmation of server startup. If the server does not start within this time, *Note `mysql.server': 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). This option was added in MySQL 5.1.17. Before that, a value of 900 is always used. * `--use-mysqld_safe' Use *Note `mysqld_safe': mysqld-safe. to start the server. This is the default. * `--use-manager' Use Instance Manager to start the server. * `--user=USER_NAME' The login user name to use for running *Note `mysqld': mysqld.  File: manual.info, Node: mysqld-multi, Prev: mysql-server, Up: programs-server 4.3.4 `mysqld_multi' -- Manage Multiple MySQL Servers ----------------------------------------------------- *Note `mysqld_multi': mysqld-multi. is designed to manage several *Note `mysqld': 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. The MySQL Instance Manager is an alternative means of managing multiple servers (see *Note instance-manager::). *Note `mysqld_multi': mysqld-multi. searches for groups named `[mysqldN]' in `my.cnf' (or in the file named by the `--config-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 *Note `mysqld_multi': 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 *Note `mysqld': mysqld. (See, for example, *Note 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 *Note multiple-servers::. To invoke *Note `mysqld_multi': mysqld-multi, use the following syntax: shell> mysqld_multi [OPTIONS] {start|stop|report} [GNR[,GNR] ...] `start', `stop', 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, *Note `mysqld_multi': 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 As of MySQL 5.1.18, *Note `mysqld_multi': 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.) Before MySQL 5.1.18, the preceding options are not recognized. Files in the standard locations are read, and any file named by the `--config-file=FILE_NAME' option, if one is given. A file named by `--config-file' is read only for `[mysqldN]' option groups, not the `[mysqld_multi]' group. Option files read are searched for `[mysqld_multi]' and `[mysqldN]' option groups. The `[mysqld_multi]' group can be used for options to *Note `mysqld_multi': mysqld-multi. itself. `[mysqldN]' groups can be used for options passed to specific *Note `mysqld': mysqld. instances. As of MySQL 5.1.35, the `[mysqld]' or `[mysqld_safe]' groups can be used for common options read by all instances of *Note `mysqld': mysqld. or *Note `mysqld_safe': 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. Before MySQL 5.1.35, some versions of *Note `mysqld_multi': mysqld-multi. pass the `--no-defaults' options to instances, so these techniques are inapplicable. *Note `mysqld_multi': mysqld-multi. supports the following options. * `--help' Display a help message and exit. * `--config-file=FILE_NAME' As of MySQL 5.1.18, this option is deprecated. If given, it is treated the same way as `--defaults-extra-file', described earlier. `--config-file' is removed in MySQL 5.5. Before MySQL 5.1.18, this option specifies the name of an extra option file. It affects where *Note `mysqld_multi': mysqld-multi. looks for `[mysqldN]' option groups. Without this option, all options are read from the usual `my.cnf' file. The option does not affect where *Note `mysqld_multi': mysqld-multi. reads its own options, which are always taken from the `[mysqld_multi]' group in the usual `my.cnf' file. * `--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 *Note `mysqladmin': mysqladmin. binary to be used to stop servers. * `--mysqld=PROG_NAME' The *Note `mysqld': mysqld. binary to be used. Note that you can specify *Note `mysqld_safe': mysqld-safe. as the value for this option also. If you use *Note `mysqld_safe': 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 *Note `mysqld_safe': mysqld-safe. should start and the path name of the directory where the server is located. (See the descriptions for these options in *Note 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 *Note `mysqladmin': 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 *Note `mysqladmin': mysqladmin. * `--verbose' Be more verbose. * `--version' Display version information and exit. Some notes about *Note `mysqld_multi': mysqld-multi.: * *Most important*: Before using *Note `mysqld_multi': mysqld-multi. be sure that you understand the meanings of the options that are passed to the *Note `mysqld': mysqld. servers and _why_ you would want to have separate *Note `mysqld': mysqld. processes. Beware of the dangers of using multiple *Note `mysqld': 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 *Note multiple-servers::. * *Important*: Make sure that the data directory for each server is fully accessible to the Unix account that the specific *Note `mysqld': mysqld. process is started as. _Do not_ use the Unix ROOT account for this, unless you _know_ what you are doing. See *Note changing-mysql-user::. * Make sure that the MySQL account used for stopping the *Note `mysqld': mysqld. servers (with the *Note `mysqladmin': 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> GRANT SHUTDOWN ON *.* -> TO 'multi_admin'@'localhost' IDENTIFIED BY 'multipass'; See *Note privilege-system::. You have to do this for each *Note `mysqld': 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 *Note `mysqld_multi': mysqld-multi. * The Unix socket file and the TCP/IP port number must be different for every *Note `mysqld': 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 *Note `mysqld_safe': mysqld-safe. to start *Note `mysqld': mysqld. (for example, `--mysqld=mysqld_safe') Every *Note `mysqld': mysqld. should have its own process ID file. The advantage of using *Note `mysqld_safe': mysqld-safe. instead of *Note `mysqld': mysqld. is that *Note `mysqld_safe': mysqld-safe. monitors its *Note `mysqld': 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. Please note that the *Note `mysqld_safe': mysqld-safe. script might require that you start it from a certain place. This means that you might have to change location to a certain directory before running *Note `mysqld_multi': mysqld-multi. If you have problems starting, please see the *Note `mysqld_safe': mysqld-safe. script. Check especially the lines: ---------------------------------------------------------------- MY_PWD=`pwd` # Check if we are starting this relative (for the binary release) if test -d $MY_PWD/data/mysql -a \ -f ./share/mysql/english/errmsg.sys -a \ -x ./bin/mysqld ---------------------------------------------------------------- The test performed by these lines should be successful, or you might encounter problems. See *Note mysqld-safe::. * You might want to use the `--user' option for *Note `mysqld': mysqld, but to do this you need to run the *Note `mysqld_multi': 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 *Note `mysqld': mysqld. processes are started under your own Unix account. The following example shows how you might set up an option file for use with *Note `mysqld_multi': mysqld-multi. The order in which the *Note `mysqld': 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 file should probably be in your home dir (~/.my.cnf) # or /etc/my.cnf # Version 2.1 by Jani Tolonen [mysqld_multi] mysqld = /usr/local/bin/mysqld_safe mysqladmin = /usr/local/bin/mysqladmin user = multi_admin password = multipass [mysqld2] socket = /tmp/mysql.sock2 port = 3307 pid-file = /usr/local/mysql/var2/hostname.pid2 datadir = /usr/local/mysql/var2 language = /usr/local/share/mysql/english user = john [mysqld3] socket = /tmp/mysql.sock3 port = 3308 pid-file = /usr/local/mysql/var3/hostname.pid3 datadir = /usr/local/mysql/var3 language = /usr/local/share/mysql/swedish user = monty [mysqld4] socket = /tmp/mysql.sock4 port = 3309 pid-file = /usr/local/mysql/var4/hostname.pid4 datadir = /usr/local/mysql/var4 language = /usr/local/share/mysql/estonia user = tonu [mysqld6] socket = /tmp/mysql.sock6 port = 3311 pid-file = /usr/local/mysql/var6/hostname.pid6 datadir = /usr/local/mysql/var6 language = /usr/local/share/mysql/japanese user = jani See *Note option-files::.  File: manual.info, Node: programs-installation, Next: programs-client, Prev: programs-server, Up: programs 4.4 MySQL Installation-Related Programs ======================================= * Menu: * comp-err:: `comp_err' --- Compile MySQL Error Message File * make-win-bin-dist:: `make_win_bin_dist' --- Package MySQL Distribution as Zip Archive * mysqlbug:: `mysqlbug' --- Generate Bug Report * mysql-fix-privilege-tables:: `mysql_fix_privilege_tables' --- Upgrade MySQL System Tables * mysql-install-db:: `mysql_install_db' --- Initialize MySQL Data Directory * mysql-secure-installation:: `mysql_secure_installation' --- Improve MySQL Installation Security * mysql-tzinfo-to-sql:: `mysql_tzinfo_to_sql' --- Load the Time Zone Tables * mysql-upgrade:: `mysql_upgrade' --- Check and Upgrade MySQL Tables The programs in this section are used when installing or upgrading MySQL.  File: manual.info, Node: comp-err, Next: make-win-bin-dist, Prev: programs-installation, Up: programs-installation 4.4.1 `comp_err' -- Compile MySQL Error Message File ---------------------------------------------------- *Note `comp_err': comp-err. creates the `errmsg.sys' file that is used by *Note `mysqld': mysqld. to determine the error messages to display for different error codes. *Note `comp_err': comp-err. normally is run automatically when MySQL is built. It compiles the `errmsg.sys' file from the plaintext file located at `sql/share/errmsg.txt' in MySQL source distributions. *Note `comp_err': 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 *Note `comp_err': comp-err. like this: shell> comp_err [OPTIONS] *Note `comp_err': comp-err. supports the following options. * `--help', `-?' Display a help message and exit. * `--charset=PATH', `-C PATH' 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.txt'. * `--name_file=FILE_NAME', `-N FILE_NAME' The name of the error name file. The default is `mysqld_ername.h'. * `--out_dir=PATH', `-D PATH' 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.  File: manual.info, Node: make-win-bin-dist, Next: mysqlbug, Prev: comp-err, Up: programs-installation 4.4.2 `make_win_bin_dist' -- Package MySQL Distribution as Zip Archive ---------------------------------------------------------------------- This script is used on Windows after building a MySQL distribution from source to create executable programs. It packages the binaries and support files into a Zip archive that can be unpacked at the location where you want to install MySQL. *Note `make_win_bin_dist': make-win-bin-dist. is a shell script, so you must have Cygwin installed to use it. This program's use is subject to change. Currently, you invoke it as follows from the root directory of your source distribution: shell> make_win_bin_dist [OPTIONS] PACKAGE_BASENAME [COPY_DEF ...] The PACKAGE_BASENAME argument provides the basename for the resulting Zip archive. This name will be the name of the directory that results from unpacking the archive. Because you might want to include files of directories from other builds, you can instruct this script to copy them in for you, using COPY_DEF arguments, which have the form RELATIVE_DEST_NAME=SOURCE_NAME. Example: bin/mysqld-max.exe=../my-max-build/sql/release/mysqld.exe If you specify a directory, the entire directory will be copied. *Note `make_win_bin_dist': make-win-bin-dist. supports the following options. * `--debug' Pack the debug binaries and produce an error if they were not built. * `--embedded' Pack the embedded server and produce an error if it was not built. The default is to pack it if it was built. * `--exe-suffix=SUFFIX' Add a suffix to the basename of the *Note `mysql': mysql. binary. For example, a suffix of `-abc' produces a binary named `mysqld-abc.exe'. * `--no-debug' Do not pack the debug binaries even if they were built. * `--no-embedded' Do not pack the embedded server even if it was built. * `--only-debug' Use this option when the target for this build was `Debug', and you just want to replace the normal binaries with debug versions (that is, do not use separate `debug' directories).  File: manual.info, Node: mysqlbug, Next: mysql-fix-privilege-tables, Prev: make-win-bin-dist, Up: programs-installation 4.4.3 `mysqlbug' -- Generate Bug Report --------------------------------------- This program enables you to generate a bug report and send it to Oracle Corporation. It is a shell script and runs on Unix. 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. If you have no Web access, you can generate a bug report by using the *Note `mysqlbug': mysqlbug. script. *Note `mysqlbug': mysqlbug. helps you generate a report by determining much of the following information automatically, but if something important is missing, please include it with your message. *Note `mysqlbug': mysqlbug. can be found in the `scripts' directory (source distribution) and in the `bin' directory under your MySQL installation directory (binary distribution). Invoke *Note `mysqlbug': mysqlbug. without arguments: shell> mysqlbug The script will place you in an editor with a copy of the report to be sent. Edit the lines near the beginning that indicate the nature of the problem. Then write the file to save your changes, quit the editor, and *Note `mysqlbug': mysqlbug. will send the report by email.  File: manual.info, Node: mysql-fix-privilege-tables, Next: mysql-install-db, Prev: mysqlbug, Up: programs-installation 4.4.4 `mysql_fix_privilege_tables' -- Upgrade MySQL System Tables ----------------------------------------------------------------- *Note*: In MySQL 5.1.7, *Note `mysql_fix_privilege_tables': mysql-fix-privilege-tables. was superseded by *Note `mysql_upgrade': mysql-upgrade, which should be used instead. See *Note mysql-upgrade::. Some releases of MySQL introduce changes to the structure of the system tables in the `mysql' database to add new privileges or support new features. When you update to a new version of MySQL, you should update your system tables as well to make sure that their structure is up to date. Otherwise, there might be capabilities that you cannot take advantage of. *Note `mysql_fix_privilege_tables': mysql-fix-privilege-tables. is an older script that previously was used to upgrade the system tables in the `mysql' database after a MySQL upgrade. Before running *Note `mysql_fix_privilege_tables': mysql-fix-privilege-tables, make a backup of your `mysql' database. On Unix or Unix-like systems, update the system tables by running the *Note `mysql_fix_privilege_tables': mysql-fix-privilege-tables. script: shell> mysql_fix_privilege_tables You must run this script while the server is running. It attempts to connect to the server running on the local host as `root'. If your `root' account requires a password, indicate the password on the command line like this: shell> mysql_fix_privilege_tables --password=ROOT_PASSWORD The *Note `mysql_fix_privilege_tables': mysql-fix-privilege-tables. script performs any actions necessary to convert your system tables to the current format. You might see some `Duplicate column name' warnings as it runs; you can ignore them. After running the script, stop the server and restart it so that any changes made to the system tables take effect. On Windows systems, MySQL distributions include a `mysql_fix_privilege_tables.sql' SQL script that you can run using the *Note `mysql': mysql. client. For example, if your MySQL installation is located at `C:\Program Files\MySQL\MySQL Server 5.1', the commands look like this: C:\> cd "C:\Program Files\MySQL\MySQL Server 5.1" C:\> bin\mysql -u root -p mysql mysql> SOURCE share/mysql_fix_privilege_tables.sql *Note*: Prior to version 5.1.17, the `mysql_fix_privilege_tables.sql' script is found in the `scripts' directory. The *Note `mysql': mysql. command will prompt you for the `root' password; enter it when prompted. If your installation is located in some other directory, adjust the path names appropriately. As with the Unix procedure, you might see some `Duplicate column name' warnings as *Note `mysql': mysql. processes the statements in the `mysql_fix_privilege_tables.sql' script; you can ignore them. After running the script, stop the server and restart it.  File: manual.info, Node: mysql-install-db, Next: mysql-secure-installation, Prev: mysql-fix-privilege-tables, Up: programs-installation 4.4.5 `mysql_install_db' -- Initialize MySQL Data Directory ----------------------------------------------------------- *Note `mysql_install_db': mysql-install-db. initializes the MySQL data directory and creates the system tables that it contains, if they do not exist. *Note `mysql_install_db': mysql-install-db. is a shell script and is available only on Unix platforms. To invoke *Note `mysql_install_db': mysql-install-db, use the following syntax: shell> mysql_install_db [OPTIONS] Because the MySQL server, *Note `mysqld': mysqld, needs to access the data directory when it runs later, you should either run *Note `mysql_install_db': mysql-install-db. from the same system account that will be used for running *Note `mysqld': mysqld. or run it as `root' and use the `--user' option to indicate the user name that *Note `mysqld': mysqld. will run as. It might be necessary to specify other options such as `--basedir' or `--datadir' if *Note `mysql_install_db': mysql-install-db. does not use 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 *Note `mysql_install_db': mysql-install-db. needs to invoke *Note `mysqld': mysqld. with the `--bootstrap' and `--skip-grant-tables' options. If MySQL was configured with the `--disable-grant-options' option, `--bootstrap' and `--skip-grant-tables' will be disabled (see *Note source-configuration-options::). To handle this, set the `MYSQLD_BOOTSTRAP' environment variable to the full path name of a server that has all options enabled. *Note `mysql_install_db': mysql-install-db. will use that server. *Note*: If you have set a custom `TMPDIR' environment variable when performing the installation, and the specified directory is not accessible, *Note `mysql_install_db': mysql-install-db. may fail. If so, unset `TMPDIR' or set `TMPDIR' to point to the system temporary directory (usually `/tmp'). *Note `mysql_install_db': 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. (Options that are common to *Note `mysqld': mysqld. can also be specified in the `[mysqld]' group.) Other options are passed to *Note `mysqld': mysqld. For information about option files, see *Note option-files::. *Note `mysql_install_db': mysql-install-db. also supports the options for processing option files described at *Note option-file-options::. * `--basedir=PATH' The path to the MySQL installation directory. * `--datadir=PATH', `--ldata=PATH' The path to the MySQL data directory. * `--force' Cause *Note `mysql_install_db': mysql-install-db. to run even if DNS does not work. Grant table entries that normally use host names will use IP addresses. * `--rpm' For internal use. This option is used during the MySQL installation process for install operations performed using RPM packages. * `--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. * `--srcdir=PATH' For internal use. This option specifies the directory under which *Note `mysql_install_db': mysql-install-db. looks for support files such as the error message file and the file for populating the help tables. This option was added in MySQL 5.1.14. * `--user=USER_NAME' The system (login) user name to use for running *Note `mysqld': mysqld. Files and directories created by *Note `mysqld': mysqld. will be owned by this user. You must be `root' to use this option. By default, *Note `mysqld': mysqld. runs using your current login name and files and directories that it creates will be owned by you. * `--verbose' Verbose mode. Print more information about what the program does. * `--windows' For internal use. This option is used for creating Windows distributions.  File: manual.info, Node: mysql-secure-installation, Next: mysql-tzinfo-to-sql, Prev: mysql-install-db, Up: programs-installation 4.4.6 `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_'. *Note `mysql_secure_installation': mysql-secure-installation. helps you implement security recommendations similar to those described at *Note default-privileges::. Invoke *Note `mysql_secure_installation': mysql-secure-installation. without arguments: shell> mysql_secure_installation The script will prompt you to determine which actions to perform.  File: manual.info, Node: mysql-tzinfo-to-sql, Next: mysql-upgrade, Prev: mysql-secure-installation, Up: programs-installation 4.4.7 `mysql_tzinfo_to_sql' -- Load the Time Zone Tables -------------------------------------------------------- The *Note `mysql_tzinfo_to_sql': 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 Mac 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 *Note time-zone-support::. *Note `mysql_tzinfo_to_sql': 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 *Note `mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. and send the output into the *Note `mysql': mysql. program. For example: shell> mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql *Note `mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. reads your system's time zone files and generates SQL statements from them. *Note `mysql': mysql. processes those statements to load the time zone tables. The second syntax causes *Note `mysql_tzinfo_to_sql': 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 *Note `mysql_tzinfo_to_sql': 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 *Note `mysql_tzinfo_to_sql': 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.  File: manual.info, Node: mysql-upgrade, Prev: mysql-tzinfo-to-sql, Up: programs-installation 4.4.8 `mysql_upgrade' -- Check and Upgrade MySQL Tables ------------------------------------------------------- *Note `mysql_upgrade': mysql-upgrade. examines all tables in all databases for incompatibilities with the current version of MySQL Server. *Note `mysql_upgrade': mysql-upgrade. also upgrades the system tables so that you can take advantage of new privileges or capabilities that might have been added. *Note `mysql_upgrade': mysql-upgrade. should be executed each time you upgrade MySQL. It supersedes the older *Note `mysql_fix_privilege_tables': mysql-fix-privilege-tables. script, which should no longer be used. If *Note `mysql_upgrade': 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 *Note rebuilding-tables:: for manual table repair strategies. *Note*: On Windows Server 2008, Vista, and newer, you must run *Note `mysql_upgrade': 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 *Note backup-methods::. Some upgrade incompatibilities may require special handling before you upgrade your MySQL installation and run *Note `mysql_upgrade': mysql-upgrade. See *Note upgrading::, for instructions on determining whether any such incompatibilities apply to your installation and how to handle them. To use *Note `mysql_upgrade': mysql-upgrade, make sure that the server is running, and then invoke it like this: shell> mysql_upgrade [OPTIONS] After running *Note `mysql_upgrade': mysql-upgrade, stop the server and restart it so that any changes made to the system tables take effect. *Note `mysql_upgrade': mysql-upgrade. executes the following commands to check and repair tables and to upgrade the system tables: mysqlcheck --all-databases --check-upgrade --auto-repair mysql < FIX_PRIV_TABLES mysqlcheck --all-databases --check-upgrade --fix-db-names --fix-table-names Notes about the preceding commands: * Because *Note `mysql_upgrade': mysql-upgrade. invokes *Note `mysqlcheck': mysqlcheck. with the `--all-databases' option, it 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 checks the `--check-upgrade' option entails, see the description of the `FOR UPGRADE' option of the *Note `CHECK TABLE': check-table. statement (see *Note check-table::). * FIX_PRIV_TABLES represents a script generated internally by *Note `mysql_upgrade': mysql-upgrade. that contains SQL statements to upgrade the tables in the `mysql' database. * Prior to MySQL 5.1.31, *Note `mysql_upgrade': mysql-upgrade. does not run the second *Note `mysqlcheck': mysqlcheck. command, which is necessary to re-encode database or table names that contain nonalphanumeric characters. (They still appear after the upgrade with the `#mysql50#' prefix described in *Note identifier-mapping::.) If you have such database or table names, execute the second *Note `mysqlcheck': mysqlcheck. command manually after executing *Note `mysql_upgrade': mysql-upgrade. All checked and repaired tables are marked with the current MySQL version number. This ensures that next time you run *Note `mysql_upgrade': mysql-upgrade. with the same version of the server, it can tell whether there is any need to check or repair the table again. *Note `mysql_upgrade': 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. If you install MySQL from RPM packages on Linux, you must install the server and client RPMs. *Note `mysql_upgrade': mysql-upgrade. is included in the server RPM but requires the client RPM because the latter includes *Note `mysqlcheck': mysqlcheck. (See *Note linux-installation-rpm::.) In MySQL 5.1.7, `mysql_upgrade ' was added as a shell script and worked only for Unix systems. As of MySQL 5.1.10, *Note `mysql_upgrade': mysql-upgrade. is an executable binary and is available on all systems. *Note `mysql_upgrade': mysql-upgrade. does not upgrade the contents of the help tables. For upgrade instructions, see *Note server-side-help-support::. *Note `mysql_upgrade': 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. Other options are passed to *Note `mysqlcheck': mysqlcheck. For example, it might be necessary to specify the `--password[=PASSWORD]' option. *Note `mysql_upgrade': mysql-upgrade. also supports the options for processing option files described at *Note option-file-options::. * `--help' Display a short help message and exit. * `--basedir=PATH' The path to the MySQL installation directory. This option is accepted for backward compatibility but ignored. * `--datadir=PATH' The path to the data directory. This option is accepted for backward compatibility but ignored. * `--debug-check' Print some debugging information when the program exits. This option was added in MySQL 5.1.21. * `--debug-info', `-T' Print debugging information and memory and CPU usage statistics when the program exits. This option was added in MySQL 5.1.21. * `--force' Ignore the `mysql_upgrade_info' file and force execution of *Note `mysqlcheck': mysqlcheck. even if *Note `mysql_upgrade': mysql-upgrade. has already been executed for the current version of MySQL. * `--tmpdir=PATH', `-t PATH' The path name of the directory to use for creating temporary files. This option was added in MySQL 5.1.25. * `--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. * `--write-binlog' Cause binary logging to be enabled while *Note `mysql_upgrade': mysql-upgrade. runs. This is the default behavior; to disable binary logging during the upgrade, use the inverse of this option (that is, start the program with `--skip-write-binlog'). This option was introduced in MySQL 5.1.40.  File: manual.info, Node: programs-client, Next: programs-admin-utils, Prev: programs-installation, Up: programs 4.5 MySQL Client Programs ========================= * Menu: * mysql:: `mysql' --- The MySQL Command-Line Tool * mysqladmin:: `mysqladmin' --- Client for Administering a MySQL Server * mysqlcheck:: `mysqlcheck' --- A Table Maintenance Program * mysqldump:: `mysqldump' --- A Database Backup Program * mysqlimport:: `mysqlimport' --- A Data Import Program * mysqlshow:: `mysqlshow' --- Display Database, Table, and Column Information * mysqlslap:: `mysqlslap' --- Load Emulation Client This section describes client programs that connect to the MySQL server.  File: manual.info, Node: mysql, Next: mysqladmin, Prev: programs-client, Up: programs-client 4.5.1 `mysql' -- The MySQL Command-Line Tool -------------------------------------------- * Menu: * mysql-command-options:: `mysql' Options * mysql-commands:: `mysql' Commands * mysql-logging:: `mysql' Logging * mysql-server-side-help:: `mysql' Server-Side Help * mysql-batch-commands:: Executing SQL Statements from a Text File * mysql-tips:: `mysql' Tips *Note `mysql': 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 *Note `mysql': 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 *Note `mysql_use_result()': mysql-use-result. C API function in the client/server library rather than *Note `mysql_store_result()': mysql-store-result. Using *Note `mysql': 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=YOUR_PASSWORD DB_NAME Then type an SQL statement, end it with ``;'', `\g', or `\G' and press Enter. As of MySQL 5.1.10, typing `Control+C' causes *Note `mysql': mysql. to attempt to kill the current statement. If this cannot be done, or `Control+C' is typed again before the statement is killed, *Note `mysql': mysql. exits. Previously, `Control+C' caused *Note `mysql': mysql. to exit in all cases. You can execute SQL statements in a script file (batch file) like this: shell> mysql DB_NAME < SCRIPT.SQL > OUTPUT.TAB On Unix, the *Note `mysql': mysql. client logs statements executed interactively to a history file. See *Note mysql-logging::.  File: manual.info, Node: mysql-command-options, Next: mysql-commands, Prev: mysql, Up: mysql 4.5.1.1 `mysql' Options ....................... *Note `mysql': mysql. supports the following options, which can be specified on the command line or in the `[mysql]' and `[client]' groups of an option file. *Note `mysql': mysql. also supports the options for processing option files described at *Note option-file-options::. *`mysql' Options* Format Option File Description Introduced -auto-rehashauto-rehash Enable automatic rehashing -batch batch Don't use history file -bind-address=ip_addressbind-addressUse the specified network 5.1.22-ndb-6.3.4 interface to connect to the MySQL Server -character-sets-dir=pathcharacter-sets-dirSet the default character set -column-namescolumn-namesWrite column names in results -column-type-infocolumn-type-infoDisplay result set metadata 5.1.14 -comments comments Whether to retain or strip 5.1.23 comments in statements sent to the server -compress compress Compress all information sent between the client and the server -connect_timeout=valueconnect_timeoutThe number of seconds before connection timeout -database=dbnamedatabase The database to use -debug[=debug_options]debug Write a debugging log -debug-checkdebug-check Print debugging information 5.1.21 when the program exits -debug-info debug-info Print debugging information, memory and CPU statistics when the program exits -default-character-set=charset_namedefault-character-setUse charset_name as the default character set -delimiter=strdelimiter Set the statement delimiter -execute=statementexecute Execute the statement and quit -force force Continue even if an SQL error occurs -help Display help message and exit -host=host_namehost Connect to the MySQL server on the given host -html html Produce HTML output -ignore-spacesignore-spacesIgnore spaces after function names -line-numbersline-numbersWrite line numbers for errors -local-infile[={0|1}]local-infileEnable or disable for LOCAL capability for LOAD DATA INFILE -max_allowed_packet=valuemax_allowed_packetThe maximum packet length to send to or receive from the server -max_join_size=valuemax_join_sizeThe automatic limit for rows in a join when using -safe-updates -named-commandsnamed-commandsEnable named mysql commands -net_buffer_length=valuenet_buffer_lengthThe buffer size for TCP/IP and socket communication -no-auto-rehash Disable automatic rehashing -no-beep no-beep Do not beep when errors occur -no-named-commandsno-named-commandsDisable named mysql commands -no-pager no-pager Deprecated form of -skip-pager -no-tee no-tee Do not copy output to a file -one-databaseone-databaseIgnore statements except those for the default database named on the command line -pager[=command]pager Use the given command for paging query output -password[=password]password The password to use when connecting to the server -pipe On Windows, connect to server using a named pipe -port=port_numport The TCP/IP port number to use for the connection -prompt=format_strprompt Set the prompt to the specified format -protocol=typeprotocol The connection protocol to use -quick quick Do not cache each query result -raw raw Write column values without escape conversion -reconnect reconnect If the connection to the server is lost, automatically try to reconnect -safe-updatessafe-updatesAllow only UPDATE and DELETE statements that specify key values -secure-authsecure-auth Do not send passwords to the server in old (pre-4.1.1) format -select_limit=valueselect_limitThe automatic limit for SELECT statements when using -safe-updates -show-warningsshow-warningsShow warnings after each statement if there are any -sigint-ignoresigint-ignoreIgnore SIGINT signals (typically the result of typing Control+C) -silent silent Silent mode -skip-auto-rehashskip-auto-rehashDisable automatic rehashing -skip-column-namesskip-column-namesDo not write column names in results -skip-line-numbersskip-line-numbersSkip line numbers for errors -skip-named-commandsskip-named-commandsDisable named mysql commands -skip-pager skip-pager Disable paging -skip-reconnectskip-reconnectDisable reconnecting -socket=pathsocket For connections to localhost -ssl-ca=file_namessl-ca The path to a file that contains a list of trusted SSL CAs -ssl-capath=dir_namessl-capath The path to a directory that contains trusted SSL CA certificates in PEM format -ssl-cert=file_namessl-cert The name of the SSL certificate file to use for establishing a secure connection -ssl-cipher=cipher_listssl-cipher A list of allowable ciphers to use for SSL encryption -ssl-key=file_namessl-key The name of the SSL key file to use for establishing a secure connection -ssl-verify-server-certssl-verify-server-certThe server's Common Name value in its certificate is verified against the host name used when connecting to the server -table table Display output in tabular format -tee=file_nametee Append a copy of output to the given file -unbuffered unbuffered Flush the buffer after each query -user=user_nameuser MySQL user name to use when connecting to server -verbose Verbose mode -version Display version information and exit -vertical vertical Print query output rows vertically (one line per column value) -wait wait If the connection cannot be established, wait and retry instead of aborting -xml 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 *Note `mysql': mysql. to start faster, but you must issue the `rehash' command if you want to use name completion. To complete a name, enter the first part and press Tab. If the name is unambiguous, *Note `mysql': 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. * `--batch', `-B' Print results using tab as the column separator, with each row on a new line. With this option, *Note `mysql': 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. * `--bind-address=IP_ADDRESS' On a computer having multiple network interfaces, this option can be used to select which interface is employed when connecting to the MySQL server. This option is supported only in the version of the *Note `mysql': mysql. client that is supplied with MySQL Cluster, beginning with MySQL Cluster NDB 6.3.4. It is not available in standard MySQL 5.1 releases. * `--character-sets-dir=PATH' The directory where character sets are installed. See *Note charset-configuration::. * `--column-names' Write column names in results. * `--column-type-info', `-m' Display result set metadata. This option was added in MySQL 5.1.14. (Before that, use `--debug-info'.) The `-m' short option was added in MySQL 5.1.21. * `--comments', `-c' Whether to preserve comments in statements sent to the server. The default is -skip-comments (discard comments), enable with -comments (preserve comments). This option was added in MySQL 5.1.23. * `--compress', `-C' Compress all information sent between the client and the server if both support compression. * `--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''. * `--debug-check' Print some debugging information when the program exits. This option was added in MySQL 5.1.21. * `--debug-info', `-T' Before MySQL 5.1.14, this option prints debugging information and memory and CPU usage statistics when the program exits, and also causes display of result set metadata during execution. As of MySQL 5.1.14, use `--column-type-info' to display result set metadata. * `--default-character-set=CHARSET_NAME' Use CHARSET_NAME as the default character set for the client and connection. A common issue that can occur when the operating system uses `utf8' or another multi-byte character set is that output from the *Note `mysql': mysql. client is formatted incorrectly, due to the fact that the MySQL client uses the `latin1' character set by default. You can usually fix such issues by using this option to force the client to use the system character set instead. See *Note charset-configuration::, for more information. * `--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 (``;''). *Note `mysql': mysql. starts with this option _enabled_ by default. However, even with this option, long-format commands still work from the first line. See *Note mysql-commands::. * `--execute=STATEMENT', `-e STATEMENT' Execute the statement and quit. The default output format is like that produced with `--batch'. See *Note command-line-options::, for some examples. With this option, *Note `mysql': mysql. does not use the history file. * `--force', `-f' Continue even if an SQL error occurs. * `--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 *Note server-sql-mode::). * `--line-numbers' Write line numbers for errors. Disable this with `--skip-line-numbers'. * `--local-infile[={0|1}]' Enable or disable `LOCAL' capability for *Note `LOAD DATA INFILE': load-data. 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' has no effect if the server does not also support it. * `--named-commands', `-G' Enable named *Note `mysql': 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 *Note 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-named-commands', `-g' Deprecated, use `--disable-named-commands' instead. `--no-named-commands' is removed in MySQL 5.5. * `--no-pager' Deprecated form of `--skip-pager'. See the `--pager' option. `--no-pager' is removed in MySQL 5.5. * `--no-tee' Deprecated form of `--skip-tee'. See the `--tee' option. `--no-tee' is removed in MySQL 5.5. * `--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 *Note `USE': use. statements. Initially, *Note `mysql': mysql. executes statements in the input because specifying a database DB_NAME on the command line is equivalent to inserting *Note `USE DB_NAME': use. at the beginning of the input. Then, for each *Note `USE': use. statement encountered, *Note `mysql': 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 *Note `mysql': 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 *Note `mysql --force --one-database db1': mysql, *Note `mysql': mysql. handles the input as follows: * The *Note `DELETE': delete. statement is executed because the default database is `db1', even though the statement names a table in a different database. * The *Note `DROP TABLE': drop-table. and *Note `CREATE TABLE': create-table. statements are not executed because the default database is not `db1', even though the statements name a table in `db1'. * The *Note `INSERT': insert. and *Note `CREATE TABLE': create-table. statements are executed because the default database is `db1', even though the *Note `CREATE TABLE': 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'. *Note 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, *Note `mysql': mysql. prompts for one. Specifying a password on the command line should be considered insecure. See *Note 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. * `--port=PORT_NUM', `-P PORT_NUM' The TCP/IP port number to use for the connection. * `--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 *Note 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 *Note 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, *Note `mysql': 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 *Note `UPDATE': update. and *Note `DELETE': 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 *Note 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. * `--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 *Note ssl-options::. * `--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. *Note mysql-commands::, discusses tee files further. * `--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. *Note*: Prior to MySQL 5.1.12, there was no differentiation in the output when using this option between columns containing the `NULL' value and columns containing the string literal `'NULL''; both were represented as NULL Beginning with MySQL 5.1.12, the output when `--xml' is used with *Note `mysql': mysql. matches that of *Note `mysqldump `--xml'': mysqldump. See *Note mysqldump:: for details. Beginning with MySQL 5.1.18, the XML output also uses an XML namespace, as shown here: shell> mysql --xml -uroot -e "SHOW VARIABLES LIKE 'version%'" version 5.0.40-debug version_comment Source distribution version_compile_machine i686 version_compile_os suse-linux-gnu (See Bug #25946.) You can also set the following variables by using `--VAR_NAME=VALUE'. The `--set-variable' format is deprecated and is removed in MySQL 5.5. * `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 *Note `SELECT': select. statements when using `--safe-updates'. (Default value is 1,000.)  File: manual.info, Node: mysql-commands, Next: mysql-logging, Prev: mysql-command-options, Up: mysql 4.5.1.2 `mysql' Commands ........................ *Note `mysql': mysql. sends each SQL statement that you issue to the server to be executed. There is also a set of commands that *Note `mysql': 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 command. 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. For server side help, type 'help contents' 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 multi-line `/* ... */' comments is not supported. * `help [ARG]', `\h [ARG]', `\? [ARG]', `? [ARG]' Display a help message listing the available *Note `mysql': mysql. commands. If you provide an argument to the `help' command, *Note `mysql': mysql. uses it as a search string to access server-side help from the contents of the MySQL Reference Manual. For more information, see *Note 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 *Note `mysql': mysql. is run with auto-reconnect enabled (which is not recommended), because the specified character set is used for reconnects. This command was added in MySQL 5.1.7. * `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 *Note `mysql': 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. *Note `mysql': 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. *Note `mysql': mysql. interprets this as `INDE' followed by the delimiter `X'. When the delimiter recognized by *Note `mysql': 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 *Note c-api-multiple-queries::), and for parsing the body of stored procedures and functions, triggers, and events (see *Note stored-programs-defining::). * `edit', `\e' Edit the current input statement. *Note `mysql': 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 *Note `mysql': 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' Enable display of warnings after each statement. * `pager [COMMAND]', `\P [COMMAND]' Enable output paging. By using the `--pager' option when you invoke *Note `mysql': 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, *Note `mysql': 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 *Note `mysql': 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, *Note `mysql': mysql. resets the prompt to the default of `mysql>'. * `quit', `\q' Exit *Note `mysql': 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.) * `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 *Note `mysql': 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 *Note `mysql': 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. *Note `mysql': 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 *Note `mysql': 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 *Note `mysql': 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. This table describes `prompt' command options that are used to configure the `mysql>' prompt. Option Description `\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 (new in 5.1.12) `\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 *Note `mysql': 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 *Note 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>  File: manual.info, Node: mysql-logging, Next: mysql-server-side-help, Prev: mysql-commands, Up: mysql 4.5.1.3 `mysql' Logging ....................... On Unix, the *Note `mysql': mysql. client logs statements executed interactively 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. * How Logging Occurs * 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. * *Note `mysql': mysql. logs each nonempty statement line individually. * If a statement spans multiple lines (not including the terminating delimiter), *Note `mysql': 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' -> , -> CONCAT() -> ; In this case, *Note `mysql': mysql. logs the `SELECT', `'Today is'', `,', `CONCAT()', 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(); * 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 *Note 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  File: manual.info, Node: mysql-server-side-help, Next: mysql-batch-commands, Prev: mysql-logging, Up: mysql 4.5.1.4 `mysql' Server-Side Help ................................ mysql> help SEARCH_STRING If you provide an argument to the `help' command, *Note `mysql': 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 *Note 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 *Note `help contents': help. to see a list of the help categories: mysql> help contents You asked for help about help category: "Contents" For more information, type 'help ', where 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, *Note `mysql': 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 ', where 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 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 ', where is one of the following topics: REPAIR TABLE REPEAT FUNCTION REPEAT LOOP REPLACE REPLACE FUNCTION  File: manual.info, Node: mysql-batch-commands, Next: mysql-tips, Prev: mysql-server-side-help, Up: mysql 4.5.1.5 Executing SQL Statements from a Text File ................................................. The *Note `mysql': 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 *Note `mysql': 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 *Note `mysql': 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 *Note `mysql': 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 '' AS ' '; The statement shown outputs `'. You can also invoke *Note `mysql': mysql. with the `--verbose' option, which causes each statement to be displayed before the result that it produces. As of MySQL 5.1.23, *Note `mysql': 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 *Note `mysql': mysql. to change its default character set. To do that, invoke *Note `mysql': mysql. with an option such as `--default-character-set=utf8'. For more information about batch mode, see *Note batch-mode::.  File: manual.info, Node: mysql-tips, Prev: mysql-batch-commands, Up: mysql 4.5.1.6 `mysql' Tips .................... * Menu: * mysql-input-editing:: Input-Line Editing * vertical-query-results:: Displaying Query Results Vertically * safe-updates:: Using the `--safe-updates' Option * mysql-reconnect:: Disabling `mysql' Auto-Reconnect This section describes some techniques that can help you use *Note `mysql': mysql. more effectively.  File: manual.info, Node: mysql-input-editing, Next: vertical-query-results, Prev: mysql-tips, Up: mysql-tips 4.5.1.7 Input-Line Editing .......................... *Note `mysql': 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-arror' 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 *Note `mysql': 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 *Note `mysql': 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'. *Note `mysql': mysql. will show the bindings when it starts.  File: manual.info, Node: vertical-query-results, Next: safe-updates, Prev: mysql-input-editing, Up: mysql-tips 4.5.1.8 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" 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)  File: manual.info, Node: safe-updates, Next: mysql-reconnect, Prev: vertical-query-results, Up: mysql-tips 4.5.1.9 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, *Note `mysql': mysql. issues the following statement when it connects to the MySQL server: SET sql_safe_updates=1, sql_select_limit=1000, sql_max_join_size=1000000; See *Note server-system-variables::. The *Note `SET': set-statement. statement has the following effects: * You are not permitted to execute an *Note `UPDATE': update. or *Note `DELETE': 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 *Note `SELECT': select. results to 1,000 rows unless the statement includes a `LIMIT' clause. * The server aborts multiple-table *Note `SELECT': 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  File: manual.info, Node: mysql-reconnect, Prev: safe-updates, Up: mysql-tips 4.5.1.10 Disabling `mysql' Auto-Reconnect ......................................... If the *Note `mysql': 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 *Note `mysql': 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 *Note `mysql': mysql. terminate with an error if the connection has been lost, you can start the *Note `mysql': mysql. client with the `--skip-reconnect' option. For more information about auto-reconnect and its effect on state information when a reconnection occurs, see *Note auto-reconnect::.  File: manual.info, Node: mysqladmin, Next: mysqlcheck, Prev: mysql, Up: programs-client 4.5.2 `mysqladmin' -- Client for Administering a MySQL Server ------------------------------------------------------------- *Note `mysqladmin': 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 *Note `mysqladmin': mysqladmin. like this: shell> mysqladmin [OPTIONS] COMMAND [COMMAND-ARG] [COMMAND [COMMAND-ARG]] ... *Note `mysqladmin': 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. Format and content of this information is subject to change. Beginning with MySQL 5.1.12, this includes information about the Event Scheduler. See *Note 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' Flush all logs. * `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. * `old-password NEW-PASSWORD' This is like the `password' command but stores the password using the old (pre-4.1) password-hashing format. (See *Note password-hashing::.) * `password NEW-PASSWORD' Set a new password. This changes the password to NEW-PASSWORD for the account that you use with *Note `mysqladmin': mysqladmin. for connecting to the server. Thus, the next time you invoke *Note `mysqladmin': mysqladmin. (or any other client program) using the same account, you will need to specify the new password. 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" *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 *Note `mysqladmin flush-privileges': mysqladmin. to re-enable the grant table and then use a separate *Note `mysqladmin password': mysqladmin. command to change the password. * `ping' Check whether the server is available. The return status from *Note `mysqladmin': 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 *Note `SHOW PROCESSLIST': show-processlist. statement. If the `--verbose' option is given, the output is like that of *Note `SHOW FULL PROCESSLIST': show-processlist. (See *Note 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 *Note `mysqladmin status': mysqladmin. 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 *Note 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. * `Memory in use' The amount of memory allocated directly by *Note `mysqld': mysqld. This value is displayed only when MySQL has been compiled with `--with-debug=full'. * `Maximum memory used' The maximum amount of memory allocated directly by *Note `mysqld': mysqld. This value is displayed only when MySQL has been compiled with `--with-debug=full'. If you execute *Note `mysqladmin shutdown': mysqladmin. when connecting to a local server using a Unix socket file, *Note `mysqladmin': mysqladmin. waits until the server's process ID file has been removed, to ensure that the server has stopped properly. *Note `mysqladmin': mysqladmin. supports the following options, which can be specified on the command line or in the `[mysqladmin]' and `[client]' groups of an option file. *Note `mysqladmin': mysqladmin. also supports the options for processing option files described at *Note option-file-options::. *`mysqladmin' Options* Format Option File Description Introduced -bind-address=ip_addressbind-addressUse the specified network 5.1.22-ndb-6.3.4 interface to connect to the MySQL Server -compress compress Compress all information sent between the client and the server -connect_timeout=secondsconnect_timeoutThe number of seconds before connection timeout -count=# count The number of iterations to make for repeated command execution -debug[=debug_options]debug Write a debugging log -debug-checkdebug-check Print debugging information 5.1.21 when the program exits -debug-info debug-info Print debugging information, 5.1.14 memory and CPU statistics when the program exits -default-character-set=charset_namedefault-character-setUse charset_name as the default character set -force force Continue even if an SQL error occurs -help Display help message and exit -host=host_namehost Connect to the MySQL server on the given host -no-beep no-beep Do not beep when errors occur 5.1.17 -password[=password]password The password to use when connecting to the server -pipe On Windows, connect to server using a named pipe -port=port_numport The TCP/IP port number to use for the connection -protocol=typeprotocol The connection protocol to use -relative relative Show the difference between the current and previous values when used with the -sleep option -shutdown_timeout=secondsshutdown_timeoutThe maximum number of seconds to wait for server shutdown -silent silent Silent mode -sleep=delaysleep Execute commands repeatedly, sleeping for delay seconds in between -socket=pathsocket For connections to localhost -ssl-ca=file_namessl-ca The path to a file that contains a list of trusted SSL CAs -ssl-capath=dir_namessl-capath The path to a directory that contains trusted SSL CA certificates in PEM format -ssl-cert=file_namessl-cert The name of the SSL certificate file to use for establishing a secure connection -ssl-cipher=cipher_listssl-cipher A list of allowable ciphers to use for SSL encryption -ssl-key=file_namessl-key The name of the SSL key file to use for establishing a secure connection -ssl-verify-server-certssl-verify-server-certThe server's Common Name value in its certificate is verified against the host name used when connecting to the server -user=user_name,user MySQL user name to use when connecting to server -verbose Verbose mode -version Display version information and exit -vertical vertical Print query output rows vertically (one line per column value) -wait 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, this option can be used to select which interface is employed when connecting to the MySQL server. This option is supported only in the version of *Note `mysqladmin': mysqladmin. that is supplied with MySQL Cluster, beginning with MySQL Cluster NDB 6.3.4. It is not available in standard MySQL 5.1 releases. * `--character-sets-dir=PATH' The directory where character sets are installed. See *Note 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. This option was added in MySQL 5.1.21. * `--debug-info' Print debugging information and memory and CPU usage statistics when the program exits. This option was added in MySQL 5.1.14. * `--default-character-set=CHARSET_NAME' Use CHARSET_NAME as the default character set. See *Note charset-configuration::. * `--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. * `--no-beep', `-b' Suppress the warning beep that is emitted by default for errors such as a failure to connect to the server. This option was added in MySQL 5.1.17. * `--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, *Note `mysqladmin': mysqladmin. prompts for one. Specifying a password on the command line should be considered insecure. See *Note 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. * `--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 *Note 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. * `--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, *Note `mysqladmin': 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 *Note ssl-options::. * `--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' The `--set-variable' format is deprecated and is removed in MySQL 5.5. * `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).  File: manual.info, Node: mysqlcheck, Next: mysqldump, Prev: mysqladmin, Up: programs-client 4.5.3 `mysqlcheck' -- A Table Maintenance Program ------------------------------------------------- The *Note `mysqlcheck': 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 *Note 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 *Note `mysqlcheck': mysqlcheck. might take a long time. (This is also true for *Note `mysql_upgrade': mysql-upgrade. because that program invokes *Note `mysqlcheck': mysqlcheck. to check all tables and repair them if necessary.) *Note `mysqlcheck': mysqlcheck. is similar in function to *Note `myisamchk': myisamchk, but works differently. The main operational difference is that *Note `mysqlcheck': mysqlcheck. must be used when the *Note `mysqld': mysqld. server is running, whereas *Note `myisamchk': myisamchk. should be used when it is not. The benefit of using *Note `mysqlcheck': mysqlcheck. is that you do not have to stop the server to perform table maintenance. *Note `mysqlcheck': mysqlcheck. uses the SQL statements *Note `CHECK TABLE': check-table, *Note `REPAIR TABLE': repair-table, *Note `ANALYZE TABLE': analyze-table, and *Note `OPTIMIZE TABLE': 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 *Note table-maintenance-sql::. The `MyISAM' storage engine supports all four maintenance operations, so *Note `mysqlcheck': mysqlcheck. can be used to perform any of them on `MyISAM' tables. Other storage engines do not necessarily support all operations. In such cases, an error message is displayed. For example, if `test.t' is a `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 *Note `mysqlcheck': mysqlcheck. is unable to repair a table, see *Note rebuilding-tables:: for manual table repair strategies. This will be the case, for example, for `InnoDB' tables, which can be checked with *Note `CHECK TABLE': check-table, but not repaired with *Note `REPAIR TABLE': repair-table. The use of *Note `mysqlcheck': mysqlcheck. with partitioned tables is not supported before MySQL 5.1.27. *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 *Note `mysqlcheck': 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. *Note `mysqlcheck': 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 *Note `mysqlcheck': mysqlcheck. named `mysqlrepair', or make a symbolic link to *Note `mysqlcheck': mysqlcheck. named `mysqlrepair'. If you invoke `mysqlrepair', it repairs tables. The names shown in the following table can be used to change *Note `mysqlcheck': mysqlcheck. default behavior. This table lists names that can be used to change *Note `mysqlcheck': mysqlcheck. default behavior. Command Meaning `mysqlrepair' The default option is `--repair' `mysqlanalyze' The default option is `--analyze' `mysqloptimize' The default option is `--optimize' *Note `mysqlcheck': mysqlcheck. supports the following options, which can be specified on the command line or in the `[mysqlcheck]' and `[client]' groups of an option file. *Note `mysqlcheck': mysqlcheck. also supports the options for processing option files described at *Note option-file-options::. *`mysqlcheck' Options* Format Option File Description Introduced -all-databasesall-databasesCheck all tables in all databases -all-in-1 all-in-1 Execute a single statement for each database that names all the tables from that database -analyze analyze Analyze the tables -auto-repairauto-repair If a checked table is corrupted, automatically fix it -bind-address=ip_addressbind-addressUse the specified network 5.1.22-ndb-6.3.4 interface to connect to the MySQL Server -character-sets-dir=pathcharacter-sets-dirThe directory where character sets are installed -check check Check the tables for errors -check-only-changedcheck-only-changedCheck only tables that have changed since the last check -check-upgradecheck-upgradeInvoke CHECK TABLE with the 5.1.7 FOR UPGRADE option -compress compress Compress all information sent between the client and the server -databases databases Process all tables in the named databases -debug[=debug_options]debug Write a debugging log -debug-checkdebug-check Print debugging information 5.1.21 when the program exits -debug-info debug-info Print debugging information, 5.1.14 memory and CPU statistics when the program exits -default-character-set=charset_namedefault-character-setUse charset_name as the default character set -extended extended Check and repair tables -fast fast Check only tables that have not been closed properly -fix-db-namesfix-db-namesConvert database names to 5.1.7 5.1 format -fix-table-namesfix-table-namesConvert table names to 5.1 5.1.7 format -force force Continue even if an SQL error occurs -help Display help message and exit -host=host_namehost Connect to the MySQL server on the given host -medium-checkmedium-checkDo a check that is faster than an -extended operation -optimize optimize Optimize the tables -password[=password]password The password to use when connecting to the server -pipe On Windows, connect to server using a named pipe -port=port_numport The TCP/IP port number to use for the connection -protocol=typeprotocol The connection protocol to use -quick quick The fastest method of checking -repair repair Perform a repair that can fix almost anything except unique keys that are not unique -silent silent Silent mode -socket=pathsocket For connections to localhost -ssl-ca=file_namessl-ca The path to a file that contains a list of trusted SSL CAs -ssl-capath=dir_namessl-capath The path to a directory that contains trusted SSL CA certificates in PEM format -ssl-cert=file_namessl-cert The name of the SSL certificate file to use for establishing a secure connection -ssl-cipher=cipher_listssl-cipher A list of allowable ciphers to use for SSL encryption -ssl-key=file_namessl-key The name of the SSL key file to use for establishing a secure connection -ssl-verify-server-certssl-verify-server-certThe server's Common Name value in its certificate is verified against the host name used when connecting to the server -tables tables Overrides the -databases or -B option -use-frm use-frm For repair operations on MyISAM tables -user=user_name,user MySQL user name to use when connecting to server -verbose Verbose mode -version Display version information and exit -write-binlogwrite-binlogLog ANALYZE, OPTIMIZE, 5.1.18 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. * `--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, this option can be used to select which interface is employed when connecting to the MySQL server. This option is supported only in the version of *Note `mysqlcheck': mysqlcheck. that is supplied with MySQL Cluster, beginning with MySQL Cluster NDB 6.3.4. It is not available in standard MySQL 5.1 releases. * `--character-sets-dir=PATH' The directory where character sets are installed. See *Note 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 *Note `CHECK TABLE': 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. `--check-upgrade' was added in MySQL 5.1.7. * `--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, *Note `mysqlcheck': mysqlcheck. 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. * `--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. This option was added in MySQL 5.1.21. * `--debug-info' Print debugging information and memory and CPU usage statistics when the program exits. This option was added in MySQL 5.1.14. * `--default-character-set=CHARSET_NAME' Use CHARSET_NAME as the default character set. See *Note charset-configuration::. * `--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! * `--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 was added in MySQL 5.1.7. * `--fix-table-names' Convert table names to 5.1 format. Only table names that contain special characters are affected. This option was added in MySQL 5.1.7. As of MySQL 5.1.23, this option also applies to views. * `--force', `-f' Continue even if an SQL error occurs. * `--host=HOST_NAME', `-h HOST_NAME' Connect to the MySQL server on the given host. * `--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. * `--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, *Note `mysqlcheck': mysqlcheck. prompts for one. Specifying a password on the command line should be considered insecure. See *Note 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. * `--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 *Note 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. * `--silent', `-s' Silent mode. Print only 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 *Note ssl-options::. * `--tables' Override the `--databases' or `-B' option. All name arguments following the option are regarded as table names. * `--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 *Note `ANALYZE TABLE': analyze-table, *Note `OPTIMIZE TABLE': optimize-table, and *Note `REPAIR TABLE': repair-table. statements generated by *Note `mysqlcheck': 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. This option was added in MySQL 5.1.18.  File: manual.info, Node: mysqldump, Next: mysqlimport, Prev: mysqlcheck, Up: programs-client 4.5.4 `mysqldump' -- A Database Backup Program ---------------------------------------------- The *Note `mysqldump': mysqldump. client is a backup program originally written by Igor Romanenko. It can be used to dump a database or a collection of databases for backup or transfer to another SQL server (not necessarily a MySQL server). The dump typically contains SQL statements to create the table, populate it, or both. However, *Note `mysqldump': mysqldump. can also be used to generate files in CSV, other delimited text, or XML format. *Note `mysqldump': 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 same privileges needed to create each of the dumped objects by issuing `CREATE' statements manually. *Note `mysqldump': mysqldump. output can include *Note `ALTER DATABASE': 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. If you are performing a backup on the server and your tables all are *Note `MyISAM': myisam-storage-engine. tables, you can also use *Note `mysqlhotcopy': mysqlhotcopy. for this purpose. * Syntax * There are in general three ways to use *Note `mysqldump': 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. *Note `mysqldump': mysqldump. does not dump the `INFORMATION_SCHEMA' database by default. As of MySQL 5.1.38, *Note `mysqldump': mysqldump. dumps `INFORMATION_SCHEMA' if you name it explicitly on the command line, although you must also use the `--skip-lock-tables' option. Before 5.1.38, *Note `mysqldump': mysqldump. silently ignores `INFORMATION_SCHEMA' even if you name it explicitly on the command line. Before MySQL 5.1.64, *Note `mysqldump': mysqldump. does not dump the `general_log' or `slow_query_log' tables for dumps of the `mysql' database. As of 5.1.64, the dump includes statements to recreate those tables so that they are not missing after reloading the dump file. Log table contents are not dumped. In MySQL Cluster NDB 7.1.7 and later, the `ndbinfo' information database is ignored and not dumped by *Note `mysqldump': mysqldump. To see a list of the options your version of *Note `mysqldump': mysqldump. supports, execute *Note `mysqldump --help': mysqldump. Some *Note `mysqldump': mysqldump. options are shorthand for groups of other options: * Use of `--opt' is the same as specifying `--add-drop-table', `--add-locks', `--create-options', `--disable-keys', `--extended-insert', `--lock-tables', `--quick', and `--set-charset'. All of the options that `--opt' stands for also are on by default because `--opt' is on by default. * Use of `--compact' is the same as specifying `--skip-add-drop-table', `--skip-add-locks', `--skip-comments', `--skip-disable-keys', and `--skip-set-charset' options. To reverse the effect of a group option, uses its `--skip-XXX' form (`--skip-opt' or `--skip-compact'). It is also possible to select only part of the effect of a group option by following it with options that enable or disable specific features. Here are some examples: * 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'. 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. *Note `mysqldump': 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 *Note `mysqldump': mysqldump. to generate a dump to be reloaded into a very old MySQL server, you should not use the `--opt' or `--extended-insert' option. Use `--skip-opt' instead. *Note*: *Note `mysqldump': mysqldump. from MySQL 5.1.21 cannot be used to create dumps from MySQL server 5.1.20 and older. This issue is fixed in MySQL 5.1.22. (Bug #30123) *Note `mysqldump': mysqldump. supports the following options, which can be specified on the command line or in the `[mysqldump]' and `[client]' groups of an option file. *Note `mysqldump': mysqldump. also supports the options for processing option files described at *Note option-file-options::. *`mysqldump' Options* Format Option File Description Introduced -add-drop-databaseadd-drop-databaseAdd a DROP DATABASE statement before each CREATE DATABASE statement -add-drop-tableadd-drop-tableAdd a DROP TABLE statement before each CREATE TABLE statement -add-drop-triggeradd-drop-triggerAdd a DROP TRIGGER statement 5.1.47-ndb-7.1.8 before each CREATE TRIGGER statement -add-locks add-locks Surround each table dump with LOCK TABLES and UNLOCK TABLES statements -all-databasesall-databasesDump all tables in all databases -all-tablespacesall-tablespacesAdds to a table dump all SQL 5.1.6 statements needed to create any tablespaces used by an NDB Cluster table -allow-keywordsallow-keywordsAllow creation of column names that are keywords -bind-address=ip_addressbind-addressUse the specified network 5.1.22-ndb-6.3.4 interface to connect to the MySQL Server -comments comments Add comments to the dump file -compact compact Produce more compact output -compatible=name[,name,...]compatible Produce output that is more compatible with other database systems or with older MySQL servers -complete-insertcomplete-insertUse complete INSERT statements that include column names -create-optionscreate-optionsInclude all MySQL-specific table options in CREATE TABLE statements -databases databases Dump several databases -debug[=debug_options]debug Write a debugging log -debug-checkdebug-check Print debugging information 5.1.21 when the program exits -debug-info debug-info Print debugging information, 5.1.14 memory and CPU statistics when the program exits -default-character-set=charset_namedefault-character-setUse charset_name as the default character set -delayed-insertdelayed-insertWrite INSERT DELAYED statements rather than INSERT statements -delete-master-logsdelete-master-logsOn a master replication server, delete the binary logs after performing the dump operation -disable-keysdisable-keysFor each table, surround the INSERT statements with statements to disable and enable keys -dump-date dump-date Include dump date as "Dump 5.1.23 completed on" comment if -comments is given -events events Dump events from the dumped 5.1.8 databases -extended-insertextended-insertUse multiple-row INSERT syntax that include several VALUES lists -fields-enclosed-by=stringfields-enclosed-byThis option is used with the -tab option and has the same meaning as the corresponding clause for LOAD DATA INFILE -fields-escaped-byfields-escaped-byThis option is used with the -tab option and has the same meaning as the corresponding clause for LOAD DATA INFILE -fields-optionally-enclosed-by=stringfields-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-by=stringfields-terminated-byThis option is used with the -tab option and has the same meaning as the corresponding clause for LOAD DATA INFILE -first-slavefirst-slave Deprecated; use -lock-all-tables instead -flush-logs flush-logs Flush the MySQL server log files before starting the dump -flush-privilegesflush-privilegesEmit a FLUSH PRIVILEGES statement after dumping the mysql database -help Display help message and exit -hex-blob hex-blob Dump binary columns using hexadecimal notation (for example, 'abc' becomes 0x616263) -host host Host to connect to (IP address or hostname) -ignore-table=db_name.tbl_nameignore-tableDo not dump the given table -insert-ignoreinsert-ignoreWrite INSERT IGNORE statements rather than INSERT statements -lines-terminated-by=stringlines-terminated-byThis option is used with the -tab option and has the same meaning as the corresponding clause for LOAD DATA INFILE -lock-all-tableslock-all-tablesLock all tables across all databases -lock-tableslock-tables Lock all tables before dumping them -log-error=file_namelog-error Append warnings and errors 5.1.18 to the named file -master-data[=value]master-data Write the binary log file name and position to the output -max_allowed_packet=valuemax_allowed_packetThe maximum packet length to send to or receive from the server -net_buffer_length=valuenet_buffer_lengthThe buffer size for TCP/IP and socket communication -no-autocommitno-autocommitEnclose the INSERT statements for each dumped table within SET autocommit = 0 and COMMIT statements -no-create-dbno-create-dbThis option suppresses the CREATE DATABASE statements -no-create-infono-create-infoDo not write CREATE TABLE statements that re-create each dumped table -no-data no-data Do not dump table contents -no-set-namesno-set-namesSame as -skip-set-charset -no-tablespacesno-tablespacesDo not write any CREATE 5.1.14 LOGFILE GROUP or CREATE TABLESPACE statements in output -opt opt Shorthand for -add-drop-table -add-locks -create-options -disable-keys -extended-insert -lock-tables -quick -set-charset. -order-by-primaryorder-by-primaryDump each table's rows sorted by its primary key, or by its first unique index -password[=password]password The password to use when connecting to the server -pipe On Windows, connect to server using a named pipe -port=port_numport The TCP/IP port number to use for the connection -protocol=typeprotocol The connection protocol to use -quick quick Retrieve rows for a table from the server a row at a time -quote-namesquote-names Quote identifiers within backtick characters -replace replace Write REPLACE statements 5.1.3 rather than INSERT statements -result-file=fileresult-file Direct output to a given file -routines routines Dump stored routines 5.1.2 (procedures and functions) from the dumped databases -set-charsetset-charset Add SET NAMES default_character_set to output -single-transactionsingle-transactionThis option issues a BEGIN SQL statement before dumping data from the server -skip-add-drop-tableskip-add-drop-tableDo not add a DROP TABLE statement before each CREATE TABLE statement -skip-add-locksskip-add-locksDo not add locks -skip-commentsskip-commentsDo not add comments to the dump file -skip-compactskip-compactDo not produce more compact output -skip-disable-keysskip-disable-keysDo not disable keys -skip-extended-insertskip-extended-insertTurn off extended-insert -skip-opt skip-opt Turn off the options set by -opt -skip-quick skip-quick Do not retrieve rows for a table from the server a row at a time -skip-quote-namesskip-quote-namesDo not quote identifiers -skip-set-charsetskip-set-charsetSuppress the SET NAMES statement -skip-triggersskip-triggersDo not dump triggers -skip-tz-utcskip-tz-utc Turn off tz-utc 5.1.2 -socket=pathsocket For connections to localhost -ssl-ca=file_namessl-ca The path to a file that contains a list of trusted SSL CAs -ssl-capath=dir_namessl-capath The path to a directory that contains trusted SSL CA certificates in PEM format -ssl-cert=file_namessl-cert The name of the SSL certificate file to use for establishing a secure connection -ssl-cipher=cipher_listssl-cipher A list of allowable ciphers to use for SSL encryption -ssl-key=file_namessl-key The name of the SSL key file to use for establishing a secure connection -ssl-verify-server-certssl-verify-server-certThe server's Common Name value in its certificate is verified against the host name used when connecting to the server -tab=path tab Produce tab-separated data files -tables tables Override the -databases or -B option -triggers triggers Dump triggers for each dumped table -tz-utc tz-utc Add SET TIME_ZONE='+00:00' 5.1.2 to the dump file -user=user_nameuser MySQL user name to use when connecting to server -verbose Verbose mode -version Display version information and exit -where='where_condition'where Dump only rows selected by the given WHERE condition -xml xml Produce XML output * `--help', `-?' Display a help message and exit. * `--add-drop-database' Add a *Note `DROP DATABASE': drop-database. statement before each *Note `CREATE DATABASE': create-database. statement. This option is typically used in conjunction with the `--all-databases' or `--databases' option because no *Note `CREATE DATABASE': create-database. statements are written unless one of those options is specified. * `--add-drop-table' Add a *Note `DROP TABLE': drop-table. statement before each *Note `CREATE TABLE': create-table. statement. * `--add-drop-trigger' Add a *Note `DROP TRIGGER': drop-trigger. statement before each *Note `CREATE TRIGGER': create-trigger. statement. *Note*: This option is supported only by *Note `mysqldump': mysqldump. as supplied with MySQL Cluster NDB 6.3.38, MySQL Cluster NDB 7.0.19, MySQL Cluster NDB 7.1.8, and later MySQL Cluster releases. It is not available when using MySQL 5.1. * `--add-locks' Surround each table dump with *Note `LOCK TABLES': lock-tables. and *Note `UNLOCK TABLES': lock-tables. statements. This results in faster inserts when the dump file is reloaded. See *Note insert-speed::. * `--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. * `--all-tablespaces', `-Y' Adds to a table dump all SQL statements needed to create any tablespaces used by an *Note `NDBCLUSTER': mysql-cluster. table. This information is not otherwise included in the output from *Note `mysqldump': mysqldump. This option is currently relevant only to MySQL Cluster tables. This option was added in MySQL 5.1.6. * `--allow-keywords' Permit creation of column names that are keywords. This works by prefixing each column name with the table name. * `--bind-address=IP_ADDRESS' On a computer having multiple network interfaces, this option can be used to select which interface is employed when connecting to the MySQL server. This option is supported only in the version of *Note `mysqldump': mysqldump. that is supplied with MySQL Cluster, beginning with MySQL Cluster NDB 6.3.4. It is not available in standard MySQL 5.1 releases. * `--character-sets-dir=PATH' The directory where character sets are installed. See *Note charset-configuration::. * `--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'. * `--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. *Note*: Prior to MySQL 5.1.21, this option did not create valid SQL if the database dump contained views. The recreation of views requires the creation and removal of temporary tables and this option suppressed the removal of those temporary tables. As a workaround, use `--compact' with the `--add-drop-table' option and then manually adjust the dump file. * `--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 *Note server-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. _This option requires a server version of 4.1.0 or higher_. With older servers, it does nothing. * `--complete-insert', `-c' Use complete *Note `INSERT': insert. statements that include column names. * `--compress', `-C' Compress all information sent between the client and the server if both support compression. * `--create-options' Include all MySQL-specific table options in the *Note `CREATE TABLE': create-table. statements. * `--databases', `-B' Dump several databases. Normally, *Note `mysqldump': 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. *Note `CREATE DATABASE': create-database. and *Note `USE': use. statements are included in the output before each new database. * `--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. This option was added in MySQL 5.1.21. * `--debug-info' Print debugging information and memory and CPU usage statistics when the program exits. This option was added in MySQL 5.1.14. * `--default-character-set=CHARSET_NAME' Use CHARSET_NAME as the default character set. See *Note charset-configuration::. If no character set is specified, *Note `mysqldump': mysqldump. uses `utf8', and earlier versions use `latin1'. Prior to MySQL 5.1.38, this option has no effect for output data files produced by using the `--tab' option. See the description for that option. * `--delayed-insert' Write *Note `INSERT DELAYED': insert-delayed. statements rather than *Note `INSERT': insert. statements. * `--delete-master-logs' On a master replication server, delete the binary logs by sending a *Note `PURGE BINARY LOGS': purge-binary-logs. statement to the server after performing the dump operation. This option automatically enables `--master-data'. * `--disable-keys', `-K' For each table, surround the *Note `INSERT': 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. It has no effect for other tables. * `--dump-date' If the `--comments' option is given, *Note `mysqldump': 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. This option was added in MySQL 5.1.23. * `--events', `-E' Include Event Scheduler events for the dumped databases in the output. This option was added in MySQL 5.1.8. * `--extended-insert', `-e' Use multiple-row *Note `INSERT': insert. syntax that include several `VALUES' lists. This results in a smaller dump file and speeds up inserts when the file is reloaded. * `--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 *Note `LOAD DATA INFILE': load-data. See *Note load-data::. * `--first-slave' Deprecated. Use `--lock-all-tables' instead. `--first-slave' is removed in MySQL 5.5. * `--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' or `--master-data': In this case, the logs are flushed only once, corresponding to the moment that all tables are locked. If you want your dump and the log flush to happen at exactly the same moment, you should use `--flush-logs' together with either `--lock-all-tables' or `--master-data'. * `--flush-privileges' Add a *Note `FLUSH PRIVILEGES': flush. 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. This option was added in MySQL 5.1.12. * `--force', `-f' Continue even if an SQL error occurs during a table dump. One use for this option is to cause *Note `mysqldump': 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', *Note `mysqldump': mysqldump. exits with an error message. With `--force', *Note `mysqldump': mysqldump. prints the error message, but it also writes an SQL comment containing the view definition to the dump output and continues executing. * `--host=HOST_NAME', `-h HOST_NAME' Dump data from the MySQL server on the given host. The default host is `localhost'. * `--hex-blob' Dump binary columns using hexadecimal notation (for example, `'abc'' becomes `0x616263'). The affected data types are *Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, the *Note `BLOB': blob. types, and *Note `BIT': bit-type. * `--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. * `--insert-ignore' Write *Note `INSERT IGNORE': insert. statements rather than *Note `INSERT': insert. statements. * `--lines-terminated-by=...' This option is used with the `--tab' option and has the same meaning as the corresponding `LINES' clause for *Note `LOAD DATA INFILE': load-data. See *Note load-data::. * `--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. * `--log-error=FILE_NAME' Log warnings and errors by appending them to the named file. The default is to do no logging. This option was added in MySQL 5.1.18. * `--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 *Note `CHANGE MASTER TO': 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 *Note `CHANGE MASTER TO': 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. To do this, use the following procedure on the existing slave: 1. Stop the slave's SQL thread and get its current status: mysql> STOP SLAVE SQL_THREAD; mysql> SHOW SLAVE STATUS; 2. From the output of the *Note `SHOW SLAVE STATUS': show-slave-status. statement, the binary log coordinates of the master server from which the new slave should start replicating are the values of the `Relay_Master_Log_File' and `Exec_Master_Log_Pos' fields. Denote those values as FILE_NAME and FILE_POS. 3. Dump the slave server: shell> mysqldump --master-data=2 --all-databases > dumpfile Using `--master-data=2' works only if binary logging has been enabled on the slave. Otherwise, *Note `mysqldump': mysqldump. fails with the error `Binlogging on server not active'. In this case you must handle any locking issues in another manner, using one or more of `--add-locks', `--lock-tables', `--lock-all-tables', or `--single-transaction', as required by your application and environment. 4. Restart the slave: mysql> START SLAVE; 5. On the new slave, load the dump file: shell> mysql < dumpfile 6. On the new slave, set the replication coordinates to those of the master server obtained earlier: mysql> CHANGE MASTER TO -> MASTER_LOG_FILE = 'FILE_NAME', MASTER_LOG_POS = FILE_POS; The *Note `CHANGE MASTER TO': change-master-to. statement might also need other parameters, such as `MASTER_HOST' to point the slave to the correct master server host. Add any such parameters as necessary. * `--no-autocommit' Enclose the *Note `INSERT': insert. statements for each dumped table within `SET autocommit = 0' and *Note `COMMIT': commit. statements. * `--no-create-db', `-n' This option suppresses the *Note `CREATE DATABASE': 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 *Note `CREATE TABLE': create-table. statements that re-create each dumped table. *Note*: This option does _not_ not exclude statements creating log file groups or tablespaces from *Note `mysqldump': mysqldump. output; in MySQL 5.1.14 and later, you can use the `--no-tablespaces' option for this purpose. * `--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 *Note `CREATE TABLE': create-table. statement for the table (for example, to create an empty copy of the table by loading the dump file). * `--no-set-names', `-N' This has the same effect as `--skip-set-charset'. * `--no-tablespaces', `-y' This option suppresses all *Note `CREATE LOGFILE GROUP': create-logfile-group. and *Note `CREATE TABLESPACE': create-tablespace. statements in the output of *Note `mysqldump': mysqldump. This option was added in MySQL 5.1.14. * `--opt' This option is shorthand. It is the same as specifying `--add-drop-table' `--add-locks' `--create-options' `--disable-keys' `--extended-insert' `--lock-tables' `--quick' `--set-charset'. It should give you a fast dump operation and produce a dump file that can be reloaded into a MySQL server quickly. _The `--opt' option is enabled by default. Use `--skip-opt' to disable it._ See the discussion at the beginning of this section for information about selectively enabling or disabling a subset of the options affected by `--opt'. * `--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 will make the dump operation take considerably longer. * `--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, *Note `mysqldump': mysqldump. prompts for one. Specifying a password on the command line should be considered insecure. See *Note 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. * `--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 *Note connecting::. * `--quick', `-q' This option is useful for dumping large tables. It forces *Note `mysqldump': 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. * `--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'. * `--replace' Write *Note `REPLACE': replace. statements rather than *Note `INSERT': insert. statements. This option was added in MySQL 5.1.3. * `--result-file=FILE_NAME', `-r FILE_NAME' Direct output to a given file. This option should be used on Windows to prevent newline ``\n'' characters from being converted to ``\r\n'' carriage return/newline sequences. The result file is created and its previous contents overwritten, even if an error occurs while generating the dump. * `--routines', `-R' Include stored routines (procedures and functions) for the dumped databases in the output. Use of this option requires the `SELECT' privilege for the `mysql.proc' table. The output generated by using `--routines' contains *Note `CREATE PROCEDURE': create-procedure. and *Note `CREATE FUNCTION': create-function. statements to re-create the routines. However, these statements do not include attributes such as the routine creation and modification timestamps. This means that when the routines are reloaded, they will be created with the timestamps equal to the reload time. If you require routines to be re-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 was added in MySQL 5.1.2. Before that, stored routines are not dumped. Routine `DEFINER' values are not dumped until MySQL 5.1.8. This means that before 5.1.8, when routines are reloaded, they will be created with the definer set to the reloading user. If you require routines to be re-created with their original definer, dump and load the contents of the `mysql.proc' table directly as described earlier. Prior to MySQL 5.1.62, this option had no effect when used together with the `--xml' option. (Bug #11760384, Bug #52792) * `--set-charset' Add `SET NAMES DEFAULT_CHARACTER_SET' to the output. This option is enabled by default. To suppress the `SET NAMES' statement, use `--skip-set-charset'. * `--single-transaction' This option sets the transaction isolation mode to `REPEATABLE READ' and sends a *Note `START TRANSACTION': commit. 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 *Note `START TRANSACTION': commit. 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: *Note `ALTER TABLE': alter-table, *Note `CREATE TABLE': create-table, *Note `DROP TABLE': drop-table, *Note `RENAME TABLE': rename-table, *Note `TRUNCATE TABLE': truncate-table. A consistent read is not isolated from those statements, so use of them on a table to be dumped can cause the *Note `SELECT': select. that is performed by *Note `mysqldump': 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 *Note `LOCK TABLES': lock-tables. causes any pending transactions to be committed implicitly. This option is not supported for MySQL Cluster tables; the results cannot be guaranteed to be consistent due to the fact that the *Note `NDBCLUSTER': mysql-cluster. storage engine supports only the `READ_COMMITTED' transaction isolation level. You should always use *Note `NDB': mysql-cluster. backup and restore instead. To dump large tables, you should combine the `--single-transaction' option with `--quick'. * `--skip-comments' See the description for the `--comments' option. * `--skip-opt' See the description for the `--opt' option. * `--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 *Note ssl-options::. * `--tab=PATH', `-T PATH' Produce tab-separated text-format data files. For each dumped table, *Note `mysqldump': mysqldump. creates a `TBL_NAME.sql' file that contains the *Note `CREATE TABLE': 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 *Note `mysqldump': mysqldump. is run on the same machine as the *Note `mysqld': mysqld. server. You must have the `FILE' privilege, and the server must have permission to write files in the directory that you specify. 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. As of MySQL 5.1.38, column values are converted to the character set specified by the `--default-character-set' option. Prior to 5.1.38 or if no such option is present, values are dumped using the `binary' character set. In effect, there is no character set conversion. If a table contains columns in several character sets, the output data file will as well and you may not be able to reload the file correctly. * `--tables' Override the `--databases' or `-B' option. *Note `mysqldump': 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'. * `--tz-utc' This option enables *Note `TIMESTAMP': datetime. columns to be dumped and reloaded between servers in different time zones. *Note `mysqldump': mysqldump. sets its connection time zone to UTC and adds `SET TIME_ZONE='+00:00'' to the dump file. Without this option, *Note `TIMESTAMP': datetime. 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'. This option was added in MySQL 5.1.2. * `--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. * `--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" * `--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. For a column named COLUMN_NAME, the `NULL' value, an empty string, and the string value `'NULL'' are distinguished from one another in the XML output generated by the *Note `mysqldump': mysqldump. `--xml', `-X' option, as shown in this table. Value: XML Representation: `NULL' (_unknown value_) `' `''' (_empty string_) `' `'NULL'' (_string value_) `NULL' Beginning with MySQL 5.1.12, the output from the *Note `mysql': mysql. client when run using the `--xml' option also follows the preceding rules. (See *Note mysql-command-options::.) Beginning with MySQL 5.1.18, XML output from *Note `mysqldump': mysqldump. includes the XML namespace, as shown here: shell> mysqldump --xml -u root world City 1 Kabul AFG Kabol 1780000 ... 4079 Rafah PSE Rafah 92020 Prior to MySQL 5.1.62, this option prevented the `--routines' option from working correctly--that is, no stored routines, triggers, or events could be dumped in XML format. (Bug #11760384, Bug #52792) 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 *Note `INSERT': insert. statements (as with the `--extended-insert' or `--opt' option), *Note `mysqldump': mysqldump. creates rows up to `net_buffer_length' length. If you increase this variable, you should also ensure that the `net_buffer_length' variable in the MySQL server is at least this large. A common use of *Note `mysqldump': mysqldump. is for making a backup of an entire database: shell> mysqldump DB_NAME > BACKUP-FILE.SQL You can load the dump file back into the server like this: shell> mysql DB_NAME < BACKUP-FILE.SQL Or like this: shell> mysql -e "source /PATH-TO-BACKUP/BACKUP-FILE.SQL" DB_NAME *Note `mysqldump': 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 It is possible to 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, *Note `mysqldump': mysqldump. provides a way of making an online backup: shell> mysqldump --all-databases --single-transaction > all_databases.sql This backup acquires a global read lock on all tables (using *Note `FLUSH TABLES WITH READ LOCK': flush.) 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 *Note `FLUSH': 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 *Note 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 *Note backup-methods::, and *Note backup-strategy-example::. If you encounter problems backing up views, please read the section that covers restrictions on views which describes a workaround for backing up views when this fails due to insufficient privileges. See *Note view-restrictions::.  File: manual.info, Node: mysqlimport, Next: mysqlshow, Prev: mysqldump, Up: programs-client 4.5.5 `mysqlimport' -- A Data Import Program -------------------------------------------- The *Note `mysqlimport': mysqlimport. client provides a command-line interface to the *Note `LOAD DATA INFILE': load-data. SQL statement. Most options to *Note `mysqlimport': mysqlimport. correspond directly to clauses of *Note `LOAD DATA INFILE': load-data. syntax. See *Note load-data::. Invoke *Note `mysqlimport': mysqlimport. like this: shell> mysqlimport [OPTIONS] DB_NAME TEXTFILE1 [TEXTFILE2 ...] For each text file named on the command line, *Note `mysqlimport': 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'. *Note `mysqlimport': mysqlimport. supports the following options, which can be specified on the command line or in the `[mysqlimport]' and `[client]' groups of an option file. *Note `mysqlimport': mysqlimport. also supports the options for processing option files described at *Note option-file-options::. *`mysqlimport' Options* Format Option File Description Introduced -bind-address=ip_addressbind-addressUse the specified network 5.1.22-ndb-6.3.4 interface to connect to the MySQL Server -columns=column_listcolumns This option takes a comma-separated list of column names as its value -compress compress Compress all information sent between the client and the server -debug[=debug_options]debug Write a debugging log -debug-checkdebug-check Print debugging information 5.1.21 when the program exits -debug-info debug-info Print debugging information, 5.1.14 memory and CPU statistics when the program exits -default-character-set=charset_namedefault-character-setUse charset_name as the default character set -delete delete Empty the table before importing the text file -fields-enclosed-by=stringfields-enclosed-byThis option has the same meaning as the corresponding clause for LOAD DATA INFILE -fields-escaped-byfields-escaped-byThis option has the same meaning as the corresponding clause for LOAD DATA INFILE -fields-optionally-enclosed-by=stringfields-optionally-enclosed-byThis option has the same meaning as the corresponding clause for LOAD DATA INFILE -fields-terminated-by=stringfields-terminated-by- This option has the same meaning as the corresponding clause for LOAD DATA INFILE -force force Continue even if an SQL error occurs -help Display help message and exit -host=host_namehost Connect to the MySQL server on the given host -ignore ignore See the description for the -replace option -ignore-lines=#ignore-linesIgnore the first N lines of the data file -lines-terminated-by=stringlines-terminated-byThis option has the same meaning as the corresponding clause for LOAD DATA INFILE -local local Read input files locally from the client host -lock-tableslock-tables Lock all tables for writing before processing any text files -low-prioritylow-priorityUse LOW_PRIORITY when loading the table. -password[=password]password The password to use when connecting to the server -pipe On Windows, connect to server using a named pipe -port=port_numport The TCP/IP port number to use for the connection -protocol=typeprotocol The connection protocol to use -replace replace The -replace and -ignore options control handling of input rows that duplicate existing rows on unique key values -silent silent Produce output only when errors occur -socket=pathsocket For connections to localhost -ssl-ca=file_namessl-ca The path to a file that contains a list of trusted SSL CAs -ssl-capath=dir_namessl-capath The path to a directory that contains trusted SSL CA certificates in PEM format -ssl-cert=file_namessl-cert The name of the SSL certificate file to use for establishing a secure connection -ssl-cipher=cipher_listssl-cipher A list of allowable ciphers to use for SSL encryption -ssl-key=file_namessl-key The name of the SSL key file to use for establishing a secure connection -ssl-verify-server-certssl-verify-server-certThe server's Common Name value in its certificate is verified against the host name used when connecting to the server -use-threads=#use-threads The number of threads for 5.1.7 parallel file-loading -user=user_name,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, this option can be used to select which interface is employed when connecting to the MySQL server. This option is supported only in the version of *Note `mysqlimport': mysqlimport. that is supplied with MySQL Cluster, beginning with MySQL Cluster NDB 6.3.4. It is not available in standard MySQL 5.1 releases. * `--character-sets-dir=PATH' The directory where character sets are installed. See *Note 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. This option was added in MySQL 5.1.21. * `--debug-info' Print debugging information and memory and CPU usage statistics when the program exits. This option was added in MySQL 5.1.14. * `--default-character-set=CHARSET_NAME' Use CHARSET_NAME as the default character set. See *Note charset-configuration::. 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. * `--delete', `-D' Empty the table before importing the text file. * `--fields-terminated-by=...', `--fields-enclosed-by=...', `--fields-optionally-enclosed-by=...', `--fields-escaped-by=...' These options have the same meaning as the corresponding clauses for *Note `LOAD DATA INFILE': load-data. See *Note 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', *Note `mysqlimport': 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 *Note `LOAD DATA INFILE': load-data. 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 *Note load-data::. * `--local', `-L' Read input files locally from the client host. * `--lock-tables', `-l' Lock _all_ tables for writing before processing any text files. This ensures that all tables are synchronized on the server. * `--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'). * `--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, *Note `mysqlimport': mysqlimport. prompts for one. Specifying a password on the command line should be considered insecure. See *Note 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. * `--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 *Note 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. * `--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 *Note ssl-options::. * `--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. This option was added in MySQL 5.1.7. * `--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 *Note `mysqlimport': 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 | +------+---------------+  File: manual.info, Node: mysqlshow, Next: mysqlslap, Prev: mysqlimport, Up: programs-client 4.5.6 `mysqlshow' -- Display Database, Table, and Column Information -------------------------------------------------------------------- The *Note `mysqlshow': mysqlshow. client can be used to quickly see which databases exist, their tables, or a table's columns or indexes. *Note `mysqlshow': mysqlshow. provides a command-line interface to several SQL *Note `SHOW': show. statements. See *Note show::. The same information can be obtained by using those statements directly. For example, you can issue them from the *Note `mysql': mysql. client program. Invoke *Note `mysqlshow': 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, *Note `mysqlshow': 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. *Note `mysqlshow': mysqlshow. supports the following options, which can be specified on the command line or in the `[mysqlshow]' and `[client]' groups of an option file. *Note `mysqlshow': mysqlshow. also supports the options for processing option files described at *Note option-file-options::. *`mysqlshow' Options* Format Option File Description Introduced -bind-address=ip_addressbind-addressUse the specified network 5.1.22-ndb-6.3.4 interface to connect to the MySQL Server -compress compress Compress all information sent between the client and the server -count count Show the number of rows per table -debug[=debug_options]debug Write a debugging log -debug-checkdebug-check Print debugging information 5.1.21 when the program exits -debug-info debug-info Print debugging information, 5.1.14 memory and CPU statistics when the program exits -default-character-set=charset_namedefault-character-setUse charset_name as the default character set -help Display help message and exit -host=host_namehost Connect to the MySQL server on the given host -keys keys Show table indexes -password[=password]password The password to use when connecting to the server -pipe On Windows, connect to server using a named pipe -port=port_numport The TCP/IP port number to use for the connection -protocol=typeprotocol The connection protocol to use -show-table-type Show a column indicating the table type -socket=pathsocket For connections to localhost -ssl-ca=file_namessl-ca The path to a file that contains a list of trusted SSL CAs -ssl-capath=dir_namessl-capath The path to a directory that contains trusted SSL CA certificates in PEM format -ssl-cert=file_namessl-cert The name of the SSL certificate file to use for establishing a secure connection -ssl-cipher=cipher_listssl-cipher A list of allowable ciphers to use for SSL encryption -ssl-key=file_namessl-key The name of the SSL key file to use for establishing a secure connection -ssl-verify-server-certssl-verify-server-certThe server's Common Name value in its certificate is verified against the host name used when connecting to the server -status status Display extra information about each table -user=user_name,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, this option can be used to select which interface is employed when connecting to the MySQL server. This option is supported only in the version of *Note `mysqlshow': mysqlshow. that is supplied with MySQL Cluster, beginning with MySQL Cluster NDB 6.3.4. It is not available in standard MySQL 5.1 releases. * `--character-sets-dir=PATH' The directory where character sets are installed. See *Note 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. This option was added in MySQL 5.1.21. * `--debug-info' Print debugging information and memory and CPU usage statistics when the program exits. This option was added in MySQL 5.1.14. * `--default-character-set=CHARSET_NAME' Use CHARSET_NAME as the default character set. See *Note charset-configuration::. * `--host=HOST_NAME', `-h HOST_NAME' Connect to the MySQL server on the given host. * `--keys', `-k' Show table indexes. * `--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, *Note `mysqlshow': mysqlshow. prompts for one. Specifying a password on the command line should be considered insecure. See *Note 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. * `--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 *Note connecting::. * `--show-table-type', `-t' Show a column indicating the table type, as in *Note `SHOW FULL TABLES': show-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 *Note ssl-options::. * `--status', `-i' Display extra information about each table. * `--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.  File: manual.info, Node: mysqlslap, Prev: mysqlshow, Up: programs-client 4.5.7 `mysqlslap' -- Load Emulation Client ------------------------------------------ *Note `mysqlslap': 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. *Note `mysqlslap': mysqlslap. is available as of MySQL 5.1.4. Invoke *Note `mysqlslap': 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; *Note `mysqlslap': mysqlslap. does not understand them. *Note `mysqlslap': 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 *Note `mysqlslap': mysqlslap. build the query SQL statement with a table of two *Note `INT': integer-types. columns and three *Note `VARCHAR': char. 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=";" *Note `mysqlslap': mysqlslap. supports the following options, which can be specified on the command line or in the `[mysqlslap]' and `[client]' groups of an option file. *Note `mysqlslap': mysqlslap. also supports the options for processing option files described at *Note option-file-options::. *`mysqlslap' Options* Format Option File Description IntroducedRemoved -auto-generate-sqlauto-generate-sqlGenerate SQL statements automatically when they are not supplied in files or using command options -auto-generate-sql-add-autoincrementauto-generate-sql-add-autoincrementAdd AUTO_INCREMENT column to 5.1.18 automatically generated tables -auto-generate-sql-execute-number=#auto-generate-sql-execute-numberSpecify how many queries to 5.1.18 generate automatically -auto-generate-sql-guid-primaryauto-generate-sql-guid-primaryAdd a GUID-based primary key 5.1.18 to automatically generated tables -auto-generate-sql-load-type=typeauto-generate-sql-load-typeSpecify how many queries to 5.1.16 generate automatically -auto-generate-sql-secondary-indexes=#auto-generate-sql-secondary-indexesSpecify how many secondary 5.1.18 indexes to add to automatically generated tables -auto-generate-sql-unique-query-number=#auto-generate-sql-unique-query-numberHow many different queries 5.1.18 to generate for automatic tests. -auto-generate-sql-unique-write-number=#auto-generate-sql-unique-write-numberHow many different queries 5.1.18 to generate for -auto-generate-sql-write-number -auto-generate-sql-write-number=#auto-generate-sql-write-numberHow many row inserts to 5.1.16 perform on each thread -commit=# commit How many statements to 5.1.21 execute before committing. -compress compress Compress all information sent between the client and the server -concurrency=#concurrency The number of clients to simulate when issuing the SELECT statement -create=valuecreate The file or string containing the statement to use for creating the table -create-schema=valuecreate-schemaThe schema in which to run 5.1.5 the tests -csv=[file] csv Generate output in comma-separated values format -debug[=debug_options]debug Write a debugging log -debug-checkdebug-check Print debugging information 5.1.21 when the program exits -debug-info debug-info Print debugging information, 5.1.21 memory and CPU statistics when the program exits -delimiter=strdelimiter The delimiter to use in SQL statements -detach=# detach Detach (close and reopen) 5.1.21 each connection after each N statements -engine=engine_nameengine The storage engine to use for creating the table -help Display help message and exit -host=host_namehost Connect to the MySQL server on the given host -iterations=#iterations The number of times to run the tests -lock-directory=pathlock-directoryThe directory to use for 5.1.5 5.1.18 storing locks -no-drop no-drop Do not drop any schema 5.1.57 created during the test run -number-char-cols=#number-char-colsThe number of VARCHAR columns to use if -auto-generate-sql is specified -number-int-cols=#number-int-colsThe number of INT columns to use if -auto-generate-sql is specified -number-of-queries=#number-of-queriesLimit each client to 5.1.5 approximately this number of queries -only-print only-print Do not connect to databases. 5.1.5 mysqlslap only prints what it would have done -password[=password]password The password to use when connecting to the server -pipe On Windows, connect to server using a named pipe -port=port_numport The TCP/IP port number to use for the connection -post-query=valuepost-query The file or string 5.1.18 containing the statement to execute after the tests have completed -post-system=strpost-system The string to execute using 5.1.21 system() after the tests have completed -pre-query=valuepre-query The file or string 5.1.18 containing the statement to execute before running the tests -pre-system=strpre-system The string to execute using 5.1.21 system() before running the tests -preserve-schemapreserve-schemaPreserve the schema from the 5.1.5 5.1.23 mysqlslap run -protocol=typeprotocol The connection protocol to use -query=valuequery The file or string containing the SELECT statement to use for retrieving data -silent silent Silent mode -slave slave Follow master locks for 5.1.5 5.1.18 other mysqlslap clients -socket=pathsocket For connections to localhost -ssl-ca=file_namessl-ca The path to a file that contains a list of trusted SSL CAs -ssl-capath=dir_namessl-capath The path to a directory that contains trusted SSL CA certificates in PEM format -ssl-cert=file_namessl-cert The name of the SSL certificate file to use for establishing a secure connection -ssl-cipher=cipher_listssl-cipher A list of allowable ciphers to use for SSL encryption -ssl-key=file_namessl-key The name of the SSL key file to use for establishing a secure connection -ssl-verify-server-certssl-verify-server-certThe server's Common Name value in its certificate is verified against the host name used when connecting to the server -use-threadsuse-threads On Unix, the default is to 5.1.6 5.1.18 use fork() calls -user=user_name,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. This option was added in MySQL 5.1.18. * `--auto-generate-sql-execute-number=N' Specify how many queries to generate automatically. This option was added in MySQL 5.1.18. * `--auto-generate-sql-guid-primary' Add a GUID-based primary key to automatically generated tables. This option was added in MySQL 5.1.18. * `--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'. This option was added in MySQL 5.1.16. * `--auto-generate-sql-secondary-indexes=N' Specify how many secondary indexes to add to automatically generated tables. By default, none are added. This option was added in MySQL 5.1.18. * `--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. This option was added in MySQL 5.1.18. * `--auto-generate-sql-unique-write-number=N' How many different queries to generate for `--auto-generate-sql-write-number'. The default is 10. This option was added in MySQL 5.1.18. * `--auto-generate-sql-write-number=N' How many row inserts to perform on each thread. The default is 100. This option was added in MySQL 5.1.16. * `--commit=N' How many statements to execute before committing. The default is 0 (no commits are done). This option was added in MySQL 5.1.21. * `--compress', `-C' Compress all information sent between the client and the server if both support compression. * `--concurrency=N', `-c N' The number of clients to simulate when issuing the *Note `SELECT': select. statement. * `--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. This option was added in MySQL 5.1.5. *Note*: If the `--auto-generate-sql' option is also given, *Note `mysqlslap': 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. This option was added in MySQL 5.1.5. * `--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. This option was added in MySQL 5.1.21. * `--debug-info', `-T' Print debugging information and memory and CPU usage statistics when the program exits. This option was added in MySQL 5.1.21. * `--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). This option was added in MySQL 5.1.21. * `--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. * `--lock-directory=PATH' The directory to use for storing locks. This option was added in MySQL 5.1.5 and removed in 5.1.18. * `--no-drop' Prevent *Note `mysqlslap': mysqlslap. from dropping any schema it creates during the test run. This option was added in MySQL 5.1.57. * `--number-char-cols=N', `-x N' The number of *Note `VARCHAR': char. columns to use if `--auto-generate-sql' is specified. * `--number-int-cols=N', `-y N' The number of *Note `INT': integer-types. 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 *Note `mysqlslap': 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)" This option was added in MySQL 5.1.5. * `--only-print' Do not connect to databases. *Note `mysqlslap': mysqlslap. only prints what it would have done. This option was added in MySQL 5.1.5. * `--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, *Note `mysqlslap': mysqlslap. prompts for one. Specifying a password on the command line should be considered insecure. See *Note 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. * `--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. This option was added in MySQL 5.1.18. * `--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. * `--post-system=STR' The string to execute using `system()' after the tests have completed. This execution is not counted for timing purposes. This option was added in MySQL 5.1.21. * `--pre-query=VALUE' The file or string containing the statement to execute before running the tests. This execution is not counted for timing purposes. This option was added in MySQL 5.1.18. * `--pre-system=STR' The string to execute using `system()' before running the tests. This execution is not counted for timing purposes. This option was added in MySQL 5.1.21. * `--preserve-schema' Preserve the schema from the *Note `mysqlslap': mysqlslap. run. The `--auto-generate-sql' and `--create' options disable this option. This option was added in MySQL 5.1.5 and removed in MySQL 5.1.23. * `--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 *Note connecting::. * `--query=VALUE', `-q VALUE' The file or string containing the *Note `SELECT': select. statement to use for retrieving data. * `--silent', `-s' Silent mode. No output. * `--slave' Follow master locks for other *Note `mysqlslap': mysqlslap. clients. Use this option if you are trying to synchronize around one master server with `--lock-directory' plus NFS. This option was added in MySQL 5.1.5 and removed in 5.1.18. * `--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 *Note ssl-options::. * `--use-threads' On Unix, the default is to use `fork()' calls and this option causes `pthread' calls to be used instead. (On Windows, the default is to use `pthread' calls and the option has no effect.) This option was added in MySQL 5.1.6 and removed in 5.1.18. * `--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.  File: manual.info, Node: programs-admin-utils, Next: programs-development, Prev: programs-client, Up: programs 4.6 MySQL Administrative and Utility Programs ============================================= * Menu: * innochecksum:: `innochecksum' --- Offline InnoDB File Checksum Utility * myisam-ftdump:: `myisam_ftdump' --- Display Full-Text Index information * myisamchk:: `myisamchk' --- MyISAM Table-Maintenance Utility * myisamlog:: `myisamlog' --- Display MyISAM Log File Contents * myisampack:: `myisampack' --- Generate Compressed, Read-Only MyISAM Tables * mysqlaccess:: `mysqlaccess' --- Client for Checking Access Privileges * mysqlbinlog:: `mysqlbinlog' --- Utility for Processing Binary Log Files * mysqldumpslow:: `mysqldumpslow' --- Summarize Slow Query Log Files * mysqlhotcopy:: `mysqlhotcopy' --- A Database Backup Program * instance-manager:: `mysqlmanager' --- The MySQL Instance Manager * mysql-convert-table-format:: `mysql_convert_table_format' --- Convert Tables to Use a Given Storage Engine * mysql-find-rows:: `mysql_find_rows' --- Extract SQL Statements from Files * mysql-fix-extensions:: `mysql_fix_extensions' --- Normalize Table File Name Extensions * mysql-setpermission:: `mysql_setpermission' --- Interactively Set Permissions in Grant Tables * mysql-waitpid:: `mysql_waitpid' --- Kill Process and Wait for Its Termination * mysql-zap:: `mysql_zap' --- Kill Processes That Match a Pattern This section describes administrative programs and programs that perform miscellaneous utility operations.  File: manual.info, Node: innochecksum, Next: myisam-ftdump, Prev: programs-admin-utils, Up: programs-admin-utils 4.6.1 `innochecksum' -- Offline InnoDB File Checksum Utility ------------------------------------------------------------ *Note `innochecksum': 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 will cause `InnoDB' to deliberately shut down a running server, it can be preferable to use this tool rather than waiting for a server in production usage to encounter the damaged pages. *Note `innochecksum': innochecksum. cannot be used on tablespace files that the server already has open. For such files, you should use *Note `CHECK TABLE': check-table. to check tables within the tablespace. If checksum mismatches are found, you would normally restore the tablespace from backup or start the server and attempt to use *Note `mysqldump': mysqldump. to make a backup of the tables within the tablespace. Invoke *Note `innochecksum': innochecksum. like this: shell> innochecksum [OPTIONS] FILE_NAME *Note `innochecksum': innochecksum. supports the following options. For options that refer to page numbers, the numbers are zero-based. * `-c' Print a count of the number of pages in the file. * `-d' Debug mode; prints checksums for each page. * `-e NUM' End at this page number. * `-p NUM' Check only this page number. * `-s NUM' Start at this page number. * `-v' Verbose mode; print a progress indicator every five seconds.  File: manual.info, Node: myisam-ftdump, Next: myisamchk, Prev: innochecksum, Up: programs-admin-utils 4.6.2 `myisam_ftdump' -- Display Full-Text Index information ------------------------------------------------------------ *Note `myisam_ftdump': 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 *Note `myisam_ftdump': myisam-ftdump, be sure to issue a `FLUSH TABLES' statement first if the server is running. *Note `myisam_ftdump': 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 *Note `myisam_ftdump': 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 *Note `myisam_ftdump': 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 *Note `myisam_ftdump': 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 *Note `myisam_ftdump': myisam-ftdump. in the database directory: shell> myisam_ftdump /usr/local/mysql/data/test/mytexttable 1 You can use *Note `myisam_ftdump': myisam-ftdump. to generate a list of index entries in order of frequency of occurrence like this: shell> myisam_ftdump -c mytexttable 1 | sort -r *Note `myisam_ftdump': 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.  File: manual.info, Node: myisamchk, Next: myisamlog, Prev: myisam-ftdump, Up: programs-admin-utils 4.6.3 `myisamchk' -- MyISAM Table-Maintenance Utility ----------------------------------------------------- * Menu: * myisamchk-general-options:: `myisamchk' General Options * myisamchk-check-options:: `myisamchk' Check Options * myisamchk-repair-options:: `myisamchk' Repair Options * myisamchk-other-options:: Other `myisamchk' Options * myisamchk-table-info:: Obtaining Table Information with `myisamchk' * myisamchk-memory:: `myisamchk' Memory Usage The *Note `myisamchk': myisamchk. utility gets information about your database tables or checks, repairs, or optimizes them. *Note `myisamchk': myisamchk. works with `MyISAM' tables (tables that have `.MYD' and `.MYI' files for storing data and indexes). You can also use the *Note `CHECK TABLE': check-table. and *Note `REPAIR TABLE': repair-table. statements to check and repair `MyISAM' tables. See *Note check-table::, and *Note repair-table::. The use of *Note `myisamchk': 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 *Note `myisamchk': myisamchk. like this: shell> myisamchk [OPTIONS] TBL_NAME ... The OPTIONS specify what you want *Note `myisamchk': myisamchk. to do. They are described in the following sections. You can also get a list of options by invoking *Note `myisamchk --help': myisamchk. With no options, *Note `myisamchk': myisamchk. simply checks your table as the default operation. To get more information or to tell *Note `myisamchk': 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 *Note `myisamchk': myisamchk. somewhere other than in the database directory, you must specify the path to the database directory, because *Note `myisamchk': myisamchk. has no idea where the database is located. In fact, *Note `myisamchk': 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 *Note `myisamchk': 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 *Note `myisamchk': myisamchk, see *Note myisamchk-memory::. For additional information about using *Note `myisamchk': myisamchk, see *Note myisam-table-maintenance::. *Important*: _You must ensure that no other program is using the tables while you are running *Note `myisamchk': myisamchk._. The most effective means of doing so is to shut down the MySQL server while running *Note `myisamchk': myisamchk, or to lock all tables that *Note `myisamchk': myisamchk. is being used on. Otherwise, when you run *Note `myisamchk': 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 *Note `mysqld': 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 *Note `mysqld': mysqld. is running, you must force it to flush any table modifications that are still buffered in memory by using *Note `FLUSH TABLES': flush. You should then ensure that no one is using the tables while you are running *Note `myisamchk': myisamchk. However, the easiest way to avoid this problem is to use *Note `CHECK TABLE': check-table. instead of *Note `myisamchk': myisamchk. to check tables. See *Note check-table::. *Note `myisamchk': myisamchk. supports the following options, which can be specified on the command line or in the `[myisamchk]' group of an option file. *Note `myisamchk': myisamchk. also supports the options for processing option files described at *Note option-file-options::. *`myisamchk' Options* Format Option File Description IntroducedDeprecated -analyze analyze Analyze the distribution of key values -backup backup Make a backup of the .MYD file as file_name-time.BAK -block-search=offsetblock-searchFind the record that a block at the given offset belongs to -check check Check the table for errors -check-only-changedcheck-only-changedCheck only tables that have changed since the last check -correct-checksumcorrect-checksumCorrect the checksum information for the table -data-file-length=lendata-file-lengthMaximum length of the data file (when re-creating data file when it is full) -debug[=debug_options]debug Write a debugging log decode_bits=#decode_bits Decode_bits -descriptiondescription Print some descriptive information about the table -extend-checkextend-checkDo very thorough table check or repair that tries to recover every possible row from the data file -fast fast Check only tables that haven't been closed properly -force force Do a repair operation automatically if myisamchk finds any errors in the table -force force-recoverOverwrite old temporary files. For use with the -r or -o option ft_max_word_len=#ft_max_word_lenMaximum word length for FULLTEXT indexes ft_min_word_len=#ft_min_word_lenMinimum word length for FULLTEXT indexes ft_stopword_file=valueft_stopword_fileUse stopwords from this file instead of built-in list -HELP Display help message and exit -help Display help message and exit -informationinformation Print informational statistics about the table that is checked key_buffer_size=#key_buffer_sizeThe size of the buffer used for index blocks for MyISAM tables -keys-used=valkeys-used A bit-value that indicates which indexes to update -max-record-length=lenmax-record-lengthSkip rows larger than the given length if myisamchk cannot allocate memory to hold them -medium-checkmedium-checkDo a check that is faster than an -extend-check operation myisam_block_size=#myisam_block_sizeBlock size to be used for MyISAM index pages myisam_sort_buffer_size=#myisam_sort_buffer_sizeThe buffer that is allocated 5.1.67 when sorting the index when doing a REPAIR or when creating indexes with CREATE INDEX or ALTER TABLE -parallel-recoverparallel-recoverUses the same technique as -r and -n, but creates all the keys in parallel, using different threads (beta) -quick quick Achieve a faster repair by not modifying the data file. read_buffer_size=#read_buffer_sizeEach thread that does a sequential scan allocates a buffer of this size for each table it scans -read-only read-only Don't mark the table as checked -recover recover Do a repair that can fix almost any problem except unique keys that aren't unique -safe-recoversafe-recoverDo 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[=value]set-auto-incrementForce AUTO_INCREMENT numbering for new records to start at the given value -set-collation=nameset-collationSpecify the collation to use for sorting table indexes -silent silent Silent mode sort_buffer_size=#sort_buffer_sizeThe buffer that is allocated 5.1.67 when sorting the index when doing a REPAIR or when creating indexes with CREATE INDEX or ALTER TABLE -sort-index sort-index Sort the index tree blocks in high-low order sort_key_blocks=#sort_key_blockssort_key_blocks -sort-records=#sort-recordsSort records according to a particular index -sort-recoversort-recoverForce myisamchk to use sorting to resolve the keys even if the temporary files would be very large stats_method=valuestats_methodSpecifies how MyISAM index statistics collection code should treat NULLs -tmpdir=pathtmpdir Path of the directory to be used for storing temporary files -unpack unpack Unpack a table that was packed with myisampack -update-stateupdate-stateStore 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_sizeWrite buffer size  File: manual.info, Node: myisamchk-general-options, Next: myisamchk-check-options, Prev: myisamchk, Up: myisamchk 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 *Note `myisamchk': 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''. * `--silent', `-s' Silent mode. Write output only when errors occur. You can use `-s' twice (`-ss') to make *Note `myisamchk': 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 *Note `mysqld': mysqld. with external locking disabled, the table can be locked only by another *Note `myisamchk': myisamchk. command. You can also set the following variables by using `--VAR_NAME=VALUE' syntax: This table lists *Note `myisamchk': myisamchk. variables that can be set using `--VAR_NAME=VALUE' syntax. The table also provides the default value for each variable. 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 *Note `myisamchk': myisamchk. variables and their default values can be examined with *Note `myisamchk --help': myisamchk.: `sort_buffer_size' is used when the keys are repaired by sorting keys, which is the normal case when you use `--recover'. As of MySQL 5.1.67, `myisam_sort_buffer_size' is available as an alternative name to `sort_buffer_size'. `myisam_sort_buffer_size' is preferable to `sort_buffer_size' because its name corresponds to the `myisam_sort_buffer_size' server system variable that has a similar meaning. `sort_buffer_size' should be considered deprecated. `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 *Note `CHAR': char, *Note `VARCHAR': char, or *Note `TEXT': blob. 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 *Note `myisamchk': 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 *Note server-system-variables::, and *Note myisam-index-statistics::. `ft_min_word_len' and `ft_max_word_len' indicate the minimum and maximum word length for `FULLTEXT' indexes. `ft_stopword_file' names the stopword file. These need to be set under the following circumstances. If you use *Note `myisamchk': 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 *Note `myisamchk': myisamchk. that you use for *Note `mysqld': mysqld. For example, if you have set the minimum word length to 3, you can repair a table with *Note `myisamchk': myisamchk. like this: shell> myisamchk --recover --ft_min_word_len=3 TBL_NAME.MYI To ensure that *Note `myisamchk': 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 *Note `myisamchk': myisamchk. is to use the *Note `REPAIR TABLE': repair-table, *Note `ANALYZE TABLE': analyze-table, *Note `OPTIMIZE TABLE': optimize-table, or *Note `ALTER TABLE': alter-table. These statements are performed by the server, which knows the proper full-text parameter values to use.  File: manual.info, Node: myisamchk-check-options, Next: myisamchk-repair-options, Prev: myisamchk-general-options, Up: myisamchk 4.6.3.2 `myisamchk' Check Options ................................. *Note `myisamchk': 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, *Note `myisamchk': myisamchk. or *Note `myisamchk --medium-check': myisamchk. 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 *Note myisamchk-table-info::. * `--fast', `-F' Check only tables that haven't been closed properly. * `--force', `-f' Do a repair operation automatically if *Note `myisamchk': 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 *Note `myisamchk': myisamchk. to check a table that is in use by some other application that does not use locking, such as *Note `mysqld': 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 *Note `mysqld': mysqld. server is using the table and you are running it with external locking disabled.  File: manual.info, Node: myisamchk-repair-options, Next: myisamchk-other-options, Prev: myisamchk-check-options, Up: myisamchk 4.6.3.3 `myisamchk' Repair Options .................................. *Note `myisamchk': 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=PATH' The directory where character sets are installed. See *Note 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 *Note 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 *Note `myisamchk': 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 *Note `myisamchk -r': myisamchk. * `--no-symlinks', `-l' Do not follow symbolic links. Normally *Note `myisamchk': 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 *Note `myisamchk': 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 *Note `myisamchk': 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 *Note `myisamchk': 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-character-set=NAME' Change the character set used by the table indexes. This option was replaced by `--set-collation' in MySQL 5.0.3. * `--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 *Note `myisamchk': myisamchk. to use sorting to resolve the keys even if the temporary files would be very large. * `--tmpdir=PATH', `-t PATH' The path of the directory to be used for storing temporary files. If this is not set, *Note `myisamchk': 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, NetWare, and OS/2. * `--unpack', `-u' Unpack a table that was packed with *Note `myisampack': myisampack.  File: manual.info, Node: myisamchk-other-options, Next: myisamchk-table-info, Prev: myisamchk-repair-options, Up: myisamchk 4.6.3.4 Other `myisamchk' Options ................................. *Note `myisamchk': 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 *Note `myisamchk --description --verbose TBL_NAME': myisamchk. 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 *Note 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 *Note `SELECT': 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 *Note `SHOW INDEX': show-index, which displays a table's indexes in the same order that *Note `myisamchk': myisamchk. sees them. Indexes are numbered beginning with 1. If keys are not packed (`PACK_KEYS=0'), they have the same length, so when *Note `myisamchk': myisamchk. sorts and moves records, it just overwrites record offsets in the index. If keys are packed (`PACK_KEYS=1'), *Note `myisamchk': 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.)  File: manual.info, Node: myisamchk-table-info, Next: myisamchk-memory, Prev: myisamchk-other-options, Up: myisamchk 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. * *Note `myisamchk -d TBL_NAME': myisamchk. Runs *Note `myisamchk': myisamchk. in `describe mode' to produce a description of your table. If you start the MySQL server with external locking disabled, *Note `myisamchk': myisamchk. may report an error for a table that is updated while it runs. However, because *Note `myisamchk': myisamchk. does not change the table in describe mode, there is no risk of destroying data. * *Note `myisamchk -dv TBL_NAME': myisamchk. Adding `-v' runs *Note `myisamchk': myisamchk. in verbose mode so that it produces more information about the table. Adding `-v' a second time produces even more information. * *Note `myisamchk -eis TBL_NAME': myisamchk. Shows only the most important information from a table. This operation is slow because it must read the entire table. * *Note `myisamchk -eiv TBL_NAME': myisamchk. 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 *Note 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 *Note `myisamchk': 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; 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 *Note `myisamchk -dvv': myisamchk. 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 *Note `myisamchk': 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. Currently 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 *Note 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 *Note 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, *Note `myisamchk': 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 *Note `myisamchk -a': myisamchk. 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 *Note `ENUM': 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 *Note `myisampack': myisampack. See *Note myisampack::, for an example of this information. Example of *Note `myisamchk -eiv': myisamchk. 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) *Note `myisamchk -eiv': myisamchk. 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 *Note myisam-optimization::. * `Key' The key number. * `Keyblocks used' What percentage of the keyblocks are used. When a table has just been reorganized with *Note `myisamchk': 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 *Note `CHAR': char. and *Note `VARCHAR': char. 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 *Note 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.  File: manual.info, Node: myisamchk-memory, Prev: myisamchk-table-info, Up: myisamchk 4.6.3.6 `myisamchk' Memory Usage ................................ Memory allocation is important when you run *Note `myisamchk': myisamchk. *Note `myisamchk': myisamchk. uses no more memory than its memory-related variables are set to. If you are going to use *Note `myisamchk': 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 *Note `myisamchk': 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 *Note `myisamchk': 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 *Note `myisamchk': myisamchk. with the `--tmpdir=PATH' option to specify a directory located on a file system that has more space. When performing repair operations, *Note `myisamchk': 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=PATH'). 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 *Note `myisamchk -dv TBL_NAME': myisamchk. (see *Note 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'.  File: manual.info, Node: myisamlog, Next: myisampack, Prev: myisamchk, Up: programs-admin-utils 4.6.4 `myisamlog' -- Display MyISAM Log File Contents ----------------------------------------------------- *Note `myisamlog': 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 *Note `myisamlog': 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. *Note `myisamlog': 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. * `-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.  File: manual.info, Node: myisampack, Next: mysqlaccess, Prev: myisamlog, Up: programs-admin-utils 4.6.5 `myisampack' -- Generate Compressed, Read-Only MyISAM Tables ------------------------------------------------------------------ The *Note `myisampack': myisampack. utility compresses `MyISAM' tables. *Note `myisampack': myisampack. works by compressing each column in the table separately. Usually, *Note `myisampack': 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 *Note `mysqld': mysqld. server was invoked with external locking disabled, it is not a good idea to invoke *Note `myisampack': 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). Invoke *Note `myisampack': 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 *Note `myisampack': myisampack, you should use *Note `myisamchk -rq': myisamchk. to rebuild its indexes. *Note myisamchk::. *Note `myisampack': myisampack. supports the following options. It also reads option files and supports the options for processing them described at *Note 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=PATH' The directory where character sets are installed. See *Note 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 *Note `myisampack': myisampack. exists. (*Note `myisampack': myisampack. creates an intermediate file named `TBL_NAME.TMD' in the database directory while it compresses the table. If you kill *Note `myisampack': myisampack, the `.TMD' file might not be deleted.) Normally, *Note `myisampack': myisampack. exits with an error if it finds that `TBL_NAME.TMD' exists. With `--force', *Note `myisampack': 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. The join operation does not create a `.frm' file for BIG_TBL_NAME, so after the join operation finishes, copy the `.frm' file from one of the source tables and name it `BIG_TBL_NAME.frm'. * `--silent', `-s' Silent mode. Write output only when errors occur. * `--test', `-t' Do not actually pack the table, just test packing it. * `--tmpdir=PATH', `-T PATH' Use the named directory as the location where *Note `myisampack': 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 *Note `mysqld': mysqld. server was invoked with external locking disabled, it is not a good idea to invoke *Note `myisampack': 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> 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 *Note `myisampack': 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 *Note `BIGINT': integer-types. column (eight bytes) can be stored as a *Note `TINYINT': integer-types. 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 *Note `ENUM': 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 *Note `myisamchk -dvv': myisamchk. 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 *Note `ENUM': 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 *Note `myisampack': myisampack, you must run *Note `myisamchk': 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 *Note `mysqladmin flush-tables': mysqladmin. to force *Note `mysqld': mysqld. to start using the new table. To unpack a packed table, use the `--unpack' option to *Note `myisamchk': myisamchk.  File: manual.info, Node: mysqlaccess, Next: mysqlbinlog, Prev: myisampack, Up: programs-admin-utils 4.6.6 `mysqlaccess' -- Client for Checking Access Privileges ------------------------------------------------------------ *Note `mysqlaccess': mysqlaccess. is a diagnostic tool that Yves Carlier has provided for the MySQL distribution. It checks the access privileges for a host name, user name, and database combination. Note that *Note `mysqlaccess': mysqlaccess. checks access using only the `user', `db', and `host' tables. It does not check table, column, or routine privileges specified in the `tables_priv', `columns_priv', or `procs_priv' tables. Invoke *Note `mysqlaccess': mysqlaccess. like this: shell> mysqlaccess [HOST_NAME [USER_NAME [DB_NAME]]] [OPTIONS] *Note `mysqlaccess': mysqlaccess. supports the following options. *`mysqlaccess' Options* Format Option File Description -brief brief Generate reports in single-line tabular format -commit commit Copy the new access privileges from the temporary tables to the original grant tables -copy copy Reload the temporary grant tables from original ones -db=db_name db Specify the database name -debug=# debug Specify the debug level -help Display help message and exit -host=host_namehost Connect to the MySQL server on the given host -howto howto Display some examples that show how to use mysqlaccess -old_server old_server Assume that the server is an old MySQL server (prior to MySQL 3.21) -password[=password]password The password to use when connecting to the server -plan plan Display suggestions and ideas for future releases -preview preview Show the privilege differences after making changes to the temporary grant tables -relnotes relnotes Display the release notes -rhost=host_namerhost Connect to the MySQL server on the given host -rollback rollback Undo the most recent changes to the temporary grant tables. -spassword[=password]spassword The password to use when connecting to the server as the superuser -superuser=user_namesuperuser Specify the user name for connecting as the superuser -table table Generate reports in table format -user=user_name,user MySQL user name to use when connecting to server -version Display version information and exit * `--help', `-?' Display a help message and exit. * `--brief', `-b' Generate reports in single-line tabular format. * `--commit' Copy the new access privileges from the temporary tables to the original grant tables. The grant tables must be flushed for the new privileges to take effect. (For example, execute a *Note `mysqladmin reload': mysqladmin. command.) * `--copy' Reload the temporary grant tables from original ones. * `--db=DB_NAME', `-d DB_NAME' Specify the database name. * `--debug=N' Specify the debug level. N can be an integer from 0 to 3. * `--host=HOST_NAME', `-h HOST_NAME' The host name to use in the access privileges. * `--howto' Display some examples that show how to use *Note `mysqlaccess': mysqlaccess. * `--old_server' Assume that the server is an old MySQL server (before MySQL 3.21) that does not yet know how to handle full `WHERE' clauses. * `--password[=PASSWORD]', `-p[PASSWORD]' The password to use when connecting to the server. If you omit the PASSWORD value following the `--password' or `-p' option on the command line, *Note `mysqlaccess': mysqlaccess. prompts for one. Specifying a password on the command line should be considered insecure. See *Note password-security-user::. * `--plan' Display suggestions and ideas for future releases. * `--preview' Show the privilege differences after making changes to the temporary grant tables. * `--relnotes' Display the release notes. * `--rhost=HOST_NAME', `-H HOST_NAME' Connect to the MySQL server on the given host. * `--rollback' Undo the most recent changes to the temporary grant tables. * `--spassword[=PASSWORD]', `-P[PASSWORD]' The password to use when connecting to the server as the superuser. If you omit the PASSWORD value following the `--spassword' or `-p' option on the command line, *Note `mysqlaccess': mysqlaccess. prompts for one. Specifying a password on the command line should be considered insecure. See *Note password-security-user::. * `--superuser=USER_NAME', `-U USER_NAME' Specify the user name for connecting as the superuser. * `--table', `-t' Generate reports in table format. * `--user=USER_NAME', `-u USER_NAME' The user name to use in the access privileges. * `--version', `-v' Display version information and exit. If your MySQL distribution is installed in some nonstandard location, you must change the location where *Note `mysqlaccess': mysqlaccess. expects to find the *Note `mysql': mysql. client. Edit the `mysqlaccess' script at approximately line 18. Search for a line that looks like this: $MYSQL = '/usr/local/bin/mysql'; # path to mysql executable Change the path to reflect the location where *Note `mysql': mysql. actually is stored on your system. If you do not do this, a `Broken pipe' error will occur when you run *Note `mysqlaccess': mysqlaccess.  File: manual.info, Node: mysqlbinlog, Next: mysqldumpslow, Prev: mysqlaccess, Up: programs-admin-utils 4.6.7 `mysqlbinlog' -- Utility for Processing Binary Log Files -------------------------------------------------------------- * Menu: * mysqlbinlog-hexdump:: `mysqlbinlog' Hex Dump Format * mysqlbinlog-row-events:: `mysqlbinlog' Row Event Display 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 *Note `mysqlbinlog': mysqlbinlog. utility. You can also use *Note `mysqlbinlog': 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 *Note binary-log::, and *Note slave-logs::. Invoke *Note `mysqlbinlog': 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 *Note 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 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. The output from *Note `mysqlbinlog': mysqlbinlog. can be re-executed (for example, by using it as input to *Note `mysql': 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 *Note point-in-time-recovery::. Normally, you use *Note `mysqlbinlog': 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. *Note `mysqlbinlog': mysqlbinlog. supports the following options, which can be specified on the command line or in the `[mysqlbinlog]' and `[client]' groups of an option file. *Note `mysqlbinlog': mysqlbinlog. also supports the options for processing option files described at *Note option-file-options::. *`mysqlbinlog' Options* Format Option File Description Introduced -base64-output=valuebase64-outputPrint binary log entries 5.1.5 using base-64 encoding -bind-address=ip_addressbind-addressUse the specified network 5.1.22-ndb-6.3.4 interface to connect to the MySQL Server -character-sets-dir=pathcharacter-sets-dirThe directory where character sets are installed -database=db_namedatabase List entries for just this database -debug[=debug_options]debug Write a debugging log -debug-checkdebug-check Print debugging information 5.1.21 when the program exits -debug-info debug-info Print debugging information, 5.1.21 memory and CPU statistics when the program exits -disable-log-bindisable-log-binDisable binary logging -force-if-openforce-if-openRead binary log files even 5.1.15 if open or not closed properly -force-read 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 hexdump Display a hex dump of the 5.1.2 log in comments -host=host_namehost Connect to the MySQL server on the given host -local-load=pathlocal-load Prepare local temporary files for LOAD DATA INFILE in the specified directory -offset=# offset Skip the first N entries in the log -password[=password]password The password to use when connecting to the server -port=port_numport The TCP/IP port number to use for the connection -position=# position Deprecated. Use -start-position -protocol=typeprotocol The connection protocol to use -read-from-remote-serverread-from-remote-serverRead binary log from MySQL server rather than local log file -result-file=nameresult-file Direct output to the given file -server-id=idserver-id Extract only those events 5.1.4 created by the server having the given server ID -server-id-bits=#server-id-bitsTell mysqlbinlog how to 5.1.47-ndb-7.1.6 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=charset_nameset-charset Add a SET NAMES charset_name 5.1.12 statement to the output -short-form short-form Display only the statements contained in the log -socket=pathsocket For connections to localhost -start-datetime=datetimestart-datetimeRead binary log from first event with timestamp equal to or later than datetime argument -start-position=#start-positionRead binary log from first event with position equal to or greater than argument -stop-datetime=datetimestop-datetimeStop reading binary log at first event with timestamp equal to or greater than datetime argument -stop-position=#stop-positionStop reading binary log at first event with position equal to or greater than argument -to-last-logto-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=user_name,user MySQL user name to use when connecting to server -verbose Reconstruct row events as 5.1.28 SQL statements -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 *Note `BINLOG': binlog. statements. The option has these permissible values (not case sensitive): * `AUTO' ("automatic") or `UNSPEC' ("unspecified") displays *Note `BINLOG': 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 *Note `BINLOG': binlog. display is the only safe behavior if you intend to use the output of *Note `mysqlbinlog': 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. * `ALWAYS' displays *Note `BINLOG': binlog. statements whenever possible. If the `--base64-output' option is given without a value, the effect is the same as `--base64-output=ALWAYS'. * `NEVER' causes *Note `BINLOG': binlog. statements not to be displayed. *Note `mysqlbinlog': mysqlbinlog. exits with an error if a row event is found that must be displayed using *Note `BINLOG': binlog. * `DECODE-ROWS' specifies to *Note `mysqlbinlog': 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 *Note `BINLOG': binlog. statements, but unlike `NEVER', it does not exit with an error if a row event is found. The `--base64-output' option was introduced in MySQL 5.1.5, to be given as `--base64-output' or `--skip-base64-output' (with the sense of `AUTO' or `NEVER'). The option values described in the preceding list may be used as of MySQL 5.1.24, with the exception of `UNSPEC' and `DECODE-ROWS', which are available as of MySQL 5.1.28. For examples that show the effect of `--base64-output' and `--verbose' on row event output, see *Note mysqlbinlog-row-events::. * `--bind-address=IP_ADDRESS' On a computer having multiple network interfaces, this option can be used to select which interface is employed when connecting to the MySQL server. This option is supported only in the version of *Note `mysqlbinlog': mysqlbinlog. that is supplied with MySQL Cluster, beginning with MySQL Cluster NDB 6.3.4. It is not available in standard MySQL 5.1 releases. * `--character-sets-dir=PATH' The directory where character sets are installed. See *Note charset-configuration::. * `--database=DB_NAME', `-d DB_NAME' This option causes *Note `mysqlbinlog': mysqlbinlog. to output entries from the binary log (local log only) that occur while DB_NAME is been selected as the default database by *Note `USE': use. The `--database' option for *Note `mysqlbinlog': mysqlbinlog. is similar to the `--binlog-do-db' option for *Note `mysqld': 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 *Note `CREATE DATABASE': create-database, *Note `ALTER DATABASE': alter-database, and *Note `DROP DATABASE': 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); *Note `mysqlbinlog --database=test': mysqlbinlog. does not output the first two *Note `INSERT': insert. statements because there is no default database. It outputs the three *Note `INSERT': insert. statements following *Note `USE test': use, but not the three *Note `INSERT': insert. statements following *Note `USE db2': use. *Note `mysqlbinlog --database=db2': mysqlbinlog. does not output the first two *Note `INSERT': insert. statements because there is no default database. It does not output the three *Note `INSERT': insert. statements following *Note `USE test': use, but does output the three *Note `INSERT': insert. statements following *Note `USE db2': use. Row-based logging *Note `mysqlbinlog': 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. *Note `mysqlbinlog --database=test': mysqlbinlog. outputs only those entries that modify `t1' in the test database, regardless of whether *Note `USE': 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 *Note `mysqlbinlog': mysqlbinlog. with the `--database' option, you must ensure that tables that are modified are in the database selected by *Note `USE': use. (In particular, no cross-database updates should be used.) This option did not work correctly for *Note `mysqlbinlog': mysqlbinlog. with row-based logging prior to MySQL 5.1.37. (Bug #42941) *Note*: Prior to MySQL Cluster NDB 7.0.28 and MySQL Cluster NDB 7.1.17, this option did not work correctly with MySQL Cluster tables unless, unless the binary log was generated using `--log-bin-use-v1-row-events=0'. (Bug #13067813) * `--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. This option was added in MySQL 5.1.21. * `--debug-info' Print debugging information and memory and CPU usage statistics when the program exits. This option was added in MySQL 5.1.21. * `--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 *Note `mysqlbinlog': mysqlbinlog. to include a `SET sql_log_bin = 0' statement in its output to disable binary logging of the remaining output. The *Note `SET': set-statement. statement is ineffective unless you have the `SUPER' privilege. * `--force-if-open', `-F' Read binary log files even if they are open or were not closed properly. This option was added in MySQL 5.1.15. * `--force-read', `-f' With this option, if *Note `mysqlbinlog': mysqlbinlog. reads a binary log event that it does not recognize, it prints a warning, ignores the event, and continues. Without this option, *Note `mysqlbinlog': mysqlbinlog. stops if it reads such an event. * `--hexdump', `-H' Display a hex dump of the log in comments, as described in *Note mysqlbinlog-hexdump::. The hex output can be helpful for replication debugging. This option was added in MySQL 5.1.2. * `--host=HOST_NAME', `-h HOST_NAME' Get the binary log from the MySQL server on the given host. * `--local-load=PATH', `-l PATH' Prepare local temporary files for *Note `LOAD DATA INFILE': load-data. in the specified directory. *Important*: These temporary files are not automatically removed by *Note `mysqlbinlog': mysqlbinlog. or any other MySQL program. * `--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, *Note `mysqlbinlog': mysqlbinlog. prompts for one. Specifying a password on the command line should be considered insecure. See *Note password-security-user::. You can use an option file to avoid giving the password on the command line. * `--port=PORT_NUM', `-P PORT_NUM' The TCP/IP port number to use for connecting to a remote server. * `--position=N' Deprecated. Use `--start-position' instead. `--position' is removed in MySQL 5.5. * `--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 *Note connecting::. * `--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. * `--result-file=NAME', `-r NAME' Direct output to the given file. * `--server-id=ID' Display only those events created by the server having the given server ID. This option is available as of MySQL 5.1.4. * `--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 *Note `mysqld': mysqld. with server-id-bits set to less than 32 and user data stored in the most significant bit, running *Note `mysqlbinlog': mysqlbinlog. with `--server-id-bits' set to 32 enables this data to be seen. This option was added in MySQL Cluster NDB 7.0.17 and MySQL Cluster NDB 7.1.6, and is supported only by the versions of *Note `mysqlbinlog': mysqlbinlog. supplied with these and later releases of MySQL Cluster. * `--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. This option was added in MySQL 5.1.12. * `--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. * `--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. * `--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 *Note `mysqlbinlog': mysqlbinlog. The value should be in a format accepted for the *Note `DATETIME': datetime. or *Note `TIMESTAMP': datetime. 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 *Note 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 *Note 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 *Note backup-strategy-example::. * `--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 *Note backup-strategy-example::. * `--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, the output includes comments to indicate column data types and some metadata. This option was added in MySQL 5.1.28. For examples that show the effect of `--base64-output' and `--verbose' on row event output, see *Note mysqlbinlog-row-events::. * `--version', `-V' Display version information and exit. In MySQL 5.1, the version number shown for *Note `mysqlbinlog': mysqlbinlog. is always 3.3. 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 *Note `mysqlbinlog': mysqlbinlog. into the *Note `mysql': 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 *Note point-in-time-recovery::). For example: shell> mysqlbinlog binlog.000001 | mysql -u root -p Or: shell> mysqlbinlog binlog.[0-9]* | mysql -u root -p You can also redirect the output of *Note `mysqlbinlog': 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 *Note `mysql': mysql. program: shell> mysqlbinlog binlog.000001 > tmpfile shell> ... EDIT TMPFILE ... shell> mysql -u root -p < tmpfile When *Note `mysqlbinlog': 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 *Note `CREATE TEMPORARY TABLE': create-table. statement and the second log contains a statement that uses the temporary table. When the first *Note `mysql': mysql. process terminates, the server drops the temporary table. When the second *Note `mysql': mysql. process attempts to use the table, the server reports `unknown table.' To avoid problems like this, use a _single_ *Note `mysql': 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" *Note `mysqlbinlog': mysqlbinlog. can produce output that reproduces a *Note `LOAD DATA INFILE': load-data. operation without the original data file. *Note `mysqlbinlog': mysqlbinlog. copies the data to a temporary file and writes a *Note `LOAD DATA LOCAL INFILE': load-data. 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 *Note `mysqlbinlog': mysqlbinlog. converts *Note `LOAD DATA INFILE': load-data. statements to *Note `LOAD DATA LOCAL INFILE': load-data. 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 *Note load-data-local::. *Warning*: The temporary files created for *Note `LOAD DATA LOCAL': load-data. 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-#-#.  File: manual.info, Node: mysqlbinlog-hexdump, Next: mysqlbinlog-row-events, Prev: mysqlbinlog, Up: mysqlbinlog 4.6.7.1 `mysqlbinlog' Hex Dump Format ..................................... The `--hexdump' option causes *Note `mysqlbinlog': 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. This table lists event type codes found in *Note `mysqlbinlog': mysqlbinlog. `--hexdump' output. The table also lists the corresponding name and meaning for each event code type. 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 *Note `LOAD DATA INFILE': load-data. in MySQL 3.23. `07' `SLAVE_EVENT' Reserved for future use. `08' `CREATE_FILE_EVENT' Used for *Note `LOAD DATA INFILE': load-data. 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 *Note `LOAD DATA INFILE': load-data. statement. The data is stored in the temporary file on the slave. `0a' `EXEC_LOAD_EVENT' Used for *Note `LOAD DATA INFILE': load-data. 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 *Note `LOAD DATA INFILE': load-data. statement. The temporary file should be deleted on the slave. `0c' `NEW_LOAD_EVENT' Used for *Note `LOAD DATA INFILE': load-data. 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 *Note `LOAD DATA INFILE': load-data. statements in MySQL 5 and later. `12' `EXECUTE_LOAD_QUERY_EVENT'Used for *Note `LOAD DATA INFILE': load-data. 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. Currently, the following flags are used. The others are reserved for future use. This table lists flag values found in *Note `mysqlbinlog': mysqlbinlog. `--hexdump' output. The table also provides corresponding names and meanings for each flag value. 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.  File: manual.info, Node: mysqlbinlog-row-events, Prev: mysqlbinlog-hexdump, Up: mysqlbinlog 4.6.7.2 `mysqlbinlog' Row Event Display ....................................... The following examples illustrate how *Note `mysqlbinlog': 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. These options are available as of MySQL 5.1.28. 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, *Note `mysqlbinlog': mysqlbinlog. displays row events encoded as base-64 strings using *Note `BINLOG': 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 *Note `mysqlbinlog': 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 *Note `mysqlbinlog': mysqlbinlog. to suppress the *Note `BINLOG': 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 *Note `BINLOG': binlog. statements if you intend to re-execute *Note `mysqlbinlog': mysqlbinlog. output. The SQL statements produced by `--verbose' for row events are much more readable than the corresponding *Note `BINLOG': 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 (*Note `BINARY': binary-varbinary. and *Note `CHAR': char, *Note `VARBINARY': binary-varbinary. and *Note `VARCHAR': char, *Note `BLOB': blob. and *Note `TEXT': blob.). The output uses a data type of `STRING' for fixed-length strings and `VARSTRING' for variable-length strings. * For multi-byte 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', *Note `UPDATE': 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 *Note `mysqlbinlog': 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 *Note `BINLOG': binlog. statement in the initial part of the output. If the binary log is known not to contain any events requiring a *Note `BINLOG': binlog. statement (that is, no row events), the `--base64-output=NEVER' option can be used to prevent this header from being written.  File: manual.info, Node: mysqldumpslow, Next: mysqlhotcopy, Prev: mysqlbinlog, Up: programs-admin-utils 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 *Note slow-query-log::). *Note `mysqldumpslow': mysqldumpslow. parses MySQL slow query log files and prints a summary of their contents. Normally, *Note `mysqldumpslow': 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 *Note `mysqldumpslow': mysqldumpslow. like this: shell> mysqldumpslow [OPTIONS] [LOG_FILE ...] *Note `mysqldumpslow': mysqldumpslow. supports the following options. *`mysqldumpslow' Options* Format Option File Description -a Do not abstract all numbers to N and strings to S -n num Abstract numbers with at least the specified digits -debug debug Write debugging information -g pattern Only consider statements that match the pattern -help Display help message and exit -h name Host name of the server in the log file name -i name Name of the server instance -l Do not subtract lock time from total time -r Reverse the sort order -s value How to sort output -t num Display only first num queries -verbose 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 *Note `mysql.server': 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, *Note `mysqldumpslow': 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  File: manual.info, Node: mysqlhotcopy, Next: instance-manager, Prev: mysqldumpslow, Up: programs-admin-utils 4.6.9 `mysqlhotcopy' -- A Database Backup Program ------------------------------------------------- *Note `mysqlhotcopy': mysqlhotcopy. is a Perl script that was originally written and contributed by Tim Bunce. It uses *Note `FLUSH TABLES': flush, *Note `LOCK TABLES': lock-tables, and `cp' or `scp' to make a database backup. It is a fast way to make a backup of the database or single tables, but it can be run only on the same machine where the database directories are located. *Note `mysqlhotcopy': mysqlhotcopy. works only for backing up `MyISAM' and `ARCHIVE' tables. It runs on Unix and NetWare. To use *Note `mysqlhotcopy': mysqlhotcopy, you must have read access to the files for the tables that you are backing up, the `SELECT' privilege for those tables, the `RELOAD' privilege (to be able to execute *Note `FLUSH TABLES': flush.), and the `LOCK TABLES' privilege (to be able to lock the tables). shell> mysqlhotcopy DB_NAME [/PATH/TO/NEW_DIRECTORY] shell> mysqlhotcopy DB_NAME_1 ... DB_NAME_N /PATH/TO/NEW_DIRECTORY Back up tables in the given database that match a regular expression: shell> mysqlhotcopy DB_NAME./REGEX/ The regular expression for the table name can be negated by prefixing it with a tilde (``~''): shell> mysqlhotcopy DB_NAME./~REGEX/ *Note `mysqlhotcopy': mysqlhotcopy. supports the following options, which can be specified on the command line or in the `[mysqlhotcopy]' and `[client]' groups of an option file. For information about option files, see *Note option-files::. *`mysqlhotcopy' Options* Format Option File Description -addtodest addtodest Do not rename target directory (if it exists); merely add files to it -allowold allowold Do not abort if a target exists; rename it by adding an _old suffix -checkpoint=db_name.tbl_namecheckpoint Insert checkpoint entries -chroot=pathchroot Base directory of the chroot jail in which mysqld operates -debug debug Write a debugging log -dryrun dryrun Report actions without performing them -flushlog flushlog Flush logs after all tables are locked -help Display help message and exit -host=host_namehost Connect to the MySQL server on the given host -keepold keepold Do not delete previous (renamed) target when done -method method The method for copying files -noindices noindices Do not include full index files in the backup -password[=password]password The password to use when connecting to the server -port=port_numport The TCP/IP port number to use for the connection -quiet quiet Be silent except for errors -regexp regexp Copy all databases with names that match the given regular expression -resetmasterresetmaster Reset the binary log after locking all the tables -resetslave resetslave Reset the master.info file after locking all the tables -socket=pathsocket For connections to localhost -tmpdir=pathtmpdir The temporary directory -user=user_name,user MySQL user name to use when connecting to server * `--help', `-?' Display a help message and exit. * `--addtodest' Do not rename target directory (if it exists); merely add files to it. * `--allowold' Do not abort if a target exists; rename it by adding an `_old' suffix. * `--checkpoint=DB_NAME.TBL_NAME' Insert checkpoint entries into the specified database DB_NAME and table TBL_NAME. * `--chroot=PATH' Base directory of the `chroot' jail in which *Note `mysqld': mysqld. operates. The PATH value should match that of the `--chroot' option given to *Note `mysqld': mysqld. * `--debug' Enable debug output. * `--dryrun', `-n' Report actions without performing them. * `--flushlog' Flush logs after all tables are locked. * `--host=HOST_NAME', `-h HOST_NAME' The host name of the local host to use for making a TCP/IP connection to the local server. By default, the connection is made to `localhost' using a Unix socket file. * `--keepold' Do not delete previous (renamed) target when done. * `--method=COMMAND' The method for copying files (`cp' or `scp'). The default is `cp'. * `--noindices' Do not include full index files for *Note `MyISAM': myisam-storage-engine. tables in the backup. This makes the backup smaller and faster. The indexes for reloaded tables can be reconstructed later with *Note `myisamchk -rq': myisamchk. * `--password=PASSWORD', `-pPASSWORD' The password to use when connecting to the server. The password value is not optional for this option, unlike for other MySQL programs. Specifying a password on the command line should be considered insecure. See *Note password-security-user::. You can use an option file to avoid giving the password on the command line. * `--port=PORT_NUM', `-P PORT_NUM' The TCP/IP port number to use when connecting to the local server. * `--quiet', `-q' Be silent except for errors. * `--record_log_pos=DB_NAME.TBL_NAME' Record master and slave status in the specified database DB_NAME and table TBL_NAME. * `--regexp=EXPR' Copy all databases with names that match the given regular expression. * `--resetmaster' Reset the binary log after locking all the tables. * `--resetslave' Reset the `master.info' file after locking all the tables. * `--socket=PATH', `-S PATH' The Unix socket file to use for connections to `localhost'. * `--suffix=STR' The suffix to use for names of copied databases. * `--tmpdir=PATH' The temporary directory. The default is `/tmp'. * `--user=USER_NAME', `-u USER_NAME' The MySQL user name to use when connecting to the server. Use `perldoc' for additional *Note `mysqlhotcopy': mysqlhotcopy. documentation, including information about the structure of the tables needed for the `--checkpoint' and `--record_log_pos' options: shell> perldoc mysqlhotcopy  File: manual.info, Node: instance-manager, Next: mysql-convert-table-format, Prev: mysqlhotcopy, Up: programs-admin-utils 4.6.10 `mysqlmanager' -- The MySQL Instance Manager --------------------------------------------------- * Menu: * instance-manager-command-options:: MySQL Instance Manager Command Options * instance-manager-configuration-files:: MySQL Instance Manager Configuration Files * instance-manager-startup-process:: Starting the MySQL Server with MySQL Instance Manager * instance-manager-security-passwords:: Instance Manager User and Password Management * instance-manager-security-monitoring:: MySQL Server Instance Status Monitoring * instance-manager-security:: Connecting to MySQL Instance Manager * instance-manager-commands:: MySQL Instance Manager Commands *Important*: MySQL Instance Manager has been deprecated and is removed in MySQL 5.5. `mysqlmanager' is the MySQL Instance Manager (IM). This program monitors and manages MySQL Database Server instances. MySQL Instance Manager is available for Unix-like operating systems, as well as Windows. It runs as a daemon that listens on a TCP/IP port. On Unix, it also listens on a Unix socket file. MySQL Instance Manager can be used in place of the *Note `mysqld_safe': mysqld-safe. script to start and stop one or more instances of MySQL Server. Because Instance Manager can manage multiple server instances, it can also be used in place of the *Note `mysqld_multi': mysqld-multi. script. Instance Manager offers these capabilities: * Instance Manager can start and stop instances, and report on the status of instances. * Server instances can be treated as guarded or unguarded: * When Instance Manager starts, it starts each guarded instance. If the instance crashes, Instance Manager detects this and restarts it. When Instance Manager stops, it stops the instance. * A nonguarded instance is not started when Instance Manager starts or monitored by it. If the instance crashes after being started, Instance Manager does not restart it. When Instance Manager exits, it does not stop the instance if it is running. Instances are guarded by default. An instance can be designated as nonguarded by including the `nonguarded' option in the configuration file. * Instance Manager provides an interactive interface for configuring instances, so that the need to edit the configuration file manually is reduced or eliminated. * Instance Manager provides remote instance management. That is, it runs on the host where you want to control MySQL Server instances, but you can connect to it from a remote host to perform instance-management operations. The following sections describe MySQL Instance Manager operation in more detail.  File: manual.info, Node: instance-manager-command-options, Next: instance-manager-configuration-files, Prev: instance-manager, Up: instance-manager 4.6.10.1 MySQL Instance Manager Command Options ............................................... *Important*: MySQL Instance Manager has been deprecated and is removed in MySQL 5.5. The MySQL Instance Manager supports a number of command options. For a brief listing, invoke `mysqlmanager' with the `--help' option. Options may be given on the command line or in the Instance Manager configuration file. On Windows, the standard configuration file is `my.ini' in the directory where Instance Manager is installed. On Unix, the standard file is `/etc/my.cnf'. To specify a different configuration file, start Instance Manager with the `--defaults-file' option. `mysqlmanager' supports the following options. The options for managing entries in the password file are described further in *Note instance-manager-security-passwords::. * `--help', `-?' Display a help message and exit. * `--add-user' Add a new user (specified with the `--username' option) to the password file. This option was added in MySQL 5.1.12. * `--angel-pid-file=FILE_NAME' The file in which the angel process records its process ID when `mysqlmanager' runs in daemon mode (that is, when the `--run-as-service' option is given). The default file name is `mysqlmanager.angel.pid'. If the `--angel-pid-file' option is not given, the default angel PID file has the same name as the PID file except that any PID file extension is replaced with an extension of `.angel.pid'. (For example, `mysqlmanager.pid' becomes `mysqlmanager.angel.pid'.) This option was added in MySQL 5.1.11. * `--bind-address=IP' The IP address to bind to. * `--check-password-file' Check the validity and consistency of the password file. This option was added in MySQL 5.1.12. * `--clean-password-file' Drop all users from the password file. This option was added in MySQL 5.1.12. * `--debug=DEBUG_OPTIONS', `-# DEBUG_OPTIONS' Write a debugging log. A typical DEBUG_OPTIONS string is `'d:t:o,FILE_NAME''. This option was added in MySQL 5.1.10. * `--default-mysqld-path=PATH' The path name of the MySQL Server binary. This path name is used for all server instance sections in the configuration file for which no `mysqld-path' option is present. The default value of this option is the compiled-in path name, which depends on how the MySQL distribution was configured. Example: `--default-mysqld-path=/usr/sbin/mysqld' * `--defaults-file=FILE_NAME' Read Instance Manager and MySQL Server settings from the given file. All configuration changes made by the Instance Manager will be written to this file. This must be the first option on the command line if it is used, and the file must exist. If this option is not given, Instance Manager uses its standard configuration file. On Windows, the standard file is `my.ini' in the directory where Instance Manager is installed. On Unix, the standard file is `/etc/my.cnf'. * `--drop-user' Drop a user (specified with the `--username' option) from the password file. This option was added in MySQL 5.1.12. * `--edit-user' Change an entry for an existing user (specified with the `--username' option) in the password file. This option was added in MySQL 5.1.12. * `--install' On Windows, install Instance Manager as a Windows service. The service name is `MySQL Manager'. * `--list-users' List the users in the password file. This option was added in MySQL 5.1.12. * `--log=FILE_NAME' The path to the Instance Manager log file. This option has no effect unless the `--run-as-service' option is also given. If the file name specified for the option is a relative name, the log file is created under the directory from which Instance Manager is started. To ensure that the file is created in a specific directory, specify it as a full path name. If `--run-as-service' is given without `--log', the log file is `mysqlmanager.log' in the data directory. If `--run-as-service' is not given, log messages go to the standard output. To capture log output, you can redirect Instance Manager output to a file: mysqlmanager > im.log * `--monitoring-interval=SECONDS' The interval in seconds for monitoring server instances. The default value is 20 seconds. Instance Manager tries to connect to each monitored (guarded) instance using the nonexisting `MySQL_Instance_Manager' user account to check whether it is available/not hanging. If the result of the connection attempt indicates that the instance is unavailable, Instance Manager performs several attempts to restart the instance. Normally, the `MySQL_Instance_Manager' account does not exist, so the connection attempts by Instance Manager cause the monitored instance to produce messages in its general query log similar to the following: Access denied for user 'MySQL_Instance_M'@'localhost' » (using password: YES) The `nonguarded' option in the appropriate server instance section disables monitoring for a particular instance. If the instance dies after being started, Instance Manager will not restart it. Instance Manager tries to connect to a nonguarded instance only when you request the instance's status (for example, with the `SHOW INSTANCES' status. See *Note instance-manager-security-monitoring::, for more information. * `--mysqld-safe-compatible' Run in a *Note `mysqld_safe': mysqld-safe.-compatible manner. For details, see *Note instance-manager-startup-process::. This option was added in MySQL 5.1.12. * `--password=PASSWORD', `-p PASSWORD' Specify the password for an entry to be added to or modified in the password file. Unlike the `--password'/`-P' option for most MySQL programs, the password value is required, not optional. See also *Note instance-manager-security-passwords::. This option was added in MySQL 5.1.12. * `--password-file=FILE_NAME' The name of the file where the Instance Manager looks for users and passwords. On Windows, the default is `mysqlmanager.passwd' in the directory where Instance Manager is installed. On Unix, the default file is `/etc/mysqlmanager.passwd'. See also *Note instance-manager-security-passwords::. * `--pid-file=FILE_NAME' The process ID file to use. On Windows, the default file is `mysqlmanager.pid' in the directory where Instance Manager is installed. On Unix, the default is `mysqlmanager.pid' in the data directory. * `--port=PORT_NUM' The port number to use when listening for TCP/IP connections from clients. The default port number (assigned by IANA) is 2273. * `--print-defaults' Print the current defaults and exit. This must be the first option on the command line if it is used. * `--print-password-line' Prepare an entry for the password file, print it to the standard output, and exit. You can redirect the output from Instance Manager to a file to save the entry in the file. Prior to MySQL 5.1.12, this option was named `--passwd'. * `--remove' On Windows, removes Instance Manager as a Windows service. This assumes that Instance Manager has been run with `--install' previously. * `--run-as-service' On Unix, daemonize and start an angel process. The angel process monitors Instance Manager and restarts it if it crashes. (The angel process itself is simple and unlikely to crash.) * `--socket=PATH' On Unix, the socket file to use for incoming connections. The default file is named `/tmp/mysqlmanager.sock'. This option has no meaning on Windows. * `--standalone' This option is used on Windows to run Instance Manager in standalone mode. You should specify it when you start Instance Manager from the command line. * `--user=USER_NAME' On Unix, the user name of the system account to use for starting and running `mysqlmanager'. This option generates a warning and has no effect unless you start `mysqlmanager' as `root' (so that it can change its effective user ID), or as the named user. It is recommended that you configure `mysqlmanager' to run using the same account used to run the *Note `mysqld': mysqld. server. (`User' in this context refers to a system login account, not a MySQL user listed in the grant tables.) * `--username=USER_NAME', `-u USER_NAME' Specify the user name for an entry to be added to or modified in the password file. This option was added in MySQL 5.1.12. * `--version', `-V' Display version information and exit. * `--wait-timeout=N' The number of seconds to wait for activity on an incoming connection before closing it. The default is 28800 seconds (8 hours). This option was added in MySQL 5.1.7. Before that, the timeout is 30 seconds and cannot be changed.  File: manual.info, Node: instance-manager-configuration-files, Next: instance-manager-startup-process, Prev: instance-manager-command-options, Up: instance-manager 4.6.10.2 MySQL Instance Manager Configuration Files ................................................... *Important*: MySQL Instance Manager has been deprecated and is removed in MySQL 5.5. Instance Manager uses its standard configuration file unless it is started with a `--defaults-file' option that specifies a different file. On Windows, the standard file is `my.ini' in the directory where Instance Manager is installed. On Unix, the standard file is `/etc/my.cnf'. Instance Manager reads options for itself from the `[manager]' section of the configuration file, and options for server instances from `[mysqld]' or `[mysqldN]' sections. The `[manager]' section contains any of the options listed in *Note instance-manager-command-options::, except for those specified as having to be given as the first option on the command line. Here is a sample `[manager]' section: # MySQL Instance Manager options section [manager] default-mysqld-path = /usr/local/mysql/libexec/mysqld socket=/tmp/manager.sock pid-file=/tmp/manager.pid password-file = /home/cps/.mysqlmanager.passwd monitoring-interval = 2 port = 1999 bind-address = 192.168.1.5 Each `[mysqld]' or `[mysqldN]' instance section specifies options given by Instance Manager to a server instance at startup. These are mainly common MySQL Server options (see *Note server-options::). In addition, a `[mysqldN]' section can contain the options in the following list, which are specific to Instance Manager. These options are interpreted by Instance Manager itself; it does not pass them to the server when it attempts to start that server. *Warning*: The Instance Manager-specific options must not be used in a `[mysqld]' section. If a server is started without using Instance Manager, it will not recognize these options and will fail to start properly. * `mysqld-path = PATH' The path name of the *Note `mysqld': mysqld. server binary to use for the server instance. * `nonguarded' This option disables Instance Manager monitoring functionality for the server instance. By default, an instance is guarded: At Instance Manager start time, it starts the instance. It also monitors the instance status and attempts to restart it if it fails. At Instance Manager exit time, it stops the instance. None of these things happen for nonguarded instances. * `shutdown-delay = SECONDS' The number of seconds Instance Manager should wait for the server instance to shut down. The default value is 35 seconds. After the delay expires, Instance Manager assumes that the instance is hanging and attempts to terminate it. If you use `InnoDB' with large tables, you should increase this value. Here are some sample instance sections: [mysqld1] mysqld-path=/usr/local/mysql/libexec/mysqld socket=/tmp/mysql.sock port=3307 server_id=1 skip-stack-trace core-file log-bin log-error log=mylog log-slow-queries [mysqld2] nonguarded port=3308 server_id=2 mysqld-path= /home/cps/mysql/trees/mysql-5.1/sql/mysqld socket = /tmp/mysql.sock5 pid-file = /tmp/hostname.pid5 datadir= /home/cps/mysql_data/data_dir1 language=/home/cps/mysql/trees/mysql-5.1/sql/share/english log-bin log=/tmp/fordel.log  File: manual.info, Node: instance-manager-startup-process, Next: instance-manager-security-passwords, Prev: instance-manager-configuration-files, Up: instance-manager 4.6.10.3 Starting the MySQL Server with MySQL Instance Manager .............................................................. *Important*: MySQL Instance Manager has been deprecated and is removed in MySQL 5.5. This section discusses how Instance Manager starts server instances when it starts. However, before you start Instance Manager, you should set up a password file for it. Otherwise, you will not be able to connect to Instance Manager to control it after it starts. For details about creating Instance Manager accounts, see *Note instance-manager-security-passwords::. On Unix, the *Note `mysqld': mysqld. MySQL database server normally is started with the *Note `mysql.server': mysql-server. script, which usually resides in the `/etc/init.d/' folder. That script invokes the *Note `mysqld_safe': mysqld-safe. script by default. However, you can use Instance Manager instead if you modify the `/etc/my.cnf' configuration file by adding `use-manager' to the `[mysql.server]' section: [mysql.server] use-manager Before MySQL 5.1.12, Instance Manager always tries to start at least one server instance: When it starts, it reads its configuration file if it exists to find server instance sections and prepare a list of instances. Instance sections have names of the form `[mysqld]' or `[mysqldN]', where N is an unsigned integer (for example, `[mysqld1]', `[mysqld2]', and so forth). After preparing the list of instances, Instance Manager starts the guarded instances in the list. If there are no instances, Instance Manager creates an instance named `mysqld' and attempts to start it with default (compiled-in) configuration values. This means that the Instance Manager cannot find the *Note `mysqld': mysqld. program if it is not installed in the default location. (*Note installation-layouts::, describes default locations for components of MySQL distributions.) If you have installed the MySQL server in a nonstandard location, you should create the Instance Manager configuration file. The startup behavior just described is similar to that of *Note `mysqld_safe': mysqld-safe, which always attempts to start a server. However, it lacks the flexibility required for some operations because it is not possible to run Instance Manager in such a way that it refrains from starting any server instances. For example, you cannot invoke Instance Manager for the purpose of configuring an instance without also starting it (a task that a MySQL installer application might want to perform). Consequently, MySQL 5.1.12 introduces the following changes: * A new option, `--mysqld-safe-compatible', may be used to cause Instance Manager to run with startup behavior similar to that used before MySQL 5.1.12: If Instance Manager finds a `[mysqld]' instance section in the configuration file, it will start it. If Instance Manager finds no `[mysqld]' section, it creates one using default configuration values, writes a `[mysqld]' section to the configuration file if it is accessible, and starts the `mysqld' instance. Instance Manager also starts any other guarded instances listed in the configuration file. * Without `--mysqld-safe-compatible', Instance Manager reads its configuration file if it exists and starts instances for any guarded instance sections that it finds. If there are none, it starts no instances. Instance Manager also stops all guarded server instances when it shuts down. The permissible options for `[mysqldN]' server instance sections are described in *Note instance-manager-configuration-files::. In these sections, you can use a special `mysqld-path=PATH-TO-MYSQLD-BINARY' option that is recognized only by Instance Manager. Use this option to let Instance Manager know where the *Note `mysqld': mysqld. binary resides. If there are multiple instances, it may also be necessary to set other options such as `datadir' and `port', to ensure that each instance has a different data directory and TCP/IP port number. *Note multiple-servers::, discusses the configuration values that must differ for each instance when you run multiple instance on the same machine. *Warning*: The `[mysqld]' instance section, if it exists, must not contain any Instance Manager-specific options. The typical Unix startup/shutdown cycle for a MySQL server with the MySQL Instance Manager enabled is as follows: 1. The `/etc/init.d/mysql' script starts MySQL Instance Manager. 2. Instance Manager starts the guarded server instances and monitors them. 3. If a server instance fails, Instance Manager restarts it. 4. If Instance Manager is shut down (for example, with the `/etc/init.d/mysql stop' command), it shuts down all server instances.  File: manual.info, Node: instance-manager-security-passwords, Next: instance-manager-security-monitoring, Prev: instance-manager-startup-process, Up: instance-manager 4.6.10.4 Instance Manager User and Password Management ...................................................... *Important*: MySQL Instance Manager has been deprecated and is removed in MySQL 5.5. The Instance Manager stores its user information in a password file. On Windows, the default is `mysqlmanager.passwd' in the directory where Instance Manager is installed. On Unix, the default file is `/etc/mysqlmanager.passwd'. To specify a different location for the password file, use the `--password-file' option. If the password file does not exist or contains no password entries, you cannot connect to the Instance Manager. *Note*: Any Instance Manager process that is running to monitor server instances does not notice changes to the password file. You must stop it and restart it after making password entry changes. Entries in the password file have the following format, where the two fields are the account user name and encrypted password, separated by a colon: petr:*35110DC9B4D8140F5DE667E28C72DD2597B5C848 Instance Manager password encryption is the same as that used by MySQL Server. It is a one-way operation; no means are provided for decrypting encrypted passwords. Instance Manager accounts differ somewhat from MySQL Server accounts: * MySQL Server accounts are associated with a host name, user name, and password (see *Note user-names::). * Instance Manager accounts are associated with a user name and password only. This means that a client can connect to Instance Manager with a given user name from any host. To limit connections so that clients can connect only from the local host, start Instance Manager with the `--bind-address=127.0.0.1' option so that it listens only to the local network interface. Remote clients will not be able to connect. Local clients can connect like this: shell> mysql -h 127.0.0.1 -P 2273 Before MySQL 5.1.12, the only option for creating password file entries is `--passwd', which causes Instance Manager to prompt for user name and password values and display the resulting entry. You can save the output in the `/etc/mysqlmanager.passwd' password file to store it. Here is an example: shell> mysqlmanager --passwd >> /etc/mysqlmanager.passwd Creating record for new user. Enter user name: mike Enter password: mikepass Re-type password: mikepass At the prompts, enter the user name and password for the new Instance Manager user. You must enter the password twice. It does not echo to the screen, so double entry guards against entering a different password than you intend (if the two passwords do not match, no entry is generated). The preceding command causes the following line to be added to `/etc/mysqlmanager.passwd': mike:*BBF1F551DD9DD96A01E66EC7DDC073911BAD17BA Use of the `--password' option fails if `mysqlmanager' is invoked directly from an IBM 5250 terminal. To work around this, use a command like the following from the command line to generate the password entry: shell> mysql -B --skip-column-name \ -e 'SELECT CONCAT("USER_NAME",":",PASSWORD("PASS_VAL"));' The output from the command can be used an entry in the `/etc/mysqlmanager.passwd' file. Beginning with MySQL 5.1.12, the `--passwd' option is renamed to `--print-password-line' and there are several other options for managing user accounts from the command line. For example, the `--username' and `--password' options are available on the command line for specifying the user name and password for an account entry. You can use them to generate an entry with no prompting like this (type the command on a single line): shell> mysqlmanager --print-password-line --username=mike --password=mikepass >> /etc/mysqlmanager.passwd If you omit the `--username' or `--password' option, Instance Manager prompts for the required value. `--print-password-line' causes Instance Manager to send the resulting account entry to its output, which you can append to the password file. The following list describes other account-management options that cause Instance Manager to operate directly on the password file. (These options make Instance Manager scriptable for account-management purposes.) For operations on the password file to succeed, the file must exist and it must be accessible by Instance Manager. (The exception is `--clean-password-file', which creates the file if it does not exist. Alternatively, if there is no password file, manually create it as an empty file and ensure that its ownership and access modes permit it to be read and written by Instance Manager.) The default password file is used unless you specify a `--password-file' option. To ensure consistent treatment of the password file, it should be owned by the system account that you use for running Instance Manager to manage server instances, and you should invoke it from that account when you use it to manage accounts in the password file. * Create a new user: mysqlmanager --add-user --username=USER_NAME [--password=PASSWORD] This command adds a new entry with the given user name and password to the password file. The `--username' (or `-u') option is required. `mysqlmanager' prompts for the password if it is not given on the command line with the `--password' (or `-p') option. The command fails if the user already exists. * Drop an existing user: mysqlmanager --drop-user --username=USER_NAME This command removes the entry with the given user name from the password file. The user name is required. The command fails if the user does not exist. * Change the password for an existing user: mysqlmanager --edit-user --username=USER_NAME [--password=PASSWORD] This command changes the given user's password in the password file. The user name is required. `mysqlmanager' prompts for the password it is not given on the command line. The command fails if the user does not exist. * List existing users: mysqlmanager --list-users This command lists the user names of the accounts in the password file. * Check the password file: mysqlmanager --check-password-file This command performs a consistency and validity check of the password file. The command fails if there is something wrong with the file. * Empty the password file: mysqlmanager --clean-password-file This command empties the password file, which has the effect of dropping all users listed in it. The option creates the password file if it does not exist, so it can be used to initialize a new password file to be used for other account-management operations. Take care not to use this option to reinitialize a file containing accounts that you do not want to drop.  File: manual.info, Node: instance-manager-security-monitoring, Next: instance-manager-security, Prev: instance-manager-security-passwords, Up: instance-manager 4.6.10.5 MySQL Server Instance Status Monitoring ................................................ *Important*: MySQL Instance Manager has been deprecated and is removed in MySQL 5.5. To monitor the status of each guarded server instance, the MySQL Instance Manager attempts to connect to the instance at regular intervals using the `MySQL_Instance_Manager@localhost' user account with a password of `check_connection'. You are _not_ required to create this account for MySQL Server; in fact, it is expected that it will not exist. Instance Manager can tell that a server is operational if the server accepts the connection attempt but refuses access for the account by returning a login error. However, these failed connection attempts are logged by the server to its general query log (see *Note query-log::). Instance Manager also attempts a connection to nonguarded server instances when you use the `SHOW INSTANCES' or `SHOW INSTANCE STATUS' command. This is the only status monitoring done for nonguarded instances. Instance Manager knows if a server instance fails at startup because it receives a status from the attempt. For an instance that starts but later crashes, Instance Manager receives a signal because it is the parent process of the instance. Beginning with MySQL 5.1.12, Instance Manager tracks instance states so that it can determine which commands are permitted for each instance. For example, commands that modify an instance's configuration are permitted only while the instance is offline. Each instance is in one of the states described in the following table. Guarded instances can be in any of the states. Nonguarded instances can only be offline or online. Instance state information is displayed in the `status' column of the `SHOW INSTANCES' and `SHOW INSTANCE STATUS' commands. This table lists MySQL server instance states and describes the meaning of each state. State Meaning `offline' The instance has not been started and is not running. `starting' The instance is starting (initializing). Nonguarded instances cannot be in this state. A nonguarded instance goes directly from offline to online. `stopping' The instance is stopping. Nonguarded instances cannot be in this state. A nonguarded instance goes directly from online to offline, or stays offline if startup fails. `online' The instance has started and is running. `failed' The instance was online but it crashed and is being restarted by Instance Manager, or else the instance failed to start at all and Instance Manager is again attempting to start it. Nonguarded instances cannot be in this state. `crashed' Instance Manager failed to start the instance after several attempts. (Instance Manager will try again later.) Nonguarded instances cannot be in this state. `abandoned' Instance Manager was not able to start the instance, has given up, and will make no further attempts until instructed otherwise. To tell Instance Manager to try again, you must first use `STOP INSTANCE' to put the instance in offline state, and then use `START INSTANCE' to start the instance. If it is necessary to make configuration changes for the instance, you must do so after putting the instance offline and before starting it. (Instance Manager accepts configuration-changing commands only for offline instances.) Nonguarded instances cannot be in this state.  File: manual.info, Node: instance-manager-security, Next: instance-manager-commands, Prev: instance-manager-security-monitoring, Up: instance-manager 4.6.10.6 Connecting to MySQL Instance Manager ............................................. *Important*: MySQL Instance Manager has been deprecated and is removed in MySQL 5.5. After you set up a password file for the MySQL Instance Manager and Instance Manager is running, you can connect to it. The MySQL client/server protocol is used to communicate with the Instance Manager. For example, you can connect to it using the standard *Note `mysql': mysql. client program: shell> mysql --port=2273 --host=im.example.org --user=mysql --password Instance Manager supports the version of the MySQL client/server protocol used by the client tools and libraries distributed with MySQL 4.1 or later, so other programs that use the MySQL C API also can connect to it.  File: manual.info, Node: instance-manager-commands, Prev: instance-manager-security, Up: instance-manager 4.6.10.7 MySQL Instance Manager Commands ........................................ *Important*: MySQL Instance Manager has been deprecated and is removed in MySQL 5.5. After you connect to MySQL Instance Manager, you can issue commands. The following general principles apply to Instance Manager command execution: * Commands that take an instance name fail if the name is not a valid instance name. * Commands that take an instance name (other than `CREATE INSTANCE') fail if the instance does not exist. * As of MySQL 5.1.12, commands for an instance require that the instance be in an appropriate state. You cannot configure or start an instance that is not offline. You cannot start an instance that is online. * Instance Manager maintains information about instance configuration in an internal (in-memory) cache. Initially, this information comes from the configuration file if it exists, but some commands change the configuration of an instance. Commands that modify the configuration file fail if the file does not exist or is not accessible to Instance Manager. As of MySQL 5.1.12, configuration-changing commands modify both the in-memory cache and the server instance section recorded in the configuration file to maintain consistency between them. For this to occur, the instance must be offline and the configuration file must be accessible and not malformed. If the configuration file cannot be updated, the command fails and the cache remains unchanged. * On Windows, the standard file is `my.ini' in the directory where Instance Manager is installed. On Unix, the standard configuration file is `/etc/my.cnf'. To specify a different configuration file, start Instance Manager with the `--defaults-file' option. * If a `[mysqld]' instance section exists in the configuration file, it must not contain any Instance Manager-specific options (see *Note instance-manager-configuration-files::). Therefore, you must not add any of these options if you change the configuration for an instance named `mysqld'. The following list describes the commands that Instance Manager accepts, with examples. * `CREATE INSTANCE INSTANCE_NAME [OPTION_NAME[=OPTION_VALUE], ...]' This command configures a new instance by creating an `[INSTANCE_NAME]' section in the configuration file. The command fails if INSTANCE_NAME is not a valid instance name or the instance already exists. The created section instance is empty if no options are given. Otherwise, the options are added to the section. Options should be given in the same format used when you write options in option files. (See *Note option-files:: for a description of the permissible syntax.) If you specify multiple options, separate them by commas. For example, to create an instance section named `[mysqld98]', you might write something like this were you to modify the configuration file directly: [mysqld98] basedir=/var/mysql98 To achieve the same effect using `CREATE INSTANCE', issue this command to Instance Manager: mysql> CREATE INSTANCE mysqld98 basedir="/var/mysql98"; Query OK, 0 rows affected (0,00 sec) `CREATE INSTANCE' creates the instance but does not start it. If the instance name is the (deprecated) name `mysqld', the option list cannot include any options that are specific to Instance Manager, such as `nonguarded' (see *Note instance-manager-configuration-files::). This command was added in MySQL 5.1.12. * `DROP INSTANCE INSTANCE_NAME' This command removes the configuration for INSTANCE_NAME from the configuration file. mysql> DROP INSTANCE mysqld98; Query OK, 0 rows affected (0,00 sec) The command fails if INSTANCE_NAME is not a valid instance name, the instance does not exist, or is not offline. This command was added in MySQL 5.1.12. * `START INSTANCE INSTANCE_NAME' This command attempts to start an offline instance. The command is asynchronous; it does not wait for the instance to start. mysql> START INSTANCE mysqld4; Query OK, 0 rows affected (0,00 sec) * `STOP INSTANCE INSTANCE_NAME' This command attempts to stop an instance. The command is synchronous; it waits for the instance to stop. mysql> STOP INSTANCE mysqld4; Query OK, 0 rows affected (0,00 sec) * `SHOW INSTANCES' Shows the names and status of all loaded instances. mysql> SHOW INSTANCES; +---------------+---------+ | instance_name | status | +---------------+---------+ | mysqld3 | offline | | mysqld4 | online | | mysqld2 | offline | +---------------+---------+ * `SHOW INSTANCE STATUS INSTANCE_NAME' Shows status and version information for an instance. mysql> SHOW INSTANCE STATUS mysqld3; +---------------+--------+---------+ | instance_name | status | version | +---------------+--------+---------+ | mysqld3 | online | unknown | +---------------+--------+---------+ * `SHOW INSTANCE OPTIONS INSTANCE_NAME' Shows the options used by an instance. mysql> SHOW INSTANCE OPTIONS mysqld3; +---------------+---------------------------------------------------+ | option_name | value | +---------------+---------------------------------------------------+ | instance_name | mysqld3 | | mysqld-path | /home/cps/mysql/trees/mysql-4.1/sql/mysqld | | port | 3309 | | socket | /tmp/mysql.sock3 | | pid-file | hostname.pid3 | | datadir | /home/cps/mysql_data/data_dir1/ | | language | /home/cps/mysql/trees/mysql-4.1/sql/share/english | +---------------+---------------------------------------------------+ * `SHOW INSTANCE_NAME LOG FILES' The command lists all log files used by the instance. The result set contains the path to the log file and the log file size. If no log file path is specified in the instance section of the configuration file (for example, `log=/var/mysql.log'), the Instance Manager tries to guess its placement. If Instance Manager is unable to guess the log file placement you should specify the log file location explicitly by using a log option in the appropriate instance section of the configuration file. mysql> SHOW mysqld LOG FILES; +-------------+------------------------------------+----------+ | Logfile | Path | Filesize | +-------------+------------------------------------+----------+ | ERROR LOG | /home/cps/var/mysql/owlet.err | 9186 | | GENERAL LOG | /home/cps/var/mysql/owlet.log | 471503 | | SLOW LOG | /home/cps/var/mysql/owlet-slow.log | 4463 | +-------------+------------------------------------+----------+ `SHOW ... LOG FILES' displays information only about log files. If a server instance uses log tables (see *Note log-destinations::), no information about those tables is shown. Log options are described in *Note server-options::. * `SHOW INSTANCE_NAME LOG {ERROR | SLOW | GENERAL} SIZE[,OFFSET_FROM_END]' This command retrieves a portion of the specified log file. Because most users are interested in the latest log messages, the SIZE parameter defines the number of bytes to retrieve from the end of the log. To retrieve data from the middle of the log file, specify the optional OFFSET_FROM_END parameter. The following example retrieves 21 bytes of data, starting 23 bytes before the end of the log file and ending 2 bytes before the end: mysql> SHOW mysqld LOG GENERAL 21, 2; +---------------------+ | Log | +---------------------+ | using password: YES | +---------------------+ * `SET INSTANCE_NAME.OPTION_NAME[=OPTION_VALUE]' This command edits the specified instance's configuration section to change or add instance options. The option is added to the section is it is not already present. Otherwise, the new setting replaces the existing one. mysql> SET mysqld2.port=3322; Query OK, 0 rows affected (0.00 sec) As of MySQL 5.1.12, you can specify multiple options (separated by commas), and `SET' can be used only for offline instances. Each option must indicate the instance name: mysql> SET mysqld2.port=3322, mysqld3.nonguarded; Query OK, 0 rows affected (0.00 sec) Before MySQL 5.1.12, only a single option can be specified. Also, changes made to the configuration file do not take effect until the MySQL server is restarted. In addition, these changes are not stored in the instance manager's local cache of instance settings until a `FLUSH INSTANCES' command is executed. * `UNSET INSTANCE_NAME.OPTION_NAME' This command removes an option from an instance's configuration section. mysql> UNSET mysqld2.port; Query OK, 0 rows affected (0.00 sec) As of MySQL 5.1.12, you can specify multiple options (separated by commas), and `UNSET' can be used only for offline instances. Each option must indicate the instance name: mysql> UNSET mysqld2.port, mysqld4.nonguarded; Query OK, 0 rows affected (0.00 sec) Before MySQL 5.1.12, only a single option can be specified. Also, changes made to the configuration file do not take effect until the MySQL server is restarted. In addition, these changes are not stored in the instance manager's local cache of instance settings until a `FLUSH INSTANCES' command is executed. * `FLUSH INSTANCES' As of MySQL 5.1.12, `FLUSH INSTANCES' cannot be used unless all instances are offline. The command causes Instance Manager to reread the configuration file, update its in-memory configuration cache, and start any guarded instances. Before MySQL 5.1.12, this command forces Instance Manager reread the configuration file and to refresh internal structures. This command should be performed after editing the configuration file. The command does not restart instances. mysql> FLUSH INSTANCES; Query OK, 0 rows affected (0.04 sec)  File: manual.info, Node: mysql-convert-table-format, Next: mysql-find-rows, Prev: instance-manager, Up: programs-admin-utils 4.6.11 `mysql_convert_table_format' -- Convert Tables to Use a Given Storage Engine ----------------------------------------------------------------------------------- *Note `mysql_convert_table_format': mysql-convert-table-format. converts the tables in a database to use a particular storage engine (`MyISAM' by default). *Note `mysql_convert_table_format': mysql-convert-table-format. is written in Perl and requires that the `DBI' and `DBD::mysql' Perl modules be installed (see *Note perl-support::). Invoke *Note `mysql_convert_table_format': mysql-convert-table-format. like this: shell> mysql_convert_table_format [OPTIONS]DB_NAME The DB_NAME argument indicates the database containing the tables to be converted. *Note `mysql_convert_table_format': mysql-convert-table-format. supports the options described in the following list. * `--help' Display a help message and exit. * `--force' Continue even if errors occur. * `--host=HOST_NAME' Connect to the MySQL server on the given host. * `--password=PASSWORD' The password to use when connecting to the server. Note that the password value is not optional for this option, unlike for other MySQL programs. Specifying a password on the command line should be considered insecure. See *Note password-security-user::. You can use an option file to avoid giving the password on the command line. * `--port=PORT_NUM' The TCP/IP port number to use for the connection. * `--socket=PATH' For connections to `localhost', the Unix socket file to use. * `--type=ENGINE_NAME' Specify the storage engine that the tables should be converted to use. The default is `MyISAM' if this option is not given. * `--user=USER_NAME' The MySQL user name to use when connecting to the server. * `--verbose' Verbose mode. Print more information about what the program does. * `--version' Display version information and exit.  File: manual.info, Node: mysql-find-rows, Next: mysql-fix-extensions, Prev: mysql-convert-table-format, Up: programs-admin-utils 4.6.12 `mysql_find_rows' -- Extract SQL Statements from Files ------------------------------------------------------------- *Note `mysql_find_rows': mysql-find-rows. reads files containing SQL statements and extracts statements that match a given regular expression or that contain `USE DB_NAME' or *Note `SET': set-statement. statements. The utility was written for use with update log files (as used prior to MySQL 5.0) and as such expects statements to be terminated with semicolon (`;') characters. It may be useful with other files that contain SQL statements as long as statements are terminated with semicolons. Invoke *Note `mysql_find_rows': mysql-find-rows. like this: shell> mysql_find_rows [OPTIONS] [FILE_NAME ...] Each FILE_NAME argument should be the name of file containing SQL statements. If no file names are given, *Note `mysql_find_rows': mysql-find-rows. reads the standard input. Examples: mysql_find_rows --regexp=problem_table --rows=20 < update.log mysql_find_rows --regexp=problem_table update-log.1 update-log.2 *Note `mysql_find_rows': mysql-find-rows. supports the following options: * `--help', `--Information' Display a help message and exit. * `--regexp=PATTERN' Display queries that match the pattern. * `--rows=N' Quit after displaying N queries. * `--skip-use-db' Do not include `USE DB_NAME' statements in the output. * `--start_row=N' Start output from this row.  File: manual.info, Node: mysql-fix-extensions, Next: mysql-setpermission, Prev: mysql-find-rows, Up: programs-admin-utils 4.6.13 `mysql_fix_extensions' -- Normalize Table File Name Extensions --------------------------------------------------------------------- *Note `mysql_fix_extensions': mysql-fix-extensions. converts the extensions for `MyISAM' (or `ISAM') table files to their canonical forms. It looks for files with extensions matching any lettercase variant of `.frm', `.myd', `.myi', `.isd', and `.ism' and renames them to have extensions of `.frm', `.MYD', `.MYI', `.ISD', and `.ISM', respectively. This can be useful after transferring the files from a system with case-insensitive file names (such as Windows) to a system with case-sensitive file names. Invoke *Note `mysql_fix_extensions': mysql-fix-extensions. like this, where DATA_DIR is the path name to the MySQL data directory. shell> mysql_fix_extensions DATA_DIR  File: manual.info, Node: mysql-setpermission, Next: mysql-waitpid, Prev: mysql-fix-extensions, Up: programs-admin-utils 4.6.14 `mysql_setpermission' -- Interactively Set Permissions in Grant Tables ----------------------------------------------------------------------------- *Note `mysql_setpermission': mysql-setpermission. is a Perl script that was originally written and contributed by Luuk de Boer. It interactively sets permissions in the MySQL grant tables. *Note `mysql_setpermission': mysql-setpermission. is written in Perl and requires that the `DBI' and `DBD::mysql' Perl modules be installed (see *Note perl-support::). Invoke *Note `mysql_setpermission': mysql-setpermission. like this: shell> mysql_setpermission [OPTIONS] OPTIONS should be either `--help' to display the help message, or options that indicate how to connect to the MySQL server. The account used when you connect determines which permissions you have when attempting to modify existing permissions in the grant tables. `mysql_setpermissions' also reads options from the `[client]' and `[perl]' groups in the `.my.cnf' file in your home directory, if the file exists. *Note `mysql_setpermission': mysql-setpermission. supports the following options: * `--help' Display a help message and exit. * `--host=HOST_NAME' Connect to the MySQL server on the given host. * `--password=PASSWORD' The password to use when connecting to the server. Note that the password value is not optional for this option, unlike for other MySQL programs. Specifying a password on the command line should be considered insecure. See *Note password-security-user::. You can use an option file to avoid giving the password on the command line. * `--port=PORT_NUM' The TCP/IP port number to use for the connection. * `--socket=PATH' For connections to `localhost', the Unix socket file to use. * `--user=USER_NAME' The MySQL user name to use when connecting to the server.  File: manual.info, Node: mysql-waitpid, Next: mysql-zap, Prev: mysql-setpermission, Up: programs-admin-utils 4.6.15 `mysql_waitpid' -- Kill Process and Wait for Its Termination ------------------------------------------------------------------- *Note `mysql_waitpid': mysql-waitpid. signals a process to terminate and waits for the process to exit. It uses the `kill()' system call and Unix signals, so it runs on Unix and Unix-like systems. Invoke *Note `mysql_waitpid': mysql-waitpid. like this: shell> mysql_waitpid [OPTIONS] PID WAIT_TIME *Note `mysql_waitpid': mysql-waitpid. sends signal 0 to the process identified by PID and waits up to WAIT_TIME seconds for the process to terminate. PID and WAIT_TIME must be positive integers. If process termination occurs within the wait time or the process does not exist, *Note `mysql_waitpid': mysql-waitpid. returns 0. Otherwise, it returns 1. If the `kill()' system call cannot handle signal 0, `mysql_waitpid()' uses signal 1 instead. *Note `mysql_waitpid': mysql-waitpid. supports the following options: * `--help', `-?', `-I' Display a help message and exit. * `--verbose', `-v' Verbose mode. Display a warning if signal 0 could not be used and signal 1 is used instead. * `--version', `-V' Display version information and exit.  File: manual.info, Node: mysql-zap, Prev: mysql-waitpid, Up: programs-admin-utils 4.6.16 `mysql_zap' -- Kill Processes That Match a Pattern --------------------------------------------------------- *Note `mysql_zap': mysql-zap. kills processes that match a pattern. It uses the `ps' command and Unix signals, so it runs on Unix and Unix-like systems. Invoke *Note `mysql_zap': mysql-zap. like this: shell> mysql_zap [-SIGNAL] [-?Ift] PATTERN A process matches if its output line from the `ps' command contains the pattern. By default, *Note `mysql_zap': mysql-zap. asks for confirmation for each process. Respond `y' to kill the process, or `q' to exit *Note `mysql_zap': mysql-zap. For any other response, *Note `mysql_zap': mysql-zap. does not attempt to kill the process. If the `-SIGNAL' option is given, it specifies the name or number of the signal to send to each process. Otherwise, *Note `mysql_zap': mysql-zap. tries first with `TERM' (signal 15) and then with *Note `KILL': kill. (signal 9). *Note `mysql_zap': mysql-zap. supports the following additional options: * `--help', `-?', `-I' Display a help message and exit. * `-f' Force mode. *Note `mysql_zap': mysql-zap. attempts to kill each process without confirmation. * `-t' Test mode. Display information about each process but do not kill it.  File: manual.info, Node: programs-development, Next: programs-miscellaneous, Prev: programs-admin-utils, Up: programs 4.7 MySQL Program Development Utilities ======================================= * Menu: * msql2mysql:: `msql2mysql' --- Convert mSQL Programs for Use with MySQL * mysql-config:: `mysql_config' --- Display Options for Compiling Clients * my-print-defaults:: `my_print_defaults' --- Display Options from Option Files * resolve-stack-dump:: `resolve_stack_dump' --- Resolve Numeric Stack Trace Dump to Symbols This section describes some utilities that you may find useful when developing MySQL programs. In shell scripts, you can use the *Note `my_print_defaults': 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 *Note `my_print_defaults': 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.  File: manual.info, Node: msql2mysql, Next: mysql-config, Prev: programs-development, Up: programs-development 4.7.1 `msql2mysql' -- Convert mSQL Programs for Use with MySQL -------------------------------------------------------------- Initially, the MySQL C API was developed to be very similar to that for the mSQL database system. Because of this, mSQL programs often can be converted relatively easily for use with MySQL by changing the names of the C API functions. The *Note `msql2mysql': msql2mysql. utility performs the conversion of mSQL C API function calls to their MySQL equivalents. *Note `msql2mysql': msql2mysql. converts the input file in place, so make a copy of the original before converting it. For example, use *Note `msql2mysql': msql2mysql. like this: shell> cp client-prog.c client-prog.c.orig shell> msql2mysql client-prog.c client-prog.c converted Then examine `client-prog.c' and make any post-conversion revisions that may be necessary. *Note `msql2mysql': msql2mysql. uses the *Note `replace': replace-utility. utility to make the function name substitutions. See *Note replace-utility::.  File: manual.info, Node: mysql-config, Next: my-print-defaults, Prev: msql2mysql, Up: programs-development 4.7.2 `mysql_config' -- Display Options for Compiling Clients ------------------------------------------------------------- *Note `mysql_config': 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 `mysql_config': mysql-config. supports the following options. * `--cflags' 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. * `--include' Compiler options to find MySQL include files. * `--libmysqld-libs', `--embedded' Libraries and options required to link with the MySQL embedded server. * `--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. * `--plugindir' The default plugin directory path name, defined when configuring MySQL. This option was added in MySQL 5.1.24. * `--port' The default TCP/IP port number, defined when configuring MySQL. * `--socket' The default Unix socket file, defined when configuring MySQL. * `--version' Version number for the MySQL distribution. If you invoke *Note `mysql_config': 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] --include [-I/usr/local/mysql/include/mysql] --libs [-L/usr/local/mysql/lib/mysql -lmysqlclient -lz -lz -lcrypt -lnsl -lm] --libs_r [-L/usr/local/mysql/lib/mysql -lmysqlclient_r -lz -lpthread -lcrypt -lnsl -lm -lpthread] --socket [/tmp/mysql.sock] --port [3306] --version [5.1.69] --libmysqld-libs [-L/usr/local/mysql/lib/mysql -lmysqld -ldl -lz -lpthread -lcrypt -lnsl -lm -lpthread -lrt] You can use *Note `mysql_config': mysql-config. within a command line using backticks to include the output that it produces for a particular option. For example, to compile and link a MySQL client program, use *Note `mysql_config': mysql-config. as follows: shell> gcc -c `mysql_config --cflags` progname.c shell> gcc -o progname progname.o `mysql_config --libs`  File: manual.info, Node: my-print-defaults, Next: resolve-stack-dump, Prev: mysql-config, Up: programs-development 4.7.3 `my_print_defaults' -- Display Options from Option Files -------------------------------------------------------------- *Note `my_print_defaults': 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 *Note `mysqlcheck': mysqlcheck. program reads the `[mysqlcheck]' and `[client]' option groups. To see what options are present in those groups in the standard option files, invoke *Note `my_print_defaults': my-print-defaults. like this: shell> my_print_defaults mysqlcheck client --user=myusername --password=secret --host=localhost The output consists of options, one per line, in the form that they would be specified on the command line. *Note `my_print_defaults': 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. * `--no-defaults', `-n' Return an empty string. * `--verbose', `-v' Verbose mode. Print more information about what the program does. * `--version', `-V' Display version information and exit.  File: manual.info, Node: resolve-stack-dump, Prev: my-print-defaults, Up: programs-development 4.7.4 `resolve_stack_dump' -- Resolve Numeric Stack Trace Dump to Symbols ------------------------------------------------------------------------- *Note `resolve_stack_dump': resolve-stack-dump. resolves a numeric stack dump to symbols. Invoke *Note `resolve_stack_dump': 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 *Note `mysqld': mysqld. If no numeric dump file is named on the command line, the stack trace is read from the standard input. *Note `resolve_stack_dump': 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 *Note using-stack-trace::.  File: manual.info, Node: programs-miscellaneous, Prev: programs-development, Up: programs 4.8 Miscellaneous Programs ========================== * Menu: * perror:: `perror' --- Explain Error Codes * replace-utility:: `replace' --- A String-Replacement Utility * resolveip:: `resolveip' --- Resolve Host name to IP Address or Vice Versa  File: manual.info, Node: perror, Next: replace-utility, Prev: programs-miscellaneous, Up: programs-miscellaneous 4.8.1 `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 *Note `perror': perror. utility. *Note `perror': perror. prints a description for a system error code or for a storage engine (table handler) error code. Invoke *Note `perror': 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 To obtain the error message for a MySQL Cluster error code, invoke *Note `perror': perror. with the `--ndb' option: shell> perror --ndb ERRORCODE Note that 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. *Note `perror': perror. supports the following options. * `--help', `--info', `-I', `-?' Display a help message and exit. * `--ndb' Print the error message for a MySQL Cluster error code. * `--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.  File: manual.info, Node: replace-utility, Next: resolveip, Prev: perror, Up: programs-miscellaneous 4.8.2 `replace' -- A String-Replacement Utility ----------------------------------------------- The *Note `replace': replace-utility. utility program changes strings in place in files or on the standard input. Invoke *Note `replace': replace-utility. 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, *Note `replace': replace-utility. reads the standard input and writes to the standard output. *Note `replace': replace-utility. 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 ... The *Note `replace': replace-utility. program is used by *Note `msql2mysql': msql2mysql. See *Note msql2mysql::. *Note `replace': replace-utility. 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.  File: manual.info, Node: resolveip, Prev: replace-utility, Up: programs-miscellaneous 4.8.3 `resolveip' -- Resolve Host name to IP Address or Vice Versa ------------------------------------------------------------------ The *Note `resolveip': resolveip. utility resolves host names to IP addresses and vice versa. Invoke *Note `resolveip': resolveip. like this: shell> resolveip [OPTIONS] {HOST_NAME|IP-ADDR} ... *Note `resolveip': 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.  File: manual.info, Node: server-administration, Next: security, Prev: programs, Up: Top 5 MySQL Server Administration ***************************** * Menu: * mysqld-server:: The MySQL Server * server-logs:: MySQL Server Logs * multiple-servers:: Running Multiple MySQL Instances on One Machine MySQL Server (*Note `mysqld': 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 server log files. * Management of multiple servers on a single machine. For additional information on administrative topics, see also: * *Note security:: * *Note backup-and-recovery:: * *Note replication::  File: manual.info, Node: mysqld-server, Next: server-logs, Prev: server-administration, Up: server-administration 5.1 The MySQL Server ==================== * Menu: * mysqld-option-tables:: Server Option and Variable Reference * server-configuration-defaults:: Server Configuration Defaults * server-options:: Server Command Options * server-system-variables:: Server System Variables * using-system-variables:: Using System Variables * server-status-variables:: Server Status Variables * server-sql-mode:: Server SQL Modes * server-plugins:: Server Plugins * server-side-help-support:: Server-Side Help * server-signal-response:: Server Response to Signals * server-shutdown:: The Shutdown Process *Note `mysqld': 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. * The server shutdown process. There are performance and reliability considerations depending on the type of table (transactional or nontransactional) and whether you use replication. *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 *Note show-engines::.  File: manual.info, Node: mysqld-option-tables, Next: server-configuration-defaults, Prev: mysqld-server, Up: mysqld-server 5.1.1 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 MySQL Cluster, see *Note mysql-cluster-option-tables::. *Option/Variable Summary* Name Cmd-Line Option file System Var Status Var Var Scope Dynamic abort-slave-event-countYes Yes Aborted_clients Yes Global No Aborted_connects Yes Global No allow-suspicious-udfsYes Yes ansi Yes Yes auto_increment_increment Yes Both Yes auto_increment_offset Yes Both Yes autocommit Yes Yes Yes Session Yes automatic_sp_privileges Yes Global Yes back_log Yes Global No basedir Yes Yes Yes Global No big-tables Yes Yes Session Yes - _Variable_: Yes Session Yes big_tables bind-address Yes Yes Yes Global No Binlog_cache_disk_use Yes Global No binlog_cache_sizeYes Yes Yes Global Yes Binlog_cache_use Yes Global No binlog_direct_non_transactional_updatesYes Yes Yes Both Yes binlog-do-db Yes Yes binlog-format Yes Yes Both Yes - _Variable_: Yes Both Yes binlog_format binlog-ignore-dbYes Yes binlog-row-event-max-sizeYes 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-handshakeYes Yes character_set_connection Yes Both Yes character_set_database Yes Both Yes This option is dynamic, but only the server should set this information. You should not set the value of this variable manually. character-set-filesystemYes Yes Both Yes - _Variable_: Yes Both Yes character_set_filesystem character_set_results Yes Both Yes character-set-serverYes Yes Both Yes - _Variable_: Yes Both Yes character_set_server character_set_system Yes Global No character-sets-dirYes Yes Global No - _Variable_: Yes Global No character_sets_dir chroot Yes Yes collation_connection Yes Both Yes collation_database Yes Both Yes This option is dynamic, but only the server should set this information. You should not set the value of this variable manually. collation-serverYes Yes Both Yes - _Variable_: Yes Both Yes 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_analyze Yes Both No Com_assign_to_keycache Yes Both No Com_backup_table 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_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_flush Yes Both No Com_grant Yes Both 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_restore_table 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_column_types 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_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_logs 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_slave_hosts Yes Both No Com_show_slave_status 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_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 Connections Yes Global No console Yes Yes core-file Yes Yes Created_tmp_disk_tables Yes Both No Created_tmp_files Yes Global No Created_tmp_tables Yes Both No datadir Yes Yes Yes Global No date_format Yes Both No datetime_format Yes Both No debug Yes Yes Yes Both Yes debug_sync Yes Both Yes debug-sync-timeoutYes Yes default-storage-engineYes Yes Yes Both Yes default-table-typeYes Yes default-time-zoneYes Yes default_week_formatYes Yes Yes Both Yes defaults-extra-fileYes defaults-file Yes defaults-group-suffixYes delay-key-writeYes Yes Global Yes - _Variable_: Yes Global Yes 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 disconnect-slave-event-countYes Yes div_precision_incrementYes Yes Yes Both Yes enable-locking Yes Yes enable-named-pipeYes Yes - _Variable_: named_pipe enable-pstack Yes Yes engine-condition-pushdownYes Yes Both Yes - _Variable_: Yes Both Yes engine_condition_pushdown error_count Yes Session No event-schedulerYes Yes Global Yes - _Variable_: Yes Global Yes event_scheduler exit-info Yes Yes expire_logs_daysYes Yes Yes Global Yes external-lockingYes Yes - _Variable_: skip_external_locking *Note Yes Yes federated: federated-storage-engine. flush Yes Yes Yes Global Yes Flush_commands Yes Global No flush_time Yes Yes Yes Global Yes foreign_key_checks Yes Session 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_limitYes Yes Yes Global No ft_stopword_fileYes Yes Yes Global No gdb Yes Yes general-log Yes Yes Global Yes - _Variable_: Yes Global Yes general_log general_log_fileYes Yes Yes Global Yes group_concat_max_lenYes Yes Yes Both Yes Handler_commit Yes Both No Handler_delete Yes Both No Handler_discover Yes Both No Handler_prepare Yes Both No Handler_read_first Yes Both No Handler_read_key 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_archive Yes Global No have_blackhole_engine Yes Global No have_community_features Yes Global No have_compress Yes Global No have_crypt Yes Global No have_csv Yes Global No have_dynamic_loading Yes Global No have_example_engine Yes Global No have_federated_engine Yes Global No have_geometry Yes Global No have_innodb Yes Global No have_isam Yes Global No have_merge_engine Yes Global No have_ndbcluster Yes Global No have_openssl Yes Global No have_partition_engine Yes Global No have_partitioning Yes Global No have_query_cache Yes Global No have_raid Yes Global No have_row_based_replication Yes Global No have_rtree_keys Yes Global No have_ssl Yes Global No have_symlink Yes Global No help Yes Yes hostname Yes Global No identity Yes Session Yes ignore-builtin-innodbYes Yes Global No - _Variable_: Yes Global No ignore_builtin_innodb init_connect Yes Yes Yes Global Yes init-file Yes Yes Global No - _Variable_: Yes Global No init_file init-rpl-role Yes Yes init_slave Yes Yes Yes Global Yes innodb Yes Yes innodb_adaptive_flushingYes Yes Yes Global Yes innodb_adaptive_hash_indexYes Yes Yes Global No innodb_additional_mem_pool_sizeYes Yes Yes Global No innodb_autoextend_incrementYes Yes Yes Global Yes innodb_autoinc_lock_modeYes Yes Yes Global No innodb_buffer_pool_awe_mem_mbYes Yes 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_ahead_seq Yes Global No Innodb_buffer_pool_read_requests Yes Global No Innodb_buffer_pool_reads Yes Global No innodb_buffer_pool_sizeYes Yes Yes Global No Innodb_buffer_pool_wait_free Yes Global No Innodb_buffer_pool_write_requests Yes Global No innodb_change_bufferingYes Yes Yes Global Yes innodb_checksumsYes Yes Yes Global No innodb_commit_concurrencyYes Yes Yes Global Yes innodb_concurrency_ticketsYes Yes 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_doublewriteYes Yes Yes Global No innodb_fast_shutdownYes Yes Yes Global Yes innodb_file_formatYes Yes Yes Global Yes innodb_file_format_checkYes Yes Yes Global Yes innodb_file_io_threadsYes Yes Yes Global No innodb_file_per_tableYes Yes Yes Global No innodb_flush_log_at_trx_commitYes Yes Yes Global Yes innodb_flush_methodYes Yes Yes Global No innodb_force_recoveryYes Yes Yes Global No Innodb_have_atomic_builtins Yes Global No innodb_io_capacityYes Yes Yes Global No innodb_lock_wait_timeoutYes Yes Yes Both Yes innodb_locks_unsafe_for_binlogYes Yes Yes Global No innodb_log_arch_dirYes Yes Yes Global No innodb_log_archiveYes Yes Yes Global No innodb_log_buffer_sizeYes Yes Yes Global No innodb_log_file_sizeYes Yes Yes Global No innodb_log_files_in_groupYes Yes Yes Global No innodb_log_group_home_dirYes Yes Yes Global No Innodb_log_waits Yes Global No Innodb_log_write_requests Yes Global No Innodb_log_writes Yes Global No innodb_max_dirty_pages_pctYes Yes Yes Global Yes innodb_max_purge_lagYes Yes Yes Global Yes innodb_mirrored_log_groupsYes Yes Yes Global No innodb_old_blocks_pctYes Yes Yes Global Yes innodb_old_blocks_timeYes Yes Yes Global Yes innodb_open_filesYes Yes Yes Global No 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_size Yes Global No Innodb_pages_created Yes Global No Innodb_pages_read Yes Global No Innodb_pages_written Yes Global No innodb_random_read_aheadYes Yes Yes Global Yes innodb_read_ahead_thresholdYes Yes Yes Global Yes innodb_read_io_threadsYes Yes Yes Global No innodb_replication_delayYes Yes Yes Global Yes innodb_rollback_on_timeoutYes Yes Yes Global No 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_spin_wait_delayYes Yes Yes Global Yes innodb_stats_methodYes Yes Yes Global Yes innodb_stats_on_metadataYes Yes Yes Global Yes innodb_stats_sample_pagesYes Yes Yes Global Yes innodb-status-fileYes Yes innodb_strict_modeYes Yes Yes Both Yes innodb_support_xaYes Yes Yes Both Yes innodb_sync_spin_loopsYes Yes Yes Global Yes innodb_table_locksYes Yes Yes Both Yes innodb_thread_concurrencyYes Yes Yes Global Yes innodb_thread_sleep_delayYes Yes Yes Global Yes innodb_use_legacy_cardinality_algorithmYes Yes Yes Global Yes 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 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_limitYes Yes 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 language Yes Yes Yes Global No large_files_support Yes Global No large_page_size Yes Global No large-pages Yes Yes Global No - _Variable_: Yes Global No large_pages last_insert_id Yes Session Yes Last_query_cost Yes Session No lc_time_names Yes Both Yes license Yes Global No local_infile Yes Global Yes locked_in_memory Yes Global No log Yes Yes Yes Global Yes log_bin Yes Global No log-bin Yes Yes Yes Global No log-bin-index Yes Yes log-bin-trust-function-creatorsYes Yes Global Yes - _Variable_: Yes Global Yes log_bin_trust_function_creators log-bin-trust-routine-creatorsYes Yes Global Yes - _Variable_: Yes Global Yes log_bin_trust_routine_creators (http://dev.mysql.com/doc/refman/5.0/en/server-system-variables.html#sysvar_log_bin_trust_routine_creators) log_bin_use_v1_row_eventsYes Yes Yes Global No log-bin-use-v1-row-eventsYes Yes Global No - _Variable_: Yes Global No log_bin_use_v1_row_events log-error Yes Yes Global No - _Variable_: Yes Global No log_error log-isam Yes Yes log-output Yes Yes Global Yes - _Variable_: Yes Global Yes log_output log-queries-not-using-indexesYes Yes Global Yes - _Variable_: Yes Global Yes log_queries_not_using_indexes log-short-formatYes Yes log-slave-updatesYes Yes Global No - _Variable_: Yes Global No log_slave_updates log_slave_updatesYes Yes Yes Global No log-slow-admin-statementsYes Yes log-slow-queriesYes Yes Global Yes - _Variable_: Yes Global Yes log_slow_queries log-slow-slave-statementsYes Yes log-tc Yes Yes log-tc-size Yes Yes log-warnings Yes Yes Both Yes - _Variable_: Yes Both Yes log_warnings long_query_timeYes Yes Yes Both Yes low-priority-updatesYes Yes Both Yes - _Variable_: Yes Both Yes low_priority_updates lower_case_file_system Yes Global No lower_case_table_namesYes Yes Yes Global No master-connect-retryYes Yes master-host Yes Yes master-info-fileYes Yes master-passwordYes Yes master-port Yes Yes master-retry-countYes Yes master-ssl Yes Yes master-ssl-ca Yes Yes master-ssl-capathYes Yes master-ssl-certYes Yes master-ssl-cipherYes Yes master-ssl-key Yes Yes master-user Yes Yes max_allowed_packetYes Yes Yes Global Yes max_binlog_cache_sizeYes Yes Yes Global Yes max-binlog-dump-eventsYes Yes max_binlog_sizeYes Yes Yes Global Yes max_connect_errorsYes Yes Yes Global Yes max_connectionsYes Yes Yes Global Yes max_delayed_threadsYes Yes Yes Both Yes max_error_countYes 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_dataYes Yes Yes Both Yes max_long_data_sizeYes Yes Yes Global No 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_used_connections Yes Global No max_user_connectionsYes Yes Yes Both Yes max_write_lock_countYes Yes Yes Global Yes memlock Yes Yes Yes Global No merge Yes Yes min-examined-row-limitYes Yes Yes Both Yes multi_range_countYes Yes Yes Both Yes myisam-block-sizeYes Yes myisam_data_pointer_sizeYes Yes Yes Global Yes myisam_max_sort_file_sizeYes Yes Yes Global Yes myisam_mmap_sizeYes Yes Yes Global No myisam-recover Yes 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 named_pipe Yes Global No 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_session Yes Session No Ndb_api_bytes_sent_count_slave Yes Global No Ndb_api_event_bytes_count Yes Global No Ndb_api_event_bytes_count_injector Yes Global No Ndb_api_event_data_count Yes Global No Ndb_api_event_data_count_injector Yes Global No Ndb_api_event_nondata_count 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_pruned_scan_count_slave Yes Global No Ndb_api_range_scan_count Yes Global No Ndb_api_range_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_read_row_count_slave Yes Global No Ndb_api_scan_batch_count Yes Global No Ndb_api_scan_batch_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_table_scan_count_slave Yes Global 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 Yes Global No Ndb_api_trans_local_read_row_count_session Yes Session 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_session Yes Session 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_meta_request_count_slave Yes Global 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_szYes Yes Yes Both Yes ndb-batch-size Yes Yes Yes Global No ndb-blob-read-batch-bytesYes Yes Yes Both Yes ndb-blob-write-batch-bytesYes Yes Yes Both Yes ndb_cache_check_timeYes Yes Yes Global Yes ndb-cluster-connection-poolYes Yes Yes Yes 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 Yes Global 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_conflict_commit_count Yes Global No Ndb_conflict_trans_detect_iter_count Yes Global No Ndb_conflict_trans_reject_count Yes Global No Ndb_conflict_trans_row_conflict_count Yes Global No Ndb_conflict_trans_row_reject_count Yes Global No ndb-connectstringYes Yes ndb-deferred-constraintsYes Yes Both Yes - _Variable_: Yes Both Yes ndb_deferred_constraints ndb_deferred_constraintsYes Yes Yes Both Yes ndb_distributionYes Yes Yes Both Yes ndb-distributionYes Yes Both Yes - _Variable_: Yes Both Yes ndb_distribution ndb_execute_count Yes Global No ndb_extra_loggingYes Yes Yes Global Yes ndb_force_send Yes Yes Yes Both Yes ndb_index_stat_cache_entriesYes Yes ndb_index_stat_enableYes Yes ndb_index_stat_update_freqYes Yes ndb_join_pushdown Yes Global No ndb-log-apply-statusYes Yes Global No - _Variable_: Yes Global No ndb_log_apply_status 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-orig Yes Yes Global No - _Variable_: Yes Global No ndb_log_orig ndb-log-transaction-idYes Yes Global No - _Variable_: Yes Global No ndb_log_transaction_id ndb_log_transaction_id Yes Global No ndb-log-update-as-writeYes 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_selectionYes Yes ndb_pruned_scan_count Yes Global No Ndb_pushed_queries_defined Yes Global No Ndb_pushed_queries_dropped Yes Global No Ndb_pushed_queries_executed Yes Global No ndb_pushed_reads Yes Global No ndb_report_thresh_binlog_epoch_slipYes Yes ndb_report_thresh_binlog_mem_usageYes Yes ndb_scan_count 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-wait-connectedYes Yes Yes Global No ndb-wait-setup Yes Yes Yes Global No ndbcluster Yes Yes - _Variable_: have_ndbcluster ndbinfo_database Yes Global No ndbinfo_max_bytesYes Yes Both Yes ndbinfo_max_rowsYes Yes Both 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 no-defaults Yes Not_flushed_delayed_rows Yes Global No old Yes Yes Yes Global No old-alter-tableYes Yes Both Yes - _Variable_: Yes Both Yes old_alter_table old_passwords Yes Both Yes old-style-user-limitsYes Yes one-thread Yes Yes Open_files Yes Global No open-files-limitYes Yes Global No - _Variable_: Yes Global No 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 partition Yes Yes - _Variable_: have_partitioning pid-file Yes Yes Global No - _Variable_: Yes Global No pid_file plugin Yes Yes plugin_dir Yes Yes Yes Global No plugin-load Yes Yes port Yes Yes Yes Global No port-open-timeoutYes Yes preload_buffer_sizeYes Yes Yes Both Yes prepared_stmt_count Yes Global No Prepared_stmt_count Yes Global No print-defaults Yes profiling Yes Session Yes profiling_history_sizeYes Yes Yes Both Yes protocol_version Yes Global No 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_unitYes Yes Yes Global Yes query_cache_sizeYes Yes Yes Global Yes query_cache_typeYes Yes Yes Both Yes query_cache_wlock_invalidateYes Yes 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 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 - _Variable_: Yes Global No relay_log relay-log-indexYes Yes Global No - _Variable_: Yes Global No 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_purgeYes Yes Yes Global Yes 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-idYes Yes replicate-wild-do-tableYes Yes replicate-wild-ignore-tableYes Yes report-host Yes Yes Global No - _Variable_: Yes Global No report_host report-passwordYes Yes Global No - _Variable_: Yes Global No report_password report-port Yes Yes Global No - _Variable_: Yes Global No report_port report-user Yes Yes Global No - _Variable_: Yes Global No report_user rpl_recovery_rank Yes Global Yes Rpl_status Yes Global No safe-mode Yes Yes safe-show-databaseYes Yes Yes Global Yes safe-user-createYes Yes safemalloc-mem-limitYes Yes secure-auth Yes Yes Global Yes - _Variable_: Yes Global Yes secure_auth secure-file-privYes Yes Global No - _Variable_: Yes Global No 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 - _Variable_: Yes Global Yes server_id server-id-bits Yes Yes Global No - _Variable_: Yes Global No server_id_bits shared_memory Yes Global No shared_memory_base_name Yes Global No show-slave-auth-infoYes Yes skip-character-set-client-handshakeYes Yes 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-locking Yes Yes skip-merge Yes Yes skip-name-resolveYes Yes Global No - _Variable_: Yes Global No skip_name_resolve skip-ndbclusterYes Yes skip-networkingYes Yes Global No - _Variable_: Yes Global No skip_networking skip-new Yes Yes skip-partition Yes Yes skip-safemallocYes Yes skip-show-databaseYes Yes Global No - _Variable_: Yes Global No skip_show_database skip-slave-startYes Yes skip-ssl Yes Yes skip-stack-traceYes Yes skip-symbolic-linksYes skip-symlink Yes Yes skip-thread-priorityYes Yes slave_allow_batchingYes Yes Yes Global Yes slave_compressed_protocolYes Yes Yes Global Yes slave_exec_modeYes Yes Yes Global Yes Slave_heartbeat_period Yes Global No slave-load-tmpdirYes Yes Global No - _Variable_: Yes Global No slave_load_tmpdir slave_max_allowed_packet Yes Global Yes slave-max-allowed-packetYes Yes - _Variable_: slave_max_allowed_packet slave-net-timeoutYes Yes Global Yes - _Variable_: Yes Global Yes slave_net_timeout Slave_open_temp_tables Yes Global No Slave_received_heartbeats Yes Global No Slave_retried_transactions Yes Global No Slave_running Yes Global No slave-skip-errorsYes Yes Global No - _Variable_: Yes Global No slave_skip_errors slave_transaction_retriesYes Yes 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 - _Variable_: Yes Global Yes slow_query_log slow_query_log_fileYes Yes Yes Global 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-failYes Yes sql_auto_is_null Yes Session Yes sql_big_selects Yes Session Yes sql_big_tables Yes Session Yes sql_buffer_result Yes Session Yes sql_log_bin Yes Session Yes sql_log_off Yes Session Yes sql_log_update Yes Session Yes sql_low_priority_updates Yes Both Yes sql_max_join_size Yes Both Yes sql-mode Yes Yes Both Yes - _Variable_: Yes Both Yes sql_mode sql_notes Yes Session Yes sql_quote_show_create Yes Session Yes sql_safe_updates Yes Session Yes sql_select_limit Yes Both Yes sql_slave_skip_counter Yes Global Yes sql_warnings Yes Session Yes ssl Yes Yes Ssl_accept_renegotiates Yes Global No Ssl_accepts Yes Global No ssl-ca Yes Yes Global No - _Variable_: Yes Global No ssl_ca Ssl_callback_cache_hits Yes Global No ssl-capath Yes Yes Global No - _Variable_: Yes Global No ssl_capath ssl-cert Yes Yes Global No - _Variable_: Yes Global No ssl_cert ssl-cipher Yes Yes Global No - _Variable_: Yes Global No ssl_cipher Ssl_cipher Yes Both No Ssl_cipher_list Yes Both No Ssl_client_connects Yes Global No Ssl_connect_renegotiates Yes Global No 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 - _Variable_: Yes Global No ssl_key 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-verify-server-certYes Yes Ssl_version Yes Both No standalone Yes Yes storage_engine Yes Both Yes symbolic-links Yes Yes sync_binlog Yes Yes Yes Global Yes sync_frm Yes Yes Yes Global Yes sysdate-is-now Yes Yes system_time_zone Yes Global No table_cache Yes Yes Yes Global Yes table_definition_cache Yes Global Yes table_lock_wait_timeoutYes Yes Yes Global Yes Table_locks_immediate Yes Global No Table_locks_waited Yes Global No table_open_cache Yes Global Yes table_type Yes Both Yes 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_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 Both No time_zone Yes Both Yes timed_mutexes Yes Yes Yes Global Yes timestamp Yes Session Yes tmp_table_size Yes Yes Yes Both Yes tmpdir Yes Yes Yes Global No transaction_alloc_block_sizeYes Yes Yes Both Yes transaction_allow_batching Yes Session Yes transaction-isolationYes Yes - _Variable_: tx_isolation transaction_prealloc_sizeYes Yes Yes Both Yes tx_isolation Yes Both Yes unique_checks Yes Session Yes updatable_views_with_limitYes Yes Yes Both Yes Uptime Yes Global No Uptime_since_flush_status Yes Global No use-symbolic-linksYes Yes user Yes Yes verbose Yes Yes version Yes Global No version_comment Yes Global No version_compile_machine Yes Global No version_compile_os Yes Global No wait_timeout Yes Yes Yes Both Yes warning_count Yes Session No  File: manual.info, Node: server-configuration-defaults, Next: server-options, Prev: mysqld-option-tables, Up: mysqld-server 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 *Note server-options::, and *Note server-system-variables::. MySQL provides a number of preconfigured option files that can be used as a basis for tuning the MySQL server. Look for files named `my-small.cnf', `my-medium.cnf', `my-large.cnf', and `my-huge.cnf', which are sample option files for small, medium, large, and very large systems. On Windows, the extension is `.ini' rather than `.cnf'. *Note*: On Windows, the `.ini' or `.cnf' option file extension might not be displayed. For a binary distribution, look for the sample files in or under your installation directory. If you have a source distribution, look in the `support-files' directory. To use a sample file as a base configuration file, rename a copy of it and place the copy in the appropriate location. Regarding names and appropriate location, see the general information provided in *Note option-files::. That section also describes option file format and syntax.  File: manual.info, Node: server-options, Next: server-system-variables, Prev: server-configuration-defaults, Up: mysqld-server 5.1.3 Server Command Options ---------------------------- When you start the *Note `mysqld': mysqld. server, you can specify program options using any of the methods described in *Note 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 *Note option-files::. *Note `mysqld': mysqld. reads options from the `[mysqld]' and `[server]' groups. *Note `mysqld_safe': mysqld-safe. reads options from the `[mysqld]', `[server]', `[mysqld_safe]', and `[safe_mysqld]' groups. *Note `mysql.server': 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. *Note `mysqld': mysqld. accepts many command options. For a brief summary, execute *Note `mysqld --help': mysqld. To see the full list, use *Note `mysqld --verbose --help': mysqld. The following list shows some of the most common server options. Additional options are described in other sections: * Options that affect security: See *Note security-options::. * SSL-related options: See *Note ssl-options::. * Binary log control options: See *Note binary-log::. * Replication-related options: See *Note replication-options::. * Options for loading plugins such as pluggable storage engines: See *Note server-plugin-loading::. * Options specific to particular storage engines: See *Note innodb-parameters::, *Note myisam-start::, and *Note mysql-cluster-program-options-mysqld::. You can also set the values of server system variables by using variable names as options, as described at the end of this section. 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. * `--help', `-?' Options for help *Command-Line `-?' Format* `--help' *Option-File Format* `help' Display a short help message and exit. Use both the `--verbose' and `--help' options to see the full message. * `--allow-suspicious-udfs' Options for allow-suspicious-udfs *Command-Line `--allow-suspicious-udfs' Format* *Option-File Format* `allow-suspicious-udfs' *Permitted Values* *Type* `boolean' *Default* `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 *Note udf-security::. * `--ansi' Options for ansi *Command-Line `--ansi' Format* `-a' *Option-File 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 *Note ansi-mode::, and *Note server-sql-mode::. * `--basedir=PATH', `-b PATH' Options for basedir *Command-Line `--basedir=path' Format* `-b' *Option-File Format* `basedir' *System Variable `basedir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The path to the MySQL installation directory. All paths are usually resolved relative to this directory. * `--big-tables' Options for big-tables *Command-Line `--big-tables' Format* *Option-File Format* `big-tables' *System Variable `big_tables' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' 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. Since MySQL 3.23.2, 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' Options for bind-address *Command-Line `--bind-address=addr' Format* *Option-File Format* `bind-address' *System Variable `bind_address' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' *Default* `0.0.0.0' 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. The default address is `0.0.0.0'. To specify an address explicitly, use the `--bind-address=ADDR' option at server startup, where ADDR is an IPv4 address or a host name. If ADDR is a host name, the server resolves the name to an IPv4 address and binds to that address. The server treats different types of addresses as follows: * If the address is `0.0.0.0', the server accepts TCP/IP connections on all server host IPv4 interfaces. * If the address is a `regular' IPv4 address (such as `127.0.0.1'), the server accepts TCP/IP connections only for that particular IPv4 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 connect to that address. Otherwise, you will not be able to shut down the server. For example, if you bind to `0.0.0.0', you can connect to the server using all existing accounts. But if you bind to `127.0.0.1', the server accepts connections only on that address. In this case, first make sure that the `'root'@'127.0.0.1'' account is present in the `mysql.user' table so that you can still connect to the server to shut it down. * `--binlog-format={ROW|STATEMENT|MIXED}' Options for binlog-format *Introduced* 5.1.5 *Command-Line `--binlog-format=format' Format* *Option-File Format* `binlog-format' *System Variable `binlog_format' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values (>= 5.1.5, <= 5.1.7)* *Type* `enumeration' *Default* `STATEMENT' *Valid Values* `ROW' `STATEMENT' *Permitted Values (>= 5.1.8, <= 5.1.11)* *Type* `enumeration' *Default* `STATEMENT' *Valid Values* `ROW' `STATEMENT' `MIXED' *Permitted Values (>= 5.1.12, <= 5.1.28)* *Type* `enumeration' *Default* `MIXED' *Valid Values* `ROW' `STATEMENT' `MIXED' *Permitted Values (>= 5.1.29)* *Type* `enumeration' *Default* `STATEMENT' *Valid Values* `ROW' `STATEMENT' `MIXED' Specify whether to use row-based, statement-based, or mixed replication (statement-based was the default prior to MySQL 5.1.12; in 5.1.12, the default was changed to mixed replication; in 5.1.29, the default was changed back to statement-based). See *Note replication-formats::. This option was added in MySQL 5.1.5. Under some conditions, changing this variable at runtime is not possible, or causes replication to fail. See *Note binary-log-setting::, for more information. *Important*: Setting the binary logging format without enabling binary logging prevents the MySQL server from starting. This is a known issue in MySQL 5.1 which is fixed in MySQL 5.5. (Bug #42928) MySQL Cluster The default value for this option in all MySQL Cluster NDB 6.1 through 7.1 releases is `MIXED'. See *Note mysql-cluster-replication-general::, for more information. * `--bootstrap' Options for bootstrap *Command-Line `--bootstrap' Format* *Option-File Format* `bootstrap' This option is used by the *Note `mysql_install_db': mysql-install-db. script to create the MySQL privilege tables without having to start a full MySQL server. This option is unavailable if MySQL was configured with the `--disable-grant-options' option. See *Note source-configuration-options::. * `--character-sets-dir=PATH' Options for character-sets-dir *Command-Line `--character-sets-dir=path' Format* *Option-File Format* `character-sets-dir' *System Variable `character_sets_dir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `directory name' The directory where character sets are installed. See *Note charset-configuration::. * `--character-set-client-handshake' Options for character-set-client-handshake *Command-Line `--character-set-client-handshake' Format* *Option-File Format* `character-set-client-handshake' *Permitted Values* *Type* `boolean' *Default* `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' Options for character-set-filesystem *Introduced* 5.1.6 *Command-Line `--character-set-filesystem=name' Format* *Option-File Format* `character-set-filesystem' *System Variable `character_set_filesystem' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' The file system character set. This option sets the `character_set_filesystem' system variable. It was added in MySQL 5.1.6. * `--character-set-server=CHARSET_NAME', `-C CHARSET_NAME' Options for character-set-server *Command-Line `--character-set-server' Format* *Option-File Format* `character-set-server' *System Variable `character_set_server' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' Use CHARSET_NAME as the default server character set. See *Note charset-configuration::. If you use this option to specify a nondefault character set, you should also use `--collation-server' to specify the collation. * `--chroot=PATH', `-r PATH' Options for chroot *Command-Line `--chroot=name' Format* `-r name' *Option-File Format* `chroot' *Permitted Values* *Type* `file name' Put the *Note `mysqld': mysqld. server in a closed environment during startup by using the `chroot()' system call. This is a recommended security measure. Note that use of this option somewhat limits *Note `LOAD DATA INFILE': load-data. and *Note `SELECT ... INTO OUTFILE': select-into. * `--collation-server=COLLATION_NAME' Options for collation-server *Command-Line `--collation-server' Format* *Option-File Format* `collation-server' *System Variable `collation_server' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' Use COLLATION_NAME as the default server collation. See *Note charset-configuration::. * `--console' Options for console *Command-Line `--console' Format* *Option-File Format* `console' *Platform Specific* windows (Windows only.) Write error log messages to `stderr' and `stdout'. *Note `mysqld': mysqld. does not close the console window if this option is used. If both `--log-error' and `--console' are specified, whichever option is given last takes precedence. * `--core-file' Options for core-file *Command-Line `--core-file' Format* *Option-File Format* `core-file' *Permitted Values* *Type* `boolean' *Default* `OFF' Write a core file if *Note `mysqld': 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 *Note `mysqld': mysqld. is the data directory. PID represents the process ID of the server process. On Mac 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 *Note `mysqld_safe': mysqld-safe. See *Note 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. * `--datadir=PATH', `-h PATH' Options for datadir *Command-Line `--datadir=path' Format* `-h' *Option-File Format* `datadir' *System Variable `datadir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The path to the data directory. * `--debug[=DEBUG_OPTIONS]', `-# [DEBUG_OPTIONS]' Options for debug *Command-Line `--debug[=debug_options]' Format* *Option-File Format* `debug' *System Variable `debug' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' *Default* `'d:t:o,/tmp/mysqld.trace'' If MySQL is configured with `--with-debug', you can use this option to get a trace file of what *Note `mysqld': mysqld. is doing. A typical DEBUG_OPTIONS string is `'d:t:o,FILE_NAME''. The default is `'d:t:i:o,mysqld.trace''. As of MySQL 5.1.12, using `--with-debug' 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 *Note dbug-package::. * `--debug-sync-timeout[=N]' Options for debug-sync-timeout *Introduced* 5.1.41 *Command-Line `--debug-sync-timeout[=#]' Format* *Option-File Format* `debug-sync-timeout' *Permitted Values* *Type* `numeric' Controls whether the Debug Sync facility for testing and debugging is enabled. Use of Debug Sync requires that MySQL be configured with the `--enable-debug-sync' option (see *Note 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). This option was added in MySQL 5.1.41. * `--default-character-set=CHARSET_NAME' Options for default-character-set *Deprecated* 5.0.0 *Command-Line `--default-character-set=name' Format* `-C name' *Option-File Format* `default-character-set' *Permitted Values* *Type* `string' Use CHARSET_NAME as the default character set. This option is deprecated in favor of `--character-set-server'. See *Note charset-configuration::. `--default-character-set' is removed in MySQL 5.5. * `--default-collation=COLLATION_NAME' Options for default-collation *Deprecated* 4.1.3 *Command-Line `--default-collation=name' Format* *Option-File Format* `default-collation' *Permitted Values* *Type* `string' Use COLLATION_NAME as the default collation. This option is deprecated in favor of `--collation-server'. See *Note charset-configuration::. `--default-collation' is removed in MySQL 5.5. * `--default-storage-engine=TYPE' Options for default-storage-engine *Command-Line `--default-storage-engine=name' Format* *Option-File Format* `default-storage-engine' *System Variable `storage_engine' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `MyISAM' Set the default storage engine (table type) for tables. See *Note storage-engines::. * `--default-table-type=TYPE' Options for default-table-type *Deprecated* 5.0.0, by default-storage-engine *Command-Line `--default-table-type=name' Format* *Option-File Format* `default-table-type' *Permitted Values* *Type* `string' This option is a synonym for `--default-storage-engine'. It is deprecated and removed in MySQL 5.5. * `--default-time-zone=TIMEZONE' Options for default-time-zone *Command-Line `--default-time-zone=name' Format* *Option-File Format* `default-time-zone' *Permitted Values* *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. * `--delay-key-write[={OFF|ON|ALL}]' Options for delay-key-write *Command-Line `--delay-key-write[=name]' Format* *Option-File Format* `delay-key-write' *System Variable `delay_key_write' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `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 *Note server-parameters::, and *Note 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 *Note `myisamchk': myisamchk.) when the tables are in use. Doing so leads to index corruption. * `--des-key-file=FILE_NAME' Options for des-key-file *Command-Line `--des-key-file=file_name' Format* *Option-File Format* `des-key-file' Read the default DES keys from this file. These keys are used by the `DES_ENCRYPT()' and `DES_DECRYPT()' functions. * `--enable-locking' This option is deprecated. Use `--external-locking' instead. * `--enable-named-pipe' Options for enable-named-pipe *Command-Line `--enable-named-pipe' Format* *Option-File Format* `enable-named-pipe' *Platform Specific* windows Enable support for named pipes. This option applies only on Windows. For MySQL 5.1.20 and earlier, this option is available only when using the *Note `mysqld-nt': mysqld. and `mysqld-debug' servers that support named-pipe connections. For MySQL 5.1.21 and later, *Note `mysqld-nt': mysqld. is not available, but support is included in the standard *Note `mysqld': mysqld. and *Note `mysqld-debug': mysqld. servers. * `--enable-pstack' Options for enable-pstack *Deprecated* 5.1.54 *Command-Line `--enable-pstack' Format* *Option-File Format* `enable-pstack' *Permitted Values* *Type* `boolean' *Default* `FALSE' This option is nonfunctional. It is deprecated as of MySQL 5.1.54 and removed in MySQL 5.5. * `--engine-condition-pushdown={ON|OFF}' Options for engine-condition-pushdown *Command-Line `--engine-condition-pushdown' Format* *Option-File Format* `engine-condition-pushdown' *System Variable `engine_condition_pushdown' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `ON' Sets the `engine_condition_pushdown' system variable. For more information, see *Note condition-pushdown-optimization::. * `--event-scheduler[=VALUE]' Options for event-scheduler *Introduced* 5.1.6 *Command-Line `--event-scheduler[=value]' Format* *Option-File Format* `event-scheduler' *System Variable `event_scheduler' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `OFF' *Valid Values* `ON' `OFF' `DISABLED' Enable or disable, and start or stop, the event scheduler. This option was added in MySQL 5.1.6. Note that its permitted values and behavior changed in MySQL 5.1.11, and again in MySQL 5.1.12. For detailed information, see The `--event-scheduler' Option. * `--exit-info[=FLAGS]', `-T [FLAGS]' Options for exit-info *Command-Line `--exit-info[=flags]' Format* `-T [flags]' *Option-File Format* `exit-info' *Permitted Values* *Type* `numeric' This is a bit mask of different flags that you can use for debugging the *Note `mysqld': mysqld. server. Do not use this option unless you know _exactly_ what it does! * `--external-locking' Options for external-locking *Command-Line `--external-locking' Format* *Option-File Format* `external-locking' *Permitted Values* *Type* `boolean' *Default* `FALSE' Enable external locking (system locking), which is disabled by default as of MySQL 4.0. Note that if you use this option on a system on which `lockd' does not fully work (such as Linux), it is easy for *Note `mysqld': mysqld. to deadlock. To disable external locking explicitly, use `--skip-external-locking'. External locking affects only *Note `MyISAM': myisam-storage-engine. table access. For more information, including conditions under which it can and cannot be used, see *Note external-locking::. * `--flush' Options for flush *Command-Line `--flush' Format* *Option-File Format* `flush' *System Variable `flush' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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 *Note crashing::. * `--gdb' Options for gdb *Command-Line `--gdb' Format* *Option-File Format* `gdb' *Permitted Values* *Type* `boolean' *Default* `FALSE' Install an interrupt handler for `SIGINT' (needed to stop *Note `mysqld': mysqld. with `^C' to set breakpoints) and disable stack tracing and core file handling. See *Note porting::. * `--general-log[={0|1}]' Options for general-log *Introduced* 5.1.12 *Command-Line `--general-log' Format* *Option-File Format* `general-log' *System Variable `general_log' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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. This option was added in MySQL 5.1.12. * `--init-file=FILE_NAME' Options for init-file *Command-Line `--init-file=file_name' Format* *Option-File Format* `init-file' *System Variable `init_file' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' Read SQL statements from this file at startup. Each statement must be on a single line and should not include comments. This option is unavailable if MySQL was configured with the `--disable-grant-options' option. See *Note source-configuration-options::. * `--innodb-XXX' Set an option for the `InnoDB' storage engine. The `InnoDB' options are listed in *Note innodb-parameters::. * `--install [SERVICE_NAME]' Options for install *Command-Line `--install Format* [service_name]' (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 *Note windows-start-service::. *Note*: If the server is started with the `--defaults-file' and `--install' options, `--install' must be first. * `--install-manual [SERVICE_NAME]' Options for install-manual *Command-Line `--install-manual Format* [service_name]' (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 *Note 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' Options for language *Command-Line `--language=name' Format* `-L' *Option-File Format* `language' *System Variable `language' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `directory name' *Default* `/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 *Note error-message-language::. * `--large-pages' Options for large-pages *Command-Line `--large-pages' Format* *Option-File Format* `large-pages' *System Variable `large_pages' Name* *Variable Scope* Global *Dynamic Variable* No *Platform Specific* linux *Permitted Values* *Type* (linux) `boolean' *Default* `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. Currently, MySQL supports only the Linux implementation of large page support (which is called HugeTLB in Linux). See *Note large-page-support::. `--large-pages' is disabled by default. * `--log[=FILE_NAME]', `-l [FILE_NAME]' Options for log *Deprecated* 5.1.29, by general-log *Command-Line `--log[=name]' Format* `-l' *Option-File Format* `log' *System Variable `log' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `string' *Default* `OFF' This option enables logging to the general query log, which contains entries that record client connections and SQL statements received from clients. The log output destination can be selected with the `--log-output' option as of MySQL 5.1.6. Before 5.1.6, logging occurs to the general query log file. If you omit the file name, MySQL uses `HOST_NAME.log' as the file name. See *Note log-destinations::, and *Note query-log::. As of MySQL 5.1.29, the `--log' option is deprecated and is removed (along with the `log' system variable) in MySQL 5.6. Instead, use the `--general_log' option to enable the general query log and the `--general_log_file=FILE_NAME' option to set the general query log file name. * `--log-error[=FILE_NAME]' Options for log-error *Command-Line `--log-error[=name]' Format* *Option-File Format* `log-error' *System Variable `log_error' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' Log errors and startup messages to this file. See *Note error-log::. If you omit the file name, MySQL uses `HOST_NAME.err'. If the file name has no extension, the server adds an extension of `.err'. * `--log-isam[=FILE_NAME]' Options for log-isam *Command-Line `--log-isam[=name]' Format* *Option-File Format* `log-isam' *Permitted Values* *Type* `file name' Log all `MyISAM' changes to this file (used only when debugging `MyISAM'). * `--log-long-format' Options for log-long-format *Deprecated* 4.1.0 *Command-Line `--log-long-format' Format* `-0' *Option-File Format* `log-long-format' Log extra information to the binary log and slow query log, if they have been activated. For example, the user name and timestamp are logged for all queries. This option is deprecated, as it now represents the default logging behavior. (See the description for `--log-short-format'.) The `--log-queries-not-using-indexes' option is available for the purpose of logging queries that do not use indexes to the slow query log. `--log-long-format' is removed in MySQL 5.5. * `--log-output[=VALUE,...]' Options for log-output *Introduced* 5.1.6 *Command-Line `--log-output=name' Format* *Option-File Format* `log-output' *System Variable `log_output' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `set' *Default* `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'. If the option is given without a value, the default is `FILE'. (For MySQL 5.1.6 through 5.1.20, the default is `TABLE'.) `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. (Before MySQL 5.1.29, enable the logs with the `--log' and `--log-slow-queries' options. The options take an optional file name argument to specify the log file name.) For more information, see *Note log-destinations::. The `--log-output' option was added in MySQL 5.1.6. * `--log-queries-not-using-indexes' Options for log-queries-not-using-indexes *Command-Line `--log-queries-not-using-indexes' Format* *Option-File Format* `log-queries-not-using-indexes' *System Variable `log_queries_not_using_indexes' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' If you are using this option with the slow query log enabled, queries that are expected to retrieve all rows are logged. See *Note 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-short-format' Options for log-short-format *Command-Line `--log-short-format' Format* *Option-File Format* `log-short-format' *Permitted Values* *Type* `boolean' *Default* `FALSE' Log less information to the binary log and slow query log, if they have been activated. * `--log-slow-admin-statements' Options for log-slow-admin-statements *Command-Line `--log-slow-admin-statements' Format* *Option-File Format* `log-slow-admin-statements' *Permitted Values* *Type* `boolean' *Default* `OFF' Include slow administrative statements in the statements written to the slow query log. Administrative statements include *Note `ALTER TABLE': alter-table, *Note `ANALYZE TABLE': analyze-table, *Note `CHECK TABLE': check-table, *Note `CREATE INDEX': create-index, *Note `DROP INDEX': drop-index, *Note `OPTIMIZE TABLE': optimize-table, and *Note `REPAIR TABLE': repair-table. * `--log-slow-queries[=FILE_NAME]' Options for log-slow-queries *Deprecated* 5.1.29, by slow-query-log *Command-Line `--log-slow-queries[=name]' Format* *Option-File Format* `log-slow-queries' *System Variable `log_slow_queries' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' This option enables logging to the slow query log, which contains entries for all queries that have taken more than `long_query_time' seconds to execute. See the descriptions of the `--log-long-format' and `--log-short-format' options for details. The log output destination can be selected with the `--log-output' option as of MySQL 5.1.6. Before 5.1.6, logging occurs to the slow query log file. If you omit the file name, MySQL uses `HOST_NAME-slow.log' as the file name. See *Note log-destinations::, and *Note slow-query-log::. As of MySQL 5.1.29, the `--log-slow-queries' option is deprecated and is removed (along with the `log_slow_queries' system variable) in MySQL 5.6. Instead, use the `--slow_query_log' option to enable the slow query log and the `--slow_query_log_file=FILE_NAME' option to set the slow query log file name. * `--log-tc=FILE_NAME' Options for log-tc *Command-Line `--log-tc=name' Format* *Option-File Format* `log-tc' *Permitted Values* *Type* `file name' *Default* `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. Currently, this option is unused. * `--log-tc-size=SIZE' Options for log-tc-size *Command-Line `--log-tc-size=#' Format* *Option-File Format* `log-tc-size' *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `24576' *Max Value* `4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `24576' *Max Value* `18446744073709547520' The size in bytes of the memory-mapped transaction coordinator log. The default size is 24KB. * `--log-warnings[=LEVEL]', `-W [LEVEL]' Options for log-warnings *Command-Line `--log-warnings[=#]' Format* `-W [#]' *Option-File Format* `log-warnings[=#]' *System Variable `log_warnings' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `1' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `1' *Range* `0 .. 18446744073709547520' Print out warnings such as `Aborted connection...' to the error log. This option is enabled (1) by default. To disable it, use `--log-warnings=0'. Specifying the option without a LEVEL value increments the current value by 1. Enabling this option by setting it greater than 0 is recommended, for example, if you use replication (you get more information about what is happening, such as messages about network failures and reconnections). If the value is greater than 1, aborted connections are written to the error log. See *Note communication-errors::. If a slave server was 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. As of MySQL 5.1.38, the server logs messages about statements that are unsafe for statement-based logging if `--log-warnings' is greater than 0. * `--low-priority-updates' Options for low-priority-updates *Command-Line `--low-priority-updates' Format* *Option-File Format* `low-priority-updates' *System Variable `low_priority_updates' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `FALSE' Give table-modifying operations (*Note `INSERT': insert, *Note `REPLACE': replace, *Note `DELETE': delete, *Note `UPDATE': 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 *Note table-locking::. * `--min-examined-row-limit=NUMBER' Options for min-examined-row-limit *Introduced* 5.1.21 *Command-Line `--min-examined-row-limit=#' Format* *Option-File Format* `min-examined-row-limit' *System Variable `min_examined_row_limit' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `0' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `0' *Range* `0 .. 18446744073709547520' When this option is set, queries which examine fewer than NUMBER rows are not written to the slow query log. The default is 0. This option was introduced in MySQL 5.1.21. * `--memlock' Options for memlock *Command-Line `--memlock' Format* *Option-File Format* `memlock' *System Variable `locked_in_memory' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `FALSE' Lock the *Note `mysqld': mysqld. process in memory. This option might help if you have a problem where the operating system is causing *Note `mysqld': 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 newer 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 *Note 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 *Note 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, *Note `mysqld': mysqld. will very likely crash as soon as you try to start it. * `--myisam-block-size=N' Options for myisam-block-size *Command-Line `--myisam-block-size=#' Format* *Option-File Format* `myisam-block-size' *Permitted Values* *Type* `numeric' *Default* `1024' *Range* `1024 .. 16384' The block size to be used for `MyISAM' index pages. * `--myisam-recover[=OPTION[,OPTION]...]]' Options for myisam-recover *Command-Line `--myisam-recover[=name]' Format* *Option-File Format* `myisam-recover' *Permitted Values* *Type* `enumeration' *Default* `OFF' *Valid Values* `DEFAULT' `BACKUP' `FORCE' `QUICK' Set the `MyISAM' storage engine recovery mode. The option value is any combination of the values of `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 not giving the option). If recovery is enabled, each time *Note `mysqld': 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, *Note `mysqld': mysqld. runs a check on the table. If the table was corrupted, *Note `mysqld': mysqld. attempts to repair it. The following options affect how the repair works. This table describes `--myisam-recover' options. Option Description `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 *Note myisam-start::. * `--old-alter-table' Options for old-alter-table *Command-Line `--old-alter-table' Format* *Option-File Format* `old-alter-table' *System Variable `old_alter_table' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' When this option is given, the server does not use the optimized method of processing an *Note `ALTER TABLE': 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 *Note `ALTER TABLE': alter-table, see *Note alter-table::. * `--old-style-user-limits' Options for old-style-user-limits *Command-Line `--old-style-user-limits' Format* *Option-File Format* `old-style-user-limits' *Permitted Values* *Type* `boolean' *Default* `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 *Note user-resources::. * `--one-thread' Options for one-thread *Command-Line `--one-thread' Format* *Option-File Format* `one-thread' Only use one thread (for debugging under Linux). This option is available only if the server is built with debugging enabled. See *Note porting::. As of MySQL 5.1.17, this option is deprecated and is removed in MySQL 5.6. Use `--thread_handling=no-threads' instead. * `--open-files-limit=COUNT' Options for open-files-limit *Command-Line `--open-files-limit=#' Format* *Option-File Format* `open-files-limit' *System Variable `open_files_limit' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 65535' Changes the number of file descriptors available to *Note `mysqld': mysqld. You should try increasing the value of this option if *Note `mysqld': mysqld. gives you the error `Too many open files'. *Note `mysqld': mysqld. uses the option value to reserve descriptors with `setrlimit()'. If the requested number of file descriptors cannot be allocated, *Note `mysqld': mysqld. writes a warning to the error log. *Note `mysqld': 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 less than `ulimit -n'. * `--partition[=VALUE]' Options for partition *Command-Line `--partition' Format* *Option-File Format* `partition' *Disabled by* `skip-partition' *Permitted Values* *Type* `boolean' *Default* `ON' Enables or disables user-defined partitioning support in the MySQL Server. * `--pid-file=PATH' Options for pid-file *Command-Line `--pid-file=file_name' Format* *Option-File Format* `pid-file' *System Variable `pid_file' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *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. This file is used by other programs such as *Note `mysqld_safe': mysqld-safe. to determine the server's process ID. * `--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 *Note 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' Options for plugin-load *Introduced* 5.1.18 *Command-Line `--plugin-load=plugin_list' Format* *Option-File Format* `plugin-load' *Permitted Values* *Type* `string' This option tells the server to load the named plugins at startup. The option value is a semicolon-separated list of `NAME=PLUGIN_LIBRARY' pairs. Each NAME is the name of the plugin, and PLUGIN_LIBRARY is the name of the shared library that contains the plugin code. Each library file must be located 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 load them at startup: shell> `mysqld --plugin-load="myplug1=myplug1.so;myplug2=myplug2.so"' Quotes are used around the argument value here because semicolon (`;') is interpreted as a special character by some command interpreters. (Unix shells treat it as a command terminator, for example.) All plugins to load must be named in the same `--plugin-load' option. If multiple `--plugin-load' options are given, only the last one is used. If a plugin library is named without any preceding plugin name, the server loads all plugins in the library. Each plugin is loaded for a single invocation of *Note `mysqld': mysqld. only. After a restart, the plugin is not loaded unless `--plugin-load' is used again. This is in contrast to *Note `INSTALL PLUGIN': 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 under configurations when plugins cannot be loaded at runtime. For additional information about plugin loading, see *Note server-plugin-loading::. This option was added in MySQL 5.1.18. * `--port=PORT_NUM', `-P PORT_NUM' Options for port *Command-Line `--port=#' Format* `-P' *Option-File Format* `port' *System Variable `port' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `3306' *Range* `0 .. 65535' The port number to 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. * `--port-open-timeout=NUM' Options for port-open-timeout *Introduced* 5.1.5 *Command-Line `--port-open-timeout=#' Format* *Option-File Format* `port-open-timeout' *Permitted Values* *Type* `numeric' *Default* `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. This option was added in MySQL 5.1.5. * `--remove [SERVICE_NAME]' Options for remove *Command-Line `--remove Format* [service_name]' (Windows only) Remove a MySQL Windows service. The default service name is `MySQL' if no SERVICE_NAME value is given. For more information, see *Note windows-start-service::. * `--safe-mode' Options for safe-mode *Command-Line `--safe-mode' Format* *Option-File Format* `safe-mode' Skip some optimization stages. This option is deprecated and is removed in MySQL 5.6. * `--safe-show-database' Options for safe-show-database *Deprecated* 4.0.2 *Command-Line `--safe-show-database' Format* *Option-File Format* `safe-show-database' *System Variable `safe_show_database' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' This option is deprecated and does not do anything because there is a *Note `SHOW DATABASES': show-databases. privilege that can be used to control access to database names on a per-account basis. See *Note privileges-provided::. `--safe-show-database' is removed in MySQL 5.5. * `--safe-user-create' Options for safe-user-create *Command-Line `--safe-user-create' Format* *Option-File Format* `safe-user-create' *Permitted Values* *Type* `boolean' *Default* `FALSE' If this option is enabled, a user cannot create new MySQL users by using the *Note `GRANT': 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 *Note `GRANT': grant. statement to give privileges to other users. * `--secure-auth' Options for secure-auth *Command-Line `--secure-auth' Format* *Option-File Format* `secure-auth' *System Variable `secure_auth' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' 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). Server startup fails with an error if this option is enabled and the privilege tables are in pre-4.1 format. See *Note old-client::. The *Note `mysql': 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. * `--secure-file-priv=PATH' Options for secure-file-priv *Introduced* 5.1.17 *Command-Line `--secure-file-priv=path' Format* *Option-File Format* `secure-file-priv' *System Variable `secure_file_priv' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' This option limits the effect of the `LOAD_FILE()' function and the *Note `LOAD DATA': load-data. and *Note `SELECT ... INTO OUTFILE': select-into. statements to work only with files in the specified directory. This option was added in MySQL 5.1.17. * `--shared-memory' Options for shared_memory *System Variable `shared_memory' Name* *Variable Scope* Global *Dynamic Variable* No *Platform Specific* windows Enable shared-memory connections by local clients. This option is available only on Windows. * `--shared-memory-base-name=NAME' Options for shared_memory_base_name *System Variable `shared_memory_base_name' Name* *Variable Scope* Global *Dynamic Variable* No *Platform Specific* windows 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 *Note concurrent-inserts::. * `--skip-event-scheduler' Options for skip-event-scheduler *Command-Line `--skip-event-scheduler' Format* `--disable-event-scheduler' *Option-File Format* `skip-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 *Note `mysqladmin flush-privileges': mysqladmin. or *Note `mysqladmin reload': mysqladmin. command from a system shell, or by issuing a MySQL *Note `FLUSH PRIVILEGES': flush. statement after connecting to the server. This option also suppresses loading of plugins that were installed with the *Note `INSTALL PLUGIN': install-plugin. statement, user-defined functions (UDFs), and, beginning with MySQL 5.1.17, scheduled events. To cause plugins to be loaded anyway, use the `--plugin-load' option. Note that *Note `FLUSH PRIVILEGES': flush. might be executed implicitly by other actions performed after startup. For example, *Note `mysql_upgrade': mysql-upgrade. flushes the privileges during the upgrade procedure. `--skip-grant-tables' is unavailable if MySQL was configured with the `--disable-grant-options' option. See *Note source-configuration-options::. * `--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 *Note host-cache::. * `--skip-innodb' Disable the `InnoDB' storage engine. In this case, the server will not start if the default storage engine is set to *Note `InnoDB': innodb-storage-engine. Use `--default-storage-engine' to set the default to some other engine if necessary. * `--skip-merge' Disable the `MERGE' storage engine. This option was added in MySQL 5.1.12 and removed in 5.1.14. * `--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 or `localhost'. See *Note host-cache::. * `--skip-networking' Do not listen for TCP/IP connections at all. All interaction with *Note `mysqld': 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 *Note host-cache::. * `--skip-partition' Options for skip-partition *Command-Line `--skip-partition' Format* `--disable-partition' *Option-File Format* `skip-partition' Disables user-defined partitioning. Partitioned tables can be seen using *Note `SHOW TABLES': show-tables. or by querying the *Note `INFORMATION_SCHEMA.TABLES': tables-table. table, but cannot be created or modified, nor can data in such tables be accessed. All partition-specific columns in the *Note `INFORMATION_SCHEMA.PARTITIONS': partitions-table. table display `NULL'. Since *Note `DROP TABLE': 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 `.par' files associated with partitioned tables in such cases. For this reason, you should avoid dropping partitioned tables with partitioning disabled, or take action to remove the orphaned `.par' files manually. * `--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 *Note ssl-options::. * `--standalone' Options for standalone *Command-Line `--standalone' Format* *Option-File Format* `standalone' *Platform Specific* windows Available on Windows only; instructs the MySQL server not to run as a service. * `--symbolic-links', `--skip-symbolic-links' Options for symbolic-links *Command-Line `--symbolic-links' Format* *Option-File Format* `symbolic-links' Enable or disable symbolic link support. This option has different effects on Windows and Unix: * On Windows, enabling symbolic links enables you to establish a symbolic link to a database directory by creating a `DB_NAME.sym' file that contains the path to the real directory. See *Note windows-symbolic-links::. * 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 *Note `CREATE TABLE': create-table. statement. If you delete or rename the table, the files that its symbolic links point to also are deleted or renamed. See *Note symbolic-links-to-tables::. * `--skip-safemalloc' Options for skip-safemalloc *Command-Line `--skip-safemalloc' Format* *Option-File Format* `skip-safemalloc' If MySQL is configured with `--with-debug=full', all MySQL programs check for memory overruns during each memory allocation and memory freeing operation. This checking is very slow, so for the server you can avoid it when you do not need it by using the `--skip-safemalloc' option. * `--skip-show-database' Options for skip-show-database *Command-Line `--skip-show-database' Format* *Option-File Format* `skip-show-database' *System Variable `skip_show_database' Name* *Variable Scope* Global *Dynamic Variable* No This option sets the `skip_show_database' system variable that controls who is permitted to use the *Note `SHOW DATABASES': show-databases. statement. See *Note server-system-variables::. * `--skip-stack-trace' Options for skip-stack-trace *Command-Line `--skip-stack-trace' Format* *Option-File Format* `skip-stack-trace' Do not write stack traces. This option is useful when you are running *Note `mysqld': mysqld. under a debugger. On some systems, you also must use this option to get a core file. See *Note porting::. * `--skip-thread-priority' Options for skip-thread-priority *Deprecated* 5.1.29 *Command-Line `--skip-thread-priority' Format* *Option-File Format* `skip-thread-priority' Disable using thread priorities for faster response time. This option is deprecated as of MySQL 5.1.29 and is removed in MySQL 5.6. Prior to MySQL 5.1.29, *Note `mysqld': mysqld. makes a large number of invalid calls to thread scheduling routines on Linux. These calls do not affect performance noticeably but may be a source of `noise' for debugging tools. For example, they can overwhelm other information of more interest in kernel logs. To avoid these calls, start the server with the `--skip-thread-priority' option. * `--slow-query-log[={0|1}]' Options for slow-query-log *Introduced* 5.1.12 *Command-Line `--slow-query-log'from Format* 5.1.29 *Option-File Format* `slow-query-log'from 5.1.29 *System Variable `slow_query_log' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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. This option was added in MySQL 5.1.12. * `--socket=PATH' Options for socket *Command-Line `--socket=name' Format* *Option-File Format* `socket' *System Variable `socket' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' *Default* `/tmp/mysql.sock' 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...]]' Options for sql-mode *Command-Line `--sql-mode=name' Format* *Option-File Format* `sql-mode' *System Variable `sql_mode' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `set' *Default* `''' *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 *Note server-sql-mode::. *Note*: MySQL installation programs may configure the SQL mode during the installation process. 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' Options for sysdate-is-now *Introduced* 5.1.8 *Command-Line `--sysdate-is-now' Format* *Option-File Format* `sysdate-is-now' *Permitted Values* *Type* `boolean' *Default* `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 *Note date-and-time-functions:: and for `SET TIMESTAMP' in *Note server-system-variables::. This option was added in MySQL 5.1.8. * `--tc-heuristic-recover={COMMIT|ROLLBACK}' Options for tc-heuristic-recover *Command-Line `--tc-heuristic-recover=name' Format* *Option-File Format* `tc-heuristic-recover' *Permitted Values* *Type* `enumeration' *Valid Values* `COMMIT' `RECOVER' The type of decision to use in the heuristic recovery process. Currently, this option is unused. * `--temp-pool' Options for temp-pool *Command-Line `--temp-pool' Format* *Option-File Format* `temp-pool' *Permitted Values* *Type* `boolean' *Default* `TRUE' This option 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.1.31, this option is ignored except on Linux. * `--transaction-isolation=LEVEL' Options for transaction-isolation *Command-Line `--transaction-isolation=name' Format* *Option-File Format* `transaction-isolation' *Permitted Values* *Type* `enumeration' *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 *Note set-transaction::. The default transaction isolation level can also be set at runtime using the *Note `SET TRANSACTION': set-transaction. statement or by setting the `tx_isolation' system variable. * `--tmpdir=PATH', `-t PATH' Options for tmpdir *Command-Line `--tmpdir=path' Format* `-t' *Option-File Format* `tmpdir' *System Variable `tmpdir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file 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, NetWare, and OS/2. 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 *Note temporary-files::. A replication slave needs some of its temporary files to survive a machine restart so that it can replicate temporary tables or *Note `LOAD DATA INFILE': load-data. 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}' Options for user *Command-Line `--user=name' Format* `-u name' *Option-File Format* `user' *Permitted Values* *Type* `string' Run the *Note `mysqld': 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 *Note `mysqld': 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 *Note 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'), *Note `mysqld': 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. You can assign a value to a server system variable by using an option of the form `--VAR_NAME=VALUE'. For example, `--key_buffer_size=32M' sets the `key_buffer_size' variable to a value of 32MB. Note that 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. If you want to restrict the maximum value to which a variable can be set at runtime with *Note `SET': set-statement, you can define this by using the `--maximum-VAR_NAME=VALUE' command-line option. You can change the values of most system variables for a running server with the *Note `SET': set-statement. statement. See *Note set-statement::. *Note server-system-variables::, provides a full description for all variables, and additional information for setting them at server startup and runtime. *Note server-parameters::, includes information on optimizing the server by tuning system variables.  File: manual.info, Node: server-system-variables, Next: using-system-variables, Prev: server-options, Up: mysqld-server 5.1.4 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 while the server is running by means of the *Note `SET': set-statement. statement, which enables you to modify operation of the server without having to stop and restart it. You can refer to system variable values in expressions. 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 *Note `SHOW VARIABLES': show-variables. statement. This section provides a description of each system variable. Variables with no version indicated are present in all MySQL 5.1 releases. For historical information concerning their implementation, please see `http://dev.mysql.com/doc/refman/5.0/en/', and `http://dev.mysql.com/doc/refman/4.1/en/'. The following table lists all available system variables. *System Variable Summary* Name Cmd-Line Option file System Var Var Scope Dynamic auto_increment_increment Yes Both Yes auto_increment_offset Yes Both Yes autocommit Yes Yes Yes Session Yes automatic_sp_privileges Yes Global Yes back_log Yes Global No basedir Yes Yes Yes Global No big-tables Yes Yes Yes - _Variable_: Yes Session Yes big_tables bind-address Yes Yes Yes Global No binlog_cache_sizeYes Yes Yes Global Yes binlog_direct_non_transactional_updatesYes Yes Yes Both Yes binlog-format Yes Yes Yes - _Variable_: Yes Both Yes binlog_format 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 This option is dynamic, but only the server should set this information. You should not set the value of this variable manually. character-set-filesystemYes Yes Yes - _Variable_: Yes Both Yes character_set_filesystem character_set_results Yes Both Yes character-set-serverYes Yes Yes - _Variable_: Yes Both Yes character_set_server character_set_system Yes Global No character-sets-dirYes Yes No - _Variable_: Yes Global No character_sets_dir collation_connection Yes Both Yes collation_database Yes Both Yes This option is dynamic, but only the server should set this information. You should not set the value of this variable manually. collation-serverYes Yes Yes - _Variable_: Yes Both Yes collation_server completion_typeYes Yes Yes Both Yes concurrent_insertYes Yes Yes Global Yes connect_timeoutYes Yes Yes Global Yes datadir Yes Yes Yes Global No date_format Yes Both No datetime_format Yes Both No debug Yes Yes Yes Both Yes debug_sync Yes Both Yes default-storage-engineYes Yes Yes Both Yes default_week_formatYes Yes Yes Both Yes delay-key-writeYes Yes Yes - _Variable_: Yes Global Yes delay_key_write delayed_insert_limitYes Yes Yes Global Yes delayed_insert_timeoutYes Yes Yes Global Yes delayed_queue_sizeYes Yes Yes Global Yes div_precision_incrementYes Yes Yes Both Yes engine-condition-pushdownYes Yes Yes - _Variable_: Yes Both Yes engine_condition_pushdown error_count Yes Session No event-schedulerYes Yes Yes - _Variable_: Yes Global Yes event_scheduler expire_logs_daysYes Yes Yes Global Yes flush Yes Yes Yes Global Yes flush_time Yes Yes Yes Global Yes foreign_key_checks Yes Session 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_limitYes Yes Yes Global No ft_stopword_fileYes Yes Yes Global No general-log Yes Yes Yes - _Variable_: Yes Global Yes general_log general_log_fileYes Yes Yes Global Yes group_concat_max_lenYes Yes Yes Both Yes have_archive Yes Global No have_blackhole_engine Yes Global No have_community_features Yes Global No have_compress Yes Global No have_crypt Yes Global No have_csv Yes Global No have_dynamic_loading Yes Global No have_example_engine Yes Global No have_federated_engine Yes Global No have_geometry Yes Global No have_innodb Yes Global No have_isam Yes Global No have_merge_engine Yes Global No have_ndbcluster Yes Global No have_openssl Yes Global No have_partition_engine Yes Global No have_partitioning Yes Global No have_query_cache Yes Global No have_raid Yes Global No have_row_based_replication Yes Global No have_rtree_keys Yes Global No have_ssl Yes Global No have_symlink Yes Global No hostname Yes Global No identity Yes Session Yes ignore-builtin-innodbYes Yes No - _Variable_: Yes Global No ignore_builtin_innodb init_connect Yes Yes Yes Global Yes init-file Yes Yes No - _Variable_: Yes Global No init_file init_slave Yes Yes Yes Global Yes innodb_adaptive_flushingYes Yes Yes Global Yes innodb_adaptive_hash_indexYes Yes Yes Global No innodb_additional_mem_pool_sizeYes Yes Yes Global No innodb_autoextend_incrementYes Yes Yes Global Yes innodb_autoinc_lock_modeYes Yes Yes Global No innodb_buffer_pool_awe_mem_mbYes Yes Yes Global No innodb_buffer_pool_sizeYes Yes Yes Global No innodb_change_bufferingYes Yes Yes Global Yes innodb_checksumsYes Yes Yes Global No innodb_commit_concurrencyYes Yes Yes Global Yes innodb_concurrency_ticketsYes Yes Yes Global Yes innodb_data_file_pathYes Yes Yes Global No innodb_data_home_dirYes Yes Yes Global No innodb_doublewriteYes Yes Yes Global No innodb_fast_shutdownYes Yes Yes Global Yes innodb_file_formatYes Yes Yes Global Yes innodb_file_format_checkYes Yes Yes Global Yes innodb_file_io_threadsYes Yes Yes Global No innodb_file_per_tableYes Yes Yes Global No innodb_flush_log_at_trx_commitYes Yes Yes Global Yes innodb_flush_methodYes Yes Yes Global No innodb_force_recoveryYes Yes Yes Global No innodb_io_capacityYes Yes Yes Global No innodb_lock_wait_timeoutYes Yes Yes Both Yes innodb_locks_unsafe_for_binlogYes Yes Yes Global No innodb_log_arch_dirYes Yes Yes Global No innodb_log_archiveYes Yes Yes Global No innodb_log_buffer_sizeYes Yes Yes Global No innodb_log_file_sizeYes Yes Yes Global No innodb_log_files_in_groupYes Yes Yes Global No innodb_log_group_home_dirYes Yes Yes Global No innodb_max_dirty_pages_pctYes Yes Yes Global Yes innodb_max_purge_lagYes Yes Yes Global Yes innodb_mirrored_log_groupsYes Yes Yes Global No innodb_old_blocks_pctYes Yes Yes Global Yes innodb_old_blocks_timeYes Yes Yes Global Yes innodb_open_filesYes Yes Yes Global No innodb_random_read_aheadYes Yes Yes Global Yes innodb_read_ahead_thresholdYes Yes Yes Global Yes innodb_read_io_threadsYes Yes Yes Global No innodb_replication_delayYes Yes Yes Global Yes innodb_rollback_on_timeoutYes Yes Yes Global No innodb_spin_wait_delayYes Yes Yes Global Yes innodb_stats_methodYes Yes Yes Global Yes innodb_stats_on_metadataYes Yes Yes Global Yes innodb_stats_sample_pagesYes Yes Yes Global Yes innodb_strict_modeYes Yes Yes Both Yes innodb_support_xaYes Yes Yes Both Yes innodb_sync_spin_loopsYes Yes Yes Global Yes innodb_table_locksYes Yes Yes Both Yes innodb_thread_concurrencyYes Yes Yes Global Yes innodb_thread_sleep_delayYes Yes Yes Global Yes innodb_use_legacy_cardinality_algorithmYes Yes Yes Global Yes 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 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_limitYes Yes 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 - _Variable_: Yes Global No large_pages last_insert_id Yes Session Yes lc_time_names Yes Both Yes license Yes Global No local_infile Yes Global Yes locked_in_memory Yes Global No log Yes Yes Yes Global Yes log_bin Yes Global No log-bin Yes Yes Yes Global No log-bin-trust-function-creatorsYes Yes Yes - _Variable_: Yes Global Yes log_bin_trust_function_creators log-bin-trust-routine-creatorsYes Yes Yes - _Variable_: Yes Global Yes log_bin_trust_routine_creators (http://dev.mysql.com/doc/refman/5.0/en/server-system-variables.html#sysvar_log_bin_trust_routine_creators) log_bin_use_v1_row_eventsYes Yes Yes Global No log-bin-use-v1-row-eventsYes Yes No - _Variable_: Yes Global No log_bin_use_v1_row_events log-error Yes Yes No - _Variable_: Yes Global No log_error log-output Yes Yes Yes - _Variable_: Yes Global Yes log_output log-queries-not-using-indexesYes Yes Yes - _Variable_: Yes Global Yes log_queries_not_using_indexes log-slave-updatesYes Yes No - _Variable_: Yes Global No log_slave_updates log_slave_updatesYes Yes Yes Global No log-slow-queriesYes Yes Yes - _Variable_: Yes Global Yes log_slow_queries log-warnings Yes Yes Yes - _Variable_: Yes Both Yes log_warnings long_query_timeYes Yes Yes Both Yes low-priority-updatesYes Yes Yes - _Variable_: Yes Both Yes low_priority_updates lower_case_file_system Yes Global No lower_case_table_namesYes Yes Yes Global No max_allowed_packetYes Yes Yes Global Yes max_binlog_cache_sizeYes Yes Yes Global Yes max_binlog_sizeYes Yes Yes Global Yes max_connect_errorsYes Yes Yes Global Yes max_connectionsYes Yes Yes Global Yes max_delayed_threadsYes Yes Yes Both Yes max_error_countYes 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_dataYes Yes Yes Both Yes max_long_data_sizeYes Yes Yes Global No 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_user_connectionsYes Yes Yes Both Yes max_write_lock_countYes Yes Yes Global Yes memlock Yes Yes Yes Global No min-examined-row-limitYes Yes Yes Both Yes multi_range_countYes Yes Yes Both Yes myisam_data_pointer_sizeYes Yes Yes Global Yes myisam_max_sort_file_sizeYes Yes 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 named_pipe Yes Global No ndb_autoincrement_prefetch_szYes Yes Yes Both Yes ndb-batch-size Yes Yes Yes Global No ndb-blob-read-batch-bytesYes Yes Yes Both Yes ndb-blob-write-batch-bytesYes Yes Yes Both Yes ndb_cache_check_timeYes Yes Yes Global Yes ndb-cluster-connection-poolYes Yes Yes Global No ndb-deferred-constraintsYes Yes Yes - _Variable_: Yes Both Yes ndb_deferred_constraints ndb_deferred_constraintsYes Yes Yes Both Yes ndb_distributionYes Yes Yes Both Yes ndb-distributionYes Yes Yes - _Variable_: Yes Both Yes ndb_distribution ndb_extra_loggingYes Yes Yes Global Yes ndb_force_send Yes Yes Yes Both Yes ndb_join_pushdown Yes Global No ndb-log-apply-statusYes Yes No - _Variable_: Yes Global No ndb_log_apply_status 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-orig Yes Yes No - _Variable_: Yes Global No ndb_log_orig ndb-log-transaction-idYes Yes No - _Variable_: Yes Global No ndb_log_transaction_id ndb_log_transaction_id Yes Global No ndb-log-update-as-writeYes Yes Yes Global Yes ndb_log_updated_onlyYes Yes Yes Global Yes ndb_optimization_delay Yes Global Yes 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-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_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 old Yes Yes Yes Global No old-alter-tableYes Yes Yes - _Variable_: Yes Both Yes old_alter_table old_passwords Yes Both Yes open-files-limitYes Yes No - _Variable_: Yes Global No open_files_limit optimizer_prune_levelYes Yes Yes Both Yes optimizer_search_depthYes Yes Yes Both Yes optimizer_switchYes Yes Yes Both Yes pid-file Yes Yes No - _Variable_: Yes Global No pid_file plugin_dir Yes Yes Yes Global No port Yes Yes Yes Global No preload_buffer_sizeYes Yes Yes Both Yes prepared_stmt_count Yes Global No profiling Yes Session Yes profiling_history_sizeYes Yes Yes Both Yes protocol_version Yes Global No 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_unitYes Yes Yes Global Yes query_cache_sizeYes Yes Yes Global Yes query_cache_typeYes Yes Yes Both Yes query_cache_wlock_invalidateYes Yes 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 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 - _Variable_: Yes Global No relay_log relay-log-indexYes Yes No - _Variable_: Yes Global No relay_log_index relay_log_indexYes Yes Yes Global No relay_log_info_fileYes Yes Yes Global No relay_log_purgeYes Yes Yes Global Yes relay_log_space_limitYes Yes Yes Global No report-host Yes Yes No - _Variable_: Yes Global No report_host report-passwordYes Yes No - _Variable_: Yes Global No report_password report-port Yes Yes No - _Variable_: Yes Global No report_port report-user Yes Yes No - _Variable_: Yes Global No report_user rpl_recovery_rank Yes Global Yes safe-show-databaseYes Yes Yes Global Yes secure-auth Yes Yes Yes - _Variable_: Yes Global Yes secure_auth secure-file-privYes Yes No - _Variable_: Yes Global No secure_file_priv server-id Yes Yes Yes - _Variable_: Yes Global Yes server_id server-id-bits Yes Yes No - _Variable_: Yes Global No server_id_bits shared_memory Yes Global No shared_memory_base_name Yes Global No skip_external_lockingYes Yes Yes Global No skip-name-resolveYes Yes No - _Variable_: Yes Global No skip_name_resolve skip-networkingYes Yes No - _Variable_: Yes Global No skip_networking skip-show-databaseYes Yes No - _Variable_: Yes Global No skip_show_database slave_allow_batchingYes Yes Yes Global Yes slave_compressed_protocolYes Yes Yes Global Yes slave_exec_modeYes Yes Yes Global Yes slave-load-tmpdirYes Yes No - _Variable_: Yes Global No slave_load_tmpdir slave_max_allowed_packet Yes Global Yes slave-net-timeoutYes Yes Yes - _Variable_: Yes Global Yes slave_net_timeout slave-skip-errorsYes Yes No - _Variable_: Yes Global No slave_skip_errors slave_transaction_retriesYes Yes Yes Global Yes slave_type_conversionsYes Yes Yes Global No slow_launch_timeYes Yes Yes Global Yes slow-query-log Yes Yes Yes - _Variable_: Yes Global Yes 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 Session Yes sql_big_selects Yes Session Yes sql_big_tables Yes Session Yes sql_buffer_result Yes Session Yes sql_log_bin Yes Session Yes sql_log_off Yes Session Yes sql_log_update Yes Session Yes sql_low_priority_updates Yes Both Yes sql_max_join_size Yes Both Yes sql-mode Yes Yes Yes - _Variable_: Yes Both Yes sql_mode sql_notes Yes Session Yes sql_quote_show_create Yes Session Yes sql_safe_updates Yes Session Yes sql_select_limit Yes Both Yes sql_slave_skip_counter Yes Global Yes sql_warnings Yes Session Yes ssl-ca Yes Yes No - _Variable_: Yes Global No ssl_ca ssl-capath Yes Yes No - _Variable_: Yes Global No ssl_capath ssl-cert Yes Yes No - _Variable_: Yes Global No ssl_cert ssl-cipher Yes Yes No - _Variable_: Yes Global No ssl_cipher ssl-key Yes Yes No - _Variable_: Yes Global No ssl_key storage_engine Yes Both Yes sync_binlog Yes Yes Yes Global Yes sync_frm Yes Yes Yes Global Yes system_time_zone Yes Global No table_cache Yes Yes Yes Global Yes table_definition_cache Yes Global Yes table_lock_wait_timeoutYes Yes Yes Global Yes table_open_cache Yes Global Yes table_type Yes Both Yes thread_cache_sizeYes Yes Yes Global Yes thread_concurrencyYes Yes Yes Global No thread_handlingYes Yes Yes Global No thread_stack Yes Yes Yes Global No time_format Yes Both No time_zone Yes Both Yes timed_mutexes Yes Yes Yes Global Yes timestamp Yes Session Yes tmp_table_size Yes Yes Yes Both Yes tmpdir Yes Yes Yes Global No transaction_alloc_block_sizeYes Yes Yes Both Yes transaction_allow_batching Yes Session Yes transaction_prealloc_sizeYes Yes Yes Both Yes tx_isolation Yes Both Yes unique_checks Yes Session Yes updatable_views_with_limitYes Yes Yes Both Yes version Yes Global No version_comment Yes Global No version_compile_machine Yes Global No version_compile_os Yes Global No wait_timeout Yes Yes Yes Both Yes warning_count Yes Session No For additional system variable information, see these sections: * *Note using-system-variables::, discusses the syntax for setting and displaying system variable values. * *Note dynamic-system-variables::, lists the variables that can be set at runtime. * Information on tuning system variables can be found in *Note server-parameters::. * *Note innodb-parameters::, lists `InnoDB' system variables. * *Note mysql-cluster-system-variables::, lists system variables which are specific to MySQL Cluster. * For information on server system variables specific to replication, see *Note replication-options::. *Note*: Some of the following variable descriptions refer to `enabling' or `disabling' a variable. These variables can be enabled with the *Note `SET': set-statement. 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. 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. * `autocommit' Options for autocommit *System Variable `autocommit' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `ON' The autocommit mode. If set to 1, all changes to a table take effect immediately. If set to 0, you must use *Note `COMMIT': commit. to accept a transaction or *Note `ROLLBACK': commit. to cancel it. If `autocommit' is 0 and you change it to 1, MySQL performs an automatic *Note `COMMIT': commit. of any open transaction. Another way to begin a transaction is to use a *Note `START TRANSACTION': commit. or *Note `BEGIN': commit. statement. See *Note commit::. By default, client connections begin with `autocommit' set to 1. To cause clients to begin with a default of 0, set the server's `init_connect' system variable: 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' The content of `init_connect' is not executed for users that have the `SUPER' privilege. * `automatic_sp_privileges' Options for automatic_sp_privileges *System Variable `automatic_sp_privileges' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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 *Note stored-routines-privileges::. * `back_log' Options for back_log *System Variable `back_log' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `50' *Range* `1 .. 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. * `basedir' Options for basedir *Command-Line `--basedir=path' Format* `-b' *Option-File Format* `basedir' *System Variable `basedir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The MySQL installation base directory. This variable can be set with the `--basedir' option. Relative path names for other variables usually are resolved relative to the base directory. * `big_tables' 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 *Note `SELECT': 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. *Note*: This variable was formerly named `sql_big_tables'. * `bulk_insert_buffer_size' Options for bulk_insert_buffer_size *Command-Line `--bulk_insert_buffer_size=#' Format* *Option-File Format* `bulk_insert_buffer_size' *System Variable `bulk_insert_buffer_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `8388608' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `8388608' *Range* `0 .. 18446744073709547520' `MyISAM' uses a special tree-like cache to make bulk inserts faster for *Note `INSERT ... SELECT': insert-select, `INSERT ... VALUES (...), (...), ...', and *Note `LOAD DATA INFILE': load-data. 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' Options for character_set_client *System Variable `character_set_client' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *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 *Note 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. * *Note `mysqld': 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' cannot be used as a client character set, which means that it also does not work for `SET NAMES' or `SET CHARACTER SET'. * `character_set_connection' Options for character_set_connection *System Variable `character_set_connection' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' The character set for the current connection. Used for literals that do not have an explicit character set specification and for number-to-string conversion. * `character_set_database' Options for character_set_database *System Variable `character_set_database' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Footnote* This option is dynamic, but only the server should set this information. You should not set the value of this variable manually. *Permitted Values* *Type* `string' 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'. * `character_set_filesystem' Options for character-set-filesystem *Introduced* 5.1.6 *Command-Line `--character-set-filesystem=name' Format* *Option-File Format* `character-set-filesystem' *System Variable `character_set_filesystem' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' The file system character set. This variable is used to interpret string literals that refer to file names, such as in the *Note `LOAD DATA INFILE': load-data. and *Note `SELECT ... INTO OUTFILE': select-into. 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 multi-byte 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''. This variable was added in MySQL 5.1.6. * `character_set_results' Options for character_set_results *System Variable `character_set_results' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' The character set used for returning query results such as result sets or error messages to the client. * `character_set_server' Options for character-set-server *Command-Line `--character-set-server' Format* *Option-File Format* `character-set-server' *System Variable `character_set_server' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' The server's default character set. * `character_set_system' Options for character_set_system *System Variable `character_set_system' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' The character set used by the server for storing identifiers. The value is always `utf8'. * `character_sets_dir' Options for character-sets-dir *Command-Line `--character-sets-dir=path' Format* *Option-File Format* `character-sets-dir' *System Variable `character_sets_dir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `directory name' The directory where character sets are installed. * `collation_connection' Options for collation_connection *System Variable `collation_connection' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' The collation of the connection character set. * `collation_database' Options for collation_database *System Variable `collation_database' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Footnote* This option is dynamic, but only the server should set this information. You should not set the value of this variable manually. *Permitted Values* *Type* `string' 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'. * `collation_server' Options for collation-server *Command-Line `--collation-server' Format* *Option-File Format* `collation-server' *System Variable `collation_server' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' The server's default collation. * `completion_type' Options for completion_type *Command-Line `--completion_type=#' Format* *Option-File Format* `completion_type' *System Variable `completion_type' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Valid Values* `0' `1' `2' The transaction completion type. This variable can take the values shown in the following table. This table describes values that may be specified for the `completion_type' system variable. Value Description 0 *Note `COMMIT': commit. and *Note `ROLLBACK': commit. are unaffected. This is the default value. 1 *Note `COMMIT': commit. and *Note `ROLLBACK': commit. are equivalent to `COMMIT AND CHAIN' and `ROLLBACK AND CHAIN', respectively. (A new transaction starts immediately with the same isolation level as the just-terminated transaction.) 2 *Note `COMMIT': commit. and *Note `ROLLBACK': commit. are equivalent to `COMMIT RELEASE' and `ROLLBACK RELEASE', respectively. (The server disconnects after terminating the transaction.) `completion_type' affects transactions that begin with *Note `START TRANSACTION': commit. or *Note `BEGIN': commit. and end with *Note `COMMIT': commit. or *Note `ROLLBACK': commit. It does not apply to implicit commits resulting from execution of the statements listed in *Note implicit-commit::. It also does not apply for *Note `XA COMMIT': xa-statements, *Note `XA ROLLBACK': xa-statements, or when `autocommit=1'. * `concurrent_insert' Options for concurrent_insert *Command-Line `--concurrent_insert[=#]' Format* *Option-File Format* `concurrent_insert' *System Variable `concurrent_insert' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `TRUE' If 1 (the default), MySQL permits *Note `INSERT': insert. and *Note `SELECT': select. statements to run concurrently for `MyISAM' tables that have no free blocks in the middle of the data file. If you start *Note `mysqld': mysqld. with `--skip-new', this variable is set to 0. This variable can take three integer values. This table describes values that may be specified for the `concurrent_insert' system variable. Value Description 0 Disables concurrent inserts 1 (Default) Enables concurrent insert for `MyISAM' tables that do not have holes 2 Enables concurrent inserts for all `MyISAM' tables, even those that have holes. For a table with a 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 *Note concurrent-inserts::. * `connect_timeout' Options for connect_timeout *Command-Line `--connect_timeout=#' Format* *Option-File Format* `connect_timeout' *System Variable `connect_timeout' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values (<= 5.1.22)* *Type* `numeric' *Default* `5' *Permitted Values (>= 5.1.23)* *Type* `numeric' *Default* `10' The number of seconds that the *Note `mysqld': mysqld. server waits for a connect packet before responding with `Bad handshake'. The default value is 10 seconds as of MySQL 5.1.23 and 5 seconds before that. 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'. * `datadir' Options for datadir *Command-Line `--datadir=path' Format* `-h' *Option-File Format* `datadir' *System Variable `datadir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The MySQL data directory. This variable can be set with the `--datadir' option. * `date_format' This variable is unused. * `datetime_format' This variable is unused. * `debug' Options for debug *Command-Line `--debug[=debug_options]' Format* *Option-File Format* `debug' *System Variable `debug' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' *Default* `'d:t: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 | +---------+ This variable was added in MySQL 5.1.7. * `debug_sync' Options for debug_sync *Introduced* 5.1.41 *System Variable `debug_sync' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' This variable is the user interface to the Debug Sync facility. Use of Debug Sync requires that MySQL be configured with the `--enable-debug-sync' option (see *Note 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). This variable was added in MySQL 5.1.41. * `default_week_format' Options for default_week_format *Command-Line `--default_week_format=#' Format* *Option-File Format* `default_week_format' *System Variable `default_week_format' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 7' The default mode value to use for the `WEEK()' function. See *Note date-and-time-functions::. * `delay_key_write' Options for delay-key-write *Command-Line `--delay-key-write[=name]' Format* *Option-File Format* `delay-key-write' *System Variable `delay_key_write' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `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 *Note `CREATE TABLE': create-table. statements. This table describes options that may be specified for the `delay_key_write' system variable. Option Description `OFF' `DELAY_KEY_WRITE' is ignored. `ON' MySQL honors any `DELAY_KEY_WRITE' option specified in *Note `CREATE TABLE': 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' option (for example, `--myisam-recover=BACKUP,FORCE'). See *Note server-options::, and *Note 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' Options for delayed_insert_limit *Command-Line `--delayed_insert_limit=#' Format* *Option-File Format* `delayed_insert_limit' *System Variable `delayed_insert_limit' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `100' *Range* `1 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `100' *Range* `1 .. 18446744073709547520' After inserting `delayed_insert_limit' delayed rows, the *Note `INSERT DELAYED': insert-delayed. handler thread checks whether there are any *Note `SELECT': select. statements pending. If so, it permits them to execute before continuing to insert delayed rows. * `delayed_insert_timeout' Options for delayed_insert_timeout *Command-Line `--delayed_insert_timeout=#' Format* *Option-File Format* `delayed_insert_timeout' *System Variable `delayed_insert_timeout' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `300' How many seconds an *Note `INSERT DELAYED': insert-delayed. handler thread should wait for *Note `INSERT': insert. statements before terminating. * `delayed_queue_size' Options for delayed_queue_size *Command-Line `--delayed_queue_size=#' Format* *Option-File Format* `delayed_queue_size' *System Variable `delayed_queue_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `1000' *Range* `1 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `1000' *Range* `1 .. 18446744073709547520' This is a per-table limit on the number of rows to queue when handling *Note `INSERT DELAYED': insert-delayed. statements. If the queue becomes full, any client that issues an *Note `INSERT DELAYED': insert-delayed. statement waits until there is room in the queue again. * `div_precision_increment' Options for div_precision_increment *Command-Line `--div_precision_increment=#' Format* *Option-File Format* `div_precision_increment' *System Variable `div_precision_increment' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `4' *Range* `0 .. 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 | +----------------+ For more information, see *Note dbug-package::. * `engine_condition_pushdown' Options for engine-condition-pushdown *Command-Line `--engine-condition-pushdown' Format* *Option-File Format* `engine-condition-pushdown' *System Variable `engine_condition_pushdown' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `ON' The engine condition pushdown optimization enables processing for certain comparisons to be `pushed down' to the storage engine level for more efficient execution. For more information, see *Note condition-pushdown-optimization::. Engine condition pushdown is used only by the *Note `NDBCLUSTER': mysql-cluster. storage engine. Enabling this optimization on a MySQL Server acting as a MySQL Cluster SQL node causes `WHERE' conditions on unindexed columns to be evaluated on the cluster's data nodes and only the rows that match to be sent back to the SQL node that issued the query. This greatly reduces the amount of cluster data that must be sent over the network, increasing the efficiency with which results are returned. The `engine_condition_pushdown' variable controls whether engine condition pushdown is enabled. By default, this variable is `ON' (1). Setting it to `OFF' (0) disables pushdown. * `error_count' The number of errors that resulted from the last statement that generated messages. This variable is read only. See *Note show-errors::. * `event_scheduler' Options for event-scheduler *Introduced* 5.1.6 *Command-Line `--event-scheduler[=value]' Format* *Option-File Format* `event-scheduler' *System Variable `event_scheduler' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `OFF' *Valid Values* `ON' `OFF' `DISABLED' This variable indicates the status of the Event Scheduler; as of MySQL 5.1.12, 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. This variable was added in MySQL 5.1.6. * `expire_logs_days' Options for expire_logs_days *Command-Line `--expire_logs_days=#' Format* *Option-File Format* `expire_logs_days' *System Variable `expire_logs_days' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 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 *Note server-logs::. To remove binary log files manually, use the *Note `PURGE BINARY LOGS': purge-binary-logs. statement. See *Note purge-binary-logs::. * `flush' Options for flush *Command-Line `--flush' Format* *Option-File Format* `flush' *System Variable `flush' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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 *Note crashing::. This variable is set to `ON' if you start *Note `mysqld': mysqld. with the `--flush' option. * `flush_time' Options for flush_time *Command-Line `--flush_time=#' Format* *Option-File Format* `flush_time' *System Variable `flush_time' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Min 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. * `foreign_key_checks' If set to 1 (the default), foreign key constraints for `InnoDB' tables are checked. If set to 0, they are ignored. Disabling foreign key checking can be useful for reloading `InnoDB' tables in an order different from that required by their parent/child relationships. See *Note innodb-foreign-key-constraints::. Setting `foreign_key_checks' to 0 also affects data definition statements: *Note `DROP SCHEMA': drop-database. drops a schema even if it contains tables that have foreign keys that are referred to by tables outside the schema, and *Note `DROP TABLE': 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. * `ft_boolean_syntax' Options for ft_boolean_syntax *Command-Line `--ft_boolean_syntax=name' Format* *Option-File Format* `ft_boolean_syntax' *System Variable `ft_boolean_syntax' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `string' *Default* `+ -><()~*:""&|' The list of operators supported by boolean full-text searches performed using `IN BOOLEAN MODE'. See *Note 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' Options for ft_max_word_len *Command-Line `--ft_max_word_len=#' Format* *Option-File Format* `ft_max_word_len' *System Variable `ft_max_word_len' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Min Value* `10' The maximum length of the word to be included in a `FULLTEXT' index. *Note*: `FULLTEXT' indexes must be rebuilt after changing this variable. Use `REPAIR TABLE TBL_NAME QUICK'. * `ft_min_word_len' Options for ft_min_word_len *Command-Line `--ft_min_word_len=#' Format* *Option-File Format* `ft_min_word_len' *System Variable `ft_min_word_len' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `4' *Min Value* `1' The minimum length of the word to be included in a `FULLTEXT' index. *Note*: `FULLTEXT' indexes must be rebuilt after changing this variable. Use `REPAIR TABLE TBL_NAME QUICK'. * `ft_query_expansion_limit' Options for ft_query_expansion_limit *Command-Line `--ft_query_expansion_limit=#' Format* *Option-File Format* `ft_query_expansion_limit' *System Variable `ft_query_expansion_limit' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `20' *Range* `0 .. 1000' The number of top matches to use for full-text searches performed using `WITH QUERY EXPANSION'. * `ft_stopword_file' Options for ft_stopword_file *Command-Line `--ft_stopword_file=file_name' Format* *Option-File Format* `ft_stopword_file' *System Variable `ft_stopword_file' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The file from which to read the list of stopwords for full-text searches. 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 *Note fulltext-stopwords::. *Note*: `FULLTEXT' indexes must be rebuilt after changing this variable or the contents of the stopword file. Use `REPAIR TABLE TBL_NAME QUICK'. * `general_log' Options for general-log *Introduced* 5.1.12 *Command-Line `--general-log' Format* *Option-File Format* `general-log' *System Variable `general_log' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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 (`--log' before MySQL 5.1.29). 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. The `general_log' variable was added in MySQL 5.1.12. * `general_log_file' Options for general_log_file *Introduced* 5.1.12 *Command-Line `--general-log-file=file_name'from Format* 5.1.29 *Option-File Format* `general_log_file'from 5.1.29 *System Variable `general_log_file' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `file name' *Default* `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 (`--log' before MySQL 5.1.29). This variable was added in MySQL 5.1.12. * `group_concat_max_len' Options for group_concat_max_len *Command-Line `--group_concat_max_len=#' Format* *Option-File Format* `group_concat_max_len' *System Variable `group_concat_max_len' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `1024' *Range* `4 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `1024' *Range* `4 .. 18446744073709547520' The maximum permitted result length in bytes for the `GROUP_CONCAT()' function. The default is 1024. * `have_archive' `YES' if *Note `mysqld': mysqld. supports `ARCHIVE' tables, `NO' if not. This variable was removed in MySQL 5.1.14. * `have_blackhole_engine' `YES' if *Note `mysqld': mysqld. supports `BLACKHOLE' tables, `NO' if not. This variable was removed in MySQL 5.1.14. * `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_community_features' `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 *Note show-profiles::. This variable was added in MySQL 5.1.24. It is renamed to `have_profiling' in MySQL 5.5. * `have_crypt' `YES' if the `crypt()' system call is available to the server, `NO' if not. If not, the `ENCRYPT()' function cannot be used. * `have_csv' `YES' if *Note `mysqld': mysqld. supports `CSV' tables, `NO' if not. This variable is deprecated and is removed in MySQL 5.6. Use *Note `SHOW PLUGINS': show-plugins. instead. For more information, see *Note partitioning::. * `have_dynamic_loading' `YES' if *Note `mysqld': mysqld. supports dynamic loading of plugins, `NO' if not. This variable was added in MySQL 5.1.10. * `have_example_engine' `YES' if *Note `mysqld': mysqld. supports `EXAMPLE' tables, `NO' if not. This variable was removed in MySQL 5.1.14. * `have_federated_engine' `YES' if *Note `mysqld': mysqld. supports `FEDERATED' tables, `NO' if not. This variable was removed in MySQL 5.1.14. * `have_geometry' `YES' if the server supports spatial data types, `NO' if not. * `have_innodb' `YES' if *Note `mysqld': mysqld. supports `InnoDB' tables. `DISABLED' if `--skip-innodb' is used. This variable is deprecated and is removed in MySQL 5.6. Use *Note `SHOW ENGINES': show-engines. instead. * `have_isam' In MySQL 5.1, this variable appears only for reasons of backward compatibility. It is always `NO' because `ISAM' tables are no longer supported. This variable was removed in MySQL 5.1.7. * `have_merge_engine' `YES' if *Note `mysqld': mysqld. supports `MERGE' tables. `DISABLED' if `--skip-merge' is used. This variable was removed in MySQL 5.1.3. * `have_openssl' `YES' if *Note `mysqld': mysqld. supports SSL connections, `NO' if not. As of MySQL 5.1.17, this variable is an alias for `have_ssl'. * `have_partitioning' `YES' if *Note `mysqld': mysqld. supports partitioning. Added in MySQL 5.1.1 as `have_partition_engine' and renamed to `have_partioning' in 5.1.6. This variable is deprecated and is removed in MySQL 5.6. Use *Note `SHOW ENGINES': show-engines. instead. * `have_query_cache' `YES' if *Note `mysqld': mysqld. supports the query cache, `NO' if not. * `have_row_based_replication' Options for have_row_based_replication *Introduced* 5.1.5 *Removed* 5.1.15 *System Variable `have_row_based_replication' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' `YES' if the server can perform replication using row-based binary logging. If the value is `NO', the server can use only statement-based logging. See *Note replication-formats::. This variable was added in MySQL 5.1.5 and removed in 5.1.15. * `have_raid' In MySQL 5.1, this variable appears only for reasons of backward compatibility. It is always `NO' because `RAID' tables are no longer supported. This variable was removed in MySQL 5.1.7. * `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 *Note `mysqld': mysqld. supports SSL connections, `NO' if not. `DISABLED' indicates that the server was compiled with SSL support, but but was not started with the appropriate `--ssl-XXX' options. For more information, see *Note configuring-for-ssl::. This variable was added in MySQL 5.1.17. Before that, use `have_openssl'. * `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, and on Windows for support of data directory symlinks. If the server is started with the `--skip-symbolic-links' option, the value is `DISABLED'. * `hostname' Options for hostname *Introduced* 5.1.17 *System Variable `hostname' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' The server sets this variable to the server host name at startup. This variable was added in MySQL 5.1.17. * `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'. * `init_connect' Options for init_connect *Command-Line `--init-connect=name' Format* *Option-File Format* `init_connect' *System Variable `init_connect' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *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. There is no global `autocommit' system variable to specify that autocommit should be disabled by default, but `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' The content of `init_connect' is not executed for users that have the `SUPER' privilege. 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. * `init_file' Options for init-file *Command-Line `--init-file=file_name' Format* *Option-File Format* `init-file' *System Variable `init_file' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *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. No statement terminator such as `;', `\g', or `\G' should be given at the end of each statement. Note that the `--init-file' option is unavailable if MySQL was configured with the `--disable-grant-options' option. See *Note source-configuration-options::. * `innodb_XXX' *Note `InnoDB': innodb-storage-engine. system variables are listed in *Note innodb-parameters::. These variables control many aspects of storage, memory use, and I/O patterns for `InnoDB' tables, and are especially important in MySQL 5.5 and higher, where InnoDB is the default storage engine (http://dev.mysql.com/doc/refman/5.5/en/innodb-default-se.html). * `insert_id' The value to be used by the following *Note `INSERT': insert. or *Note `ALTER TABLE': alter-table. statement when inserting an `AUTO_INCREMENT' value. This is mainly used with the binary log. * `interactive_timeout' Options for interactive_timeout *Command-Line `--interactive_timeout=#' Format* *Option-File Format* `interactive_timeout' *System Variable `interactive_timeout' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `28800' *Min 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 *Note `mysql_real_connect()': mysql-real-connect. See also `wait_timeout'. * `join_buffer_size' Options for join_buffer_size *Command-Line `--join_buffer_size=#' Format* *Option-File Format* `join_buffer_size' *System Variable `join_buffer_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `131072' *Range* `8200 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `131072' *Range* `8228 .. 18446744073709547520' 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. 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. The maximum permissible setting for `join_buffer_size' is 4GB. As of MySQL 5.1.23, values larger than 4GB are permitted for 64-bit platforms (except 64-bit Windows, for which large values are truncated to 4GB with a warning). For additional information about join buffering, see *Note nested-loop-joins::. * `keep_files_on_create' Options for keep_files_on_create *Introduced* 5.1.21 *Command-Line `--keep_files_on_create=#' Format* *Option-File Format* `keep_files_on_create' *System Variable `keep_files_on_create' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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. This variable was added in MySQL 5.1.23. * `key_buffer_size' Options for key_buffer_size *Command-Line `--key_buffer_size=#' Format* *Option-File Format* `key_buffer_size' *System Variable `key_buffer_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values (<= 5.1.22)* *Type* `numeric' *Default* `8388608' *Range* `8 .. 4294967295' *Permitted Values (>= 5.1.23)* *Platform Bit Size* `32' *Type* `numeric' *Default* `8388608' *Range* `8 .. 4294967295' *Permitted Values (>= 5.1.23)* *Platform Bit Size* `64' *Type* `numeric' *Default* `8388608' *Range* `8 .. OS_PER_PROCESS_LIMIT' 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 on 32-bit platforms. As of MySQL 5.1.23, values larger than 4GB are permitted for 64-bit platforms, except 64-bit Windows prior to MySQL 5.1.31, for which large values are truncated to 4GB with a warning. As of MySQL 5.1.31, values larger than 4GB are also permitted for 64-bit Windows. 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 *Note `MyISAM': myisam-storage-engine. 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 *Note `MyISAM': myisam-storage-engine. For even more speed when writing many rows at the same time, use *Note `LOCK TABLES': lock-tables. See *Note insert-speed::. You can check the performance of the key buffer by issuing a *Note `SHOW STATUS': show-status. statement and examining the `Key_read_requests', `Key_reads', `Key_write_requests', and `Key_writes' status variables. (See *Note 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 *Note myisam-key-cache::. * `key_cache_age_threshold' Options for key_cache_age_threshold *Command-Line `--key_cache_age_threshold=#' Format* *Option-File Format* `key_cache_age_threshold' *System Variable `key_cache_age_threshold' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `300' *Range* `100 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `300' *Range* `100 .. 18446744073709547520' 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 *Note myisam-key-cache::. * `key_cache_block_size' Options for key_cache_block_size *Command-Line `--key_cache_block_size=#' Format* *Option-File Format* `key_cache_block_size' *System Variable `key_cache_block_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `1024' *Range* `512 .. 16384' The size in bytes of blocks in the key cache. The default value is 1024. See *Note myisam-key-cache::. * `key_cache_division_limit' Options for key_cache_division_limit *Command-Line `--key_cache_division_limit=#' Format* *Option-File Format* `key_cache_division_limit' *System Variable `key_cache_division_limit' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `100' *Range* `1 .. 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 *Note myisam-key-cache::. * `language' Options for language *Command-Line `--language=name' Format* `-L' *Option-File Format* `language' *System Variable `language' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `directory name' *Default* `/usr/local/mysql/share/mysql/english/' The directory where error messages are located. See *Note error-message-language::. * `large_files_support' Options for large_files_support *System Variable `large_files_support' Name* *Variable Scope* Global *Dynamic Variable* No Whether *Note `mysqld': mysqld. was compiled with options for large file support. * `large_pages' Options for large-pages *Command-Line `--large-pages' Format* *Option-File Format* `large-pages' *System Variable `large_pages' Name* *Variable Scope* Global *Dynamic Variable* No *Platform Specific* linux *Permitted Values* *Type* (linux) `boolean' *Default* `FALSE' Whether large page support is enabled (via the `--large-pages' option). See *Note large-page-support::. * `large_page_size' Options for large_page_size *System Variable `large_page_size' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* (linux) `numeric' *Default* `0' If large page support is enabled, this shows the size of memory pages. Currently, large memory pages are supported only on Linux; on other platforms, the value of this variable is always 0. See *Note 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 *Note `mysql_insert_id()': mysql-insert-id. C API function. * `lc_time_names' Options for lc_time_names *Introduced* 5.1.12 *System Variable `lc_time_names' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *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 *Note locale-support::. This variable was added in MySQL 5.1.12. * `license' Options for license *System Variable `license' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' *Default* `GPL' The type of license the server has. * `local_infile' Options for local_infile *System Variable `local_infile' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' Whether `LOCAL' is supported for *Note `LOAD DATA INFILE': load-data. statements. If this variable is disabled, clients cannot use `LOCAL' in *Note `LOAD DATA': load-data. statements. See *Note load-data-local::. * `locked_in_memory' Options for locked_in_memory *System Variable `locked_in_memory' Name* *Variable Scope* Global *Dynamic Variable* No Whether *Note `mysqld': mysqld. was locked in memory with `--memlock'. * `log' Options for log *Deprecated* 5.1.29, by general-log *Command-Line `--log[=name]' Format* `-l' *Option-File Format* `log' *System Variable `log' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `string' *Default* `OFF' Whether logging of all statements to the general query log is enabled. See *Note query-log::. This variable is deprecated as of MySQL 5.1.29 and is removed in MySQL 5.6. Use `general_log' instead. * `log_bin_trust_function_creators' Options for log-bin-trust-function-creators *Command-Line `--log-bin-trust-function-creators' Format* *Option-File Format* `log-bin-trust-function-creators' *System Variable `log_bin_trust_function_creators' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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 *Note stored-programs-logging::. * `log_error' Options for log-error *Command-Line `--log-error[=name]' Format* *Option-File Format* `log-error' *System Variable `log_error' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The location of the error log, or empty if the server is writing error message to the standard error output. See *Note error-log::. * `log_output' Options for log-output *Introduced* 5.1.6 *Command-Line `--log-output=name' Format* *Option-File Format* `log-output' *System Variable `log_output' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `set' *Default* `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 *Note log-destinations::. This variable was added in MySQL 5.1.6. * `log_queries_not_using_indexes' Options for log-queries-not-using-indexes *Command-Line `--log-queries-not-using-indexes' Format* *Option-File Format* `log-queries-not-using-indexes' *System Variable `log_queries_not_using_indexes' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' Whether queries that do not use indexes are logged to the slow query log. See *Note slow-query-log::. This variable was added in MySQL 5.1.11. * `log_slow_queries' Options for log-slow-queries *Deprecated* 5.1.29, by slow-query-log *Command-Line `--log-slow-queries[=name]' Format* *Option-File Format* `log-slow-queries' *System Variable `log_slow_queries' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' Whether slow queries should be logged. `Slow' is determined by the value of the `long_query_time' variable. See *Note slow-query-log::. This variable is deprecated as of MySQL 5.1.29 and is removed in MySQL 5.6. Use `slow_query_log' instead. * `log_warnings' Options for log-warnings *Command-Line `--log-warnings[=#]' Format* `-W [#]' *Option-File Format* `log-warnings[=#]' *System Variable `log_warnings' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `1' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `1' *Range* `0 .. 18446744073709547520' Whether to produce additional warning messages to the error log. This variable is enabled (1) by default and can be disabled by setting it to 0. As of MySQL 5.1.38, 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. * `long_query_time' Options for long_query_time *Command-Line `--long_query_time=#' Format* *Option-File Format* `long_query_time' *System Variable `long_query_time' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values (>= 5.1.21)* *Type* `numeric' *Default* `10' *Min 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 default value of `long_query_time' is 10. Beginning with MySQL 5.1.21, the minimum is 0, and 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. Prior to MySQL 5.1.21, the minimum value is 1, and the value for this variable must be an integer. See *Note slow-query-log::. * `low_priority_updates' Options for low-priority-updates *Command-Line `--low-priority-updates' Format* *Option-File Format* `low-priority-updates' *System Variable `low_priority_updates' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `FALSE' If set to `1', all *Note `INSERT': insert, *Note `UPDATE': update, *Note `DELETE': delete, and `LOCK TABLE WRITE' statements wait until there is no pending *Note `SELECT': 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'). This variable previously was named `sql_low_priority_updates'. * `lower_case_file_system' Options for lower_case_file_system *System Variable `lower_case_file_system' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *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' Options for lower_case_table_names *Command-Line `--lower_case_table_names[=#]' Format* *Option-File Format* `lower_case_table_names' *System Variable `lower_case_table_names' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 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 *Note identifier-case-sensitivity::. 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 Mac OS X). If you set this variable to 0 on such a system and access `MyISAM' tablenames using different lettercases, index corruption may result. On Windows the default value is 1. On Mac OS X, the default value is 2. If you are using `InnoDB' tables, you should set this variable to 1 on all platforms to force names to be converted to lowercase. Prior to MySQL Cluster NDB 6.3.35, MySQL Cluster NDB 7.0.15, and MySQL Cluster NDB 7.1.4, this is also true for tables using the `NDB' storage engine. The setting of this variable has no effect on replication filtering options. See *Note replication-rules::, for more information. You should not use different settings for `lower_case_table_names' on replication masters and slaves. In particular, you should not do this when the slave uses a case-sensitive file system, as this can cause replication to fail. For more information, see *Note replication-features-variables::. * `max_allowed_packet' Options for max_allowed_packet *Command-Line `--max_allowed_packet=#' Format* *Option-File Format* `max_allowed_packet' *System Variable `max_allowed_packet' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `1048576' *Range* `1024 .. 1073741824' The maximum size of one packet or any generated/intermediate string. 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 *Note `BLOB': blob. columns or long strings. It should be as big as the largest *Note `BLOB': 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, *Note `mysql': mysql. and *Note `mysqldump': 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. As of MySQL 5.1.31, the session value of this variable is read only. Before 5.1.31, setting the session value is permitted but has no effect. * `max_connect_errors' Options for max_connect_errors *Command-Line `--max_connect_errors=#' Format* *Option-File Format* `max_connect_errors' *System Variable `max_connect_errors' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `10' *Range* `1 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `10' *Range* `1 .. 18446744073709547520' 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 *Note `FLUSH HOSTS': flush. statement or execute a *Note `mysqladmin flush-hosts': mysqladmin. 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. * `max_connections' Options for max_connections *Command-Line `--max_connections=#' Format* *Option-File Format* `max_connections' *System Variable `max_connections' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values (<= 5.1.14)* *Type* `numeric' *Default* `100' *Permitted Values (>= 5.1.15)* *Type* `numeric' *Default* `151' *Range* `1 .. 16384' *Permitted Values (>= 5.1.17)* *Type* `numeric' *Default* `151' *Range* `1 .. 100000' The maximum permitted number of simultaneous client connections. By default, this is 151, beginning with MySQL 5.1.15. (Previously, the default was 100.) See *Note too-many-connections::, for more information. Increasing this value increases the number of file descriptors that *Note `mysqld': mysqld. requires. See *Note table-cache::, for comments on file descriptor limits. * `max_delayed_threads' Options for max_delayed_threads *Command-Line `--max_delayed_threads=#' Format* *Option-File Format* `max_delayed_threads' *System Variable `max_delayed_threads' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `20' *Range* `0 .. 16384' Do not start more than this number of threads to handle *Note `INSERT DELAYED': insert-delayed. statements. If you try to insert data into a new table after all *Note `INSERT DELAYED': insert-delayed. threads are in use, the row is inserted as if the `DELAYED' attribute was not specified. If you set this to 0, MySQL never creates a thread to handle `DELAYED' rows; in effect, this disables `DELAYED' entirely. For the `SESSION' value of this variable, the only valid values are 0 or the `GLOBAL' value. * `max_error_count' Options for max_error_count *Command-Line `--max_error_count=#' Format* *Option-File Format* `max_error_count' *System Variable `max_error_count' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `64' *Range* `0 .. 65535' The maximum number of error, warning, and note messages to be stored for display by the *Note `SHOW ERRORS': show-errors. and *Note `SHOW WARNINGS': show-warnings. statements. * `max_heap_table_size' Options for max_heap_table_size *Command-Line `--max_heap_table_size=#' Format* *Option-File Format* `max_heap_table_size' *System Variable `max_heap_table_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `16777216' *Range* `16384 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `16777216' *Range* `16384 .. 1844674407370954752' 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 *Note `CREATE TABLE': create-table. or altered with *Note `ALTER TABLE': alter-table. or *Note `TRUNCATE TABLE': 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 *Note internal-temporary-tables::. `max_heap_table_size' is not replicated. See *Note replication-features-memory::, and *Note replication-features-variables::, for more information. * `max_insert_delayed_threads' Options for max_insert_delayed_threads *System Variable `max_insert_delayed_threads' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' This variable is a synonym for `max_delayed_threads'. * `max_join_size' Options for max_join_size *Command-Line `--max_join_size=#' Format* *Option-File Format* `max_join_size' *System Variable `max_join_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `4294967295' *Range* `1 .. 4294967295' 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. This variable previously was named `sql_max_join_size'. * `max_length_for_sort_data' Options for max_length_for_sort_data *Command-Line `--max_length_for_sort_data=#' Format* *Option-File Format* `max_length_for_sort_data' *System Variable `max_length_for_sort_data' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `1024' *Range* `4 .. 8388608' The cutoff on the size of index values that determines which `filesort' algorithm to use. See *Note order-by-optimization::. * `max_long_data_size' Options for max_long_data_size *Introduced* 5.1.57 *Deprecated* 5.1.57 *Command-Line `--max_long_data_size=#' Format* *Option-File Format* `max_long_data_size' *System Variable `max_long_data_size' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `1048576' *Range* `1024 .. 4294967295' The maximum size of parameter values that can be sent with the *Note `mysql_stmt_send_long_data()': mysql-stmt-send-long-data. C API function. If not set at server startup, the default is the value of the `max_allowed_packet' system variable. This variable is deprecated. In MySQL 5.6, it is removed and the maximum parameter size is controlled by `max_allowed_packet'. * `max_prepared_stmt_count' Options for max_prepared_stmt_count *Introduced* 5.1.10 *Command-Line `--max_prepared_stmt_count=#' Format* *Option-File Format* `max_prepared_stmt_count' *System Variable `max_prepared_stmt_count' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `16382' *Range* `0 .. 1048576' This variable limits the total number of prepared statements in the server. (The sum of the number of prepared statements across all sessions.) 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. This variable was added in MySQL 5.1.10. * `max_relay_log_size' Options for max_relay_log_size *Command-Line `--max_relay_log_size=#' Format* *Option-File Format* `max_relay_log_size' *System Variable `max_relay_log_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 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 *Note replication-implementation-details::. * `max_seeks_for_key' Options for max_seeks_for_key *Command-Line `--max_seeks_for_key=#' Format* *Option-File Format* `max_seeks_for_key' *System Variable `max_seeks_for_key' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `4294967295' *Range* `1 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `18446744073709547520' *Range* `1 .. 18446744073709547520' 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 *Note 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' Options for max_sort_length *Command-Line `--max_sort_length=#' Format* *Option-File Format* `max_sort_length' *System Variable `max_sort_length' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `1024' *Range* `4 .. 8388608' The number of bytes to use when sorting data values. Only the first `max_sort_length' bytes of each value are used; the rest are ignored. * `max_sp_recursion_depth' Options for max_sp_recursion_depth *Command-Line `--max_sp_recursion_depth[=#]' Format* *Option-File Format* `max_sp_recursion_depth' *System Variable `max_sp_recursion_depth' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Max 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_tmp_tables' This variable is unused. * `max_user_connections' Options for max_user_connections *Command-Line `--max_user_connections=#' Format* *Option-File Format* `max_user_connections' *System Variable `max_user_connections' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 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 *Note `GRANT': grant. statement. See *Note user-resources::, and *Note grant::. * `max_write_lock_count' Options for max_write_lock_count *Command-Line `--max_write_lock_count=#' Format* *Option-File Format* `max_write_lock_count' *System Variable `max_write_lock_count' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `4294967295' *Range* `1 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `18446744073709547520' *Range* `1 .. 18446744073709547520' After this many write locks, permit some pending read lock requests to be processed in between. * `min_examined_row_limit' Options for min-examined-row-limit *Introduced* 5.1.21 *Command-Line `--min-examined-row-limit=#' Format* *Option-File Format* `min-examined-row-limit' *System Variable `min_examined_row_limit' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `0' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `0' *Range* `0 .. 18446744073709547520' Queries that examine fewer than this number of rows are not logged to the slow query log. This variable was added in MySQL 5.1.21. * `myisam_data_pointer_size' Options for myisam_data_pointer_size *Command-Line `--myisam_data_pointer_size=#' Format* *Option-File Format* `myisam_data_pointer_size' *System Variable `myisam_data_pointer_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `6' *Range* `2 .. 7' The default pointer size in bytes, to be used by *Note `CREATE TABLE': 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 *Note full-table::. * `myisam_max_sort_file_size' Options for myisam_max_sort_file_size *Command-Line `--myisam_max_sort_file_size=#' Format* *Option-File Format* `myisam_max_sort_file_size' *System Variable `myisam_max_sort_file_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `2147483648' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `9223372036854775807' The maximum size of the temporary file that MySQL is permitted to use while re-creating a `MyISAM' index (during *Note `REPAIR TABLE': repair-table, *Note `ALTER TABLE': alter-table, or *Note `LOAD DATA INFILE': load-data.). 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. The default value is 2GB. 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' Options for myisam_mmap_size *Introduced* 5.1.43 *Command-Line `--myisam_mmap_size=#' Format* *Option-File Format* `myisam_mmap_size' *System Variable `myisam_mmap_size' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `4294967295' *Range* `7 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `18446744073709547520' *Range* `7 .. 18446744073709547520' The maximum amount of memory to use for memory mapping compressed *Note `MyISAM': myisam-storage-engine. files. If many compressed `MyISAM' tables are used, the value can be decreased to reduce the likelihood of memory-swapping problems. This variable was added in MySQL 5.1.43. * `myisam_recover_options' Options for myisam_recover_options *System Variable `myisam_recover_options' Name* *Variable Scope* Global *Dynamic Variable* No The value of the `--myisam-recover' option. See *Note server-options::. * `myisam_repair_threads' Options for myisam_repair_threads *Command-Line `--myisam_repair_threads=#' Format* *Option-File Format* `myisam_repair_threads' *System Variable `myisam_repair_threads' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `1' *Range* `1 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `1' *Range* `1 .. 18446744073709547520' 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' Options for myisam_sort_buffer_size *Command-Line `--myisam_sort_buffer_size=#' Format* *Option-File Format* `myisam_sort_buffer_size' *System Variable `myisam_sort_buffer_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `8388608' *Range* `4096 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `8388608' *Range* `4096 .. 18446744073709547520' The size of the buffer that is allocated when sorting `MyISAM' indexes during a *Note `REPAIR TABLE': repair-table. or when creating indexes with *Note `CREATE INDEX': create-index. or *Note `ALTER TABLE': alter-table. The maximum permissible setting for `myisam_sort_buffer_size' is 4GB. As of MySQL 5.1.23, values larger than 4GB are permitted for 64-bit platforms (except 64-bit Windows, for which large values are truncated to 4GB with a warning). * `myisam_stats_method' Options for myisam_stats_method *Command-Line `--myisam_stats_method=name' Format* *Option-File Format* `myisam_stats_method' *System Variable `myisam_stats_method' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *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 *Note myisam-index-statistics::. Any unique prefix of a valid value may be used to set the value of this variable. * `myisam_use_mmap' Options for myisam_use_mmap *Introduced* 5.1.4 *Command-Line `--myisam_use_mmap' Format* *Option-File Format* `myisam_use_mmap' *System Variable `myisam_use_mmap' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' Use memory mapping for reading and writing `MyISAM' tables. This variable was added in MySQL 5.1.4. * `named_pipe' Options for named_pipe *System Variable `named_pipe' Name* *Variable Scope* Global *Dynamic Variable* No *Platform Specific* windows *Permitted Values* *Type* (windows) `boolean' *Default* `OFF' (Windows only.) Indicates whether the server supports connections over named pipes. * `net_buffer_length' Options for net_buffer_length *Command-Line `--net_buffer_length=#' Format* *Option-File Format* `net_buffer_length' *System Variable `net_buffer_length' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `16384' *Range* `1024 .. 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. As of MySQL 5.1.31, the session value of this variable is read only. Before 5.1.31, setting the session value is permitted but has no effect. * `net_read_timeout' Options for net_read_timeout *Command-Line `--net_read_timeout=#' Format* *Option-File Format* `net_read_timeout' *System Variable `net_read_timeout' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `30' *Min Value* `1' The number of seconds to wait for more data from a connection before aborting the read. Before MySQL 5.1.41, this timeout applies only to TCP/IP connections, not to connections made through Unix socket files, named pipes, or shared memory. 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'. On Linux, the `NO_ALARM' build flag affects timeout behavior as indicated in the description of the `net_retry_count' system variable. * `net_retry_count' Options for net_retry_count *Command-Line `--net_retry_count=#' Format* *Option-File Format* `net_retry_count' *System Variable `net_retry_count' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `10' *Range* `1 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `10' *Range* `1 .. 18446744073709547520' 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. On Linux, the `NO_ALARM' build flag (`-DNO_ALARM') modifies how the binary treats both `net_read_timeout' and `net_write_timeout'. With this flag enabled, neither timer cancels the current statement until after the failing connection has been waited on an additional `net_retry_count' times. This means that the effective timeout value becomes `(timeout setting) x (net_retry_count+1)'. * `net_write_timeout' Options for net_write_timeout *Command-Line `--net_write_timeout=#' Format* *Option-File Format* `net_write_timeout' *System Variable `net_write_timeout' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `60' *Min Value* `1' The number of seconds to wait for a block to be written to a connection before aborting the write. Before MySQL 5.1.41, this timeout applies only to TCP/IP connections, not to connections made using Unix socket files, named pipes, or shared memory. See also `net_read_timeout'. On Linux, the `NO_ALARM' build flag affects timeout behavior as indicated in the description of the `net_retry_count' system variable. * `new' Options for new *Command-Line `--new' Format* `-n' *Option-File Format* `new' *System Variable `new' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Disabled by* `skip-new' *Permitted Values* *Type* `boolean' *Default* `FALSE' This variable was used in MySQL 4.0 to turn on some 4.1 behaviors, and is retained for backward compatibility. In MySQL 5.1, its value is always `OFF'. * `old' Options for old *Introduced* 5.1.18 *Command-Line `--old' Format* *Option-File Format* `old' *System Variable `old' Name* *Variable Scope* Global *Dynamic Variable* 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. Currently, 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 *Note 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. This variable was added as `old_mode' in MySQL 5.1.17 and renamed to `old' in MySQL 5.1.18. * `old_alter_table' Options for old-alter-table *Command-Line `--old-alter-table' Format* *Option-File Format* `old-alter-table' *System Variable `old_alter_table' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' When this variable is enabled, the server does not use the optimized method of processing an *Note `ALTER TABLE': 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 *Note `ALTER TABLE': alter-table, see *Note alter-table::. * `old_passwords' Options for old_passwords *System Variable `old_passwords' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `0' This variable controls the password hashing method used by the `PASSWORD()' function and for the `IDENTIFIED BY' clause of the *Note `CREATE USER': create-user. and *Note `GRANT': grant. statements. The value determines whether or not to use `old' native MySQL password hashing. A value of 0 (or `OFF') causes passwords to be encrypted using the format available from MySQL 4.1 on. A value of 1 (or `ON') causes password encryption to use the older pre-4.1 format. If `old_passwords=1', `PASSWORD('STR')' returns the same value as `OLD_PASSWORD('STR')'. The latter function is not affected by the value of `old_passwords'. For information about hashing formats, see *Note password-hashing::. * `one_shot' This is not a variable, but it can be used when setting some variables. It is described in *Note set-statement::. * `open_files_limit' Options for open-files-limit *Command-Line `--open-files-limit=#' Format* *Option-File Format* `open-files-limit' *System Variable `open_files_limit' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 65535' The number of files that the operating system permits *Note `mysqld': mysqld. to open. This is the real value permitted by the system and might be different from the value you gave using the `--open-files-limit' option to *Note `mysqld': mysqld. or *Note `mysqld_safe': mysqld-safe. The value is 0 on systems where MySQL cannot change the number of open files. * `optimizer_prune_level' Options for optimizer_prune_level *Command-Line `--optimizer_prune_level[=#]' Format* *Option-File Format* `optimizer_prune_level' *System Variable `optimizer_prune_level' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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' Options for optimizer_search_depth *Command-Line `--optimizer_search_depth[=#]' Format* *Option-File Format* `optimizer_search_depth' *System Variable `optimizer_search_depth' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `62' *Range* `0 .. 63' 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. If set to 63, the optimizer switches to the algorithm used in MySQL 5.0.0 (and previous versions) for performing searches. The value of 63 is deprecated and will be treated as invalid in a future MySQL release. * `optimizer_switch' Options for optimizer_switch *Introduced* 5.1.34 *Command-Line `--optimizer_switch=value' Format* *Option-File Format* `optimizer_switch' *System Variable `optimizer_switch' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `set' *Valid Values* `index_merge={on|off}' `index_merge_intersection={on|off}' `index_merge_sort_union={on|off}' `index_merge_union={on|off}' The `optimizer_switch' system variable enables control over optimizer behaviors. 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 For more information about the syntax of this variable and the optimizer behaviors that it controls, see *Note switchable-optimizations::. * `pid_file' Options for pid-file *Command-Line `--pid-file=file_name' Format* *Option-File Format* `pid-file' *System Variable `pid_file' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The path name of the process ID (PID) file. This variable can be set with the `--pid-file' option. * `plugin_dir' Options for plugin_dir *Introduced* 5.1.2 *Command-Line `--plugin_dir=path' Format* *Option-File Format* `plugin_dir' *System Variable `plugin_dir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values (>= 5.1.2)* *Type* (windows) `directory name' *Default* `BASEDIR/lib/plugin' *Permitted Values (>= 5.1.2)* *Type* (other) `directory name' *Default* `BASEDIR/lib/mysql/plugin' The path name of the plugin directory. This variable was added in MySQL 5.1.2. 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 *Note `SELECT ... INTO DUMPFILE': select. This can be prevented by making `plugin_dir' read only to the server or by setting `--secure-file-priv' to a directory where *Note `SELECT': select. writes can be made safely. * `port' Options for port *Command-Line `--port=#' Format* `-P' *Option-File Format* `port' *System Variable `port' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `3306' *Range* `0 .. 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' Options for preload_buffer_size *Command-Line `--preload_buffer_size=#' Format* *Option-File Format* `preload_buffer_size' *System Variable `preload_buffer_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `32768' *Range* `1024 .. 1073741824' The size of the buffer that is allocated when preloading indexes. * `prepared_stmt_count' Options for prepared_stmt_count *Introduced* 5.1.10 *Removed* 5.1.13 *System Variable `prepared_stmt_count' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' The current number of prepared statements. (The maximum number of statements is given by the `max_prepared_stmt_count' system variable.) This variable was added in MySQL 5.1.10. In MySQL 5.1.14, it was converted to the global `Prepared_stmt_count' status variable. * `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 *Note `SHOW PROFILE': show-profile. and *Note `SHOW PROFILES': show-profiles. statements provide access to profiling information. See *Note show-profiles::. This variable was added in MySQL 5.1.24. * `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 *Note show-profiles::. This variable was added in MySQL 5.1.24. * `protocol_version' Options for protocol_version *System Variable `protocol_version' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' The version of the client/server protocol used by the MySQL server. * `pseudo_thread_id' Options for pseudo_thread_id *System Variable `pseudo_thread_id' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' This variable is for internal server use. * `query_alloc_block_size' Options for query_alloc_block_size *Command-Line `--query_alloc_block_size=#' Format* *Option-File Format* `query_alloc_block_size' *System Variable `query_alloc_block_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `8192' *Range* `1024 .. 4294967295' *Block Size* `1024' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `8192' *Range* `1024 .. 18446744073709547520' *Block Size* `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' Options for query_cache_limit *Command-Line `--query_cache_limit=#' Format* *Option-File Format* `query_cache_limit' *System Variable `query_cache_limit' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `1048576' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `1048576' *Range* `0 .. 18446744073709547520' Do not cache results that are larger than this number of bytes. The default value is 1MB. * `query_cache_min_res_unit' Options for query_cache_min_res_unit *Command-Line `--query_cache_min_res_unit=#' Format* *Option-File Format* `query_cache_min_res_unit' *System Variable `query_cache_min_res_unit' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `4096' *Range* `512 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `4096' *Range* `512 .. 18446744073709547520' 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 *Note query-cache-configuration::. * `query_cache_size' Options for query_cache_size *Command-Line `--query_cache_size=#' Format* *Option-File Format* `query_cache_size' *System Variable `query_cache_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `0' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `0' *Range* `0 .. 18446744073709547520' The amount of memory allocated for caching query results. The default value is 0, which disables the query cache. The permissible values are multiples of 1024; other values are rounded down to the nearest multiple. Note that `query_cache_size' bytes of memory are allocated even if `query_cache_type' is set to 0. See *Note 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 *Note query-cache-configuration::. * `query_cache_type' Options for query_cache_type *Command-Line `--query_cache_type=#' Format* *Option-File Format* `query_cache_type' *System Variable `query_cache_type' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `1' *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. This table describes options that may be specified for the `query_cache_type' system variable. Option Description `0' or Do not cache results in or retrieve results `OFF' from 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 `ON'. Any unique prefix of a valid value may be used to set the value of this variable. * `query_cache_wlock_invalidate' Options for query_cache_wlock_invalidate *Command-Line `--query_cache_wlock_invalidate' Format* *Option-File Format* `query_cache_wlock_invalidate' *System Variable `query_cache_wlock_invalidate' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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. * `query_prealloc_size' Options for query_prealloc_size *Command-Line `--query_prealloc_size=#' Format* *Option-File Format* `query_prealloc_size' *System Variable `query_prealloc_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `8192' *Range* `8192 .. 4294967295' *Block Size* `1024' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `8192' *Range* `8192 .. 18446744073709547520' *Block Size* `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. Beginning with MySQL 5.1.18, the variables--but not their values--are shown in the output of *Note `SHOW VARIABLES': 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' Options for range_alloc_block_size *Command-Line `--range_alloc_block_size=#' Format* *Option-File Format* `range_alloc_block_size' *System Variable `range_alloc_block_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `4096' *Range* `4096 .. 4294967295' *Block Size* `1024' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `4096' *Range* `4096 .. 18446744073709547520' *Block Size* `1024' The size of blocks that are allocated when doing range optimization. * `read_buffer_size' Options for read_buffer_size *Command-Line `--read_buffer_size=#' Format* *Option-File Format* `read_buffer_size' *System Variable `read_buffer_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `131072' *Range* `8200 .. 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 search 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 *Note `MEMORY': memory-storage-engine. tables. The maximum permissible setting for `read_buffer_size' is 2GB. For more information about memory use during different operations, see *Note memory-use::. * `read_only' Options for read_only *Command-Line `--read-only' Format* *Option-File Format* `read_only' *System Variable `read_only' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `false' This variable is off by default. When it is enabled, the server permits no updates except from users that have the `SUPER' privilege or (on a slave server) from updates performed by slave threads. 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. `read_only' does not apply to `TEMPORARY' tables, nor does it prevent the server from inserting rows into the log tables (see *Note log-destinations::). This variable does not prevent the use of *Note `ANALYZE TABLE': analyze-table. or *Note `OPTIMIZE TABLE': optimize-table. statements because its purpose 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 slaves can be performed with *Note `mysqlcheck --all-databases --analyze': mysqlcheck. `read_only' exists only as a `GLOBAL' variable, so changes to its value require the `SUPER' privilege. 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. *Important*: In MySQL 5.1, enabling `read_only' prevents the use of the *Note `SET PASSWORD': set-password. statement by any user not having the `SUPER' privilege. This is not necessarily the case for all MySQL release series. When replicating from one MySQL release series to another (for example, from a MySQL 5.0 master to a MySQL 5.1 or later slave), you should check the documentation for the versions running on both master and slave to determine whether the behavior of `read_only' in this regard is or is not the same, and, if it is different, whether this has an impact on your applications. As of MySQL 5.1.15, the following conditions apply: * If you attempt to enable `read_only' while you have any explicit locks (acquired with *Note `LOCK TABLES': lock-tables.) or have a pending transaction, an error occurs. * If you attempt to enable `read_only' while other clients hold explicit table locks or have pending transactions, the attempt blocks 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. * `read_only' can be enabled while you hold a global read lock (acquired with *Note `FLUSH TABLES WITH READ LOCK': flush.) because that does not involve table locks. * `read_rnd_buffer_size' Options for read_rnd_buffer_size *Command-Line `--read_rnd_buffer_size=#' Format* *Option-File Format* `read_rnd_buffer_size' *System Variable `read_rnd_buffer_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `262144' *Range* `8200 .. 4294967295' 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 *Note 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 *Note memory-use::. * `relay_log_purge' Options for relay_log_purge *Command-Line `--relay_log_purge' Format* *Option-File Format* `relay_log_purge' *System Variable `relay_log_purge' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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' Options for relay_log_space_limit *Command-Line `--relay_log_space_limit=#' Format* *Option-File Format* `relay_log_space_limit' *System Variable `relay_log_space_limit' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `0' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `0' *Range* `0 .. 18446744073709547520' The maximum amount of space to use for all relay logs. * `report_host' Options for report-host *Command-Line `--report-host=host_name' Format* *Option-File Format* `report-host' *System Variable `report_host' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' The value of the `--report-host' option. This variable was added in MySQL 5.1.24. * `report_password' Options for report-password *Command-Line `--report-password=name' Format* *Option-File Format* `report-password' *System Variable `report_password' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' The value of the `--report-password' option. Not the same as the password for the MySQL replication user account. This variable was added in MySQL 5.1.24. * `report_port' Options for report-port *Command-Line `--report-port=#' Format* *Option-File Format* `report-port' *System Variable `report_port' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `3306' *Range* `0 .. 65535' The value of the `--report-port' option. This variable was added in MySQL 5.1.24. * `report_user' Options for report-user *Command-Line `--report-user=name' Format* *Option-File Format* `report-user' *System Variable `report_user' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' The value of the `--report-user' option. This variable was added in MySQL 5.1.24. * `secure_auth' Options for secure-auth *Command-Line `--secure-auth' Format* *Option-File Format* `secure-auth' *System Variable `secure_auth' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' 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). Server startup fails with an error if this variable is enabled and the privilege tables are in pre-4.1 format. See *Note old-client::. * `secure_file_priv' Options for secure-file-priv *Introduced* 5.1.17 *Command-Line `--secure-file-priv=path' Format* *Option-File Format* `secure-file-priv' *System Variable `secure_file_priv' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' By default, this variable is empty. If set to the name of a directory, it limits the effect of the `LOAD_FILE()' function and the *Note `LOAD DATA': load-data. and *Note `SELECT ... INTO OUTFILE': select-into. statements to work only with files in that directory. This variable was added in MySQL 5.1.17. * `server_id' Options for server-id *Command-Line `--server-id=#' Format* *Option-File Format* `server-id' *System Variable `server_id' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 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. * `shared_memory' Options for shared_memory *System Variable `shared_memory' Name* *Variable Scope* Global *Dynamic Variable* No *Platform Specific* windows (Windows only.) Whether the server permits shared-memory connections. * `shared_memory_base_name' Options for shared_memory_base_name *System Variable `shared_memory_base_name' Name* *Variable Scope* Global *Dynamic Variable* No *Platform Specific* windows (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. * `skip_external_locking' Options for skip_external_locking *Command-Line `--skip-external-locking' Format* *Option-File Format* `skip_external_locking' *System Variable `skip_external_locking' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `ON' This is `OFF' if *Note `mysqld': mysqld. uses external locking (system locking), `ON' if external locking is disabled. This affects only *Note `MyISAM': myisam-storage-engine. table access. This variable is set by the `--external-locking' or `--skip-external-locking' option. External locking has been disabled by default as of MySQL 4.0. External locking affects only *Note `MyISAM': myisam-storage-engine. table access. For more information, including conditions under which it can and cannot be used, see *Note external-locking::. * `skip_name_resolve' Options for skip-name-resolve *Command-Line `--skip-name-resolve' Format* *Option-File Format* `skip-name-resolve' *System Variable `skip_name_resolve' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `OFF' This variable is set from the value of the `--skip-name-resolve' option. If it is `ON', *Note `mysqld': mysqld. resolves host names when checking client connections. If `OFF', *Note `mysqld': mysqld. uses only IP numbers and all `Host' column values in the grant tables must be IP addresses or `localhost'. See *Note host-cache::. This variable was added in MySQL 5.1.46. * `skip_networking' Options for skip-networking *Command-Line `--skip-networking' Format* *Option-File Format* `skip-networking' *System Variable `skip_networking' Name* *Variable Scope* Global *Dynamic Variable* 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. On NetWare, only TCP/IP connections are supported, so do not set this variable to `ON'. This variable can be set to `ON' with the `--skip-networking' option. * `skip_show_database' Options for skip-show-database *Command-Line `--skip-show-database' Format* *Option-File Format* `skip-show-database' *System Variable `skip_show_database' Name* *Variable Scope* Global *Dynamic Variable* No This prevents people from using the *Note `SHOW DATABASES': 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 *Note `SHOW DATABASES': 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', *Note `SHOW DATABASES': 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' Options for slow_launch_time *Command-Line `--slow_launch_time=#' Format* *Option-File Format* `slow_launch_time' *System Variable `slow_launch_time' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `2' If creating a thread takes longer than this many seconds, the server increments the `Slow_launch_threads' status variable. * `slow_query_log' Options for slow-query-log *Introduced* 5.1.12 *Command-Line `--slow-query-log'from Format* 5.1.29 *Option-File Format* `slow-query-log'from 5.1.29 *System Variable `slow_query_log' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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 (`--log-slow-queries' before MySQL 5.1.29). 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. The `slow_query_log' variable was added in MySQL 5.1.12. `Slow' is determined by the value of the `long_query_time' variable. See *Note slow-query-log::. * `slow_query_log_file' Options for slow_query_log_file *Introduced* 5.1.12 *Command-Line `--slow-query-log-file=file_name' Format* *Option-File Format* `slow_query_log_file' *System Variable `slow_query_log_file' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `file name' 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 (`--log-slow-queries' before MySQL 5.1.29). This variable was added in MySQL 5.1.12. * `socket' Options for socket *Command-Line `--socket=name' Format* *Option-File Format* `socket' *System Variable `socket' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' *Default* `/tmp/mysql.sock' 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' Options for sort_buffer_size *Command-Line `--sort_buffer_size=#' Format* *Option-File Format* `sort_buffer_size' *System Variable `sort_buffer_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `2097144' *Range* `32768 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `2097144' *Range* `32768 .. 18446744073709547520' Each session that needs to do 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. See *Note order-by-optimization::, for example. If you see many `Sort_merge_passes' per second in *Note `SHOW GLOBAL STATUS': show-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 entire buffer is allocated even if it is not all needed, so 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 *Note temporary-files::. The maximum permissible setting for `sort_buffer_size' is 4GB. As of MySQL 5.1.23, values larger than 4GB are permitted for 64-bit platforms (except 64-bit Windows, for which large values are truncated to 4GB with a warning). * `sql_auto_is_null' Options for sql_auto_is_null *System Variable `sql_auto_is_null' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `1' If this variable is set to 1 (the default), 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 *Note information-functions::. If no `AUTO_INCREMENT' value was successfully inserted, the *Note `SELECT': 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 *Note connector-odbc-usagenotes-functionality-last-insert-id::. This behavior can be disabled by setting `sql_auto_is_null' to 0. * `sql_big_selects' Options for sql_big_selects *System Variable `sql_big_selects' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `1' If set to 0, MySQL aborts *Note `SELECT': 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 *Note `SELECT': 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' Options for sql_buffer_result *System Variable `sql_buffer_result' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `0' If set to 1, `sql_buffer_result' forces results from *Note `SELECT': 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' Options for sql_log_bin *System Variable `sql_log_bin' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' If set to 0, no logging is done to the binary log for the client. The client must have the `SUPER' privilege to set this option. The default value is 1. * `sql_log_off' Options for sql_log_off *System Variable `sql_log_off' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `0' If set to 1, no logging is done to the general query log for this client. The client must have the `SUPER' privilege to set this option. The default value is 0. * `sql_log_update' Options for sql_log_update *Deprecated* 5.0.0, by sql_log_bin *System Variable `sql_log_update' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' This variable is deprecated, and is mapped to `sql_log_bin'. It is removed in MySQL 5.5. * `sql_mode' Options for sql-mode *Command-Line `--sql-mode=name' Format* *Option-File Format* `sql-mode' *System Variable `sql_mode' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `set' *Default* `''' *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. See *Note server-sql-mode::. *Note*: MySQL installation programs may configure the SQL mode during the installation process. 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. *Note `mysqldump': 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 *Note `SHOW CREATE TABLE': show-create-table. and *Note `SHOW CREATE DATABASE': 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 *Note show-create-table::, and *Note show-create-database::. * `sql_safe_updates' If set to 1, MySQL aborts *Note `UPDATE': update. or *Note `DELETE': delete. statements that do not use a key in the `WHERE' clause or a `LIMIT' clause. This makes it possible to catch *Note `UPDATE': update. or *Note `DELETE': 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' Options for sql_select_limit *System Variable `sql_select_limit' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' The maximum number of rows to return from *Note `SELECT': select. statements. The default value for a new connection is the maximum number of rows that the server permits per table, which depends on the server configuration and may be affected if the server build was configured with `--with-big-tables'. 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 *Note `SELECT': select. has a `LIMIT' clause, the `LIMIT' takes precedence over the value of `sql_select_limit'. * `sql_warnings' This variable controls whether single-row *Note `INSERT': 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' Options for ssl-ca *Introduced* 5.1.11 *Command-Line `--ssl-ca=name' Format* *Option-File Format* `ssl-ca' *System Variable `ssl_ca' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The path to a file with a list of trusted SSL CAs. This variable was added in MySQL 5.1.11. * `ssl_capath' Options for ssl-capath *Introduced* 5.1.11 *Command-Line `--ssl-capath=name' Format* *Option-File Format* `ssl-capath' *System Variable `ssl_capath' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `directory name' The path to a directory that contains trusted SSL CA certificates in PEM format. This variable was added in MySQL 5.1.11. * `ssl_cert' Options for ssl-cert *Introduced* 5.1.11 *Command-Line `--ssl-cert=name' Format* *Option-File Format* `ssl-cert' *System Variable `ssl_cert' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The name of the SSL certificate file to use for establishing a secure connection. This variable was added in MySQL 5.1.11. * `ssl_cipher' Options for ssl-cipher *Introduced* 5.1.11 *Command-Line `--ssl-cipher=name' Format* *Option-File Format* `ssl-cipher' *System Variable `ssl_cipher' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' A list of permissible ciphers to use for SSL encryption. This variable was added in MySQL 5.1.11. * `ssl_key' Options for ssl-key *Introduced* 5.1.11 *Command-Line `--ssl-key=name' Format* *Option-File Format* `ssl-key' *System Variable `ssl_key' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' The name of the SSL key file to use for establishing a secure connection. This variable was added in MySQL 5.1.11. * `storage_engine' Options for storage_engine *System Variable `storage_engine' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `MyISAM' The default storage engine (table type). To set the storage engine at server startup, use the `--default-storage-engine' option. See *Note server-options::. * `sync_frm' Options for sync_frm *Command-Line `--sync-frm' Format* *Option-File Format* `sync_frm' *System Variable `sync_frm' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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. * `system_time_zone' Options for system_time_zone *System Variable `system_time_zone' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *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 *Note `mysqld_safe': 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 *Note time-zone-support::. * `table_cache' Options for table_cache *Deprecated* 5.1.3, by table_open_cache *Removed* 5.1.3 *Command-Line `--table_cache=#' Format* *Option-File Format* `table_cache' *System Variable `table_cache' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `64' *Range* `1 .. 524288' This is the old name of `table_open_cache' before MySQL 5.1.3. From 5.1.3 on, use `table_open_cache' instead. * `table_definition_cache' Options for table_definition_cache *Introduced* 5.1.3 *System Variable `table_definition_cache' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values (<= 5.1.24)* *Type* `numeric' *Default* `128' *Range* `1 .. 524288' *Permitted Values (>= 5.1.25)* *Type* `numeric' *Default* `256' *Range* `256 .. 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. This variable was added in MySQL 5.1.3. The minimum and default values are 1 and 128 before MySQL 5.1.25. The minimum and default are both 256 as of MySQL 5.1.25. * `table_lock_wait_timeout' Options for table_lock_wait_timeout *Command-Line `--table_lock_wait_timeout=#' Format* *Option-File Format* `table_lock_wait_timeout' *System Variable `table_lock_wait_timeout' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `50' *Range* `1 .. 1073741824' This variable is unused. * `table_open_cache' Options for table_open_cache *Introduced* 5.1.3 *System Variable `table_open_cache' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `64' *Range* `64 .. 524288' The number of open tables for all threads. Increasing this value increases the number of file descriptors that *Note `mysqld': mysqld. requires. You can check whether you need to increase the table cache by checking the `Opened_tables' status variable. See *Note server-status-variables::. If the value of `Opened_tables' is large and you do not use *Note `FLUSH TABLES': flush. 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 *Note table-cache::. Before MySQL 5.1.3, this variable is called `table_cache'. * `table_type' Options for table_type *System Variable `table_type' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' This variable is a synonym for `storage_engine'. In MySQL 5.1, `storage_engine' is the preferred name; `table_type' is deprecated and is removed in MySQL 5.5. * `thread_cache_size' Options for thread_cache_size *Command-Line `--thread_cache_size=#' Format* *Option-File Format* `thread_cache_size' *System Variable `thread_cache_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 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 *Note server-status-variables::. * `thread_concurrency' Options for thread_concurrency *Command-Line `--thread_concurrency=#' Format* *Option-File Format* `thread_concurrency' *System Variable `thread_concurrency' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `10' *Range* `1 .. 512' This variable is specific to Solaris systems, for which *Note `mysqld': mysqld. invokes the `thr_setconcurrency()' 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. * `thread_handling' Options for thread_handling *Introduced* 5.1.17 *Command-Line `--thread_handling=name' Format* *Option-File Format* `thread_handling' *System Variable `thread_handling' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `enumeration' *Valid Values* `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) and `one-thread-per-connection' (the server uses one thread to handle each client connection). `no-threads' is useful for debugging under Linux; see *Note porting::. This variable was added in MySQL 5.1.17 * `thread_stack' Options for thread_stack *Command-Line `--thread_stack=#' Format* *Option-File Format* `thread_stack' *System Variable `thread_stack' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `196608' *Range* `131072 .. 4294967295' *Block Size* `1024' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `262144' *Range* `131072 .. 18446744073709547520' *Block Size* `1024' The stack size for each thread. Many of the limits detected by the `crash-me' test are dependent on this value. See *Note mysql-benchmarks::. 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. * `time_zone' Options for time_zone *System Variable `time_zone' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *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 *Note time-zone-support::. * `timed_mutexes' Options for timed_mutexes *Command-Line `--timed_mutexes' Format* *Option-File Format* `timed_mutexes' *System Variable `timed_mutexes' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' This variable controls whether `InnoDB' mutexes are timed. If this variable is set to 0 or `OFF' (the default), mutex timing is disabled. If the variable is set to 1 or `ON', mutex timing is enabled. With timing enabled, the `os_wait_times' value in the output from *Note `SHOW ENGINE INNODB MUTEX': show-engine. indicates the amount of time (in ms) spent in operating system waits. Otherwise, the value is 0. * `timestamp = {TIMESTAMP_VALUE | DEFAULT}' 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, not a MySQL timestamp. `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. * `tmp_table_size' Options for tmp_table_size *Command-Line `--tmp_table_size=#' Format* *Option-File Format* `tmp_table_size' *System Variable `tmp_table_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `system dependent' *Range* `1024 .. 4294967295' The maximum size of internal in-memory temporary tables. (The actual limit is determined as the minimum of `tmp_table_size' and `max_heap_table_size'.) If an in-memory temporary table exceeds the limit, MySQL automatically converts it to an on-disk `MyISAM' table. 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. This variable does not apply to user-created `MEMORY' 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 *Note internal-temporary-tables::. * `tmpdir' Options for tmpdir *Command-Line `--tmpdir=path' Format* `-t' *Option-File Format* `tmpdir' *System Variable `tmpdir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file 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, NetWare, and OS/2. 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 *Note `LOAD DATA INFILE': load-data. 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' Options for transaction_alloc_block_size *Command-Line `--transaction_alloc_block_size=#' Format* *Option-File Format* `transaction_alloc_block_size' *System Variable `transaction_alloc_block_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `8192' *Range* `1024 .. 4294967295' *Block Size* `1024' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `8192' *Range* `1024 .. 18446744073709547520' *Block Size* `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_prealloc_size' Options for transaction_prealloc_size *Command-Line `--transaction_prealloc_size=#' Format* *Option-File Format* `transaction_prealloc_size' *System Variable `transaction_prealloc_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `4096' *Range* `1024 .. 4294967295' *Block Size* `1024' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `4096' *Range* `1024 .. 18446744073709547520' *Block Size* `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. * `tx_isolation' Options for tx_isolation *System Variable `tx_isolation' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `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 *Note `SET TRANSACTION': set-transaction. statement. See *Note 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. * `unique_checks' Options for unique_checks *System Variable `unique_checks' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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'. Note that 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' Options for updatable_views_with_limit *Command-Line `--updatable_views_with_limit=#' Format* *Option-File Format* `updatable_views_with_limit' *System Variable `updatable_views_with_limit' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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 *Note `UPDATE': update. or *Note `DELETE': 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. * `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' Options for version_comment *System Variable `version_comment' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' The `configure' script has a `--with-comment' option that permits a comment to be specified when building MySQL. This variable contains the value of that comment. * `version_compile_machine' Options for version_compile_machine *System Variable `version_compile_machine' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' The type of machine or architecture on which MySQL was built. * `version_compile_os' Options for version_compile_os *System Variable `version_compile_os' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' The type of operating system on which MySQL was built. * `wait_timeout' Options for wait_timeout *Command-Line `--wait_timeout=#' Format* *Option-File Format* `wait_timeout' *System Variable `wait_timeout' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `28800' *Range* `1 .. 31536000' *Permitted Values* *Type* (windows) `numeric' *Default* `28800' *Range* `1 .. 2147483' The number of seconds the server waits for activity on a noninteractive connection before closing it. Before MySQL 5.1.41, this timeout applies only to TCP/IP connections, not to connections made through Unix socket files, named pipes, or shared memory. 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 *Note `mysql_real_connect()': 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 *Note show-warnings::.  File: manual.info, Node: using-system-variables, Next: server-status-variables, Prev: server-system-variables, Up: mysqld-server 5.1.5 Using System Variables ---------------------------- * Menu: * structured-system-variables:: Structured System Variables * dynamic-system-variables:: Dynamic System Variables The MySQL server maintains many system variables that indicate how it is configured. *Note 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 *Note `SET': set-statement. statement, which enables you to modify operation of the server without having to stop and restart it. You can refer to system variable values in expressions. The server maintains two kinds of system variables. 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 all global variables to their default values. These defaults can be changed by options specified on the command line or in an option file. (See *Note 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, the 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. 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 a query cache size of 16 megabytes and a maximum packet size of one gigabyte: mysqld --query_cache_size=16M --max_allowed_packet=1G Within an option file, those variables are set like this: [mysqld] query_cache_size=16M max_allowed_packet=1G The lettercase of suffix letters does not matter; `16M' and `16m' are equivalent, as are `1G' and `1g'. If you want to restrict the maximum value to which a system variable can be set at runtime with the *Note `SET': set-statement. statement, you can specify this maximum by using an option of the form `--maximum-VAR_NAME=VALUE' at server startup. For example, to prevent the value of `query_cache_size' from being increased to more than 32MB at runtime, use the option `--maximum-query_cache_size=32M'. Many system variables are dynamic and can be changed while the server runs by using the *Note `SET': set-statement. statement. For a list, see *Note dynamic-system-variables::. To change a system variable with *Note `SET': set-statement, refer to it as VAR_NAME, optionally preceded by a modifier: * To indicate explicitly that a variable is a global variable, precede its name by `GLOBAL' or `@@global.'. The `SUPER' privilege is required to set global variables. * To indicate explicitly that a variable is a session variable, precede its name by `SESSION', `@@session.', or `@@'. Setting a session variable requires no special privilege, but a client can change only its own session variables, not those of any other client. * `LOCAL' and `@@local.' are synonyms for `SESSION' and `@@session.'. * If no modifier is present, *Note `SET': set-statement. changes the session variable. A *Note `SET': set-statement. statement can contain multiple variable assignments, separated by commas. If you set several system variables, the most recent `GLOBAL' or `SESSION' modifier in the statement is used for following variables that have no modifier specified. Examples: SET sort_buffer_size=10000; SET @@local.sort_buffer_size=10000; SET GLOBAL sort_buffer_size=1000000, SESSION sort_buffer_size=1000000; SET @@sort_buffer_size=1000000; SET @@global.sort_buffer_size=1000000, @@local.sort_buffer_size=1000000; The `@@VAR_NAME' syntax for system variables is supported for compatibility with some other database systems. If you change a session system variable, the value remains in effect until your session ends or until you change the variable to a different value. The change is not visible to other clients. If you change a global system variable, the value is remembered and used for new connections until the server restarts. (To make a global system variable setting permanent, you should set it in an option file.) The change is visible to any client that accesses that 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 client that is currently connected (not even that of the client that issues the *Note `SET GLOBAL': set-statement. statement). To prevent incorrect usage, MySQL produces an error if you use *Note `SET GLOBAL': set-statement. with a variable that can only be used with *Note `SET SESSION': set-statement. or if you do not specify `GLOBAL' (or `@@global.') when setting a global variable. To set a `SESSION' variable to the `GLOBAL' value or a `GLOBAL' value to the compiled-in MySQL default value, use the `DEFAULT' keyword. For example, the following two statements are identical in setting the session value of `max_join_size' to the global value: SET 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, use of `DEFAULT' results in an error. You can refer to the values of specific global or session system variables in expressions by using one of the `@@'-modifiers. For example, you can retrieve values in a *Note `SELECT': select. statement like this: SELECT @@global.sql_mode, @@session.sql_mode, @@sql_mode; When you refer to a system variable in an expression as `@@VAR_NAME' (that is, when you do not specify `@@global.' or `@@session.'), MySQL returns the session value if it exists and the global value otherwise. (This differs from `SET @@VAR_NAME = VALUE', which always refers to the session value.) *Note*: Some variables displayed by `SHOW VARIABLES' may not be available using `SELECT @@VAR_NAME' syntax; an `Unknown system variable' occurs. As a workaround in such cases, you can use `SHOW VARIABLES LIKE 'VAR_NAME''. Suffixes for specifying a value multiplier can be used when setting a variable at server startup, but not to set the value with *Note `SET': set-statement. at runtime. On the other hand, with *Note `SET': set-statement. 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 *Note `SET': set-statement. 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 *Note `SHOW VARIABLES': 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 | latin1 | | character_set_connection | latin1 | | character_set_database | latin1 | | character_set_results | latin1 | | character_set_server | latin1 | | character_set_system | utf8 | | character_sets_dir | /home/mysql/share/mysql/charsets/ | | collation_connection | latin1_swedish_ci | | collation_database | latin1_swedish_ci | | collation_server | latin1_swedish_ci | ... | innodb_additional_mem_pool_size | 1048576 | | 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.1.6-alpha-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 *Note `SHOW VARIABLES': 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. If we were 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. If we 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.  File: manual.info, Node: structured-system-variables, Next: dynamic-system-variables, Prev: using-system-variables, Up: using-system-variables 5.1.5.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 5.1 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 *Note 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.  File: manual.info, Node: dynamic-system-variables, Prev: structured-system-variables, Up: using-system-variables 5.1.5.2 Dynamic System Variables ................................ Many server system variables are dynamic and can be set at runtime using *Note `SET GLOBAL': set-statement. or *Note `SET SESSION': set-statement. You can also obtain their values using *Note `SELECT': select. See *Note 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 *Note `SET': set-statement. statement. *Note 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'. (If you set them on the command line or in an option file, use the numeric values.) 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 *Note `ENUM': enum. columns, for which the first enumeration value corresponds to 1. *Dynamic Variable Summary* Variable Name Variable Type Variable Scope `auto_increment_increment' numeric `GLOBAL' | `SESSION' `auto_increment_offset' numeric `GLOBAL' | `SESSION' `autocommit' boolean `SESSION' `automatic_sp_privileges' boolean `GLOBAL' `big_tables' boolean `SESSION' `binlog_cache_size' numeric `GLOBAL' `binlog_direct_non_transactional_updates'boolean `GLOBAL' | `SESSION' `binlog_format' enumeration `GLOBAL' | `SESSION' `bulk_insert_buffer_size' numeric `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' `collation_connection' string `GLOBAL' | `SESSION' `collation_database' string `GLOBAL' | `SESSION' `collation_server' string `GLOBAL' | `SESSION' `completion_type' numeric `GLOBAL' | `SESSION' `concurrent_insert' boolean `GLOBAL' `connect_timeout' numeric `GLOBAL' `debug' string `GLOBAL' | `SESSION' `debug_sync' string `GLOBAL' | `SESSION' `storage_engine' enumeration `GLOBAL' | `SESSION' `default_week_format' numeric `GLOBAL' | `SESSION' `delay_key_write' enumeration `GLOBAL' `delayed_insert_limit' numeric `GLOBAL' `delayed_insert_timeout' numeric `GLOBAL' `delayed_queue_size' numeric `GLOBAL' `div_precision_increment' numeric `GLOBAL' | `SESSION' `engine_condition_pushdown' boolean `GLOBAL' | `SESSION' `event_scheduler' enumeration `GLOBAL' `expire_logs_days' numeric `GLOBAL' `flush' boolean `GLOBAL' `flush_time' numeric `GLOBAL' `foreign_key_checks' boolean `SESSION' `ft_boolean_syntax' string `GLOBAL' `general_log' boolean `GLOBAL' `general_log_file' filename `GLOBAL' `group_concat_max_len' numeric `GLOBAL' | `SESSION' `identity' numeric `SESSION' `init_connect' string `GLOBAL' `init_slave' string `GLOBAL' `innodb_adaptive_flushing' boolean `GLOBAL' `innodb_autoextend_increment' numeric `GLOBAL' `innodb_change_buffering' enumeration `GLOBAL' `innodb_commit_concurrency' numeric `GLOBAL' `innodb_concurrency_tickets' numeric `GLOBAL' `innodb_fast_shutdown' numeric `GLOBAL' `innodb_file_format' string `GLOBAL' `innodb_file_format_check' string `GLOBAL' `innodb_flush_log_at_trx_commit'enumeration `GLOBAL' `innodb_lock_wait_timeout' numeric `GLOBAL' | `SESSION' `innodb_max_dirty_pages_pct' numeric `GLOBAL' `innodb_max_purge_lag' numeric `GLOBAL' `innodb_old_blocks_pct' numeric `GLOBAL' `innodb_old_blocks_time' numeric `GLOBAL' `innodb_random_read_ahead' boolean `GLOBAL' `innodb_read_ahead_threshold' numeric `GLOBAL' `innodb_replication_delay' numeric `GLOBAL' `innodb_spin_wait_delay' numeric `GLOBAL' `innodb_stats_method' enumeration `GLOBAL' `innodb_stats_on_metadata' boolean `GLOBAL' `innodb_stats_sample_pages' numeric `GLOBAL' `innodb_strict_mode' boolean `GLOBAL' | `SESSION' `innodb_support_xa' boolean `GLOBAL' | `SESSION' `innodb_sync_spin_loops' numeric `GLOBAL' `innodb_table_locks' boolean `GLOBAL' | `SESSION' `innodb_thread_concurrency' numeric `GLOBAL' `innodb_thread_sleep_delay' numeric `GLOBAL' `innodb_use_legacy_cardinality_algorithm'boolean `GLOBAL' `insert_id' numeric `SESSION' `interactive_timeout' numeric `GLOBAL' | `SESSION' `join_buffer_size' numeric `GLOBAL' | `SESSION' `keep_files_on_create' boolean `GLOBAL' | `SESSION' `key_buffer_size' numeric `GLOBAL' `key_cache_age_threshold' numeric `GLOBAL' `key_cache_block_size' numeric `GLOBAL' `key_cache_division_limit' numeric `GLOBAL' `last_insert_id' numeric `SESSION' `lc_time_names' string `GLOBAL' | `SESSION' `local_infile' boolean `GLOBAL' `log' string `GLOBAL' `log_bin_trust_function_creators'boolean `GLOBAL' `log_bin_trust_routine_creators'boolean `GLOBAL' `log_output' set `GLOBAL' `log_queries_not_using_indexes'boolean `GLOBAL' `log_slow_queries' boolean `GLOBAL' `log_warnings' numeric `GLOBAL' | `SESSION' `long_query_time' numeric `GLOBAL' | `SESSION' `low_priority_updates' boolean `GLOBAL' | `SESSION' `max_allowed_packet' numeric `GLOBAL' `max_binlog_cache_size' numeric `GLOBAL' `max_binlog_size' numeric `GLOBAL' `max_connect_errors' numeric `GLOBAL' `max_connections' numeric `GLOBAL' `max_delayed_threads' numeric `GLOBAL' | `SESSION' `max_error_count' numeric `GLOBAL' | `SESSION' `max_heap_table_size' numeric `GLOBAL' | `SESSION' `max_insert_delayed_threads' numeric `GLOBAL' | `SESSION' `max_join_size' numeric `GLOBAL' | `SESSION' `max_length_for_sort_data' numeric `GLOBAL' | `SESSION' `max_prepared_stmt_count' numeric `GLOBAL' `max_relay_log_size' numeric `GLOBAL' `max_seeks_for_key' numeric `GLOBAL' | `SESSION' `max_sort_length' numeric `GLOBAL' | `SESSION' `max_sp_recursion_depth' numeric `GLOBAL' | `SESSION' `max_user_connections' numeric `GLOBAL' | `SESSION' `max_write_lock_count' numeric `GLOBAL' `min_examined_row_limit' numeric `GLOBAL' | `SESSION' `multi_range_count' numeric `GLOBAL' | `SESSION' `myisam_data_pointer_size' numeric `GLOBAL' `myisam_max_sort_file_size' numeric `GLOBAL' `myisam_repair_threads' numeric `GLOBAL' | `SESSION' `myisam_sort_buffer_size' numeric `GLOBAL' | `SESSION' `myisam_stats_method' enumeration `GLOBAL' | `SESSION' `myisam_use_mmap' boolean `GLOBAL' `ndb_autoincrement_prefetch_sz'numeric `GLOBAL' | `SESSION' `ndb_blob_read_batch_bytes' numeric `GLOBAL' | `SESSION' `ndb_blob_write_batch_bytes' numeric `GLOBAL' | `SESSION' `ndb_cache_check_time' numeric `GLOBAL' `ndb_deferred_constraints' integer `GLOBAL' | `SESSION' `ndb_deferred_constraints' integer `GLOBAL' | `SESSION' `ndb_distribution={KEYHASH|LINHASH}'enumeration `GLOBAL' | `SESSION' `ndb_distribution' enumeration `GLOBAL' | `SESSION' `ndb_extra_logging' numeric `GLOBAL' `ndb_force_send' 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_update_as_write' boolean `GLOBAL' `ndb_log_updated_only' boolean `GLOBAL' `ndb_optimization_delay' numeric `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' numeric `GLOBAL' | `SESSION' `ndbinfo_max_rows' numeric `GLOBAL' | `SESSION' `ndbinfo_show_hidden' boolean `GLOBAL' | `SESSION' `ndbinfo_table_prefix' string `GLOBAL' | `SESSION' `net_buffer_length' numeric `GLOBAL' | `SESSION' `net_read_timeout' numeric `GLOBAL' | `SESSION' `net_retry_count' numeric `GLOBAL' | `SESSION' `net_write_timeout' numeric `GLOBAL' | `SESSION' `new' boolean `GLOBAL' | `SESSION' `old_alter_table' boolean `GLOBAL' | `SESSION' `old_passwords' boolean `GLOBAL' | `SESSION' `optimizer_prune_level' boolean `GLOBAL' | `SESSION' `optimizer_search_depth' numeric `GLOBAL' | `SESSION' `optimizer_switch' set `GLOBAL' | `SESSION' `preload_buffer_size' numeric `GLOBAL' | `SESSION' `profiling' boolean `SESSION' `profiling_history_size' numeric `GLOBAL' | `SESSION' `pseudo_thread_id' numeric `SESSION' `query_alloc_block_size' numeric `GLOBAL' | `SESSION' `query_cache_limit' numeric `GLOBAL' `query_cache_min_res_unit' numeric `GLOBAL' `query_cache_size' numeric `GLOBAL' `query_cache_type' enumeration `GLOBAL' | `SESSION' `query_cache_wlock_invalidate'boolean `GLOBAL' | `SESSION' `query_prealloc_size' numeric `GLOBAL' | `SESSION' `rand_seed1' numeric `SESSION' `rand_seed2' numeric `SESSION' `range_alloc_block_size' numeric `GLOBAL' | `SESSION' `read_buffer_size' numeric `GLOBAL' | `SESSION' `read_only' boolean `GLOBAL' `read_rnd_buffer_size' numeric `GLOBAL' | `SESSION' `relay_log_purge' boolean `GLOBAL' `rpl_recovery_rank' numeric `GLOBAL' `safe_show_database' boolean `GLOBAL' `secure_auth' boolean `GLOBAL' `server_id' numeric `GLOBAL' `slave_allow_batching' boolean `GLOBAL' `slave_compressed_protocol' boolean `GLOBAL' `slave_exec_mode' enumeration `GLOBAL' `slave_max_allowed_packet' numeric `GLOBAL' `slave_net_timeout' numeric `GLOBAL' `slave_transaction_retries' numeric `GLOBAL' `slow_launch_time' numeric `GLOBAL' `slow_query_log' boolean `GLOBAL' `slow_query_log_file' filename `GLOBAL' `sort_buffer_size' numeric `GLOBAL' | `SESSION' `sql_auto_is_null' boolean `SESSION' `sql_big_selects' boolean `SESSION' `sql_big_tables' boolean `SESSION' `sql_buffer_result' boolean `SESSION' `sql_log_bin' boolean `SESSION' `sql_log_off' boolean `SESSION' `sql_log_update' boolean `SESSION' `sql_low_priority_updates' boolean `GLOBAL' | `SESSION' `sql_max_join_size' numeric `GLOBAL' | `SESSION' `sql_mode' set `GLOBAL' | `SESSION' `sql_notes' boolean `SESSION' `sql_quote_show_create' boolean `SESSION' `sql_safe_updates' boolean `SESSION' `sql_select_limit' numeric `GLOBAL' | `SESSION' `sql_slave_skip_counter' numeric `GLOBAL' `sql_warnings' boolean `SESSION' `storage_engine' enumeration `GLOBAL' | `SESSION' `sync_binlog' numeric `GLOBAL' `sync_frm' boolean `GLOBAL' `table_cache' numeric `GLOBAL' `table_definition_cache' numeric `GLOBAL' `table_lock_wait_timeout' numeric `GLOBAL' `table_open_cache' numeric `GLOBAL' `table_type' enumeration `GLOBAL' | `SESSION' `thread_cache_size' numeric `GLOBAL' `time_zone' string `GLOBAL' | `SESSION' `timed_mutexes' boolean `GLOBAL' `timestamp' numeric `SESSION' `tmp_table_size' numeric `GLOBAL' | `SESSION' `transaction_alloc_block_size'numeric `GLOBAL' | `SESSION' `transaction_allow_batching' boolean `SESSION' `transaction_prealloc_size' numeric `GLOBAL' | `SESSION' `tx_isolation' enumeration `GLOBAL' | `SESSION' `unique_checks' boolean `SESSION' `updatable_views_with_limit' boolean `GLOBAL' | `SESSION' `wait_timeout' numeric `GLOBAL' | `SESSION'  File: manual.info, Node: server-status-variables, Next: server-sql-mode, Prev: using-system-variables, Up: mysqld-server 5.1.6 Server Status Variables ----------------------------- The 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 *Note 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 | +-----------------------------------+------------+ Many status variables are reset to 0 by the *Note `FLUSH STATUS': flush. statement. The following table lists all available server status variables: *Status Variable Summary* Variable Name Variable Type Variable Scope `Aborted_clients' numeric `GLOBAL' `Aborted_connects' numeric `GLOBAL' `Binlog_cache_disk_use' numeric `GLOBAL' `Binlog_cache_use' numeric `GLOBAL' `Bytes_received' numeric `GLOBAL' | `SESSION' `Bytes_sent' numeric `GLOBAL' | `SESSION' `Com_admin_commands' numeric `GLOBAL' | `SESSION' `Com_alter_db' numeric `GLOBAL' | `SESSION' `Com_alter_db_upgrade' numeric `GLOBAL' | `SESSION' `Com_alter_event' numeric `GLOBAL' | `SESSION' `Com_alter_function' numeric `GLOBAL' | `SESSION' `Com_alter_procedure' numeric `GLOBAL' | `SESSION' `Com_alter_server' numeric `GLOBAL' | `SESSION' `Com_alter_table' numeric `GLOBAL' | `SESSION' `Com_alter_tablespace' numeric `GLOBAL' | `SESSION' `Com_analyze' numeric `GLOBAL' | `SESSION' `Com_assign_to_keycache' numeric `GLOBAL' | `SESSION' `Com_backup_table' numeric `GLOBAL' | `SESSION' `Com_begin' numeric `GLOBAL' | `SESSION' `Com_binlog' numeric `GLOBAL' | `SESSION' `Com_call_procedure' numeric `GLOBAL' | `SESSION' `Com_change_db' numeric `GLOBAL' | `SESSION' `Com_change_master' numeric `GLOBAL' | `SESSION' `Com_check' numeric `GLOBAL' | `SESSION' `Com_checksum' numeric `GLOBAL' | `SESSION' `Com_commit' numeric `GLOBAL' | `SESSION' `Com_create_db' numeric `GLOBAL' | `SESSION' `Com_create_event' numeric `GLOBAL' | `SESSION' `Com_create_function' numeric `GLOBAL' | `SESSION' `Com_create_index' numeric `GLOBAL' | `SESSION' `Com_create_procedure' numeric `GLOBAL' | `SESSION' `Com_create_server' numeric `GLOBAL' | `SESSION' `Com_create_table' numeric `GLOBAL' | `SESSION' `Com_create_trigger' numeric `GLOBAL' | `SESSION' `Com_create_udf' numeric `GLOBAL' | `SESSION' `Com_create_user' numeric `GLOBAL' | `SESSION' `Com_create_view' numeric `GLOBAL' | `SESSION' `Com_dealloc_sql' numeric `GLOBAL' | `SESSION' `Com_delete' numeric `GLOBAL' | `SESSION' `Com_delete_multi' numeric `GLOBAL' | `SESSION' `Com_do' numeric `GLOBAL' | `SESSION' `Com_drop_db' numeric `GLOBAL' | `SESSION' `Com_drop_event' numeric `GLOBAL' | `SESSION' `Com_drop_function' numeric `GLOBAL' | `SESSION' `Com_drop_index' numeric `GLOBAL' | `SESSION' `Com_drop_procedure' numeric `GLOBAL' | `SESSION' `Com_drop_server' numeric `GLOBAL' | `SESSION' `Com_drop_table' numeric `GLOBAL' | `SESSION' `Com_drop_trigger' numeric `GLOBAL' | `SESSION' `Com_drop_user' numeric `GLOBAL' | `SESSION' `Com_drop_view' numeric `GLOBAL' | `SESSION' `Com_empty_query' numeric `GLOBAL' | `SESSION' `Com_execute_sql' numeric `GLOBAL' | `SESSION' `Com_flush' numeric `GLOBAL' | `SESSION' `Com_grant' numeric `GLOBAL' | `SESSION' `Com_ha_close' numeric `GLOBAL' | `SESSION' `Com_ha_open' numeric `GLOBAL' | `SESSION' `Com_ha_read' numeric `GLOBAL' | `SESSION' `Com_help' numeric `GLOBAL' | `SESSION' `Com_insert' numeric `GLOBAL' | `SESSION' `Com_insert_select' numeric `GLOBAL' | `SESSION' `Com_install_plugin' numeric `GLOBAL' | `SESSION' `Com_kill' numeric `GLOBAL' | `SESSION' `Com_load' numeric `GLOBAL' | `SESSION' `Com_lock_tables' numeric `GLOBAL' | `SESSION' `Com_optimize' numeric `GLOBAL' | `SESSION' `Com_preload_keys' numeric `GLOBAL' | `SESSION' `Com_prepare_sql' numeric `GLOBAL' | `SESSION' `Com_purge' numeric `GLOBAL' | `SESSION' `Com_purge_before_date' numeric `GLOBAL' | `SESSION' `Com_release_savepoint' numeric `GLOBAL' | `SESSION' `Com_rename_table' numeric `GLOBAL' | `SESSION' `Com_rename_user' numeric `GLOBAL' | `SESSION' `Com_repair' numeric `GLOBAL' | `SESSION' `Com_replace' numeric `GLOBAL' | `SESSION' `Com_replace_select' numeric `GLOBAL' | `SESSION' `Com_reset' numeric `GLOBAL' | `SESSION' `Com_restore_table' numeric `GLOBAL' | `SESSION' `Com_revoke' numeric `GLOBAL' | `SESSION' `Com_revoke_all' numeric `GLOBAL' | `SESSION' `Com_rollback' numeric `GLOBAL' | `SESSION' `Com_rollback_to_savepoint' numeric `GLOBAL' | `SESSION' `Com_savepoint' numeric `GLOBAL' | `SESSION' `Com_select' numeric `GLOBAL' | `SESSION' `Com_set_option' numeric `GLOBAL' | `SESSION' `Com_show_authors' numeric `GLOBAL' | `SESSION' `Com_show_binlog_events' numeric `GLOBAL' | `SESSION' `Com_show_binlogs' numeric `GLOBAL' | `SESSION' `Com_show_charsets' numeric `GLOBAL' | `SESSION' `Com_show_collations' numeric `GLOBAL' | `SESSION' `Com_show_column_types' numeric `GLOBAL' | `SESSION' `Com_show_contributors' numeric `GLOBAL' | `SESSION' `Com_show_create_db' numeric `GLOBAL' | `SESSION' `Com_show_create_event' numeric `GLOBAL' | `SESSION' `Com_show_create_func' numeric `GLOBAL' | `SESSION' `Com_show_create_proc' numeric `GLOBAL' | `SESSION' `Com_show_create_table' numeric `GLOBAL' | `SESSION' `Com_show_create_trigger' numeric `GLOBAL' | `SESSION' `Com_show_databases' numeric `GLOBAL' | `SESSION' `Com_show_engine_logs' numeric `GLOBAL' | `SESSION' `Com_show_engine_mutex' numeric `GLOBAL' | `SESSION' `Com_show_engine_status' numeric `GLOBAL' | `SESSION' `Com_show_errors' numeric `GLOBAL' | `SESSION' `Com_show_events' numeric `GLOBAL' | `SESSION' `Com_show_fields' numeric `GLOBAL' | `SESSION' `Com_show_function_code' numeric `GLOBAL' | `SESSION' `Com_show_function_status' numeric `GLOBAL' | `SESSION' `Com_show_grants' numeric `GLOBAL' | `SESSION' `Com_show_keys' numeric `GLOBAL' | `SESSION' `Com_show_logs' numeric `GLOBAL' | `SESSION' `Com_show_master_status' numeric `GLOBAL' | `SESSION' `Com_show_ndb_status' numeric `GLOBAL' | `SESSION' `Com_show_new_master' numeric `GLOBAL' | `SESSION' `Com_show_open_tables' numeric `GLOBAL' | `SESSION' `Com_show_plugins' numeric `GLOBAL' | `SESSION' `Com_show_privileges' numeric `GLOBAL' | `SESSION' `Com_show_procedure_code' numeric `GLOBAL' | `SESSION' `Com_show_procedure_status' numeric `GLOBAL' | `SESSION' `Com_show_processlist' numeric `GLOBAL' | `SESSION' `Com_show_profile' numeric `GLOBAL' | `SESSION' `Com_show_profiles' numeric `GLOBAL' | `SESSION' `Com_show_slave_hosts' numeric `GLOBAL' | `SESSION' `Com_show_slave_status' numeric `GLOBAL' | `SESSION' `Com_show_status' numeric `GLOBAL' | `SESSION' `Com_show_storage_engines' numeric `GLOBAL' | `SESSION' `Com_show_table_status' numeric `GLOBAL' | `SESSION' `Com_show_tables' numeric `GLOBAL' | `SESSION' `Com_show_triggers' numeric `GLOBAL' | `SESSION' `Com_show_variables' numeric `GLOBAL' | `SESSION' `Com_show_warnings' numeric `GLOBAL' | `SESSION' `Com_slave_start' numeric `GLOBAL' | `SESSION' `Com_slave_stop' numeric `GLOBAL' | `SESSION' `Com_stmt_close' numeric `GLOBAL' | `SESSION' `Com_stmt_execute' numeric `GLOBAL' | `SESSION' `Com_stmt_fetch' numeric `GLOBAL' | `SESSION' `Com_stmt_prepare' numeric `GLOBAL' | `SESSION' `Com_stmt_reprepare' numeric `GLOBAL' | `SESSION' `Com_stmt_reset' numeric `GLOBAL' | `SESSION' `Com_stmt_send_long_data' numeric `GLOBAL' | `SESSION' `Com_truncate' numeric `GLOBAL' | `SESSION' `Com_uninstall_plugin' numeric `GLOBAL' | `SESSION' `Com_unlock_tables' numeric `GLOBAL' | `SESSION' `Com_update' numeric `GLOBAL' | `SESSION' `Com_update_multi' numeric `GLOBAL' | `SESSION' `Com_xa_commit' numeric `GLOBAL' | `SESSION' `Com_xa_end' numeric `GLOBAL' | `SESSION' `Com_xa_prepare' numeric `GLOBAL' | `SESSION' `Com_xa_recover' numeric `GLOBAL' | `SESSION' `Com_xa_rollback' numeric `GLOBAL' | `SESSION' `Com_xa_start' numeric `GLOBAL' | `SESSION' `Compression' numeric `SESSION' `Connections' numeric `GLOBAL' `Created_tmp_disk_tables' numeric `GLOBAL' | `SESSION' `Created_tmp_files' numeric `GLOBAL' `Created_tmp_tables' numeric `GLOBAL' | `SESSION' `Delayed_errors' numeric `GLOBAL' `Delayed_insert_threads' numeric `GLOBAL' `Delayed_writes' numeric `GLOBAL' `Flush_commands' numeric `GLOBAL' `Handler_commit' numeric `GLOBAL' | `SESSION' `Handler_delete' numeric `GLOBAL' | `SESSION' `Handler_discover' numeric `GLOBAL' | `SESSION' `Handler_prepare' numeric `GLOBAL' | `SESSION' `Handler_read_first' numeric `GLOBAL' | `SESSION' `Handler_read_key' numeric `GLOBAL' | `SESSION' `Handler_read_next' numeric `GLOBAL' | `SESSION' `Handler_read_prev' numeric `GLOBAL' | `SESSION' `Handler_read_rnd' numeric `GLOBAL' | `SESSION' `Handler_read_rnd_next' numeric `GLOBAL' | `SESSION' `Handler_rollback' numeric `GLOBAL' | `SESSION' `Handler_savepoint' numeric `GLOBAL' | `SESSION' `Handler_savepoint_rollback' numeric `GLOBAL' | `SESSION' `Handler_update' numeric `GLOBAL' | `SESSION' `Handler_write' numeric `GLOBAL' | `SESSION' `Innodb_buffer_pool_pages_data'numeric `GLOBAL' `Innodb_buffer_pool_pages_dirty'numeric `GLOBAL' `Innodb_buffer_pool_pages_flushed'numeric `GLOBAL' `Innodb_buffer_pool_pages_free'numeric `GLOBAL' `Innodb_buffer_pool_pages_latched'numeric `GLOBAL' `Innodb_buffer_pool_pages_misc'numeric `GLOBAL' `Innodb_buffer_pool_pages_total'numeric `GLOBAL' `Innodb_buffer_pool_read_ahead'numeric `GLOBAL' `Innodb_buffer_pool_read_ahead_evicted'numeric `GLOBAL' `Innodb_buffer_pool_read_ahead_rnd'numeric `GLOBAL' `Innodb_buffer_pool_read_ahead_seq'numeric `GLOBAL' `Innodb_buffer_pool_read_requests'numeric `GLOBAL' `Innodb_buffer_pool_reads' numeric `GLOBAL' `Innodb_buffer_pool_wait_free'numeric `GLOBAL' `Innodb_buffer_pool_write_requests'numeric `GLOBAL' `Innodb_data_fsyncs' numeric `GLOBAL' `Innodb_data_pending_fsyncs' numeric `GLOBAL' `Innodb_data_pending_reads' numeric `GLOBAL' `Innodb_data_pending_writes' numeric `GLOBAL' `Innodb_data_read' numeric `GLOBAL' `Innodb_data_reads' numeric `GLOBAL' `Innodb_data_writes' numeric `GLOBAL' `Innodb_data_written' numeric `GLOBAL' `Innodb_dblwr_pages_written' numeric `GLOBAL' `Innodb_dblwr_writes' numeric `GLOBAL' `Innodb_have_atomic_builtins' numeric `GLOBAL' `Innodb_log_waits' numeric `GLOBAL' `Innodb_log_write_requests' numeric `GLOBAL' `Innodb_log_writes' numeric `GLOBAL' `Innodb_os_log_fsyncs' numeric `GLOBAL' `Innodb_os_log_pending_fsyncs'numeric `GLOBAL' `Innodb_os_log_pending_writes'numeric `GLOBAL' `Innodb_os_log_written' numeric `GLOBAL' `Innodb_page_size' numeric `GLOBAL' `Innodb_pages_created' numeric `GLOBAL' `Innodb_pages_read' numeric `GLOBAL' `Innodb_pages_written' numeric `GLOBAL' `Innodb_row_lock_current_waits'numeric `GLOBAL' `Innodb_row_lock_time' numeric `GLOBAL' `Innodb_row_lock_time_avg' numeric `GLOBAL' `Innodb_row_lock_time_max' numeric `GLOBAL' `Innodb_row_lock_waits' numeric `GLOBAL' `Innodb_rows_deleted' numeric `GLOBAL' `Innodb_rows_inserted' numeric `GLOBAL' `Innodb_rows_read' numeric `GLOBAL' `Innodb_rows_updated' numeric `GLOBAL' `Key_blocks_not_flushed' numeric `GLOBAL' `Key_blocks_unused' numeric `GLOBAL' `Key_blocks_used' numeric `GLOBAL' `Key_read_requests' numeric `GLOBAL' `Key_reads' numeric `GLOBAL' `Key_write_requests' numeric `GLOBAL' `Key_writes' numeric `GLOBAL' `Last_query_cost' numeric `SESSION' `Max_used_connections' numeric `GLOBAL' `Ndb_api_bytes_received_count'numeric `GLOBAL' `Ndb_api_bytes_received_count_session'numeric `SESSION' `Ndb_api_bytes_received_count_slave'numeric `GLOBAL' `Ndb_api_bytes_sent_count' numeric `GLOBAL' `Ndb_api_bytes_sent_count_session'numeric `SESSION' `Ndb_api_bytes_sent_count_slave'numeric `GLOBAL' `Ndb_api_event_bytes_count' numeric `GLOBAL' `Ndb_api_event_bytes_count_injector'numeric `GLOBAL' `Ndb_api_event_data_count' numeric `GLOBAL' `Ndb_api_event_data_count_injector'numeric `GLOBAL' `Ndb_api_event_nondata_count' numeric `GLOBAL' `Ndb_api_event_nondata_count_injector'numeric `GLOBAL' `Ndb_api_pk_op_count' numeric `GLOBAL' `Ndb_api_pk_op_count_session' numeric `SESSION' `Ndb_api_pk_op_count_slave' numeric `GLOBAL' `Ndb_api_pruned_scan_count' numeric `GLOBAL' `Ndb_api_pruned_scan_count_session'numeric `SESSION' `Ndb_api_pruned_scan_count_slave'numeric `GLOBAL' `Ndb_api_range_scan_count' numeric `GLOBAL' `Ndb_api_range_scan_count_session'numeric `SESSION' `Ndb_api_range_scan_count_slave'numeric `GLOBAL' `Ndb_api_read_row_count' numeric `GLOBAL' `Ndb_api_read_row_count_session'numeric `SESSION' `Ndb_api_read_row_count_slave'numeric `GLOBAL' `Ndb_api_scan_batch_count' numeric `GLOBAL' `Ndb_api_scan_batch_count_session'numeric `SESSION' `Ndb_api_scan_batch_count_slave'numeric `GLOBAL' `Ndb_api_table_scan_count' numeric `GLOBAL' `Ndb_api_table_scan_count_session'numeric `SESSION' `Ndb_api_table_scan_count_slave'numeric `GLOBAL' `Ndb_api_trans_abort_count' numeric `GLOBAL' `Ndb_api_trans_abort_count_session'numeric `SESSION' `Ndb_api_trans_abort_count_slave'numeric `GLOBAL' `Ndb_api_trans_close_count' numeric `GLOBAL' `Ndb_api_trans_close_count_session'numeric `SESSION' `Ndb_api_trans_close_count_slave'numeric `GLOBAL' `Ndb_api_trans_commit_count' numeric `GLOBAL' `Ndb_api_trans_commit_count_session'numeric `SESSION' `Ndb_api_trans_commit_count_slave'numeric `GLOBAL' `Ndb_api_trans_local_read_row_count'numeric `GLOBAL' `Ndb_api_trans_local_read_row_count_session'numeric `SESSION' `Ndb_api_trans_local_read_row_count_slave'numeric `GLOBAL' `Ndb_api_trans_start_count' numeric `GLOBAL' `Ndb_api_trans_start_count_session'numeric `SESSION' `Ndb_api_trans_start_count_slave'numeric `GLOBAL' `Ndb_api_uk_op_count' numeric `GLOBAL' `Ndb_api_uk_op_count_session' numeric `SESSION' `Ndb_api_uk_op_count_slave' numeric `GLOBAL' `Ndb_api_wait_exec_complete_count'numeric `GLOBAL' `Ndb_api_wait_exec_complete_count_session'numeric `SESSION' `Ndb_api_wait_exec_complete_count_slave'numeric `GLOBAL' `Ndb_api_wait_meta_request_count'numeric `GLOBAL' `Ndb_api_wait_meta_request_count_session'numeric `SESSION' `Ndb_api_wait_meta_request_count_slave'numeric `GLOBAL' `Ndb_api_wait_nanos_count' numeric `GLOBAL' `Ndb_api_wait_nanos_count_session'numeric `SESSION' `Ndb_api_wait_nanos_count_slave'numeric `GLOBAL' `Ndb_api_wait_scan_result_count'numeric `GLOBAL' `Ndb_api_wait_scan_result_count_session'numeric `SESSION' `Ndb_api_wait_scan_result_count_slave'numeric `GLOBAL' `ndb_cluster_connection_pool' numeric `GLOBAL' `Ndb_cluster_node_id' numeric `GLOBAL' | `SESSION' `Ndb_config_from_host' numeric `GLOBAL' | `SESSION' `Ndb_config_from_port' numeric `GLOBAL' | `SESSION' `Ndb_conflict_fn_epoch' numeric `GLOBAL' `Ndb_conflict_fn_epoch_trans' numeric `GLOBAL' `Ndb_conflict_fn_max' numeric `GLOBAL' `Ndb_conflict_fn_old' numeric `GLOBAL' `Ndb_conflict_trans_conflict_commit_count'numeric `GLOBAL' `Ndb_conflict_trans_detect_iter_count'numeric `GLOBAL' `Ndb_conflict_trans_reject_count'numeric `GLOBAL' `Ndb_conflict_trans_row_conflict_count'numeric `GLOBAL' `Ndb_conflict_trans_row_reject_count'numeric `GLOBAL' `ndb_execute_count' numeric `GLOBAL' `ndb-nodeid' numeric `GLOBAL' `Ndb_number_of_data_nodes' numeric `GLOBAL' `ndb_pruned_scan_count' numeric `GLOBAL' `Ndb_pushed_queries_defined' numeric `GLOBAL' `Ndb_pushed_queries_dropped' numeric `GLOBAL' `Ndb_pushed_queries_executed' numeric `GLOBAL' `ndb_pushed_reads' numeric `GLOBAL' `ndb_scan_count' numeric `GLOBAL' `Not_flushed_delayed_rows' numeric `GLOBAL' `Open_files' numeric `GLOBAL' `Open_streams' numeric `GLOBAL' `Open_table_definitions' numeric `GLOBAL' `Open_tables' numeric `GLOBAL' | `SESSION' `Opened_files' numeric `GLOBAL' `Opened_table_definitions' numeric `GLOBAL' | `SESSION' `Opened_tables' numeric `GLOBAL' | `SESSION' `Prepared_stmt_count' numeric `GLOBAL' `Qcache_free_blocks' numeric `GLOBAL' `Qcache_free_memory' numeric `GLOBAL' `Qcache_hits' numeric `GLOBAL' `Qcache_inserts' numeric `GLOBAL' `Qcache_lowmem_prunes' numeric `GLOBAL' `Qcache_not_cached' numeric `GLOBAL' `Qcache_queries_in_cache' numeric `GLOBAL' `Qcache_total_blocks' numeric `GLOBAL' `Queries' numeric `GLOBAL' | `SESSION' `Questions' numeric `GLOBAL' | `SESSION' `Rpl_status' string `GLOBAL' `Select_full_join' numeric `GLOBAL' | `SESSION' `Select_full_range_join' numeric `GLOBAL' | `SESSION' `Select_range' numeric `GLOBAL' | `SESSION' `Select_range_check' numeric `GLOBAL' | `SESSION' `Select_scan' numeric `GLOBAL' | `SESSION' `Slave_heartbeat_period' `GLOBAL' `Slave_open_temp_tables' numeric `GLOBAL' `Slave_received_heartbeats' `GLOBAL' `Slave_retried_transactions' numeric `GLOBAL' `Slave_running' boolean `GLOBAL' `Slow_launch_threads' numeric `GLOBAL' | `SESSION' `Slow_queries' numeric `GLOBAL' | `SESSION' `Sort_merge_passes' numeric `GLOBAL' | `SESSION' `Sort_range' numeric `GLOBAL' | `SESSION' `Sort_rows' numeric `GLOBAL' | `SESSION' `Sort_scan' numeric `GLOBAL' | `SESSION' `Ssl_accept_renegotiates' numeric `GLOBAL' `Ssl_accepts' numeric `GLOBAL' `Ssl_callback_cache_hits' numeric `GLOBAL' `Ssl_cipher' string `GLOBAL' | `SESSION' `Ssl_cipher_list' string `GLOBAL' | `SESSION' `Ssl_client_connects' numeric `GLOBAL' `Ssl_connect_renegotiates' numeric `GLOBAL' `Ssl_ctx_verify_depth' numeric `GLOBAL' `Ssl_ctx_verify_mode' numeric `GLOBAL' `Ssl_default_timeout' numeric `GLOBAL' | `SESSION' `Ssl_finished_accepts' numeric `GLOBAL' `Ssl_finished_connects' numeric `GLOBAL' `Ssl_session_cache_hits' numeric `GLOBAL' `Ssl_session_cache_misses' numeric `GLOBAL' `Ssl_session_cache_mode' string `GLOBAL' `Ssl_session_cache_overflows' numeric `GLOBAL' `Ssl_session_cache_size' numeric `GLOBAL' `Ssl_session_cache_timeouts' numeric `GLOBAL' `Ssl_sessions_reused' numeric `GLOBAL' | `SESSION' `Ssl_used_session_cache_entries'numeric `GLOBAL' `Ssl_verify_depth' numeric `GLOBAL' | `SESSION' `Ssl_verify_mode' numeric `GLOBAL' | `SESSION' `Ssl_version' string `GLOBAL' | `SESSION' `Table_locks_immediate' numeric `GLOBAL' `Table_locks_waited' numeric `GLOBAL' `Tc_log_max_pages_used' numeric `GLOBAL' `Tc_log_page_size' numeric `GLOBAL' `Tc_log_page_waits' numeric `GLOBAL' `Threads_cached' numeric `GLOBAL' `Threads_connected' numeric `GLOBAL' `Threads_created' numeric `GLOBAL' `Threads_running' numeric `GLOBAL' `Uptime' numeric `GLOBAL' `Uptime_since_flush_status' numeric `GLOBAL' The status variables have the following meanings. For meanings of status variables specific to MySQL Cluster, see *Note mysql-cluster-status-variables::. * `Aborted_clients' The number of connections that were aborted because the client died without closing the connection properly. See *Note communication-errors::. * `Aborted_connects' The number of failed attempts to connect to the MySQL server. See *Note communication-errors::. * `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. * `Binlog_cache_use' The number of transactions that used the temporary binary log 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 *Note `DELETE': delete. and *Note `UPDATE': update. statements, respectively. `Com_delete_multi' and `Com_update_multi' are similar but apply to *Note `DELETE': delete. and *Note `UPDATE': 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 *Note query-cache-status-and-maintenance::. 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 *Note `PREPARE': prepare, *Note `EXECUTE': execute, or *Note `DEALLOCATE PREPARE': 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 *Note `PREPARE': prepare, *Note `EXECUTE': execute, and *Note `DEALLOCATE PREPARE': 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. This variable was added in MySQL 5.1.25. A reprepare operation increments `Com_stmt_reprepare', and also `Com_stmt_prepare'. * `Compression' Whether the client connection uses compression in the client/server protocol. Added in MySQL 5.1.2. * `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 *Note internal-temporary-tables::. * `Created_tmp_files' How many temporary files *Note `mysqld': 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 *Note internal-temporary-tables::. Each invocation of the *Note `SHOW STATUS': show-status. statement uses an internal temporary table and increments the global `Created_tmp_tables' value. * `Delayed_errors' The number of rows written with *Note `INSERT DELAYED': insert-delayed. for which some error occurred (probably `duplicate key'). * `Delayed_insert_threads' The number of *Note `INSERT DELAYED': insert-delayed. handler threads in use. * `Delayed_writes' The number of *Note `INSERT DELAYED': insert-delayed. rows written. * `Flush_commands' The number of times the server flushes tables, whether because a user executed a *Note `FLUSH TABLES': flush. 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 *Note `FLUSH TABLES': flush, *Note `FLUSH LOGS': flush, and so forth. * `Handler_commit' The number of internal *Note `COMMIT': commit. statements. * `Handler_delete' The number of times that rows have been deleted from tables. * `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_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_buffer_pool_pages_data' The number of pages containing data (dirty or clean). * `Innodb_buffer_pool_pages_dirty' The number of pages currently dirty. * `Innodb_buffer_pool_pages_flushed' The number of buffer pool page-flush requests. * `Innodb_buffer_pool_pages_free' The number of free pages. * `Innodb_buffer_pool_pages_latched' The number of latched pages in `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 as of MySQL 5.1.28, it is available only when the `UNIV_DEBUG' system is defined at server build time. * `Innodb_buffer_pool_pages_misc' The number of pages 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'. * `Innodb_buffer_pool_pages_total' The total size of the buffer pool, in pages. * `Innodb_buffer_pool_read_ahead' (`InnoDB Plugin' only) The number of pages read into the `InnoDB' buffer pool by the read-ahead background thread. This variable was added in MySQL 5.1.41. * `Innodb_buffer_pool_read_ahead_evicted' (`InnoDB Plugin' only) 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. This variable was added in MySQL 5.1.41. * `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. For `InnoDB Plugin', this variable was removed in MySQL 5.1.41. * `Innodb_buffer_pool_read_ahead_seq' The number of sequential read-aheads initiated by `InnoDB'. This happens when `InnoDB' does a sequential full table scan. For `InnoDB Plugin', this variable was removed in MySQL 5.1.41. * `Innodb_buffer_pool_read_requests' The number of logical read requests `InnoDB' has done. * `Innodb_buffer_pool_reads' The number of logical reads that `InnoDB' could not satisfy from the buffer pool, and had to read directly from the disk. * `Innodb_buffer_pool_wait_free' Normally, writes to the `InnoDB' buffer pool happen in the background. However, if it is necessary to read or create a page and no clean pages are available, it is also necessary to wait for pages to be flushed first. This counter counts instances of these waits. If the buffer pool size has been set properly, this value should be small. * `Innodb_buffer_pool_write_requests' The number writes done to the `InnoDB' buffer pool. * `Innodb_data_fsyncs' The number of `fsync()' operations so far. * `Innodb_data_pending_fsyncs' The current number of pending `fsync()' operations. * `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. * `Innodb_data_reads' The total number of data 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 for doublewrite operations. See *Note innodb-disk-io::. * `Innodb_dblwr_writes' The number of doublewrite operations that have been performed. See *Note innodb-disk-io::. * `Innodb_have_atomic_builtins' (`InnoDB Plugin' only) Indicates whether the server was built with atomic instructions. This variable was added in in MySQL 5.1.38. * `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 log write requests. * `Innodb_log_writes' The number of physical writes to the log file. * `Innodb_os_log_fsyncs' The number of `fsync()' writes done to the log file. * `Innodb_os_log_pending_fsyncs' The number of pending log file `fsync()' operations. * `Innodb_os_log_pending_writes' The number of pending log file writes. * `Innodb_os_log_written' The number of bytes written to the log file. * `Innodb_page_size' The compiled-in `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. * `Innodb_pages_read' The number of pages read. * `Innodb_pages_written' The number of pages written. * `Innodb_row_lock_current_waits' The number of row locks currently being waited for. * `Innodb_row_lock_time' The total time spent in acquiring row locks, in milliseconds. * `Innodb_row_lock_time_avg' The average time to acquire a row lock, in milliseconds. * `Innodb_row_lock_time_max' The maximum time to acquire a row lock, in milliseconds. * `Innodb_row_lock_waits' The number of times a row lock had to be waited for. * `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. * `Key_blocks_not_flushed' The number of key blocks in the key cache that have changed but have not yet been flushed to disk. * `Key_blocks_unused' The number of unused blocks in the 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 *Note server-system-variables::. * `Key_blocks_used' The number of used blocks in the 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 cache. * `Key_reads' The number of physical reads of a key block from disk. 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 cache. * `Key_writes' The number of physical writes of a key block 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 *Note `UNION': union. For the latter, the value is set to 0. * `Max_used_connections' The maximum number of connections that have been in use simultaneously since the server started. * `Not_flushed_delayed_rows' The number of rows waiting to be written in *Note `INSERT DELAYED': insert-delayed. queues. * `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. This variable was added in MySQL 5.1.3. * `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. This variable was added in MySQL 5.1.21. * `Opened_table_definitions' The number of `.frm' files that have been cached. This variable was added in MySQL 5.1.24. * `Opened_tables' The number of tables that have been opened. If `Opened_tables' is big, your `table_open_cache' value is probably too small. * `Prepared_stmt_count' The current number of prepared statements. (The maximum number of statements is given by the `max_prepared_stmt_count' system variable.) This variable was added in MySQL 5.1.14. * `Qcache_free_blocks' The number of free memory blocks in the query cache. * `Qcache_free_memory' The amount of free memory for the query cache. * `Qcache_hits' The number of query cache hits. * `Qcache_inserts' The number of queries added to the query cache. * `Qcache_lowmem_prunes' The number of queries that were deleted from the query cache because of low memory. * `Qcache_not_cached' The number of noncached queries (not cacheable, or not cached due to the `query_cache_type' setting). * `Qcache_queries_in_cache' The number of queries registered in the query cache. * `Qcache_total_blocks' The total number of blocks in the query cache. * `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. This variable was added in MySQL 5.1.31. * `Questions' The number of statements executed by the server. As of MySQL 5.1.31, this includes only statements sent to the server by clients and no longer includes 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. * `Rpl_status' The status of fail-safe replication (not implemented). This variable is unused and is removed in MySQL 5.6. * `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_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 *Note replication-features-temptables::. * `Slave_retried_transactions' The total number of times since startup that the replication slave SQL thread has retried transactions. * `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'. * `Slow_launch_threads' The number of threads that have taken more than `slow_launch_time' seconds to create. * `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 *Note 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 SSL cipher (empty for non-SSL connections). * `Ssl_cipher_list' The list of possible SSL ciphers. * `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_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 for replication SSL connections. * `Ssl_version' The SSL protocol version of the connection. * `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. * `Tc_log_max_pages_used' For the memory-mapped implementation of the log that is used by *Note `mysqld': 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. Currently, 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 capable of two-phase commit 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()'. Currently, 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. * `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. This variable was added in 5.1.24.  File: manual.info, Node: server-sql-mode, Next: server-plugins, Prev: server-status-variables, Up: mysqld-server 5.1.7 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. This capability enables each application to tailor the server's operating mode to its own requirements. For answers to some questions that are often asked about server SQL modes in MySQL, see *Note faqs-sql-modes::. 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. When working with `InnoDB' tables using the InnoDB Plugin, consider also the `innodb_strict_mode' configuration option. It enables additional error checks for `InnoDB' tables, as listed in InnoDB Strict Mode (http://dev.mysql.com/doc/refman/5.5/en/innodb-other-changes-strict-mode.html). * Setting the SQL Mode * The default SQL mode is empty (no modes set). 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. 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, use a `SET [GLOBAL|SESSION] sql_mode='MODES'' statement to set the `sql_mode' system variable. 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. Any client can change its own session `sql_mode' value at any time. To determine the current global or session `sql_mode' value, use the following statements: 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 master and slave can also lead to problems. For best results, you should always use the same server SQL mode on the master and on the slave. See *Note partitioning-limitations::, for more information. * 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 detail is given later in this section. * `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*: The *Note `INSERT': insert. or *Note `UPDATE': update. aborts as soon as the error is noticed. This may not be what you want if you are using a nontransactional storage engine, 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 where at least one of `STRICT_TRANS_TABLES' or `STRICT_ALL_TABLES' is enabled. * Full List of SQL Modes * The following list describes all supported 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 is 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). This mode applies to *Note `DATE': datetime. and *Note `DATETIME': datetime. columns. It does not apply *Note `TIMESTAMP': datetime. columns, which always require a valid date. 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 it is interpreted as an identifier. * `ERROR_FOR_DIVISION_BY_ZERO' Produce an error in strict mode (otherwise a warning) when a division by zero (or `MOD(X,0)') occurs during an *Note `INSERT': insert. or *Note `UPDATE': update. If this mode is not enabled, MySQL instead returns `NULL' for divisions by zero. For *Note `INSERT IGNORE': insert. or *Note `UPDATE IGNORE': update, MySQL generates a warning for divisions by zero, but the result of the operation is `NULL'. For *Note `SELECT': select, division by zero returns `NULL'. Enabling this mode causes a warning to be generated as well. * `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 *Note 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 *Note function-resolution::. * `NO_AUTO_CREATE_USER' Prevent the *Note `GRANT': grant. statement from automatically creating new users if it would otherwise do so, unless a nonempty password also is specified. * `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 *Note `mysqldump': 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. *Note `mysqldump': mysqldump. now automatically includes in its output a statement that enables `NO_AUTO_VALUE_ON_ZERO', to avoid this problem. * `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 *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. specifies a storage engine that is disabled or not compiled in. Up through MySQL 5.1.11, with `NO_ENGINE_SUBSTITUTION' disabled, the default engine is used and a warning occurs if the desired engine is known but disabled or not compiled in. If the desired engine is invalid (not a known engine name), an error occurs and the table is not created or altered. With `NO_ENGINE_SUBSTITUTION' enabled, an error occurs and the table is not created or altered if the desired engine is unavailable for any reason (whether disabled or invalid). As of MySQL 5.1.12, storage engines can be pluggable at runtime, so the distinction between disabled and invalid no longer applies. All unavailable engines are treated the same way: With `NO_ENGINE_SUBSTITUTION' disabled, for *Note `CREATE TABLE': create-table. the default engine is used and a warning occurs if the desired engine is unavailable. For *Note `ALTER TABLE': 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 *Note `SHOW CREATE TABLE': show-create-table. This mode is used by *Note `mysqldump': mysqldump. in portability mode. * `NO_KEY_OPTIONS' Do not print MySQL-specific index options in the output of *Note `SHOW CREATE TABLE': show-create-table. This mode is used by *Note `mysqldump': mysqldump. in portability mode. * `NO_TABLE_OPTIONS' Do not print MySQL-specific table options (such as `ENGINE') in the output of *Note `SHOW CREATE TABLE': show-create-table. This mode is used by *Note `mysqldump': mysqldump. in portability mode. * `NO_UNSIGNED_SUBTRACTION' By default, subtraction between integer operands produces an `UNSIGNED' result if any operand is`UNSIGNED'. 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 | | | 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) | | | 0 | | +-------+------------+------+-----+---------+-------+ Note that this means that `BIGINT UNSIGNED' is not 100% usable in all contexts. See *Note cast-functions::. mysql> SET sql_mode = ''; mysql> SELECT CAST(0 AS UNSIGNED) - 1; +-------------------------+ | CAST(0 AS UNSIGNED) - 1 | +-------------------------+ | 18446744073709551615 | +-------------------------+ mysql> SET sql_mode = 'NO_UNSIGNED_SUBTRACTION'; mysql> SELECT CAST(0 AS UNSIGNED) - 1; +-------------------------+ | CAST(0 AS UNSIGNED) - 1 | +-------------------------+ | -1 | +-------------------------+ * `NO_ZERO_DATE' In strict mode, do not permit `'0000-00-00'' as a valid date. You can still insert zero dates with the `IGNORE' option. When not in strict mode, the date is accepted but a warning is generated. * `NO_ZERO_IN_DATE' In strict mode, do not accept dates where the year part is nonzero but the month or day part is 0 (for example, `'0000-00-00'' is legal but `'2010-00-01'' and `'2010-01-00'' are not). If used with the `IGNORE' option, MySQL inserts a `'0000-00-00'' date for any such date. When not in strict mode, the date is accepted but a warning is generated. * `ONLY_FULL_GROUP_BY' Do not permit queries for which the select list or (as of MySQL 5.1.10) `HAVING' list refers to nonaggregated columns that are not named in the `GROUP BY' clause. The following queries are invalid with `ONLY_FULL_GROUP_BY' enabled. The first is invalid because `address' in the select list is not named in the `GROUP BY' clause, and the second because `max_age' in the `HAVING' clause is not named in the `GROUP BY' clause: mysql> SELECT name, address, MAX(age) FROM t GROUP BY name; ERROR 1055 (42000): 't.address' isn't in GROUP BY mysql> SELECT name, MAX(age) AS max_age FROM t GROUP BY name -> HAVING max_age < 30; Empty set (0.00 sec) ERROR 1463 (42000): Non-grouping field 'max_age' is used in HAVING clause In the second example, the query could be rewritten to use `HAVING MAX(age)' instead, so that the reference is to a column named in an aggregate function. (`max_age' fails because it _is_ an aggregate function.) In addition, if a query has aggregate functions and no `GROUP BY' clause, it cannot have nonaggregated columns in the select list or `ORDER BY' list: mysql> SELECT name, MAX(age) FROM t; ERROR 1140 (42000): Mixing of GROUP columns (MIN(),MAX(),COUNT(),...) with no GROUP columns is illegal if there is no GROUP BY clause For more information, see *Note group-by-extensions::. * `PAD_CHAR_TO_FULL_LENGTH' By default, trailing spaces are trimmed from *Note `CHAR': char. column values on retrieval. If `PAD_CHAR_TO_FULL_LENGTH' is enabled, trimming does not occur and retrieved *Note `CHAR': char. values are padded to their full length. This mode does not apply to *Note `VARCHAR': char. columns, for which trailing spaces are retained on retrieval. This mode was added in MySQL 5.1.20. 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 *Note `REAL': floating-point-types. as a synonym for *Note `FLOAT': floating-point-types. By default, MySQL treats *Note `REAL': floating-point-types. as a synonym for *Note `DOUBLE': floating-point-types. * `STRICT_ALL_TABLES' Enable strict mode for all storage engines. Invalid data values are rejected. Additional detail follows. * `STRICT_TRANS_TABLES' Enable strict mode for transactional storage engines, and when possible for nontransactional storage engines. Additional details follow. Strict mode controls how MySQL handles invalid or missing values in data-change statements such as *Note `INSERT': insert. or *Note `UPDATE': 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.) For statements that do not change data, such as *Note `SELECT': select, invalid values generate a warning in strict mode, not an error. For transactional tables, an error occurs for invalid or missing values in a data-change statement when either of the `STRICT_ALL_TABLES' or `STRICT_TRANS_TABLES' modes are 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 option is enabled: * For `STRICT_ALL_TABLES', MySQL returns an error and ignores the rest of the rows. However, in this case, the earlier rows still have been inserted or updated. This means that you might get a partial update, which might not be what you want. To avoid this, it is best to use single-row statements because these 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 insert 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 *Note data-type-defaults::. Strict mode disallows invalid date values such as `'2004-04-31''. It does not disallow dates with zero month or day parts such as `'2004-04-00'' or `zero' dates. To disallow these as well, enable the `NO_ZERO_IN_DATE' and `NO_ZERO_DATE' SQL modes in addition to strict mode. If you are not using strict mode (that is, neither `STRICT_TRANS_TABLES' nor `STRICT_ALL_TABLES' is enabled), MySQL inserts adjusted values for invalid or missing values and produces warnings. In strict mode, you can produce this behavior by using *Note `INSERT IGNORE': insert. or *Note `UPDATE IGNORE': update. See *Note show-warnings::. Strict mode does not affect whether foreign key constraints are checked. `foreign_key_checks' can be used for that. (See *Note server-system-variables::.) * Combination Modes * The following special modes are provided as shorthand for combinations of mode values from the preceding list. The descriptions include all mode values that are available in the most recent version of MySQL. For older versions, a combination mode does not include individual mode values that are not available except in newer versions. * `ANSI' Equivalent to `REAL_AS_FLOAT', `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE'. As of MySQL 5.1.18, `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)', as was always done prior to 5.1.18. See *Note ansi-mode::. * `DB2' Equivalent to `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE', `NO_KEY_OPTIONS', `NO_TABLE_OPTIONS', `NO_FIELD_OPTIONS'. * `MAXDB' Equivalent to `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE', `NO_KEY_OPTIONS', `NO_TABLE_OPTIONS', `NO_FIELD_OPTIONS', `NO_AUTO_CREATE_USER'. * `MSSQL' Equivalent to `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE', `NO_KEY_OPTIONS', `NO_TABLE_OPTIONS', `NO_FIELD_OPTIONS'. * `MYSQL323' Equivalent to `NO_FIELD_OPTIONS', `HIGH_NOT_PRECEDENCE'. * `MYSQL40' Equivalent to `NO_FIELD_OPTIONS', `HIGH_NOT_PRECEDENCE'. * `ORACLE' Equivalent to `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE', `NO_KEY_OPTIONS', `NO_TABLE_OPTIONS', `NO_FIELD_OPTIONS', `NO_AUTO_CREATE_USER'. * `POSTGRESQL' Equivalent to `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE', `NO_KEY_OPTIONS', `NO_TABLE_OPTIONS', `NO_FIELD_OPTIONS'. * `TRADITIONAL' Equivalent to `STRICT_TRANS_TABLES', `STRICT_ALL_TABLES', `NO_ZERO_IN_DATE', `NO_ZERO_DATE', `ERROR_FOR_DIVISION_BY_ZERO', `NO_AUTO_CREATE_USER'.  File: manual.info, Node: server-plugins, Next: server-side-help-support, Prev: server-sql-mode, Up: mysqld-server 5.1.8 Server Plugins -------------------- * Menu: * server-plugin-loading:: Installing and Uninstalling Plugins * obtaining-plugin-information:: Obtaining Server Plugin Information MySQL 5.1 and up 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, full-text parser plugins, partitioning support, and server extensions.  File: manual.info, Node: server-plugin-loading, Next: obtaining-plugin-information, Prev: server-plugins, Up: server-plugins 5.1.8.1 Installing and Uninstalling Plugins ........................................... Server plugins must be loaded in to the server before they can be used. MySQL enables you to load a plugin at server startup or at runtime. It is also possible to control the activation of loaded plugins at startup, and to unload them at runtime. * Installing plugins * Controlling plugin activation * Uninstalling plugins * Installing Plugins * Server plugins must be known to the server before they can be used. A plugin can be made known several ways, as described here. In the following descriptions, PLUGIN_NAME stands for a plugin name such as `innodb' or `csv'. *Built-in plugins:* A plugin that is built in to the server is known by the server automatically. Normally, the server enables the plugin at startup, although this can be changed with the `--PLUGIN_NAME' option. *Plugins registered in the `mysql.plugin' table:* The `mysql.plugin' table serves as a registry of plugins. The server normally enables each plugin listed in the table at startup, although whether a given plugin is enabled can be changed with the `--PLUGIN_NAME' option. If the server is started with the `--skip-grant-tables' option, it does not consult this table and does not load the plugins listed there. *Plugins named with the `--plugin-load' option:* A plugin that is located in a plugin library file can be loaded at server startup with the `--plugin-load' option. Normally, the server enables the plugin at startup, although this can be changed with the `--PLUGIN_NAME' option. The option value is a semicolon-separated list of `NAME=PLUGIN_LIBRARY' pairs. Each NAME is the name of the plugin, and PLUGIN_LIBRARY is the name of the shared library that contains the plugin code. If a plugin library is named without any preceding plugin name, the server loads all plugins in the library. Each library file must be located in the directory named by the `plugin_dir' system variable. This option does not register any plugin in the `mysql.plugin' table. For subsequent restarts, the server loads the plugin again only if `--plugin-load' is given again. That is, this option effects a one-time installation that persists only for one server invocation. `--plugin-load' enables plugins to be loaded even when `--skip-grant-tables' is given (which causes the server to ignore the `mysql.plugin' table). `--plugin-load' also enables plugins to be loaded at startup under configurations when plugins cannot be loaded at runtime. *Plugins installed with the *Note `INSTALL PLUGIN': install-plugin. statement:* A plugin that is 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, `INSTALL PLUGIN' requires the `INSERT' privilege for the `mysql.plugin' table. If a plugin is named both using a `--plugin-load' option and in the `mysql.plugin' table, the server starts but writes these messages to the error log: 100310 19:15:44 [ERROR] Function 'PLUGIN_NAME' already exists 100310 19:15:44 [Warning] Couldn't load plugin named 'PLUGIN_NAME' with soname 'PLUGIN_OBJECT_FILE'. Example: The `--plugin-load' option installs a plugin at server startup. To install a plugin named `myplugin' in 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 *Note `INSTALL PLUGIN': install-plugin. statement causes the server to load the plugin code from the library file at runtime: mysql> INSTALL PLUGIN myplugin SONAME 'somepluglib.so'; *Note `INSTALL PLUGIN': install-plugin. also causes `permanent' plugin registration: The server lists the plugin in the `mysql.plugin' table to ensure that it is loaded on subsequent server 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, use `--plugin-load' rather than *Note `INSTALL PLUGIN': install-plugin. While a plugin is loaded, information about it is available at runtime from several sources, such as the *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. table and the *Note `SHOW PLUGINS': show-plugins. statement. For more information, see *Note obtaining-plugin-information::. * Controlling Plugin Activation * If the server knows about a plugin when it starts (for example, because the plugin is named using a `--plugin-load' option or registered in the `mysql.plugin' table), the server loads and enables the plugin by default. It is possible to control activation for such a plugin using a `--PLUGIN_NAME[=VALUE]' startup option named after the plugin. In the following descriptions, PLUGIN_NAME stands for a plugin name such as `innodb' or `csv'. As with other options, dashes and underscores are interchangeable in option names. For example, `--my_plugin=ON' and `--my-plugin=ON' are equivalent. As of MySQL 5.1.36, these options control plugin loading: * `--PLUGIN_NAME=OFF' Tells the server to disable the plugin. * `--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. The values `OFF', `ON', and `FORCE' are not case sensitive. 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, but must require that `BLACKHOLE' initialization succeeds, and `ARCHIVE' should be disabled. To accomplish that, use these lines in an option file: [mysqld] csv=ON blackhole=FORCE archive=OFF The `--enable-PLUGIN_NAME' option format is supported as a synonym for `--PLUGIN_NAME=ON'. The `--disable-PLUGIN_NAME' and `--skip-PLUGIN_NAME' option formats are supported as synonyms for `--PLUGIN_NAME=OFF'. Before MySQL 5.1.36, plugin options are boolean options (see *Note option-modifiers::). That is, any of these options enable the plugin: --PLUGIN_NAME --PLUGIN_NAME=1 --enable-PLUGIN_NAME And these options disable the plugin: --PLUGIN_NAME=0 --disable-PLUGIN_NAME --skip-PLUGIN_NAME If you upgrade to MySQL 5.1.36 or later from an older version and previously used options of the form `--PLUGIN_NAME=0' or `--PLUGIN_NAME=1', the equivalent options are now `--PLUGIN_NAME=OFF' and `--PLUGIN_NAME=ON', respectively. You also have the choice of requiring plugins to start successfully by using `--PLUGIN_NAME=FORCE'. 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 has been 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 *Note `InnoDB': innodb-storage-engine, other `innodb_XXX' options likely will need to be omitted from the startup command. In addition, if the server is configured to use *Note `InnoDB': innodb-storage-engine. as the default storage engine, it will not start unless you specify another available storage engine with `--default-storage-engine'. * Uninstalling Plugins * A plugin known to the server can be uninstalled to disable it at runtime with the *Note `UNINSTALL PLUGIN': uninstall-plugin. statement. The statement unloads the plugin and removes it from the `mysql.plugin' table if it is registered there. For this reason, *Note `UNINSTALL PLUGIN': 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. *Note `UNINSTALL PLUGIN': uninstall-plugin. can unload plugins regardless of whether they were loaded with *Note `INSTALL PLUGIN': install-plugin. or `--plugin-load'. *Note `UNINSTALL PLUGIN': uninstall-plugin. 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 *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. or *Note `SHOW PLUGINS': show-plugins.  File: manual.info, Node: obtaining-plugin-information, Prev: server-plugin-loading, Up: server-plugins 5.1.8.2 Obtaining Server Plugin Information ........................................... There are several ways to determine which plugins are installed in the server: * The *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. 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 ... *************************** 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 ... * The *Note `SHOW PLUGINS': 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 *Note `INSTALL PLUGIN': install-plugin. The table contains only plugin names and library file names, so it does not provide as much information as the *Note `PLUGINS': plugins-table. table or the *Note `SHOW PLUGINS': show-plugins. statement.  File: manual.info, Node: server-side-help-support, Next: server-signal-response, Prev: server-plugins, Up: mysqld-server 5.1.9 Server-Side Help ---------------------- MySQL Server supports a *Note `HELP': help. statement that returns online information from the MySQL Reference manual (see *Note help::). The proper operation of this statement requires that the help tables in the `mysql' database be initialized with help topic information, 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 setup occurs when you run *Note `mysql_install_db': mysql-install-db. For an RPM distribution on Linux or binary distribution on Windows, help table setup occurs as part of the MySQL installation process. If you upgrade MySQL using a binary distribution, the help tables are not upgraded automatically, but you can upgrade them 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 *Note `mysql': 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 *Note `mysql': mysql. as described previously. If you are working with Bazaar and a MySQL development source tree, you will need to download the `fill_help_tables.sql' file because the tree contains only a `stub' version.  File: manual.info, Node: server-signal-response, Next: server-shutdown, Prev: server-side-help-support, Up: mysqld-server 5.1.10 Server Response to Signals --------------------------------- On Unix, signals can be sent to processes. *Note `mysqld': 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 *Note `FLUSH': 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 On some Mac OS X 10.3 versions, *Note `mysqld': mysqld. ignores `SIGHUP' and `SIGQUIT'.  File: manual.info, Node: server-shutdown, Prev: server-signal-response, Up: mysqld-server 5.1.11 The 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 *Note `mysqladmin shutdown': mysqladmin. command. *Note `mysqladmin': 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 *Note kill::, in particular for the instructions about killed *Note `REPAIR TABLE': repair-table. or *Note `OPTIMIZE TABLE': optimize-table. operations on `MyISAM' tables. For threads that have an open transaction, the transaction is rolled back. Note that if a thread is updating a nontransactional table, an operation such as a multiple-row *Note `UPDATE': update. or *Note `INSERT': 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. In MySQL 5.1.34 and earlier, if the SQL thread was in the middle of a transaction at this point, the transaction was rolled back; in MySQL 5.1.35 and later, the server waits until the current replication event group (if any) has finished executing, or until the user issues a *Note `KILL QUERY': kill. or *Note `KILL CONNECTION': kill. statement. See also *Note stop-slave::. If the slave is updating a nontransactional table when it is forcibly killed, the slave's data may become inconsistent with the master. 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. For example, `MyISAM' flushes any pending index writes for a table. `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. 6. The server exits.  File: manual.info, Node: server-logs, Next: multiple-servers, Prev: mysqld-server, Up: server-administration 5.2 MySQL Server Logs ===================== * Menu: * log-destinations:: Selecting General Query and Slow Query Log Output Destinations * error-log:: The Error Log * query-log:: The General Query Log * binary-log:: The Binary Log * slow-query-log:: The Slow Query Log * log-file-maintenance:: Server Log Maintenance MySQL Server has several logs that can help you find out what activity is taking place. This table lists MySQL Server log types and describes the information written to each log. Log Type Information Written to Log Error log Problems encountered starting, running, or stopping *Note `mysqld': 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 By default, no logs are enabled (except the error log on Windows). 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 *Note `FLUSH LOGS': flush. statement; execute *Note `mysqladmin': mysqladmin. with a `flush-logs' or `refresh' argument; or execute *Note `mysqldump': mysqldump. with a `--flush-logs' or `--master-data' option. See *Note flush::, *Note mysqladmin::, and *Note 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 *Note log-destinations::, *Note query-log::, and *Note 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 *Note slave-logs-relaylog::. For information about log maintenance operations such as expiration of old log files, see *Note log-file-maintenance::. For information about keeping logs secure, see *Note password-logging::.  File: manual.info, Node: log-destinations, Next: error-log, Prev: server-logs, Up: server-logs 5.2.1 Selecting General Query and Slow Query Log Output Destinations -------------------------------------------------------------------- As of MySQL 5.1.6, 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 the `general_log' and `slow_log' tables in the `mysql' database. Either or both destinations can be selected. (Before MySQL 5.1.6, the server uses only log files as the destination for general query log and slow query log entries.) *Note*: For new installations of MySQL 5.1.6 or higher, the log tables are created during the installation procedure along with the other system tables. If you upgrade MySQL from a release older than 5.1.6 to MySQL 5.1.6 or higher, you must upgrade the system tables after upgrading to make sure that the log tables exist. See *Note mysql-upgrade::. Currently, logging to tables incurs significantly more server overhead than logging to files. If you enable the general log or slow query log and require highest performance, you should use file logging, not table logging. *Log control at server startup.* The `--log-output' option specifies the destination for log output, if logging is enabled. 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 or given without a value, the default is `FILE'. (For MySQL 5.1.6 through 5.1.20, the default logging destination is `TABLE'.) 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. Prior to MySQL 5.1.29, the `--log' and `--log-slow-queries' options enable the general query log and slow query log. Either option may be given with a file name argument to specify a log file name to override the default. 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. As of MySQL 5.1.29, you can set these variables at server startup or at runtime to change the names of the log files. Before MySQL 5.1.29, you can set these variables only at runtime, but the `--log' and `--log-slow-queries' options can be given with a file name argument at startup to change the log file names from their default values. * 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. * *Note `CREATE TABLE': create-table, *Note `ALTER TABLE': alter-table, and *Note `DROP TABLE': drop-table. are valid operations on a log table. For *Note `ALTER TABLE': alter-table. and *Note `DROP TABLE': 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. Beginning with MySQL 5.1.12, the log tables can be altered to use the `MyISAM' storage engine. You cannot use *Note `ALTER TABLE': 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; * *Note `TRUNCATE TABLE': truncate-table. is a valid operation on a log table. It can be used to expire log entries. * As of MySQL 5.1.13, *Note `RENAME TABLE': 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; * *Note `LOCK TABLES': lock-tables. cannot be used on a log table. * *Note `INSERT': insert, *Note `DELETE': delete, and *Note `UPDATE': update. cannot be used on a log table. These operations are permitted only internally to the server itself. * *Note `FLUSH TABLES WITH READ LOCK': flush. and the state of the global `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 *Note `FLUSH TABLES': flush. or *Note `FLUSH LOGS': flush, respectively. (From MySQL 5.1.12 to 5.1.20, *Note `FLUSH TABLES': flush. ignores log tables and *Note `FLUSH LOGS': flush. flushes both the log tables and files.) * Partitioning of log tables is not permitted beginning with MySQL 5.1.20, and not recommended before that. * Before MySQL 5.1.64, *Note `mysqldump': mysqldump. does not dump the `general_log' or `slow_query_log' tables for dumps of the `mysql' database. As of 5.1.64, the dump includes statements to recreate those tables so that they are not missing after reloading the dump file. Log table contents are not dumped.  File: manual.info, Node: error-log, Next: query-log, Prev: log-destinations, Up: server-logs 5.2.2 The Error Log ------------------- The error log contains information indicating when *Note `mysqld': mysqld. was started and stopped and also any critical errors that occur while the server is running. If *Note `mysqld': mysqld. notices a table that 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 *Note `mysqld': mysqld. dies. The trace can be used to determine where *Note `mysqld': mysqld. died. See *Note porting::. In the following discussion, `console' means `stderr', the standard error output; this is your terminal or console window unless the standard error output has been redirected. (For example, if invoked with the `--syslog' option, *Note `mysqld_safe': mysqld-safe. arranges for the server's `stderr' to be sent to the `syslog' facility, as described later.) On Windows, the `--log-error' and `--console' options both affect error logging: * Without `--log-error', *Note `mysqld': mysqld. writes error messages to `HOST_NAME.err' in the data directory. * With `--log-error[=FILE_NAME]', *Note `mysqld': mysqld. writes error messages to an error log file. The server uses the named file if present, creating it in in the data directory unless an absolute path name is given to specify a different directory. If no file is named, the default name is `HOST_NAME.err' in the data directory. * If `--console' is given, *Note `mysqld': mysqld. writes error messages to the console, unless `--log-error' is also given. If both options are present, the last one takes precedence. In addition, on Windows, events and error messages are written to the Windows Event Log within the Application log. Entries marked as `Warning' and `Note' are written to the Event Log, but not informational messages such as information statements from individual storage engines. These log entries have a source of `MySQL'. You cannot disable writing information to the Windows Event Log. On Unix and Unix-like systems, *Note `mysqld': mysqld. writes error log messages as follows: * Without `--log-error', *Note `mysqld': mysqld. writes error messages to the console. * With `--log-error[=`file_name']', *Note `mysqld': mysqld. writes error messages to an error log file. The server uses the named file if present, creating it in the data directory unless an absolute path name is given to specify a different directory. If no file is named, the default name is `HOST_NAME.err' in the data directory. At runtime, `log_error' system variable indicates the the error log file name if error output is written to a file. If you flush the logs using *Note `FLUSH LOGS': flush. or *Note `mysqladmin flush-logs': mysqladmin. and *Note `mysqld': mysqld. is writing the error log to a file (for example, if it was started with the `--log-error' option), the effect is version dependent: * As of MySQL 5.1.51, the server closes and reopens the log file. To rename the file, do so manually before flushing. Then flushing the logs reopens a new file with the original file name. For example, to rename the file and create a new one, use the following commands: shell> mv HOST_NAME.err HOST_NAME.err-old shell> mysqladmin flush-logs shell> mv HOST_NAME.err-old BACKUP-DIRECTORY On Windows, use `rename' rather than `mv'. * Prior to MySQL 5.1.51, the server renames the current log file with the suffix `-old', then creates a new empty log file. Be aware that a second log-flushing operation thus causes the original error log file to be lost unless you save it under a different name. On Windows, you cannot rename the error log while the server has it open before MySQL 5.1.51. To avoid a restart, flush the logs first to cause the server to rename the original file and create a new one, then save the renamed file. That also works on Unix, or you can use the commands shown earlier. No error log renaming occurs when the logs are flushed in any case if the server is not writing to a named file. If you use *Note `mysqld_safe': mysqld-safe. to start *Note `mysqld': mysqld, *Note `mysqld_safe': mysqld-safe. arranges for *Note `mysqld': mysqld. to write error messages to a log file or (as of MySQL 5.1.20) to `syslog': * Before 5.1.20, *Note `mysqld_safe': mysqld-safe. behavior is to log to a file, using the default error log file if the `--log-error' option is not given to *Note `mysqld_safe': mysqld-safe. Otherwise, *Note `mysqld_safe': mysqld-safe. uses the file name specified using `--log-error=FILE_NAME'. * From 5.1.20 on, *Note `mysqld_safe': mysqld-safe. has two additional error-logging options, `--syslog' and `--skip-syslog'. In 5.1.21 and up, the default with no logging options is `--skip-syslog', which is compatible with the default behavior of writing an error log file for releases prior to 5.1.20. To explicitly specify use of an error log file, specify `--log-error=FILE_NAME' to *Note `mysqld_safe': mysqld-safe, and *Note `mysqld_safe': mysqld-safe. will arrange for *Note `mysqld': mysqld. to write messages to a log file. To use `syslog' instead, specify the `--syslog' option. *In 5.1.20 _only_, the following conditions apply*: 1) The default is to use `syslog', which is not compatible with releases prior to 5.1.20. 2) Logging to `syslog' may fail to operate correctly in some cases; if so, use `--skip-syslog' or `--log-error'. For logging to `syslog', messages from *Note `mysqld_safe': mysqld-safe. and *Note `mysqld': mysqld. are written with a tag of `mysqld_safe' and `mysqld', respectively. As of MySQL 5.1.21, to specify a suffix for the tag, use `--syslog-tag=TAG', which modifies the tags to be `mysqld_safe-TAG' and `mysqld-TAG'. If you specify `--log-error' in an option file in a `[mysqld]', `[server]', or `[mysqld_safe]' section, *Note `mysqld_safe': mysqld-safe. will find and use the option. If *Note `mysqld_safe': mysqld-safe. is used to start *Note `mysqld': mysqld. and *Note `mysqld': mysqld. dies unexpectedly, *Note `mysqld_safe': mysqld-safe. notices that it needs to restart *Note `mysqld': mysqld. and writes a `restarted mysqld' message to the error log. The `--log-warnings' option or `log_warnings' system variable can be used to control warning logging to the error log. The default value is enabled (1). Warning logging can be disabled using a value of 0. If the value is greater than 1, aborted connections are written to the error log. See *Note communication-errors::.  File: manual.info, Node: query-log, Next: binary-log, Prev: error-log, Up: server-logs 5.2.3 The General Query Log --------------------------- The general query log is a general record of what *Note `mysqld': 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 *Note `mysqld': mysqld. *Note `mysqld': 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 logging all statements are written to the query log, but when using row-based 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 *Note replication-sbr-rbr::, for more information. Control the general query log at server startup as follows: * Before 5.1.6, the general query log destination is always a file. To enable the log, start *Note `mysqld': mysqld. with the `--log[=FILE_NAME]' or `-l [FILE_NAME]' option. * As of MySQL 5.1.6, the destination can be a file or a table, or both. Start *Note `mysqld': mysqld. with the `--log[=FILE_NAME]' or `-l [FILE_NAME]' option to enable the general query log, and optionally use `--log-output' to specify the log destination (as described in *Note log-destinations::). * As of MySQL 5.1.12, as an alternative to `--log' or `-l', use `--general_log[={0|1}]' to specify the initial general query log state. In this case, the default general query log file name is used. With no argument or an argument of 1, `--general_log' enables the log. With an argument of 0, this option disables the log. * As of MySQL 5.1.29, use `--general_log[={0|1}]' to enable or disable the general query log, and optionally `--general_log_file=FILE_NAME' to specify a log file name. The `--log' and `-l' options are deprecated. If the general query log file is enabled but no name is specified, the default name is `HOST_NAME.log' and the server creates the file in the same directory where it creates the PID file. If a name is given, 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). On Unix, you can rename the file and create a new one by using 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, you cannot rename the general query log file while the server has it open before MySQL 5.1.3. You must stop the server, rename the file, and then restart the server to create a new log file. As of MySQL 5.1.12, you can 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. The general query log should be protected because logged statements might contain passwords. See *Note password-logging::.  File: manual.info, Node: binary-log, Next: slow-query-log, Prev: query-log, Up: server-logs 5.2.4 The Binary Log -------------------- * Menu: * binary-log-formats:: Binary Logging Formats * binary-log-setting:: Setting The Binary Log Format * binary-log-mixed:: Mixed Binary Logging Format * binary-log-mysql-database:: Logging Format for Changes to `mysql' Database Tables 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 *Note `DELETE': 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 *Note 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 *Note point-in-time-recovery::. The binary log is not used for statements such as *Note `SELECT': select. or *Note `SHOW': show. that do not modify data. To log all statements (for example, to identify a problem query), use the general query log. See *Note 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 should be protected because logged statements might contain passwords. See *Note 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 *Note 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 basename is given, the server writes the file in the data directory unless the basename is given with a leading absolute path name to specify a different directory. It is recommended that you specify a basename explicitly rather than using the default of the host name; see *Note bugs::, for the reason. *Note*: From MySQL 5.1.18 through 5.1.22, `mysql' was used when no BASE_NAME was specified. Also in these versions, a path given as part of the `--log-bin' options was treated as absolute rather than relative. The previous behaviors were restored in MySQL 5.1.23. (See Bug #28603 and Bug #28597.) If you supply an extension in the log name (for example, `--log-bin=BASE_NAME.EXTENSION'), the extension is silently removed and ignored. *Note `mysqld': mysqld. appends a numeric extension to the binary log basename 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, *Note `mysqld': mysqld. also creates a binary log index file that contains the names of all used binary log files. By default, this has the same basename 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 *Note `mysqld': mysqld. is running; doing so would confuse *Note `mysqld': 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 *Note server-system-variables::. 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 *Note 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 *Note replication-rules-db-options::. If you are replicating from a MySQL Cluster to a standalone MySQL Server, you should be aware that the the *Note `NDB': mysql-cluster. storage engine uses default values for some binary logging options (including options specific to `NDB' such as `--ndb-log-update-as-write') that differ from those used by other storage engines. If not corrected for, these differences can lead to divergence of the master's and slave's binary logs. For more information, see *Note mysql-cluster-replication-ndb-to-non-ndb::. In particular, if you are using a nontransactional storage engine such as *Note `MyISAM': myisam-storage-engine. on the slave, see *Note mysql-cluster-replication-ndb-to-nontransactional::. 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 *Note 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 *Note `RESET MASTER': reset-master. statement, or a subset of them with *Note `PURGE BINARY LOGS': purge-binary-logs. See *Note reset::, and *Note 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 *Note `mysqladmin flush-logs': mysqladmin. 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 *Note `PURGE BINARY LOGS': purge-binary-logs, which also safely updates the binary log index file for you (and which can take a date argument). See *Note purge-binary-logs::. You can display the contents of binary log files with the *Note `mysqlbinlog': 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 *Note `mysqlbinlog': 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 *Note `mysqlbinlog': mysqlbinlog. utility and how to use it, see *Note mysqlbinlog::. For more information about the binary log and recovery operations, see *Note 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. In MySQL 5.1.22 and earlier versions of MySQL 5.1, an *Note `UPDATE': update. statement using a stored function that modified a nontransactional table was not logged if it failed, and an *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. statement that encountered a duplicate key constraint--but did not actually change any data--was not logged. Beginning with MySQL 5.1.23, both of these statements are written to the binary log. (Bug #23333) Within an uncommitted transaction, all updates (*Note `UPDATE': update, *Note `DELETE': delete, or *Note `INSERT': insert.) that change transactional tables such as `InnoDB' tables are cached until a *Note `COMMIT': commit. statement is received by the server. At that point, *Note `mysqld': mysqld. writes the entire transaction to the binary log before the *Note `COMMIT': 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 *Note `ROLLBACK': commit. 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 *Note `INSERT ... SELECT': 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 *Note replication-features::. Binary logging for stored programs is done as described in *Note stored-programs-logging::. Note that the binary log format differs in MySQL 5.1 from previous versions of MySQL, due to enhancements in replication. See *Note 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 *Note full-disk::. By default, the binary log is not synchronized to disk at each write. So if the operating system or machine (not only the MySQL server) crashes, there is a chance that the last statements of the binary log are lost. To prevent this, you can make the binary log be synchronized to disk after every N writes to the binary log, with the `sync_binlog' system variable. See *Note server-system-variables::. 1 is the safest value for `sync_binlog', but also the slowest. Even with `sync_binlog' set to 1, there is still the chance of an inconsistency between the table content and binary log content in case of a crash. For example, if you are using `InnoDB' tables and the MySQL server processes a *Note `COMMIT': commit. statement, it writes the whole transaction to 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. To resolve this, you should set `--innodb_support_xa' to 1. 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 at every 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 cuts rolled back `InnoDB' transactions from the binary log. This ensures that the binary log reflects the exact data of `InnoDB' tables, and so, that the slave remains in synchrony with the master (not receiving a statement which has been rolled back). 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. For MySQL 5.1.20 and later (and MySQL 5.0.46 and later for backward compatibility), 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 *Note replication-features-variables::) * `foreign_key_checks' * `unique_checks' * `character_set_client' * `collation_connection' * `collation_database' * `collation_server' * `sql_auto_is_null'  File: manual.info, Node: binary-log-formats, Next: binary-log-setting, Prev: binary-log, Up: binary-log 5.2.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. 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 *Note `mysqld': mysqld. with the option `--binlog-format=MIXED'. Support for row-based logging was added in MySQL 5.1.5. Mixed logging is available beginning with MySQL 5.1.8. In MySQL 5.1.12, `MIXED' become the default logging mode; in 5.1.29, the default was changed back to `STATEMENT' for compatibility with MySQL 5.0. Starting with MySQL 5.1.20, 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 that 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'. Prior to MySQL 5.1.36, this warning read, `Statement is not safe to log in statement format'. (Bug #42415) You can avoid these issues by using MySQL's row-based replication instead.  File: manual.info, Node: binary-log-setting, Next: binary-log-mixed, Prev: binary-log-formats, Up: binary-log 5.2.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 default binary logging format depends on the version of MySQL you are using: * For MySQL 5.1.11 and earlier, and for MySQL 5.1.29 and later, statement-based logging is used by default. * For MySQL 5.1.12 through MySQL 5.1.28, mixed logging is used by default. Exception For all MySQL Cluster releases using version 6.1 or later of the *Note `NDBCLUSTER': mysql-cluster. storage engine (even those releases based on MySQL 5.1.29 and later), the default binary log format is `MIXED'. See *Note mysql-cluster-replication::. The logging format also can be switched at runtime. To specify the format globally for all clients, set the global value of the `binlog_format' system variable: 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 thus cause unexpected results, or even cause replication to fail altogether. To change the global `binlog_format' value, you must have the `SUPER' privilege. This is also true for the session value as of MySQL 5.1.29. In addition to switching the logging format manually, a slave server may switch the format _automatically_. This happens when the server is running in either `STATEMENT' or `MIXED' format and encounters an event in the binary log that is written in `ROW' logging format. In that case, the slave switches to row-based replication temporarily for that event, and switches back to the previous format afterward. 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 *Note `NDBCLUSTER': mysql-cluster. 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 *Note `InnoDB': innodb-storage-engine. 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 *Note `CREATE TABLE': create-table, *Note `ALTER TABLE': alter-table, or *Note `DROP TABLE': 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 1024. *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 *Note bugs::.  File: manual.info, Node: binary-log-mixed, Next: binary-log-mysql-database, Prev: binary-log-setting, Up: binary-log 5.2.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 DML statement updates an *Note `NDBCLUSTER': mysql-cluster. table. * When a function contains `UUID()'. * Prior to MySQL 5.1.40, when two or more tables with `AUTO_INCREMENT' columns are updated. As of 5.1.40, when one or more tables with `AUTO_INCREMENT' columns are updated and a trigger or stored function is invoked. Unlike other unsafe statements, this does not generate a warning if `binlog_format = STATEMENT'. For more information, see *Note replication-features-auto-increment::. * When any *Note `INSERT DELAYED': insert-delayed. is executed. * 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. * Beginning with MySQL 5.1.23: * When `FOUND_ROWS()' or `ROW_COUNT()' is used. (Bug #12092, Bug #30244) * When `USER()', `CURRENT_USER()', or `CURRENT_USER' is used. (Bug #28086) * Beginning with MySQL 5.1.24, 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 *Note using-system-variables::. For information about how replication treats `sql_mode', see *Note replication-features-variables::. * Beginning with MySQL 5.1.30, when one of the tables involved is a log table in the `mysql' database. * Beginning with MySQL 5.1.34, when the `LOAD_FILE()' function is used. (Bug #39701) *Note*: Starting with MySQL 5.1.20, 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 *Note `SHOW WARNINGS': show-warnings.) and through the *Note `mysqld': mysqld. error log. A warning is added to the *Note `SHOW WARNINGS': 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. Starting with MySQL 5.1.20, 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 logging formats supported by each storage engine. This table lists the logging formats supported by each storage engine. Storage Engine Row Logging Statement Logging Supported 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 *Note `NDBCLUSTER': mysql-cluster. Yes No When determining the logging mode to be used, the capabilities of all the tables affected by the event are combined. The set of affected tables is then marked according to these rules: * A set of tables is defined as _row-logging restricted_ if the tables are row-logging capable but not statement-logging capable. * A set of tables is defined as _statement-logging restricted_ if the tables are statement-logging capable but not row-logging capable. Once the determination of the possible logging formats required by the statement is complete it is compared to the current `binlog_format' setting. The following table is used to decide how the information is recorded in the binary log or, if appropriate, whether an error is raised. In the table, a safe operation is defined as one that is deterministic. Several rules decide whether the statement is deterministic, as shown in the following table, where *SLR* stands for `statement-logging restricted' and *RLR* stands for `row-logging restricted'. A statement is _statement-logging restricted_ if one or more of the tables it accesses is not row-logging capable. Similarly, a statement is _row-logging restricted_ if any table accessed by the statement is not statement-logging capable. The information in this table is used to determine how information is recorded in the binary log or, if appropriate, whether an error is raised. The table outlines conditions (Safe/unsafe, `binlog_format', SLR, RLR) and corresponding actions. ConditionAction Safe/unsafe`binlog_format' SLR RLR Error/Warning Logged as Safe `STATEMENT' Yes Yes `Error: not loggable' Safe `STATEMENT' Yes No `STATEMENT' Safe `STATEMENT' No Yes `Error: not loggable' Safe `STATEMENT' No No `STATEMENT' Safe `MIXED' Yes Yes `Error: not loggable' Safe `MIXED' Yes No `STATEMENT' Safe `MIXED' No Yes `ROW' Safe `MIXED' No No `STATEMENT' Safe `ROW' Yes Yes `Error: not loggable' Safe `ROW' Yes No `Error: not loggable' Safe `ROW' No Yes `ROW' Safe `ROW' No No `ROW' Unsafe `STATEMENT' Yes Yes `Error: not loggable' Unsafe `STATEMENT' Yes No `Warning: `STATEMENT' unsafe' Unsafe `STATEMENT' No Yes `Error: not loggable' Unsafe `STATEMENT' No No `Warning: `STATEMENT' unsafe' Unsafe `MIXED' Yes Yes `Error: not loggable' Unsafe `MIXED' Yes No `Error: not loggable' Unsafe `MIXED' No Yes `ROW' Unsafe `MIXED' No No `ROW' Unsafe `ROW' Yes Yes `Error: not loggable' Unsafe `ROW' Yes No `Error: not loggable' Unsafe `ROW' No Yes `ROW' Unsafe `ROW' No No `ROW' When a warning is produced by the determination, a standard MySQL warning is produced (and is available using *Note `SHOW WARNINGS': show-warnings.). The information is also written to the *Note `mysqld': 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 was 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.  File: manual.info, Node: binary-log-mysql-database, Prev: binary-log-mixed, Up: binary-log 5.2.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 *Note `INSERT': insert. or *Note `DELETE': delete.) or indirectly (for example, with *Note `GRANT': grant. or *Note `CREATE USER': create-user.). As of MySQL 5.1.17, 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 *Note `INSERT': insert, *Note `UPDATE': update, *Note `DELETE': delete, *Note `REPLACE': replace, *Note `DO': do, *Note `LOAD DATA INFILE': load-data, *Note `SELECT': select, and *Note `TRUNCATE TABLE': 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 *Note `GRANT': grant, *Note `REVOKE': revoke, *Note `SET PASSWORD': set-password, *Note `RENAME USER': rename-user, `CREATE' (all forms except *Note `CREATE TABLE ... SELECT': create-table.), `ALTER' (all forms), and `DROP' (all forms). *Note `CREATE TABLE ... SELECT': create-table. is a combination of data definition and data manipulation. The *Note `CREATE TABLE': create-table. part is logged using statement format and the *Note `SELECT': select. part is logged according to the value of `binlog_format'.  File: manual.info, Node: slow-query-log, Next: log-file-maintenance, Prev: binary-log, Up: server-logs 5.2.5 The Slow Query Log ------------------------ The slow query log consists of SQL statements that took more than `long_query_time' seconds to execute and (as of MySQL 5.1.21) required at least `min_examined_row_limit' rows to be examined. The default value of `long_query_time' is 10. Beginning with MySQL 5.1.21, the minimum is 0, and 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. Prior to MySQL 5.1.21, the minimum value is 1, and the value for this variable must be an integer. 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. *Note `mysqld': 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. Control the slow query log at server startup as follows: * Before 5.1.6, the slow query log destination is always a file. To enable the log, start *Note `mysqld': mysqld. with the `--log-slow-queries[=FILE_NAME]' option. * As of MySQL 5.1.6, the destination can be a file or a table, or both. Start *Note `mysqld': mysqld. with the `--log-slow-queries[=FILE_NAME]' option to enable the slow query log, and optionally use `--log-output' to specify the log destination (as described in *Note log-destinations::). * As of MySQL 5.1.12, as an alternative to `--log-slow-queries', use `--slow_query_log[={0|1}]' to specify the initial slow query log state. In this case, the default slow query log file name is used. With no argument or an argument of 1, `--slow_query_log' enables the log. With an argument of 0, this option disables the log. * As of MySQL 5.1.29, use `--slow_query_log[={0|1}]' to enable or disable the slow query log, and optionally `--slow_query_log_file=FILE_NAME' to specify a log file name. The `--log-slow-queries' option is deprecated. If the slow query log file is enabled but no name is specified, the default name is `HOST_NAME-slow.log' and the server creates the file in the same directory where it creates the PID file. If a name is given, 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 (and binary 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' server option. Administrative statements include *Note `ALTER TABLE': alter-table, *Note `ANALYZE TABLE': analyze-table, *Note `CHECK TABLE': check-table, *Note `CREATE INDEX': create-index, *Note `DROP INDEX': drop-index, *Note `OPTIMIZE TABLE': optimize-table, and *Note `REPAIR TABLE': repair-table. To include queries that do not use indexes for row lookups in the statements written to the slow query log, use the `--log-queries-not-using-indexes' server option. See *Note server-options::. When such queries are logged, the slow query log may grow quickly. 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 have been specified. 2. The query must have taken at least `long_query_time' seconds, or `--log-queries-not-using-indexes' must have been specified and the query used no indexes for row lookups. 3. The query must have examined at least `min_examined_row_limit' rows. 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. Prior to MySQL 5.1.45, replication slaves did not write replicated queries to the slow query log, even if the same queries were written to the slow query log on the master. (Bug #23300) In MySQL 5.1.45 and later, this behavior can be overridden using the `--log-slow-slave-statements' option. The slow query log should be protected because logged statements might contain passwords. See *Note 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 *Note `mysqldumpslow': mysqldumpslow. command to summarize the queries that appear in the log. See *Note mysqldumpslow::.  File: manual.info, Node: log-file-maintenance, Prev: slow-query-log, Up: server-logs 5.2.6 Server Log Maintenance ---------------------------- As described in *Note 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 *Note 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 *Note 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 *Note `PURGE BINARY LOGS': purge-binary-logs. statement (see *Note purge-binary-logs::). You can force MySQL to start using new log files by flushing the logs. Log flushing occurs when you issue a *Note `FLUSH LOGS': flush. statement or execute a *Note `mysqladmin flush-logs': mysqladmin, *Note `mysqladmin refresh': mysqladmin, *Note `mysqldump --flush-logs': mysqldump, or *Note `mysqldump --master-data': mysqldump. command. See *Note flush::, *Note mysqladmin::, and *Note mysqldump::. In addition, the binary log is flushed when its size reaches the value of the `max_binlog_size' system variable. 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 result of a log-flushing operation is version dependent: * As of MySQL 5.1.51, the server closes and reopens the log file. * Prior to MySQL 5.1.51, the server renames the current log file with the suffix `-old', then creates a new empty 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. As of MySQL 5.1.12, 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. For older versions of MySQL on Windows, you cannot rename certain log files while the server has them open. Before MySQL 5.1.3, this restriction applies to all log files. You must stop the server, rename the file, then restart the server to create a new log file. From 5.1.4 to 5.1.50, the restriction applies only to the error log file. To rename the error log file, a stop and restart can be avoided by flushing the logs to cause the server to rename the current log file with the suffix `-old' and create a new empty error log file. For further information, see *Note error-log::.  File: manual.info, Node: multiple-servers, Prev: server-logs, Up: server-administration 5.3 Running Multiple MySQL Instances on One Machine =================================================== * Menu: * multiple-data-directories:: Setting Up Multiple Data Directories * multiple-windows-servers:: Running Multiple MySQL Instances on Windows * multiple-unix-servers:: Running Multiple MySQL Instances on Unix * multiple-server-clients:: Using Client Programs in a Multiple-Server Environment 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 *Note `mysqld': 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.0 and one from MySQL 5.1, 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 *Note program-options::. To see the values used by a given instance, connect to it and execute a *Note `SHOW VARIABLES': 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=PATH' option. For methods of configuring each instance with its own data directory, and warnings about the dangers of failing to do so, see *Note 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=PATH' `--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 *Note 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=PATH' 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=PATH' 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. *Note `mysqld_safe': mysqld-safe. determines the proper `--basedir' option to pass to *Note `mysqld': mysqld, and you need specify only the `--socket' and `--port' options to *Note `mysqld_safe': 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.  File: manual.info, Node: multiple-data-directories, Next: multiple-windows-servers, Prev: multiple-servers, Up: multiple-servers 5.3.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=PATH' 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 by running *Note `mysql_install_db': mysql-install-db. See *Note unix-postinstallation::. On Windows, the data directory is included in MySQL distributions. If you obtain a distribution in Windows Zip archive format, you can unpack it into a temporary location, then copy the `data' directory from this location to where you are setting up the new instance. * 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 *Note multiple-servers::. 5. Start the new instance, telling it to use the new option file.  File: manual.info, Node: multiple-windows-servers, Next: multiple-unix-servers, Prev: multiple-data-directories, Up: multiple-servers 5.3.2 Running Multiple MySQL Instances on Windows ------------------------------------------------- * Menu: * multiple-windows-command-line-servers:: Starting Multiple MySQL Instances at the Windows Command Line * multiple-windows-services:: Starting Multiple MySQL Instances as Windows Services 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 *Note 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 *Note multiple-servers::.  File: manual.info, Node: multiple-windows-command-line-servers, Next: multiple-windows-services, Prev: multiple-windows-servers, Up: multiple-windows-servers 5.3.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 *Note 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 *Note `mysqld': mysqld. on port 3307 with a data directory of `C:\mydata1', and *Note `mysqld-debug': mysqld. 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-debug --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 shutdown C:\> C:\mysql\bin\mysqladmin --port=3308 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, use the *Note `mysqld-nt': mysqld. (MySQL 5.1.20 and earlier), *Note `mysqld': mysqld. (MySQL 5.1.21 and later) or *Note `mysqld-debug': mysqld. server and 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.  File: manual.info, Node: multiple-windows-services, Prev: multiple-windows-command-line-servers, Up: multiple-windows-servers 5.3.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 *Note 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 *Note `mysqld': mysqld. server from two different versions of MySQL that are installed at `C:\mysql-5.0.92' and `C:\mysql-5.1.73', respectively. (This might be the case if you are running 5.0.92 as your production server, but also want to conduct tests using 5.1.73.) To install MySQL as a Windows service, use the `--install' or `--install-manual' option. For information about these options, see *Note 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.0.92 *Note `mysqld': mysqld. using the service name of `mysqld1' and the 5.1.73 *Note `mysqld': mysqld. using the service name `mysqld2'. In this case, you can use the `[mysqld1]' group for 5.0.92 and the `[mysqld2]' group for 5.1.73. For example, you can set up `C:\my.cnf' like this: # options for mysqld1 service [mysqld1] basedir = C:/mysql-5.0.92 port = 3307 enable-named-pipe socket = mypipe1 # options for mysqld2 service [mysqld2] basedir = C:/mysql-5.1.73 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.0.92\bin\mysqld --install mysqld1 C:\> C:\mysql-5.1.73\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.0.92 *Note `mysqld-nt': mysqld, create a file `C:\my-opts1.cnf' that looks like this: [mysqld] basedir = C:/mysql-5.0.92 port = 3307 enable-named-pipe socket = mypipe1 For the 5.1.73 *Note `mysqld': mysqld, create a file `C:\my-opts2.cnf' that looks like this: [mysqld] basedir = C:/mysql-5.1.73 port = 3308 enable-named-pipe socket = mypipe2 Install the services as follows (enter each command on a single line): C:\> C:\mysql-5.0.92\bin\mysqld --install mysqld1 --defaults-file=C:\my-opts1.cnf C:\> C:\mysql-5.1.73\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 *Note `mysqld --remove': mysqld. for each one, specifying a service name following the `--remove' option. If the service name is the default (`MySQL'), you can omit it.  File: manual.info, Node: multiple-unix-servers, Next: multiple-server-clients, Prev: multiple-windows-servers, Up: multiple-servers 5.3.3 Running Multiple MySQL Instances on Unix ---------------------------------------------- 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.0 server is configured for the default TCP/IP port number (3306) and Unix socket file (`/tmp/mysql.sock'). To configure a new 5.1.73 server to have different operating parameters, use a `configure' command something like this: shell> ./configure --with-tcp-port=PORT_NUMBER \ --with-unix-socket-path=FILE_NAME \ --prefix=/usr/local/mysql-5.1.73 Here, PORT_NUMBER and FILE_NAME must be different from the default TCP/IP port number and Unix socket file path name, and the `--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, *Note `mysqladmin': 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=PATH' option to *Note `mysqld_safe': 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. *Note environment-variables::, includes a list of other environment variables you can use to affect MySQL programs. On Unix, the *Note `mysqld_multi': mysqld-multi. script provides another way to start multiple servers. See *Note mysqld-multi::.  File: manual.info, Node: multiple-server-clients, Prev: multiple-unix-servers, Up: multiple-servers 5.3.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 *Note 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 *Note option-files::. * In a C program, you can specify the socket file or port number arguments in the *Note `mysql_real_connect()': mysql-real-connect. call. You can also have the program read option files by calling *Note `mysql_options()': mysql-options. See *Note 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 *Note apis-perl::. Other programming interfaces may provide similar capabilities for reading option files.  File: manual.info, Node: security, Next: backup-and-recovery, Prev: server-administration, Up: Top 6 Security ********** * Menu: * general-security-issues:: General Security Issues * privilege-system:: The MySQL Access Privilege System * user-account-management:: MySQL User Account Management 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 *Note 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 *Note 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 *Note privilege-system::, and *Note user-account-management::. * 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 *Note backup-and-recovery::.  File: manual.info, Node: general-security-issues, Next: privilege-system, Prev: security, Up: security 6.1 General Security Issues =========================== * Menu: * security-guidelines:: Security Guidelines * password-security:: Keeping Passwords Secure * security-against-attack:: Making MySQL Secure Against Attackers * security-options:: Security-Related `mysqld' Options and Variables * changing-mysql-user:: How to Run MySQL as a Normal User * load-data-local:: Security Issues with `LOAD DATA LOCAL' * secure-client-programming:: Client Programming Security Guidelines 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 *Note postinstallation::. For answers to some questions that are often asked about MySQL Server security issues, see *Note faqs-security::.  File: manual.info, Node: security-guidelines, Next: password-security, Prev: general-security-issues, Up: general-security-issues 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 *Note privilege-system::). Use the *Note `GRANT': grant. and *Note `REVOKE': 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 *Note default-privileges::. * Use the *Note `SHOW GRANTS': show-grants. statement to check which accounts have access to what. Then use the *Note `REVOKE': 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 `SHA1()', `MD5()', or some other one-way hashing function and store the hash value. * 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 *Note 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.  File: manual.info, Node: password-security, Next: security-against-attack, Prev: security-guidelines, Up: general-security-issues 6.1.2 Keeping Passwords Secure ------------------------------ * Menu: * password-security-user:: End-User Guidelines for Password Security * password-security-admin:: Administrator Guidelines for Password Security * password-logging:: Passwords and Logging * password-hashing:: Password Hashing in MySQL * application-password-use:: Implications of Password Hashing Changes in MySQL 4.1 for Application Programs 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.  File: manual.info, Node: password-security-user, Next: password-security-admin, Prev: password-security, Up: password-security 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 a `-pYOUR_PASS' or `--password=YOUR_PASS' option on the command line. For example: shell> mysql -u francis -pfrank DB_NAME 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 *Note option-files::, discusses option files in more detail. * Store your password in the `MYSQL_PWD' environment variable. See *Note 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 *Note `mysql': mysql. client writes a record of executed statements to a history file (see *Note 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 *Note `CREATE USER': create-user, *Note `GRANT': grant, and *Note `SET PASSWORD': set-password, 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.  File: manual.info, Node: password-security-admin, Next: password-logging, Prev: password-security-user, Up: password-security 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. 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 location of the plugin directory can replace plugins and modify the capabilities provided by plugins. Files such as log files to which passwords might be written should be protected. See *Note password-logging::.  File: manual.info, Node: password-logging, Next: password-hashing, Prev: password-security-admin, Up: password-security 6.1.2.3 Passwords and Logging ............................. Passwords can be written as plain text in SQL statements such as *Note `CREATE USER': create-user, *Note `GRANT': grant, and *Note `SET PASSWORD': set-password, or statements that invoke the `PASSWORD()' function. If these statements are logged by the MySQL server as written, such passwords become available to anyone with access to the logs. This applies to the general query log, the slow query log, and the binary log (see *Note server-logs::). To guard against unwarranted exposure to log files, they should be located in a directory that restricts access to only the server and the database administrator. If you log to tables in the `mysql' database, access to the tables should never be granted to any nonadministrative accounts. Replication slaves store the password for the replication master in the `master.info' file. Restrict this file to be accessible only to the database administrator. Database backups that include tables or log files containing passwords should be protected using a restricted access mode.  File: manual.info, Node: password-hashing, Next: application-password-use, Prev: password-logging, Up: password-security 6.1.2.4 Password Hashing in MySQL ................................. 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 (*Note `CREATE USER': create-user, *Note `GRANT': grant, or *Note `SET PASSWORD': 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 provides better security and reduces the risk of passwords being intercepted. There were several aspects to this change: * Different `PASSWORD()' function result format * 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. Because this method was so short lived, the following discussion says no 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.) In addition, the *Note `mysql': 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 *Note mysql-upgrade::.) The 4.1 hashing method is understood only by MySQL 4.1 (and newer) servers and clients, which can result in some compatibility problems. A 4.1 or newer 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 newer server may run into difficulties. For example, a 4.0 *Note `mysql': 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 newer. (See *Note apis-php-problems::.) 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.) Additional information can be found in *Note old-client::. 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 *Note `mysql_upgrade': 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 newer 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 *Note `mysql_upgrade': 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 *Note `SET PASSWORD': set-password. as follows to change an account password: SET PASSWORD FOR 'SOME_USER'@'SOME_HOST' = PASSWORD('mypass'); To change the password but create a short hash, use the `OLD_PASSWORD()' function instead: SET PASSWORD FOR 'SOME_USER'@'SOME_HOST' = OLD_PASSWORD('mypass'); `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'.  File: manual.info, Node: application-password-use, Prev: password-hashing, Up: password-security 6.1.2.5 Implications of Password Hashing Changes in MySQL 4.1 for Application Programs ...................................................................................... An upgrade to MySQL version 4.1 or later can cause compatibility issues for applications that use `PASSWORD()' to generate passwords for their own purposes. Applications really should not do this, because `PASSWORD()' should be used only to manage passwords for MySQL accounts. But some applications use `PASSWORD()' for their own purposes anyway. If you upgrade to 4.1 or later from a pre-4.1 version of MySQL and run the server under conditions where it generates long password hashes, an application using `PASSWORD()' for its own passwords breaks. The recommended course of action in such cases is to modify the application to use another function, such as `SHA1()' or `MD5()', to produce hashed values. If that is not possible, you can use the `OLD_PASSWORD()' function, which is provided for generate short hashes in the old format. However, you should note that `OLD_PASSWORD()' may one day no longer be supported. If the server is running with `old_passwords=1', it generates short hashes and `OLD_PASSWORD()' is is equivalent to `PASSWORD()'. PHP programmers migrating their MySQL databases from version 4.0 or lower to version 4.1 or higher should see *Note apis-php::.  File: manual.info, Node: security-against-attack, Next: security-options, Prev: password-security, Up: general-security-issues 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 *Note 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 *Note ssl-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 commercial SSH client at `http://www.ssh.com/'. 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 *Note `mysql': 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 *Note 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 *Note `mysqld': 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, *Note `mysqld': mysqld. refuses to run as `root' unless that is specified explicitly using the `--user=root' option. *Note `mysqld': 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 *Note `mysqld': 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 *Note `mysqld_safe': mysqld-safe. or *Note `mysql.server': mysql-server. For more details, see *Note changing-mysql-user::. Running *Note `mysqld': 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 *Note `mysqld': 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 *Note `SELECT ... INTO OUTFILE': select-into. 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 *Note `LOAD DATA': load-data. to load `/etc/passwd' into a table, which then can be displayed with *Note `SELECT': select. To limit the location in which files can be read and written, set the `secure_file_priv' system to a specific directory. See *Note server-system-variables::. * Do not grant the `PROCESS' or `SUPER' privilege to nonadministrative users. The output of *Note `mysqladmin processlist': mysqladmin. and *Note `SHOW PROCESSLIST': 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')'. *Note `mysqld': 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 *Note `mysqld': mysqld. as `root', because anyone that has write access to the server's data directory then could delete any file in the system! See *Note symbolic-links-to-tables::. * Stored programs and views should be written using the security guidelines discussed in *Note 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 *Note `mysqld': mysqld. The *Note `GRANT': grant. statement also supports resource control options for limiting the extent of server use permitted to an account. See *Note grant::. * 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 *Note `SELECT ... INTO DUMPFILE': select. This can be prevented by making `plugin_dir' read only to the server or by setting `--secure-file-priv' to a directory where *Note `SELECT': select. writes can be made safely.  File: manual.info, Node: security-options, Next: changing-mysql-user, Prev: security-against-attack, Up: general-security-issues 6.1.4 Security-Related `mysqld' Options and Variables ----------------------------------------------------- The following table shows *Note `mysqld': mysqld. options and system variables that affect security. For descriptions of each of these, see *Note server-options::, and *Note server-system-variables::. *Security Option/Variable Summary* Name Cmd-Line Option file System Var Status Var Var Scope Dynamic 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-show-databaseYes Yes Yes Global Yes safe-user-createYes Yes secure-auth Yes Yes Global Yes - _Variable_: Yes Global Yes secure_auth secure-file-privYes Yes Global No - _Variable_: Yes Global No secure_file_priv skip-grant-tablesYes Yes skip-name-resolveYes Yes Global No - _Variable_: Yes Global No skip_name_resolve skip-networkingYes Yes Global No - _Variable_: Yes Global No skip_networking skip-show-databaseYes Yes Global No - _Variable_: Yes Global No skip_show_database  File: manual.info, Node: changing-mysql-user, Next: load-data-local, Prev: security-options, Up: general-security-issues 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 Unix, the MySQL server *Note `mysqld': 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 *Note `mysqld': 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 *Note `mysqladmin shutdown': mysqladmin.). 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 *Note `mysqld': mysqld. as the Unix `root' user and use the `--user=USER_NAME' option. *Note `mysqld': 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' accounts in the grant tables. Otherwise, any user with a login account on that machine can run the *Note `mysql': 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 *Note default-privileges::.  File: manual.info, Node: load-data-local, Next: secure-client-programming, Prev: changing-mysql-user, Up: general-security-issues 6.1.6 Security Issues with `LOAD DATA LOCAL' -------------------------------------------- The *Note `LOAD DATA': load-data. statement can load a file that is located on the server host, or it can load a file that is located on the client host when the `LOCAL' keyword is specified. There are two potential security issues with supporting the `LOCAL' version of *Note `LOAD DATA': load-data. statements: * 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 *Note `LOAD DATA': load-data. statement. Such a server could access any file on the client host to which the client user has read access. * In a Web environment where the clients are connecting from a Web server, a user could use *Note `LOAD DATA LOCAL': load-data. to read any files that the Web server process has read access to (assuming that a user could run any command against the SQL server). In this environment, the client with respect to the MySQL server actually is the Web server, not the remote program being run by the user who connects to the Web server. To deal with these problems, we changed how *Note `LOAD DATA LOCAL': load-data. is handled as of MySQL 3.23.49 and MySQL 4.0.2 (4.0.13 on Windows): * By default, all MySQL clients and libraries in binary distributions are compiled with the `--enable-local-infile' option, to be compatible with MySQL 3.23.48 and before. * If you build MySQL from source but do not invoke `configure' with the `--enable-local-infile' option, *Note `LOAD DATA LOCAL': load-data. cannot be used by any client unless it is written explicitly to invoke *Note `mysql_options(... MYSQL_OPT_LOCAL_INFILE, 0)': mysql-options. See *Note mysql-options::. * You can disable all *Note `LOAD DATA LOCAL': load-data. statements from the server side by starting *Note `mysqld': mysqld. with the `--local-infile=0' option. * For the *Note `mysql': mysql. command-line client, enable *Note `LOAD DATA LOCAL': load-data. by specifying the `--local-infile[=1]' option, or disable it with the `--local-infile=0' option. For *Note `mysqlimport': mysqlimport, local data file loading is off by default; enable it with the `--local' or `-L' option. In any case, successful use of a local load operation requires that the server permits it. * If you use *Note `LOAD DATA LOCAL': load-data. in Perl scripts or other programs that read the `[client]' group from option files, you can add the `local-infile=1' option to that group. However, to keep this from causing problems for programs that do not understand `local-infile', specify it using the `loose-' prefix: [client] loose-local-infile=1 * If *Note `LOAD DATA LOCAL': load-data. is disabled, either in the server or the client, a client that attempts to issue such a statement receives the following error message: ERROR 1148: The used command is not allowed with this MySQL version  File: manual.info, Node: secure-client-programming, Prev: load-data-local, Up: general-security-issues 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 *Note server-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 *Note `mysql_real_escape_string()': mysql-real-escape-string. 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 *Note apis-php-mysqlinfo.api.choosing::. If the older `ext/mysql' extension must be used, then for escaping use the *Note `mysql_real_escape_string()': mysql-real-escape-string. function and not *Note `mysql_escape_string()': mysql-escape-string. or `addslashes()' because only *Note `mysql_real_escape_string()': mysql-real-escape-string. is character set-aware; the other functions can be `bypassed' when using (invalid) multi-byte 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.  File: manual.info, Node: privilege-system, Next: user-account-management, Prev: general-security-issues, Up: security 6.2 The MySQL Access Privilege System ===================================== * Menu: * privileges-provided:: Privileges Provided by MySQL * grant-table-structure:: Privilege System Grant Tables * account-names:: Specifying Account Names * connection-access:: Access Control, Stage 1: Connection Verification * request-access:: Access Control, Stage 2: Request Verification * privilege-changes:: When Privilege Changes Take Effect * access-denied:: Causes of Access-Denied Errors 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 *Note `SELECT': select, *Note `INSERT': insert, *Note `UPDATE': update, and *Note `DELETE': delete. Additional functionality includes the ability to have anonymous users and to grant privileges for MySQL-specific functions such as *Note `LOAD DATA INFILE': load-data. 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 *Note `CREATE USER': create-user, *Note `GRANT': grant, and *Note `REVOKE': revoke. See *Note 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 *Note `SHOW GRANTS': 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 *Note connection-access::, and *Note 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 *Note privilege-changes::. For general security-related advice, see *Note general-security-issues::. For help in diagnosing privilege-related problems, see *Note access-denied::.  File: manual.info, Node: privileges-provided, Next: grant-table-structure, Prev: privilege-system, Up: privilege-system 6.2.1 Privileges Provided by MySQL ---------------------------------- MySQL provides privileges that apply in different contexts 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', `host', `tables_priv', `columns_priv', and `procs_priv' tables in the `mysql' database (see *Note grant-table-structure::). The MySQL server reads the contents of these tables into memory when it starts and reloads them under the circumstances indicated in *Note privilege-changes::. Access-control decisions are based on the in-memory copies of the grant tables. Some releases of MySQL introduce changes to the structure of the grant tables to add new access privileges or features. Whenever you update to a new version of MySQL, you should update your grant tables to make sure that they have the current structure so that you can take advantage of any new capabilities. See *Note mysql-upgrade::. The following table shows the privilege names used at the SQL level in the *Note `GRANT': grant. and *Note `REVOKE': 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 `CREATE' `Create_priv' databases, tables, or indexes `DROP' `Drop_priv' databases, tables, or views `GRANT OPTION' `Grant_priv' databases, tables, or stored routines `LOCK TABLES' `Lock_tables_priv' databases `REFERENCES' `References_priv' databases or tables `EVENT' `Event_priv' databases `ALTER' `Alter_priv' tables `DELETE' `Delete_priv' tables `INDEX' `Index_priv' tables `INSERT' `Insert_priv' tables or columns `SELECT' `Select_priv' tables or columns `UPDATE' `Update_priv' tables or columns `CREATE TEMPORARY `Create_tmp_table_priv' tables TABLES' `TRIGGER' `Trigger_priv' tables `CREATE VIEW' `Create_view_priv' views `SHOW VIEW' `Show_view_priv' views `ALTER ROUTINE' `Alter_routine_priv' stored routines `CREATE ROUTINE' `Create_routine_priv' stored routines `EXECUTE' `Execute_priv' stored routines `FILE' `File_priv' file access on server host `CREATE USER' `Create_user_priv' server administration `PROCESS' `Process_priv' server administration `RELOAD' `Reload_priv' server administration `REPLICATION CLIENT' `Repl_client_priv' server administration `REPLICATION SLAVE' `Repl_slave_priv' server administration `SHOW DATABASES' `Show_db_priv' server administration `SHUTDOWN' `Shutdown_priv' server administration `SUPER' `Super_priv' server administration `ALL [PRIVILEGES]' server administration `USAGE' server administration The following list provides a general description of each privilege 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 *Note `ALTER TABLE': alter-table. to change the structure of tables. *Note `ALTER TABLE': alter-table. also requires the `CREATE' and `INSERT' privileges. Renaming a table requires `ALTER' and `DROP' on the old table, `ALTER', `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 TEMPORARY TABLES' privilege enables the creation of temporary tables using the *Note `CREATE TEMPORARY TABLE': create-table. statement. However, other operations on a temporary table, such as *Note `INSERT': insert, *Note `UPDATE': update, or *Note `SELECT': select, require additional privileges for those operations for the database containing the temporary table, or for the nontemporary table of the same name. To keep privileges for temporary and nontemporary tables separate, a common workaround for this situation is to create a database dedicated to the use of temporary tables. Then for that database, a user can be granted the `CREATE TEMPORARY TABLES' privilege, along with any other privileges required for temporary table operations done by that user. * The `CREATE USER' privilege enables use of *Note `CREATE USER': create-user, *Note `DROP USER': drop-user, *Note `RENAME USER': rename-user, and *Note `REVOKE ALL PRIVILEGES': revoke. * The `CREATE VIEW' privilege enables use of *Note `CREATE VIEW': create-view. * 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. Beginning with MySQL 5.1.10, the `DROP' privilege is also required to use the statement `ALTER TABLE ... DROP PARTITION' on a partitioned table. Beginning with MySQL 5.1.16, the `DROP' privilege is required for *Note `TRUNCATE TABLE': truncate-table. (before that, *Note `TRUNCATE TABLE': truncate-table. requires the `DELETE' privilege). _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. This privilege was added in MySQL 5.1.6. * 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 *Note `LOAD DATA INFILE': load-data. and *Note `SELECT ... INTO OUTFILE': select-into. 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. To limit the location in which files can be read and written, set the `secure_file_priv' system to a specific directory. See *Note 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 *Note `CREATE TABLE': create-table. statement. * The `INSERT' privilege enables rows to be inserted into tables in a database. `INSERT' is also required for the *Note `ANALYZE TABLE': analyze-table, *Note `OPTIMIZE TABLE': optimize-table, and *Note `REPAIR TABLE': repair-table. table-maintenance statements. * The `LOCK TABLES' privilege enables the use of explicit *Note `LOCK TABLES': 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 *Note `SHOW PROCESSLIST': show-processlist. or *Note `mysqladmin processlist': mysqladmin. to see threads belonging to other accounts; you can always see your own threads. * The `REFERENCES' privilege currently is unused. * The `RELOAD' privilege enables use of the *Note `FLUSH': flush. statement. It also enables *Note `mysqladmin': mysqladmin. commands that are equivalent to *Note `FLUSH': 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 *Note `SHOW MASTER STATUS': show-master-status. and *Note `SHOW SLAVE STATUS': show-slave-status. In MySQL 5.1.64 and later, it also enables the use of the *Note `SHOW BINARY LOGS': show-binary-logs. statement. * 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. *Note `SELECT': select. statements require the `SELECT' privilege only if they actually retrieve rows from a table. Some *Note `SELECT': select. statements do not access tables and can be executed without permission for any database. For example, you can use *Note `SELECT': 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 *Note `UPDATE': update. statements or for columns named in the `WHERE' clause of *Note `DELETE': delete. or *Note `UPDATE': update. statements. * 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 *Note `SHOW CREATE VIEW': show-create-view. * The `SHUTDOWN' privilege enables use of the *Note `mysqladmin shutdown': mysqladmin. command. There is no corresponding SQL statement. * The `SUPER' privilege enables an account to use *Note `CHANGE MASTER TO': change-master-to, *Note `KILL': kill. or *Note `mysqladmin kill': mysqladmin. to kill threads belonging to other accounts (you can always kill your own threads), *Note `PURGE BINARY LOGS': purge-binary-logs, configuration changes using *Note `SET GLOBAL': set-statement. to modify global system variables, the *Note `mysqladmin debug': mysqladmin. command, enabling or disabling logging, performing updates even if the `read_only' system variable is enabled, starting and stopping replication on slave servers, specification of any account in the `DEFINER' attribute of stored programs and views, and enables you to connect (once) even if the connection limit controlled by the `max_connections' system variable is reached. To create or alter stored functions if binary logging is enabled, you may also need the `SUPER' privilege, as described in *Note stored-programs-logging::. * The `TRIGGER' privilege enables trigger operations. You must have this privilege for a table to create, drop, or execute triggers for that table. This privilege was added in MySQL 5.1.6. (Prior to MySQL 5.1.6, trigger operations required the `SUPER' 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 *Note `GRANT': grant. to modify account attributes such as resource limits or SSL characteristics without affecting existing account privileges. 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 *Note `SELECT': 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 `Password' column can change an account's password, and then connect to the MySQL server using that account.  File: manual.info, Node: grant-table-structure, Next: account-names, Prev: privileges-provided, Up: privilege-system 6.2.2 Privilege System Grant Tables ----------------------------------- Normally, you manipulate the contents of the grant tables in the `mysql' database indirectly by using statements such as *Note `GRANT': grant. and *Note `REVOKE': revoke. to set up accounts and control the privileges available to each one. See *Note 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. These `mysql' database tables contain grant information: * `user': Contains user accounts, global privileges, and other non-privilege columns. * `db': Contains database-level privileges. * `host': Obsolete. * `tables_priv': Contains table-level privileges. * `columns_priv': Contains column-level privileges. * `procs_priv': Contains stored procedure and function privileges. Other tables in the `mysql' database do not hold grant information and are discussed elsewhere: * `event': Contains information about Event Scheduler events: See *Note events::. * `func': Contains information about user-defined functions: See *Note adding-functions::. * `help_XXX': These tables are used for server-side help: See *Note server-side-help-support::. * `plugin': Contains information about server plugins: See *Note server-plugin-loading::, and *Note plugin-api::. * `proc': Contains information about stored procedures and functions: See *Note stored-routines::. * `servers': Used by the `FEDERATED' storage engine: See *Note federated-create-server::. * `time_zone_XXX': These tables contain time zone information: See *Note time-zone-support::. * Tables with `_log' in their name are used for logging: See *Note server-logs::. *Note*: Modifications to tables in the `mysql' database normally are made by the server in response to statements such as *Note `CREATE USER': create-user, *Note `GRANT': grant, or *Note `CREATE PROCEDURE': create-procedure. Direct modification of these tables using statements such as *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': delete. is not encouraged. The server is free to ignore rows that become malformed as a result of such modifications. Each grant table contains scope columns and privilege columns: * Scope columns determine the scope of each row (entry) in the tables; that is, the context in which the row applies. For example, a `user' table row with `Host' and `User' values of `'thomas.loc.gov'' and `'bob'' would be used for authenticating connections made to the server from the host `thomas.loc.gov' by a client that specifies a user name of `bob'. Similarly, a `db' table row with `Host', `User', and `Db' column values of `'thomas.loc.gov'', `'bob'' and `'reports'' would be used when `bob' connects from the host `thomas.loc.gov' 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 are granted by a table row; that is, what operations can be performed. The server combines the information in the various grant tables to form a complete description of a user's privileges. *Note request-access::, describes the rules that are used to do 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 privilege granted in this table applies to _all_ databases on the server. *Note*: Because any global privilege is considered a privilege for all databases, any global privilege enables a user to see all database names with *Note `SHOW DATABASES': show-databases. or by examining the *Note `SCHEMATA': schemata-table. table of `INFORMATION_SCHEMA'. * The `db' table scope columns determine which users can access which databases from which hosts. The privilege columns determine which operations are permitted. 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 `host' table is used in conjunction with the `db' table when you want a given `db' table row to apply to several hosts. For example, if you want a user to be able to use a database from several hosts in your network, leave the `Host' value empty in the user's `db' table row, then populate the `host' table with a row for each of those hosts. This mechanism is described more detail in *Note request-access::. *Note*: The `host' table must be modified directly with statements such as *Note `INSERT': insert, *Note `UPDATE': update, and *Note `DELETE': delete. It is not affected by statements such as *Note `GRANT': grant. and *Note `REVOKE': revoke. that modify the grant tables indirectly. Most MySQL installations need not use this table at all. * 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. A privilege granted at the routine level applies only to a single routine. The server uses the `user', `db', and `host' tables in the `mysql' database at both the first and second stages of access control (see *Note privilege-system::). The columns in the `user' and `db' tables are shown here. The `host' table is similar to the `db' table but has a specialized use as described in *Note request-access::. *`user' and `db' Table Columns* Table Name `user' `db' *Scope columns* `Host' `Host' `User' `Db' `Password' `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' *Security columns* `ssl_type' `ssl_cipher' `x509_issuer' `x509_subject' *Resource control columns* `max_questions' `max_updates' `max_connections' `max_user_connections' The `Event_priv' and `Trigger_priv' columns were added in MySQL 5.1.6. During the second stage of access control, the server performs request verification to make sure that each client has sufficient privileges for each request that it issues. In addition to the `user', `db', and `host' 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 currently are unused and are discussed no further here. 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 *Note `ENUM': 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 set to the current timestamp and the `CURRENT_USER' value, respectively. However, they are unused and are discussed no further here. Scope columns in the grant tables contain strings. They are declared as shown here; the default value for each is the empty string. *Grant Table Scope Column Types* Column Name Type `Host' `CHAR(60)' `User' `CHAR(16)' `Password' `CHAR(41)' `Db' `CHAR(64)' `Table_name' `CHAR(64)' `Column_name' `CHAR(64)' `Routine_name' `CHAR(64)' For access-checking purposes, comparisons of `User', `Password', `Db', and `Table_name' values are case sensitive. Comparisons of `Host', `Column_name', and `Routine_name' values are not case sensitive. In the `user', `db', and `host' tables, each privilege is listed 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. In the `tables_priv', `columns_priv', and `procs_priv' tables, the privilege columns are declared as *Note `SET': 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'' Administrative privileges (such as `RELOAD' or `SHUTDOWN') are specified only in the `user' table. 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, to determine whether you can perform an administrative operation, the server need consult only the `user' table. The `FILE' privilege also is specified only in the `user' table. It is not an administrative privilege as such, but your ability to read or write files on the server host is independent of the database you are accessing. The *Note `mysqld': mysqld. server reads the contents of the grant tables into memory when it starts. You can tell it to reload the tables by issuing a *Note `FLUSH PRIVILEGES': flush. statement or executing a *Note `mysqladmin flush-privileges': mysqladmin. or *Note `mysqladmin reload': mysqladmin. command. Changes to the grant tables take effect as indicated in *Note privilege-changes::. When you modify an account's privileges, it is a good idea to verify that the changes set up privileges the way you want. To check the privileges for a given account, use the *Note `SHOW GRANTS': show-grants. statement (see *Note show-grants::). 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';  File: manual.info, Node: account-names, Next: connection-access, Prev: grant-table-structure, Up: privilege-system 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 *Note `CREATE USER': create-user, *Note `GRANT': grant, and *Note `SET PASSWORD': set-password, write account names using the following rules: * Syntax for account names 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 ``-''), or a HOST_NAME string containing special characters or wildcard characters (such as ``%''); 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 (``"''). * The user name and host name parts, if quoted, must be quoted separately. That is, write `'me'@'localhost'', not `'me@localhost''; the latter is interpreted as `'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' 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 additional detail about grant table structure, see *Note grant-table-structure::. User names and host names have certain special values or wildcard conventions, as described following. A user 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. The name `'localhost'' indicates the local host. The IP address `'127.0.0.1'' indicates the loopback interface. * You can use the wildcard characters ``%'' and ``_'' 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. `'192.168.1.%'' matches any host in the 192.168.1 class C network. Because you can use IP wildcard values in host values (for example, `'192.168.1.%'' to match every host on a subnet), someone could try to exploit this capability by naming a host `192.168.1.somewhere.com'. To foil such attempts, MySQL disallows matching on host names that start with digits and a dot. Thus, if you have a host named something like `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 IP address, you can specify a netmask indicating how many address bits to use for the network number. The syntax is `HOST_IP/NETMASK'. For example: CREATE USER 'david'@'192.58.197.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 *Note `CREATE USER': create-user. statement just shown: CLIENT_IP & 255.255.255.0 = 192.58.197.0 IP addresses that satisfy this condition and can connect to the MySQL server are those in the range from `192.58.197.0' to `192.58.197.255'. The netmask can only be used to tell the server to use 8, 16, 24, or 32 bits of the address. Examples: * `192.0.0.0/255.0.0.0': Any host on the 192 class A network * `192.168.0.0/255.255.0.0': Any host on the 192.168 class B network * `192.168.1.0/255.255.255.0': Any host on the 192.168.1 class C network * `192.168.1.1': Only the host with this specific IP address The following netmask will not work because it masks 28 bits, and 28 is not a multiple of 8: 192.168.0.1/255.255.255.240 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, this comparison is performed 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. But if DNS returns just `host1', use `host1' instead. * If DNS returns the IP address for a given host as `192.168.1.2', that will match an account host value of `192.168.1.2' but not `192.168.01.2'. Similarly, it will match an account host pattern like `192.168.1.%' but not `192.168.01.%'. To avoid problems like this, it is advisable to check the format in which your DNS returns host names and addresses, and use values in the same format in MySQL account names.  File: manual.info, Node: connection-access, Next: request-access, Prev: account-names, Up: privilege-system 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 your identity and whether you can verify your identity by supplying the correct password. If not, the server denies access to you completely. Otherwise, the server accepts the connection, and then enters Stage 2 and waits for requests. Your identity is based on two pieces of information: * The client host from which you connect * Your MySQL user name Identity checking is performed using the three `user' table scope columns (`Host', `User', and `Password'). 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 and the client supplies the password specified in that row. The rules for permissible `Host' and `User' values are given in *Note account-names::. 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 `Password' 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. Nonblank `Password' values in the `user' table represent encrypted passwords. MySQL does not store passwords in plaintext form for anyone to see. Rather, the password supplied by a user who is attempting to connect is encrypted (using the `PASSWORD()' function). 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 *Note 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 `Host' and `User' values in the `user' table apply to incoming connections. This table shows how various combinations of `Host' and `User' values in the `user' table apply to incoming connections to a MySQL server. `Host' Value `User' Permissible Connections Value `'thomas.loc.gov'' `'fred'' `fred', connecting from `thomas.loc.gov' `'thomas.loc.gov'' `''' Any user, connecting from `thomas.loc.gov' `'%'' `'fred'' `fred', connecting from any host `'%'' `''' Any user, connecting from any host `'%.loc.gov'' `'fred'' `fred', connecting from any host in the `loc.gov' domain `'x.y.%'' `'fred'' `fred', connecting from `x.y.net', `x.y.com', `x.y.edu', and so on; this is probably not useful `'144.155.166.177'' `'fred'' `fred', connecting from the host with IP address `144.155.166.177' `'144.155.166.%'' `'fred'' `fred', connecting from any host in the `144.155.166' class C subnet `'144.155.166.0/255.255.255.0''`'fred'' 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 `thomas.loc.gov' 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 `192.168.1.13' and `192.168.1.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). 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 | ... | thomas.loc.gov | | ... +----------------+----------+- The sorted table looks like this: +----------------+----------+- | Host | User | ... +----------------+----------+- | thomas.loc.gov | | ... | % | jeffrey | ... +----------------+----------+- A connection by `jeffrey' from `thomas.loc.gov' 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 `thomas.loc.gov' 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 *Note 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.  File: manual.info, Node: request-access, Next: privilege-changes, Prev: connection-access, Up: privilege-system 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', `host', `tables_priv', `columns_priv', or `procs_priv' tables. (You may find it helpful to refer to *Note grant-table-structure::, 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' and `host' tables grant database-specific privileges. Values in the scope columns of these tables can take the following forms: * A blank `User' value in the `db' table 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 of either table. 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 *Note `GRANT': grant. statement. * A `'%'' `Host' value in the `db' table means `any host.' A blank `Host' value in the `db' table means `consult the `host' table for further information' (a process that is described later in this section). * A `'%'' or blank `Host' value in the `host' table means `any host.' * A `'%'' or blank `Db' value in either table means `any database.' The server reads the `db' and `host' tables into memory and sorts them 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, and sorts the `host' table based on the `Host' and `Db' 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 entries, 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 *Note `mysqladmin shutdown': mysqladmin. but your `user' table row does not grant the `SHUTDOWN' privilege to you, the server denies access without even checking the `db' or `host' tables. (They contain no `Shutdown_priv' column, so there is no need to do so.) For database-related requests (*Note `INSERT': insert, *Note `UPDATE': 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' and `host' tables: 1. 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. 2. If there is a matching `db' table row and its `Host' column is not blank, that row defines the user's database-specific privileges. 3. If the matching `db' table row's `Host' column is blank, it signifies that the `host' table enumerates which hosts should be permitted access to the database. In this case, a further lookup is done in the `host' table to find a match on the `Host' and `Db' columns. If no `host' table row matches, access is denied. If there is a match, the user's database-specific privileges are computed as the intersection (_not_ the union!) of the privileges in the `db' and `host' table entries; that is, the privileges that are `'Y'' in both entries. (This way you can grant general privileges in the `db' table row and then selectively restrict them on a host-by-host basis using the `host' table entries.) After determining the database-specific privileges granted by the `db' and `host' table entries, 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 *Note `INSERT INTO ... SELECT': insert-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 entries in both tables must be combined. The `host' table is not affected by the *Note `GRANT': grant. or *Note `REVOKE': revoke. statements, so it is unused in most MySQL installations. If you modify it directly, you can use it for some specialized purposes, such as to maintain a list of secure servers on the local network that are granted all privileges. You can also use the `host' table to indicate hosts that are _not_ secure. Suppose that you have a machine `public.your.domain' that is located in a public area that you do not consider secure. You can enable access to all hosts on your network except that machine by using `host' table entries like this: +--------------------+----+- | Host | Db | ... +--------------------+----+- | public.your.domain | % | ... (all privileges set to 'N') | %.your.domain | % | ... (all privileges set to 'Y') +--------------------+----+-  File: manual.info, Node: privilege-changes, Next: access-denied, Prev: request-access, Up: privilege-system 6.2.6 When Privilege Changes Take Effect ---------------------------------------- When *Note `mysqld': 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 *Note `GRANT': grant, *Note `REVOKE': revoke, *Note `SET PASSWORD': set-password, or *Note `RENAME USER': 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 *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': 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 *Note `FLUSH PRIVILEGES': flush. statement or by executing a *Note `mysqladmin flush-privileges': mysqladmin. or *Note `mysqladmin reload': mysqladmin. 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 or flushing the privileges. * 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.  File: manual.info, Node: access-denied, Prev: privilege-changes, Up: privilege-system 6.2.7 Causes of Access-Denied Errors ------------------------------------ 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 the Windows XP personal 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' database containing the grant tables. For distributions that do not do this, you must initialize the grant tables manually by running the *Note `mysql_install_db': mysql-install-db. script. For details, see *Note unix-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, execute the *Note `mysql_install_db': mysql-install-db. script. After running this script and starting the server, test the initial privileges by executing this command: shell> mysql -u root test The server should let you connect without error. * After a fresh installation, you should connect to the server and set up your users and their access permissions: shell> mysql -u root mysql The server should let you connect because the MySQL `root' user has no password initially. That is also a security risk, so setting the password for the `root' accounts is something you should do while you're setting up your other MySQL accounts. For instructions on setting the initial passwords, see *Note default-privileges::. * If you have updated an existing MySQL installation to a newer version, did you run the *Note `mysql_upgrade': 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 *Note 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 *Note password-hashing::, and *Note old-client::. * 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 *Note option-files::. Environment variables are listed in *Note 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 *Note assigning-passwords::. If you have lost or forgotten the `root' password, see *Note resetting-permissions::. * If you change a password by using *Note `SET PASSWORD': set-password, *Note `INSERT': insert, or *Note `UPDATE': update, you must encrypt the password using the `PASSWORD()' function. If you do not use `PASSWORD()' for these statements, the password will not work. For example, the following statement assigns a password, but fails to encrypt it, so the user is not able to connect afterward: SET PASSWORD FOR 'abe'@'HOST_NAME' = 'eagle'; Instead, set the password like this: SET PASSWORD FOR 'abe'@'HOST_NAME' = PASSWORD('eagle'); The `PASSWORD()' function is unnecessary when you specify a password using the *Note `CREATE USER': create-user. or *Note `GRANT': grant. statements or the *Note `mysqladmin password': mysqladmin. command. Each of those automatically uses `PASSWORD()' to encrypt the password. See *Note assigning-passwords::, and *Note create-user::. * `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. To avoid this problem on such systems, 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 *Note `mysqld': 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 *Note `mysqld': mysqld. cannot resolve the host name for your client: Access denied for user ''@'unknown' These errors indicate a DNS problem. To fix it, execute *Note `mysqladmin flush-hosts': mysqladmin. to reset the internal DNS host cache. See *Note 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 *Note `mysqld': mysqld. with the `--skip-name-resolve' option. * Start *Note `mysqld': 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'. Unix connections to `localhost' use a Unix socket file rather than TCP/IP. * 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 test' works but `mysql -h YOUR_HOSTNAME -u root test' 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 an entry with host `'pluto'' in the `user' table, but your DNS tells MySQL that your host name is `'pluto.example.com'', the entry does not work. Try adding an entry to the `user' table that contains the IP address of your host as the `Host' column value. (Alternatively, you could add an entry 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 test' works but `mysql -u USER_NAME OTHER_DB' does not, you have not granted access to the given user for the database named OTHER_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 entries that have `Host' values containing wildcards (entries that contain `'%'' or `'_'' characters). A very common error is to insert a new entry 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 an entry with `Host'=`'localhost'' and `User'=`'''. Because that entry has a `Host' value `'localhost'' that is more specific than `'%'', it is used in preference to the new entry when connecting from `localhost'! The correct procedure is to insert a second entry with `Host'=`'localhost'' and `User'=`'SOME_USER'', or to delete the entry with `Host'=`'localhost'' and `User'=`'''. After deleting the entry, remember to issue a *Note `FLUSH PRIVILEGES': flush. statement to reload the grant tables. See also *Note connection-access::. * If you are able to connect to the MySQL server, but get an `Access denied' message whenever you issue a *Note `SELECT ... INTO OUTFILE': select-into. or *Note `LOAD DATA INFILE': load-data. statement, your entry in the `user' table does not have the `FILE' privilege enabled. * If you change the grant tables directly (for example, by using *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': delete. statements) and your changes seem to be ignored, remember that you must execute a *Note `FLUSH PRIVILEGES': flush. statement or a *Note `mysqladmin flush-privileges': mysqladmin. 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 *Note `UPDATE': 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 *Note 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 *Note `mysql': 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 *Note `mysqld': mysqld. server with the `--skip-grant-tables' option. Then you can change the MySQL grant tables and use the *Note `mysqlaccess': mysqlaccess. script to check whether your modifications have the desired effect. When you are satisfied with your changes, execute *Note `mysqladmin flush-privileges': mysqladmin. to tell the *Note `mysqld': mysqld. server to reload the privileges. This enables you to begin using the new grant table contents without stopping and restarting the server. * If you get the following error, you may have a problem with the `db' or `host' table: Access to database denied If the entry selected from the `db' table has an empty value in the `Host' column, make sure that there are one or more corresponding entries in the `host' table specifying which hosts the `db' table entry applies to. This problem occurs infrequently because the `host' table is rarely used. * If everything else fails, start the *Note `mysqld': 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 *Note 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 *Note `mysqldump mysql': mysqldump. command. To file a bug report, see the instructions at *Note bug-reports::. In some cases, you may need to restart *Note `mysqld': mysqld. with `--skip-grant-tables' to run *Note `mysqldump': mysqldump.  File: manual.info, Node: user-account-management, Prev: privilege-system, Up: security 6.3 MySQL User Account Management ================================= * Menu: * user-names:: User Names and Passwords * adding-users:: Adding User Accounts * removing-users:: Removing User Accounts * user-resources:: Setting Account Resource Limits * assigning-passwords:: Assigning Account Passwords * ssl-connections:: Using SSL for Secure Connections * windows-and-ssh:: Connecting to MySQL Remotely from Windows with SSH * account-activity-auditing:: SQL-Based MySQL Account Activity Auditing 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 * How to use secure connections with SSL See also *Note account-management-sql::, which describes the syntax and use for all user-management SQL statements.  File: manual.info, Node: user-names, Next: adding-users, Prev: user-account-management, Up: user-account-management 6.3.1 User Names and Passwords ------------------------------ MySQL stores accounts in the `user' table of the `mysql' 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. The account may also have a password. For information about account representation in the `user' table, see *Note grant-table-structure::. There are several distinctions between the way user names and passwords are used by MySQL and the way they are used by 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. Because this means that anyone can attempt to connect to the server using any user name, 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 16 characters long. Operating system user names, because they are completely unrelated to MySQL 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 hard-coded in the 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 any of the tables in the `mysql' database in any manner whatsoever except by means of the procedure that is described in *Note mysql-upgrade::. Attempting to redefine MySQL's system tables in any other fashion results in undefined (and unsupported!) behavior. * The server uses MySQL passwords stored in the `user' table to authenticate client connections using MySQL built-in authentication. These passwords have nothing to do with 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. * MySQL encrypts passwords stored in the `user' table using its own algorithm. This encryption is the same as that implemented by the `PASSWORD()' SQL function but differs from that used during the Unix login process. Unix password encryption is the same as that implemented by the `ENCRYPT()' SQL function. See the descriptions of the `PASSWORD()' and `ENCRYPT()' functions in *Note encryption-functions::. From version 4.1 on, MySQL employs a stronger authentication method that has better password protection during the connection process than in earlier versions. It is secure even if TCP/IP packets are sniffed or the `mysql' database is captured. (In earlier versions, even though passwords are stored in encrypted form in the `user' table, knowledge of the encrypted password value could be used to connect to the MySQL server.) *Note password-hashing::, discusses password encryption further. * It is possible to connect to the server regardless of character set settings if the user name and password contain only ASCII characters. To connect when the user name or password contain non-ASCII characters, the client should call the *Note `mysql_options()': 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 *Note `mysql_options()': mysql-options. to be called as just described. For programs that use a connector that is not based on the C API, the connector may provide an equivalent to *Note `mysql_options()': mysql-options. that can be used instead. Check the connector documentation. The preceding notes do not apply for `ucs2', which is not permitted as a client character set. When you install MySQL, the grant tables are populated with an initial set of accounts. The names and access privileges for these accounts are described in *Note default-privileges::, which also discusses how to assign passwords to them. Thereafter, you normally set up, modify, and remove MySQL accounts using statements such as *Note `CREATE USER': create-user, *Note `GRANT': grant, and *Note `REVOKE': revoke. See *Note account-management-sql::. When you connect to a MySQL server with a command-line client, specify the user name and password as necessary for the account that you want to use: shell> mysql --user=monty --password=PASSWORD DB_NAME If you prefer short options, the command looks like this: shell> mysql -u monty -pPASSWORD DB_NAME There must be _no space_ between the `-p' option and the following password value. If you omit the PASSWORD value following the `--password' or `-p' option on the command line, the client prompts for one. Specifying a password on the command line should be considered insecure. See *Note password-security-user::. You can use an option file to avoid giving the password on the command line. For additional information about specifying user names, passwords, and other connection parameters, see *Note connecting::.  File: manual.info, Node: adding-users, Next: removing-users, Prev: user-names, Up: user-account-management 6.3.2 Adding User Accounts -------------------------- You can create MySQL accounts in two ways: * By using statements intended for creating accounts, such as *Note `CREATE USER': create-user. or *Note `GRANT': grant. These statements cause the server to make appropriate modifications to the grant tables. * By manipulating the MySQL grant tables directly with statements such as *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': delete. The preferred method is to use account-creation statements because they are more concise and less error-prone than manipulating the grant tables directly. *Note `CREATE USER': create-user. and *Note `GRANT': grant. are described in *Note account-management-sql::. Another option for creating accounts is to use the GUI tool MySQL Workbench. Or one of several available third-party programs that offer capabilities for MySQL account administration. `phpMyAdmin' is one such program. The following examples show how to use the *Note `mysql': mysql. client program to set up new accounts. These examples assume that privileges have been set up according to the defaults described in *Note default-privileges::. This means that to make changes, you must connect to the MySQL server as the MySQL `root' user, and the `root' account must have the `INSERT' privilege for the `mysql' database and the `RELOAD' administrative privilege. As noted in the examples where appropriate, some of the statements will fail if the server's SQL mode has been set to enable certain restrictions. In particular, strict mode (`STRICT_TRANS_TABLES', `STRICT_ALL_TABLES') and `NO_AUTO_CREATE_USER' will prevent the server from accepting some of the statements. Workarounds are indicated for these cases. For more information about SQL modes and their effect on grant table manipulation, see *Note server-sql-mode::, and *Note grant::. First, use the *Note `mysql': 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 will also need to supply a `--password' or `-p' option, both for this *Note `mysql': mysql. command and for those later in this section. After connecting to the server as `root', you can add new accounts. The following statements use *Note `GRANT': grant. to set up four new accounts: mysql> CREATE USER 'monty'@'localhost' IDENTIFIED BY 'some_pass'; mysql> GRANT ALL PRIVILEGES ON *.* TO 'monty'@'localhost' -> WITH GRANT OPTION; mysql> CREATE USER 'monty'@'%' IDENTIFIED BY 'some_pass'; mysql> GRANT ALL PRIVILEGES ON *.* TO 'monty'@'%' -> WITH GRANT OPTION; mysql> CREATE USER 'admin'@'localhost'; mysql> GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost'; mysql> CREATE USER 'dummy'@'localhost'; The accounts created by these statements have the following properties: * Two of the accounts have a user name of `monty' and a password of `some_pass'. Both accounts are superuser accounts with full privileges to do anything. The `'monty'@'localhost'' account can be used only when connecting from the local host. The `'monty'@'%'' account uses the `'%'' wildcard for the host part, so it can be used to connect from any host. It is necessary to have both accounts for `monty' to be able to connect from anywhere as `monty'. Without the `localhost' account, the anonymous-user account for `localhost' that is created by *Note `mysql_install_db': mysql-install-db. would take precedence when `monty' connects from the local host. As a result, `monty' would be treated as an anonymous user. The reason for this is that the anonymous-user account has a more specific `Host' column value than the `'monty'@'%'' account and thus comes earlier in the `user' table sort order. (`user' table sorting is discussed in *Note connection-access::.) * The `'admin'@'localhost'' account has no password. This 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 *Note `mysqladmin reload': mysqladmin, *Note `mysqladmin refresh': mysqladmin, and *Note `mysqladmin flush-XXX': mysqladmin. commands, as well as *Note `mysqladmin processlist': mysqladmin . No privileges are granted for accessing any databases. You could add such privileges later by issuing other *Note `GRANT': grant. statements. * The `'dummy'@'localhost'' account has no password. 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 later. The statements that create accounts with no password will fail if the `NO_AUTO_CREATE_USER' SQL mode is enabled. To deal with this, use an `IDENTIFIED BY' clause that specifies a nonempty password. To check the privileges for an account, use *Note `SHOW GRANTS': show-grants.: mysql> SHOW GRANTS FOR 'admin'@'localhost'; +-----------------------------------------------------+ | Grants for admin@localhost | +-----------------------------------------------------+ | GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' | +-----------------------------------------------------+ As an alternative to *Note `CREATE USER': create-user. and *Note `GRANT': grant, you can create the same accounts directly by issuing *Note `INSERT': insert. statements and then telling the server to reload the grant tables using *Note `FLUSH PRIVILEGES': flush.: shell> mysql --user=root mysql mysql> INSERT INTO user -> VALUES('localhost','monty',PASSWORD('some_pass'), -> 'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y'); mysql> INSERT INTO user -> VALUES('%','monty',PASSWORD('some_pass'), -> 'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y', -> 'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y', -> '','','','',0,0,0,0); mysql> INSERT INTO user SET Host='localhost',User='admin', -> Reload_priv='Y', Process_priv='Y'; mysql> INSERT INTO user (Host,User,Password) -> VALUES('localhost','dummy',''); mysql> FLUSH PRIVILEGES; When you create accounts with *Note `INSERT': insert, it is necessary to use *Note `FLUSH PRIVILEGES': flush. to tell the server to reload the grant tables. Otherwise, the changes go unnoticed until you restart the server. With *Note `CREATE USER': create-user, *Note `FLUSH PRIVILEGES': flush. is unnecessary. The reason for using the `PASSWORD()' function with *Note `INSERT': insert. is to encrypt the password. The *Note `CREATE USER': create-user. statement encrypts the password for you, so `PASSWORD()' is unnecessary. The `'Y'' values enable privileges for the accounts. Depending on your MySQL version, you may have to use a different number of `'Y'' values in the first two *Note `INSERT': insert. statements. The *Note `INSERT': insert. statement for the `admin' account employs the more readable extended *Note `INSERT': insert. syntax using `SET'. In the *Note `INSERT': insert. statement for the `dummy' account, only the `Host', `User', and `Password' columns in the `user' table row are assigned values. None of the privilege columns are set explicitly, so MySQL assigns them all the default value of `'N''. This is equivalent to what *Note `CREATE USER': create-user. does. If strict SQL mode is enabled, all columns that have no default value must have a value specified. In this case, *Note `INSERT': insert. statements must explicitly specify values for the `ssl_cipher', `x509_issuer', and `x509_subject' columns. To set up a superuser account, it is necessary only to insert a `user' table row with all privilege columns set to `'Y''. The `user' table privileges are global, so no entries in any of the other grant tables are needed. The next examples create three accounts and give them access to specific databases. Each of them has a user name of `custom' and password of `obscure'. To create the accounts with *Note `CREATE USER': create-user. and *Note `GRANT': grant, use the following statements: shell> mysql --user=root mysql mysql> CREATE USER 'custom'@'localhost' IDENTIFIED BY 'obscure'; mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP -> ON bankaccount.* -> TO 'custom'@'localhost'; mysql> CREATE USER 'custom'@'host47.example.com' IDENTIFIED BY 'obscure'; mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP -> ON expenses.* -> TO 'custom'@'host47.example.com'; mysql> CREATE USER 'custom'@'server.domain' IDENTIFIED BY 'obscure'; mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP -> ON customer.* -> TO 'custom'@'server.domain'; 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, but only from the host `server.domain'. To set up the `custom' accounts without *Note `GRANT': grant, use *Note `INSERT': insert. statements as follows to modify the grant tables directly: shell> mysql --user=root mysql mysql> INSERT INTO user (Host,User,Password) -> VALUES('localhost','custom',PASSWORD('obscure')); mysql> INSERT INTO user (Host,User,Password) -> VALUES('host47.example.com','custom',PASSWORD('obscure')); mysql> INSERT INTO user (Host,User,Password) -> VALUES('server.domain','custom',PASSWORD('obscure')); mysql> INSERT INTO db -> (Host,Db,User,Select_priv,Insert_priv, -> Update_priv,Delete_priv,Create_priv,Drop_priv) -> VALUES('localhost','bankaccount','custom', -> 'Y','Y','Y','Y','Y','Y'); mysql> INSERT INTO db -> (Host,Db,User,Select_priv,Insert_priv, -> Update_priv,Delete_priv,Create_priv,Drop_priv) -> VALUES('host47.example.com','expenses','custom', -> 'Y','Y','Y','Y','Y','Y'); mysql> INSERT INTO db -> (Host,Db,User,Select_priv,Insert_priv, -> Update_priv,Delete_priv,Create_priv,Drop_priv) -> VALUES('server.domain','customer','custom', -> 'Y','Y','Y','Y','Y','Y'); mysql> FLUSH PRIVILEGES; The first three *Note `INSERT': insert. statements add `user' table entries that permit the user `custom' to connect from the various hosts with the given password, but grant no global privileges (all privileges are set to the default value of `'N''). The next three *Note `INSERT': insert. statements add `db' table entries that grant privileges to `custom' for the `bankaccount', `expenses', and `customer' databases, but only when accessed from the proper hosts. As usual when you modify the grant tables directly, you must tell the server to reload them with *Note `FLUSH PRIVILEGES': flush. so that the privilege changes take effect. To create a user who has access from all machines in a given domain (for example, `mydomain.com'), you can use the ``%'' wildcard character in the host part of the account name: mysql> CREATE USER 'myname'@'%.mydomain.com' IDENTIFIED BY 'mypass'; To do the same thing by modifying the grant tables directly, do this: mysql> INSERT INTO user (Host,User,Password,...) -> VALUES('%.mydomain.com','myname',PASSWORD('mypass'),...); mysql> FLUSH PRIVILEGES;  File: manual.info, Node: removing-users, Next: user-resources, Prev: adding-users, Up: user-account-management 6.3.3 Removing User Accounts ---------------------------- To remove an account, use the *Note `DROP USER': drop-user. statement, which is described in *Note drop-user::.  File: manual.info, Node: user-resources, Next: assigning-passwords, Prev: removing-users, Up: user-account-management 6.3.4 Setting Account Resource Limits ------------------------------------- One means of limiting 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 many MySQL administrators, particularly those working for Internet Service Providers. In MySQL 5.1, you can limit use of the following server resources for individual accounts: * The number of queries that an account can issue per hour * The number of updates that 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.3, an `account' was assessed against the actual host from which a user connects. This older method 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 set resource limits for an account, use the *Note `GRANT': grant. statement (see *Note grant::). 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'; mysql> GRANT ALL ON customer.* TO 'francis'@'localhost' -> 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 existing limits for an account, use a *Note `GRANT USAGE': grant. statement at the global level (`ON *.*'). The following statement changes the query limit for `francis' to 100: mysql> GRANT USAGE ON *.* TO '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> GRANT USAGE ON *.* TO '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 resource limits specified with *Note `GRANT': grant.: GRANT ... TO 'user1'@'localhost' WITH MAX_USER_CONNECTIONS 0; GRANT ... TO 'user2'@'localhost' WITH MAX_USER_CONNECTIONS 5; GRANT ... TO 'user3'@'localhost' WITH MAX_USER_CONNECTIONS 20; `user1' has a connection limit of 10 (the global `max_user_connections' value) because it has a zero `MAX_USER_CONNECTIONS' limit). `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 *Note grant-table-structure::.) If your `user' table does not have these columns, it must be upgraded; see *Note mysql-upgrade::. 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, further connections for the account are rejected until that hour is up. Similarly, if the account reaches its limit on the number of queries or updates, further queries or updates are rejected until the hour is up. In all such cases, an appropriate error message is issued. Resource counting is done 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 *Note `FLUSH USER_RESOURCES': flush. statement. The counts also can be reset by reloading the grant tables (for example, with a *Note `FLUSH PRIVILEGES': flush. statement or a *Note `mysqladmin reload': mysqladmin. command). * The counts for an individual account can be set to zero by re-granting it any of its limits. To do this, use *Note `GRANT USAGE': grant. as described earlier and specify a limit value equal to the value that the account currently has. Counter resets do not affect the `MAX_USER_CONNECTIONS' limit. All counts begin at zero when the server starts; counts are not carried over through a restart. 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.  File: manual.info, Node: assigning-passwords, Next: ssl-connections, Prev: user-resources, Up: user-account-management 6.3.5 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. To assign a password when you create a new account with *Note `CREATE USER': create-user, include an `IDENTIFIED BY' clause: mysql> CREATE USER 'jeffrey'@'localhost' -> IDENTIFIED BY 'mypass'; To assign or change a password for an existing account, one way is to issue a *Note `SET PASSWORD': set-password. statement: mysql> SET PASSWORD FOR -> 'jeffrey'@'localhost' = PASSWORD('mypass'); MySQL stores passwords in the `user' table in the `mysql' database. Only users such as `root' that have update access to the `mysql' database can change the password for other users. If you are not connected as an anonymous user, you can change your own password by omitting the `FOR' clause: mysql> SET PASSWORD = PASSWORD('mypass'); The `old_passwords' system variable value determines the hashing method used by `PASSWORD()'. If you specify the password using that function and *Note `SET PASSWORD': set-password. rejects the password as not being in the correct format, it may be necessary to set `old_passwords' to change the hashing method. For descriptions of the permitted values, see *Note server-system-variables::. In MySQL 5.1, enabling the `read_only' system variable prevents the use of the *Note `SET PASSWORD': set-password. statement by any user not having the `SUPER' privilege. You can also use a *Note `GRANT USAGE': grant. statement at the global level (`ON *.*') to assign a password to an account without affecting the account's current privileges: mysql> GRANT USAGE ON *.* TO 'jeffrey'@'localhost' -> IDENTIFIED BY 'mypass'; To assign a password from the command line, use the *Note `mysqladmin': mysqladmin. command: shell> mysqladmin -u USER_NAME -h HOST_NAME password "NEWPWD" The account for which this command sets the password is the one with a `user' table row that matches USER_NAME in the `User' column and the client host _from which you connect_ in the `Host' column. During authentication when a client connects to the server, MySQL treats the password in the `user' table as an encrypted hash value (the value that `PASSWORD()' would return for the password). When assigning a password to an account, it is important to store an encrypted value, not the plaintext password. Use the following guidelines: * When you assign a password using *Note `CREATE USER': create-user, *Note `GRANT': grant. with an `IDENTIFIED BY' clause, or the *Note `mysqladmin password': mysqladmin. command, they encrypt the password for you. Specify the literal plaintext password: mysql> CREATE USER 'jeffrey'@'localhost' -> IDENTIFIED BY 'mypass'; * For *Note `CREATE USER': create-user. or *Note `GRANT': grant, you can avoid sending the plaintext password if you know the hash value that `PASSWORD()' would return for the password. Specify the hash value preceded by the keyword `PASSWORD': mysql> CREATE USER 'jeffrey'@'localhost' -> IDENTIFIED BY PASSWORD '*90E462C37378CED12064BB3388827D2BA3A9B689'; * When you assign an account a nonempty password using *Note `SET PASSWORD': set-password, you must use the `PASSWORD()' function to encrypt the password, otherwise the password is stored as plaintext. Suppose that you assign a password like this: mysql> SET PASSWORD FOR -> 'jeffrey'@'localhost' = 'mypass'; The result is that the literal value `'mypass'' is stored as the password in the `user' table, not the encrypted value. When `jeffrey' attempts to connect to the server using this password, the value is encrypted and compared to the value stored in the `user' table. However, the stored value is the literal string `'mypass'', so the comparison fails and the server rejects the connection with an `Access denied' error. *Note*: `PASSWORD()' encryption differs from Unix password encryption. See *Note user-names::. It is preferable to assign passwords using *Note `SET PASSWORD': set-password, *Note `GRANT': grant, or *Note `mysqladmin': mysqladmin, but it is also possible to modify the `user' table directly. In this case, you must also use *Note `FLUSH PRIVILEGES': flush. to cause the server to reread the grant tables. Otherwise, the change remains unnoticed by the server until you restart it. * To establish a password for a new account, provide a value for the `Password' column: mysql> INSERT INTO mysql.user (Host,User,Password) -> VALUES('localhost','jeffrey',PASSWORD('mypass')); mysql> FLUSH PRIVILEGES; * To change the password for an existing account, use *Note `UPDATE': update. to set the `Password' column value: mysql> UPDATE mysql.user SET Password = PASSWORD('bagel') -> WHERE Host = 'localhost' AND User = 'francis'; mysql> FLUSH PRIVILEGES;  File: manual.info, Node: ssl-connections, Next: windows-and-ssh, Prev: assigning-passwords, Up: user-account-management 6.3.6 Using SSL for Secure Connections -------------------------------------- * Menu: * ssl-basics:: Basic SSL Concepts * configuring-for-ssl:: Configuring MySQL for SSL * using-ssl-connections:: Using SSL Connections * ssl-options:: SSL Command Options * creating-ssl-certs:: Setting Up SSL Certificates and Keys for MySQL MySQL supports secure (encrypted) connections between MySQL clients and the server using the Secure Sockets Layer (SSL) protocol. This section discusses how to use SSL connections. For information on how to require users to use SSL connections, see the discussion of the `REQUIRE' clause of the *Note `GRANT': grant. statement in *Note grant::. The standard configuration of MySQL is intended to be as fast as possible, so encrypted connections are not used by default. For applications that require the security provided by encrypted connections, the extra computation to encrypt the data is worthwhile. MySQL enables encryption on a per-connection basis. You can choose an unencrypted connection or a secure encrypted SSL connection according the requirements of individual applications. Secure connections are based on the OpenSSL API and are available through the MySQL C API. Replication uses the C API, so secure connections can be used between master and slave servers. See *Note replication-solutions-ssl::. Another way to connect securely is from within an SSH connection to the MySQL server host. For an example, see *Note windows-and-ssh::.  File: manual.info, Node: ssl-basics, Next: configuring-for-ssl, Prev: ssl-connections, Up: ssl-connections 6.3.6.1 Basic SSL Concepts .......................... To understand how MySQL uses SSL, it is necessary to explain some basic SSL and X509 concepts. People who are familiar with these concepts can skip this part of the discussion. By default, MySQL uses unencrypted connections between the client and the server. This means that someone with access to the network could watch all your traffic and look at the data being sent or received. They could even change the data while it is in transit between client and server. To improve security a little, you can compress client/server traffic by using the `--compress' option when invoking client programs. However, this does not foil a determined attacker. When you need to move information over a network in a secure fashion, an unencrypted connection is unacceptable. Encryption is the way to make any kind of data unreadable. 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. SSL is a protocol that uses different encryption algorithms to ensure that data received over a public network can be trusted. It has mechanisms to detect any data change, loss, or replay. SSL also incorporates algorithms that provide identity verification using the X509 standard. X509 makes it possible to identify someone on the Internet. It is most commonly used in e-commerce applications. 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 show the certificate to another party as proof of identity. A certificate consists of its owner's public key. Any data encrypted with this public key can be decrypted only using the corresponding secret key, which is held by the owner of the certificate. For more information about SSL, X509, encryption, or public-key cryptography, perform an Internet search for the keywords in which you are interested.  File: manual.info, Node: configuring-for-ssl, Next: using-ssl-connections, Prev: ssl-basics, Up: ssl-connections 6.3.6.2 Configuring MySQL for SSL ................................. To use SSL connections between the MySQL server and client programs, your system must support either OpenSSL or yaSSL, and your version of MySQL must be built with SSL support. To make it easier to use secure connections, MySQL is bundled with yaSSL, which uses the same licensing model as MySQL. (OpenSSL uses an Apache-style license.) yaSSL support is available on all MySQL platforms supported by Oracle Corporation. To get secure connections to work with MySQL and SSL, you must do the following: 1. If you are not using a binary (precompiled) version of MySQL that has been built with SSL support, and you are going to use OpenSSL rather than the bundled yaSSL library, install OpenSSL if it has not already been installed. We have tested MySQL with OpenSSL 0.9.6. To obtain OpenSSL, visit `http://www.openssl.org'. Building MySQL using OpenSSL requires a shared OpenSSL library, otherwise linker errors occur. Alternatively, build MySQL using yaSSL. 2. If you are not using a binary (precompiled) version of MySQL that has been built with SSL support, configure a MySQL source distribution to use SSL. When you configure MySQL, invoke the `configure' script like this: shell> ./configure --with-ssl That command configures the distribution to use the bundled yaSSL library. To use OpenSSL instead, specify the `--with-ssl' option with the path to the directory where the OpenSSL header files and libraries are located: shell> ./configure --with-ssl=PATH *Note*: On some platforms the full determination of the You may also need to explicitly add the SSL library and header directories. You can do this by setting the `LDFLAGS', `CFLAGS', `CPPFLAGS' and `CXXFLAGS' with the full directories. For example: shell> LDFLAGS="-L/usr/local/ssl/lib" CFLAGS="-I/usr/local/ssl/include" \ CPPFLAGS="-I/usr/local/ssl/include" CXXFLAGS="-I/usr/local/ssl/include" \ configure --with-ssl=/usr/local/ssl Before MySQL 5.1.11, you must use the appropriate option to select the SSL library that you want to use. For yaSSL: shell> ./configure --with-yassl For OpenSSL: shell> ./configure --with-openssl Then compile and install the distribution. On Unix platforms, yaSSL retrieves true random numbers from either `/dev/urandom' or `/dev/random'. Bug#13164 lists workarounds for some very old platforms which do not support these devices. 3. To check whether a *Note `mysqld': mysqld. server supports SSL, 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 SSL connections. If the value is `DISABLED', the server is capable of supporting SSL connections but was not started with the appropriate `--ssl-XXX' options to enable them to be used; see *Note using-ssl-connections::.  File: manual.info, Node: using-ssl-connections, Next: ssl-options, Prev: configuring-for-ssl, Up: ssl-connections 6.3.6.3 Using SSL Connections ............................. To enable SSL connections, your MySQL distribution must be built with SSL support, as described in *Note configuring-for-ssl::. In addition, the proper SSL-related options must be used to specify the appropriate certificate and key files. For a complete list of SSL options, see *Note ssl-options::. To start the MySQL server so that it permits clients to connect using SSL, use the options that identify the certificate and key files the server uses when establishing a secure connection: * `--ssl-ca' identifies the Certificate Authority (CA) certificate. * `--ssl-cert' identifies the server public key certificate. This can be sent to the client and authenticated against the CA certificate that it has. * `--ssl-key' identifies the server private key. For example, start the server like this: shell> mysqld --ssl-ca=CA-CERT.PEM \ --ssl-cert=SERVER-CERT.PEM \ --ssl-key=SERVER-KEY.PEM Each option names a file in PEM format. For instructions on generating the required SSL certificate and key files, see *Note creating-ssl-certs::. If you have a MySQL source distribution, you can also test your setup using the demonstration certificate and key files in the `mysql-test/std_data' directory of the distribution. Similar options are used on the client side, although in this case, `--ssl-cert' and `--ssl-key' identify the client public and private key. Note that the Certificate Authority certificate, if specified, must be the same as used by the server. To establish a secure connection to a MySQL server with SSL support, the options that a client must specify depend on the SSL requirements of the MySQL account used by the client. (See the discussion of the `REQUIRE' clause in *Note grant::.) Suppose that you want to connect using an account that has no special SSL requirements or was created using a *Note `GRANT': grant. statement that includes the `REQUIRE SSL' option. As a recommended set of SSL options, start the server with at least `--ssl-cert' and `--ssl-key', and invoke the client with `--ssl-ca'. A client can connect securely like this: shell> mysql --ssl-ca=CA-CERT.PEM To require that a client certificate also be specified, create the account using the `REQUIRE X509' option. Then the client must also specify the proper client key and certificate files or the server will reject the connection: shell> mysql --ssl-ca=CA-CERT.PEM \ --ssl-cert=CLIENT-CERT.PEM \ --ssl-key=CLIENT-KEY.PEM A client can determine whether the current connection with the server uses SSL by checking the value of the `Ssl_cipher' status variable. The value of `Ssl_cipher' is nonempty if SSL is used, and empty otherwise. For example: mysql> SHOW STATUS LIKE 'Ssl_cipher'; +---------------+--------------------+ | Variable_name | Value | +---------------+--------------------+ | Ssl_cipher | DHE-RSA-AES256-SHA | +---------------+--------------------+ For the *Note `mysql': 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-AES256-SHA ... The C API enables application programs to use SSL: * To establish a secure connection, use the *Note `mysql_ssl_set()': mysql-ssl-set. C API function to set the appropriate certificate options before calling *Note `mysql_real_connect()': mysql-real-connect. See *Note mysql-ssl-set::. * To determine whether SSL is in use after the connection is established, use *Note `mysql_get_ssl_cipher()': mysql-get-ssl-cipher. A non-`NULL' return value indicates a secure connection and names the SSL cipher used for encryption. A `NULL' return value indicates that SSL is not being used. See *Note mysql-get-ssl-cipher::. Replication uses the C API, so secure connections can be used between master and slave servers. See *Note replication-solutions-ssl::.  File: manual.info, Node: ssl-options, Next: creating-ssl-certs, Prev: using-ssl-connections, Up: ssl-connections 6.3.6.4 SSL Command Options ........................... This section describes options that are used to specify whether to use SSL and the names of SSL certificate and key files. These options can be given on the command line or in an option file. They are not available unless MySQL has been built with SSL support. See *Note configuring-for-ssl::. (There are also `--master-ssl*' options that can be used for setting up a secure connection from a slave replication server to a master server; see *Note replication-options::.) *SSL Option/Variable Summary* Name Cmd-Line Option file System Var Status Var Var Scope Dynamic have_openssl Yes Global No have_ssl Yes Global No skip-ssl Yes Yes ssl Yes Yes ssl-ca Yes Yes Global No - _Variable_: Yes Global No ssl_ca ssl-capath Yes Yes Global No - _Variable_: Yes Global No ssl_capath ssl-cert Yes Yes Global No - _Variable_: Yes Global No ssl_cert ssl-cipher Yes Yes Global No - _Variable_: Yes Global No ssl_cipher ssl-key Yes Yes Global No - _Variable_: Yes Global No ssl_key ssl-verify-server-certYes Yes * `--ssl' For the server, this option specifies that the server permits SSL connections. For a client program, it permits the client to connect to the server using SSL, but this option is not sufficient in itself to cause an SSL connection to be used. As a recommended set of options to enable SSL connections, use at least `--ssl-cert' and `--ssl-key' on the server side and `--ssl-ca' on the client side. `--ssl' is implied by other `--ssl-XXX' options as indicated in the descriptions for those options. For this reason, `--ssl' is not usually specified explicitly. It is more often used explicitly in its opposite form to override other SSL options and indicate that SSL should _not_ be used. To do this, specify the option as `--skip-ssl' or `--ssl=0'. For example, you might have SSL options specified in the `[client]' group of your option file to use SSL connections by default when you invoke MySQL client programs. To use an unencrypted connection instead, invoke the client program with `--skip-ssl' on the command line to override the options in the option file. Use of `--ssl' does not _require_ an SSL connection to be used, it only permits it. For example, if you specify this option for a client program but the server has not been configured to permit SSL connections, an unencrypted connection is used. The secure way to require use of an SSL connection is to create a MySQL account that includes at least a `REQUIRE SSL' clause in the *Note `GRANT': grant. statement. In this case, connections for that account will be rejected unless MySQL supports SSL connections and the server and client have been started with the proper SSL options. The `REQUIRE' clause permits other SSL-related restrictions as well. These can be used for stricter requirements than `REQUIRE SSL'. The description of `REQUIRE' in *Note grant::, provides additional detail about which SSL command options may or must be specified by clients that connect using accounts that are created using the various `REQUIRE' options. * `--ssl-ca=FILE_NAME' The path to a file in PEM format that contains a list of trusted SSL certificate authorities. This option implies `--ssl'. As of MySQL 5.1.18, if you use SSL when establishing a client connection, you can tell the client not to authenticate the server certificate by specifying neither `--ssl-ca' nor `--ssl-capath'. The server still verifies the client according to any applicable requirements established using *Note `GRANT': grant. statements for the client, and it still uses any `--ssl-ca'/`--ssl-capath' values that were passed to server at startup. * `--ssl-capath=DIRECTORY_NAME' The path to a directory that contains trusted SSL certificate authority certificates in PEM format. This option implies `--ssl'. As of MySQL 5.1.18, if you use SSL when establishing a client connection, you can tell the client not to authenticate the server certificate by specifying neither `--ssl-ca' nor `--ssl-capath'. The server still verifies the client according to any applicable requirements established using *Note `GRANT': grant. statements for the client, and it still uses any `--ssl-ca'/`--ssl-capath' values that were passed to server at startup. MySQL distributions built with OpenSSL support the `--ssl-capath' option. Distributions built with 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. Then specify the new file as the value of the `--ssl-capath' option. * `--ssl-cert=FILE_NAME' The name of the SSL certificate file in PEM format to use for establishing a secure connection. This option implies `--ssl'. * `--ssl-cipher=CIPHER_LIST' A list of permissible ciphers to use for SSL encryption. If no cipher in the list is supported, SSL connections will not work. 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-AES256-SHA:AES128-SHA OpenSSL supports a more flexible syntax for specifying ciphers, as described in the OpenSSL documentation at `http://www.openssl.org/docs/apps/ciphers.html'. However, yaSSL does not, so attempts to use that extended syntax fails for a MySQL distribution built with yaSSL. * `--ssl-key=FILE_NAME' The name of the SSL key file in PEM format to use for establishing a secure connection. If the MySQL distribution was built using OpenSSL and the key file is protected by a passphrase, the program will prompt 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. If the MySQL distribution was built using yaSSL and the key file is protected by a passphrase, an error occurs. * `--ssl-verify-server-cert' This option is available for client programs only, not the server. It causes the client to check the server's Common Name value in the certificate that the server sends to the client. The client verifies that name against the host name the client uses for connecting to the server, and the connection fails if there is a mismatch. This feature can be used to prevent man-in-the-middle attacks. Verification is disabled by default. This option was added in MySQL 5.1.11.  File: manual.info, Node: creating-ssl-certs, Prev: ssl-options, Up: ssl-connections 6.3.6.5 Setting Up SSL Certificates and Keys for MySQL ...................................................... This section demonstrates how 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. *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) * 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 shell> rm -rf newcerts shell> mkdir newcerts && cd newcerts # Create CA certificate shell> openssl genrsa 2048 > ca-key.pem shell> openssl req -new -x509 -nodes -days 3600 \ -key ca-key.pem -out ca-cert.pem # Create server certificate, remove passphrase, and sign it # server-cert.pem = public key, server-key.pem = private key shell> openssl req -newkey rsa:2048 -days 3600 \ -nodes -keyout server-key.pem -out server-req.pem shell> openssl rsa -in server-key.pem -out server-key.pem shell> openssl x509 -req -in server-req.pem -days 3600 \ -CA ca-cert.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 shell> openssl req -newkey rsa:2048 -days 3600 \ -nodes -keyout client-key.pem -out client-req.pem shell> openssl rsa -in client-key.pem -out client-key.pem shell> openssl x509 -req -in client-req.pem -days 3600 \ -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem After generating the certificates, verify them: shell> openssl verify -CAfile ca-cert.pem server-cert.pem client-cert.pem server-cert.pem: OK client-cert.pem: OK Now you have a set of files that can be used as follows: * `ca-cert.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. To use the files to test SSL connections, see *Note using-ssl-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 to test SSL connections as described in *Note using-ssl-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-cert.pem \ -days 3600 -config $DIR/openssl.cnf # Sample output: # Using configuration from /home/monty/openssl/openssl.cnf # Generating a 1024 bit RSA private key # ................++++++ # .........++++++ # writing new private key to '/home/monty/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/monty/openssl/openssl.cnf # Generating a 1024 bit RSA private key # ..++++++ # ..........++++++ # writing new private key to '/home/monty/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-cert.pem -policy policy_anything \ -out $DIR/server-cert.pem -config $DIR/openssl.cnf \ -infiles $DIR/server-req.pem # Sample output: # Using configuration from /home/monty/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/monty/openssl/openssl.cnf # Generating a 1024 bit RSA private key # .....................................++++++ # .............................................++++++ # writing new private key to '/home/monty/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-cert.pem -policy policy_anything \ -out $DIR/client-cert.pem -config $DIR/openssl.cnf \ -infiles $DIR/client-req.pem # Sample output: # Using configuration from /home/monty/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 < $DIR/my.cnf [client] ssl-ca=$DIR/ca-cert.pem ssl-cert=$DIR/client-cert.pem ssl-key=$DIR/client-key.pem [mysqld] ssl-ca=$DIR/ca-cert.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: 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:\> Depending on your version of Windows, the preceding path-setting instructions might differ slightly. After OpenSSL has been installed, use instructions similar to those from from Example 1 (shown earlier in this section), with the following changes: * Change the following Unix commands: # Create clean environment shell> rm -rf newcerts shell> mkdir newcerts && cd newcerts On Windows, use these commands instead: # Create clean environment shell> md c:\newcerts shell> 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 to test SSL connections, see *Note using-ssl-connections::.  File: manual.info, Node: windows-and-ssh, Next: account-activity-auditing, Prev: ssl-connections, Up: user-account-management 6.3.7 Connecting to MySQL Remotely from Windows with SSH -------------------------------------------------------- This section describes how to get a secure connection to a remote MySQL server with SSH. The information was provided by David Carlson . 1. Install an SSH client on your Windows machine. As a user, the best nonfree one I have found is from `SecureCRT' from `http://www.vandyke.com/'. Another option is `f-secure' from `http://www.f-secure.com/'. You can also find some free ones on `Google' at `http://directory.google.com/Top/Computers/Internet/Protocols/SSH/Clients/Windows/'. 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.  File: manual.info, Node: account-activity-auditing, Prev: windows-and-ssh, Up: user-account-management 6.3.8 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 (as of MySQL 5.1.12) * 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. If 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()' 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 | +----------------------------------------+  File: manual.info, Node: backup-and-recovery, Next: optimization, Prev: security, Up: Top 7 Backup and Recovery ********************* * Menu: * backup-types:: Backup and Recovery Types * backup-methods:: Database Backup Methods * backup-strategy-example:: Example Backup and Recovery Strategy * using-mysqldump:: Using `mysqldump' for Backups * point-in-time-recovery:: Point-in-Time (Incremental) Recovery Using the Binary Log * myisam-table-maintenance:: `MyISAM' Table Maintenance and Crash 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 *Note mysql-enterprise-backup::. * A forum dedicated to backup issues is available at `http://forums.mysql.com/list.php?93'. * Details for *Note `mysqldump': mysqldump, *Note `mysqlhotcopy': mysqlhotcopy, and other MySQL backup programs can be found in *Note programs::. * The syntax of the SQL statements described here is given in *Note sql-syntax::. * For additional information about `InnoDB' backup procedures, see *Note 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 *Note replication::. * MySQL Cluster provides a high-availability, high-redundancy version of MySQL adapted for the distributed computing environment. See *Note mysql-cluster::. For information specifically about MySQL Cluster backup, see *Note mysql-cluster-backup::. * Distributed Replicated Block Device (DRBD) is another high-availability solution. It works by replicating a block device from a primary server to a secondary server at the block level. See *Note ha-overview::  File: manual.info, Node: backup-types, Next: backup-methods, Prev: backup-and-recovery, Up: backup-and-recovery 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 (*Note `CREATE DATABASE': create-database, *Note `CREATE TABLE': create-table. statements) and content (*Note `INSERT': 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. 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 *Note `mysqldump': mysqldump. program and the *Note `SELECT ... INTO OUTFILE': select. statement. These work for any storage engine, even `MEMORY'. * To restore logical backups, SQL-format dump files can be processed using the *Note `mysql': mysql. client. To load delimited-text files, use the *Note `LOAD DATA INFILE': load-data. statement or the *Note `mysqlimport': mysqlimport. client. 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. Data from `MEMORY' tables cannot be backed up this way because their contents are not stored on disk. * Physical backup methods are faster than logical because they involve only file copying without conversion. * Output is more compact than for logical 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. (Each `MyISAM' table corresponds uniquely to a set of files, but an `InnoDB' table shares file storage with other `InnoDB' tables.) * In addition to databases, the backup can include any related files such as log or configuration files. * 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. * Physical backup tools include file system-level commands (such as `cp', `scp', `tar', `rsync'), *Note `mysqlhotcopy': mysqlhotcopy. for `MyISAM' tables, `ibbackup' for `InnoDB' tables, or `START BACKUP' for *Note `NDB': mysql-cluster. tables. * For restore, files copied at the file system level or with *Note `mysqlhotcopy': mysqlhotcopy. can be copied back to their original locations with file system commands; `ibbackup' restores `InnoDB' tables, and *Note `ndb_restore': mysql-cluster-programs-ndb-restore. restores *Note `NDB': mysql-cluster. tables. *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. * *Note `mysqldump': mysqldump. can connect to local or remote servers. For SQL output (`CREATE' and *Note `INSERT': 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. * *Note `mysqlhotcopy': mysqlhotcopy. performs only local backups: It connects to the server to lock it against data modifications and then copies local table files. * *Note `SELECT ... INTO OUTFILE': select-into. 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 *Note `InnoDB': innodb-storage-engine. tables, this is not a typical issue. For programs to check *Note `MyISAM': myisam-storage-engine. tables and repair them if problems are found, see *Note 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.  File: manual.info, Node: backup-methods, Next: backup-strategy-example, Prev: backup-types, Up: backup-and-recovery 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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_mysql_enterprise_backup) product to do physical (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_physical) backups of entire instances or selected databases, tables, or both. This product includes features for incremental (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_incremental_backup) and compressed (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_compressed_backup) 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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_warm_backup) mechanism. For an overview of the MySQL Enterprise Backup product, see *Note mysql-enterprise-backup::. * Making Backups with *Note `mysqldump': mysqldump. or *Note `mysqlhotcopy': mysqlhotcopy. * The *Note `mysqldump': mysqldump. program and the *Note `mysqlhotcopy': mysqlhotcopy. script can make backups. *Note `mysqldump': mysqldump. is more general because it can back up all kinds of tables. *Note `mysqlhotcopy': mysqlhotcopy. works only with some storage engines. (See *Note using-mysqldump::, and *Note mysqlhotcopy::.) For `InnoDB' tables, it is possible to perform an online backup that takes no locks on tables using the `--single-transaction' option to *Note `mysqldump': mysqldump. See *Note 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: LOCK TABLES TBL_LIST READ; FLUSH TABLES TBL_LIST; 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 *Note `FLUSH TABLES': flush. statement is needed to ensure that the all active index pages are written to disk before you start the backup. See *Note lock-tables::, and *Note flush::. You can also create a binary backup simply by copying all table files, as long as the server isn't updating anything. The *Note `mysqlhotcopy': mysqlhotcopy. script uses this method. (But note that table file copying methods do not work if your database contains `InnoDB' tables. *Note `mysqlhotcopy': mysqlhotcopy. does not work for `InnoDB' tables because `InnoDB' does not necessarily store table contents in database directories. 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 *Note `SELECT * INTO OUTFILE 'FILE_NAME' FROM TBL_NAME': select-into. 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 *Note 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 *Note `CREATE TABLE': create-table. statements for the backed up tables) is to use *Note `mysqldump': mysqldump. with the `--tab' option. See *Note mysqldump-delimited-text::. To reload a delimited-text data file, use *Note `LOAD DATA INFILE': load-data. or *Note `mysqlimport': 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 *Note 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 *Note `FLUSH LOGS': flush. 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 *Note point-in-time-recovery::. The next time you do a full backup, you should also rotate the binary log using *Note `FLUSH LOGS': flush, *Note `mysqldump --flush-logs': mysqldump, or *Note `mysqlhotcopy --flushlog': mysqlhotcopy. See *Note mysqldump::, and *Note mysqlhotcopy::. * 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 *Note replication-solutions-backups::. If you are backing up a slave replication server, you should back up its `master.info' and `relay-log.info' files 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 *Note `LOAD DATA INFILE': load-data. 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 *Note `LOAD DATA INFILE': load-data. 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 *Note `REPAIR TABLE': repair-table. or *Note `myisamchk -r': myisamchk. first. That should work in 99.9% of all cases. If *Note `myisamchk': myisamchk. fails, see *Note 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 *Note `FLUSH TABLES WITH READ LOCK': flush. 2. From another shell, execute `mount vxfs snapshot'. 3. From the first client, execute *Note `UNLOCK TABLES': lock-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.  File: manual.info, Node: backup-strategy-example, Next: using-mysqldump, Prev: backup-methods, Up: backup-and-recovery 7.3 Example Backup and Recovery Strategy ======================================== * Menu: * backup-policy:: Establishing a Backup Policy * recovery-from-backups:: Using Backups for Recovery * backup-strategy-summary:: Backup Strategy Summary 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 *Note `mysqldump': mysqldump. and *Note `mysql': 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.  File: manual.info, Node: backup-policy, Next: recovery-from-backups, Prev: backup-strategy-example, Up: backup-strategy-example 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, *Note MySQL Enterprise Backup: mysql-enterprise-backup. can perform a physical backup (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_physical_backup) of an entire instance, with optimizations to minimize overhead and avoid disruption when backing up `InnoDB' data files; *Note `mysqldump': mysqldump. provides online logical backup (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_logical_backup). This discussion uses *Note `mysqldump': 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 --single-transaction --all-databases > backup_sunday_1_PM.sql The resulting `.sql' file produced by *Note `mysqldump': mysqldump. contains a set of SQL *Note `INSERT': 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 *Note `FLUSH TABLES WITH READ LOCK': flush.). 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 *Note `FLUSH': 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 *Note `mysqldump': mysqldump. does not change. (Changes made by other clients to `InnoDB' tables are not seen by the *Note `mysqldump': 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 *Note `FLUSH LOGS': flush. SQL statement or with a *Note `mysqladmin flush-logs': mysqladmin. command. *Note `mysqldump': 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 *Note `mysqldump': 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 *Note `mysqldump': 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 *Note `mysqldump': 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 newer. * 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 newer. 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 *Note `mysqladmin flush-logs': mysqladmin. 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 *Note `mysqladmin flush-logs': mysqladmin. 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 *Note `mysqldump --delete-master-logs': mysqldump. 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 *Note `PURGE BINARY LOGS': purge-binary-logs. statement explains what should be verified before deleting the MySQL binary logs. See *Note purge-binary-logs::.  File: manual.info, Node: recovery-from-backups, Next: backup-strategy-summary, Prev: backup-policy, Up: backup-strategy-example 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 *Note `mysqlbinlog': mysqlbinlog. and *Note `mysql': 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 *Note `mysqlbinlog': mysqlbinlog. to process binary log files, see *Note point-in-time-recovery::.  File: manual.info, Node: backup-strategy-summary, Prev: recovery-from-backups, Up: backup-strategy-example 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 *Note `mysqldump': mysqldump. command shown earlier in *Note backup-policy::, that makes an online, nonblocking backup. * Make periodic incremental backups by flushing the logs with *Note `FLUSH LOGS': flush. or *Note `mysqladmin flush-logs': mysqladmin.  File: manual.info, Node: using-mysqldump, Next: point-in-time-recovery, Prev: backup-strategy-example, Up: backup-and-recovery 7.4 Using `mysqldump' for Backups ================================= * Menu: * mysqldump-sql-format:: Dumping Data in SQL Format with `mysqldump' * reloading-sql-format-dumps:: Reloading SQL-Format Backups * mysqldump-delimited-text:: Dumping Data in Delimited-Text Format with `mysqldump' * reloading-delimited-text-dumps:: Reloading Delimited-Text Format Backups * mysqldump-tips:: `mysqldump' Tips This section describes how to use *Note `mysqldump': 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. *Note `mysqldump': mysqldump. produces two types of output, depending on whether the `--tab' option is given: * Without `--tab', *Note `mysqldump': 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 *Note `mysql': 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', *Note `mysqldump': 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 *Note `CREATE TABLE': create-table. statement for the table to *Note `mysqldump': mysqldump, which writes it as a file named `TBL_NAME.sql' in the output directory.  File: manual.info, Node: mysqldump-sql-format, Next: reloading-sql-format-dumps, Prev: using-mysqldump, Up: using-mysqldump 7.4.1 Dumping Data in SQL Format with `mysqldump' ------------------------------------------------- This section describes how to use *Note `mysqldump': mysqldump. to create SQL-format dump files. For information about reloading such dump files, see *Note reloading-sql-format-dumps::. By default, *Note `mysqldump': 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 *Note `mysqldump': 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, *Note `mysqldump': mysqldump. treats the first name as a database name and those following as table names. With `--all-databases' or `--databases', *Note `mysqldump': mysqldump. writes *Note `CREATE DATABASE': create-database. and *Note `USE': 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, *Note `mysqldump': mysqldump. writes a *Note `DROP DATABASE': drop-database. statement preceding each *Note `CREATE DATABASE': 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 *Note `CREATE DATABASE': create-database. or *Note `USE': 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 *Note `CREATE DATABASE': create-database. statement, the `--add-drop-database' option has no effect. If you use it, it produces no *Note `DROP DATABASE': 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  File: manual.info, Node: reloading-sql-format-dumps, Next: mysqldump-delimited-text, Prev: mysqldump-sql-format, Up: using-mysqldump 7.4.2 Reloading SQL-Format Backups ---------------------------------- To reload a dump file written by *Note `mysqldump': mysqldump. that consists of SQL statements, use it as input to the *Note `mysql': mysql. client. If the dump file was created by *Note `mysqldump': mysqldump. with the `--all-databases' or `--databases' option, it contains *Note `CREATE DATABASE': create-database. and *Note `USE': 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 *Note `mysql': mysql, use a `source' command: mysql> source dump.sql If the file is a single-database dump not containing *Note `CREATE DATABASE': create-database. and *Note `USE': 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 *Note `mysql': 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  File: manual.info, Node: mysqldump-delimited-text, Next: reloading-delimited-text-dumps, Prev: reloading-sql-format-dumps, Up: using-mysqldump 7.4.3 Dumping Data in Delimited-Text Format with `mysqldump' ------------------------------------------------------------ This section describes how to use *Note `mysqldump': mysqldump. to create delimited-text dump files. For information about reloading such dump files, see *Note reloading-delimited-text-dumps::. If you invoke *Note `mysqldump': 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 basename for these files. For a table named `t1', the files are named `t1.sql' and `t1.txt'. The `.sql' file contains a *Note `CREATE TABLE': 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 *Note `SELECT ... INTO OUTFILE': select-into. 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 *Note `mysqldump': mysqldump, which writes them to `.sql' files. These files therefore are owned by the user who executes *Note `mysqldump': 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 *Note `mysqldump': mysqldump. in the local directory (on the client host). For *Note `mysqldump --tab': mysqldump, 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 *Note `SELECT ... INTO OUTFILE': select-into.) To enable data files to be written using a different format, *Note `mysqldump': 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 *Note `mysqldump': 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.  File: manual.info, Node: reloading-delimited-text-dumps, Next: mysqldump-tips, Prev: mysqldump-delimited-text, Up: using-mysqldump 7.4.4 Reloading Delimited-Text Format Backups --------------------------------------------- For backups produced with *Note `mysqldump --tab': mysqldump, each table is represented in the output directory by an `.sql' file containing the *Note `CREATE TABLE': 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 *Note `mysql': 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 *Note `mysqlimport': mysqlimport. to load the data file is to use the *Note `LOAD DATA INFILE': load-data. statement from within the *Note `mysql': mysql. client: mysql> USE db1; mysql> LOAD DATA INFILE 't1.txt' INTO TABLE t1; If you used any data-formatting options with *Note `mysqldump': mysqldump. when you initially dumped the table, you must use the same options with *Note `mysqlimport': mysqlimport. or *Note `LOAD DATA INFILE': load-data. 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';  File: manual.info, Node: mysqldump-tips, Prev: reloading-delimited-text-dumps, Up: using-mysqldump 7.4.5 `mysqldump' Tips ---------------------- * Menu: * mysqldump-copying-database:: Making a Copy of a Database * mysqldump-copying-to-other-server:: Copy a Database from one Server to Another * mysqldump-stored-programs:: Dumping Stored Programs * mysqldump-definition-data-dumps:: Dumping Table Definitions and Content Separately * mysqldump-upgrade-testing:: Using `mysqldump' to Test for Upgrade Incompatibilities This section surveys techniques that enable you to use *Note `mysqldump': 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  File: manual.info, Node: mysqldump-copying-database, Next: mysqldump-copying-to-other-server, Prev: mysqldump-tips, Up: mysqldump-tips 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 *Note `mysqldump': mysqldump. command line because that causes `USE db1' to be included in the dump file, which overrides the effect of naming `db2' on the *Note `mysql': mysql. command line.  File: manual.info, Node: mysqldump-copying-to-other-server, Next: mysqldump-stored-programs, Prev: mysqldump-copying-database, Up: mysqldump-tips 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 *Note `mysqldump': mysqldump. command line causes the dump file to include *Note `CREATE DATABASE': create-database. and *Note `USE': 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 *Note `mysqldump': 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 *Note `mysqldump': mysqldump. command enables you to dump data from one database and load it into another.  File: manual.info, Node: mysqldump-stored-programs, Next: mysqldump-definition-data-dumps, Prev: mysqldump-copying-to-other-server, Up: mysqldump-tips 7.4.5.3 Dumping Stored Programs ............................... Several options control how *Note `mysqldump': 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'.  File: manual.info, Node: mysqldump-definition-data-dumps, Next: mysqldump-upgrade-testing, Prev: mysqldump-stored-programs, Up: mysqldump-tips 7.4.5.4 Dumping Table Definitions and Content Separately ........................................................ The `--no-data' option tells *Note `mysqldump': 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 *Note `mysqldump': 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  File: manual.info, Node: mysqldump-upgrade-testing, Prev: mysqldump-definition-data-dumps, Up: mysqldump-tips 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.  File: manual.info, Node: point-in-time-recovery, Next: myisam-table-maintenance, Prev: using-mysqldump, Up: backup-and-recovery 7.5 Point-in-Time (Incremental) Recovery Using the Binary Log ============================================================= * Menu: * point-in-time-recovery-times:: Point-in-Time Recovery Using Event Times * point-in-time-recovery-positions:: Point-in-Time Recovery Using Event Positions 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 *Note 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. 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 *Note 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. *Note 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 *Note `mysqlbinlog': mysqlbinlog. utility converts the events in the binary log files from binary format to text so that they can be executed or viewed. *Note `mysqlbinlog': mysqlbinlog. has options for selecting sections of the binary log based on event times or position of events within the log. See *Note 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 *Note `mysqlbinlog': mysqlbinlog. output using the *Note `mysql': 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 *Note `mysqlbinlog': 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 *Note `DROP DATABASE': 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 *Note `CREATE TEMPORARY TABLE': create-table. statement and the second log contains a statement that uses the temporary table. When the first *Note `mysql': mysql. process terminates, the server drops the temporary table. When the second *Note `mysql': 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"  File: manual.info, Node: point-in-time-recovery-times, Next: point-in-time-recovery-positions, Prev: point-in-time-recovery, Up: point-in-time-recovery 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 *Note `mysqlbinlog': mysqlbinlog, in *Note `DATETIME': 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 *Note `mysqlbinlog': 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 *Note `mysqlbinlog': 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 *Note `mysqlbinlog': mysqlbinlog. does not work well if multiple statements executed at the same time as the one to be excluded.  File: manual.info, Node: point-in-time-recovery-positions, Prev: point-in-time-recovery-times, Up: point-in-time-recovery 7.5.2 Point-in-Time Recovery Using Event Positions -------------------------------------------------- Instead of specifying dates and times, the `--start-position' and `--stop-position' options for *Note `mysqlbinlog': 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 *Note `mysqlbinlog': 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 *Note `mysqlbinlog': 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.  File: manual.info, Node: myisam-table-maintenance, Prev: point-in-time-recovery, Up: backup-and-recovery 7.6 `MyISAM' Table Maintenance and Crash Recovery ================================================= * Menu: * myisam-crash-recovery:: Using `myisamchk' for Crash Recovery * myisam-check:: How to Check `MyISAM' Tables for Errors * myisam-repair:: How to Repair `MyISAM' Tables * myisam-optimization:: `MyISAM' Table Optimization * myisam-maintenance-schedule:: Setting Up a `MyISAM' Table Maintenance Schedule This section discusses how to use *Note `myisamchk': myisamchk. to check or repair `MyISAM' tables (tables that have `.MYD' and `.MYI' files for storing data and indexes). For general *Note `myisamchk': myisamchk. background, see *Note myisamchk::. Other table-repair information can be found at *Note rebuilding-tables::. You can use *Note `myisamchk': 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 *Note `myisamchk': myisamchk. to get information about your tables, see *Note myisamchk-table-info::. Even though table repair with *Note `myisamchk': 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. *Note `myisamchk': myisamchk. operations that affect indexes can cause `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 *Note myisamchk-general-options::. `MyISAM' table maintenance can also be done using the SQL statements that perform operations similar to what *Note `myisamchk': myisamchk. can do: * To check `MyISAM' tables, use *Note `CHECK TABLE': check-table. * To repair `MyISAM' tables, use *Note `REPAIR TABLE': repair-table. * To optimize `MyISAM' tables, use *Note `OPTIMIZE TABLE': optimize-table. * To analyze `MyISAM' tables, use *Note `ANALYZE TABLE': analyze-table. For additional information about these statements, see *Note table-maintenance-sql::. These statements can be used directly or by means of the *Note `mysqlcheck': mysqlcheck. client program. One advantage of these statements over *Note `myisamchk': myisamchk. is that the server does all the work. With *Note `myisamchk': 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 *Note `myisamchk': myisamchk. and the server.  File: manual.info, Node: myisam-crash-recovery, Next: myisam-check, Prev: myisam-table-maintenance, Up: myisam-table-maintenance 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 *Note crashing::. For an explanation of how `MyISAM' tables can become corrupted, see *Note myisam-table-problems::. If you run *Note `mysqld': mysqld. with external locking disabled (which is the default), you cannot reliably use *Note `myisamchk': myisamchk. to check a table when *Note `mysqld': mysqld. is using the same table. If you can be certain that no one will access the tables through *Note `mysqld': mysqld. while you run *Note `myisamchk': myisamchk, you only have to execute *Note `mysqladmin flush-tables': mysqladmin. before you start checking the tables. If you cannot guarantee this, you must stop *Note `mysqld': mysqld. while you check the tables. If you run *Note `myisamchk': myisamchk. to check tables that *Note `mysqld': 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 *Note `myisamchk': myisamchk. to check tables at any time. In this case, if the server tries to update a table that *Note `myisamchk': myisamchk. is using, the server will wait for *Note `myisamchk': myisamchk. to finish before it continues. If you use *Note `myisamchk': myisamchk. to repair or optimize tables, you _must_ always ensure that the *Note `mysqld': mysqld. server is not using the table (this also applies if external locking is disabled). If you do not stop *Note `mysqld': mysqld, you should at least do a *Note `mysqladmin flush-tables': mysqladmin. before you run *Note `myisamchk': myisamchk. Your tables _may become corrupted_ if the server and *Note `myisamchk': 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. This table lists the three files in the database directory that correspond to each `MyISAM' 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. *Note `myisamchk': 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', *Note `myisamchk': 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 *Note `myisamchk': 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 *Note `myisamchk': myisamchk. In this case, *Note `myisamchk': 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 *Note `myisamchk': myisamchk.  File: manual.info, Node: myisam-check, Next: myisam-repair, Prev: myisam-crash-recovery, Up: myisam-table-maintenance 7.6.2 How to Check `MyISAM' Tables for Errors --------------------------------------------- To check a `MyISAM' table, use the following commands: * *Note `myisamchk TBL_NAME': myisamchk. 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 *Note `myisamchk': myisamchk. without options or with the `-s' (silent) option. * *Note `myisamchk -m TBL_NAME': myisamchk. 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. * *Note `myisamchk -e TBL_NAME': myisamchk. 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, *Note `myisamchk': myisamchk. stops after the first error it finds. If you want to obtain more information, you can add the `-v' (verbose) option. This causes *Note `myisamchk': myisamchk. to keep going, up through a maximum of 20 errors. * *Note `myisamchk -e -i TBL_NAME': myisamchk. This is like the previous command, but the `-i' option tells *Note `myisamchk': myisamchk. to print additional statistical information. In most cases, a simple *Note `myisamchk': myisamchk. command with no arguments other than the table name is sufficient to check a table.  File: manual.info, Node: myisam-repair, Next: myisam-optimization, Prev: myisam-check, Up: myisam-table-maintenance 7.6.3 How to Repair `MyISAM' Tables ----------------------------------- The discussion in this section describes how to use *Note `myisamchk': myisamchk. on `MyISAM' tables (extensions `.MYI' and `.MYD'). You can also use the *Note `CHECK TABLE': check-table. and *Note `REPAIR TABLE': repair-table. statements to check and repair `MyISAM' tables. See *Note check-table::, and *Note 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 *Note `perror': perror. NNN, where NNN is the error number. The following example shows how to use *Note `perror': 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 *Note `ALTER TABLE': 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 *Note `SHOW CREATE TABLE': show-create-table. For the other errors, you must repair your tables. *Note `myisamchk': 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 *Note `mysqld': 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 *Note myisam-check::), or you want to use the extended features that *Note `myisamchk': myisamchk. provides. The *Note `myisamchk': myisamchk. options used for table maintenance with are described in *Note myisamchk::. *Note `myisamchk': myisamchk. also has variables that you can set to control memory allocation that may improve performance. See *Note myisamchk-memory::. If you are going to repair a table from the command line, you must first stop the *Note `mysqld': mysqld. server. Note that when you do *Note `mysqladmin shutdown': mysqladmin. on a remote server, the *Note `mysqld': mysqld. server is still available for a while after *Note `mysqladmin': mysqladmin. returns, until all statement-processing has stopped and all index changes have been flushed to disk. *Stage 1: Checking your tables* Run *Note `myisamchk *.MYI': myisamchk. or *Note `myisamchk -e *.MYI': myisamchk. if you have more time. Use the `-s' (silent) option to suppress unnecessary information. If the *Note `mysqld': mysqld. server is stopped, you should use the `--update-state' option to tell *Note `myisamchk': myisamchk. to mark the table as `checked.' You have to repair only those tables for which *Note `myisamchk': 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 *Note `myisamchk': myisamchk. crashes, go to Stage 3. *Stage 2: Easy safe repair* First, try *Note `myisamchk -r -q TBL_NAME': myisamchk. (`-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 *Note `myisamchk -r TBL_NAME': myisamchk. (`-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 *Note `myisamchk --safe-recover TBL_NAME': myisamchk. 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 *Note `myisamchk': myisamchk. If you get unexpected errors when repairing (such as `out of memory' errors), or if *Note `myisamchk': 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. *Note `myisamchk -r -q': myisamchk. 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 *Note `REPAIR TABLE': repair-table. See *Note 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 *Note `myisamchk -r': myisamchk. 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.  File: manual.info, Node: myisam-optimization, Next: myisam-maintenance-schedule, Prev: myisam-repair, Up: myisam-table-maintenance 7.6.4 `MyISAM' Table Optimization --------------------------------- To coalesce fragmented rows and eliminate wasted space that results from deleting or updating rows, run *Note `myisamchk': myisamchk. in recovery mode: shell> myisamchk -r TBL_NAME You can optimize a table in the same way by using the *Note `OPTIMIZE TABLE': optimize-table. SQL statement. *Note `OPTIMIZE TABLE': 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 *Note `OPTIMIZE TABLE': optimize-table. See *Note optimize-table::. *Note `myisamchk': 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 *Note `SELECT': select. and `ORDER BY' operations that use this index. For a full description of all available options, see *Note myisamchk::.  File: manual.info, Node: myisam-maintenance-schedule, Prev: myisam-optimization, Up: myisam-table-maintenance 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 *Note `CHECK TABLE': check-table. and *Note `REPAIR TABLE': repair-table. statements. See *Note table-maintenance-sql::. Another way to check tables is to use *Note `myisamchk': myisamchk. For maintenance purposes, you can use *Note `myisamchk -s': myisamchk. The `-s' option (short for `--silent') causes *Note `myisamchk': 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' option. See *Note 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 *Note `myisamchk -s': myisamchk. 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 *Note `VARCHAR': char, *Note `BLOB': blob, or *Note `TEXT': blob. 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 *Note `OPTIMIZE TABLE': optimize-table. on the tables in question. Alternatively, if you can stop the *Note `mysqld': 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  File: manual.info, Node: optimization, Next: language-structure, Prev: backup-and-recovery, Up: Top 8 Optimization ************** * Menu: * optimize-overview:: Optimization Overview * execution-plan-information:: Obtaining Query Execution Plan Information * statement-optimization:: Optimizing SQL Statements * controlling-optimizer:: Controlling the Query Optimizer * optimization-indexes:: Optimization and Indexes * buffering-caching:: Buffering and Caching * locking-issues:: Locking Issues * optimizing-database-structure:: Optimizing Database Structure * optimizing-the-server:: Optimizing the MySQL Server * thread-information:: Examining Thread Information This chapter explains different ways to optimize MySQL and provides examples. Optimization is a complex task because ultimately it requires understanding of the entire system to be optimized. Although it may be possible to perform some local optimizations with little knowledge of your system or application, the more optimal you want your system to become, the more you must know about it.  File: manual.info, Node: optimize-overview, Next: execution-plan-information, Prev: optimization, Up: optimization 8.1 Optimization Overview ========================= * Menu: * design-limitations:: MySQL Design Limitations and Tradeoffs * portability:: Designing Applications for Portability * mysql-benchmarks:: The MySQL Benchmark Suite * custom-benchmarks:: Using Your Own Benchmarks The most important factor in making a system fast is its basic design. You must also know what kinds of processing your system is doing, and what its bottlenecks are. In most cases, system bottlenecks 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 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 we have the data in main memory, we need to process it to get our result. Having small 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.  File: manual.info, Node: design-limitations, Next: portability, Prev: optimize-overview, Up: optimize-overview 8.1.1 MySQL Design Limitations and Tradeoffs -------------------------------------------- When using the `MyISAM' storage engine, MySQL uses extremely fast table locking that permits multiple readers or a single writer. The biggest problem with this storage engine occurs when you have a steady stream of mixed updates and slow selects on a single table. If this is a problem for certain tables, you can use another storage engine for them. See *Note storage-engines::. MySQL can work with both transactional and nontransactional tables. To make it easier to work smoothly with nontransactional tables (which cannot roll back if something goes wrong), MySQL has the following rules. Note that these rules apply _only_ when not running in strict SQL mode or if you use the `IGNORE' specifier for *Note `INSERT': insert. or *Note `UPDATE': update. * All columns have default values. * If you insert an inappropriate or out-of-range value into a column, MySQL sets the column to the `best possible value' instead of reporting an error. For numeric values, this is 0, the smallest possible value or the largest possible value. For strings, this is either the empty string or as much of the string as can be stored in the column. * All calculated expressions return a value that can be used instead of signaling an error condition. For example, 1/0 returns `NULL'. To change the preceding behaviors, you can enable stricter data handling by setting the server SQL mode appropriately. For more information about data handling, see *Note constraints::, *Note server-sql-mode::, and *Note insert::.  File: manual.info, Node: portability, Next: mysql-benchmarks, Prev: design-limitations, Up: optimize-overview 8.1.2 Designing Applications for Portability -------------------------------------------- Because all SQL servers implement different parts of standard SQL, it takes work to write portable database applications. It is very easy to achieve portability for very simple selects and inserts, but becomes more difficult the more capabilities you require. If you want an application that is fast with many database systems, it becomes even more difficult. All database systems have some weak points. That is, they have different design compromises that lead to different behavior. To make a complex application portable, you need to determine which SQL servers it must work with, and then determine what features those servers support. You can use the MySQL `crash-me' program to find functions, types, and limits that you can use with a selection of database servers. `crash-me' does not check for every possible feature, but it is still reasonably comprehensive, performing about 450 tests. An example of the type of information `crash-me' can provide is that you should not use column names that are longer than 18 characters if you want to be able to use Informix or DB2. The `crash-me' program and the MySQL benchmarks are all very database independent. By taking a look at how they are written, you can get a feeling for what you must do to make your own applications database independent. The programs can be found in the `sql-bench' directory of MySQL source distributions. They are written in Perl and use the DBI database interface. Use of DBI in itself solves part of the portability problem because it provides database-independent access methods. See *Note mysql-benchmarks::. If you strive for database independence, you need to get a good feeling for each SQL server's bottlenecks. For example, MySQL is very fast in retrieving and updating rows for `MyISAM' tables, but has a problem in mixing slow readers and writers on the same table. Transactional database systems in general are not very good at generating summary tables from log tables, because in this case row locking is almost useless. To make your application _really_ database independent, you should define an easily extendable interface through which you manipulate your data. For example, C++ is available on most systems, so it makes sense to use a C++ class-based interface to the databases. If you use some feature that is specific to a given database system (such as the *Note `REPLACE': replace. statement, which is specific to MySQL), you should implement the same feature for other SQL servers by coding an alternative method. Although the alternative might be slower, it enables the other servers to perform the same tasks. With MySQL, you can use the `/*! */' syntax to add MySQL-specific keywords to a statement. The code inside `/* */' is treated as a comment (and ignored) by most other SQL servers. For information about writing comments, see *Note comments::. If high performance is more important than exactness, as for some Web applications, it is possible to create an application layer that caches all results to give you even higher performance. By letting old results expire after a while, you can keep the cache reasonably fresh. This provides a method to handle high load spikes, in which case you can dynamically increase the cache size and set the expiration timeout higher until things get back to normal. In this case, the table creation information should contain information about the initial cache size and how often the table should normally be refreshed. An attractive alternative to implementing an application cache is to use the MySQL query cache. By enabling the query cache, the server handles the details of determining whether a query result can be reused. This simplifies your application. See *Note query-cache::.  File: manual.info, Node: mysql-benchmarks, Next: custom-benchmarks, Prev: portability, Up: optimize-overview 8.1.3 The MySQL Benchmark Suite ------------------------------- This benchmark suite is meant to tell any user what operations a given SQL implementation performs well or poorly. You can get a good idea for how the benchmarks work by looking at the code and results in the `sql-bench' directory in any MySQL source distribution. Note that this benchmark is single-threaded, so it measures the minimum time for the operations performed. We plan to add multi-threaded tests to the benchmark suite in the future. To use the benchmark suite, the following requirements must be satisfied: * The benchmark suite is provided with MySQL source distributions. You can either download a released distribution from `http://dev.mysql.com/downloads/', or use the current development source tree. (See *Note installing-development-tree::.) * The benchmark scripts are written in Perl and use the Perl DBI module to access database servers, so DBI must be installed. You also need the server-specific DBD drivers for each of the servers you want to test. For example, to test MySQL, PostgreSQL, and DB2, you must have the `DBD::mysql', `DBD::Pg', and `DBD::DB2' modules installed. See *Note perl-support::. After you obtain a MySQL source distribution, you can find the benchmark suite located in its `sql-bench' directory. To run the benchmark tests, build MySQL, and then change location into the `sql-bench' directory and execute the `run-all-tests' script: shell> cd sql-bench shell> perl run-all-tests --server=SERVER_NAME SERVER_NAME should be the name of one of the supported servers. To get a list of all options and supported servers, invoke this command: shell> perl run-all-tests --help The `crash-me' script also is located in the `sql-bench' directory. `crash-me' tries to determine what features a database system supports and what its capabilities and limitations are by actually running queries. For example, it determines: * What data types are supported * How many indexes are supported * What functions are supported * How big a query can be * How big a *Note `VARCHAR': char. column can be For more information about benchmark results, visit http://www.mysql.com/why-mysql/benchmarks/.  File: manual.info, Node: custom-benchmarks, Prev: mysql-benchmarks, Up: optimize-overview 8.1.4 Using Your Own Benchmarks ------------------------------- You should definitely 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. For examples of portable benchmark programs, look at those in the MySQL benchmark suite. See *Note mysql-benchmarks::. You can take any program from this suite and modify it for your own needs. By doing this, you can try different solutions to your problem and test which really is fastest for you. Another 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, you should put some effort into benchmarking your whole application under the worst possible load: * The *Note `mysqlslap': mysqlslap. program can be helpful for simulating a high load produced by multiple clients issuing queries simultaneously. See *Note mysqlslap::. * You can also try benchmarking packages such as SysBench and DBT2, available at `http://sourceforge.net/projects/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.  File: manual.info, Node: execution-plan-information, Next: statement-optimization, Prev: optimize-overview, Up: optimization 8.2 Obtaining Query Execution Plan Information ============================================== * Menu: * using-explain:: Optimizing Queries with `EXPLAIN' * explain-output:: `EXPLAIN' Output Format * explain-extended:: `EXPLAIN EXTENDED' Output Format * estimating-performance:: Estimating Query Performance  File: manual.info, Node: using-explain, Next: explain-output, Prev: execution-plan-information, Up: execution-plan-information 8.2.1 Optimizing Queries with `EXPLAIN' --------------------------------------- The *Note `EXPLAIN': explain. statement can be used to obtain information about how MySQL executes a statement: * When you precede a *Note `SELECT': select. statement with the keyword *Note `EXPLAIN': explain, 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 *Note `EXPLAIN': explain. to obtain execution plan information, see *Note explain-output::. * *Note `EXPLAIN EXTENDED': explain-extended. can be used to obtain additional execution plan information. See *Note explain-extended::. * As of MySQL 5.1.5, *Note `EXPLAIN PARTITIONS': explain. is useful for examining queries involving partitioned tables. See *Note partitioning-info::. With the help of *Note `EXPLAIN': 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 *Note `EXPLAIN': 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 *Note `SELECT': select. statement, begin the statement with `SELECT STRAIGHT_JOIN' rather than just *Note `SELECT': select. (See *Note select::.) If you have a problem with indexes not being used when you believe that they should be, run *Note `ANALYZE TABLE': analyze-table. to update table statistics, such as cardinality of keys, that can affect the choices the optimizer makes. See *Note analyze-table::. *Note*: *Note `EXPLAIN': explain. can also be used to obtain information about the columns in a table. *Note `EXPLAIN TBL_NAME': explain. is synonymous with `DESCRIBE TBL_NAME' and `SHOW COLUMNS FROM TBL_NAME'. For more information, see *Note describe::, and *Note show-columns::.  File: manual.info, Node: explain-output, Next: explain-extended, Prev: using-explain, Up: execution-plan-information 8.2.2 `EXPLAIN' Output Format ----------------------------- The *Note `EXPLAIN': explain. statement provides information about the execution plan for a *Note `SELECT': select. statement. *Note `EXPLAIN': explain. returns a row of information for each table used in the *Note `SELECT': 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. When the `EXTENDED' keyword is used, *Note `EXPLAIN': explain. produces extra information that can be viewed by issuing a *Note `SHOW WARNINGS': show-warnings. statement following the *Note `EXPLAIN': explain. statement. *Note `EXPLAIN EXTENDED': explain-extended. also displays the `filtered' column as of MySQL 5.1.12. See *Note explain-extended::. *Note*: You cannot use the `EXTENDED' and `PARTITIONS' keywords together in the same *Note `EXPLAIN': explain. statement. * `EXPLAIN' Output Columns * `EXPLAIN' Join Types * `EXPLAIN' Extra Information * `EXPLAIN' Output Interpretation * `EXPLAIN' Output Columns * This section describes the output columns produced by *Note `EXPLAIN': explain. Later sections provide additional information about the `type' and `Extra' columns. Each output row from *Note `EXPLAIN': explain. provides information about one table. Each row contains the values summarized in *Note explain-output-column-table::, and described in more detail following the table. *`EXPLAIN' Output Columns* Column Meaning `id' The `SELECT' identifier `select_type' The `SELECT' type `table' The table for the output row `partitions' The matching partitions `type' The join type `possible_keys' The possible indexes to choose `key' The index actually chosen `key_len' The length of the chosen key `ref' The columns compared to the index `rows' Estimate of rows to be examined `filtered' Percentage of rows filtered by table condition `Extra' Additional information * `id' The *Note `SELECT': select. identifier. This is the sequential number of the *Note `SELECT': 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 `' to indicate that the row refers to the union of the rows with `id' values of M and N. * `select_type' The type of *Note `SELECT': select, which can be any of those shown in the following table. This table lists `select_type' values and describes the meaning of each. `select_type' Meaning Value `SIMPLE' Simple *Note `SELECT': select. (not using *Note `UNION': union. or subqueries) `PRIMARY' Outermost *Note `SELECT': select. *Note `UNION': Second or later *Note `SELECT': select. statement union. in a *Note `UNION': union. `DEPENDENT UNION' Second or later *Note `SELECT': select. statement in a *Note `UNION': union, dependent on outer query `UNION RESULT' Result of a *Note `UNION': union. `SUBQUERY' First *Note `SELECT': select. in subquery `DEPENDENT First *Note `SELECT': select. in subquery, SUBQUERY' dependent on outer query `DERIVED' Derived table *Note `SELECT': select. (subquery in `FROM' clause) `UNCACHEABLE A subquery for which the result cannot be cached SUBQUERY' and must be re-evaluated for each row of the outer query `UNCACHEABLE The second or later select in a *Note `UNION': UNION' union. that belongs to an uncacheable subquery (see `UNCACHEABLE SUBQUERY') `DEPENDENT' typically signifies the use of a correlated subquery. See *Note 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 *Note query-cache-operation::). Subquery caching occurs during query execution, whereas the query cache is used to store results only after query execution finishes. * `table' The name of the table to which the row of output refers. This can also be one of the following values: * `': The row refers to the union of the rows with `id' values of M and N. * `': 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. * `partitions' The partitions from which records would be matched by the query. This column is displayed only if the `PARTITIONS' keyword is used. The value is `NULL' for nonpartitioned tables. See *Note partitioning-info::. * `type' The join type. For descriptions of the different types, see `EXPLAIN' Join Types. * `possible_keys' The `possible_keys' column indicates which indexes MySQL can choose from use 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 *Note `EXPLAIN': 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', 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 *Note `EXPLAIN': explain. again. See *Note alter-table::. To see what indexes a table has, use `SHOW INDEX FROM TBL_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 *Note index-hints::. For `MyISAM' and `NDB' tables, running *Note `ANALYZE TABLE': analyze-table. helps the optimizer choose better indexes. For `MyISAM' tables, *Note `myisamchk --analyze': myisamchk. does the same as *Note `ANALYZE TABLE': analyze-table. See *Note myisam-table-maintenance::. * `key_len' The `key_len' column indicates the length of the key that MySQL decided to use. The length is `NULL' if the `key' column says `NULL'. Note that the value of `key_len' enables you to determine how many parts of a multiple-part key MySQL actually uses. * `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. * `rows' The `rows' column indicates the number of rows MySQL believes it must examine to execute the query. For *Note `InnoDB': innodb-storage-engine. tables, this number is an estimate, and may not always be exact. * `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. This column is displayed if you use *Note `EXPLAIN EXTENDED': explain-extended. (New in MySQL 5.1.12) * `Extra' This column contains additional information about how MySQL resolves the query. For descriptions of the different values, see `EXPLAIN' Extra Information. * `EXPLAIN' Join Types * The `type' column of *Note `EXPLAIN': explain. output describes how tables are joined. 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 *Note 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 *Note index-merge-optimization::. * `unique_subquery' This type replaces `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 *Note `EXPLAIN': explain. output contains additional information about how MySQL resolves the query. The following list explains the values that can appear in this column. If you want to make your queries as fast as possible, look out for `Extra' values of `Using filesort' and `Using temporary'. * `Child of 'TABLE' pushed join@1' This table is referenced as the child of TABLE in a join that can be pushed down to the NDB kernel. Applies only in MySQL Cluster NDB 7.2.0 and later, 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' For a query such as `SELECT ... FROM TBL_NAME', the table was empty. * `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. * `Full scan on NULL key' This occurs for subquery optimization as a fallback strategy when the optimizer cannot use an index-lookup access method. * `Impossible HAVING' The `HAVING' clause is always false and cannot select any rows. * `Impossible WHERE' The `WHERE' clause is always false and cannot select any rows. * `Impossible WHERE noticed after reading const tables' MySQL has read all `const' (and `system') tables and notice that the `WHERE' clause is always false. * `No matching min/max row' No row satisfies the condition for a query such as `SELECT MIN(...) FROM ... WHERE CONDITION'. * `no matching row in const table' For a query with a join, there was an empty table or a table with no rows satisfying a unique index condition. * `No tables used' The query has no `FROM' clause, or has a `FROM DUAL' clause. * `Not exists' 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'. * `Parent of N pushed join@1' This table is referenced as the parent of the table in row N of the current *Note `EXPLAIN': explain. output in a join that can be pushed down to the NDB kernel. Applies only in MySQL Cluster NDB 7.2.0 and later when pushed-down joins are enabled. See the description of the `ndb_join_pushdown' server system variable for more information and examples. * `Range checked for each record (index map: N)' 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 *Note range-optimization::, and *Note 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 *Note `SHOW INDEX': 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' This indicates how many directory scans the server performs when processing a query for `INFORMATION_SCHEMA' tables, as described in *Note information-schema-optimization::. The value of N can be 0, 1, or `all'. * `Select tables optimized away' The query contained only aggregate functions (`MIN()', `MAX()') that were all resolved using an index, or `COUNT(*)' for `MyISAM', and no `GROUP BY' clause. The optimizer determined that only one row should be returned. * `Skip_open_table', `Open_frm_only', `Open_trigger_only', `Open_full_table' These values indicate file-opening optimizations that apply to queries for `INFORMATION_SCHEMA' tables, as described in *Note 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_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. * `unique row not found' 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' 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 *Note order-by-optimization::. * `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. If the `Extra' column also says `Using where', it means the index is being used to perform lookups of key values. Without `Using where', the optimizer may be reading the index to avoid reading data rows but not using it for lookups. For example, if the index is a covering index for the query, the optimizer may scan it without using it for lookups. 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 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 *Note group-by-optimization::. * `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. * `Using sort_union(...)', `Using union(...)', `Using intersect(...)' These indicate how index scans are merged for the `index_merge' join type. See *Note index-merge-optimization::. * `Using temporary' 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' 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'. Even if you are using an index for all parts of a `WHERE' clause, you may see `Using where' if the column can be `NULL'. * `Using where with pushed condition' This item applies to *Note `NDBCLUSTER': mysql-cluster. tables _only_. It means that MySQL 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 *Note condition-pushdown-optimization::. * `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 *Note `EXPLAIN': 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 *Note `SELECT': select. statements to execute and which to abort. See *Note server-parameters::. The following example shows how a multiple-table join can be optimized progressively based on the information provided by *Note `EXPLAIN': explain. Suppose that you have the *Note `SELECT': select. statement shown here and that you plan to examine it using *Note `EXPLAIN': 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. This table outlines table names, column names, and data types for the columns being compared in the `EXPLAIN' example described in the preceding text. 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. This table lists indexes for each of the tables that are part of the `EXPLAIN' example described in the preceding text. 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 *Note `EXPLAIN': 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, *Note `VARCHAR': char. and *Note `CHAR': 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 *Note `ALTER TABLE': 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 *Note `EXPLAIN': 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, *Note `EXPLAIN': 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 *Note `EXPLAIN': 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 Note that the `rows' column in the output from *Note `EXPLAIN': explain. is an educated guess from the MySQL join optimizer. You should 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 *Note `SELECT': select. statement and trying to list the tables in a different order in the `FROM' clause. It is possible in some cases to execute statements that modify data when *Note `EXPLAIN SELECT': explain. is used with a subquery; for more information, see *Note from-clause-subqueries::.  File: manual.info, Node: explain-extended, Next: estimating-performance, Prev: explain-output, Up: execution-plan-information 8.2.3 `EXPLAIN EXTENDED' Output Format -------------------------------------- When *Note `EXPLAIN': explain. is used with the `EXTENDED' keyword, the output includes a `filtered' column not otherwise displayed. This column indicates the estimated percentage of table rows that will be filtered by the table condition. In addition, the statement produces extra information that can be viewed by issuing a *Note `SHOW WARNINGS': show-warnings. statement following the *Note `EXPLAIN': explain. statement. The `Message' value in *Note `SHOW WARNINGS': show-warnings. output displays how the optimizer qualifies table and column names in the *Note `SELECT': select. statement, what the *Note `SELECT': select. looks like after the application of rewriting and optimization rules, and possibly other notes about the optimization process. Here is an example: mysql> EXPLAIN EXTENDED -> 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: DEPENDENT SUBQUERY table: t2 type: index_subquery possible_keys: a key: a key_len: 5 ref: func rows: 2 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 `test`.`t1`.`a` AS `a`, (`test`.`t1`.`a`, (((`test`.`t1`.`a`) in t2 on a checking NULL having (`test`.`t2`.`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 *Note `SHOW WARNINGS': 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 `EXTENDED' output displayed by *Note `SHOW WARNINGS': show-warnings.: * `(EXPR)' The expression (such as a scalar subquery) is executed once and the resulting value is saved in memory for later use. * `(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. * `(QUERY FRAGMENT)' This is an internal optimizer object with no user significance. * `(QUERY FRAGMENT)' The query fragment is processed using an index lookup to find qualifying rows. * `(EXPR)' A test to verify that the expression does not evaluate to `NULL'. * `(QUERY FRAGMENT)' The query fragment is processed using a primary key lookup to find qualifying rows. * `(EXPR)' This is an internal optimizer object with no user significance.  File: manual.info, Node: estimating-performance, Prev: explain-extended, Up: execution-plan-information 8.2.4 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 *Note `MEDIUMINT': integer-types.), 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. Note that 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 *Note server-parameters::.  File: manual.info, Node: statement-optimization, Next: controlling-optimizer, Prev: execution-plan-information, Up: optimization 8.3 Optimizing SQL Statements ============================= * Menu: * select-optimization:: Optimizing `SELECT' Statements * non-select-optimization:: Optimizing Non-`SELECT' Statements * information-schema-optimization:: `INFORMATION_SCHEMA' Optimization * miscellaneous-optimization-tips:: Other Optimization Tips  File: manual.info, Node: select-optimization, Next: non-select-optimization, Prev: statement-optimization, Up: statement-optimization 8.3.1 Optimizing `SELECT' Statements ------------------------------------ * Menu: * select-speed:: Speed of `SELECT' Statements * where-optimizations:: How MySQL Optimizes `WHERE' Clauses * range-optimization:: Range Optimization * index-merge-optimization:: Index Merge Optimization * condition-pushdown-optimization:: Engine Condition Pushdown Optimization * is-null-optimization:: `IS NULL' Optimization * left-join-optimization:: `LEFT JOIN' and `RIGHT JOIN' Optimization * nested-loop-joins:: Nested-Loop Join Algorithms * nested-join-optimization:: Nested Join Optimization * outer-join-simplification:: Outer Join Simplification * order-by-optimization:: `ORDER BY' Optimization * group-by-optimization:: `GROUP BY' Optimization * distinct-optimization:: `DISTINCT' Optimization * subquery-optimization-with-exists:: Optimizing Subqueries with `EXISTS' Strategy * limit-optimization:: Optimizing `LIMIT' Queries * how-to-avoid-table-scan:: How to Avoid Table Scans First, one factor affects all statements: The more complex your permissions setup, the more overhead you have. Using simpler permissions when you issue *Note `GRANT': 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, it may be worth the time to use a simplified grant structure to reduce permission-checking overhead. If your problem is with a specific MySQL expression or function, you can perform a timing test by invoking the `BENCHMARK()' function using the *Note `mysql': mysql. client program. Its syntax is `BENCHMARK(LOOP_COUNT,EXPRESSION)'. The return value is always zero, but *Note `mysql': 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. All MySQL functions should be 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.  File: manual.info, Node: select-speed, Next: where-optimizations, Prev: select-optimization, Up: select-optimization 8.3.1.1 Speed of `SELECT' Statements .................................... In general, when you want to make a slow `SELECT ... WHERE' query faster, the first thing to check is whether you can add an index. All references between different tables should usually be done with indexes. You can use the *Note `EXPLAIN': explain. statement to determine which indexes are used for a *Note `SELECT': select. See *Note using-explain::, and *Note mysql-indexes::. Some general tips for speeding up queries on `MyISAM' tables: * To help MySQL better optimize queries, use *Note `ANALYZE TABLE': analyze-table. or run *Note `myisamchk --analyze': myisamchk. 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. *Note `myisamchk --description --verbose': myisamchk. shows index distribution information. * To sort an index and data according to an index, use *Note `myisamchk --sort-index --sort-records=1': myisamchk. (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.  File: manual.info, Node: where-optimizations, Next: range-optimization, Prev: select-speed, Up: select-optimization 8.3.1.2 How MySQL Optimizes `WHERE' Clauses ........................................... This section discusses optimizations that can be made for processing `WHERE' clauses. The examples use *Note `SELECT': select. statements, but the same optimizations apply for `WHERE' clauses in *Note `DELETE': delete. and *Note `UPDATE': update. statements. Work on the MySQL optimizer is ongoing, so this section is incomplete. MySQL performs a great many optimizations, not all of which are documented here. 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>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 *Note `SELECT': 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' option, 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, ... ;  File: manual.info, Node: range-optimization, Next: index-merge-optimization, Prev: where-optimizations, Up: select-optimization 8.3.1.3 Range Optimization .......................... * Menu: * range-access-single-part:: The Range Access Method for Single-Part Indexes * range-access-multi-part:: The Range Access Method for Multiple-Part Indexes 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 a detailed description of how intervals are extracted from the `WHERE' clause.  File: manual.info, Node: range-access-single-part, Next: range-access-multi-part, Prev: range-optimization, Up: range-optimization 8.3.1.4 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, so we speak of _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 types of indexes, 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'; Note that some nonconstant values may be converted to constants during the 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. Having replaced them with `TRUE', we get: (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, we get: (key1 < 'abc' AND TRUE) OR (key1 < 'bar' AND TRUE) OR (FALSE) Removing unnecessary `TRUE' and `FALSE' constants, we obtain: (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. Currently, MySQL does not support merging multiple ranges for the `range' access method for spatial indexes. To work around this limitation, you can use a *Note `UNION': union. with identical *Note `SELECT': select. statements, except that you put each spatial predicate in a different *Note `SELECT': select.  File: manual.info, Node: range-access-multi-part, Prev: range-access-single-part, Up: range-optimization 8.3.1.5 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 *Note 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 *Note `EXPLAIN': 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 *Note 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.  File: manual.info, Node: index-merge-optimization, Next: condition-pushdown-optimization, Prev: range-optimization, Up: select-optimization 8.3.1.6 Index Merge Optimization ................................ * Menu: * index-merge-intersection:: The Index Merge Intersection Access Algorithm * index-merge-union:: The Index Merge Union Access Algorithm * index-merge-sort-union:: The Index Merge Sort-Union Access Algorithm The _Index Merge_ method is used to retrieve rows with several `range' scans and to merge their results into one. The merge can produce unions, intersections, or unions-of-intersections of its underlying scans. This access method merges index scans from a single table; it does not merge scans across multiple tables. In *Note `EXPLAIN': 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. Examples: 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); The Index Merge method has several access algorithms (seen in the `Extra' field of *Note `EXPLAIN': explain. output): * `Using intersect(...)' * `Using union(...)' * `Using sort_union(...)' The following sections describe these methods in greater detail. *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 doesn't choose the optimal plan, try distributing terms using the following identity laws: (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. We plan to extend it to cover these in a future MySQL release. * If a range scan is possible on some key, the optimizer will not consider using Index Merge Union or Index Merge Sort-Union algorithms. For example, consider this query: SELECT * FROM t1 WHERE (goodkey1 < 10 OR goodkey2 < 20) AND badkey < 30; For this query, two plans are possible: * An Index Merge scan using the `(goodkey1 < 10 OR goodkey2 < 20)' condition. * A range scan using the `badkey < 30' condition. However, the optimizer considers only the second plan. The choice between different possible variants of the Index Merge access method and other access methods is based on cost estimates of various available options.  File: manual.info, Node: index-merge-intersection, Next: index-merge-union, Prev: index-merge-optimization, Up: index-merge-optimization 8.3.1.7 The Index Merge Intersection Access Algorithm ..................................................... This access algorithm can be employed when a `WHERE' clause was converted to several range conditions on different keys combined with `AND', and each condition is one of the following: * In 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 (*Note `EXPLAIN': 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 don't 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.  File: manual.info, Node: index-merge-union, Next: index-merge-sort-union, Prev: index-merge-intersection, Up: index-merge-optimization 8.3.1.8 The Index Merge Union Access Algorithm .............................................. The applicability criteria for this algorithm are similar to those for the Index Merge method intersection algorithm. The algorithm can be employed when the table's `WHERE' clause was converted to several range conditions on different keys combined with `OR', and each condition is one of the following: * In 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 method 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;  File: manual.info, Node: index-merge-sort-union, Prev: index-merge-union, Up: index-merge-optimization 8.3.1.9 The Index Merge Sort-Union Access Algorithm ................................................... This access algorithm is employed when the `WHERE' clause was converted to several range conditions combined by `OR', but for which the Index Merge method 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.  File: manual.info, Node: condition-pushdown-optimization, Next: is-null-optimization, Prev: index-merge-optimization, Up: select-optimization 8.3.1.10 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 *Note `NDBCLUSTER': mysql-cluster. storage engine. For MySQL 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 a MySQL Cluster table is defined as follows: CREATE TABLE t1 ( a INT, b INT, KEY(a) ) ENGINE=NDBCLUSTER; 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 *Note `EXPLAIN': 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 *Note 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 `engine_condition_pushdown' system variable. For example, in a `my.cnf' file, use these lines: [mysqld] engine_condition_pushdown=0 At runtime, disable condition pushdown with either of the following statements: SET engine_condition_pushdown=OFF; SET engine_condition_pushdown=0; Limitations Engine condition pushdown is subject to the following limitations: * Condition pushdown is supported only by the *Note `NDBCLUSTER': mysql-cluster. 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 *Note `BLOB': blob. or *Note `TEXT': blob. 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 *Note `EXPLAIN EXTENDED': explain-extended. to determine which conditions are actually pushed down.  File: manual.info, Node: is-null-optimization, Next: left-join-optimization, Prev: condition-pushdown-optimization, Up: select-optimization 8.3.1.11 `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. *Note `EXPLAIN': 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. Note that 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);  File: manual.info, Node: left-join-optimization, Next: nested-loop-joins, Prev: is-null-optimization, Up: select-optimization 8.3.1.12 `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 dependence, MySQL issues an error. * 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 implementation of `RIGHT JOIN' is analogous to that of `LEFT JOIN' with the roles of the tables reversed. The join optimizer calculates the order in which tables should be joined. 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. Note that this means that if you do 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; This can be made faster because MySQL 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 *Note select::.)  File: manual.info, Node: nested-loop-joins, Next: nested-join-optimization, Prev: left-join-optimization, Up: select-optimization 8.3.1.13 Nested-Loop Join Algorithms .................................... MySQL executes joins between tables using a nested-loop algorithm or variations on it. *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. The reduces the number of times the inner table must be read by an order of magnitude. MySQL uses join buffering under these conditions: * The `join_buffer_size' system variable determines the size of each join buffer. * 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'. * 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 never allocated for the first nonconst table, even if it would be of type `ALL' or `index'. * A join buffer is allocated prior to executing the join and freed after the query is done. * Only columns of interest to the join are stored in the join buffer, not whole rows. For the example join described previously for the NLJ algorithm (without buffering), the join is done as follow 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 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, there is no speed to be gained by making it larger.  File: manual.info, Node: nested-join-optimization, Next: outer-join-simplification, Prev: nested-loop-joins, Up: select-optimization 8.3.1.14 Nested Join Optimization ................................. The syntax for expressing joins permits nested joins. The following discussion refers to the join syntax described in *Note 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 a syntactic 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. After removing parentheses and grouping operations to the left, the join expression: t1 LEFT JOIN (t2 LEFT JOIN t3 ON t2.b=t3.b OR t2.b IS NULL) ON t1.a=t2.a transforms into the 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: t1, t2 LEFT JOIN t3 ON P(t2.b,t3.b) for any tables `t1,t2,t3' and any condition `P' over attributes `t2.b' and `t3.b'. Whenever the order of execution of the 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 The nested join is formed in the first query with a left join operation, whereas 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' would 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. You can remove parentheses and evaluate left to right (or, in fact, you can evaluate the tables 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 by what algorithmic schema the nested-loop join executes a query. Suppose that we have a join query over 3 tables `T1,T2,T3' of the 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' means `a row constructed by concatenating the columns of rows `t1', `t2', and `t3'.' In some of the following examples, `NULL' where a row name appears means that `NULL' is used for each column of that row. For example, `t1||t2||NULL' means `a row constructed by concatenating the columns of rows `t1' and `t2', and `NULL' for each column of `t3'.' Now let's 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, we modify the nested-loop pattern to get: 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 our example, the outer join table expressed by the following expression is embedded: (T2 LEFT JOIN T3 ON P2(T2,T3)) Note that 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 the 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 will evaluate two different nestings: SELECT * T1 LEFT JOIN (T2,T3) ON P1(T1,T2) AND P2(T1,T3) WHERE P(T1,T2,T3) The nestings are these: 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; } } } and: 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; } } } 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. 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 schema 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 have to introduce conditional pushed-down predicates guarded by the flags that are turned on when a match has been encountered. For our example with outer joins with: P(T1,T2,T3)=C1(T1) AND C(T2) AND C3(T3) the nested-loop schema 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. Note that 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. (We could use conditional key access in this case, but this technique is not employed yet in MySQL 5.1.)  File: manual.info, Node: outer-join-simplification, Next: order-by-optimization, Prev: nested-join-optimization, Up: select-optimization 8.3.1.15 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 joins operations are converted to equivalent queries containing only left join operations. In the general case, the conversion is performed according to the following rule: (T1, ...) RIGHT JOIN (T2,...) ON P(T1,...,T2,...) = (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 join queries with outer join operation, it takes into consideration only the plans where, for each such operation, the outer tables are accessed before the inner tables. The optimizer options are limited because only such plans enables us to execute queries with outer joins operations by the nested loop schema. Suppose that we have a query of the form: SELECT * T1 LEFT JOIN T2 ON P1(T1,T2) WHERE P(T1,T2) AND R(T2) with `R(T2)' narrowing greatly the number of matching rows from table `T2'. If we executed the query as it is, the optimizer would have no other choice besides to access table `T1' before table `T2' that may lead to a very inefficient execution plan. Fortunately, MySQL converts such a query into a query without an outer join operation if the `WHERE' condition is null-rejected. A condition is called null-rejected for an outer join operation if it evaluates to `FALSE' or to `UNKNOWN' for any `NULL'-complemented row built for the operation. Thus, for this outer join: T1 LEFT JOIN T2 ON T1.A=T2.A Conditions such as these are null-rejected: 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: 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. A condition is null-rejected in the following cases: * If it is of the form `A IS NOT NULL', where `A' is an attribute of any of the inner tables * If it is a predicate containing a reference to an inner table that evaluates to `UNKNOWN' when one of its arguments is `NULL' * If it is a conjunction containing a null-rejected condition as a conjunct * If 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 the query: SELECT * FROM T1 LEFT JOIN T2 ON T2.A=T1.A LEFT JOIN T3 ON T3.B=T1.B WHERE T3.C > 0 the `WHERE' condition is null-rejected for the second outer join operation but is not null-rejected for the first one. 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, the preceding query is replaced with the query: 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 would evaluate plans compatible with only one access order `T1,T2,T3'. For the replacing query, it additionally considers the access sequence `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 will be 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 Now the remaining outer join operation can be replaced by an inner join, too, because the condition `T3.B=T2.B' is null-rejected and we get a query without 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 we succeed 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. When trying to convert an embedded outer join operation in a query, we must take into account the join condition for the embedding outer join together with the `WHERE' condition. In the query: 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 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. So 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  File: manual.info, Node: order-by-optimization, Next: group-by-optimization, Prev: outer-join-simplification, Up: select-optimization 8.3.1.16 `ORDER BY' Optimization ................................ In some cases, MySQL can use an index to satisfy an `ORDER BY' clause without doing any extra sorting. The index can also be used even if the `ORDER BY' does not match the index exactly, as long as all of the unused portions of the index and all the 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 still uses indexes to find the rows that match the `WHERE' clause. These cases include the following: * You use `ORDER BY' on different keys: SELECT * FROM t1 ORDER BY KEY1, KEY2; * You use `ORDER BY' on nonconsecutive parts of a key: SELECT * FROM t1 WHERE KEY2=CONSTANT ORDER BY KEY_PART2; * You mix `ASC' and `DESC': SELECT * FROM t1 ORDER BY KEY_PART1 DESC, KEY_PART2 ASC; * The key used to fetch the rows is not the same as the one used in the `ORDER BY': SELECT * FROM t1 WHERE KEY2=CONSTANT ORDER BY KEY1; * You use `ORDER BY' with an expression that includes terms other than the key column name: SELECT * FROM t1 ORDER BY ABS(KEY); SELECT * FROM t1 ORDER BY -KEY; * You are joining 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 *Note `EXPLAIN': explain. output that does not have a `const' join type.) * You have different `ORDER BY' and `GROUP BY' expressions. * You index 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 you have a *Note `CHAR(20)': char. column, but index only the first 10 bytes, the index cannot distinguish values past the 10th byte and a `filesort' will be needed. * The type of table index used 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', so for the reference to `a' in the `ORDER BY', the index 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)', so for the reference to `a' in the `ORDER BY', the index 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' uses that, and the index 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 `ORDER BY' clause explicitly 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; With *Note `EXPLAIN SELECT ... ORDER BY': explain, you can check whether MySQL can use indexes to resolve the query. It cannot if you see `Using filesort' in the `Extra' column. See *Note using-explain::. Filesort uses a fixed-length row-storage format similar to that used by the *Note `MEMORY': memory-storage-engine. storage engine. Variable-length types such as *Note `VARCHAR': char. are stored using a fixed length. MySQL has two `filesort' algorithms for sorting and retrieving results. The original method uses only the `ORDER BY' columns. The modified method uses not just the `ORDER BY' columns, but all the columns used in the query. The optimizer selects which `filesort' algorithm to use. It normally uses the modified algorithm except when *Note `BLOB': blob. or *Note `TEXT': blob. columns are involved, in which case it uses the original algorithm. The original `filesort' algorithm works as follows: 1. Read all rows according to key or by table scanning. Rows that do not match the `WHERE' clause are skipped. 2. For each row, store a pair of values in a buffer (the sort key and the row pointer). The size of the buffer is the value of the `sort_buffer_size' system variable. 3. When the buffer gets full, run a qsort (quicksort) on it and store the result in a temporary file. Save a pointer to the sorted block. (If all pairs fit into the sort buffer, no temporary file is created.) 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 pointer to the row (the last part of the sort key) is written to a result file. 8. Read the rows in sorted order by using the row pointers in the result file. To optimize this, we read in a big block of row pointers, sort them, and use them to read the rows in sorted order into a row buffer. The size of the buffer is the value of the `read_rnd_buffer_size' system variable. The code for this step is in the `sql/records.cc' source file. One problem with this approach is that it reads rows twice: One time when evaluating the `WHERE' clause, and again after sorting the pair values. 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 incorporates an optimization such that it records not only the sort key value and row position, but also the columns required for the query. This avoids reading the rows twice. The modified `filesort' algorithm works like this: 1. Read the rows that match the `WHERE' clause. 2. For each row, record a tuple of values consisting of the sort key value and row position, and also the columns required for the query. 3. Sort the tuples by sort key value 4. Retrieve the rows in sorted order, but read the required columns directly from the sorted tuples rather than by accessing the table a second time. Using the modified `filesort' algorithm, the tuples are longer than the pairs used in the original method, and fewer of them fit in the sort buffer (the size of which is given by `sort_buffer_size'). As a result, it is possible for the extra I/O to make the modified approach slower, not faster. To avoid a slowdown, the optimization is used 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 that you should see high disk activity and low CPU activity.) For slow queries for which `filesort' is not used, you might try lowering `max_length_for_sort_data' to a value that is appropriate to trigger a `filesort'. If you want 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 size of the `sort_buffer_size' variable. * Increase the size of the `read_rnd_buffer_size' variable. * 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 `tmpdir' to point to a dedicated file system with large amounts of free space. Also, this option accepts several paths that are used in round-robin fashion, so you can use this feature to spread the load across several directories. Paths should be separated by colon characters (``:'') on Unix and semicolon characters (``;'') on Windows, NetWare, and OS/2. The paths should be for directories in file systems that are located on different _physical_ disks, not different partitions on the same disk.  File: manual.info, Node: group-by-optimization, Next: distinct-optimization, Prev: order-by-optimization, Up: select-optimization 8.3.1.17 `GROUP BY' Optimization ................................ * Menu: * loose-index-scan:: Loose Index Scan * tight-index-scan:: Tight Index Scan 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. See *Note order-by-optimization::.  File: manual.info, Node: loose-index-scan, Next: tight-index-scan, Prev: group-by-optimization, Up: group-by-optimization 8.3.1.18 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 *Note 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 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 *Note `EXPLAIN': 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.  File: manual.info, Node: tight-index-scan, Prev: loose-index-scan, Up: group-by-optimization 8.3.1.19 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;  File: manual.info, Node: distinct-optimization, Next: subquery-optimization-with-exists, Prev: group-by-optimization, Up: select-optimization 8.3.1.20 `DISTINCT' Optimization ................................ `DISTINCT' combined with `ORDER BY' needs a temporary table in many cases. Because `DISTINCT' may use `GROUP BY', you should be aware of how MySQL works with columns in `ORDER BY' or `HAVING' clauses that are not part of the selected columns. See *Note group-by-extensions::. 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 *Note 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 *Note `EXPLAIN': 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;  File: manual.info, Node: subquery-optimization-with-exists, Next: limit-optimization, Prev: distinct-optimization, Up: select-optimization 8.3.1.21 Optimizing Subqueries with `EXISTS' Strategy ..................................................... Certain optimizations are applicable to comparisons that use the `IN' operator to test subquery results (or that use `=ANY', which is equivalent). This section discusses these optimizations, particularly with regard to the challenges that `NULL' values present. Suggestions on what you can do to help the optimizer are given at the end of the discussion. 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. That is, the comparison is converted to 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 that it must examine when evaluating 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) The following discussion assumes a single pair of outer and inner expression values for simplicity. 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 two conditions are true: * OUTER_EXPR and INNER_EXPR cannot be `NULL'. * You do not need to 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 don't care.) 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 *Note `SELECT': select. produces any row where INNER_EXPR is `NULL' * `FALSE', if the *Note `SELECT': 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: 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. However, they are not visible in *Note `EXPLAIN': explain. output, so you must use *Note `EXPLAIN EXTENDED': explain-extended. followed by *Note `SHOW WARNINGS': show-warnings. (note the `checking NULL' in the warning message): mysql> EXPLAIN EXTENDED -> SELECT OUTER_EXPR IN (SELECT maybe_null_key FROM t2) 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: maybe_null_key key: maybe_null_key key_len: 5 ref: func rows: 2 Extra: Using index mysql> SHOW WARNINGS\G *************************** 1. row *************************** Level: Note Code: 1003 Message: select (`test`.`t1`.`outer_expr`, (((`test`.`t1`.`outer_expr`) in t2 on maybe_null_key checking NULL))) AS `outer_expr IN (SELECT maybe_null_key FROM t2)` from `test`.`t1` 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 *Note `SELECT': select. produces any rows * `FALSE', if the *Note `SELECT': select. produces no rows For proper evaluation, it is necessary to be able to check whether the *Note `SELECT': 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. In MySQL 5.1 before 5.1.16, the optimizer chose speed over distinguishing a `NULL' from `FALSE' result, so for some queries, you might get a `FALSE' result rather than `NULL'. As of MySQL 5.1.16, 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 run the *Note `SELECT': select. to determine whether it produces any rows: NULL IN (SELECT INNER_EXPR FROM ... WHERE SUBQUERY_WHERE) It is necessary to run the original *Note `SELECT': 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 to push down or not push down conditions into the subquery, the conditions are wrapped in `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 that trigger functions are _not_ triggers of the kind that you create with *Note `CREATE TRIGGER': create-trigger. Equalities that are wrapped into `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. At the moment, 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 will be 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 *Note `EXPLAIN': 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 *Note `EXPLAIN EXTENDED': explain-extended. followed by *Note `SHOW WARNINGS': show-warnings, you can see the triggered condition: *************************** 1. row *************************** Level: Note Code: 1003 Message: select `test`.`t1`.`col1` AS `col1`, (`test`.`t1`.`col1`, (((`test`.`t1`.`col1`) in t2 on key1 checking NULL where (`test`.`t2`.`col2` = `test`.`t1`.`col2`) having trigcond((`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 was to improve compliance and not speed). For multiple-table subqueries, execution of `NULL IN (SELECT ...)' will be particularly slow because the join optimizer doesn't 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 tips: * A column must be declared as `NOT NULL' if it really is. (This also helps other aspects of the optimizer.) * If you don't need to 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 ...)' will never be evaluated because MySQL stops evaluating `AND' parts as soon as the expression result is clear.  File: manual.info, Node: limit-optimization, Next: how-to-avoid-table-scan, Prev: subquery-optimization-with-exists, Up: select-optimization 8.3.1.22 Optimizing `LIMIT' Queries ................................... In some cases, MySQL handles a query differently when you are using `LIMIT ROW_COUNT' and not using `HAVING': * If you are selecting 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 use `LIMIT ROW_COUNT' with `ORDER BY', MySQL ends the 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 must be selected, and most or all of them must be sorted, before it can be ascertained that the first ROW_COUNT rows have been found. In either case, after the initial rows have been found, there is no need to sort any remainder of the result set, and MySQL does not do so. * When combining `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 key in order (or doing a sort on the key) and then calculating summaries until the key 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'. * `LIMIT 0' quickly returns an empty set. This can be useful for checking the validity of a query. When using one of the MySQL APIs, it can also be employed for obtaining the types of the result columns. (This trick does not work in the MySQL Monitor (the *Note `mysql': mysql. program), which merely displays `Empty set' in such cases; you should instead use *Note `SHOW COLUMNS': show-columns. or *Note `DESCRIBE': describe. for this purpose.) * When the server uses temporary tables to resolve the query, it uses the `LIMIT ROW_COUNT' clause to calculate how much space is required.  File: manual.info, Node: how-to-avoid-table-scan, Prev: limit-optimization, Up: select-optimization 8.3.1.23 How to Avoid Table Scans ................................. The output from *Note `EXPLAIN': explain. shows `ALL' in the `type' column when MySQL uses a 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 *Note where-optimizations::. * 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 *Note 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 *Note index-hints::. * Start *Note `mysqld': 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 *Note server-system-variables::.  File: manual.info, Node: non-select-optimization, Next: information-schema-optimization, Prev: select-optimization, Up: statement-optimization 8.3.2 Optimizing Non-`SELECT' Statements ---------------------------------------- * Menu: * insert-speed:: Speed of `INSERT' Statements * update-speed:: Speed of `UPDATE' Statements * delete-speed:: Speed of `DELETE' Statements * repair-table-speed:: Speed of `REPAIR TABLE' Statements  File: manual.info, Node: insert-speed, Next: update-speed, Prev: non-select-optimization, Up: non-select-optimization 8.3.2.1 Speed of `INSERT' Statements .................................... 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 *Note `INSERT': 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 *Note `INSERT': 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 *Note server-system-variables::. * If multiple clients are inserting a lot of rows, you can get higher speed by using the *Note `INSERT DELAYED': insert-delayed. statement. See *Note insert-delayed::. * For a `MyISAM' table, you can use concurrent inserts to add rows at the same time that *Note `SELECT': select. statements are running, if there are no deleted rows in middle of the data file. See *Note concurrent-inserts::. * When loading a table from a text file, use *Note `LOAD DATA INFILE': load-data. This is usually 20 times faster than using *Note `INSERT': insert. statements. See *Note load-data::. * With some extra work, it is possible to make *Note `LOAD DATA INFILE': load-data. run even faster for a `MyISAM' table when the table has many indexes. Use the following procedure: 1. Optionally create the table with *Note `CREATE TABLE': create-table. 2. Execute a *Note `FLUSH TABLES': flush. statement or a *Note `mysqladmin flush-tables': mysqladmin. command. 3. Use *Note `myisamchk --keys-used=0 -rq /PATH/TO/DB/TBL_NAME.': myisamchk. This removes all use of indexes for the table. 4. Insert data into the table with *Note `LOAD DATA INFILE': load-data. This does not update any indexes and therefore is very fast. 5. If you intend only to read from the table in the future, use *Note `myisampack': myisampack. to compress it. See *Note compressed-format::. 6. Re-create the indexes with *Note `myisamchk -rq /PATH/TO/DB/TBL_NAME': myisamchk. This creates the index tree in memory before writing it to disk, which is much faster that updating the index during *Note `LOAD DATA INFILE': load-data. because it avoids lots of disk seeks. The resulting index tree is also perfectly balanced. 7. Execute a *Note `FLUSH TABLES': flush. statement or a *Note `mysqladmin flush-tables': mysqladmin. command. *Note `LOAD DATA INFILE': load-data. 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 *Note `myisamchk': 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 *Note `LOAD DATA INFILE': load-data. statement. You can also disable or enable the nonunique indexes for a `MyISAM' table by using the following statements rather than *Note `myisamchk': myisamchk. If you use these statements, you can skip the *Note `FLUSH TABLE': flush. operations: ALTER TABLE TBL_NAME DISABLE KEYS; ALTER TABLE TBL_NAME ENABLE KEYS; * To speed up *Note `INSERT': 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 *Note `INSERT': insert. statements have completed. Normally, there would be as many index buffer flushes as there are *Note `INSERT': insert. statements. Explicit locking statements are not needed if you can insert all rows with a single *Note `INSERT': insert. To obtain faster insertions for transactional tables, you should use *Note `START TRANSACTION': commit. and *Note `COMMIT': commit. instead of *Note `LOCK TABLES': lock-tables. 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. *Note `INSERT': insert, *Note `UPDATE': update, and *Note `DELETE': 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 *Note `LOCK TABLES': lock-tables. followed by an *Note `UNLOCK TABLES': lock-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. *Note `INSERT': insert. is still much slower for loading data than *Note `LOAD DATA INFILE': load-data, even when using the strategies just outlined. * To increase performance for `MyISAM' tables, for both *Note `LOAD DATA INFILE': load-data. and *Note `INSERT': insert, enlarge the key cache by increasing the `key_buffer_size' system variable. See *Note server-parameters::.  File: manual.info, Node: update-speed, Next: delete-speed, Prev: insert-speed, Up: non-select-optimization 8.3.2.2 Speed of `UPDATE' Statements .................................... An update statement is optimized like a *Note `SELECT': 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 *Note `OPTIMIZE TABLE': optimize-table. occasionally. See *Note optimize-table::.  File: manual.info, Node: delete-speed, Next: repair-table-speed, Prev: update-speed, Up: non-select-optimization 8.3.2.3 Speed of `DELETE' Statements .................................... The time required to delete individual rows 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 *Note server-parameters::. To delete all rows from a table, `TRUNCATE TABLE TBL_NAME' is faster than 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 *Note truncate-table::.  File: manual.info, Node: repair-table-speed, Prev: delete-speed, Up: non-select-optimization 8.3.2.4 Speed of `REPAIR TABLE' Statements .......................................... *Note `REPAIR TABLE': repair-table. for `MyISAM' tables is similar to using *Note `myisamchk': myisamchk. for repair operations, and some of the same performance optimizations apply: * *Note `myisamchk': myisamchk. has variables that control memory allocation. You may be able to its improve performance by setting these variables, as described in *Note myisamchk-memory::. * For *Note `REPAIR TABLE': repair-table, the same principle applies, but because the repair is done by the server, you set server system variables instead of *Note `myisamchk': 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 *Note `myisamchk': 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 *Note `myisamchk': myisamchk. variables correspond to server system variables: This table lists *Note `myisamchk': myisamchk. variables and corresponding server system variables. *Note `myisamchk': 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 *Note `myisamchk': 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 *Note multiple-key-caches::. Based on the preceding remarks, a *Note `REPAIR TABLE': repair-table. operation can be done as follows to use settings similar to the *Note `myisamchk': 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 *Note `REPAIR TABLE': 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 *Note `REPAIR TABLE': 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.  File: manual.info, Node: information-schema-optimization, Next: miscellaneous-optimization-tips, Prev: non-select-optimization, Up: statement-optimization 8.3.3 `INFORMATION_SCHEMA' Optimization --------------------------------------- As of MySQL 5.1.21, the implementation of `INFORMATION_SCHEMA' is such that certain types of queries for `INFORMATION_SCHEMA' tables can be optimized to execute more quickly. This section provides guidelines on writing queries that take advantage of these optimizations. In general, the strategies outlined here minimize the need for the server to access the file system to obtain the information that makes up the contents of `INFORMATION_SCHEMA' tables. By writing queries that enable the server to avoid directory scans or opening table files, you will obtain better performance. These optimizations do have an effect on how collations are used for searches in `INFORMATION_SCHEMA' tables. For more information, see *Note 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 *Note `TABLES': tables-table, using a constant lookup value for `TABLE_SCHEMA' in the `WHERE' clause enables a data directory scan to be avoided. This table lists `INFORMATION_SCHEMA' tables and table columns for which a constant lookup value enables the server to avoid directory scans. Table Column to specify to Column to specify to avoid data directory avoid database scan directory scan *Note `COLUMNS': `TABLE_SCHEMA' `TABLE_NAME' columns-table. *Note `TABLE_SCHEMA' `TABLE_NAME' `KEY_COLUMN_USAGE': key-column-usage-table. *Note `PARTITIONS': `TABLE_SCHEMA' `TABLE_NAME' partitions-table. *Note `CONSTRAINT_SCHEMA' `TABLE_NAME' `REFERENTIAL_CONSTRAINTS': referential-constraints-table. *Note `STATISTICS': `TABLE_SCHEMA' `TABLE_NAME' statistics-table. *Note `TABLES': `TABLE_SCHEMA' `TABLE_NAME' tables-table. *Note `TABLE_SCHEMA' `TABLE_NAME' `TABLE_CONSTRAINTS': table-constraints-table. *Note `TRIGGERS': `EVENT_OBJECT_SCHEMA' `EVENT_OBJECT_TABLE' triggers-table. *Note `VIEWS': `TABLE_SCHEMA' `TABLE_NAME' views-table. 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. * *Note `COLUMNS': columns-table.: `OPEN_FRM_ONLY' applies to all columns * *Note `KEY_COLUMN_USAGE': key-column-usage-table.: `OPEN_FULL_TABLE' applies to all columns * *Note `PARTITIONS': partitions-table.: `OPEN_FULL_TABLE' applies to all columns * *Note `REFERENTIAL_CONSTRAINTS': referential-constraints-table.: `OPEN_FULL_TABLE' applies to all columns * *Note `STATISTICS': statistics-table.: This table shows optimization types that apply to `INFORMATION_SCHEMA' *Note `STATISTICS': statistics-table. table columns. 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' * *Note `TABLES': tables-table.: This table shows optimization types that apply to `INFORMATION_SCHEMA' *Note `TABLES': tables-table. table columns. 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' * *Note `TABLE_CONSTRAINTS': table-constraints-table.: `OPEN_FULL_TABLE' applies to all columns * *Note `TRIGGERS': triggers-table.: `OPEN_FULL_TABLE' applies to all columns * *Note `VIEWS': views-table.: This table shows optimization types that apply to `INFORMATION_SCHEMA' *Note `VIEWS': views-table. table columns. Column Optimization type `TABLE_CATALOG' `OPEN_FRM_ONLY' `TABLE_SCHEMA' `OPEN_FRM_ONLY' `TABLE_NAME' `OPEN_FRM_ONLY' `VIEW_DEFINITION' `OPEN_FULL_TABLE' `CHECK_OPTION' `OPEN_FULL_TABLE' `IS_UPDATABLE' `OPEN_FULL_TABLE' `DEFINER' `OPEN_FULL_TABLE' `SECURITY_TYPE' `OPEN_FULL_TABLE' `CHARACTER_SET_CLIENT' `OPEN_FULL_TABLE' `COLLATION_CONNECTION' `OPEN_FULL_TABLE' *3) Use *Note `EXPLAIN': 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 *Note `EXPLAIN': 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). *Note `EXPLAIN': 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. *Note `EXPLAIN': 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 *Note `EXPLAIN': 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 *Note `EXPLAIN': explain. output row: All *Note `COLUMNS': columns-table. 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 *Note `COLLATIONS': collations-table. is not one of the `INFORMATION_SCHEMA' tables for which optimizations are available.  File: manual.info, Node: miscellaneous-optimization-tips, Prev: information-schema-optimization, Up: statement-optimization 8.3.4 Other Optimization Tips ----------------------------- This section lists a number of miscellaneous tips for improving query processing speed: * Use persistent connections to the database to avoid connection overhead. If you cannot use persistent connections and you are initiating many new connections to the database, you may want to change the value of the `thread_cache_size' variable. See *Note server-parameters::. * Always check whether all your queries really use the indexes that you have created in the tables. In MySQL, you can do this with the *Note `EXPLAIN': explain. statement. See *Note using-explain::. * Try to avoid complex *Note `SELECT': 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 *Note `INSERT': 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, you should consider using the table in ways that avoid deleting rows. Another possibility is to run *Note `OPTIMIZE TABLE': 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 *Note concurrent-inserts::. * To fix any compression issues that may have occurred with `ARCHIVE' tables, you can use *Note `OPTIMIZE TABLE': optimize-table. See *Note archive-storage-engine::. * 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. * In some cases, it may make sense to introduce a column that is `hashed' based on information from other columns. If this column is short, reasonably unique, and indexed, it may be much 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; * For `MyISAM' tables that change frequently, you should try to avoid all variable-length columns (*Note `VARCHAR': char, *Note `BLOB': blob, and *Note `TEXT': blob.). The table uses dynamic row format if it includes even a single variable-length column. See *Note 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 *Note storage-engines::. * 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. * If you need to collect statistics from large log tables, use summary tables instead of scanning the entire log table. Maintaining the summaries should be much faster than trying to calculate statistics `live.' Regenerating new summary tables from the logs when things change (depending on business decisions) is faster than changing the running application. * If possible, you should 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. * 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. * In some cases, it is convenient to pack and store data into a *Note `BLOB': blob. column. In this case, you must provide code in your application to pack and unpack information, but this may save a lot of accesses at some stage. This is practical when you have data that does not conform well to a rows-and-columns table structure. * Normally, you should try to keep all data nonredundant (observing what is referred to in database theory as _third normal form_). However, there may be situations in which it can be advantageous to duplicate information or create summary tables to gain more speed. * Stored routines or UDFs (user-defined functions) may be a good way to gain performance for some tasks. See *Note stored-routines::, and *Note adding-functions::, for more information. * You can increase performance by caching queries or answers in your application and then executing many inserts or updates together. If your database system supports table locks, this should help to ensure 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 *Note query-cache::. * Use *Note `INSERT DELAYED': insert-delayed. when you do not need to know when your data is written. This reduces the overall insertion impact because many rows can be written with a single disk write. * Use `INSERT LOW_PRIORITY' when you want to give *Note `SELECT': select. statements higher priority than your inserts. Use `SELECT HIGH_PRIORITY' to get retrievals that jump the queue. That is, the *Note `SELECT': select. is executed even if there is another client waiting to do a write. `LOW_PRIORITY' and `HIGH_PRIORITY' have an effect only for storage engines that use only table-level locking (such as `MyISAM', `MEMORY', and `MERGE'). * Use multiple-row *Note `INSERT': insert. statements to store many rows with one SQL statement. Many SQL servers support this, including MySQL. * Use *Note `LOAD DATA INFILE': load-data. to load large amounts of data. This is faster than using *Note `INSERT': insert. statements. * Use `AUTO_INCREMENT' columns so that each row in a table can be identified by a single unique value. unique values. * Use *Note `OPTIMIZE TABLE': optimize-table. once in a while to avoid fragmentation with dynamic-format `MyISAM' tables. See *Note myisam-table-formats::. * Use `MEMORY' tables when possible to get more speed. See *Note memory-storage-engine::. `MEMORY' tables are useful for noncritical data that is accessed often, such as information about the last displayed banner for users who don't have cookies enabled in their Web browser. User sessions are another alternative available in many Web application environments for handling volatile state data. * With Web servers, images and other binary assets should normally be stored as files. That is, store only a reference to the file rather than the file itself in the database. Most Web servers are better at caching files than database contents, so using files is generally faster. * Columns with identical information in different tables should be declared to have identical data types so that joins based on the corresponding columns will be faster. * Try to keep column names simple. 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, you should keep them shorter than 18 characters. * If you need really high speed, you should take a look at the low-level interfaces for data storage that the different SQL servers support. For example, by accessing the MySQL `MyISAM' storage engine directly, you could get a speed increase of two to five times compared to using the SQL interface. To be able to do this, the data must be on the same server as the application, and usually it should only be accessed by one process (because external file locking is really slow). One could eliminate these problems by introducing low-level `MyISAM' commands in the MySQL server (this could be one easy way to get more performance if needed). By carefully designing the database interface, it should be quite easy to support this type of optimization. * 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 need not parse your text files to find line and column boundaries. * 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 *Note replication::. * 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 should ensure that the table is okay by running the server with the `--myisam-recover' option, or by running *Note `myisamchk': 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.)  File: manual.info, Node: controlling-optimizer, Next: optimization-indexes, Prev: statement-optimization, Up: optimization 8.4 Controlling the Query Optimizer =================================== * Menu: * controlling-query-plan-evaluation:: Controlling Query Plan Evaluation * switchable-optimizations:: Controlling Switchable Optimizations MySQL provides optimizer control through system variables that affect how query plans are evaluated and which switchable optimizations are enabled.  File: manual.info, Node: controlling-query-plan-evaluation, Next: switchable-optimizations, Prev: controlling-optimizer, Up: controlling-optimizer 8.4.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.  File: manual.info, Node: switchable-optimizations, Prev: controlling-query-plan-evaluation, Up: controlling-optimizer 8.4.2 Controlling 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 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. This table describes the syntax of the COMMAND value for SET `optimizer_switch' commands. 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 table lists the permissible OPT_NAME flag names. This table describes permissible OPT_NAME flag names for SET `optimizer_switch' commands. Flag Name Meaning `index_merge' Controls all Index Merge optimizations `index_merge_intersection'Controls the Index Merge Intersection Access optimization `index_merge_sort_union' Controls the Index Merge Sort-Union Access optimization `index_merge_union' Controls the Index Merge Union Access optimization For information about Index Merge, see *Note index-merge-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 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  File: manual.info, Node: optimization-indexes, Next: buffering-caching, Prev: controlling-optimizer, Up: optimization 8.5 Optimization and Indexes ============================ * Menu: * column-indexes:: Column Indexes * multiple-column-indexes:: Multiple-Column Indexes * mysql-indexes:: How MySQL Uses Indexes * myisam-index-statistics:: `InnoDB' and `MyISAM' Index Statistics Collection  File: manual.info, Node: column-indexes, Next: multiple-column-indexes, Prev: optimization-indexes, Up: optimization-indexes 8.5.1 Column Indexes -------------------- All MySQL data types can be indexed. Use of indexes on the relevant columns is the best way to improve the performance of *Note `SELECT': select. operations. The maximum number of indexes per table and the maximum index length is defined per storage engine. See *Note 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. With `COL_NAME(N)' syntax in an index specification, you can create an index that uses only the first N characters of a string column. Indexing only a prefix of column values in this way can make the index file much smaller. When you index a *Note `BLOB': blob. or *Note `TEXT': blob. 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). *Note*: Prefix limits are measured in bytes, while the prefix length in *Note `CREATE TABLE': create-table. statements is interpreted as number of characters. _Take this into account when specifying a prefix length for a column that uses a multi-byte character set_. You can also create `FULLTEXT' indexes. These are used for full-text searches. Only the `MyISAM' storage engine supports `FULLTEXT' indexes and only for *Note `CHAR': char, *Note `VARCHAR': char, and *Note `TEXT': blob. columns. Indexing always takes place over the entire column and column prefix indexing is not supported. For details, see *Note fulltext-search::. You can also create indexes on spatial data types. Currently, only `MyISAM' supports R-tree indexes on spatial types. Other storage engines use B-trees for indexing spatial types (except for `ARCHIVE' and *Note `NDBCLUSTER': mysql-cluster, which do not support spatial type indexing). The `MEMORY' storage engine uses `HASH' indexes by default, but also supports `BTREE' indexes.  File: manual.info, Node: multiple-column-indexes, Next: mysql-indexes, Prev: column-indexes, Up: optimization-indexes 8.5.2 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 *Note 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 *Note `SELECT': select. statement: mysql> 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 *Note 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 find 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 *Note `SELECT': 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 `(col2)' and `(col2, col3)' are not leftmost prefixes of `(col1, col2, col3)'.  File: manual.info, Node: mysql-indexes, Next: myisam-index-statistics, Prev: multiple-column-indexes, Up: optimization-indexes 8.5.3 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. If a table has 1,000 rows, this is at least 100 times faster than reading sequentially. If you need to access most of the rows, it is faster to read sequentially, because this minimizes disk seeks. Most MySQL indexes (`PRIMARY KEY', `UNIQUE', `INDEX', and `FULLTEXT') are stored in B-trees. Exceptions are that indexes on spatial data types use R-trees, and that `MEMORY' tables also support hash indexes. Strings are automatically prefix- and end-space compressed. See *Note create-index::. In general, indexes are used as described in the following discussion. Characteristics specific to hash indexes (as used in `MEMORY' tables) are described at the end of this section. 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. * 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, *Note `VARCHAR': char. and *Note `CHAR': 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. Comparison of dissimilar columns may prevent use of indexes if values cannot be compared directly without conversion. Suppose that a numeric column is compared to a string column. 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 key (for example, `ORDER BY KEY_PART1, KEY_PART2'). If all key parts are followed by `DESC', the key is read in reverse order. See *Note order-by-optimization::, and *Note group-by-optimization::. * In some cases, a query can be optimized to retrieve values without consulting the data rows. If a query uses only columns from a table that are numeric and that form a leftmost prefix for some key, the selected values may be retrieved from the index tree for greater speed: SELECT KEY_PART3 FROM TBL_NAME WHERE KEY_PART1=1 Suppose that you issue the following *Note `SELECT': select. statement: mysql> 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 will attempt to use the Index Merge optimization (see *Note index-merge-optimization::), or attempt to find the most restrictive index by deciding which index finds fewer 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 find 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 an index if the columns do not form a leftmost prefix of the index. Suppose that you have the *Note `SELECT': 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 `(col2)' and `(col2, col3)' are not leftmost prefixes of `(col1, col2, col3)'. * 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 *Note `SELECT': 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 *Note `SELECT': 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. * 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' 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.)  File: manual.info, Node: myisam-index-statistics, Prev: mysql-indexes, Up: optimization-indexes 8.5.4 `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 *Note `SHOW INDEX': 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 table statistics, you can use any of the following methods: * Execute *Note `myisamchk --stats_method=METHOD_NAME --analyze': myisamchk. * 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 *Note `ANALYZE TABLE': 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 *Note `ALTER TABLE': 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.  File: manual.info, Node: buffering-caching, Next: locking-issues, Prev: optimization-indexes, Up: optimization 8.6 Buffering and Caching ========================= * Menu: * myisam-key-cache:: The `MyISAM' Key Cache * innodb-buffer-pool:: The `InnoDB' Buffer Pool * query-cache:: The MySQL Query Cache MySQL uses several strategies that cache information in memory buffers to increase performance.  File: manual.info, Node: myisam-key-cache, Next: innodb-buffer-pool, Prev: buffering-caching, Up: buffering-caching 8.6.1 The `MyISAM' Key Cache ---------------------------- * Menu: * shared-key-cache:: Shared Key Cache Access * multiple-key-caches:: Multiple Key Caches * midpoint-insertion:: Midpoint Insertion Strategy * index-preloading:: Index Preloading * key-cache-block-size:: Key Cache Block Size * key-cache-restructuring:: Restructuring a 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 *Note innodb-buffer-pool::.  File: manual.info, Node: shared-key-cache, Next: multiple-key-caches, Prev: myisam-key-cache, Up: myisam-key-cache 8.6.1.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.  File: manual.info, Node: multiple-key-caches, Next: midpoint-insertion, Prev: shared-key-cache, Up: myisam-key-cache 8.6.1.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 *Note `CACHE INDEX': cache-index. statement (see *Note 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 *Note `CACHE INDEX': cache-index. statement can be created by setting its size with a *Note `SET GLOBAL': set-statement. 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; Note that you cannot destroy the default key cache. Any attempt to do this will be 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 *Note 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 *Note `CACHE INDEX': 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 *Note `CACHE INDEX': 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  File: manual.info, Node: midpoint-insertion, Next: index-preloading, Prev: multiple-key-caches, Up: myisam-key-cache 8.6.1.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.  File: manual.info, Node: index-preloading, Next: key-cache-block-size, Prev: midpoint-insertion, Up: myisam-key-cache 8.6.1.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 *Note `LOAD INDEX INTO CACHE': load-index. 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 *Note `CACHE INDEX': cache-index. statement, preloading places index blocks into that cache. Otherwise, the index is loaded into the default key cache.  File: manual.info, Node: key-cache-block-size, Next: key-cache-restructuring, Prev: index-preloading, Up: myisam-key-cache 8.6.1.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.  File: manual.info, Node: key-cache-restructuring, Prev: key-cache-block-size, Up: myisam-key-cache 8.6.1.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.  File: manual.info, Node: innodb-buffer-pool, Next: query-cache, Prev: myisam-key-cache, Up: buffering-caching 8.6.2 The `InnoDB' Buffer Pool ------------------------------ *Note `InnoDB': innodb-storage-engine. maintains a buffer pool for caching data and indexes in memory. `InnoDB' manages the pool as a list, using a least recently used (LRU) algorithm incorporating a midpoint insertion strategy. When room is needed to add a new block to the pool, `InnoDB' evicts the least recently used block and adds the new block to the middle of the list. The midpoint insertion strategy in effect causes the list to be treated as two sublists: * At the head, a sublist of `new' (or `young') blocks that have been recently used. * At the tail, a sublist of `old' blocks that are less recently used. As a result of the algorithm, the new sublist contains blocks that are heavily used by queries. The old sublist contains less-used blocks, and candidates for eviction are taken from this sublist. 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 block into the buffer pool, it initially inserts it at the midpoint (the head of the old sublist). A block can be read in as a result of two types of read requests: Because it is required (for example, to satisfy query execution), or as part of read-ahead performed in anticipation that it will be required. * The first access to a block in the old sublist makes it `young', causing it to move to the head of the buffer pool (the head of the new sublist). If the block was read in because it was required, the first access occurs immediately and the block is made young. If the block was read in due to read-ahead, the first access does not occur immediately (and might not occur at all before the block is evicted). * As long as no accesses occur for a block in the pool, it `ages' by moving toward the tail of the list. Blocks in both the new and old sublists age as other blocks are made new. Blocks in the old sublist also age as blocks are inserted at the midpoint. Eventually, a block that remains unused for long enough reaches the tail of the old sublist and is evicted. In the default operation of the buffer pool, a block when read in is loaded at the midpoint and then moved immediately to the head of the new sublist as soon as an access occurs. In the case of a table scan (such as performed for a *Note `mysqldump': mysqldump. operation), each block read by the scan ends up moving to the head of the new sublist because multiple rows are accessed from each block. This occurs even for a one-time scan, where the blocks are not otherwise used by other queries. Blocks may also be loaded by the read-ahead background thread and then moved to the head of the new sublist by a single access. These effects can be disadvantageous because they push blocks that are in heavy use by other queries out of the new sublist to the old sublist where they become subject to eviction. Several `InnoDB' system variables control the size of the buffer pool and let you tune the LRU algorithm: * `innodb_buffer_pool_size' Specifies the size of the buffer pool. If your buffer pool is small and you have sufficient memory, making the pool larger can improve performance by reducing the amount of disk I/O needed as queries access `InnoDB' tables. * `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). * `innodb_old_blocks_time' Specifies how long in milliseconds (ms) a block inserted into the old sublist must stay there after its first access before it can be moved to the new sublist. The default value is 0: A block inserted into the old sublist moves to the new sublist when Innodb has evicted 1/4 of the inserted block's pages from the buffer pool, 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 ms 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. `innodb_old_blocks_pct' and `innodb_old_blocks_time' are available as of MySQL 5.1.41, but only for `InnoDB Plugin', not the built-in version of `InnoDB'. By setting `innodb_old_blocks_time' greater than 0, you can prevent one-time table scans from flooding the new sublist with blocks used only for the scan. Rows in a block read in for a scan are accessed rapidly many times in succession, but the block is unused after that. If `innodb_old_blocks_time' is set to a value greater than the block scan time, the block is not moved to the new sublist during the table scan. Instead, it remains in the old sublist and ages to the tail of the list to be evicted quickly. This way, blocks used only for a one-time scan do not act to the detriment of heavily used blocks 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 to prevent them from flooding the new sublist: 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 fill the buffer pool with a table's content. For example, you might perform a table or index scan at server startup or during benchmarking or testing specifically to `warm up' the buffer pool. In this case, leaving `innodb_old_blocks_time' set to 0 accomplishes the goal of loading the scanned blocks into the new sublist. The output from the InnoDB Standard Monitor contains several fields in the `BUFFER POOL AND MEMORY' section that pertain to operation of the buffer pool LRU algorithm: * `Old database pages': The number of pages in the old sublist of the buffer pool. * `Pages made young, not young': The number of old pages that were moved to the head of the buffer pool (the new sublist), and the number of pages that have remained in the old sublist without being made new. * `youngs/s non-youngs/s': The number of accesses to old pages that have resulted in making them young or not. This metric differs from that of the previous item in two ways. First, it relates only to old pages. Second, it is based on 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.) * `young-making rate': Hits that cause blocks to move to the head of the buffer pool. * `not': Hits that do not cause blocks to move to the head of the buffer pool (due to the delay not being met). The `young-making' rate and `not' rate will not normally add up to the overall buffer pool hit rate. Hits for blocks in the old sublist cause them to move to the new sublist, but hits to blocks in the new sublist cause them to move to the head of the list only if they are a certain distance from the head. The preceding information from the Monitor can help you make LRU tuning decisions: * If you see very low `youngs/s' values when you do not have large scans going on, that indicates that you might need to either 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 blocks in that sublist take longer to move to the tail and be evicted. This increases the likelihood that they will be accessed again and be made young. * If you do not see a lot of `non-youngs/s' when you are doing large table scans (and lots of `youngs/s'), you will want to tune your delay value to be larger. For more information about InnoDB Monitors, see *Note innodb-monitors::. The `MyISAM' storage engine also uses an LRU algorithm, to manage its key cache. See *Note myisam-key-cache::.  File: manual.info, Node: query-cache, Prev: innodb-buffer-pool, Up: buffering-caching 8.6.3 The MySQL Query Cache --------------------------- * Menu: * query-cache-operation:: How the Query Cache Operates * query-cache-in-select:: Query Cache `SELECT' Options * query-cache-configuration:: Query Cache Configuration * query-cache-status-and-maintenance:: Query Cache Status and Maintenance The query cache stores the text of a *Note `SELECT': 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 *Note `mysqld': mysqld. servers updating the same `MyISAM' tables. *Note*: As of MySQL 5.1.17, the query cache is used for prepared statements under the conditions described in *Note query-cache-operation::. Before 5.1.17, the query cache is not used for prepared statements. *Note*: As of MySQL 5.1.63, 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. (Bug #53775) 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. If you build MySQL from source, query cache capabilities can be excluded from the server entirely by invoking `configure' with the `--without-query-cache' option. The query cache offers the potential for substantial performance improvement, but you should 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 *Note `SELECT': select. statements is much more likely to benefit from enabling the cache than a mix in which frequent *Note `INSERT': 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 *Note `SELECT': select. statements that use frequently modified tables. (See *Note 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.  File: manual.info, Node: query-cache-operation, Next: query-cache-in-select, Prev: query-cache, Up: query-cache 8.6.3.1 How the Query Cache Operates .................................... This section describes how the query cache works when it is operational. *Note 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 *Note `SELECT': 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 *Note 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 *Note `INSERT': insert, *Note `UPDATE': update, *Note `DELETE': delete, *Note `TRUNCATE TABLE': truncate-table, *Note `ALTER TABLE': alter-table, *Note `DROP TABLE': drop-table, or *Note `DROP DATABASE': drop-database. The query cache also works within transactions when using `InnoDB' tables. In MySQL 5.1, the result from a *Note `SELECT': 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. Before MySQL 5.1.17, prepared statements do not use the query cache. Beginning with 5.1.17, prepared statements use the query cache under certain conditions, which differ depending on the preparation method: * Statements that are issued using the binary protocol using *Note `mysql_stmt_prepare()': mysql-stmt-prepare. and *Note `mysql_stmt_execute()': mysql-stmt-execute. See *Note c-api-prepared-statements::. For a prepared statement executed using the binary protocol, 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, statements issued using the binary protocol are distinct from statements issued using the text protocol. * Statements that are issued using the text (nonbinary) protocol using *Note `PREPARE': prepare. and *Note `EXECUTE': execute. See *Note sql-syntax-prepared-statements::. These are denoted SQL PS statements here. Before MySQL 5.1.21, for a prepared statement executed using *Note `PREPARE': prepare. and *Note `EXECUTE': execute, it is not cached if it contains any `?' parameter markers. In that case, the statement after parameter expansion contains references to user variables, which prevents caching, even for nonprepared statements. If the statement contains no parameter markers, the statement is compared with statements in the query cache that were executed using the text protocol (that is, it is compared with other SQL PS statements and nonprepared statements). As of MySQL 5.1.21, this limitation is lifted and prepared statements that contain parameter markers can be cached because expansion directly substitutes the user variable values. A query cannot be cached if it contains any of the functions shown in the following table. This table lists functions that if used within a query, do not allow the query to be cached. `BENCHMARK()' `CONNECTION_ID()' `CONVERT_TZ()' `CURDATE()' `CURRENT_DATE()' `CURRENT_TIME()' `CURRENT_TIMESTAMP()' `CURTIME()' `DATABASE()' `ENCRYPT()' with one `FOUND_ROWS()' `GET_LOCK()' parameter `LAST_INSERT_ID()' `LOAD_FILE()' `MASTER_POS_WAIT()' `NOW()' `RAND()' `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' or `INFORMATION_SCHEMA' system database. * (_MySQL 5.1.63 and later_:) 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 *Note 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.  File: manual.info, Node: query-cache-in-select, Next: query-cache-configuration, Prev: query-cache-operation, Up: query-cache 8.6.3.2 Query Cache `SELECT' Options .................................... Two query cache-related options may be specified in *Note `SELECT': 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. (Due to a limitation in the parser, a space character must precede and follow the `SQL_NO_CACHE' keyword; a nonspace such as a newline causes the server to check the query cache to see whether the result is already cached.) Examples: SELECT SQL_CACHE id, name FROM customer; SELECT SQL_NO_CACHE id, name FROM customer;  File: manual.info, Node: query-cache-configuration, Next: query-cache-status-and-maintenance, Prev: query-cache-in-select, Up: query-cache 8.6.3.3 Query Cache Configuration ................................. 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 *Note `mysqld': mysqld. The query cache system variables all have names that begin with `query_cache_'. They are described briefly in *Note 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. The default size is 0, so the query cache is disabled by default. 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*: 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. You should 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'. 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 *Note `SET': set-statement. 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. *Note*: You can set the maximum size that can be specified for the query cache at runtime with the *Note `SET': set-statement. 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, you should 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).  File: manual.info, Node: query-cache-status-and-maintenance, Prev: query-cache-configuration, Up: query-cache 8.6.3.4 Query Cache Status and Maintenance .......................................... 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 *Note `FLUSH QUERY CACHE': flush. 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 *Note `FLUSH TABLES': flush. statement also does this. To monitor query cache performance, use *Note `SHOW STATUS': 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 *Note server-status-variables::. Some uses for them are described here. The total number of *Note `SELECT': 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 *Note `FLUSH QUERY CACHE': flush, 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 *Note query-cache-configuration::.  File: manual.info, Node: locking-issues, Next: optimizing-database-structure, Prev: buffering-caching, Up: optimization 8.7 Locking Issues ================== * Menu: * internal-locking:: Internal Locking Methods * table-locking:: Table Locking Issues * concurrent-inserts:: Concurrent Inserts * external-locking:: External Locking 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 *Note internal-locking::. * External locking occurs when the server and other programs lock *Note `MyISAM': myisam-storage-engine. table files to coordinate among themselves which program can access the tables at which time. See *Note external-locking::.  File: manual.info, Node: internal-locking, Next: table-locking, Prev: locking-issues, Up: locking-issues 8.7.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. External locking occurs when the server and other programs lock *Note `MyISAM': myisam-storage-engine. table files to coordinate among themselves which program can access the tables at which time. See *Note external-locking::. MySQL uses row-level locking (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_row_lock) for `InnoDB' tables to support simultaneous write access by multiple sessions, making them suitable for multi-user, highly concurrent, and OLTP applications. MySQL uses table-level locking (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_table_lock) for `MyISAM', `MEMORY', and `MERGE' tables, allowing only one session to update those tables at a time, making them more suitable for read-only, read-mostly, or single-user applications. * Considerations for Table Locking * Table locking in MySQL is deadlock-free for storage engines that use table-level locking. Deadlock avoidance is managed by always requesting all needed locks at once at the beginning of a query and always locking the tables in the same order. 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 if there is heavy *Note `SELECT': select. activity for the table. However, if you have many updates for a table, *Note `SELECT': select. statements wait until there are no more updates. For information on altering the priority of reads and writes, see *Note 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 `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 *Note `INSERT': insert. and *Note `SELECT': 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. This behavior is altered by the `concurrent_insert' system variable. See *Note concurrent-inserts::. If you acquire a table lock explicitly with *Note `LOCK TABLES': 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 *Note `INSERT': insert. and *Note `SELECT': select. operations on a table `real_table' when concurrent inserts are not possible, you can insert rows into a temporary table `temp_table' and update the real table with the rows from the temporary table periodically. This can be done with the following code: mysql> LOCK TABLES real_table WRITE, temp_table WRITE; mysql> INSERT INTO real_table SELECT * FROM temp_table; mysql> DELETE FROM temp_table; mysql> UNLOCK TABLES; `InnoDB' uses row locks. Deadlocks are possible for `InnoDB' because it automatically acquires locks during the processing of SQL statements, not at the start of the transaction. * Considerations for Row Locking * 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 Disadvantages of row-level locking: * Requires more memory than table-level locks * Slower than table-level locks when used on a large part of the table because you must acquire many more locks * Slower than other locks if you often do `GROUP BY' operations on a large part of the data or if you must scan the entire table frequently * 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; * *Note `SELECT': select. combined with concurrent *Note `INSERT': insert. statements, and very few *Note `UPDATE': update. or *Note `DELETE': 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 *Note miscellaneous-functions::.  File: manual.info, Node: table-locking, Next: concurrent-inserts, Prev: internal-locking, Up: locking-issues 8.7.2 Table Locking Issues -------------------------- To achieve a very high lock speed, MySQL uses table locking (instead of page, row, or column locking) for all storage engines except `InnoDB' and *Note `NDBCLUSTER': mysql-cluster. For `InnoDB' tables, MySQL uses table locking only if you explicitly lock the table with *Note `LOCK TABLES': lock-tables. For this storage engine, avoid using *Note `LOCK TABLES': lock-tables. at all, because `InnoDB' uses automatic row-level locking to ensure transaction isolation. For large tables, table locking is often better than row locking, but there are some disadvantages: * 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. During the update, all other sessions that want to access this particular table must wait until the update is done. * Table locking causes problems in cases such as 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. Table locking is also disadvantageous under the following scenario: * A session issues a *Note `SELECT': select. that takes a long time to run. * Another session then issues an *Note `UPDATE': update. on the same table. This session waits until the *Note `SELECT': select. is finished. * Another session issues another *Note `SELECT': select. statement on the same table. Because *Note `UPDATE': update. has higher priority than *Note `SELECT': select, this *Note `SELECT': select. waits for the *Note `UPDATE': update. to finish, _after_ waiting for the first *Note `SELECT': select. to finish. The following items describe some ways to avoid or reduce contention caused by table locking: * Try to get the *Note `SELECT': 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 *Note `mysqld': 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 *Note `SELECT': select. statements. In this case, the second *Note `SELECT': select. statement in the preceding scenario would execute before the *Note `UPDATE': update. statement, and would not need to wait for the first *Note `SELECT': 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 *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': delete. statement lower priority, use the `LOW_PRIORITY' attribute. * To give a specific *Note `SELECT': select. statement higher priority, use the `HIGH_PRIORITY' attribute. See *Note select::. * Start *Note `mysqld': mysqld. with a low value for the `max_write_lock_count' system variable to force MySQL to temporarily elevate the priority of all *Note `SELECT': 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 *Note `INSERT': insert. combined with *Note `SELECT': select, consider switching to `MyISAM' tables, which support concurrent *Note `SELECT': select. and *Note `INSERT': insert. statements. (See *Note concurrent-inserts::.) * If you mix inserts and deletes on the same table, *Note `INSERT DELAYED': insert-delayed. may be of great help. See *Note insert-delayed::. * If you have problems with mixed *Note `SELECT': select. and *Note `DELETE': delete. statements, the `LIMIT' option to *Note `DELETE': delete. may help. See *Note delete::. * Using `SQL_BUFFER_RESULT' with *Note `SELECT': select. statements can help to make the duration of table locks shorter. See *Note select::. * 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. Here are some tips concerning table locks in MySQL: * Concurrent users are not a problem if you do not mix updates with selects that need to examine many rows in the same table. * You can use *Note `LOCK TABLES': lock-tables. to increase speed, because many updates within a single lock is much faster than updating without locks. Splitting table contents into separate tables may also help. * If you encounter speed problems with table locks in MySQL, you may be able to improve performance by converting some of your tables to `InnoDB'. See *Note innodb-storage-engine::.  File: manual.info, Node: concurrent-inserts, Next: external-locking, Prev: table-locking, Up: locking-issues 8.7.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 *Note `INSERT': insert. statement can be executed to add rows to the end of the table at the same time that *Note `SELECT': select. statements are reading rows from the table. If there are multiple *Note `INSERT': insert. statements, they are queued and performed in sequence, concurrently with the *Note `SELECT': select. statements. The results of a concurrent *Note `INSERT': 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 1 and concurrent inserts are handled as just described. If `concurrent_insert' is set to 0, concurrent inserts are disabled. If the variable is set to 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. Under circumstances where concurrent inserts can be used, there is seldom any need to use the `DELAYED' modifier for *Note `INSERT': insert. statements. See *Note insert-delayed::. If you are using the binary log, concurrent inserts are converted to normal inserts for `CREATE ... SELECT' or *Note `INSERT ... SELECT': 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 *Note 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 *Note `LOAD DATA INFILE': load-data, 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 *Note `LOAD DATA': load-data. is executing. Use of the `CONCURRENT' option affects the performance of *Note `LOAD DATA': 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 *Note `LOCK TABLE': lock-tables, the difference between `READ LOCAL' and `READ' is that `READ LOCAL' permits nonconflicting *Note `INSERT': 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.  File: manual.info, Node: external-locking, Prev: concurrent-inserts, Up: locking-issues 8.7.4 External Locking ---------------------- External locking is the use of file system locking to manage contention for *Note `MyISAM': myisam-storage-engine. 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 *Note `myisamchk': myisamchk. to perform table maintenance operations on *Note `MyISAM': myisam-storage-engine. 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 *Note `myisamchk': myisamchk. for access to the tables. The same is true for use of *Note `myisampack': myisampack. to pack *Note `MyISAM': myisam-storage-engine. tables. If the server is run with external locking enabled, you can use *Note `myisamchk': myisamchk. at any time for read operations such a checking tables. In this case, if the server tries to update a table that *Note `myisamchk': myisamchk. is using, the server will wait for *Note `myisamchk': myisamchk. to finish before it continues. If you use *Note `myisamchk': myisamchk. for write operations such as repairing or optimizing tables, or if you use *Note `myisampack': myisampack. to pack tables, you _must_ always ensure that the *Note `mysqld': mysqld. server is not using the table. If you don't stop *Note `mysqld': mysqld, you should at least do a *Note `mysqladmin flush-tables': mysqladmin. before you run *Note `myisamchk': myisamchk. Your tables _may become corrupted_ if the server and *Note `myisamchk': 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 *Note `myisamchk': myisamchk. need to modify tables while the server is running. If you only _read_ tables with other programs, external locking is not required, although *Note `myisamchk': myisamchk. might report warnings if the server changes tables while *Note `myisamchk': myisamchk. is reading them. With external locking disabled, to use *Note `myisamchk': myisamchk, you must either stop the server while *Note `myisamchk': myisamchk. executes or else lock and flush the tables before running *Note `myisamchk': myisamchk. (See *Note system-optimization::.) To avoid this requirement, use the *Note `CHECK TABLE': check-table. and *Note `REPAIR TABLE': repair-table. statements to check and repair *Note `MyISAM': myisam-storage-engine. tables. For *Note `mysqld': 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. From MySQL 4.0 on, 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 *Note `MyISAM': myisam-storage-engine. tables from many MySQL processes, you must ensure that the following conditions are satisfied: * You should not use the query cache for queries that use tables that are updated by another process. * You should 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.)  File: manual.info, Node: optimizing-database-structure, Next: optimizing-the-server, Prev: locking-issues, Up: optimization 8.8 Optimizing Database Structure ================================= * Menu: * data-size:: Make Your Data as Small as Possible * procedure-analyse:: Using `PROCEDURE ANALYSE' * table-cache:: How MySQL Opens and Closes Tables * creating-many-tables:: Disadvantages of Creating Many Tables in the Same Database * internal-temporary-tables:: How MySQL Uses Internal Temporary Tables  File: manual.info, Node: data-size, Next: procedure-analyse, Prev: optimizing-database-structure, Up: optimizing-database-structure 8.8.1 Make Your Data as Small as Possible ----------------------------------------- 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 may give you a big performance gain. See *Note storage-engines::. You can get better performance for a table and minimize storage space by using the techniques listed here: * 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. *Note `MEDIUMINT': integer-types. is often a better choice than *Note `INT': integer-types. because a *Note `MEDIUMINT': integer-types. column uses 25% less space. * Declare columns to be `NOT NULL' if possible. It makes everything faster and you save one bit per column. If you really need `NULL' in your application, you should definitely use it. Just avoid having it on all columns by default. * For `MyISAM' tables, if you do not have any variable-length columns (*Note `VARCHAR': char, *Note `TEXT': blob, or *Note `BLOB': blob. columns), a fixed-size row format is used. This is faster but may waste some space. See *Note myisam-table-formats::. You can hint that you want to have fixed length rows even if you have *Note `VARCHAR': char. columns with the *Note `CREATE TABLE': create-table. option `ROW_FORMAT=FIXED'. * `InnoDB' tables use a compact storage format. In versions of MySQL earlier than 5.0.3, `InnoDB' rows contain some redundant information, such as the number of columns and the length of each column, even for fixed-size columns. By default, tables are created in the compact format (`ROW_FORMAT=COMPACT'). If you wish to downgrade to older versions of MySQL, you can request the old format with `ROW_FORMAT=REDUNDANT'. The presence of the compact row format decreases row storage space by about 20% 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 `InnoDB' format also changes how *Note `CHAR': char. columns containing UTF-8 data are stored. With `ROW_FORMAT=REDUNDANT', a UTF-8 `CHAR(N)' occupies 3 x N bytes, given that the maximum length of a UTF-8 encoded character is three bytes. Many languages can be written primarily using single-byte UTF-8 characters, so a fixed storage length often wastes space. With `ROW_FORMAT=COMPACT' format, `InnoDB' allocates a variable amount of storage in the range from N to 3 x N bytes for these columns by stripping trailing spaces if necessary. The minimum storage length is kept as N bytes to facilitate in-place updates in typical cases. * The primary index of a table should be as short as possible. This makes identification of each row easy and efficient. * Create only the indexes that you really need. Indexes are good for retrieval but bad when you need to store data quickly. If you access a table mostly by searching on a combination of columns, create an index on them. 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 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 *Note 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 *Note server-parameters::. * 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.  File: manual.info, Node: procedure-analyse, Next: table-cache, Prev: data-size, Up: optimizing-database-structure 8.8.2 Using `PROCEDURE ANALYSE' ------------------------------- `ANALYSE([MAX_ELEMENTS[,MAX_MEMORY]])' `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 *Note `SELECT': 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 *Note `ENUM': 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 *Note `ENUM': enum.; if there are more than MAX_ELEMENTS distinct values, then *Note `ENUM': 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.  File: manual.info, Node: table-cache, Next: creating-many-tables, Prev: procedure-analyse, Up: optimizing-database-structure 8.8.3 How MySQL Opens and Closes Tables --------------------------------------- When you execute a *Note `mysqladmin status': mysqladmin. 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.) *Note*: `table_open_cache' was known as `table_cache' in MySQL 5.1.2 and earlier. 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, you should have 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 also have to take into account that the `MyISAM' storage engine needs two file descriptors for each unique open table. You can increase the number of file descriptors available to MySQL using the `--open-files-limit' startup option to *Note `mysqld': mysqld. See *Note not-enough-file-handles::. The cache of open tables is kept at a level of `table_open_cache' entries. The default value is 64; this can be changed with the `--table_open_cache' option to *Note `mysqld': mysqld. 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 *Note `FLUSH TABLES': flush. statement or executes a *Note `mysqladmin flush-tables': mysqladmin. or *Note `mysqladmin refresh': mysqladmin. 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 *Note handler::. You can determine whether your table cache is too small by checking the *Note `mysqld': 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 *Note `FLUSH TABLES': flush. statements, you should increase the table cache size. See *Note server-system-variables::, and *Note server-status-variables::.  File: manual.info, Node: creating-many-tables, Next: internal-temporary-tables, Prev: table-cache, Up: optimizing-database-structure 8.8.4 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 *Note `SELECT': 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.  File: manual.info, Node: internal-temporary-tables, Prev: creating-many-tables, Up: optimizing-database-structure 8.8.5 How MySQL Uses Internal Temporary Tables ---------------------------------------------- In some cases, the server creates internal temporary tables while processing queries. Such a table can be held in memory and processed by the `MEMORY' storage engine, or stored on disk and processed by the `MyISAM' storage engine. The server may create a temporary table initially as an in-memory table, then convert it to an on-disk table if it becomes too large. Users have no direct control over when the server creates an internal temporary table or which storage engine the server uses to manage it. Temporary tables can be created under conditions such as these: * 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. * `DISTINCT' combined with `ORDER BY' may require a temporary table. * If you use the `SQL_SMALL_RESULT' option, MySQL uses an in-memory temporary table, unless the query also contains elements (described later) that require on-disk storage. To determine whether a query requires a temporary table, use *Note `EXPLAIN': explain. and check the `Extra' column to see whether it says `Using temporary'. See *Note using-explain::. Some conditions prevent the use of an in-memory temporary table, in which case the server uses an on-disk table instead: * Presence of a *Note `BLOB': blob. or *Note `TEXT': blob. column in the table * Presence of any string column in a `GROUP BY' or `DISTINCT' clause larger than 512 bytes * Presence of any string column with a maximum length larger than 512 (bytes for binary strings, characters for nonbinary strings) in the *Note `SELECT': select. list, if *Note `UNION': union. or *Note `UNION ALL': union. is used The *Note `SHOW COLUMNS': show-columns. and The *Note `DESCRIBE': describe. statements use `BLOB' as the type for some columns, thus the temporary table used for the results is an on-disk table. 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. This differs from `MEMORY' tables explicitly created with *Note `CREATE TABLE': create-table.: For such tables, 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. 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.  File: manual.info, Node: optimizing-the-server, Next: thread-information, Prev: optimizing-database-structure, Up: optimization 8.9 Optimizing the MySQL Server =============================== * Menu: * system-optimization:: System Factors and Startup Parameter Tuning * server-parameters:: Tuning Server Parameters * connection-threads:: How MySQL Uses Threads for Client Connections * memory-use:: How MySQL Uses Memory * disk-issues:: Disk Issues * symbolic-links:: Using Symbolic Links * large-page-support:: Enabling Large Page Support * host-cache:: DNS Lookup Optimization and the Host Cache  File: manual.info, Node: system-optimization, Next: server-parameters, Prev: optimizing-the-server, Up: optimizing-the-server 8.9.1 System Factors and Startup Parameter Tuning ------------------------------------------------- We start with system-level factors, because some of these decisions must be made very early to achieve large performance gains. In other cases, a quick look at this section may suffice. However, it is always nice to have a sense of how much can be gained by changing factors that apply at this level. The operating system to use is very important. To get the best use of multiple-CPU machines, you should use Solaris (because its threads implementation works well) or Linux (because the 2.4 and later kernels have good SMP support). Note that older Linux kernels have a 2GB filesize limit by default. If you have such a kernel and a need for files larger than 2GB, you should get the Large File Support (LFS) patch for the ext2 file system. Other file systems such as ReiserFS and XFS do not have this 2GB limitation. Before using MySQL in production, we advise you to test it on your intended platform. Other tips: * 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 *Note `MyISAM': myisam-storage-engine. tables. Since MySQL 4.0, the default has been for external locking to be disabled on all systems. The `--external-locking' and `--skip-external-locking' options explicitly enable and disable external locking. Note that 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 *Note `myisamchk': 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 *Note `myisamchk': 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 MySQL Cluster. The *Note `LOCK TABLES': lock-tables. and *Note `UNLOCK TABLES': lock-tables. statements use internal locking, so you can use them even if external locking is disabled.  File: manual.info, Node: server-parameters, Next: connection-threads, Prev: system-optimization, Up: optimizing-the-server 8.9.2 Tuning Server Parameters ------------------------------ You can determine the default buffer sizes used by the *Note `mysqld': mysqld. server using this command: shell> mysqld --verbose --help This command produces a list of all *Note `mysqld': mysqld. options and configurable system variables. The output includes the default variable values and looks something like this: abort-slave-event-count 0 allow-suspicious-udfs FALSE auto-increment-increment 1 auto-increment-offset 1 automatic-sp-privileges TRUE back_log 50 basedir /home/jon/bin/mysql-5.1/ bind-address (No default value) binlog-row-event-max-size 1024 binlog_cache_size 32768 binlog_format (No default value) bulk_insert_buffer_size 8388608 character-set-client-handshake TRUE character-set-filesystem binary character-set-server latin1 character-sets-dir /home/jon/bin/mysql-5.1/share/mysql/charsets/ chroot (No default value) collation-server latin1_swedish_ci completion-type 0 concurrent-insert 1 connect_timeout 10 console FALSE datadir . datetime_format %Y-%m-%d %H:%i:%s date_format %Y-%m-%d default-character-set latin1 default-collation latin1_swedish_ci default-storage-engine MyISAM default-table-type MyISAM default-time-zone (No default value) default_week_format 0 delayed_insert_limit 100 delayed_insert_timeout 300 delayed_queue_size 1000 disconnect-slave-event-count 0 div_precision_increment 4 enable-locking FALSE engine-condition-pushdown TRUE expire_logs_days 0 external-locking FALSE flush_time 0 ft_max_word_len 84 ft_min_word_len 4 ft_query_expansion_limit 20 ft_stopword_file (No default value) gdb FALSE general_log FALSE general_log_file (No default value) group_concat_max_len 1024 help TRUE init-connect (No default value) init-file (No default value) init-slave (No default value) innodb TRUE innodb-adaptive-hash-index TRUE innodb-additional-mem-pool-size 1048576 innodb-autoextend-increment 8 innodb-autoinc-lock-mode 1 innodb-buffer-pool-size 8388608 innodb-checksums TRUE innodb-commit-concurrency 0 innodb-concurrency-tickets 500 innodb-data-file-path (No default value) innodb-data-home-dir (No default value) innodb-doublewrite TRUE innodb-fast-shutdown 1 innodb-file-io-threads 4 innodb-file-per-table FALSE innodb-flush-log-at-trx-commit 1 innodb-flush-method (No default value) innodb-force-recovery 0 innodb-lock-wait-timeout 50 innodb-locks-unsafe-for-binlog FALSE innodb-log-buffer-size 1048576 innodb-log-file-size 5242880 innodb-log-files-in-group 2 innodb-log-group-home-dir (No default value) innodb-max-dirty-pages-pct 90 innodb-max-purge-lag 0 innodb-mirrored-log-groups 1 innodb-open-files 300 innodb-rollback-on-timeout FALSE innodb-stats-on-metadata TRUE innodb-status-file FALSE innodb-support-xa TRUE innodb-sync-spin-loops 20 innodb-table-locks TRUE innodb-thread-concurrency 8 innodb-thread-sleep-delay 10000 interactive_timeout 28800 join_buffer_size 131072 keep_files_on_create FALSE key_buffer_size 8384512 key_cache_age_threshold 300 key_cache_block_size 1024 key_cache_division_limit 100 language /home/jon/bin/mysql-5.1/share/mysql/english/ large-pages FALSE lc-time-names en_US local-infile TRUE log (No default value) log-bin (No default value) log-bin-index (No default value) log-bin-trust-function-creators FALSE log-bin-trust-routine-creators FALSE log-error log-isam myisam.log log-output FILE log-queries-not-using-indexes FALSE log-short-format FALSE log-slave-updates FALSE log-slow-admin-statements FALSE log-slow-slave-statements FALSE log-tc tc.log log-tc-size 24576 log-update (No default value) log-warnings 1 log_slow_queries (No default value) long_query_time 10 low-priority-updates FALSE lower_case_table_names 0 master-connect-retry 60 master-host (No default value) master-info-file master.info master-password (No default value) master-port 3306 master-retry-count 86400 master-ssl FALSE master-ssl-ca (No default value) master-ssl-capath (No default value) master-ssl-cert (No default value) master-ssl-cipher (No default value) master-ssl-key (No default value) master-user test max-binlog-dump-events 0 max_allowed_packet 1048576 max_binlog_cache_size 18446744073709547520 max_binlog_size 1073741824 max_connections 151 max_connect_errors 10 max_delayed_threads 20 max_error_count 64 max_heap_table_size 16777216 max_join_size 18446744073709551615 max_length_for_sort_data 1024 max_prepared_stmt_count 16382 max_relay_log_size 0 max_seeks_for_key 18446744073709551615 max_sort_length 1024 max_sp_recursion_depth 0 max_tmp_tables 32 max_user_connections 0 max_write_lock_count 18446744073709551615 memlock FALSE min_examined_row_limit 0 multi_range_count 256 myisam-recover OFF myisam_block_size 1024 myisam_data_pointer_size 6 myisam_max_extra_sort_file_size 2147483648 myisam_max_sort_file_size 9223372036853727232 myisam_repair_threads 1 myisam_sort_buffer_size 8388608 myisam_stats_method nulls_unequal myisam_use_mmap FALSE ndb-autoincrement-prefetch-sz 1 ndb-cache-check-time 0 ndb-connectstring (No default value) ndb-extra-logging 0 ndb-force-send TRUE ndb-index-stat-enable FALSE ndb-mgmd-host (No default value) ndb-nodeid 0 ndb-optimized-node-selection TRUE ndb-report-thresh-binlog-epoch-slip 3 ndb-report-thresh-binlog-mem-usage 10 ndb-shm FALSE ndb-use-copying-alter-table FALSE ndb-use-exact-count TRUE ndb-use-transactions TRUE ndb_force_send TRUE ndb_use_exact_count TRUE ndb_use_transactions TRUE net_buffer_length 16384 net_read_timeout 30 net_retry_count 10 net_write_timeout 60 new FALSE old FALSE old-alter-table FALSE old-passwords FALSE old-style-user-limits FALSE open_files_limit 1024 optimizer_prune_level 1 optimizer_search_depth 62 pid-file /home/jon/bin/mysql-5.1/var/tonfisk.pid plugin-load (No default value) plugin_dir /home/jon/bin/mysql-5.1/lib/mysql/plugin port 3306 port-open-timeout 0 preload_buffer_size 32768 profiling_history_size 15 query_alloc_block_size 8192 query_cache_limit 1048576 query_cache_min_res_unit 4096 query_cache_size 0 query_cache_type 1 query_cache_wlock_invalidate FALSE query_prealloc_size 8192 range_alloc_block_size 4096 read_buffer_size 131072 read_only FALSE read_rnd_buffer_size 262144 record_buffer 131072 relay-log (No default value) relay-log-index (No default value) relay-log-info-file relay-log.info relay_log_purge TRUE relay_log_space_limit 0 replicate-same-server-id FALSE report-host (No default value) report-password (No default value) report-port 3306 report-user (No default value) rpl-recovery-rank 0 safe-user-create FALSE secure-auth FALSE secure-file-priv (No default value) server-id 0 show-slave-auth-info FALSE skip-grant-tables FALSE skip-slave-start FALSE slave-exec-mode STRICT slave-load-tmpdir /tmp slave_compressed_protocol FALSE slave_net_timeout 3600 slave_transaction_retries 10 slow-query-log FALSE slow_launch_time 2 slow_query_log_file (No default value) socket /tmp/mysql.sock sort_buffer_size 2097144 sporadic-binlog-dump-fail FALSE sql-mode OFF symbolic-links TRUE sync-binlog 0 sync-frm TRUE sysdate-is-now FALSE table_definition_cache 256 table_lock_wait_timeout 50 table_open_cache 64 tc-heuristic-recover (No default value) temp-pool TRUE thread_cache_size 0 thread_concurrency 10 thread_stack 262144 timed_mutexes FALSE time_format %H:%i:%s tmpdir (No default value) tmp_table_size 16777216 transaction_alloc_block_size 8192 transaction_prealloc_size 4096 updatable_views_with_limit 1 use-symbolic-links TRUE verbose TRUE wait_timeout 28800 warnings 1 For a *Note `mysqld': mysqld. server that is currently running, you can see the current values of its system variables by connecting to it and issuing this statement: mysql> SHOW VARIABLES; You can also see some statistical and status indicators for a running server by issuing this statement: mysql> SHOW STATUS; System variable and status information also can be obtained using *Note `mysqladmin': mysqladmin.: shell> mysqladmin variables shell> mysqladmin extended-status For a full description of all system and status variables, see *Note server-system-variables::, and *Note server-status-variables::. MySQL uses algorithms that are very scalable, so you can usually run with very little memory. However, normally you get better performance by 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 256MB of memory and many tables and want maximum performance with a moderate number of clients, you should use something like this: shell> mysqld_safe --key_buffer_size=64M --table_open_cache=256 \ --sort_buffer_size=4M --read_buffer_size=1M & * If you have only 128MB 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=16M --sort_buffer_size=1M If there are very many simultaneous connections, swapping problems may occur unless *Note `mysqld': mysqld. has been configured to use very little memory for each connection. *Note `mysqld': 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, you should increase the value of `read_rnd_buffer_size' to speed up the reading of rows following sorting operations. You can make use of the example option files included with your MySQL distribution; see *Note server-configuration-defaults::. If you specify an option on the command line for *Note `mysqld': mysqld. or *Note `mysqld_safe': 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. To see the effects of a parameter change, do something like this: shell> mysqld --key_buffer_size=32M --verbose --help The variable values are listed near the end of the output. Make sure that the `--verbose' and `--help' options are last. Otherwise, the effect of any options listed after them on the command line are not reflected in the output. For information on tuning the `InnoDB' storage engine, see *Note innodb-tuning::.  File: manual.info, Node: connection-threads, Next: memory-use, Prev: server-parameters, Up: optimizing-the-server 8.9.3 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 *Note server-system-variables::, and *Note 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'.  File: manual.info, Node: memory-use, Next: disk-issues, Prev: connection-threads, Up: optimizing-the-server 8.9.4 How MySQL Uses Memory --------------------------- The following list indicates some of the ways that the *Note `mysqld': mysqld. server uses memory. Where applicable, the name of the system variable relevant to the memory use is given: * All threads share the *Note `MyISAM': myisam-storage-engine. key buffer; its size is determined by the `key_buffer_size' variable. Other buffers used by the server are allocated as needed. See *Note server-parameters::. * Each thread that is used to manage client connections uses some thread-specific space. The following list indicates these and which variables control their size: * A stack (variable `thread_stack') * A connection buffer (variable `net_buffer_length') * A result buffer (variable `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. * 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. * Before MySQL 5.1.4, only compressed `MyISAM' tables are memory mapped. As of MySQL 5.1.4, the `myisam_use_mmap' system variable can be set to 1 to enable memory-mapping for all `MyISAM' tables. * Each request that performs a sequential scan of a table allocates a _read buffer_ (variable `read_buffer_size'). * When reading rows in an arbitrary sequence (for example, following a sort), a _random-read buffer_ (variable `read_rnd_buffer_size') may be allocated to avoid disk seeks. * 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 *Note `BLOB': blob. columns are stored on disk. If an internal in-memory temporary table becomes too large, MySQL handles this automatically by changing the table from in-memory to on-disk format, to be handled by the `MyISAM' storage engine. You can increase the permissible temporary table size as described in *Note internal-temporary-tables::. * Most requests that perform a sort allocate a sort buffer and zero to two temporary files depending on the result set size. See *Note temporary-files::. * Almost all parsing and calculating is done in thread-local and reusable memory pools. No memory overhead is needed for small items, so the normal slow memory allocation and freeing is avoided. Memory is allocated only for unexpectedly large strings. * For each `MyISAM' table that is opened, the index file is opened once; the data file is opened once for each concurrently running thread. 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 *Note `BLOB': blob. columns). A *Note `BLOB': blob. column requires five to eight bytes plus the length of the *Note `BLOB': blob. data. The `MyISAM' storage engine maintains one extra row buffer for internal use. * For each table having *Note `BLOB': blob. columns, a buffer is enlarged dynamically to read in larger *Note `BLOB': blob. values. If you scan a table, a buffer as large as the largest *Note `BLOB': blob. value is allocated. * Handler structures for all in-use tables are saved in a cache and managed as a FIFO. The initial cache size is taken from the value of the `table_open_cache' system variable. If a table has been used by two running threads at the same time, the cache contains two entries for the table. See *Note table-cache::. * A *Note `FLUSH TABLES': flush. statement or *Note `mysqladmin flush-tables': mysqladmin. 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. *Note `FLUSH TABLES': flush. does not return until all tables have been closed. * The server caches information in memory as a result of *Note `GRANT': grant, *Note `CREATE USER': create-user, *Note `CREATE SERVER': create-server, and *Note `INSTALL PLUGIN': install-plugin. statements. This memory is not released by the corresponding *Note `REVOKE': revoke, *Note `DROP USER': drop-user, *Note `DROP SERVER': drop-server, and *Note `UNINSTALL PLUGIN': 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 *Note `FLUSH PRIVILEGES': flush. `ps' and other system status programs may report that *Note `mysqld': 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 *Note `mysqld': mysqld. with several memory-leakage detectors (both commercial and Open Source), so there should be no memory leaks.  File: manual.info, Node: disk-issues, Next: symbolic-links, Prev: memory-use, Up: optimizing-the-server 8.9.5 Disk Issues ----------------- * 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 *Note symbolic-links::. * 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 *Note 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. * On Linux, you can get much better performance by using `hdparm' to configure your disk's interface. (Up to 100% under load is not uncommon.) The following `hdparm' options should be quite good for MySQL, and probably for many other applications: hdparm -m 16 -d 1 Note that performance and reliability when using this command depend on your hardware, so we strongly suggest that you test your system thoroughly after using `hdparm'. Please consult the `hdparm' manual page for more information. If `hdparm' is not used wisely, file system corruption may result, so back up everything before experimenting! * 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.)  File: manual.info, Node: symbolic-links, Next: large-page-support, Prev: disk-issues, Up: optimizing-the-server 8.9.6 Using Symbolic Links -------------------------- * Menu: * symbolic-links-to-databases:: Using Symbolic Links for Databases on Unix * symbolic-links-to-tables:: Using Symbolic Links for `MyISAM' Tables on Unix * windows-symbolic-links:: Using Symbolic Links for Databases on Windows 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. 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';  File: manual.info, Node: symbolic-links-to-databases, Next: symbolic-links-to-tables, Prev: symbolic-links, Up: symbolic-links 8.9.6.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, or 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.  File: manual.info, Node: symbolic-links-to-tables, Next: windows-symbolic-links, Prev: symbolic-links-to-databases, Up: symbolic-links 8.9.6.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. 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 *Note `CREATE TABLE': create-table. See *Note create-table::. Alternatively, if *Note `mysqld': mysqld. is not running, symlinking can be accomplished manually using `ln -s' from the command line. *Note*: Beginning with MySQL 5.1.24, the path used with either or both of the `DATA DIRECTORY' and `INDEX DIRECTORY' options may not include the MySQL `data' directory. (Bug #32167) * *Note `myisamchk': 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 *Note `ALTER TABLE': alter-table, *Note `OPTIMIZE TABLE': optimize-table, and *Note `REPAIR TABLE': 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 *Note `mysqld': mysqld. as the system `root' or permit system users to have write access to MySQL database directories. * If you rename a table with *Note `ALTER TABLE ... RENAME': alter-table. or *Note `RENAME TABLE': 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 *Note `ALTER TABLE ... RENAME': alter-table. or *Note `RENAME TABLE': 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 *Note `mysqld': mysqld. with the `--skip-symbolic-links' option to ensure that no one can use *Note `mysqld': mysqld. to drop or rename a file outside of the data directory. These table symlink operations are not supported: * *Note `ALTER TABLE': alter-table. ignores the `DATA DIRECTORY' and `INDEX DIRECTORY' table options. * *Note `BACKUP TABLE': backup-table. and *Note `RESTORE TABLE': restore-table. do not respect symbolic links. * 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.  File: manual.info, Node: windows-symbolic-links, Prev: symbolic-links-to-tables, Up: symbolic-links 8.9.6.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. On Windows, create a symbolic link to a MySQL database by creating a `.sym' file in the data directory that contains the path to the destination directory. The file should be named `DB_NAME.sym', where DB_NAME is the database name. Support for database symbolic links on Windows using `.sym' files is enabled by default. If you do not need `.sym' file symbolic links, you can disable support for them by starting *Note `mysqld': mysqld. with the `--skip-symbolic-links' option. To determine whether your system supports `.sym' file symbolic links, check the value of the `have_symlink' system variable using this statement: SHOW VARIABLES LIKE 'have_symlink'; To create a `.sym' file symlink, use this procedure: 1. Change location into the data directory: C:\> cd \PATH\TO\DATADIR 2. In the data directory, create a text file named `mydb.sym' that contains this path name: `D:\data\mydb\' *Note*: The path name to the new database and tables should be absolute. If you specify a relative path, the location will be relative to the `mydb.sym' file. After this, all tables created in the database `mydb' are created in `D:\data\mydb'. The following limitations apply to the use of `.sym' files for database symbolic linking on Windows: * The symbolic link is not used if a directory with the same name as the database exists in the MySQL data directory. * The `--innodb_file_per_table' option cannot be used. * If you run *Note `mysqld': mysqld. as a service, you cannot use a mapped drive to a remote server as the destination of the symbolic link. As a workaround, you can use the full path (`\\servername\path\').  File: manual.info, Node: large-page-support, Next: host-cache, Prev: symbolic-links, Up: optimizing-the-server 8.9.7 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. Currently, MySQL supports only 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 by done either by editing `/etc/security/limits.conf' or by adding the following command to your *Note `mysqld_safe': mysqld-safe. script: ulimit -l unlimited Adding the `ulimit' command to *Note `mysqld_safe': mysqld-safe. causes the `root' user to set the memlock limit to `unlimited' before switching to the `mysql' user. (This assumes that *Note `mysqld_safe': 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  File: manual.info, Node: host-cache, Prev: large-page-support, Up: optimizing-the-server 8.9.8 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 the loopback interface address (`127.0.0.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 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 *Note blocked-host::. To unblock blocked hosts, flush the host cache by issuing a *Note `FLUSH HOSTS': flush. statement or executing a *Note `mysqladmin flush-hosts': mysqladmin. command. It is possible for a blocked host to become unblocked even without *Note `FLUSH HOSTS': flush. 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, start the server with the `--skip-host-cache' option. 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. 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 `HOST_CACHE_SIZE' define (default value: 128) and recompiling the server 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).  File: manual.info, Node: thread-information, Prev: optimizing-the-server, Up: optimization 8.10 Examining Thread Information ================================= * Menu: * thread-commands:: Thread Command Values * general-thread-states:: General Thread States * delayed-insert-thread-states:: Delayed-Insert Thread States * query-cache-thread-states:: Query Cache Thread States * master-thread-states:: Replication Master Thread States * slave-io-thread-states:: Replication Slave I/O Thread States * slave-sql-thread-states:: Replication Slave SQL Thread States * slave-connection-thread-states:: Replication Slave Connection Thread States * mysql-cluster-thread-states:: MySQL Cluster Thread States * event-scheduler-thread-states:: Event Scheduler Thread States 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: *Note show-processlist:: * The *Note `SHOW PROFILE': show-profile. statement: *Note show-profiles:: * The `INFORMATION_SCHEMA' *Note `PROCESSLIST': processlist-table. table: *Note processlist-table:: * The *Note `mysqladmin processlist': mysqladmin. command: *Note mysqladmin:: 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 *Note `SET TIMESTAMP = VALUE': set-statement. 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 *Note `SHOW FULL PROCESSLIST': show-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.  File: manual.info, Node: thread-commands, Next: general-thread-states, Prev: thread-information, Up: thread-information 8.10.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.  File: manual.info, Node: general-thread-states, Next: delayed-insert-thread-states, Prev: thread-commands, Up: thread-information 8.10.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 *Note `ANALYZE TABLE': 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, you should verify that you do not have a full disk and that the disk is not in very heavy use. * `converting HEAP to MyISAM' The thread is converting an internal temporary table from a `MEMORY' table to an on-disk `MyISAM' table. * `copy to tmp table' The thread is processing an *Note `ALTER TABLE': alter-table. statement. This state occurs after the table with the new structure has been created but before rows are copied into it. * `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. * `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 *Note 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 *Note `SELECT': 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'. * `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 *Note `ALTER TABLE': alter-table, *Note `CREATE VIEW': create-view, *Note `DELETE': delete, *Note `INSERT': insert, *Note `SELECT': select, or *Note `UPDATE': 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'. * `Flushing tables' The thread is executing *Note `FLUSH TABLES': flush. and is waiting for all threads to close their tables. * `FULLTEXT initialization' The server is preparing to perform a natural-language full-text search. * `init' This occurs before the initialization of *Note `ALTER TABLE': alter-table, *Note `DELETE': delete, *Note `INSERT': insert, *Note `SELECT': select, or *Note `UPDATE': 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 *Note `KILL': 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. * `Locked' The query is locked by another query. * `logging slow query' The thread is writing a statement to the slow-query log. * `NULL' This state is used for the *Note `SHOW PROCESSLIST': show-processlist. state. * `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. * `Opening tables', `Opening table' The thread is trying to open a table. This is should be very fast procedure, unless something prevents opening. For example, an *Note `ALTER TABLE': alter-table. or a *Note `LOCK TABLE': lock-tables. 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. * `Reading from net' The server is reading a packet from the network. * `Removing duplicates' The query was using *Note `SELECT DISTINCT': select. 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 *Note `SELECT': 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 *Note `ALTER TABLE': 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. * `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 *Note `UPDATE': update. is changing the index that is used to find the involved rows. * `Sending data' The thread is reading and processing rows for a *Note `SELECT': select. statement, and sending data to the client. Because operations occurring during this 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. * `setup' The thread is beginning an *Note `ALTER TABLE': 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 a `ORDER BY'. * `Sorting index' The thread is sorting index pages for more efficient access during a `MyISAM' table optimization operation. * `Sorting result' For a *Note `SELECT': 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 is going to request or is waiting for an internal or external system lock for the table. If this state is being caused by requests for external locks and you are not using multiple *Note `mysqld': mysqld. servers that are accessing the same *Note `MyISAM': myisam-storage-engine. 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. * `Table lock' The next thread state after `System lock'. The thread has acquired an external lock and is going to request an internal table lock. * `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 *Note `SHOW PROFILE': 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 release of readlock' The thread is waiting for a global read lock obtained by another thread (with *Note `FLUSH TABLES WITH READ LOCK': flush.) to be released. * `Waiting for tables', `Waiting for table' 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 *Note `FLUSH TABLES': flush. or one of the following statements on the table in question: `FLUSH TABLES TBL_NAME', *Note `ALTER TABLE': alter-table, *Note `RENAME TABLE': rename-table, *Note `REPAIR TABLE': repair-table, *Note `ANALYZE TABLE': analyze-table, or *Note `OPTIMIZE TABLE': optimize-table. * `Waiting on cond' A generic state in which the thread is waiting for a condition to become true. No specific state information is available. * `Waiting to get readlock' The thread has issued a *Note `FLUSH TABLES WITH READ LOCK': flush. statement to obtain a global read lock and is waiting to obtain the lock. * `Writing to net' The server is writing a packet to the network.  File: manual.info, Node: delayed-insert-thread-states, Next: query-cache-thread-states, Prev: general-thread-states, Up: thread-information 8.10.3 Delayed-Insert Thread States ----------------------------------- These thread states are associated with processing for `DELAYED' inserts (see *Note insert-delayed::). Some states are associated with connection threads that process *Note `INSERT DELAYED': insert-delayed. statements from clients. Other states are associated with delayed-insert handler threads that insert the rows. There is a delayed-insert handler thread for each table for which *Note `INSERT DELAYED': insert-delayed. statements are issued. States associated with a connection thread that processes an *Note `INSERT DELAYED': insert-delayed. statement from the client: * `allocating local table' The thread is preparing to feed rows to the delayed-insert handler thread. * `Creating delayed handler' The thread is creating a handler for `DELAYED' inserts. * `got handler lock' This occurs before the `allocating local table' state and after the `waiting for handler lock' state, when the connection thread gets access to the delayed-insert handler thread. * `got old table' This occurs after the `waiting for handler open' state. The delayed-insert handler thread has signaled that it has ended its initialization phase, which includes opening the table for delayed inserts. * `storing row into queue' The thread is adding a new row to the list of rows that the delayed-insert handler thread must insert. * `waiting for delay_list' This occurs during the initialization phase when the thread is trying to find the delayed-insert handler thread for the table, and before attempting to gain access to the list of delayed-insert threads. * `waiting for handler insert' An *Note `INSERT DELAYED': insert-delayed. handler has processed all pending inserts and is waiting for new ones. * `waiting for handler lock' This occurs before the `allocating local table' state when the connection thread waits for access to the delayed-insert handler thread. * `waiting for handler open' This occurs after the `Creating delayed handler' state and before the `got old table' state. The delayed-insert handler thread has just been started, and the connection thread is waiting for it to initialize. States associated with a delayed-insert handler thread that inserts the rows: * `insert' The state that occurs just before inserting rows into the table. * `reschedule' After inserting a number of rows, the delayed-insert thread sleeps to let other threads do work. * `upgrading lock' A delayed-insert handler is trying to get a lock for the table to insert rows. * `Waiting for INSERT' A delayed-insert handler is waiting for a connection thread to add rows to the queue (see `storing row into queue').  File: manual.info, Node: query-cache-thread-states, Next: master-thread-states, Prev: delayed-insert-thread-states, Up: thread-information 8.10.4 Query Cache Thread States -------------------------------- These thread states are associated with the query cache (see *Note 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.  File: manual.info, Node: master-thread-states, Next: slave-io-thread-states, Prev: query-cache-thread-states, Up: thread-information 8.10.5 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. * `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. * `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. * `Has sent all binlog to slave; waiting for binlog to be updated' The thread has read all outstanding 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. * `Waiting to finalize termination' A very brief state that occurs as the thread is stopping.  File: manual.info, Node: slave-io-thread-states, Next: slave-sql-thread-states, Prev: master-thread-states, Up: thread-information 8.10.6 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 *Note `SHOW SLAVE STATUS': show-slave-status, so you can get a good view of what is happening by using that statement. * `Waiting for master update' The initial state before `Connecting to master'. * `Connecting to master' The thread is attempting to connect to the master. * `Checking master version' A state that occurs very briefly, after the connection to the master is established. * `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 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 *Note `CHANGE MASTER TO': change-master-to. statement or the `--master-connect-retry' option. * `Reconnecting after a failed binlog dump request' The thread is trying to reconnect to the master. * `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. * `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. * `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 *Note `CHANGE MASTER TO': change-master-to. statement or `--master-connect-retry' option (default 60) before attempting to reconnect. * `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'. * `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 for slave mutex on exit' A state that occurs briefly as the thread is stopping.  File: manual.info, Node: slave-sql-thread-states, Next: slave-connection-thread-states, Prev: slave-io-thread-states, Up: thread-information 8.10.7 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: * `Waiting for the next event in relay log' The initial state before `Reading event from the relay log'. * `Reading event from the relay log' The thread has read an event from the relay log so that the event can be processed. * `Has read all relay log; waiting for the slave I/O thread to update it' 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. * `Making temp file' The thread is executing a *Note `LOAD DATA INFILE': load-data. statement and is creating a temporary file containing the data from which the slave will read rows. * `Waiting for slave mutex on exit' A very brief state that occurs as the thread is stopping. The `State' column for the I/O 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 is executing it.  File: manual.info, Node: slave-connection-thread-states, Next: mysql-cluster-thread-states, Prev: slave-sql-thread-states, Up: thread-information 8.10.8 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 *Note `CHANGE MASTER TO': change-master-to. statement. * `Creating table from master dump' The slave is creating a table using the *Note `CREATE TABLE': create-table. statement contained in the dump from the master. Used for *Note `LOAD TABLE FROM MASTER': load-table-from-master. and *Note `LOAD DATA FROM MASTER': load-data-from-master. * `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'. * `starting slave' The thread is starting the slave threads after processing a successful *Note `LOAD DATA FROM MASTER': load-data-from-master. load operation.  File: manual.info, Node: mysql-cluster-thread-states, Next: event-scheduler-thread-states, Prev: slave-connection-thread-states, Up: thread-information 8.10.9 MySQL 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 event from ndbcluster' The server is acting as an SQL node in a MySQL 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 to start' * `Waiting for schema epoch' The thread is waiting for a schema epoch (that is, a global checkpoint).  File: manual.info, Node: event-scheduler-thread-states, Prev: mysql-cluster-thread-states, Up: thread-information 8.10.10 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.  File: manual.info, Node: language-structure, Next: globalization, Prev: optimization, Up: Top 9 Language Structure ******************** * Menu: * literals:: Literal Values * identifiers:: Schema Object Names * reserved-words:: Reserved Words * user-variables:: User-Defined Variables * expressions:: Expression Syntax * comments:: Comment Syntax This chapter discusses the rules for writing the following elements of SQL (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_sql) statements when using MySQL: * Literal values such as strings and numbers * Identifiers such as database, table, and column names * Reserved words * User-defined and system variables * Comments  File: manual.info, Node: literals, Next: identifiers, Prev: language-structure, Up: language-structure 9.1 Literal Values ================== * Menu: * string-literals:: String Literals * number-literals:: Number Literals * date-and-time-literals:: Date and Time Literals * hexadecimal-literals:: Hexadecimal Literals * boolean-literals:: Boolean Literals * bit-field-literals:: Bit-Field Literals * null-values:: `NULL' Values This section describes how to write literal values in MySQL. These include strings, numbers, hexadecimal values, boolean values, and `NULL'. The section also covers the various nuances and `gotchas' that you may run into when dealing with these basic types in MySQL.  File: manual.info, Node: string-literals, Next: number-literals, Prev: literals, Up: literals 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 that has no character set or collation. A _nonbinary string_ is a string of characters that has a character set and collation. For both types of strings, comparisons are based on the numeric values of the string unit. For binary strings, the unit is the byte. For nonbinary strings the unit is the character and some character sets support multi-byte characters. Character value ordering is a function of the string collation. String literals may have an optional character set introducer and `COLLATE' clause: [_CHARSET_NAME]'STRING' [COLLATE COLLATION_NAME] Examples: SELECT _latin1'STRING'; SELECT _latin1'STRING' COLLATE latin1_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 more information about these forms of string syntax, see *Note charset-literal::, and *Note charset-national::. 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 *Note 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 *Note charset-literal::. *Special Character Escape Sequences* Escape Character Represented by Sequence Sequence `\0' An ASCII NUL (`0x00') 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 *Note 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 *Note `SELECT': 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 | +------------------------+ If you want to insert binary data into a string column (such as a *Note `BLOB': 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 *Note `mysql': 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 *Note 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 *Note `mysql_real_escape_string()': mysql-real-escape-string. C API function to escape characters. See *Note mysql-real-escape-string::. 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 *Note 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.  File: manual.info, Node: number-literals, Next: date-and-time-literals, Prev: string-literals, Up: literals 9.1.2 Number Literals --------------------- Integers are represented as a sequence of digits. Floats use ``.'' as a decimal separator. Either type of number may be preceded by ``-'' or ``+'' to indicate a negative or positive value, respectively Examples of valid integers: 1221 0 -32 Examples of valid floating-point numbers: 294.42 -32032.6809e+10 148.00 An integer may be used in a floating-point context; it is interpreted as the equivalent floating-point number.  File: manual.info, Node: date-and-time-literals, Next: hexadecimal-literals, Prev: number-literals, Up: literals 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: * *Note date-and-time-type-overview:: * *Note 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' } However, MySQL ignores the type keyword and each of the preceding constructions produces the string value `'STR'', with a type of *Note `VARCHAR': char. String and Numeric Literals in Date and Time Context MySQL recognizes *Note `DATE': datetime. 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 *Note `DATETIME': datetime. and *Note `TIMESTAMP': datetime. 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 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 *Note `DATETIME': datetime. or *Note `TIMESTAMP': datetime. value can include a trailing fractional seconds part in up to microseconds (6 digits) precision. Although this fractional part is recognized, it is discarded from values stored into *Note `DATETIME': datetime. or *Note `TIMESTAMP': datetime. columns. For information about fractional seconds support in MySQL, see *Note 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 *Note 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 *Note `TIME': 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. Although this fractional part is recognized, it is discarded from values stored into *Note `TIME': time. columns. For information about fractional seconds support in MySQL, see *Note fractional-seconds::. For *Note `TIME': 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''.  File: manual.info, Node: hexadecimal-literals, Next: boolean-literals, Prev: date-and-time-literals, Up: literals 9.1.4 Hexadecimal Literals -------------------------- MySQL supports hexadecimal values, written using `X'VAL'', `x'VAL'', or `0xVAL' format, where VAL contains hexadecimal digits (`0..9', `A..F'). Lettercase of the digits does not matter. For values written using `X'VAL'' or `x'VAL'' format, VAL must contain an even number of digits. For values written using `0xVAL syntax', values that contain an odd number of digits are treated as having an extra leading `0'. For example, `0x0a' and `0xaaa' are interpreted as `0x0a' and `0x0aaa'. In numeric contexts, hexadecimal values act like integers (64-bit precision). In string contexts, they act like binary strings, where each pair of hex digits is converted to a character: mysql> SELECT X'4D7953514C'; -> 'MySQL' mysql> SELECT 0x0a+0; -> 10 mysql> SELECT 0x5061756c; -> 'Paul' The default type of a hexadecimal value is a string. If you want to ensure that the value is treated as a number, you can use `CAST(... AS UNSIGNED)': mysql> SELECT 0x41, CAST(0x41 AS UNSIGNED); -> 'A', 65 The `X'HEXSTRING'' syntax is based on standard SQL. The `0x' syntax is based on ODBC. Hexadecimal strings are often used by ODBC to supply values for *Note `BLOB': blob. columns. You can convert a string or a number to a string in hexadecimal format with the `HEX()' function: mysql> SELECT HEX('cat'); -> '636174' mysql> SELECT 0x636174; -> 'cat'  File: manual.info, Node: boolean-literals, Next: bit-field-literals, Prev: hexadecimal-literals, Up: literals 9.1.5 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  File: manual.info, Node: bit-field-literals, Next: null-values, Prev: boolean-literals, Up: literals 9.1.6 Bit-Field Literals ------------------------ Bit-field values can be written using `b'VALUE'' or `0bVALUE' notation. VALUE is a binary value written using zeros and ones. Bit-field notation is convenient for specifying values to be assigned to *Note `BIT': bit-type. 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 are returned as binary values. To display them in printable form, add 0 or use a conversion function such as `BIN()'. High-order 0 bits are not displayed in the converted value. mysql> SELECT b+0, BIN(b+0), OCT(b+0), HEX(b+0) FROM t; +------+----------+----------+----------+ | b+0 | BIN(b+0) | OCT(b+0) | HEX(b+0) | +------+----------+----------+----------+ | 255 | 11111111 | 377 | FF | | 10 | 1010 | 12 | A | | 5 | 101 | 5 | 5 | +------+----------+----------+----------+ Bit values assigned to user variables are treated as binary strings. To assign a bit value as a number to a user variable, use `CAST()' or `+0': mysql> SET @v1 = 0b1000001; mysql> SET @v2 = CAST(0b1000001 AS UNSIGNED), @v3 = 0b1000001+0; mysql> SELECT @v1, @v2, @v3; +------+------+------+ | @v1 | @v2 | @v3 | +------+------+------+ | A | 65 | 65 | +------+------+------+  File: manual.info, Node: null-values, Prev: bit-field-literals, Up: literals 9.1.7 `NULL' Values ------------------- The `NULL' value means `no data.' `NULL' can be written in any lettercase. A synonym is `\N' (case sensitive). For text file import or export operations performed with *Note `LOAD DATA INFILE': load-data. or *Note `SELECT ... INTO OUTFILE': select-into, `NULL' is represented by the `\N' sequence. See *Note load-data::. 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 *Note problems-with-null::.  File: manual.info, Node: identifiers, Next: reserved-words, Prev: literals, Up: language-structure 9.2 Schema Object Names ======================= * Menu: * identifier-qualifiers:: Identifier Qualifiers * identifier-case-sensitivity:: Identifier Case Sensitivity * identifier-mapping:: Mapping of Identifiers to File Names * function-resolution:: Function Name Parsing and Resolution 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. *Note 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 *Note reserved-words::. 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. * Before MySQL 5.1.6, database and table names cannot contain ``/'', ``\'', ``.'', or characters that are not permitted in file names. 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 *Note server-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 *Note user-variables::, for more information and examples of workarounds. As of MySQL 5.1.6, special characters in database and table names are encoded in the corresponding file system names as described in *Note 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. This table describes the maximum length for each type of MySQL object identifier. Identifier Maximum Length (characters) Database 64 Table 64 Column 64 Index 64 Constraint 64 Stored 64 Procedure or Function Trigger 64 View 64 Event 64 Tablespace 64 Server 64 Log File 64 Group Alias 256 (see exception following table) Compound 16 Statement Label As of MySQL 5.1.23, aliases for column names in *Note `CREATE VIEW': 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 multi-byte characters without reducing the number of characters permitted for values stored in these columns, something not true prior to MySQL 4.1. As indicated earlier, the permissible Unicode characters are those in the Basic Multilingual Plane (BMP). Supplementary characters are not permitted.  File: manual.info, Node: identifier-qualifiers, Next: identifier-case-sensitivity, Prev: identifiers, Up: identifiers 9.2.1 Identifier Qualifiers --------------------------- MySQL permits names that consist of a single identifier or 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 the final identifier is interpreted. In MySQL, you can refer to a table column using any of the following forms. This table lists forms (column references) that can be used to refer to table columns. Column Reference Meaning COL_NAME The column COL_NAME from whichever table used in the statement contains a column of that name. TBL_NAME.COL_NAME The column COL_NAME from table TBL_NAME of the default database. DB_NAME.TBL_NAME.COL_NAMEThe column COL_NAME from table TBL_NAME of the database DB_NAME. 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. You need not specify a TBL_NAME or DB_NAME.TBL_NAME prefix for a column reference in a statement unless the reference would be ambiguous. Suppose that tables `t1' and `t2' each contain a column `c', and you retrieve `c' in a *Note `SELECT': select. statement that uses both `t1' and `t2'. In this case, `c' is ambiguous because it is not unique among the tables used in the statement. You must qualify it with a table name as `t1.c' or `t2.c' to indicate which table you mean. Similarly, to retrieve from a table `t' in database `db1' and from a table `t' in database `db2' in the same statement, you must refer to columns in those tables as `db1.t.COL_NAME' and `db2.t.COL_NAME'. The syntax `.TBL_NAME' means the table TBL_NAME in the default database. This syntax is accepted for ODBC compatibility because some ODBC programs prefix table names with a ``.'' character.  File: manual.info, Node: identifier-case-sensitivity, Next: identifier-mapping, Prev: identifier-qualifiers, Up: identifiers 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 Mac OS X, which is Unix-based but uses a default file system type (HFS+) that is not case sensitive. However, Mac OS X also supports UFS volumes, which are case sensitive just as on any Unix. See *Note 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 Mac 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 *Note `mysqld': 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 Mac OS X, the default value is 2. This table describes values for the `lower_case_table_names' system variable. Value Meaning `0' Table and database names are stored on disk using the lettercase specified in the *Note `CREATE TABLE': create-table. or *Note `CREATE DATABASE': 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 Mac 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 *Note `CREATE TABLE': create-table. or *Note `CREATE DATABASE': 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 *Note `SHOW TABLES': show-tables. or *Note `SHOW DATABASES': 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 *Note `mysqld': mysqld. and restarting it with the new variable setting. To do this for an individual table, use *Note `RENAME TABLE': 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 *Note `mysqldump': 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 *Note `PREPARE': 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 *Note charset-collation-information-schema::.  File: manual.info, Node: identifier-mapping, Next: function-resolution, Prev: identifier-case-sensitivity, Up: identifiers 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. Before MySQL 5.1.6, there are some limitations on the characters that can be used in identifiers for database objects that correspond to file system objects. For example, path name separator characters are not permitted, and ``.'' is not permitted because it begins the extension for table files. As of MySQL 5.1.6, any character is legal in database or table identifiers except ASCII NUL (`0x00'). 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. This table shows the encoding for national letters from alphabets that have uppercase/lowercase mapping, excluding basic Latin letters (`a..zA..Z'), digits (`0..9') and underscore (`_'), which are encoded as is. Code Range Pattern Number Used Unused Blocks 00C0..017F [@][0..4][g..z]5*20= 100 97 3 Latin-1 Supplement + Latin Extended-A 0370..03FF [@][5..9][g..z]5*20= 100 88 12 Greek and Coptic 0400..052F [@][g..z][0..6]20*7= 140 137 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=220 203 17 Latin Extended-B + IPA Extensions 1E00..1EFF [@][g..z][l..r]20*7= 140 136 4 Latin Extended Additional 1F00..1FFF [@][g..z][s..z]20*8= 160 144 16 Greek Extended .... .... [@][a..f][g..z]6*20= 120 0 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 hex 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' cannot be used as file names because they are reserved as device names. As of MySQL 5.1.10, these are permissible names in MySQL. They 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 *Note `SHOW': show. statements. For example, if you have a table named `a@b' and its name encoding has not been updated, *Note `SHOW TABLES': 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 *Note `mysqlcheck': mysqlcheck. The following command updates all names to the new encoding: shell> mysqlcheck --check-upgrade --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 *Note `mysqlcheck': mysqlcheck. invocation syntax, see *Note 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, *Note `mysqlcheck': 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 *Note `mysqldump': mysqldump. to dump them before upgrading to MySQL 5.1.6 or later, and then reload the dump file after upgrading.  File: manual.info, Node: function-resolution, Prev: identifier-mapping, Up: identifiers 9.2.4 Function Name Parsing and Resolution ------------------------------------------ MySQL 5.1 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. *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 exact list of function names for which following whitespace determines their interpretation are those listed in the `sql_functions[]' array of the `sql/lex.h' source file. Before MySQL 5.1, these are rather numerous (about 200), so you may find it easiest to treat the no-whitespace requirement as applying to all function calls. In MySQL 5.1, parser improvements reduce to about 30 the number of affected function names. For functions not listed in the `sql_functions[]') array, 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 *Note reserved-words::). 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 *Note server-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); The number of function names affected by `IGNORE_SPACE' was reduced significantly in MySQL 5.1.13, from about 200 to about 30. As of MySQL 5.1.13, only the following functions are still affected by the `IGNORE_SPACE' setting. This table lists functions that are still affected by the `IGNORE_SPACE' setting as of MySQL 5.1.13. `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 earlier versions of MySQL, check the contents of the `sql_functions[]' array in the `sql/lex.h' source file to see which functions are affected by `IGNORE_SPACE'. *Incompatibility warning*: The change in MySQL 5.1.13 that reduces the number of function names affected by `IGNORE_SPACE' improves the consistency of parser operation. However, it also introduces the possibility of incompatibility for old SQL code that relies on the following conditions: * `IGNORE_SPACE' is disabled. * The presence or absence of whitespace following a function name is used to distinguish between a built-in function and stored function that have the same name, such as `PI()' versus `PI ()'. For functions that are no longer affected by `IGNORE_SPACE' as of MySQL 5.1.13, that strategy no longer works. Either of the following approaches can be used if you have code that is subject to the preceding incompatibility: * If a stored function has a name that conflicts with a built-in function, refer to the stored function with a schema name qualifier, regardless of whether whitespace is present. For example, write `SCHEMA_NAME.PI()' or `SCHEMA_NAME.PI ()'. * Alternatively, rename the stored function to use a nonconflicting name and change invocations of the function to use the new name. *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 As of MySQL 5.1.14, an error occurs if you try to create a UDF with the same name as a built-in function. Before 5.1.14, a UDF can be created with the same name as a built-in function but the UDF cannot be invoked because the parser resolves invocations of the function to refer to the built-in function. For example, if you create a UDF named `ABS', references to `ABS()' invoke the 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, you invoke it as `test.PI()' because the server resolves `PI()' as a reference to the built-in function. As of 5.1.14, the server creates a warning if the stored function name collides with a built-in function name. The warning can be displayed with *Note `SHOW WARNINGS': 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 *Note `DROP FUNCTION': drop-function. to drop the UDF, and then use *Note `CREATE FUNCTION': create-function. to re-create the UDF with a different nonconflicting 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).  File: manual.info, Node: reserved-words, Next: user-variables, Prev: identifiers, Up: language-structure 9.3 Reserved Words ================== Certain words such as *Note `SELECT': select, *Note `DELETE': delete, or *Note `BIGINT': integer-types. 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. Reserved words are permitted as identifiers if you quote them as described in *Note 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)' 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 detail on recognition of function names, see *Note function-resolution::. The words in the following table are explicitly reserved in MySQL 5.1. 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 words in the table 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 reserved word can be used as an identifier if you quote it. For a more detailed list of reserved words, including differences between versions, see Reserved Words in MySQL 5.1 (http://dev.mysql.com/doc/mysqld-version-reference/en/mysqld-version-reference-reservedwords-5-1.html). *Reserved Words in MySQL 5.1.73* `ACCESSIBLE' `ADD' `ALL' `ALTER' `ANALYZE' `AND' `AS' `ASC' `ASENSITIVE' `BEFORE' `BETWEEN' `BIGINT' `BINARY' `BLOB' `BOTH' `BY' `CALL' `CASCADE' `CASE' `CHANGE' `CHAR' `CHARACTER' `CHECK' `COLLATE' `COLUMN' `CONDITION' `CONSTRAINT' `CONTINUE' `CONVERT' `CREATE' `CROSS' `CURRENT_DATE' `CURRENT_TIME' `CURRENT_TIMESTAMP' `CURRENT_USER' `CURSOR' `DATABASE' `DATABASES' `DAY_HOUR' `DAY_MICROSECOND' `DAY_MINUTE' `DAY_SECOND' `DEC' `DECIMAL' `DECLARE' `DEFAULT' `DELAYED' `DELETE' `DESC' `DESCRIBE' `DETERMINISTIC' `DISTINCT' `DISTINCTROW' `DIV' `DOUBLE' `DROP' `DUAL' `EACH' `ELSE' `ELSEIF' `ENCLOSED' `ESCAPED' `EXISTS' `EXIT' `EXPLAIN' `FALSE' `FETCH' `FLOAT' `FLOAT4' `FLOAT8' `FOR' `FORCE' `FOREIGN' `FROM' `FULLTEXT' `GRANT' `GROUP' `HAVING' `HIGH_PRIORITY' `HOUR_MICROSECOND' `HOUR_MINUTE' `HOUR_SECOND' `IF' `IGNORE' `IN' `INDEX' `INFILE' `INNER' `INOUT' `INSENSITIVE' `INSERT' `INT' `INT1' `INT2' `INT3' `INT4' `INT8' `INTEGER' `INTERVAL' `INTO' `IS' `ITERATE' `JOIN' `KEY' `KEYS' `KILL' `LEADING' `LEAVE' `LEFT' `LIKE' `LIMIT' `LINEAR' `LINES' `LOAD' `LOCALTIME' `LOCALTIMESTAMP' `LOCK' `LONG' `LONGBLOB' `LONGTEXT' `LOOP' `LOW_PRIORITY' `MASTER_SSL_VERIFY_SERVER_CERT' `MATCH' `MEDIUMBLOB' `MEDIUMINT' `MEDIUMTEXT' `MIDDLEINT' `MINUTE_MICROSECOND' `MINUTE_SECOND' `MOD' `MODIFIES' `NATURAL' `NOT' `NO_WRITE_TO_BINLOG' `NULL' `NUMERIC' `ON' `OPTIMIZE' `OPTION' `OPTIONALLY' `OR' `ORDER' `OUT' `OUTER' `OUTFILE' `PRECISION' `PRIMARY' `PROCEDURE' `PURGE' `RANGE' `READ' `READS' `READ_WRITE' `REAL' `REFERENCES' `REGEXP' `RELEASE' `RENAME' `REPEAT' `REPLACE' `REQUIRE' `RESTRICT' `RETURN' `REVOKE' `RIGHT' `RLIKE' `SCHEMA' `SCHEMAS' `SECOND_MICROSECOND' `SELECT' `SENSITIVE' `SEPARATOR' `SET' `SHOW' `SMALLINT' `SPATIAL' `SPECIFIC' `SQL' `SQLEXCEPTION' `SQLSTATE' `SQLWARNING' `SQL_BIG_RESULT' `SQL_CALC_FOUND_ROWS' `SQL_SMALL_RESULT' `SSL' `STARTING' `STRAIGHT_JOIN' `TABLE' `TERMINATED' `THEN' `TINYBLOB' `TINYINT' `TINYTEXT' `TO' `TRAILING' `TRIGGER' `TRUE' `UNDO' `UNION' `UNIQUE' `UNLOCK' `UNSIGNED' `UPDATE' `USAGE' `USE' `USING' `UTC_DATE' `UTC_TIME' `UTC_TIMESTAMP' `VALUES' `VARBINARY' `VARCHAR' `VARCHARACTER' `VARYING' `WHEN' `WHERE' `WHILE' `WITH' `WRITE' `XOR' `YEAR_MONTH' `ZEROFILL' *New Reserved Words in MySQL 5.1* `ACCESSIBLE' `LINEAR' `MASTER_SSL_VERIFY_SERVER_CERT' `RANGE' `READ_ONLY' `READ_WRITE' MySQL permits some keywords to be used as unquoted identifiers because many people previously used them. Examples are those in the following list: * `ACTION' * *Note `BIT': bit-type. * *Note `DATE': datetime. * *Note `ENUM': enum. * `NO' * *Note `TEXT': blob. * *Note `TIME': time. * *Note `TIMESTAMP': datetime.  File: manual.info, Node: user-variables, Next: expressions, Prev: reserved-words, Up: language-structure 9.4 User-Defined Variables ========================== You can store a value in a user-defined variable in one statement and then refer to it later in another statement. This enables you to pass values from one statement to another. _User-defined variables are session-specific_. That is, a user variable defined by one client cannot be seen or used by other clients. All variables for a given client session are automatically freed when that client exits. 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 variable names are not case sensitive in MySQL 5.0 and up. One way to set a user-defined variable is by issuing a *Note `SET': set-statement. statement: SET @VAR_NAME = EXPR [, @VAR_NAME = EXPR] ... For *Note `SET': set-statement, either `=' or `:=' can be used as the assignment operator. You can also assign a value to a user variable in statements other than *Note `SET': set-statement. In this case, the assignment operator must be `:=' and not `=' because the latter is treated as the comparison operator `=' in non-*Note `SET': set-statement. 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. 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.) Bit values assigned to user variables are treated as binary strings. To assign a bit value as a number to a user variable, use `CAST()' or `+0': mysql> SET @v1 = b'1000001'; mysql> SET @v2 = CAST(b'1000001' AS UNSIGNED), @v3 = b'1000001'+0; 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 *Note `SELECT': select. statement, or the `IGNORE N LINES' clause of a *Note `LOAD DATA': load-data. statement. As a general rule, other than in *Note `SET': set-statement. 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 *Note `SELECT': 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-*Note `SET': set-statement. 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 *Note `SELECT': 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 *Note `SELECT': 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 *Note `SELECT': 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 *Note `SELECT': 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 that if you are constructing a string for use as a prepared statement to be executed 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 *Note 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: query($query); while($row = $result->fetch_assoc()) { echo "

" . $row["$col"] . "

\n"; } $result->close(); $mysqli->close(); ?> Assembling an SQL statement in this fashion is sometimes known as `Dynamic SQL'.  File: manual.info, Node: expressions, Next: comments, Prev: user-variables, Up: language-structure 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. Operator precedence is given in *Note operator-precedence::. 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 literal value syntax, see *Note literals::. For identifier syntax, see *Note identifiers::. Variables can be user variables, system variables, or stored program local variables or parameters: * User variables: *Note user-variables:: * System variables: *Note using-system-variables:: * Local variables: *Note declare-local-variable:: * Parameters: *Note create-procedure:: PARAM_MARKER is `'?'' as used in prepared statements for placeholders. See *Note prepare::. `(SUBQUERY)' indicates a subquery that returns a single value; that is, a scalar subquery. See *Note 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 *Note fulltext-search::. CASE_EXPR indicates a `CASE' expression. See *Note 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 *Note 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 *Note server-sql-mode::.  File: manual.info, Node: comments, Prev: expressions, Up: language-structure 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 *Note 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 `TEMPORARY' keyword in the following comment is executed only by servers from MySQL 3.23.02 or higher: CREATE /*!32302 TEMPORARY */ TABLE t (a INT); The comment syntax just described applies to how the *Note `mysqld': mysqld. server parses SQL statements. The *Note `mysql': 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. The use of short-form *Note `mysql': mysql. commands such as `\C' within multi-line `/* ... */' comments is not supported.  File: manual.info, Node: globalization, Next: data-types, Prev: language-structure, Up: Top 10 Globalization **************** * Menu: * charset:: Character Set Support * error-message-language:: Setting the Error Message Language * adding-character-set:: Adding a Character Set * adding-collation:: Adding a Collation to a Character Set * charset-configuration:: Character Set Configuration * time-zone-support:: MySQL Server Time Zone Support * locale-support:: MySQL Server Locale Support This chapter covers issues of globalization, which includes internationalization (MySQL's capabilities for adapting to local use) and localization (selecting particular local conventions): * MySQL support for character sets in SQL statements. * How to configure the server to support different character sets. * Selecting the language for error messages. * How to set the server's time zone and enable per-connection time zone support. * Selecting the locale for day and month names.  File: manual.info, Node: charset, Next: error-message-language, Prev: globalization, Up: globalization 10.1 Character Set Support ========================== * Menu: * charset-general:: Character Sets and Collations in General * charset-mysql:: Character Sets and Collations in MySQL * charset-syntax:: Specifying Character Sets and Collations * charset-connection:: Connection Character Sets and Collations * charset-applications:: Configuring the Character Set and Collation for Applications * charset-errors:: Character Set for Error Messages * charset-collations:: Collation Issues * charset-repertoire:: String Repertoire * charset-operations:: Operations Affected by Character Set Support * charset-unicode:: Unicode Support * charset-metadata:: UTF-8 for Metadata * charset-conversion:: Column Character Set Conversion * charset-charsets:: Character Sets and Collations That MySQL Supports 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', *Note `NDBCLUSTER': mysql-cluster, 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. 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 *Note charset-applications::, and *Note charset-connection::.  File: manual.info, Node: charset-general, Next: charset-mysql, Prev: charset, Up: charset 10.1.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. In these respects, MySQL is far ahead of most other database management systems. However, to use these features effectively, you need to know what character sets and collations are available, how to change the defaults, and how they affect the behavior of string operators and functions.  File: manual.info, Node: charset-mysql, Next: charset-syntax, Prev: charset-general, Up: charset 10.1.2 Character Sets and Collations in MySQL --------------------------------------------- The MySQL server can support multiple character sets. To list the available character sets, use the *Note `SHOW CHARACTER SET': show-character-set. statement. A partial listing follows. For more complete information, see *Note charset-charsets::. 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 | ... Any given character set always has at least one collation. It may have several collations. To list the collations for a character set, use the *Note `SHOW COLLATION': show-collation. statement. For example, to see the collations for the `latin1' (cp1252 West European) character set, use this statement to find those collation names that begin with `latin1': mysql> SHOW COLLATION LIKE 'latin1%'; +---------------------+---------+----+---------+----------+---------+ | Collation | Charset | Id | Default | Compiled | Sortlen | +---------------------+---------+----+---------+----------+---------+ | latin1_german1_ci | latin1 | 5 | | | 0 | | latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 | | latin1_danish_ci | latin1 | 15 | | | 0 | | latin1_german2_ci | latin1 | 31 | | Yes | 2 | | latin1_bin | latin1 | 47 | | Yes | 1 | | latin1_general_ci | latin1 | 48 | | | 0 | | latin1_general_cs | latin1 | 49 | | | 0 | | latin1_spanish_ci | latin1 | 94 | | | 0 | +---------------------+---------+----+---------+----------+---------+ The `latin1' collations have the following meanings. This table lists `latin1' character set collations, as described in the example above, and provides the meaning of each collation. Collation Meaning `latin1_german1_ci' German DIN-1 `latin1_swedish_ci' Swedish/Finnish `latin1_danish_ci' Danish/Norwegian `latin1_german2_ci' German DIN-2 `latin1_bin' Binary according to `latin1' encoding `latin1_general_ci' Multilingual (Western European) `latin1_general_cs' Multilingual (ISO Western European), case sensitive `latin1_spanish_ci' Modern Spanish Collations have these general characteristics: * Two different character sets cannot have the same collation. * Each character set has one collation that is the _default collation_. For example, the default collation for `latin1' is `latin1_swedish_ci'. The output for *Note `SHOW CHARACTER SET': show-character-set. indicates which collation is the default for each displayed character set. * There is a convention for collation names: They start with the name of the character set with which they are associated, they usually include a language name, and they end with `_ci' (case insensitive), `_cs' (case sensitive), or `_bin' (binary). 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. Collation-Charts.Org (http://www.collation-charts.org/) is a useful site for information that shows how one collation compares to another.  File: manual.info, Node: charset-syntax, Next: charset-connection, Prev: charset-mysql, Up: charset 10.1.3 Specifying Character Sets and Collations ----------------------------------------------- * Menu: * charset-server:: Server Character Set and Collation * charset-database:: Database Character Set and Collation * charset-table:: Table Character Set and Collation * charset-column:: Column Character Set and Collation * charset-literal:: Character String Literal Character Set and Collation * charset-national:: National Character Set * charset-examples:: Examples of Character Set and Collation Assignment * charset-compatibility:: Compatibility with Other DBMSs 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 *Note charset-connection::.  File: manual.info, Node: charset-server, Next: charset-database, Prev: charset-syntax, Up: charset-syntax 10.1.3.1 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 *Note `mysqld': 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: shell> mysqld shell> mysqld --character-set-server=latin1 shell> mysqld --character-set-server=latin1 \ --collation-server=latin1_swedish_ci One way to change the settings is by recompiling. If you want to change the default server character set and collation when building from sources, use: `--with-charset' and `--with-collation' as arguments for `configure'. For example: shell> ./configure --with-charset=latin1 Or: shell> ./configure --with-charset=latin1 \ --with-collation=latin1_german1_ci Both *Note `mysqld': mysqld. and `configure' 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 *Note `CREATE DATABASE': 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.  File: manual.info, Node: charset-database, Next: charset-table, Prev: charset-server, Up: charset-syntax 10.1.3.2 Database Character Set and Collation ............................................. Every database has a database character set and a database collation. The *Note `CREATE DATABASE': create-database. and *Note `ALTER DATABASE': 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 X' and `COLLATE Y' are specified, character set X and collation Y are used. * If `CHARACTER SET X' is specified without `COLLATE', character set X and its default collation are used. To see the default collation for each character set, use the *Note `SHOW COLLATION': show-collation. statement. * If `COLLATE Y' is specified without `CHARACTER SET', the character set associated with Y and collation Y are used. * Otherwise, the server character set and server collation are used. The database character set and collation are used as default values for table definitions if the table character set and collation are not specified in *Note `CREATE TABLE': create-table. statements. The database character set also is used by *Note `LOAD DATA INFILE': load-data. The character set and collation have no other purposes. 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'.  File: manual.info, Node: charset-table, Next: charset-column, Prev: charset-database, Up: charset-syntax 10.1.3.3 Table Character Set and Collation .......................................... Every table has a table character set and a table collation. The *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': 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 X' and `COLLATE Y' are specified, character set X and collation Y are used. * If `CHARACTER SET X' is specified without `COLLATE', character set X and its default collation are used. To see the default collation for each character set, use the *Note `SHOW COLLATION': show-collation. statement. * If `COLLATE Y' is specified without `CHARACTER SET', the character set associated with Y and collation Y are used. * Otherwise, 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.  File: manual.info, Node: charset-column, Next: charset-literal, Prev: charset-table, Up: charset-syntax 10.1.3.4 Column Character Set and Collation ........................................... Every `character' column (that is, a column of type *Note `CHAR': char, *Note `VARCHAR': char, or *Note `TEXT': blob.) has a column character set and a column collation. Column definition syntax for *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': 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 *Note `ENUM': enum. and *Note `SET': 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 X' and `COLLATE Y' are specified, character set X and collation Y 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 X' is specified without `COLLATE', character set X 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 *Note `SHOW COLLATION': show-collation. statement. * If `COLLATE Y' is specified without `CHARACTER SET', the character set associated with Y and collation Y 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, 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 are 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 *Note `ALTER TABLE': 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.  File: manual.info, Node: charset-literal, Next: charset-national, Prev: charset-column, Up: charset-syntax 10.1.3.5 Character String Literal Character Set and Collation ............................................................. Every character string literal has a character set and a collation. A character string literal may have an optional character set introducer and `COLLATE' clause: [_CHARSET_NAME]'STRING' [COLLATE COLLATION_NAME] Examples: SELECT 'STRING'; SELECT _latin1'STRING'; SELECT _latin1'STRING' COLLATE latin1_danish_ci; For the simple statement `SELECT 'STRING'', the string has the character set and collation defined by the `character_set_connection' and `collation_connection' system variables. The `_CHARSET_NAME' expression is formally called an _introducer_. It tells the parser, `the string that is about to follow uses character set X.' Because this has confused people in the past, we emphasize that an introducer does not change the string to the introducer character set like `CONVERT()' would do. It does not change the string's value, although padding may occur. The introducer is just a signal. An introducer is also legal before standard hex literal and numeric hex literal notation (`x'LITERAL'' and `0xNNNN'), or before bit-field literal notation (`b'LITERAL'' and `0bNNNN'). Examples: SELECT _latin1 x'AABBCC'; SELECT _latin1 0xAABBCC; SELECT _latin1 b'1100011'; SELECT _latin1 0b1100011; MySQL determines a literal's character set and collation in the following manner: * If both _X and `COLLATE Y' are specified, character set X and collation Y are used. * If _X is specified but `COLLATE' is not specified, character set X and its default collation are used. To see the default collation for each character set, use the *Note `SHOW COLLATION': show-collation. statement. * Otherwise, the character set and collation given by the `character_set_connection' and `collation_connection' system variables are used. Examples: * A string with `latin1' character set and `latin1_german1_ci' collation: SELECT _latin1'Mu"ller' COLLATE latin1_german1_ci; * A string with `latin1' character set and its default collation (that is, `latin1_swedish_ci'): SELECT _latin1'Mu"ller'; * A string with the connection default character set and collation: SELECT 'Mu"ller'; Character set introducers and the `COLLATE' clause are implemented according to standard SQL specifications. An introducer indicates the character set for the following string, but does not change now 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 *Note 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; Query OK, 0 rows affected (0.01 sec) mysql> SELECT HEX('a`\n'), HEX(_sjis'a`\n'); +------------+-----------------+ | HEX('a`\n') | HEX(_sjis'a`\n') | +------------+-----------------+ | E00A | E00A | +------------+-----------------+ 1 row in set (0.00 sec) Here, ``a`'' (hex 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 (hex value `0A'). This happens even for the second string. That is, the introducer of `_sjis' does not affect the parser's escape processing. Example 2: mysql> SET NAMES sjis; Query OK, 0 rows affected (0.00 sec) mysql> SELECT HEX('a`\n'), HEX(_latin1'a`\n'); +------------+-------------------+ | HEX('a`\n') | HEX(_latin1'a`\n') | +------------+-------------------+ | E05C6E | E05C6E | +------------+-------------------+ 1 row in set (0.04 sec) Here, `character_set_connection' is `sjis', a character set in which the sequence of ``a`'' followed by ``\'' (hex values `05' and `5C') is a valid multi-byte 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'' (hex value `6E') is not interpreted as part of an escape sequence. This is true even for the second string; the introducer of `_latin1' does not affect escape processing.  File: manual.info, Node: charset-national, Next: charset-examples, Prev: charset-literal, Up: charset-syntax 10.1.3.6 National Character Set ............................... Standard SQL defines *Note `NCHAR': char. or *Note `NATIONAL CHAR': char. as a way to indicate that a *Note `CHAR': char. column should use some predefined character set. MySQL 5.1 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) 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'; For information on upgrading character sets to MySQL 5.1 from versions prior to 4.1, see the `MySQL 3.23, 4.0, 4.1 Reference Manual'.  File: manual.info, Node: charset-examples, Next: charset-compatibility, Prev: charset-national, Up: charset-syntax 10.1.3.7 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'.  File: manual.info, Node: charset-compatibility, Prev: charset-examples, Up: charset-syntax 10.1.3.8 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);  File: manual.info, Node: charset-connection, Next: charset-applications, Prev: charset-syntax, Up: charset 10.1.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 such as `_latin1' or `_utf8'). `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 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. 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, `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 *Note `SELECT': 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' cannot be used as a client character set, which means that it does not work for `SET NAMES' or `SET CHARACTER SET'. The MySQL client programs `mysql', `mysqladmin', `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 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 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. With the *Note `mysql': 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 *Note `mysql': 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 *Note `mysql': mysql.: [mysql] default-character-set=koi8r If you are using the *Note `mysql': 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 *Note `mysql': 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 *Note `SELECT': 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; 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 *Note charset-applications::. For more information about character sets and error messages, see *Note charset-errors::.  File: manual.info, Node: charset-applications, Next: charset-errors, Prev: charset-connection, Up: charset 10.1.5 Configuring the Character Set and Collation for Applications ------------------------------------------------------------------- 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 *Note `CREATE DATABASE': 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 *Note `mysql': 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 *Note `mysql': 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 *Note 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 *Note 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 `--with-charset' and `--with-collation' options: shell> ./configure --with-charset=utf8 --with-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 *Note `mysql': 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 `' tag within your `' element:  File: manual.info, Node: charset-errors, Next: charset-collations, Prev: charset-applications, Up: charset 10.1.6 Character Set for Error Messages --------------------------------------- This section describes how the 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 *Note error-message-language::. In MySQL 5.1, the server constructs error messages and returns them to clients as follows: * The message template has the character set associated with the error message language. For example, English, Korean, and Russian messages use `latin1', `euckr', and `koi8r', respectively. * Parameters in the message template are replaced with values that apply to a specific error occurrence. These parameters use their own character set. Identifiers such as table or column names use UTF-8. Data values retain their character set. For example, in the following duplicate-key message, `'XXX'' has the character set of the table column associated with key 1: Duplicate entry 'XXX' for key1 The preceding method of error-message construction can result in messages that contain a mix of character sets unless all items involved contain only ASCII characters. This issue is resolved in MySQL 5.5, in which error messages are constructed internally within the server using UTF-8 and returned to the client in the character set specified by the `character_set_results' system variable.  File: manual.info, Node: charset-collations, Next: charset-repertoire, Prev: charset-errors, Up: charset 10.1.7 Collation Issues ----------------------- * Menu: * charset-collation-names:: Collation Names * charset-collate:: Using `COLLATE' in SQL Statements * charset-collate-precedence:: `COLLATE' Clause Precedence * charset-collation-charset:: Collations Must Be for the Right Character Set * charset-collation-expressions:: Collation of Expressions * charset-binary-collations:: The `_bin' and `binary' Collations * charset-binary-op:: The `BINARY' Operator * charset-collation-effect:: Examples of the Effect of Collation * charset-collation-information-schema:: Collation and `INFORMATION_SCHEMA' Searches The following sections discuss various aspects of character set collations.  File: manual.info, Node: charset-collation-names, Next: charset-collate, Prev: charset-collations, Up: charset-collations 10.1.7.1 Collation Names ........................ MySQL collation names follow these rules: * A name ending in `_ci' indicates a case-insensitive collation. * A name ending in `_cs' indicates a case-sensitive collation. * A name ending in `_bin' indicates a binary collation. Character comparisons are based on character binary code values.  File: manual.info, Node: charset-collate, Next: charset-collate-precedence, Prev: charset-collation-names, Up: charset-collations 10.1.7.2 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;  File: manual.info, Node: charset-collate-precedence, Next: charset-collation-charset, Prev: charset-collate, Up: charset-collations 10.1.7.3 `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)  File: manual.info, Node: charset-collation-charset, Next: charset-collation-expressions, Prev: charset-collate-precedence, Up: charset-collations 10.1.7.4 Collations Must Be for the Right Character Set ....................................................... 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'  File: manual.info, Node: charset-collation-expressions, Next: charset-binary-collations, Prev: charset-collation-charset, Up: charset-collations 10.1.7.5 Collation of 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 `charset_name': 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? Standard SQL resolves such questions using what used to be called `coercibility' rules. 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. * `NULL' or an expression that is derived from `NULL' has a coercibility of 5. 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 SQL standard document 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. Examples: This table lists comparisons and the collation used for each comparison. Comparison Collation Used `column1 = 'A'' Use collation of `column1' `column1 = 'A' COLLATE x' Use collation of `'A' COLLATE x' `column1 COLLATE x = 'A' COLLATE y' Error The `COERCIBILITY()' function can be used to determine the coercibility of a string expression: mysql> SELECT COERCIBILITY('A' COLLATE latin1_swedish_ci); -> 0 mysql> SELECT COERCIBILITY(VERSION()); -> 3 mysql> SELECT COERCIBILITY('A'); -> 4 See *Note information-functions::. 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 binary string for which the character set and collation are `binary'. See *Note type-conversion::.  File: manual.info, Node: charset-binary-collations, Next: charset-binary-op, Prev: charset-collation-expressions, Up: charset-collations 10.1.7.6 The `_bin' and `binary' Collations ........................................... This section describes how `_bin' collations for nonbinary strings differ from the `binary' `collation' for binary strings. Nonbinary strings (as stored in the *Note `CHAR': char, *Note `VARCHAR': char, and *Note `TEXT': blob. data types) have a character set and collation. A given character set can have several collations, each of which defines a particular sorting and comparison 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, `latin1' and `utf8' have binary collations named `latin1_bin' and `utf8_bin'. Binary strings (as stored in the *Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, and *Note `BLOB': blob. data types) have no character set or collation in the sense that nonbinary strings do. (Applied to a binary string, the `CHARSET()' and `COLLATION()' functions both return a value of `binary'.) Binary strings are sequences of bytes and the numeric values of those bytes determine sort order. The `_bin' collations differ from the `binary' collation in several respects. *The unit for sorting and comparison.* Binary strings are sequences of bytes. Sorting and comparison is always based on numeric byte values. Nonbinary strings are sequences of characters, which might be multi-byte. Collations for nonbinary strings define an ordering of the character values for sorting and comparison. For the `_bin' collation, this ordering is based solely on binary code values of the characters (which is similar to ordering for binary strings except that a `_bin' collation must take into account that a character might contain multiple bytes). For other collations, character ordering might take additional factors such as lettercase into account. *Character set conversion.* A nonbinary string has a character set and is 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 *Note `INSERT': insert. or *Note `UPDATE': 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 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; Query OK, 0 rows affected (0.02 sec) mysql> SELECT LOWER('aA'), UPPER('zZ'); +-------------+-------------+ | LOWER('aA') | UPPER('zZ') | +-------------+-------------+ | aa | ZZ | +-------------+-------------+ 1 row in set (0.13 sec) 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; Query OK, 0 rows affected (0.00 sec) mysql> SELECT LOWER('aA'), LOWER(CONVERT('aA' USING latin1)); +-------------+-----------------------------------+ | LOWER('aA') | LOWER(CONVERT('aA' USING latin1)) | +-------------+-----------------------------------+ | aA | aa | +-------------+-----------------------------------+ 1 row in set (0.00 sec) *Trailing space handling in comparisons.* Nonbinary strings have `PADSPACE' behavior for all collations, including `_bin' collations. Trailing spaces are insignificant in comparisons: mysql> SET NAMES utf8 COLLATE utf8_bin; Query OK, 0 rows affected (0.00 sec) mysql> SELECT 'a ' = 'a'; +------------+ | 'a ' = 'a' | +------------+ | 1 | +------------+ 1 row in set (0.00 sec) For binary strings, all characters are significant in comparisons, including trailing spaces: mysql> SET NAMES binary; Query OK, 0 rows affected (0.00 sec) mysql> SELECT 'a ' = 'a'; +------------+ | 'a ' = 'a' | +------------+ | 0 | +------------+ 1 row in set (0.00 sec) *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) -> ); Query OK, 0 rows affected (0.09 sec) mysql> INSERT INTO t1 VALUES ('a','a'); Query OK, 1 row affected (0.01 sec) mysql> SELECT HEX(a), HEX(b) FROM t1; +--------+----------------------+ | HEX(a) | HEX(b) | +--------+----------------------+ | 61 | 61000000000000000000 | +--------+----------------------+ 1 row in set (0.04 sec)  File: manual.info, Node: charset-binary-op, Next: charset-collation-effect, Prev: charset-binary-collations, Up: charset-collations 10.1.7.7 The `BINARY' Operator .............................. The `BINARY' operator casts the string following it to a binary string. This is an easy way to force a comparison to be done byte by byte rather than character by character. `BINARY' also causes trailing spaces 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 `BINARY STR' is shorthand for `CAST(STR AS BINARY)'. The `BINARY' attribute in character column definitions has a different effect. A character column defined with the `BINARY' attribute is assigned the binary collation of the column character set. Every character set has a binary collation. For example, the binary collation for the `latin1' character set is `latin1_bin', so if the table default character set is `latin1', these two column definitions are equivalent: CHAR(10) BINARY CHAR(10) CHARACTER SET latin1 COLLATE latin1_bin The effect of `BINARY' as a column attribute differs from its effect prior to MySQL 4.1. Formerly, `BINARY' resulted in a column that was treated as a binary string. A binary string is a string of bytes that has no character set or collation, which differs from a nonbinary character string that has a binary collation. For both types of strings, comparisons are based on the numeric values of the string unit, but for nonbinary strings the unit is the character and some character sets support multi-byte characters. *Note binary-varbinary::. The use of `CHARACTER SET binary' in the definition of a *Note `CHAR': char, *Note `VARCHAR': char, or *Note `TEXT': blob. column causes the column to be treated as a binary 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  File: manual.info, Node: charset-collation-effect, Next: charset-collation-information-schema, Prev: charset-binary-op, Up: charset-collations 10.1.7.8 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. This table illustrates an example of the effect of collation, as described in the preceding text. The table shows the resulting order of values for three collations (`latin1_swedish_ci', `latin1_german1_ci', `latin1_german2_ci') when using `ORDER BY'. `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 *Note `SELECT': select. using the Swedish/Finnish collating rule, which says that U-umlaut sorts with Y. * The second column shows the result of the *Note `SELECT': select. using the German DIN-1 rule, which says that U-umlaut sorts with U. * The third column shows the result of the *Note `SELECT': 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).  File: manual.info, Node: charset-collation-information-schema, Prev: charset-collation-effect, Up: charset-collations 10.1.7.9 Collation and `INFORMATION_SCHEMA' Searches .................................................... String columns in `INFORMATION_SCHEMA' tables have a collation of `utf8_general_ci', which is case insensitive. However, searches in `INFORMATION_SCHEMA' string columns are also affected by file system case sensitivity. For values that correspond to objects that are represented in the file system, such as names of databases and tables, searches may be case sensitive if the file system is case sensitive. This section describes how to work around this issue 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 | +-------------+ 1 row in set (0.01 sec) mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA -> WHERE SCHEMA_NAME = 'TEST'; Empty set (0.00 sec) On Windows or Mac OS X where file systems are not case sensitive, comparisons match both `'test'' and `'TEST'': mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA -> WHERE SCHEMA_NAME = 'test'; +-------------+ | SCHEMA_NAME | +-------------+ | test | +-------------+ 1 row in set (0.00 sec) mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA -> WHERE SCHEMA_NAME = 'TEST'; +-------------+ | SCHEMA_NAME | +-------------+ | TEST | +-------------+ 1 row in set (0.00 sec) The value of the `lower_case_table_names' system variable makes no difference in this context. This behavior occurs because the `utf8_general_ci' collation is not used for `INFORMATION_SCHEMA' queries when searching the file system for database objects. It is a result of optimizations implemented for `INFORMATION_SCHEMA' searches in MySQL 5.1.21 and thus does not occur prior to 5.1.21. For information about these optimizations, see *Note information-schema-optimization::. 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 and is 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 | +--------------------+ 1 row in set (0.00 sec) mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA -> WHERE SCHEMA_NAME = 'INFORMATION_SCHEMA'; +--------------------+ | SCHEMA_NAME | +--------------------+ | information_schema | +--------------------+ 1 row in set (0.00 sec) 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 (*Note 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 | +-------------+ 1 row in set (0.00 sec) mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA -> WHERE SCHEMA_NAME COLLATE utf8_general_ci = 'TEST'; | SCHEMA_NAME | +-------------+ | test | +-------------+ 1 row in set (0.00 sec) 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: 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' The first of those comparisons (with `utf8_bin') is case sensitive; the others are not.  File: manual.info, Node: charset-repertoire, Next: charset-operations, Prev: charset-collations, Up: charset 10.1.8 String Repertoire ------------------------ The _repertoire_ of a character set is the collection of characters in the set. As of MySQL 5.1.21, 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+FFFF'. 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 string constants depends on string content: 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'. * Columns having the `ascii' character set have `ASCII' repertoire because of their 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 0x0041, _ucs2 0x0042) CONCAT(_ucs2 0x0041, _ucs2 0x00C2) 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.  File: manual.info, Node: charset-operations, Next: charset-unicode, Prev: charset-repertoire, Up: charset 10.1.9 Operations Affected by Character Set Support --------------------------------------------------- * Menu: * charset-result:: Result Strings * charset-convert:: `CONVERT()' and `CAST()' * charset-show:: `SHOW' Statements and `INFORMATION_SCHEMA' This section describes operations that take character set information into account.  File: manual.info, Node: charset-result, Next: charset-convert, Prev: charset-operations, Up: charset-operations 10.1.9.1 Result Strings ....................... 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 whose character string and collation are the same as that of 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 no character set or collation. This can be checked by using the `CHARSET()' and `COLLATION()' functions, both of which return `binary' to indicate that their argument is a binary string: 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 X' occurs, use X. * If explicit `COLLATE X' and `COLLATE Y' occur, raise an error. * Otherwise, if all collations are X, use X. * 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 *Note `UNION': 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. This applies only to `CAST()', `CONV()', `FORMAT()', `HEX()', and `SPACE()'. If you are uncertain about the character set or collation of the result returned by a string function, you can 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 | +----------------+-----------------+-------------------+  File: manual.info, Node: charset-convert, Next: charset-show, Prev: charset-result, Up: charset-operations 10.1.9.2 `CONVERT()' and `CAST()' ................................. `CONVERT()' provides a way to convert data between different character sets. The syntax is: 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 utf8table (utf8column) SELECT CONVERT(latin1field USING utf8) FROM latin1table; `CONVERT(... USING ...)' is implemented according to the standard SQL specification. You may also use `CAST()' to convert a string to a different character set. The syntax is: CAST(CHARACTER_STRING AS CHARACTER_DATA_TYPE CHARACTER SET CHARSET_NAME) Example: SELECT CAST(_latin1'test' AS CHAR CHARACTER SET utf8); If you use `CAST()' without specifying `CHARACTER SET', the resulting character set and collation are defined by the `character_set_connection' and `collation_connection' system variables. If you use `CAST()' with `CHARACTER SET X', the resulting character set and collation are `X' and the default collation of `X'. You may not use a `COLLATE' clause inside a `CONVERT()' or `CAST()' call, but you may use it outside. For example, `CAST(... COLLATE ...)' is illegal, but `CAST(...) COLLATE ...' is legal: SELECT CAST(_latin1'test' AS CHAR CHARACTER SET utf8) COLLATE utf8_bin;  File: manual.info, Node: charset-show, Prev: charset-convert, Up: charset-operations 10.1.9.3 `SHOW' Statements and `INFORMATION_SCHEMA' ................................................... Several *Note `SHOW': show. statements provide additional character set information. These include *Note `SHOW CHARACTER SET': show-character-set, *Note `SHOW COLLATION': show-collation, *Note `SHOW CREATE DATABASE': show-create-database, *Note `SHOW CREATE TABLE': show-create-table. and *Note `SHOW COLUMNS': show-columns. These statements are described here briefly. For more information, see *Note show::. `INFORMATION_SCHEMA' has several tables that contain information similar to that displayed by the *Note `SHOW': show. statements. For example, the *Note `CHARACTER_SETS': character-sets-table. and *Note `COLLATIONS': collations-table. tables contain the information displayed by *Note `SHOW CHARACTER SET': show-character-set. and *Note `SHOW COLLATION': show-collation. See *Note information-schema::. The *Note `SHOW CHARACTER SET': show-character-set. statement shows all available character sets. It takes an optional `LIKE' 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 | +---------+-----------------------------+-------------------+--------+ The output from *Note `SHOW COLLATION': show-collation. includes all available character sets. It takes an optional `LIKE' clause that indicates which collation names to match. For example: mysql> SHOW COLLATION LIKE 'latin1%'; +-------------------+---------+----+---------+----------+---------+ | Collation | Charset | Id | Default | Compiled | Sortlen | +-------------------+---------+----+---------+----------+---------+ | latin1_german1_ci | latin1 | 5 | | | 0 | | latin1_swedish_ci | latin1 | 8 | Yes | Yes | 0 | | latin1_danish_ci | latin1 | 15 | | | 0 | | latin1_german2_ci | latin1 | 31 | | Yes | 2 | | latin1_bin | latin1 | 47 | | Yes | 0 | | latin1_general_ci | latin1 | 48 | | | 0 | | latin1_general_cs | latin1 | 49 | | | 0 | | latin1_spanish_ci | latin1 | 94 | | | 0 | +-------------------+---------+----+---------+----------+---------+ *Note `SHOW CREATE DATABASE': show-create-database. displays the *Note `CREATE DATABASE': create-database. statement that creates a given database: mysql> SHOW CREATE DATABASE test; +----------+-----------------------------------------------------------------+ | Database | Create Database | +----------+-----------------------------------------------------------------+ | test | CREATE DATABASE `test` /*!40100 DEFAULT CHARACTER SET latin1 */ | +----------+-----------------------------------------------------------------+ If no `COLLATE' clause is shown, the default collation for the character set applies. *Note `SHOW CREATE TABLE': show-create-table. is similar, but displays the *Note `CREATE TABLE': create-table. statement to create a given table. The column definitions indicate any character set specifications, and the table options include character set information. The *Note `SHOW COLUMNS': show-columns. statement displays the collations of a table's columns when invoked as *Note `SHOW FULL COLUMNS': show-columns. Columns with *Note `CHAR': char, *Note `VARCHAR': char, or *Note `TEXT': blob. data types have collations. Numeric and other noncharacter types have no collation (indicated by `NULL' as the `Collation' value). For example: mysql> SHOW FULL COLUMNS FROM person\G *************************** 1. row *************************** Field: id Type: smallint(5) unsigned Collation: NULL Null: NO Key: PRI Default: NULL Extra: auto_increment Privileges: select,insert,update,references Comment: *************************** 2. row *************************** Field: name Type: char(60) Collation: latin1_swedish_ci Null: NO Key: Default: Extra: Privileges: select,insert,update,references Comment: The character set is not part of the display but is implied by the collation name.  File: manual.info, Node: charset-unicode, Next: charset-metadata, Prev: charset-operations, Up: charset 10.1.10 Unicode Support ----------------------- * Menu: * charset-unicode-ucs2:: The `ucs2' Character Set (UCS-2 Unicode Encoding) * charset-unicode-utf8:: The `utf8' Character Set (3-Byte UTF-8 Unicode Encoding) MySQL 5.1 supports two character sets for storing Unicode data: * `ucs2', the UCS-2 encoding of the Unicode character set using 16 bits per character. * `utf8', a UTF-8 encoding of the Unicode character set using one to three bytes per character. These two character sets support the characters from the Basic Multilingual Plane (BMP) of Unicode Version 3.0. BMP characters have these characteristics: * Their code values are between 0 and 65535 (or `U+0000' .. `U+FFFF'). * They can be encoded with a fixed 16-bit word, as in `ucs2'. * They can be encoded with 8, 16, or 24 bits, as in `utf8'. * They are sufficient for almost all characters in major languages. The `ucs2' and `utf8' character sets do not support supplementary characters that lie outside the BMP. Characters outside the BMP compare as REPLACEMENT CHARACTER and convert to `'?'' when converted to a Unicode character set. A similar set of collations is available for each Unicode character set. For example, each has a Danish collation, the names of which are `ucs2_danish_ci' and `utf8_danish_ci'. All Unicode collations are listed at *Note charset-unicode-sets::. The MySQL implementation of UCS-2 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. MySQL uses no BOM for UTF-8 values. Client applications that need to communicate with the server using Unicode should set the client character set accordingly; for example, by issuing a `SET NAMES 'utf8'' statement. `ucs2' cannot be used as a client character set, which means that it does not work for `SET NAMES' or `SET CHARACTER SET'. (See *Note charset-connection::.) The following sections provide additional detail on the Unicode character sets in MySQL.  File: manual.info, Node: charset-unicode-ucs2, Next: charset-unicode-utf8, Prev: charset-unicode, Up: charset-unicode 10.1.10.1 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 Home Page (http://www.unicode.org/). In MySQL, the `ucs2' character set is a fixed-length 16-bit encoding for Unicode BMP characters.  File: manual.info, Node: charset-unicode-utf8, Prev: charset-unicode-ucs2, Up: charset-unicode 10.1.10.2 The `utf8' Character Set (3-Byte UTF-8 Unicode Encoding) .................................................................. UTF-8 (Unicode Transformation Format with 8-bit units) is an alternative way to store Unicode data. It is implemented according to RFC 3629, which describes encoding sequences that take from one to four bytes. Currently, MySQL support for UTF-8 does not include 4-byte sequences. (An older standard for UTF-8 encoding, RFC 2279, describes UTF-8 sequences that take from one to six bytes. RFC 3629 renders RFC 2279 obsolete; for this reason, sequences with five and six bytes are no longer used.) 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 sequences. *Tip*: To save space with UTF-8, use *Note `VARCHAR': char. instead of *Note `CHAR': char. Otherwise, MySQL must reserve three bytes for each character in a `CHAR CHARACTER SET utf8' column because that is the maximum possible length. For example, MySQL must reserve 30 bytes for a `CHAR(10) CHARACTER SET utf8' column.  File: manual.info, Node: charset-metadata, Next: charset-conversion, Prev: charset-unicode, Up: charset 10.1.11 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 *Note `SHOW': 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 *Note `SHOW': show. statements nor *Note `SELECT': 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 *Note `DESCRIBE': 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 *Note 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 SQL standard document 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 *Note charset-collation-expressions::.  File: manual.info, Node: charset-conversion, Next: charset-charsets, Prev: charset-metadata, Up: charset 10.1.12 Column Character Set Conversion --------------------------------------- To convert a binary or nonbinary string column to use a particular character set, use *Note `ALTER TABLE': alter-table. For successful conversion to occur, one of the following conditions must apply: * If the column has a binary data type (*Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, *Note `BLOB': 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 (*Note `CHAR': char, *Note `VARCHAR': char, *Note `TEXT': blob.), 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 *Note `INSERT': insert. or *Note `UPDATE': 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 *Note `ALTER TABLE': alter-table. For example, if you specified `NOT NULL' and an explicit `DEFAULT' value, you should also provide them in the *Note `ALTER TABLE': alter-table. statement. Otherwise, the resulting column definition will not include those attributes.  File: manual.info, Node: charset-charsets, Prev: charset-conversion, Up: charset 10.1.13 Character Sets and Collations That MySQL Supports --------------------------------------------------------- * Menu: * charset-unicode-sets:: Unicode Character Sets * charset-we-sets:: West European Character Sets * charset-ce-sets:: Central European Character Sets * charset-se-me-sets:: South European and Middle East Character Sets * charset-baltic-sets:: Baltic Character Sets * charset-cyrillic-sets:: Cyrillic Character Sets * charset-asian-sets:: Asian Character Sets MySQL supports 70+ collations for 30+ character sets. 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. You can always list the available character sets and their default collations with the *Note `SHOW CHARACTER SET': show-character-set. statement: mysql> SHOW CHARACTER SET; +----------+-----------------------------+---------------------+ | Charset | Description | Default collation | +----------+-----------------------------+---------------------+ | big5 | Big5 Traditional Chinese | big5_chinese_ci | | dec8 | DEC West European | dec8_swedish_ci | | cp850 | DOS West European | cp850_general_ci | | hp8 | HP West European | hp8_english_ci | | koi8r | KOI8-R Relcom Russian | koi8r_general_ci | | latin1 | cp1252 West European | latin1_swedish_ci | | latin2 | ISO 8859-2 Central European | latin2_general_ci | | swe7 | 7bit Swedish | swe7_swedish_ci | | ascii | US ASCII | ascii_general_ci | | ujis | EUC-JP Japanese | ujis_japanese_ci | | sjis | Shift-JIS Japanese | sjis_japanese_ci | | hebrew | ISO 8859-8 Hebrew | hebrew_general_ci | | tis620 | TIS620 Thai | tis620_thai_ci | | euckr | EUC-KR Korean | euckr_korean_ci | | koi8u | KOI8-U Ukrainian | koi8u_general_ci | | gb2312 | GB2312 Simplified Chinese | gb2312_chinese_ci | | greek | ISO 8859-7 Greek | greek_general_ci | | cp1250 | Windows Central European | cp1250_general_ci | | gbk | GBK Simplified Chinese | gbk_chinese_ci | | latin5 | ISO 8859-9 Turkish | latin5_turkish_ci | | armscii8 | ARMSCII-8 Armenian | armscii8_general_ci | | utf8 | UTF-8 Unicode | utf8_general_ci | | ucs2 | UCS-2 Unicode | ucs2_general_ci | | cp866 | DOS Russian | cp866_general_ci | | keybcs2 | DOS Kamenicky Czech-Slovak | keybcs2_general_ci | | macce | Mac Central European | macce_general_ci | | macroman | Mac West European | macroman_general_ci | | cp852 | DOS Central European | cp852_general_ci | | latin7 | ISO 8859-13 Baltic | latin7_general_ci | | cp1251 | Windows Cyrillic | cp1251_general_ci | | cp1256 | Windows Arabic | cp1256_general_ci | | cp1257 | Windows Baltic | cp1257_general_ci | | binary | Binary pseudo charset | binary | | geostd8 | GEOSTD8 Georgian | geostd8_general_ci | | cp932 | SJIS for Windows Japanese | cp932_japanese_ci | | eucjpms | UJIS for Windows Japanese | eucjpms_japanese_ci | +----------+-----------------------------+---------------------+ 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. Collation-Charts.Org (http://www.collation-charts.org/) is a useful site for information that shows how one collation compares to another.  File: manual.info, Node: charset-unicode-sets, Next: charset-we-sets, Prev: charset-charsets, Up: charset-charsets 10.1.13.1 Unicode Character Sets ................................ MySQL 5.1 has two Unicode character sets: * `ucs2', the UCS-2 encoding of the Unicode character set using 16 bits per character. * `utf8', a UTF-8 encoding of the Unicode character set using one to three bytes per character. You can store text in about 650 languages using these character sets. This section lists the collations available for each Unicode character set and describes their differentiating properties. For general information about the character sets, see *Note charset-unicode::. A similar set of collations is available for each Unicode character set. These are shown in the following list, where XXX represents the character set name. For example, `XXX_danish_ci' represents the Danish collations, the specific names of which are `ucs2_danish_ci' and `utf8_danish_ci'. * `XXX_bin' * `XXX_czech_ci' * `XXX_danish_ci' * `XXX_esperanto_ci' * `XXX_estonian_ci' * `XXX_general_ci' (default) * `XXX_general_mysql500_ci' * `XXX_hungarian_ci' * `XXX_icelandic_ci' * `XXX_latvian_ci' * `XXX_lithuanian_ci' * `XXX_persian_ci' * `XXX_polish_ci' * `XXX_roman_ci' * `XXX_romanian_ci' * `XXX_slovak_ci' * `XXX_slovenian_ci' * `XXX_spanish_ci' * `XXX_spanish2_ci' * `XXX_swedish_ci' * `XXX_turkish_ci' * `XXX_unicode_ci' The `XXX_hungarian_ci' collations were added in MySQL 5.1.5. 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'. Currently, the `XXX_unicode_ci' collations have only partial support for the Unicode Collation Algorithm. Some characters are not supported yet. Also, combining marks are not fully supported. This affects primarily Vietnamese, Yoruba, and some smaller languages such as Navajo. MySQL implements language-specific Unicode collations only if the ordering with `XXX_unicode_ci' does not work well for a language. Language-specific collations are UCA-based. They are derived from `XXX_unicode_ci' with additional language tailoring rules. 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 this has in comparisons or when doing searches, see *Note 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 language-specific collations for the `utf8' character set only 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. Otherwise, use `utf8_unicode_ci' because it is more accurate. `XXX_swedish_ci' includes Swedish rules. For example, in Swedish, the following relationship holds, which is not something expected by a German or French speaker: U" = Y < O" The `XXX_spanish_ci' and `XXX_spanish2_ci' collations correspond to modern Spanish and traditional Spanish, respectively. In both collations, ``ñ'' (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'' In the `XXX_roman_ci' collations, `I' and `J' compare as equal, and `U' and `V' compare as equal. The `XXX_general_mysql500_ci' collations were added in MySQL 5.1.62. They 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. For more information, see *Note checking-table-incompatibilities::, and *Note rebuilding-tables::. For additional information about Unicode collations in MySQL, see Collation-Charts.Org (utf8 (http://www.collation-charts.org/mysql60/by-charset.html#utf8)).  File: manual.info, Node: charset-we-sets, Next: charset-ce-sets, Prev: charset-unicode-sets, Up: charset-charsets 10.1.13.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 *Note 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) For additional information about Western European collations in MySQL, see Collation-Charts.Org (ascii (http://www.collation-charts.org/mysql60/by-charset.html#ascii), cp850 (http://www.collation-charts.org/mysql60/by-charset.html#cp850), dec8 (http://www.collation-charts.org/mysql60/by-charset.html#dec8), hp8 (http://www.collation-charts.org/mysql60/by-charset.html#hp8), latin1 (http://www.collation-charts.org/mysql60/by-charset.html#latin1), macroman (http://www.collation-charts.org/mysql60/by-charset.html#macroman), swe7 (http://www.collation-charts.org/mysql60/by-charset.html#swe7)).  File: manual.info, Node: charset-ce-sets, Next: charset-se-me-sets, Prev: charset-we-sets, Up: charset-charsets 10.1.13.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) For additional information about Central European collations in MySQL, see Collation-Charts.Org (cp1250 (http://www.collation-charts.org/mysql60/by-charset.html#cp1250), cp852 (http://www.collation-charts.org/mysql60/by-charset.html#cp852), keybcs2 (http://www.collation-charts.org/mysql60/by-charset.html#keybcs2), latin2 (http://www.collation-charts.org/mysql60/by-charset.html#latin2), macce (http://www.collation-charts.org/mysql60/by-charset.html#macce)).  File: manual.info, Node: charset-se-me-sets, Next: charset-baltic-sets, Prev: charset-ce-sets, Up: charset-charsets 10.1.13.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) For additional information about South European and Middle Eastern collations in MySQL, see Collation-Charts.Org (armscii8 (http://www.collation-charts.org/mysql60/by-charset.html#armscii8), cp1256 (http://www.collation-charts.org/mysql60/by-charset.html#cp1256), geostd8 (http://www.collation-charts.org/mysql60/by-charset.html#geostd8), greek (http://www.collation-charts.org/mysql60/by-charset.html#greek), hebrew (http://www.collation-charts.org/mysql60/by-charset.html#hebrew), latin5 (http://www.collation-charts.org/mysql60/by-charset.html#latin5)).  File: manual.info, Node: charset-baltic-sets, Next: charset-cyrillic-sets, Prev: charset-se-me-sets, Up: charset-charsets 10.1.13.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' For additional information about Baltic collations in MySQL, see Collation-Charts.Org (cp1257 (http://www.collation-charts.org/mysql60/by-charset.html#cp1257), latin7 (http://www.collation-charts.org/mysql60/by-charset.html#latin7)).  File: manual.info, Node: charset-cyrillic-sets, Next: charset-asian-sets, Prev: charset-baltic-sets, Up: charset-charsets 10.1.13.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) For additional information about Cyrillic collations in MySQL, see Collation-Charts.Org (cp1251 (http://www.collation-charts.org/mysql60/by-charset.html#cp1251), cp866 (http://www.collation-charts.org/mysql60/by-charset.html#cp866), koi8r (http://www.collation-charts.org/mysql60/by-charset.html#koi8r), koi8u (http://www.collation-charts.org/mysql60/by-charset.html#koi8u)). ).  File: manual.info, Node: charset-asian-sets, Prev: charset-cyrillic-sets, Up: charset-charsets 10.1.13.7 Asian Character Sets .............................. * Menu: * charset-cp932:: The `cp932' Character Set 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 *Note charset-cp932::, for additional information about the `cp932' and `sjis' character sets. For answers to some common questions and problems relating support for Asian character sets in MySQL, see *Note 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) * `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. For additional information about Asian collations in MySQL, see Collation-Charts.Org (big5 (http://www.collation-charts.org/mysql60/by-charset.html#big5), cp932 (http://www.collation-charts.org/mysql60/by-charset.html#cp932), eucjpms (http://www.collation-charts.org/mysql60/by-charset.html#eucjpms), euckr (http://www.collation-charts.org/mysql60/by-charset.html#euckr), gb2312 (http://www.collation-charts.org/mysql60/by-charset.html#gb2312), gbk (http://www.collation-charts.org/mysql60/by-charset.html#gbk), sjis (http://www.collation-charts.org/mysql60/by-charset.html#sjis), tis620 (http://www.collation-charts.org/mysql60/by-charset.html#tis620), ujis (http://www.collation-charts.org/mysql60/by-charset.html#ujis)).  File: manual.info, Node: charset-cp932, Prev: charset-asian-sets, Up: charset-asian-sets 10.1.13.8 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 `http://www.microsoft.com/globaldev/reference/dbcs/932.htm' 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: `http://www.microsoft.com/globaldev/reference/dbcs/932/932_87.htm' * NEC selected--IBM extended characters: `http://www.microsoft.com/globaldev/reference/dbcs/932/932_ED.htm' `http://www.microsoft.com/globaldev/reference/dbcs/932/932_EE.htm' * IBM selected characters: `http://www.microsoft.com/globaldev/reference/dbcs/932/932_FA.htm' `http://www.microsoft.com/globaldev/reference/dbcs/932/932_FB.htm' `http://www.microsoft.com/globaldev/reference/dbcs/932/932_FC.htm' * `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.opengroup.or.jp/jvc/cde/sjis-euc-e.html'. For some characters, conversion to and from `ucs2' is different for `sjis' and `cp932'. The following tables illustrate these differences. Conversion to `ucs2': This table lists `sjis'/`cp932' values and shows the difference between `sjis' to `ucs2' conversion and `cp932' to `ucs2' conversion. `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': This table lists `ucs2' values and shows the difference between `ucs2' to `sjis' conversion and `ucs2' to `cp932' conversion. `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 *Note server-options::.  File: manual.info, Node: error-message-language, Next: adding-character-set, Prev: charset, Up: globalization 10.2 Setting the Error Message Language ======================================= By default, *Note `mysqld': mysqld. produces error messages in English, but they can also be displayed 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. You can select which language the server uses for error messages using the instructions in this section. To start *Note `mysqld': mysqld. with a particular language for error messages, use the `--language' or `-L' option. The option value can be a language name or the full path to the error message file. For example: shell> mysqld --language=swedish Or: shell> mysqld --language=/usr/local/share/swedish The language name should be specified in lowercase. By default, the language files are located in the `share/mysql/LANGUAGE' directory under the MySQL base directory. For information about changing the character set for error messages (rather than the language), see *Note charset-errors::. 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 the content of error messages, remember to repeat your changes after each upgrade to a newer version of MySQL.  File: manual.info, Node: adding-character-set, Next: adding-collation, Prev: error-message-language, Up: globalization 10.3 Adding a Character Set =========================== * Menu: * character-arrays:: Character Definition Arrays * string-collating:: String Collating Support for Complex Character Sets * multi-byte-characters:: Multi-Byte Character Support for Complex Character Sets 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 multi-byte 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 `' 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' `' element follows: Western cp1252 West European ... primary compiled ... binary compiled ... The `' 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, chosen from the range 1 to 254. 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, multi-byte 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 (`'). * Words within `' array elements are separated by arbitrary amounts of whitespace. * Each word within `' array elements must be a number in hexadecimal format. * The `' array element for the `' element has 257 words. The other `' array elements after that have 256 words. See *Note character-arrays::. * For each collation listed in the `' element for the character set in `Index.xml', `MYSET.xml' must contain a `' 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 *Note character-arrays::. * For each `' element listed in the `' 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 *Note string-collating::. * If the character set requires multi-byte character support, see *Note multi-byte-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/Makefile.am' and add `ctype-MYSET.c' to each definition of the `CSRCS' variable, and to the `EXTRA_DIST' variable. 3. If the character set uses `ctype-MYSET.c', edit `libmysql/Makefile.shared' and add `ctype-MYSET.lo' to the `mystringsobjects' definition. 4. Edit `config/ac-macros/character_sets.m4': 1. Add MYSET to one of the `define(CHARSETS_AVAILABLE...)' lines in alphabetic order. 2. Add MYSET to `CHARSETS_COMPLEX'. This is needed even for simple character sets, or `configure' will not recognize `--with-charset=MYSET'. 3. Add MYSET to the first `case' control structure. Omit the `USE_MB' and `USE_MB_IDENT' lines for 8-bit character sets. MYSET) AC_DEFINE(HAVE_CHARSET_MYSET, 1, [Define to enable charset MYSET]) AC_DEFINE([USE_MB], 1, [Use multi-byte character routines]) AC_DEFINE(USE_MB_IDENT, 1) ;; 4. Add MYSET to the second `case' control structure: MYSET) default_charset_default_collation="MYSET_general_ci" default_charset_collations="MYSET_general_ci MYSET_bin" ;; 4. Reconfigure, recompile, and test.  File: manual.info, Node: character-arrays, Next: string-collating, Prev: adding-character-set, Up: adding-character-set 10.3.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 `' array elements to list character set properties. `' elements appear within these elements: * `' defines attributes for each character. * `' and `' list the lowercase and uppercase characters. * `' maps 8-bit character values to Unicode values. * `' elements indicate character ordering for comparisons and sorts, one element per collation. Binary collations need no `' 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 `' array is indexed by character value + 1 and has 257 elements. This is a legacy convention for handling `EOF'. `' 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 `' 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 `' array in `MYSET.xml' should be written as hexadecimal values. The `' and `' 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 `' 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 `' array, which means that sorting is case-insensitive. For more complicated sorting rules (for complex character sets), see the discussion of string collating in *Note string-collating::.  File: manual.info, Node: string-collating, Next: multi-byte-characters, Prev: character-arrays, Up: adding-character-set 10.3.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 `' array elements within `' 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.  File: manual.info, Node: multi-byte-characters, Prev: string-collating, Up: adding-character-set 10.3.3 Multi-Byte Character Support for Complex Character Sets -------------------------------------------------------------- If you want to add support for a new character set named MYSET that includes multi-byte characters, you must use multi-byte 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.  File: manual.info, Node: adding-collation, Next: charset-configuration, Prev: adding-character-set, Up: globalization 10.4 Adding a Collation to a Character Set ========================================== * Menu: * charset-collation-implementations:: Collation Implementation Types * adding-collation-choosing-id:: Choosing a Collation ID * adding-collation-simple-8bit:: Adding a Simple Collation to an 8-Bit Character Set * adding-collation-unicode-uca:: Adding a UCA Collation to a Unicode 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. MySQL supports several collation implementations, as discussed in *Note 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 *Note 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. For further information, see *Note checking-table-incompatibilities::. * 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/' * MySQL Blog article `Instructions for adding a new Unicode collation': `http://blogs.mysql.com/peterg/2008/05/19/instructions-for-adding-a-new-unicode-collation/'  File: manual.info, Node: charset-collation-implementations, Next: adding-collation-choosing-id, Prev: adding-collation, Up: adding-collation 10.4.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.00 sec) mysql> SELECT 'a' = 'A'; +-----------+ | 'a' = 'A' | +-----------+ | 1 | +-----------+ 1 row in set (0.00 sec) For implementation instructions, see *Note 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 *Note adding-character-set::. *Collations for non-Unicode multi-byte character sets* For this type of collation, 8-bit (single-byte) and multi-byte 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 multi-byte 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 multi-byte character `'ぢ'' has a character code of `0x82C0', and the weight is also `0x82C0'. * 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 multi-byte character `'膰'' has a character code of `0x81B0' but a weight of `0xC286'. For implementation instructions, see *Note adding-character-set::. *Collations for Unicode multi-byte 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> SELECT 'a' = 'A', 'a' = 'A`', 'a' = 'a''; +-----------+-----------+-----------+ | 'a' = 'A' | 'a' = 'A`' | 'a' = 'a'' | +-----------+-----------+-----------+ | 1 | 1 | 1 | +-----------+-----------+-----------+ 1 row in set (0.06 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'. * 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'. * Many characters may have one weight. This is a contraction. Example: `'ch'' is a single letter in Czech and has a weight of `0x0EE2'. 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 *Note adding-character-set::. For a UCA collation, see *Note adding-collation-unicode-uca::. *Miscellaneous collations* There are also a few collations that do not fall into any of the previous categories.  File: manual.info, Node: adding-collation-choosing-id, Next: adding-collation-simple-8bit, Prev: charset-collation-implementations, Up: adding-collation 10.4.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. The value must be in the range from 1 to 254. The collation ID that you choose will appear in these contexts: * The `ID' column of the *Note `INFORMATION_SCHEMA.COLLATIONS': collations-table. table. * The `Id' column of *Note `SHOW COLLATION': 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 *Note `mysql_get_character_set_info()': 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 | +---------+ For the output just shown, you could choose an ID higher than 210 for the new collation. 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 | +-----+ In this case, you can either choose an unused ID from within the current range of IDs, or choose an ID that is higher than the current maximum ID. For example, in the output just shown, there are unused IDs between 53 and 57, and between 99 and 128. Or you could choose an ID higher than 210. *Warning*: If you upgrade MySQL, you may find that the collation ID you choose has been assigned to a collation included in the new MySQL distribution. In this case, you will need to choose a new value for your own collation. In addition, before upgrading, you should save the configuration files that you change. If you upgrade in place, the process will replace the your modified files.  File: manual.info, Node: adding-collation-simple-8bit, Next: adding-collation-unicode-uca, Prev: adding-collation-choosing-id, Up: adding-collation 10.4.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 `' elements associated with a `' 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 *Note adding-collation-choosing-id::. The following steps use an ID of 56. 2. Modify the `Index.xml' and `latin1.xml' configuration files. These files will be 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 `' element for the character set to which the collation is being added, and add a `' element that indicates the collation name and ID, to associate the name with the ID. For example: ... ... 4. In the `latin1.xml' configuration file, add a `' element that names the collation and that contains a `' element that defines a character code-to-weight mapping table for character codes 0 to 255. Each value within the `' element must be a number in hexadecimal format. 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 5. Restart the server and use this statement to verify that the collation is present: mysql> SHOW COLLATION LIKE 'latin1_test_ci'; +----------------+---------+----+---------+----------+---------+ | Collation | Charset | Id | Default | Compiled | Sortlen | +----------------+---------+----+---------+----------+---------+ | latin1_test_ci | latin1 | 56 | | | 1 | +----------------+---------+----+---------+----------+---------+  File: manual.info, Node: adding-collation-unicode-uca, Prev: adding-collation-simple-8bit, Up: adding-collation 10.4.4 Adding a UCA Collation to a Unicode Character Set -------------------------------------------------------- * Menu: * ldml-collation-example:: Defining a UCA Collation Using LDML Syntax * ldml-rules:: LDML Syntax Supported in MySQL This section describes how to add a UCA collation for a Unicode character set by writing the `' element within a `' 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/'. In 5.1, this method of adding collations is supported as of MySQL 5.1.20. 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. *MySQL Character Sets Available for User-Defined UCA Collations* Character Set Base Collation `utf8' `utf8_unicode_ci' `ucs2' `ucs2_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.  File: manual.info, Node: ldml-collation-example, Next: ldml-rules, Prev: adding-collation-unicode-uca, Up: adding-collation-unicode-uca 10.4.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 *Note 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 *Note adding-collation-choosing-id::. The following steps use an ID of 252. 2. To modify the `Index.xml' configuration file. This file will be 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 `' element for the character set to which the collation is being added, and add a `' element that indicates the collation name and ID, to associate the name with the ID. Within the `' element, provide a `' element containing the ordering rules: ... \u0000 \u0020 \u0028 \u0029 \u002B \u002D ... 4. If you want a similar collation for other Unicode character sets, add other `' elements. For example, to define `ucs2_phone_ci', add a `' element to the `' 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 LIKE 'utf8_phone_ci'; +---------------+---------+-----+---------+----------+---------+ | Collation | Charset | Id | Default | Compiled | Sortlen | +---------------+---------+-----+---------+----------+---------+ | utf8_phone_ci | utf8 | 252 | | | 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 sorting and comparisons: 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)  File: manual.info, Node: ldml-rules, Prev: ldml-collation-example, Up: adding-collation-unicode-uca 10.4.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. 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. *Character Representation* Characters named in LDML rules can be written in `\uNNNN' format, where NNNN is the hexadecimal Unicode code point value. Within hexadecimal values, the digits `A' through `F' are not case sensitive; `\u00E1' and `\u00e1' are equivalent. Basic Latin letters `A-Z' and `a-z' can also be written literally (this is a MySQL limitation; the LDML specification permits literal non-Latin1 characters in the rules). Only characters in the Basic Multilingual Plane can be specified. This notation does not apply to characters outside the BMP range of `0000' to `FFFF'. The `Index.xml' file itself should be written using ASCII 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 `' 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'': A \u0041 * The `

', `', and `' 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:

G

\u0047

 File: manual.info, Node: charset-configuration, Next: time-zone-support, Prev: adding-collation, Up: globalization 10.5 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 *Note `SHOW COLLATION': show-collation. statement to determine which collations are available for each character set.) See *Note 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.1/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 *Note 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 *Note `myisamchk -dvv TBL_NAME': myisamchk.  File: manual.info, Node: time-zone-support, Next: locale-support, Prev: charset-configuration, Up: globalization 10.6 MySQL Server Time Zone Support =================================== * Menu: * time-zone-upgrades:: Staying Current with Time Zone Changes * time-zone-leap-seconds:: Time Zone Leap Second Support The 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 *Note `mysqld_safe': mysqld-safe. You can also set it by setting the `TZ' environment variable before you start *Note `mysqld': 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. 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 *Note `TIMESTAMP': datetime. columns. Values for *Note `TIMESTAMP': datetime. 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 *Note `DATE': datetime, *Note `TIME': time, or *Note `DATETIME': 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 *Note `DATE': datetime, *Note `TIME': time, or *Note `DATETIME': 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. The MySQL installation procedure creates the time zone tables in the `mysql' database, but does not load them. You must do so manually using the following instructions. (If you are upgrading to MySQL 4.1.3 or later from an earlier version, you can create the tables by upgrading your `mysql' database. Use the instructions in *Note mysql-upgrade::. After creating the tables, you can load them.) *Note*: Loading the time zone information is not necessarily a one-time operation because the information changes occasionally. For example, the rules for Daylight Saving Time in the United States, Mexico, and parts of Canada changed in 2007. 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 *Note `mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. program for filling the time zone tables. Examples of such systems are Linux, FreeBSD, Solaris, and Mac 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 *Note `mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. program is used to load the time zone tables. On the command line, pass the zoneinfo directory path name to *Note `mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. and send the output into the *Note `mysql': mysql. program. For example: shell> mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql *Note `mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. reads your system's time zone files and generates SQL statements from them. *Note `mysql': mysql. processes those statements to load the time zone tables. *Note `mysql_tzinfo_to_sql': 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 *Note `mysql_tzinfo_to_sql': 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 *Note `mysql_tzinfo_to_sql': 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 or HP-UX), you can use the package of pre-built time zone tables that is available for download at the MySQL Developer Zone: `http://dev.mysql.com/downloads/timezones.html' This time zone package contains `.frm', `.MYD', and `.MYI' files for the `MyISAM' time zone tables. These tables should be part of the `mysql' database, so you should place the files in the `mysql' subdirectory of your MySQL server's data directory. The server should be stopped while you do this and restarted afterward. *Warning*: Do not use the downloadable package if your system has a zoneinfo database. Use the *Note `mysql_tzinfo_to_sql': 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 *Note replication-features::.  File: manual.info, Node: time-zone-upgrades, Next: time-zone-leap-seconds, Prev: time-zone-support, Up: time-zone-support 10.6.1 Staying Current with Time Zone Changes --------------------------------------------- As mentioned earlier, when the 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 Web site 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 *Note `mysqld': mysqld. startup, you should restart *Note `mysqld': mysqld. so that it uses the updated rules. Otherwise, *Note `mysqld': 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, using the instructions given earlier in this section. 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 your current time zone tables. *Note `mysqld': mysqld. caches time zone information that it looks up, so after replacing the time zone tables, you should restart *Note `mysqld': 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 | +------------------------------------------------------------+  File: manual.info, Node: time-zone-leap-seconds, Prev: time-zone-upgrades, Up: time-zone-support 10.6.2 Time Zone Leap Second Support ------------------------------------ Before MySQL 5.1.31, if the operating system is configured to return leap seconds from OS time calls or if the MySQL server uses a time zone definition that has leap seconds, functions such as `NOW()' could return a value having a time part that ends with `:59:60' or `:59:61'. If such values are inserted into a table, they would be dumped as is by *Note `mysqldump': mysqldump. but considered invalid when reloaded, leading to backup/restore problems. As of MySQL 5.1.31, 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 *Note `TIMESTAMP': datetime. 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)  File: manual.info, Node: locale-support, Prev: time-zone-support, Up: globalization 10.7 MySQL Server Locale Support ================================ Beginning with MySQL 5.1.12, 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. 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. This table lists locale values to which `lc_time_names' may be set. The locale values are presented in a two-column table and in alphabetical order from left to right. `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 `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 - Columbia `es_CR': Spanish - Costa Rica `es_DO': Spanish - Dominican `es_EC': Spanish - Ecuador Republic `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 Korea `lt_LT': Lithuanian - Lithuania `lv_LV': Latvian - Latvia `mk_MK': Macedonian - FYROM `mn_MN': Mongolia - Mongolian `ms_MY': Malay - Malaysia `nb_NO': Norwegian(Bokmaal) - Norway `nl_BE': Dutch - Belgium `nl_NL': Dutch - The Netherlands `no_NO': Norwegian - Norway `pl_PL': Polish - Poland `pt_BR': Portugese - Brazil `pt_PT': Portugese - Portugal `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_YU': 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  File: manual.info, Node: data-types, Next: functions, Prev: globalization, Up: Top 11 Data Types ************* * Menu: * data-type-overview:: Data Type Overview * numeric-types:: Numeric Types * date-and-time-types:: Date and Time Types * string-types:: String Types * data-type-defaults:: Data Type Default Values * storage-requirements:: Data Type Storage Requirements * choosing-types:: Choosing the Right Type for a Column * other-vendor-data-types:: Using Data Types from Other Database Engines MySQL supports a number of SQL (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_sql) data types in several categories: numeric types, date and time types, and string (character and byte) types. 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. MySQL also supports extensions for handling spatial data. For information about these data types, see *Note spatial-extensions::. 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. * Square brackets (``['' and ``]'') indicate optional parts of type definitions.  File: manual.info, Node: data-type-overview, Next: numeric-types, Prev: data-types, Up: data-types 11.1 Data Type Overview ======================= * Menu: * numeric-type-overview:: Numeric Type Overview * date-and-time-type-overview:: Date and Time Type Overview * string-type-overview:: String Type Overview  File: manual.info, Node: numeric-type-overview, Next: date-and-time-type-overview, Prev: data-type-overview, Up: 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 *Note numeric-types::, and *Note 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 *Note 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 *Note cast-functions::. * *Note `BIT[(M)]': bit-type. A bit-field type. M indicates the number of bits per value, from 1 to 64. The default is 1 if M is omitted. * *Note `TINYINT[(M)] [UNSIGNED] [ZEROFILL]': integer-types. A very small integer. The signed range is `-128' to `127'. The unsigned range is `0' to `255'. * *Note `BOOL': integer-types, *Note `BOOLEAN': integer-types. These types are synonyms for *Note `TINYINT(1)': integer-types. 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'. * *Note `SMALLINT[(M)] [UNSIGNED] [ZEROFILL]': integer-types. A small integer. The signed range is `-32768' to `32767'. The unsigned range is `0' to `65535'. * *Note `MEDIUMINT[(M)] [UNSIGNED] [ZEROFILL]': integer-types. A medium-sized integer. The signed range is `-8388608' to `8388607'. The unsigned range is `0' to `16777215'. * *Note `INT[(M)] [UNSIGNED] [ZEROFILL]': integer-types. A normal-size integer. The signed range is `-2147483648' to `2147483647'. The unsigned range is `0' to `4294967295'. * *Note `INTEGER[(M)] [UNSIGNED] [ZEROFILL]': integer-types. This type is a synonym for *Note `INT': integer-types. * *Note `BIGINT[(M)] [UNSIGNED] [ZEROFILL]': integer-types. 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 *Note `BIGINT': integer-types. columns: * All arithmetic is done using signed *Note `BIGINT': integer-types. or *Note `DOUBLE': floating-point-types. 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 *Note `BIGINT': integer-types. value to a *Note `DOUBLE': floating-point-types. MySQL can handle *Note `BIGINT': integer-types. in the following cases: * When using integers to store large unsigned values in a *Note `BIGINT': integer-types. column. * In `MIN(COL_NAME)' or `MAX(COL_NAME)', where COL_NAME refers to a *Note `BIGINT': integer-types. column. * When using operators (`+', `-', `*', and so on) where both operands are integers. * You can always store an exact integer value in a *Note `BIGINT': integer-types. 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 *Note `BIGINT': integer-types. 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'. * *Note `DECIMAL[(M[,D])] [UNSIGNED] [ZEROFILL]': fixed-point-types. 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 *Note `DECIMAL': fixed-point-types. 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 *Note `DECIMAL': fixed-point-types. columns are done with a precision of 65 digits. * *Note `DEC[(M[,D])] [UNSIGNED] [ZEROFILL]': fixed-point-types, *Note `NUMERIC[(M[,D])] [UNSIGNED] [ZEROFILL]': fixed-point-types, *Note `FIXED[(M[,D])] [UNSIGNED] [ZEROFILL]': fixed-point-types. These types are synonyms for *Note `DECIMAL': fixed-point-types. The *Note `FIXED': fixed-point-types. synonym is available for compatibility with other database systems. * *Note `FLOAT[(M,D)] [UNSIGNED] [ZEROFILL]': floating-point-types. 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 *Note `FLOAT': floating-point-types. might give you some unexpected problems because all calculations in MySQL are done with double precision. See *Note no-matching-rows::. * *Note `DOUBLE[(M,D)] [UNSIGNED] [ZEROFILL]': floating-point-types. 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. * *Note `DOUBLE PRECISION[(M,D)] [UNSIGNED] [ZEROFILL]': floating-point-types, *Note `REAL[(M,D)] [UNSIGNED] [ZEROFILL]': floating-point-types. These types are synonyms for *Note `DOUBLE': floating-point-types. Exception: If the `REAL_AS_FLOAT' SQL mode is enabled, *Note `REAL': floating-point-types. is a synonym for *Note `FLOAT': floating-point-types. rather than *Note `DOUBLE': floating-point-types. * *Note `FLOAT(P) [UNSIGNED] [ZEROFILL]': floating-point-types. A floating-point number. P represents the precision in bits, but MySQL uses this value only to determine whether to use *Note `FLOAT': floating-point-types. or *Note `DOUBLE': floating-point-types. for the resulting data type. If P is from 0 to 24, the data type becomes *Note `FLOAT': floating-point-types. with no M or D values. If P is from 25 to 53, the data type becomes *Note `DOUBLE': floating-point-types. with no M or D values. The range of the resulting column is the same as for the single-precision *Note `FLOAT': floating-point-types. or double-precision *Note `DOUBLE': floating-point-types. data types described earlier in this section. *Note `FLOAT(P)': floating-point-types. syntax is provided for ODBC compatibility.  File: manual.info, Node: date-and-time-type-overview, Next: string-type-overview, Prev: numeric-type-overview, Up: data-type-overview 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 *Note date-and-time-types::, and *Note storage-requirements::. For descriptions of functions that operate on temporal values, see *Note date-and-time-functions::. For the *Note `DATE': datetime. and *Note `DATETIME': datetime. range descriptions, `supported' means that although earlier values might work, there is no guarantee. * *Note `DATE': datetime. A date. The supported range is `'1000-01-01'' to `'9999-12-31''. MySQL displays *Note `DATE': datetime. values in `'YYYY-MM-DD'' format, but permits assignment of values to *Note `DATE': datetime. columns using either strings or numbers. * *Note `DATETIME': datetime. A date and time combination. The supported range is `'1000-01-01 00:00:00'' to `'9999-12-31 23:59:59''. MySQL displays *Note `DATETIME': datetime. values in `'YYYY-MM-DD HH:MM:SS'' format, but permits assignment of values to *Note `DATETIME': datetime. columns using either strings or numbers. * *Note `TIMESTAMP': datetime. A timestamp. The range is `'1970-01-01 00:00:01'' UTC to `'2038-01-19 03:14:07'' UTC. *Note `TIMESTAMP': datetime. values are stored as the number of seconds since the epoch (`'1970-01-01 00:00:00'' UTC). A *Note `TIMESTAMP': datetime. 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' *Note `TIMESTAMP': datetime. value. Unless specified otherwise, the first *Note `TIMESTAMP': datetime. 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 *Note `TIMESTAMP': datetime. useful for recording the timestamp of an *Note `INSERT': insert. or *Note `UPDATE': update. operation. You can also set any *Note `TIMESTAMP': 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. The automatic initialization and updating to the current date and time can be specified using `DEFAULT CURRENT_TIMESTAMP' and `ON UPDATE CURRENT_TIMESTAMP' clauses, as described in *Note timestamp-initialization::. *Note*: The *Note `TIMESTAMP': datetime. format that was used prior to MySQL 4.1 is not supported in MySQL 5.1; see `MySQL 3.23, 4.0, 4.1 Reference Manual' for information regarding the old format. * *Note `TIME': time. A time. The range is `'-838:59:59'' to `'838:59:59''. MySQL displays *Note `TIME': time. values in `'HH:MM:SS'' format, but permits assignment of values to *Note `TIME': time. columns using either strings or numbers. * *Note `YEAR[(2|4)]': year. A year in two-digit or four-digit format. The default is four-digit format. `YEAR(2)' or `YEAR(4)' differ in display format, but have the same range of values. In four-digit format, values display as `1901' to `2155', and `0000'. In two-digit format, values display as `70' to `69', representing years from 1970 to 2069. MySQL displays *Note `YEAR': year. values in `YYYY' or `YY'format, but permits assignment of values to *Note `YEAR': year. columns using either strings or numbers. *Note*: The `YEAR(2)' data type has certain issues that you should consider before choosing to use it. As of MySQL 5.1.65, `YEAR(2)' is deprecated. For more information, see *Note migrating-to-year4::. For additional information about `YEAR' display format and interpretation of input values, see *Note 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, *Note `TIMESTAMP': datetime. is identical with *Note `DATETIME': datetime. If this mode is enabled at the time that a table is created, *Note `TIMESTAMP': datetime. columns are created as *Note `DATETIME': datetime. columns. As a result, such columns use *Note `DATETIME': datetime. display format, have the same range of values, and there is no automatic initialization or updating to the current date and time. See *Note server-sql-mode::.  File: manual.info, Node: string-type-overview, Prev: date-and-time-type-overview, Up: data-type-overview 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 *Note string-types::, and *Note storage-requirements::. In some cases, MySQL may change a string column to a type different from that given in a *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. statement. See *Note silent-column-changes::. MySQL interprets length specifications in character column definitions in character units. This applies to *Note `CHAR': char, *Note `VARCHAR': char, and the *Note `TEXT': blob. 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 *Note `CHAR': char, *Note `VARCHAR': char, the *Note `TEXT': blob. types, *Note `ENUM': enum, and *Note `SET': 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 *Note charset-column::. `CHARSET' is a synonym for `CHARACTER SET'. * Specifying the `CHARACTER SET binary' attribute for a character data type causes the column to be created as the corresponding binary data type: *Note `CHAR': char. becomes *Note `BINARY': binary-varbinary, *Note `VARCHAR': char. becomes *Note `VARBINARY': binary-varbinary, and *Note `TEXT': blob. becomes *Note `BLOB': blob. For the *Note `ENUM': enum. and *Note `SET': 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 `ASCII' attribute is shorthand for `CHARACTER SET latin1'. * The `UNICODE' attribute is shorthand for `CHARACTER SET ucs2'. * The `BINARY' attribute is shorthand for specifying the binary collation of the column character set. In this case, sorting and comparison are based on numeric character values. Character column sorting and comparison are based on the character set assigned to the column. For the *Note `CHAR': char, *Note `VARCHAR': char, *Note `TEXT': blob, *Note `ENUM': enum, and *Note `SET': set. data types, you can declare a column with a binary collation or the `BINARY' attribute to cause sorting and comparison to use the underlying character code values rather than a lexical ordering. *Note charset::, provides additional information about use of character sets in MySQL. * `[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 *Note `CHAR': char. values are retrieved unless the `PAD_CHAR_TO_FULL_LENGTH' SQL mode is enabled. *Note `CHAR': char. is shorthand for *Note `CHARACTER': char. *Note `NATIONAL CHAR': char. (or its equivalent short form, *Note `NCHAR': char.) is the standard SQL way to define that a *Note `CHAR': char. column should use some predefined character set. MySQL 4.1 and up uses `utf8' as this predefined character set. *Note charset-national::. The *Note `CHAR BYTE': binary-varbinary. data type is an alias for the *Note `BINARY': binary-varbinary. 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 *Note `VARCHAR': char. 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 *Note `VARCHAR': char. column that uses the `utf8' character set can be declared to be a maximum of 21,844 characters. See *Note column-count-limit::. MySQL stores *Note `VARCHAR': char. values as a 1-byte or 2-byte length prefix plus data. The length prefix indicates the number of bytes in the value. A *Note `VARCHAR': char. 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 5.1 follows the standard SQL specification, and does _not_ remove trailing spaces from *Note `VARCHAR': char. values. *Note `VARCHAR': char. is shorthand for *Note `CHARACTER VARYING': char. *Note `NATIONAL VARCHAR': char. is the standard SQL way to define that a *Note `VARCHAR': char. column should use some predefined character set. MySQL 4.1 and up uses `utf8' as this predefined character set. *Note charset-national::. *Note `NVARCHAR': char. is shorthand for *Note `NATIONAL VARCHAR': char. * *Note `BINARY(M)': binary-varbinary. The *Note `BINARY': binary-varbinary. type is similar to the *Note `CHAR': char. type, but stores binary byte strings rather than nonbinary character strings. M represents the column length in bytes. * *Note `VARBINARY(M)': binary-varbinary. The *Note `VARBINARY': binary-varbinary. type is similar to the *Note `VARCHAR': char. type, but stores binary byte strings rather than nonbinary character strings. M represents the maximum column length in bytes. * *Note `TINYBLOB': blob. A *Note `BLOB': blob. column with a maximum length of 255 (2^8 - 1) bytes. Each *Note `TINYBLOB': blob. value is stored using a 1-byte length prefix that indicates the number of bytes in the value. * *Note `TINYTEXT [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]': blob. A *Note `TEXT': blob. column with a maximum length of 255 (2^8 - 1) characters. The effective maximum length is less if the value contains multi-byte characters. Each *Note `TINYTEXT': blob. value is stored using a 1-byte length prefix that indicates the number of bytes in the value. * *Note `BLOB[(M)]': blob. A *Note `BLOB': blob. column with a maximum length of 65,535 (2^16 - 1) bytes. Each *Note `BLOB': 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 *Note `BLOB': blob. type large enough to hold values M bytes long. * *Note `TEXT[(M)] [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]': blob. A *Note `TEXT': blob. column with a maximum length of 65,535 (2^16 - 1) characters. The effective maximum length is less if the value contains multi-byte characters. Each *Note `TEXT': 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 *Note `TEXT': blob. type large enough to hold values M characters long. * *Note `MEDIUMBLOB': blob. A *Note `BLOB': blob. column with a maximum length of 16,777,215 (2^24 - 1) bytes. Each *Note `MEDIUMBLOB': blob. value is stored using a 3-byte length prefix that indicates the number of bytes in the value. * *Note `MEDIUMTEXT [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]': blob. A *Note `TEXT': blob. column with a maximum length of 16,777,215 (2^24 - 1) characters. The effective maximum length is less if the value contains multi-byte characters. Each *Note `MEDIUMTEXT': blob. value is stored using a 3-byte length prefix that indicates the number of bytes in the value. * *Note `LONGBLOB': blob. A *Note `BLOB': blob. column with a maximum length of 4,294,967,295 or 4GB (2^32 - 1) bytes. The effective maximum length of *Note `LONGBLOB': blob. columns depends on the configured maximum packet size in the client/server protocol and available memory. Each *Note `LONGBLOB': blob. value is stored using a 4-byte length prefix that indicates the number of bytes in the value. * *Note `LONGTEXT [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]': blob. A *Note `TEXT': blob. 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 multi-byte characters. The effective maximum length of *Note `LONGTEXT': blob. columns also depends on the configured maximum packet size in the client/server protocol and available memory. Each *Note `LONGTEXT': blob. value is stored using a 4-byte length prefix that indicates the number of bytes in the value. * *Note `ENUM('VALUE1','VALUE2',...) [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]': enum. 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. *Note `ENUM': enum. values are represented internally as integers. An *Note `ENUM': 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 *Note `ENUM': enum. and *Note `SET': set. columns considered as a group. For more information on these limits, see *Note limits-frm-file::. * *Note `SET('VALUE1','VALUE2',...) [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]': set. 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'', `...' *Note `SET': set. values are represented internally as integers. A *Note `SET': set. column can have a maximum of 64 distinct members. A table can have no more than 255 unique element list definitions among its *Note `ENUM': enum. and *Note `SET': set. columns considered as a group. For more information on this limit, see *Note limits-frm-file::.  File: manual.info, Node: numeric-types, Next: date-and-time-types, Prev: data-type-overview, Up: data-types 11.2 Numeric Types ================== * Menu: * integer-types:: Integer Types (Exact Value) - `INTEGER', `INT', `SMALLINT', `TINYINT', `MEDIUMINT', `BIGINT' * fixed-point-types:: Fixed-Point Types (Exact Value) - `DECIMAL', `NUMERIC' * floating-point-types:: Floating-Point Types (Approximate Value) - `FLOAT', `DOUBLE' * bit-type:: Bit-Value Type - `BIT' * numeric-type-attributes:: Numeric Type Attributes * out-of-range-and-overflow:: Out-of-Range and Overflow Handling MySQL supports all standard SQL numeric data types. These types include the exact numeric data types (*Note `INTEGER': integer-types, *Note `SMALLINT': integer-types, *Note `DECIMAL': fixed-point-types, and *Note `NUMERIC': fixed-point-types.), as well as the approximate numeric data types (*Note `FLOAT': floating-point-types, *Note `REAL': floating-point-types, and *Note `DOUBLE PRECISION': floating-point-types.). The keyword *Note `INT': integer-types. is a synonym for *Note `INTEGER': integer-types, and the keywords *Note `DEC': fixed-point-types. and *Note `FIXED': fixed-point-types. are synonyms for *Note `DECIMAL': fixed-point-types. MySQL treats *Note `DOUBLE': floating-point-types. as a synonym for *Note `DOUBLE PRECISION': floating-point-types. (a nonstandard extension). MySQL also treats *Note `REAL': floating-point-types. as a synonym for *Note `DOUBLE PRECISION': floating-point-types. (a nonstandard variation), unless the `REAL_AS_FLOAT' SQL mode is enabled. The *Note `BIT': bit-type. data type stores bit-field values and is supported for *Note `MyISAM': myisam-storage-engine, *Note `MEMORY': memory-storage-engine, *Note `InnoDB': innodb-storage-engine, and *Note `NDBCLUSTER': mysql-cluster. tables. For information about how MySQL handles assignment of out-of-range values to columns and overflow during expression evaluation, see *Note out-of-range-and-overflow::. For information about numeric type storage requirements, see *Note 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 *Note arithmetic-functions::.  File: manual.info, Node: integer-types, Next: fixed-point-types, Prev: numeric-types, Up: numeric-types 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. This table shows required storage and range for integer types supported by MySQL. Type Storage Minimum Value Maximum Value (Bytes) (Signed/Unsigned) Signed/Unsigned) `TINYINT' 1 `-128' `127' `0' `255' `SMALLINT' 2 `-32768' `32767' `0' `65535' `MEDIUMINT' 3 `-8388608' `8388607' `0' `16777215' `INT' 4 `-2147483648' `2147483647' `0' `4294967295' `BIGINT' 8 `-9223372036854775808' `9223372036854775807' `0' `18446744073709551615'  File: manual.info, Node: fixed-point-types, Next: floating-point-types, Prev: integer-types, Up: numeric-types 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 5.1 stores `DECIMAL' values in binary format. See *Note 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.)  File: manual.info, Node: floating-point-types, Next: bit-type, Prev: fixed-point-types, Up: numeric-types 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 *Note 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.  File: manual.info, Node: bit-type, Next: numeric-type-attributes, Prev: floating-point-types, Up: numeric-types 11.2.4 Bit-Value Type - `BIT' ----------------------------- The `BIT' data type is used to store bit-field 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 *Note bit-field-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''.  File: manual.info, Node: numeric-type-attributes, Next: out-of-range-and-overflow, Prev: bit-type, Up: numeric-types 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, *Note `INT(4)': integer-types. specifies an *Note `INT': integer-types. 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 *Note `SMALLINT(3)': integer-types. has the usual *Note `SMALLINT': integer-types. 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 *Note `INT(4) ZEROFILL': integer-types, a value of `5' is retrieved as `0005'. *Note*: The `ZEROFILL' attribute is ignored when a column is involved in expressions or *Note `UNION': 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 *Note `INT': integer-types. 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' (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'. As of MySQL 5.1.67, negative values for `AUTO_INCREMENT' columns are not supported.  File: manual.info, Node: out-of-range-and-overflow, Prev: numeric-type-attributes, Up: numeric-types 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 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. If you store 256 into a *Note `TINYINT': integer-types. or `TINYINT UNSIGNED' column, MySQL stores 127 or 255, respectively. 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. Column-assignment conversions that occur due to clipping when MySQL is not operating in strict mode are reported as warnings for *Note `ALTER TABLE': alter-table, *Note `LOAD DATA INFILE': load-data, *Note `UPDATE': update, and multiple-row *Note `INSERT': insert. statements. In strict mode, these statements fail, and some or all the values will not be inserted or changed, depending on whether the table is a transactional table and other factors. For details, see *Note server-sql-mode::. In MySQL 5.1, overflow handling during numeric expression evaluation depends on the types of the operands: * Integer overflow results in silent wraparound. * `DECIMAL' overflow results in a truncated result and a warning. * Floating-point overflow produces a `NULL' result. Before MySQL 5.1.24, overflow for some operations results in `+INF', `-INF', or `NaN'. For example, the largest signed *Note `BIGINT': integer-types. value is 9223372036854775807, so the following expression wraps around to the minimum *Note `BIGINT': integer-types. value: mysql> SELECT 9223372036854775807 + 1; +-------------------------+ | 9223372036854775807 + 1 | +-------------------------+ | -9223372036854775808 | +-------------------------+ 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 *Note `DECIMAL': fixed-point-types. 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, it becomes the maximum integer value. If the `NO_UNSIGNED_SUBTRACTION' SQL mode is enabled, the result is negative. mysql> SET sql_mode = ''; mysql> SELECT CAST(0 AS UNSIGNED) - 1; +-------------------------+ | CAST(0 AS UNSIGNED) - 1 | +-------------------------+ | 18446744073709551615 | +-------------------------+ 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.  File: manual.info, Node: date-and-time-types, Next: string-types, Prev: numeric-types, Up: data-types 11.3 Date and Time Types ======================== * Menu: * datetime:: The `DATE', `DATETIME', and `TIMESTAMP' Types * time:: The `TIME' Type * year:: The `YEAR' Type * migrating-to-year4:: `YEAR(2)' Limitations and Migrating to `YEAR(4)' * timestamp-initialization:: Automatic Initialization and Updating for `TIMESTAMP' * fractional-seconds:: Fractional Seconds in Time Values * date-and-time-type-conversion:: Conversion Between Date and Time Types * two-digit-years:: Two-Digit Years in Dates The date and time types for representing temporal values are *Note `DATE': datetime, *Note `TIME': time, *Note `DATETIME': datetime, *Note `TIMESTAMP': datetime, and *Note `YEAR': 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 *Note `TIMESTAMP': datetime. type has special automatic updating behavior, described later. For temporal type storage requirements, see *Note 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 *Note 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 *Note two-digit-years::. * Conversion of values from one temporal type to another occurs according to the rules in *Note 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 *Note `TIME': time. values are clipped to the appropriate endpoint of the *Note `TIME': 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 *Note server-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 *Note `DATE': datetime. or *Note `DATETIME': datetime. column. This is extremely 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' SQL 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' SQL 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 (*Note `DATE': datetime, *Note `DATETIME': datetime, and *Note `TIMESTAMP': datetime.), use of these values produces warnings if the `NO_ZERO_DATE' SQL mode is enabled. This table shows the format of the `zero' value for temporal data types. Data Type `Zero' Value *Note `DATE': `'0000-00-00'' datetime. *Note `TIME': time. `'00:00:00'' *Note `DATETIME': `'0000-00-00 00:00:00'' datetime. *Note `TIMESTAMP': `'0000-00-00 00:00:00'' datetime. *Note `YEAR': year. `0000'  File: manual.info, Node: datetime, Next: time, Prev: date-and-time-types, Up: date-and-time-types 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 *Note 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. 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 *Note time-zone-support::. The `TIMESTAMP' data type offers automatic initialization and updating to the current date and time. For more information, see *Note timestamp-initialization::. A `DATETIME' or `TIMESTAMP' value can include a trailing fractional seconds part in up to microseconds (6 digits) precision. Although this fractional part is recognized, it is discarded from values stored into `DATETIME' or `TIMESTAMP' columns. For information about fractional seconds support in MySQL, see *Note fractional-seconds::. 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 ``:'' delimiter, 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 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 *Note server-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 *Note 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 *Note server-sql-mode::.  File: manual.info, Node: time, Next: year, Prev: datetime, Up: date-and-time-types 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, described in *Note date-and-time-literals::. Some of these formats can include a trailing fractional seconds part in up to microseconds (6 digits) precision. Although this fractional part is recognized, it is discarded from values stored into `TIME' columns. For information about fractional seconds support in MySQL, see *Note fractional-seconds::. 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''. 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 *Note server-sql-mode::.  File: manual.info, Node: year, Next: migrating-to-year4, Prev: time, Up: date-and-time-types 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(4)' or `YEAR(2)' to specify a display width of four or two characters. The default is four characters if no width is given. *Note*: The `YEAR(2)' data type has certain issues that you should consider before choosing to use it. As of MySQL 5.1.65, `YEAR(2)' is deprecated. For more information, see *Note migrating-to-year4::. `YEAR(4)' and `YEAR(2)' differ in display format, but have the same range of values. For 4-digit format, MySQL displays `YEAR' values in `YYYY' format, with a range of `1901' to `2155', or `0000'. For 2-digit format, MySQL displays only the last two (least significant) digits; for example, `70' (1970 or 2070) or `69' (2069). You can specify input `YEAR' values in a variety of formats: * As a 4-digit string in the range `'1901'' to `'2155''. * As a 4-digit number in the range `1901' to `2155'. * As a 1- or 2-digit string in the range `'0'' to `'99''. Values in the ranges `'0'' to `'69'' and `'70'' to `'99'' are converted to `YEAR' values in the ranges `2000' to `2069' and `1970' to `1999'. * As a 1- or 2-digit number in the range `1' to `99'. Values in the ranges `1' to `69' and `70' to `99' are converted to `YEAR' values in the ranges `2001' to `2069' and `1970' to `1999'. Inserting a numeric `0' has a different effect for `YEAR(2)' and `YEAR(4)'. For `YEAR(2)', the result has a display value of `00' and an internal value of `2000'. For `YEAR(4)', the result has a display value of `0000' and an internal value of `0000'. To specify zero for `YEAR(4)' 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()'. Invalid `YEAR' values are converted to `0000'. See also *Note two-digit-years::.  File: manual.info, Node: migrating-to-year4, Next: timestamp-initialization, Prev: year, Up: date-and-time-types 11.3.4 `YEAR(2)' Limitations and Migrating to `YEAR(4)' ------------------------------------------------------- Although the internal range of values for *Note `YEAR(4)': year. and *Note `YEAR(2)': year. is the same (`1901' to `2155', and `0000'), the display width for *Note `YEAR(2)': year. makes that type inherently ambiguous because displayed values indicate only the last two digits of the internal values. The result can be a loss of information under certain circumstances. For this reason, consider avoiding *Note `YEAR(2)': year. throughout your applications and using *Note `YEAR(4)': year. wherever you need a *Note `YEAR': year. data type. This section describes problems that can occur when using *Note `YEAR(2)': year. and provides information about migrating existing *Note `YEAR(2)': year. columns to *Note `YEAR(4)': year. Note that migration will become necessary at some point because support for *Note `YEAR': year. data types with display values other than 4, most notably *Note `YEAR(2)': year, is reduced as of MySQL 5.6.6 and will be removed entirely in a future release. * *Note `YEAR(2)': year. Limitations * Issues with the *Note `YEAR(2)': year. data type include ambiguity of displayed values, and possible loss of information when values are dumped and reloaded or converted to strings. * Displayed *Note `YEAR(2)': year. values can be ambiguous. It is possible for up to three *Note `YEAR(2)': year. 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 *Note `mysqldump': 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 *Note `YEAR(2)': year. or *Note `YEAR(4)': year. data value to string form uses the display width of the *Note `YEAR': year. type. Suppose that *Note `YEAR(2)': year. and *Note `YEAR(4)': year. 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 *Note `YEAR(2)': year. to string. * Values outside the range from `1970' to `2069' are stored incorrectly when inserted into a *Note `YEAR(2)': year. column in a *Note `CSV': csv-storage-engine. table. For example, inserting `2111' results in a display value of `11' but an internal value of `2011'. To avoid these problems, use *Note `YEAR(4)': year. rather than *Note `YEAR(2)': year. Suggestions regarding migration strategies appear later in this section. * Migrating from *Note `YEAR(2)': year. to *Note `YEAR(4)': year. * Should you decide to convert *Note `YEAR(2)': year. columns to *Note `YEAR(4)': year, use *Note `ALTER TABLE': alter-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. Remember to include any column attributes such as `NOT NULL' or `DEFAULT': ALTER TABLE t1 MODIFY ycol YEAR(4) NOT NULL DEFAULT '1970'; The *Note `ALTER TABLE': alter-table. statement converts the table without changing *Note `YEAR(2)': year. values. If the server is a replication master, the *Note `ALTER TABLE': alter-table. statement replicates to slaves and makes the corresponding table change on each one. One migration method should be avoided: Do not dump your data with *Note `mysqldump': mysqldump. and reload the dump file after upgrading. This has the potential to change *Note `YEAR(2)': year. values, as described previously. A migration from *Note `YEAR(2)': year. to *Note `YEAR(4)': year. should also involve examining application code for the possibility of changed behavior under conditions such as these: * Code that expects selecting a *Note `YEAR': year. column to produce exactly two digits. * Code that does not account for different handling for inserts of numeric `0': Inserting `0' into *Note `YEAR(2)': year. or *Note `YEAR(4)': year. results in an internal value of `2000' or `0000', respectively.  File: manual.info, Node: timestamp-initialization, Next: fractional-seconds, Prev: migrating-to-year4, Up: date-and-time-types 11.3.5 Automatic Initialization and Updating for `TIMESTAMP' ------------------------------------------------------------ *Note*: In older versions of MySQL (prior to 4.1), the properties of the *Note `TIMESTAMP': datetime. data type differed significantly in several ways from what is described in this section (see the `MySQL 3.23, 4.0, 4.1 Reference Manual' for details); these include syntax extensions which are deprecated in MySQL 5.1, and no longer supported in MySQL 5.5. This has implications for performing a dump and restore or replicating between MySQL Server versions. If you are using columns that are defined using the old *Note `TIMESTAMP(N)': datetime. syntax, see *Note upgrading-from-previous-series::, prior to upgrading to MySQL 5.1 or later. The *Note `TIMESTAMP': datetime. data type offers automatic initialization and updating to the current date and time (that is, the current timestamp). You can choose whether to use these properties and which column should have them: * One *Note `TIMESTAMP': datetime. column in a table can have the current timestamp as the default value for initializing the column, as the auto-update value, or both. It is not possible to have the current timestamp be the default value for one column and the auto-update value for another column. * If the column is auto-initialized, it is set to the current timestamp for inserted rows that specify no value for the column. * If the column is auto-updated, it is automatically updated to the current timestamp when the value of any other column in the row is changed from its current value. The column remains unchanged if all other columns are set to their current values. To prevent the column from updating when other columns change, explicitly set it to its current value. To update the 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, you can initialize or update any *Note `TIMESTAMP': 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. 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 *Note `TIMESTAMP': 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 that use `DEFAULT 0' do not work if the `NO_ZERO_DATE' SQL mode is enabled because that mode causes `zero' date values (specified, for example, as `0' `'0000-00-00 00:00:00'') to be rejected. Be aware that the `TRADITIONAL' SQL mode includes `NO_ZERO_DATE'. The following rules describe the possibilities for defining the first *Note `TIMESTAMP': datetime. column in a table with the current timestamp for both the default and auto-update values, for one but not the other, or for neither: * 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 ); * With neither `DEFAULT CURRENT_TIMESTAMP' nor `ON UPDATE CURRENT_TIMESTAMP', it is the same as specifying both `DEFAULT CURRENT_TIMESTAMP' and `ON UPDATE CURRENT_TIMESTAMP'. CREATE TABLE t1 ( ts 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 ); 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 ); * 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 ); * With an `ON UPDATE CURRENT_TIMESTAMP' clause but no `DEFAULT' clause, the column is automatically updated to the current timestamp. The default is 0 unless the column is defined with the `NULL' attribute, in which case the default is `NULL'. CREATE TABLE t1 ( ts TIMESTAMP ON UPDATE CURRENT_TIMESTAMP -- default 0 ); CREATE TABLE t2 ( ts TIMESTAMP NULL ON UPDATE CURRENT_TIMESTAMP -- default NULL ); It need not be the first *Note `TIMESTAMP': datetime. column in a table that is automatically initialized or updated to the current timestamp. However, to specify automatic initialization or updating for a different *Note `TIMESTAMP': datetime. column, you must suppress the automatic properties for the first one. Then, for the other *Note `TIMESTAMP': datetime. column, the rules for the `DEFAULT' and `ON UPDATE' clauses are the same as for the first *Note `TIMESTAMP': datetime. column, except that if you omit both clauses, no automatic initialization or updating occurs. To suppress automatic properties for the first *Note `TIMESTAMP': datetime. column, 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'. 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 *Note `TIMESTAMP': datetime. 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. * *Note `TIMESTAMP': datetime. Initialization and the `NULL' Attribute * By default, *Note `TIMESTAMP': datetime. columns are `NOT NULL', cannot contain `NULL' values, and assigning `NULL' assigns the current timestamp. To permit a *Note `TIMESTAMP': datetime. 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 *Note `TIMESTAMP': datetime. column not declared with the `NULL' attribute, `DEFAULT NULL' is invalid.) If a *Note `TIMESTAMP': datetime. column permits `NULL' values, assigning `NULL' sets it to `NULL', not to the current timestamp. The following table contains several *Note `TIMESTAMP': datetime. 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 *Note `TIMESTAMP': datetime. 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 *Note `TIMESTAMP': datetime. 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 *Note `TIMESTAMP': datetime. 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 *Note `TIMESTAMP': datetime. column in either table to the current timestamp at insert time, explicitly assign it that value. For example: INSERT INTO t1 VALUES (NOW()); INSERT INTO t2 VALUES (CURRENT_TIMESTAMP);  File: manual.info, Node: fractional-seconds, Next: date-and-time-type-conversion, Prev: timestamp-initialization, Up: date-and-time-types 11.3.6 Fractional Seconds in Time Values ---------------------------------------- A trailing fractional seconds part is permissible for temporal values in contexts such as literal values, and in the arguments to or return values from some temporal functions. Example: mysql> SELECT MICROSECOND('2010-12-10 14:12:09.019473'); +-------------------------------------------+ | MICROSECOND('2010-12-10 14:12:09.019473') | +-------------------------------------------+ | 19473 | +-------------------------------------------+ However, when MySQL stores a value into a column of any temporal data type, it discards any fractional part and does not store it.  File: manual.info, Node: date-and-time-type-conversion, Next: two-digit-years, Prev: fractional-seconds, Up: date-and-time-types 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 *Note `DATE': datetime, *Note `DATETIME': datetime, and *Note `TIMESTAMP': datetime. values all can be specified using the same set of formats, the types do not all have the same range of values. *Note `TIMESTAMP': datetime. 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 *Note `DATE': datetime. or *Note `DATETIME': datetime. value, is not valid as a *Note `TIMESTAMP': datetime. value and is converted to `0'. Conversion of *Note `DATE': datetime. values: * Conversion to a *Note `DATETIME': datetime. or *Note `TIMESTAMP': datetime. value adds a time part of `'00:00:00'' because the *Note `DATE': datetime. value contains no time information. * Conversion to a *Note `TIME': time. value is not useful; the result is `'00:00:00''. Conversion of *Note `DATETIME': datetime. and *Note `TIMESTAMP': datetime. values: * Conversion to a *Note `DATE': datetime. value discards the time part because the *Note `DATE': datetime. type contains no time information. * Conversion to a *Note `TIME': time. value discards the date part because the *Note `TIME': time. type contains no date information. Conversion of *Note `TIME': time. values: MySQL converts a time value to a date or date-and-time value by parsing the string value of the time as a date or date-and-time. This is unlikely to be useful. For example, `'23:12:31'' interpreted as a date becomes `'2032-12-31''. Time values not valid as dates become `'0000-00-00'' or `NULL'. Prior to MySQL 5.1.18, when *Note `DATE': datetime. values are compared with *Note `DATETIME': datetime. values, the time portion of the *Note `DATETIME': datetime. value is ignored, or the comparison could be performed as a string compare. Starting from MySQL 5.1.18, a *Note `DATE': datetime. value is coerced to the *Note `DATETIME': datetime. type by adding the time portion as `'00:00:00''. To mimic the old behavior, use the `CAST()' function to cause the comparison operands to be treated as previously. For example: DATE_COL = CAST(DATETIME_COL AS DATE) Conversion of *Note `TIME': time. or *Note `DATETIME': datetime. values to numeric form (for example, by adding `+0') results in a double-precision value with a microseconds part of `.000000': mysql> SELECT CURTIME(), CURTIME()+0; +-----------+---------------+ | CURTIME() | CURTIME()+0 | +-----------+---------------+ | 10:41:36 | 104136.000000 | +-----------+---------------+ mysql> SELECT NOW(), NOW()+0; +---------------------+-----------------------+ | NOW() | NOW()+0 | +---------------------+-----------------------+ | 2007-11-30 10:41:47 | 20071130104147.000000 | +---------------------+-----------------------+  File: manual.info, Node: two-digit-years, Prev: date-and-time-type-conversion, Up: date-and-time-types 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 *Note `DATETIME': datetime, *Note `DATE': datetime, and *Note `TIMESTAMP': datetime. 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 *Note `YEAR': year. values that have two-digit years. Some functions like `MIN()' and `MAX()' convert a *Note `YEAR': 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 *Note `YEAR': year. to four-digit year format.  File: manual.info, Node: string-types, Next: data-type-defaults, Prev: date-and-time-types, Up: data-types 11.4 String Types ================= * Menu: * char:: The `CHAR' and `VARCHAR' Types * binary-varbinary:: The `BINARY' and `VARBINARY' Types * blob:: The `BLOB' and `TEXT' Types * enum:: The `ENUM' Type * set:: The `SET' Type The string types are *Note `CHAR': char, *Note `VARCHAR': char, *Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, *Note `BLOB': blob, *Note `TEXT': blob, *Note `ENUM': enum, and *Note `SET': set. This section describes how these types work and how to use them in your queries. For string type storage requirements, see *Note storage-requirements::.  File: manual.info, Node: char, Next: binary-varbinary, Prev: string-types, Up: string-types 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 *Note 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 *Note server-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'). This table illustrates the difference between `CHAR' and `VARCHAR' storage requirements by showing the required storage for various string values in `CHAR(4)' and `VARCHAR(4)' columns. 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. 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 `PADSPACE'. This means that all `CHAR', `VARCHAR', and `TEXT' values in MySQL 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 *Note charset::. 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.  File: manual.info, Node: binary-varbinary, Next: blob, Prev: char, Up: string-types 11.4.2 The `BINARY' and `VARBINARY' Types ----------------------------------------- The `BINARY' and `VARBINARY' types are similar to *Note `CHAR': char. and *Note `VARCHAR': char, except that they contain binary strings rather than nonbinary strings. That is, they contain byte strings rather than character strings. This means that they have no character set, and sorting and comparison 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 *Note `CHAR': char. and *Note `VARCHAR': char, 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 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 no character set or collation. For information about differences between nonbinary string binary collations and binary strings, see *Note 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 *Note server-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 *Note `BLOB': blob. data types instead.  File: manual.info, Node: blob, Next: enum, Prev: binary-varbinary, Up: string-types 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 *Note storage-requirements::. `BLOB' values are treated as binary strings (byte strings). They have no character set, and sorting and comparison 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, 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 *Note server-sql-mode::. Beginning with MySQL 5.1.24, truncation of excess trailing spaces from values to be inserted into *Note `TEXT': blob. 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 *Note `VARBINARY': binary-varbinary. column that can be as large as you like. Similarly, you can regard a `TEXT' column as a *Note `VARCHAR': char. column. `BLOB' and `TEXT' differ from *Note `VARBINARY': binary-varbinary. and *Note `VARCHAR': char. in the following ways: * For indexes on `BLOB' and `TEXT' columns, you must specify an index prefix length. For *Note `CHAR': char. and *Note `VARCHAR': char, a prefix length is optional. See *Note 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 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 *Note 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 *Note `SELECT *': 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 *Note `mysql': mysql. and *Note `mysqldump': mysqldump. enable you to change the client-side `max_allowed_packet' value. See *Note server-parameters::, *Note mysql::, and *Note 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 *Note 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 *Note 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/').  File: manual.info, Node: enum, Next: set, Prev: blob, Up: string-types 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 *Note 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 *Note enum-limits::. * Using `ENUM' columns in `ORDER BY' clauses requires extra care, as explained in *Note enum-sorting::. * 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 *Note `SELECT': 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. This table shows possible values for a column specified as `ENUM('Mercury', 'Venus', 'Earth')'. The table also shows the index of each value. Value Index `NULL' `NULL' `''' 0 `'Mercury'' 1 `'Venus'' 2 `'Earth'' 3 An *Note `ENUM': 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 *Note `ENUM': enum. and *Note `SET': set. columns considered as a group. For more information on these limits, see *Note 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 *Note `LOAD DATA': 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 *Note `SHOW COLUMNS FROM TBL_NAME LIKE 'ENUM_COL'': show-columns. 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 *Note 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 *Note 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. * 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)'. * Limitations * An enumeration value cannot be an expression, even one that evaluates to a string value. For example, this *Note `CREATE TABLE': 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 *Note `TINYINT': integer-types. or *Note `SMALLINT': integer-types. 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 *Note 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.  File: manual.info, Node: set, Prev: enum, Up: string-types 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 *Note `SET': set. column can have a maximum of 64 distinct members. A table can have no more than 255 unique element list definitions among its *Note `ENUM': enum. and *Note `SET': set. columns considered as a group. For more information on this limit, see *Note 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. This table shows decimal and binary values for members of a column specified as `SET('a','b','c','d')'. `SET' Decimal Value Binary Value Member `'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 *Note c-api-data-structures::.  File: manual.info, Node: data-type-defaults, Next: storage-requirements, Prev: string-types, Up: data-types 11.5 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 a *Note `TIMESTAMP': datetime. column. See *Note timestamp-initialization::. *Note `BLOB': blob. and *Note `TEXT': blob. 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'), but also assigns it 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 *Note `INSERT': insert. or *Note `REPLACE': replace. statement includes no value for the column, or an *Note `UPDATE': 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 *Note server-sql-mode::. For a given table, you can use the *Note `SHOW CREATE TABLE': 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 *Note `TIMESTAMP': datetime, the default is the appropriate `zero' value for the type. For the first *Note `TIMESTAMP': datetime. column in a table, the default value is the current date and time. See *Note date-and-time-types::. * For string types other than *Note `ENUM': enum, the default value is the empty string. For *Note `ENUM': 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'.  File: manual.info, Node: storage-requirements, Next: choosing-types, Prev: data-type-defaults, Up: data-types 11.6 Data Type Storage Requirements =================================== The storage requirements for data vary, according to the storage engine being used for the table in question. Different storage engines use different methods for recording the raw data and different data types. In addition, some engines may compress the information in a given row, either on a column or entire row basis, making calculation of the storage requirements for a given table or column structure. However, all storage engines must communicate and exchange information on a given row within a table using the same structure, and this information is consistent, irrespective of the storage engine used to write the information to disk. This sections includes some guideliness and information for the storage requirements for each data type supported by MySQL, including details for the internal format and the sizes used by storage engines that used a fixed size representation for different 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 *Note `BLOB': blob. or *Note `TEXT': blob. columns, which contribute only 9 to 12 bytes toward this size. For *Note `BLOB': 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 *Note storage-engines::, and *Note column-count-limit::. *Important*: For tables using the *Note `NDBCLUSTER': mysql-cluster. storage engine, there is the factor of _4-byte alignment_ to be taken into account when calculating storage requirements. This means that all *Note `NDB': mysql-cluster. data storage is done in multiples of 4 bytes. Thus, a column value that would take 15 bytes in a table using a storage engine other than *Note `NDB': mysql-cluster. requires 16 bytes in an *Note `NDB': mysql-cluster. table. This requirement applies in addition to any other considerations that are discussed in this section. For example, in *Note `NDBCLUSTER': mysql-cluster. tables, the *Note `TINYINT': integer-types, *Note `SMALLINT': integer-types, *Note `MEDIUMINT': integer-types, and *Note `INTEGER': integer-types. (*Note `INT': integer-types.) column types each require 4 bytes storage per record due to the alignment factor. An exception to this rule is the *Note `BIT': bit-type. type, which is _not_ 4-byte aligned. In MySQL Cluster tables, a `BIT(M)' column takes M bits of storage space. However, if a table definition contains 1 or more *Note `BIT': bit-type. columns (up to 32 *Note `BIT': bit-type. columns), then *Note `NDBCLUSTER': mysql-cluster. reserves 4 bytes (32 bits) per row for these. If a table definition contains more than 32 *Note `BIT': bit-type. columns (up to 64 such columns), then *Note `NDBCLUSTER': mysql-cluster. reserves 8 bytes (that is, 64 bits) per row. In addition, while a `NULL' itself does not require any storage space, *Note `NDBCLUSTER': mysql-cluster. reserves 4 bytes per row if the table definition contains any columns defined as `NULL', up to 32 `NULL' columns. (If a MySQL Cluster table is defined with more than 32 `NULL' columns up to 64 `NULL' columns, then 8 bytes per row is reserved.) When calculating storage requirements for MySQL Cluster tables, you must also remember that every table using the *Note `NDBCLUSTER': mysql-cluster. storage engine requires a primary key; if no primary key is defined by the user, then a `hidden' primary key will be created by *Note `NDB': mysql-cluster. This hidden primary key consumes 31-35 bytes per table record. You may find the `ndb_size.pl' utility to be useful for estimating *Note `NDB': mysql-cluster. storage requirements. This Perl script connects to a current MySQL (non-Cluster) database and creates a report on how much space that database would require if it used the *Note `NDBCLUSTER': mysql-cluster. storage engine. See *Note mysql-cluster-programs-ndb-size-pl::, for more information. * Storage Requirements for Numeric Types * This table shows storage required for numeric data types. Data Type Storage Required *Note `TINYINT': 1 byte integer-types. *Note `SMALLINT': 2 bytes integer-types. *Note `MEDIUMINT': 3 bytes integer-types. *Note `INT': integer-types, 4 bytes *Note `INTEGER': integer-types. *Note `BIGINT': 8 bytes integer-types. `FLOAT(P)' 4 bytes if 0 <= P <= 24, 8 bytes if 25 <= P <= 53 *Note `FLOAT': 4 bytes floating-point-types. `DOUBLE [PRECISION]', *Note 8 bytes `REAL': floating-point-types. `DECIMAL(M,D)', Varies; see following discussion `NUMERIC(M,D)' `BIT(M)' approximately (M+7)/8 bytes Values for *Note `DECIMAL': fixed-point-types. (and *Note `NUMERIC': fixed-point-types.) 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. This table shows storage required by excess/leftover digits. Leftover Digits Number of Bytes 0 0 1 1 2 1 3 2 4 2 5 3 6 3 7 4 8 4 * Storage Requirements for Date and Time Types * This table shows storage required for date and time types. Data Type Storage Required *Note `DATE': datetime. 3 bytes *Note `TIME': time. 3 bytes *Note `DATETIME': datetime. 8 bytes *Note `TIMESTAMP': datetime. 4 bytes *Note `YEAR': year. 1 byte For details about internal representation of temporal values, see MySQL Internals: Important Algorithms and Structures (http://dev.mysql.com/doc/internals/en/algorithms.html). * Storage Requirements for String Types * 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. This table shows storage required for string types. 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 `BINARY(M)' M bytes, 0 `<= M <=' 255 `VARCHAR(M)', `VARBINARY(M)' L + 1 bytes if column values require 0 - 255 bytes, L + 2 bytes if values may require more than 255 bytes *Note `TINYBLOB': blob, L + 1 bytes, where L < 2^8 *Note `TINYTEXT': blob. *Note `BLOB': blob, *Note L + 2 bytes, where L < 2^16 `TEXT': blob. *Note `MEDIUMBLOB': blob, L + 3 bytes, where L < 2^24 *Note `MEDIUMTEXT': blob. *Note `LONGBLOB': blob, L + 4 bytes, where L < 2^32 *Note `LONGTEXT': blob. `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 *Note `MEDIUMTEXT': blob. 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 *Note `CHAR': char, *Note `VARCHAR': char, or *Note `TEXT': blob. column value, you must take into account the character set used for that column and whether the value contains multi-byte characters. In particular, when using the `utf8' Unicode character set, you must keep in mind that not all characters use the same number of bytes and can require up to three bytes per character. For a breakdown of the storage used for different categories of `utf8' characters, see *Note charset-unicode::. *Note `VARCHAR': char, *Note `VARBINARY': binary-varbinary, and the *Note `BLOB': blob. and *Note `TEXT': blob. 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 multi-byte 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 *Note `VARCHAR': char. or *Note `VARBINARY': binary-varbinary. column is subject to the maximum row size of 65,535 bytes, which is shared among all columns. For a *Note `VARCHAR': char. column that stores multi-byte characters, the effective maximum number of _characters_ is less. For example, `utf8' characters can require up to three bytes per character, so a *Note `VARCHAR': char. column that uses the `utf8' character set can be declared to be a maximum of 21,844 characters. See *Note column-count-limit::. The *Note `NDBCLUSTER': mysql-cluster. storage engine in MySQL 5.1 supports variable-width columns. This means that a *Note `VARCHAR': char. column in a MySQL Cluster table requires the same amount of storage as it would using 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 6 bytes for the same column value in a `MyISAM' table). This represents a change in behavior from earlier versions of *Note `NDBCLUSTER': mysql-cluster, where a `VARCHAR(50)' column would require 52 bytes storage per record regardless of the length of the string being stored. *Note `TEXT': blob. and *Note `BLOB': blob. columns are implemented differently in the NDB Cluster storage engine, wherein each row in a *Note `TEXT': blob. 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 *Note `TEXT': blob. 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 *Note `ENUM': 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 *Note enum::. The size of a *Note `SET': 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 *Note `SET': set. can have a maximum of 64 members. See *Note set::.  File: manual.info, Node: choosing-types, Next: other-vendor-data-types, Prev: storage-requirements, Up: data-types 11.7 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 *Note `DECIMAL': fixed-point-types. columns are done with precision of 65 decimal (base 10) digits. See *Note numeric-type-overview::. If accuracy is not too important or if speed is the highest priority, the *Note `DOUBLE': floating-point-types. type may be good enough. For high precision, you can always convert to a fixed-point type stored in a *Note `BIGINT': integer-types. This enables you to do all calculations with 64-bit integers and then convert results back to floating-point values as necessary. `PROCEDURE ANALYSE' can be used to obtain suggestions for optimal column data types. For more information, see *Note procedure-analyse::.  File: manual.info, Node: other-vendor-data-types, Prev: choosing-types, Up: data-types 11.8 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. This table provides a mapping of MySQL data types to data types from other vendors. Other Vendor Type MySQL Type *Note `BOOL': *Note `TINYINT': integer-types. integer-types. *Note `BOOLEAN': *Note `TINYINT': integer-types. integer-types. `CHARACTER VARYING(M)' `VARCHAR(M)' *Note `FIXED': *Note `DECIMAL': fixed-point-types. fixed-point-types. *Note `FLOAT4': *Note `FLOAT': floating-point-types. floating-point-types. *Note `FLOAT8': *Note `DOUBLE': floating-point-types. floating-point-types. *Note `INT1': *Note `TINYINT': integer-types. integer-types. *Note `INT2': *Note `SMALLINT': integer-types. integer-types. *Note `INT3': *Note `MEDIUMINT': integer-types. integer-types. *Note `INT4': *Note `INT': integer-types. integer-types. `INT8' *Note `BIGINT': integer-types. `LONG VARBINARY' *Note `MEDIUMBLOB': blob. `LONG VARCHAR' *Note `MEDIUMTEXT': blob. `LONG' *Note `MEDIUMTEXT': blob. *Note `MIDDLEINT': *Note `MEDIUMINT': integer-types. integer-types. *Note `NUMERIC': *Note `DECIMAL': fixed-point-types. 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)  File: manual.info, Node: functions, Next: sql-syntax, Prev: data-types, Up: Top 12 Functions and Operators ************************** * Menu: * func-op-summary-ref:: Function and Operator Reference * type-conversion:: Type Conversion in Expression Evaluation * non-typed-operators:: Operators * control-flow-functions:: Control Flow Functions * string-functions:: String Functions * numeric-functions:: Numeric Functions and Operators * date-and-time-functions:: Date and Time Functions * mysql-calendar:: What Calendar Is Used By MySQL? * fulltext-search:: Full-Text Search Functions * cast-functions:: Cast Functions and Operators * xml-functions:: XML Functions * bit-functions:: Bit Functions * encryption-functions:: Encryption and Compression Functions * information-functions:: Information Functions * miscellaneous-functions:: Miscellaneous Functions * group-by-functions-and-modifiers:: Functions and Modifiers for Use with `GROUP BY' Clauses * spatial-extensions:: Spatial Extensions * precision-math:: Precision Math Expressions can be used at several points in SQL (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_sql) statements, such as in the `ORDER BY' or `HAVING' clauses of *Note `SELECT': select. statements, in the `WHERE' clause of a *Note `SELECT': select, *Note `DELETE': delete, or *Note `UPDATE': update. statement, or in *Note `SET': set-statement. 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 *Note stored-routines::, and *Note adding-functions::. See *Note 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 *Note server-sql-mode::.) Individual client programs can request this behavior by using the `CLIENT_IGNORE_SPACE' option for *Note `mysql_real_connect()': 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 *Note `mysql': 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  File: manual.info, Node: func-op-summary-ref, Next: type-conversion, Prev: functions, Up: functions 12.1 Function and Operator Reference ==================================== *Functions/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 `ASCII()' Return numeric value of left-most character `ASIN()' Return the arc sine `=' Assign a value (as part of a *Note `SET': set-statement. statement, or as part of the `SET' clause in an *Note `UPDATE': update. statement) `:=' Assign a value `ATAN2()', `ATAN()' Return the arc tangent of the two arguments `ATAN()' Return the arc tangent `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 `~' Invert bits `|' Bitwise OR `^' Bitwise XOR `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 `CHAR_LENGTH()' Return number of characters in argument `CHAR()' Return the character for each integer passed `CHARACTER_LENGTH()' A 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_WS()' Return concatenate with separator `CONCAT()' Return concatenated string `CONNECTION_ID()' Return the connection ID (thread ID) for the connection `CONV()' Convert numbers between different number bases `CONVERT_TZ()' Convert from one timezone to another `CONVERT()' Cast a value as a certain type `COS()' Return the cosine `COT()' Return the cotangent `COUNT(DISTINCT)' Return the count of a number of different values `COUNT()' Return a count of the number of rows returned `CRC32()' Compute a cyclic redundancy check value `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_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 `DATE()' Extract the date part of a date or datetime expression `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()' Decodes a string encrypted using ENCODE() `DEFAULT()' Return the default value for a table column `DEGREES()' Convert radians to degrees `DES_DECRYPT()' Decrypt a string `DES_ENCRYPT()' Encrypt a string `DIV' Integer division `/' Division operator `ELT()' Return string at index number `ENCODE()' Encode a string `ENCRYPT()' Encrypt a string `<=>' NULL-safe equal to operator `=' Equal operator `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 `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_DAYS()' Convert a day number to a date `FROM_UNIXTIME()' Format UNIX timestamp as a date `GET_FORMAT()' Return a date format string `GET_LOCK()' Get a named lock `>=' Greater than or equal operator `>' Greater than operator `GREATEST()' Return the largest argument `GROUP_CONCAT()' Return a concatenated string `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 `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 `INTERVAL()' Return the index of the argument that is less than the first argument `IS_FREE_LOCK()' Checks whether the named lock is free `IS NOT NULL' NOT NULL value test `IS NOT' Test a value against a boolean `IS NULL' NULL value test `IS_USED_LOCK()' Checks whether the named lock is in use. Return connection identifier if true. `IS' Test a value against a boolean `ISNULL()' Test whether the argument is NULL `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 shift `LEFT()' Return the leftmost number of characters as specified `LENGTH()' Return the length of a string in bytes `<=' Less than or equal operator `<' Less than operator `LIKE' Simple pattern matching `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 `LOG10()' Return the base-10 logarithm of the argument `LOG2()' Return the base-2 logarithm of the argument `LOG()' Return the natural logarithm of the first 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' MAKETIME() `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 `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 `MOD()' Return the remainder `% or MOD' Modulo operator `MONTH()' Return the month from the date passed `MONTHNAME()' Return the name of the month `NAME_CONST()' Causes the column to have the given name `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 `NOT', `!' Negates value `NOW()' Return the current date and time `NULLIF()' Return NULL if expr1 = expr2 `OCT()' Return a string containing octal representation of a number `OCTET_LENGTH()' A 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 `PASSWORD()' Calculate and return a password string `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 `POSITION()' A synonym for LOCATE() `POW()' Return the argument raised to the specified power `POWER()' Return the argument raised to the specified power *Note `PROCEDURE ANALYSE()': Analyze the results of a query procedure-analyse. `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 `REGEXP' Pattern matching using regular expressions `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 shift `RIGHT()' Return the specified rightmost number of characters `RLIKE' Synonym for REGEXP `ROUND()' Round the argument `ROW_COUNT()' The number of rows updated `RPAD()' Append string the specified number of times `RTRIM()' Remove trailing spaces `SCHEMA()' A 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 `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 `STD()' Return the population standard deviation `STDDEV_POP()' Return the population standard deviation `STDDEV_SAMP()' Return the sample standard deviation `STDDEV()' Return the population standard deviation `STR_TO_DATE()' Convert a string to a date `STRCMP()' Compare two strings `SUBDATE()' A synonym for DATE_SUB() when invoked with three arguments `SUBSTR()' Return the substring as specified `SUBSTRING_INDEX()' Return a substring from a string before the specified number of occurrences of the delimiter `SUBSTRING()' Return the substring as specified `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_FORMAT()' Format as time `TIME_TO_SEC()' Return the argument converted to seconds `TIME()' Extract the time portion of the expression passed `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_DAYS()' Return the date argument converted to days `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_SHORT()' Return an integer-valued universal identifier `UUID()' Return a Universal Unique Identifier (UUID) `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()' Returns a string that indicates the MySQL server version `WEEK()' Return the week number `WEEKDAY()' Return the weekday index `WEEKOFYEAR()' Return the calendar week of the date (0-53) `XOR' Logical XOR `YEAR()' Return the year `YEARWEEK()' Return the year and week  File: manual.info, Node: type-conversion, Next: non-typed-operators, Prev: func-op-summary-ref, Up: functions 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. 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 *Note `TIMESTAMP': datetime. or *Note `DATETIME': 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. Note that 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. * 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 *Note date-and-time-type-conversion::. 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 will not be converted implicitly to a float-point number: mysql> SELECT CAST('18015376320243459' AS UNSIGNED) = 18015376320243459; -> 1 For more information about floating-point comparisons, see *Note problems-with-float::. Implicit conversion of a numeric or temporal value to a string produces a binary string (a *Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, or *Note `BLOB': blob. value). Such implicit conversions to string typically occur for functions that are passed numeric or temporal values when string values are more usual, and thus can have effects beyond the type of the converted value. Consider the expression `CONCAT(1, 'abc')'. The numeric argument `1' is converted to the binary string `'1'' and the concatenation of that value with the nonbinary string `'abc'' produces the binary string `'1abc''.  File: manual.info, Node: non-typed-operators, Next: control-flow-functions, Prev: type-conversion, Up: functions 12.3 Operators ============== * Menu: * operator-precedence:: Operator Precedence * comparison-operators:: Comparison Functions and Operators * logical-operators:: Logical Operators * assignment-operators:: Assignment Operators *Operators* Name Description `AND', `&&' Logical AND `=' Assign a value (as part of a *Note `SET': set-statement. statement, or as part of the `SET' clause in an *Note `UPDATE': 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 `~' Invert bits `|' Bitwise OR `^' Bitwise XOR `CASE' Case operator `DIV' Integer division `/' Division operator `<=>' NULL-safe equal to operator `=' Equal operator `>=' Greater than or equal operator `>' Greater than operator `IS NOT NULL' NOT NULL value test `IS NOT' Test a value against a boolean `IS NULL' NULL value test `IS' Test a value against a boolean `<<' Left shift `<=' Less than or equal operator `<' Less than operator `LIKE' Simple pattern matching `-' Minus operator `% or MOD' Modulo operator `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 `NOT', `!' Negates value `||', `OR' Logical OR `+' Addition operator `REGEXP' Pattern matching using regular expressions `>>' Right shift `RLIKE' Synonym for REGEXP `SOUNDS LIKE' Compare sounds `*' Multiplication operator `-' Change the sign of the argument `XOR' Logical XOR  File: manual.info, Node: operator-precedence, Next: comparison-operators, Prev: non-typed-operators, Up: non-typed-operators 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 `:='. *Note set-statement::, and *Note user-variables::, explain how MySQL determines which interpretation of `=' should apply. 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 *Note server-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  File: manual.info, Node: comparison-operators, Next: logical-operators, Prev: operator-precedence, Up: non-typed-operators 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 `<=>' NULL-safe equal to operator `=' Equal operator `>=' Greater than or equal operator `>' Greater than 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 NOT NULL' NOT NULL value test `IS NOT' Test a value against a boolean `IS NULL' NULL value test `IS' Test a value against a boolean `ISNULL()' Test whether the argument is NULL `LEAST()' Return the smallest argument `<=' Less than or equal operator `<' Less than 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: = > < >= <= <> != For examples of row comparisons, see *Note row-subqueries::. Some of the functions in this section return values other than `1' (`TRUE'), `0' (`FALSE'), or `NULL'. For example, `LEAST()' and `GREATEST()'. However, the value they return is based on comparison operations performed according to the rules described in *Note type-conversion::. 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 *Note 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 * `<=>' `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'. mysql> SELECT 1 <=> 1, NULL <=> NULL, 1 <=> NULL; -> 1, 1, 0 mysql> SELECT 1 = 1, NULL = NULL, 1 = NULL; -> 1, NULL, NULL * `<>', `!=' Not equal: mysql> SELECT '.01' <> '0.01'; -> 1 mysql> SELECT .01 <> '0.01'; -> 0 mysql> SELECT 'zapp' <> 'zappp'; -> 1 * `<=' Less than or equal: mysql> SELECT 0.1 <= 2; -> 1 * `<' Less than: mysql> SELECT 2 < 2; -> 0 * `>=' Greater than or equal: mysql> SELECT 2 >= 2; -> 1 * `>' Greater than: mysql> SELECT 2 > 2; -> 0 * `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 (the default), 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 *Note information-functions::. If no `AUTO_INCREMENT' value was successfully inserted, the *Note `SELECT': 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 *Note server-system-variables::. * For *Note `DATE': datetime. and *Note `DATETIME': 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 *Note connector-odbc-usagenotes-functionality-last-insert-id::, and the description for the `FLAG_AUTO_IS_NULL' option at *Note connector-odbc-configuration-connection-parameters::. * `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 *Note 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 *Note `DATETIME': datetime. to two *Note `DATE': datetime. values, convert the *Note `DATE': datetime. values to *Note `DATETIME': datetime. values. If you use a string constant such as `'2001-1-1'' in a comparison to a *Note `DATE': datetime, cast the string to a *Note `DATE': datetime. * `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. 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 *Note 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 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 *Note 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 false.) 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 the return value is used in an *Note `INTEGER': integer-types. context or all arguments are integer-valued, they are compared as integers. * If the return value is used in a *Note `REAL': floating-point-types. context or all arguments are real-valued, they are compared as reals. * 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. 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' Note that the preceding conversion rules can produce strange results in some borderline cases: mysql> SELECT CAST(LEAST(3600, 9223372036854775808.0) as SIGNED); -> -9223372036854775808 This happens because MySQL reads `9223372036854775808.0' in an integer context. The integer representation is not good enough to hold the value, so it wraps to a signed integer.  File: manual.info, Node: logical-operators, Next: assignment-operators, Prev: comparison-operators, Up: non-typed-operators 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 && 1; -> 1 mysql> SELECT 1 && 0; -> 0 mysql> SELECT 1 && NULL; -> NULL mysql> SELECT 0 && NULL; -> 0 mysql> SELECT NULL && 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 || 1; -> 1 mysql> SELECT 1 || 0; -> 1 mysql> SELECT 0 || 0; -> 0 mysql> SELECT 0 || NULL; -> NULL mysql> SELECT 1 || 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)'.  File: manual.info, Node: assignment-operators, Prev: logical-operators, Up: non-typed-operators 12.3.4 Assignment Operators --------------------------- *Assignment Operators* Name Description `=' Assign a value (as part of a *Note `SET': set-statement. statement, or as part of the `SET' clause in an *Note `UPDATE': 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 *Note `SET': set-statement. 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 *Note `SET': set-statement. 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 *Note `SELECT': select, such as *Note `UPDATE': 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. *Note 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 *Note `SET': set-statement. 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 *Note `SET': set-statement. 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 *Note `SET': set-statement. statement. In the `SET' clause of an *Note `UPDATE': 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 *Note `UPDATE': update. are met. You can make multiple assignments in the same `SET' clause of an *Note `UPDATE': 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 *Note set-statement::, *Note update::, and *Note subqueries::.  File: manual.info, Node: control-flow-functions, Next: string-functions, Prev: non-typed-operators, Up: functions 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 version returns the RESULT where `VALUE=COMPARE_VALUE'. The second version returns the result for the first condition that is true. If there was no matching result value, the result after `ELSE' is returned, or `NULL' if there is no `ELSE' part. 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 The return type of a `CASE' expression is the compatible aggregated type of all return values, but also depends on the context in which it is used. If used in a string context, the result is returned as a string. If used in a numeric context, the result is returned as a decimal, real, or integer value. *Note*: The syntax of the `CASE' _expression_ shown here differs slightly from that of the SQL *Note `CASE': case. _statement_ described in *Note case::, for use inside stored programs. The *Note `CASE': case. statement cannot have an `ELSE NULL' clause, and it is terminated with `END CASE' instead of `END'. * `IF(EXPR1,EXPR2,EXPR3)' If EXPR1 is `TRUE' (`EXPR1 <> 0' and `EXPR1 <> NULL') then `IF()' returns EXPR2; otherwise it returns EXPR3. `IF()' returns a numeric or string value, depending on the context in which it is used. 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' 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. This table lists expressions and corresponding return values which show how the default return type of `IF()' is calculated. Expression Return Value EXPR2 or EXPR3 returns a string string EXPR2 or EXPR3 returns a floating-point floating-point value EXPR2 or EXPR3 returns an integer integer If EXPR2 and EXPR3 are both strings, the result is case sensitive if either string is case sensitive. *Note*: There is also an *Note `IF': if. _statement_, which differs from the `IF()' _function_ described here. See *Note if::. * `IFNULL(EXPR1,EXPR2)' If EXPR1 is not `NULL', `IFNULL()' returns EXPR1; otherwise it returns EXPR2. `IFNULL()' returns a numeric or string value, depending on the context in which it is used. 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 result value of `IFNULL(EXPR1,EXPR2)' is the more `general' of the two expressions, in the order `STRING', *Note `REAL': floating-point-types, or *Note `INTEGER': integer-types. 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 *Note `VARBINARY(4)': binary-varbinary. * `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'. mysql> SELECT NULLIF(1,1); -> NULL mysql> SELECT NULLIF(1,2); -> 1 Note that MySQL evaluates EXPR1 twice if the arguments are not equal.  File: manual.info, Node: string-functions, Next: numeric-functions, Prev: control-flow-functions, Up: functions 12.5 String Functions ===================== * Menu: * string-comparison-functions:: String Comparison Functions * regexp:: Regular Expressions *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_LENGTH()' Return number of characters in argument `CHAR()' Return the character for each integer passed `CHARACTER_LENGTH()' A synonym for CHAR_LENGTH() `CONCAT_WS()' Return concatenate with separator `CONCAT()' Return concatenated string `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 `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()' A synonym for LENGTH() `ORD()' Return character code for leftmost character of the argument `POSITION()' A synonym for LOCATE() `QUOTE()' Escape the argument for use in an SQL statement `REGEXP' Pattern matching using regular expressions `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' Synonym for REGEXP `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_INDEX()' Return a substring from a string before the specified number of occurrences of the delimiter `SUBSTRING()' Return the substring as specified `TRIM()' Remove leading and trailing spaces `UCASE()' Synonym for UPPER() `UNHEX()' Return a string containing hex representation of a number `UPPER()' Convert to uppercase 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 *Note server-parameters::. 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 (*Note `BIGINT': integer-types.) 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(0x65)), CHARSET(CHAR(0x65 USING utf8)); +---------------------+--------------------------------+ | CHARSET(CHAR(0x65)) | CHARSET(CHAR(0x65 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 multi-byte 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 binary string form; if you want to avoid that, you can use an explicit type cast, as in this example: SELECT CONCAT(CAST(INT_COL AS CHAR), CHAR_COL); `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, 'ej', 'Heja', 'hej', 'foo'); -> 'ej' mysql> SELECT ELT(4, 'ej', 'Heja', 'hej', 'foo'); -> 'foo' * `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('ej', 'Hej', 'ej', 'Heja', 'hej', 'foo'); -> 2 mysql> SELECT FIELD('fo', 'Hej', 'ej', 'Heja', 'hej', 'foo'); -> 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 *Note `SET': 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)' 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. 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' * `HEX(STR)', `HEX(N)' For a string argument STR, `HEX()' returns a hexadecimal string representation of STR where each character in STR is converted to two hexadecimal 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 (*Note `BIGINT': integer-types.) number. This is equivalent to `CONV(N,10,16)'. The inverse of this operation is performed by `CONV(HEX(N),16,10)'. mysql> SELECT 0x616263, 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 multi-byte 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 multi-byte safe, and is case sensitive only if at least one argument is a binary string. * `LCASE(STR)' `LCASE()' is a synonym for `LOWER()'. * `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 multi-byte safe. * `LENGTH(STR)' Returns the length of the string STR, measured in bytes. A multi-byte 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 * `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'. As of MySQL 5.1.6, 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. mysql> SELECT LOCATE('bar', 'foobarbar'); -> 4 mysql> SELECT LOCATE('xbar', 'foobar'); -> 0 mysql> SELECT LOCATE('bar', 'foobarbar', 5); -> 7 This function is multi-byte 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 (*Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, *Note `BLOB': 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 | +-------------+-----------------------------------+ This function is multi-byte safe. * `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 multi-byte 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 (*Note `BIGINT': integer-types.) 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 multi-byte 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 multi-byte 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 *Note string-literals::, and *Note mysql-real-escape-string::. * `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 multi-byte safe. * `REVERSE(STR)' Returns the string STR with the order of the characters reversed. mysql> SELECT REVERSE('abc'); -> 'cba' This function is multi-byte 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 multi-byte 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 multi-byte safe. * `RTRIM(STR)' Returns the string STR with trailing space characters removed. mysql> SELECT RTRIM('barbar '); -> 'barbar' This function is multi-byte 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 multi-byte character sets, including `utf-8'. We hope to remove these limitations in a future release. 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 multi-byte 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 multi-byte safe. * `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 multi-byte safe. * `UCASE(STR)' `UCASE()' is a synonym for `UPPER()'. * `UNHEX(STR)' For a string argument STR, `UNHEX(STR)' performs the inverse operation of `HEX(STR)'. That is, it interprets each pair of characters in the argument as a hexadecimal number and converts it to the character represented by the number. The return value is a binary string. mysql> SELECT UNHEX('4D7953514C'); -> 'MySQL' mysql> SELECT 0x4D7953514C; -> '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 *Note `BINARY': binary-varbinary. 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()', such as information about how to perform lettercase conversion of binary strings (*Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, *Note `BLOB': blob.) for which these functions are ineffective. This function is multi-byte safe.  File: manual.info, Node: string-comparison-functions, Next: regexp, Prev: string-functions, Up: string-functions 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 SQL simple regular expression comparison. 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 *Note `CHAR': char. or *Note `VARCHAR': char. 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. This table lists wildcard characters that can be used with the `LIKE' string comparison function and provides a description of each character. Character Description `%' 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. This table lists strings that are assumed if you do not specify the `ESCAPE' character when testing for literal instances of wildcard characters. A description of each string is provided. String Description `\%' 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. As of MySQL 5.1.2, 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 a binary string: mysql> SELECT 'abc' LIKE 'ABC'; -> 1 mysql> SELECT 'abc' LIKE BINARY 'ABC'; -> 0 In MySQL, `LIKE' is permitted on numeric expressions. (This is an extension to the standard SQL `LIKE'.) 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 *Note charset-collation-expressions::. mysql> SELECT STRCMP(@s1, @s3); ERROR 1267 (HY000) at line 10: 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 | +--------------------------------------------+  File: manual.info, Node: regexp, Prev: string-comparison-functions, Up: string-functions 12.5.2 Regular Expressions -------------------------- *String Regular Expression Operators* Name Description `NOT REGEXP' Negation of REGEXP `REGEXP' Pattern matching using regular expressions `RLIKE' Synonym for REGEXP A regular expression is a powerful way of specifying a pattern for a complex search. 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 pattern-matching operations performed with the `REGEXP' operator in SQL statements. This section summarizes, with examples, the special characters and constructs that can be used in MySQL for `REGEXP' operations. It 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. See also *Note pattern-matching::. * `EXPR NOT REGEXP PAT', `EXPR NOT RLIKE PAT' This is the same as `NOT (EXPR REGEXP PAT)'. * `EXPR REGEXP PAT', `EXPR RLIKE PAT' Performs a pattern match of a string expression EXPR against a pattern PAT. The pattern can be an extended regular expression. The syntax for regular expressions is discussed in *Note regexp::. Returns `1' if EXPR matches PAT; otherwise it returns `0'. If either EXPR or PAT is `NULL', the result is `NULL'. `RLIKE' is a synonym for `REGEXP', provided for `mSQL' compatibility. 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' strings. `REGEXP' is not case sensitive, except when used with binary strings. mysql> SELECT 'Monty!' REGEXP '.*'; -> 1 mysql> SELECT 'new*\n*line' REGEXP 'new\\*.\\*line'; -> 1 mysql> SELECT 'a' REGEXP 'A', 'a' REGEXP BINARY 'A'; -> 1 0 mysql> SELECT 'a' REGEXP '^[a-d]'; -> 1 `REGEXP' and `RLIKE' use the character set and collations of the 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 *Note charset-collation-expressions::. *Warning*: The `REGEXP' and `RLIKE' operators work in byte-wise fashion, so they are not multi-byte safe and may produce unexpected results with multi-byte 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. 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|word' matches either the string `hello' or the string `word'. 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' 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}' `{n}' or `{m,n}' notation provides 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. `m' and `n' must be in the range from `0' to `RE_DUP_MAX' (default 255), inclusive. If both `m' and `n' are given, `m' must be less than or equal to `n'. 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. This table shows permissible character names and matching characters. To save space, the column pairing of Name and Character are presented in a four column table format in this order: Name, Character, Name, Character. 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. This table lists character class names and describes the meaning of each. 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  File: manual.info, Node: numeric-functions, Next: date-and-time-functions, Prev: string-functions, Up: functions 12.6 Numeric Functions and Operators ==================================== * Menu: * arithmetic-functions:: Arithmetic Operators * mathematical-functions:: Mathematical Functions *Numeric Functions and Operators* Name Description `ABS()' Return the absolute value `ACOS()' Return the arc cosine `ASIN()' Return the arc sine `ATAN2()', `ATAN()' Return the arc tangent of the two arguments `ATAN()' Return the arc tangent `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 `LOG10()' Return the base-10 logarithm of the argument `LOG2()' Return the base-2 logarithm of the argument `LOG()' Return the natural logarithm of the first argument `-' Minus operator `MOD()' Return the remainder `% or 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  File: manual.info, Node: arithmetic-functions, Next: mathematical-functions, Prev: numeric-functions, Up: numeric-functions 12.6.1 Arithmetic Operators --------------------------- *Arithmetic Operators* Name Description `DIV' Integer division `/' Division operator `-' Minus operator `% or 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 *Note `BIGINT': integer-types. (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 *Note cast-functions::. For information about handling of overflow in numeric expression evaluation, see *Note 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 *Note 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 *Note `BIGINT': integer-types, the return value is also a *Note `BIGINT': integer-types. 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 * `/' 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 *Note `BIGINT': integer-types. arithmetic only if performed in a context where its result is converted to an integer. * `DIV' Integer division. Similar to `FLOOR()', but is safe with *Note `BIGINT': integer-types. values. Incorrect results may occur for noninteger operands that exceed *Note `BIGINT': integer-types. range. mysql> SELECT 5 DIV 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 *Note mathematical-functions::.  File: manual.info, Node: mathematical-functions, Prev: arithmetic-functions, Up: numeric-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 `ATAN2()', `ATAN()' Return the arc tangent of the two arguments `ATAN()' Return the arc tangent `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 `LOG10()' Return the base-10 logarithm of the argument `LOG2()' Return the base-2 logarithm of the argument `LOG()' Return the natural logarithm of the first 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 *Note `BIGINT': integer-types. 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 TO_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'+0xa,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); -> NULL * `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); -> 1 mysql> SELECT FLOOR(-1.23); -> -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 *Note 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 *Note 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, then `NULL' is returned. 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, then `NULL' is returned. 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'. 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. 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 *Note `BIGINT': integer-types. 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()', `RAND(N)' Returns a random floating-point value V in the range `0' <= V < `1.0'. If a constant integer argument N is specified, it is used as the seed value, which produces a repeatable sequence of column values. In the following example, note that the sequences of values produced by `RAND(3)' is the same both places where 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) With a constant initializer, the seed is initialized once when the statement is compiled, prior to execution. As of MySQL 5.1.16, if a nonconstant initializer (such as a column name) is used as the argument, the seed is initialized with the value for each invocation of `RAND()'. (One implication of this is that for equal argument values, `RAND()' will return the same value each time.) From MySQL 5.1.3 to 5.1.15, nonconstant arguments are not permitted. Before that, the effect of using a nonconstant argument is undefined. 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', you could use the following statement: SELECT FLOOR(7 + (RAND() * 5)); `RAND()' in a `WHERE' clause is re-evaluated every time the `WHERE' is executed. You cannot use a column with `RAND()' values in an `ORDER BY' clause, because `ORDER BY' would evaluate the column multiple times. However, you can retrieve rows in random order like this: mysql> SELECT * FROM TBL_NAME ORDER BY RAND(); `ORDER BY RAND()' combined with `LIMIT' is useful for selecting a random sample from a set of rows: mysql> SELECT * FROM table1, table2 WHERE a=b AND c 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. Beginning with MySQL 5.1.43, this function is flagged as unsafe for statement-based replication; use of this function causes a warning when using statement-based replication, and the statement is logged using the binary format when `binlog_format' is `MIXED'. (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 type is the same type as that of 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 *Note precision-math::. This function is unsafe for statement-based replication. Beginning with MySQL 5.1.43, a warning is logged if you use this function when `binlog_format' is set to `STATEMENT'. (Bug #49222) * `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.  File: manual.info, Node: date-and-time-functions, Next: mysql-calendar, Prev: numeric-functions, Up: functions 12.7 Date and Time Functions ============================ This section describes the functions that can be used to manipulate temporal values. See *Note 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/Time Functions* Name Description `ADDDATE()' Add time values (intervals) to a date value `ADDTIME()' Add time `CONVERT_TZ()' Convert from one timezone 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_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 `DATE()' Extract the date part of a date or datetime expression `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' MAKETIME() `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()' A synonym for DATE_SUB() when invoked with three arguments `SUBTIME()' Subtract times `SYSDATE()' Return the time at which the function executes `TIME_FORMAT()' Format as time `TIME_TO_SEC()' Return the argument converted to seconds `TIME()' Extract the time portion of the expression passed `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 `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 (0-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 *Note 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 *Note*: From MySQL 5.1.59 to 5.1.61, a change in handling of a date-related assertion caused several functions to become 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()', `TIMESTAMPDIFF()', `TO_DAYS()', `TO_SECONDS()' (http://dev.mysql.com/doc/refman/5.5/en/date-and-time-functions.html#function_to-seconds), `WEEK()', `WEEKDAY()', `WEEKOFYEAR()', `YEARWEEK()'. Because this changes date-handling behavior in General Availability-status series MySQL 5.1, the change was reverted in 5.1.62. * `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 *Note time-zone-support::. This function returns `NULL' if the arguments are invalid. If the value falls out of the supported range of the *Note `TIMESTAMP': datetime. type when converted from FROM_TZ to UTC, no conversion occurs. The *Note `TIMESTAMP': datetime. range is described in *Note 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 *Note time-zone-support::, for instructions. Before MySQL 5.1.17, if you intend to use `CONVERT_TZ()' while other tables are locked with *Note `LOCK TABLES': lock-tables, you must also lock the `mysql.time_zone_name' table. See *Note lock-tables::. * `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()' `CURRENT_TIME' and `CURRENT_TIME()' are synonyms for `CURTIME()'. * `CURRENT_TIMESTAMP', `CURRENT_TIMESTAMP()' `CURRENT_TIMESTAMP' and `CURRENT_TIMESTAMP()' are synonyms for `NOW()'. * `CURTIME()' Returns the current time as a value in `'HH:MM:SS'' or `HHMMSS.uuuuuu' format, depending on whether the function is used in a string or numeric context. The value is expressed in the current time zone. 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. This table lists UNIT values and the expected EXPR argument for each. 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: * *Note `DATETIME': datetime. if the first argument is a *Note `DATETIME': datetime. (or *Note `TIMESTAMP': datetime.) value, or if the first argument is a *Note `DATE': datetime. and the UNIT value uses `HOURS', `MINUTES', or `SECONDS'. * String otherwise. To ensure that the result is *Note `DATETIME': datetime, you can use `CAST()' to convert the first argument to *Note `DATETIME': 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 *Note `DATE': datetime. value and your calculations involve only `YEAR', `MONTH', and `DAY' parts (that is, no time parts), the result is a *Note `DATE': datetime. value. Otherwise, the result is a *Note `DATETIME': 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 *Note `TIME': 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 *Note `DECIMAL': fixed-point-types. 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. This table lists specifier characters for the `DATE_FORMAT' function that may be used in the FORMAT string and provides a description of each specifier character. 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 `%u' Week (`00'..`53'), where Monday is the first day of the week `%V' Week (`01'..`53'), where Sunday is the first day of the week; used with `%X' `%v' Week (`01'..`53'), where Monday is the first day of the week; 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''. As of MySQL 5.1.12, the language used for day and month names and abbreviations is controlled by the value of the `lc_time_names' system variable (*Note locale-support::). As of MySQL 5.1.15, `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. Before 5.1.15, the return value is a binary string. 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. As of MySQL 5.1.12, the language used for the name is controlled by the value of the `lc_time_names' system variable (*Note 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 *Note `DATE': datetime. value. mysql> SELECT FROM_DAYS(730669); -> '2007-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 *Note 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.uuuuuu' 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(1196440219); -> '2007-11-30 10:30:19' mysql> SELECT FROM_UNIXTIME(1196440219) + 0; -> 20071130103019.000000 mysql> SELECT FROM_UNIXTIME(UNIX_TIMESTAMP(), -> '%Y %D %M %h:%i:%s %x'); -> '2007 30th November 10:30:59 2007' Note: If you use `UNIX_TIMESTAMP()' and `FROM_UNIXTIME()' to convert between *Note `TIMESTAMP': datetime. 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. This table lists function calls for the `GET_FORMAT' function along with results for each function call. 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'' *Note `TIMESTAMP': datetime. can also be used as the first argument to `GET_FORMAT()', in which case the function returns the same values as for *Note `DATETIME': 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 *Note `TIME': 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()' `LOCALTIME' and `LOCALTIME()' are synonyms for `NOW()'. * `LOCALTIMESTAMP', `LOCALTIMESTAMP()' `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. 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. As of MySQL 5.1.12, the language used for the name is controlled by the value of the `lc_time_names' system variable (*Note locale-support::). mysql> SELECT MONTHNAME('2008-02-03'); -> 'February' * `NOW()' Returns the current date and time as a value in `'YYYY-MM-DD HH:MM:SS'' or `YYYYMMDDHHMMSS.uuuuuu' format, depending on whether the function is used in a string or numeric context. The value is expressed in the current time zone. 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 *Note `TIME': time. value. The range of the result is constrained to that of the *Note `TIME': 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 *Note `DATETIME': datetime. value if the format string contains both date and time parts, or a *Note `DATE': datetime. or *Note `TIME': 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 *Note 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' *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()' Returns the current date and time as a value in `'YYYY-MM-DD HH:MM:SS'' or `YYYYMMDDHHMMSS.uuuuuu' format, depending on whether the function is used in a string or numeric context. `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. Beginning with MySQL 5.1.42, a warning is logged if you use this function when `binlog_format' is set to `STATEMENT'. (Bug #47995) * `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. Beginning with MySQL 5.1.42, a warning is logged if you use this function when `binlog_format' is set to `STATEMENT'. (Bug #47995) 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 *Note `TIME': 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: `FRAC_SECOND' (microseconds), `SECOND', `MINUTE', `HOUR', `DAY', `WEEK', `MONTH', `QUARTER', or `YEAR'. Beginning with MySQL 5.1.24, it is possible to use `MICROSECOND' in place of `FRAC_SECOND' with this function, and `FRAC_SECOND' is deprecated. `FRAC_SECOND' is removed in MySQL 5.5. 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 *Note mysql-calendar::, for details. Remember that MySQL converts two-digit year values in dates to four-digit form using the rules in *Note 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. * `UNIX_TIMESTAMP()', `UNIX_TIMESTAMP(DATE)' If called with no argument, returns a Unix timestamp (seconds since `'1970-01-01 00:00:00'' UTC) as an unsigned integer. 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. DATE may be a *Note `DATE': datetime. string, a *Note `DATETIME': datetime. string, a *Note `TIMESTAMP': datetime, or a number in the format `YYMMDD' or `YYYYMMDD'. 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 *Note time-zone-support::. mysql> SELECT UNIX_TIMESTAMP(); -> 1196440210 mysql> SELECT UNIX_TIMESTAMP('2007-11-30 10:30:19'); -> 1196440219 When `UNIX_TIMESTAMP()' is used on a *Note `TIMESTAMP': datetime. 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'. Note: If you use `UNIX_TIMESTAMP()' and `FROM_UNIXTIME()' to convert between *Note `TIMESTAMP': datetime. 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 *Note `TIMESTAMP': datetime. values to the same Unix timestamp value. `FROM_UNIXTIME()' will map that value back to only one of the original *Note `TIMESTAMP': datetime. values. Here is an example, using *Note `TIMESTAMP': datetime. 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 *Note 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()' Returns the current UTC time as a value in `'HH:MM:SS'' or `HHMMSS.uuuuuu' format, depending on whether the function is used in a string or numeric context. mysql> SELECT UTC_TIME(), UTC_TIME() + 0; -> '18:07:53', 180753.000000 * `UTC_TIMESTAMP', `UTC_TIMESTAMP()' Returns the current UTC date and time as a value in `'YYYY-MM-DD HH:MM:SS'' or `YYYYMMDDHHMMSS.uuuuuu' format, depending on whether the function is used in a string or numeric context. 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 *Note server-system-variables::. The following table describes how the MODE argument works. This table describes how the MODE argument of the `WEEK' function works. For each mode value, the table lists the first day of the week, the range, and a description of week 1. 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 more than 3 days this year 2 Sunday 1-53 with a Sunday in this year 3 Monday 1-53 with more than 3 days this year 4 Sunday 0-53 with more than 3 days this year 5 Monday 0-53 with a Monday in this year 6 Sunday 1-53 with more than 3 days this year 7 Monday 1-53 with a Monday in this year 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 MySQL should return `52' for the `WEEK()' function, because the given date actually occurs in the 52nd week of 1999. We decided to return `0' instead because we want the function to return `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 would prefer the result to be 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 MODE argument works exactly like the MODE argument to `WEEK()'. 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. mysql> SELECT YEARWEEK('1987-01-01'); -> 198653 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.  File: manual.info, Node: mysql-calendar, Next: fulltext-search, Prev: date-and-time-functions, Up: functions 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. This table shows the month of October 1582, when the first Julian-to-Gregorian switch occurred. Table headings are days of the week and table rows list the dates for each day of the week. The table is intended to illustrate that there are no dates between October 4 and October 15. 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 *Note `DATE': datetime. or *Note `DATETIME': 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.  File: manual.info, Node: fulltext-search, Next: cast-functions, Prev: mysql-calendar, Up: functions 12.9 Full-Text Search Functions =============================== * Menu: * fulltext-natural-language:: Natural Language Full-Text Searches * fulltext-boolean:: Boolean Full-Text Searches * fulltext-query-expansion:: Full-Text Searches with Query Expansion * fulltext-stopwords:: Full-Text Stopwords * fulltext-restrictions:: Full-Text Restrictions * fulltext-fine-tuning:: Fine-Tuning MySQL Full-Text Search * full-text-adding-collation:: Adding a Collation for Full-Text Indexing `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 `MyISAM' tables. (In MySQL 5.6 and up, they can also be used with `InnoDB' tables.) Full-text indexes can be created only for *Note `CHAR': char, *Note `VARCHAR': char, or *Note `TEXT': blob. columns. * A `FULLTEXT' index definition can be given in the *Note `CREATE TABLE': create-table. statement when a table is created, or added later using *Note `ALTER TABLE': alter-table. or *Note `CREATE INDEX': 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. The stopword list applies. In addition, words that are present in 50% or more of the rows are considered common and do not match. 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 *Note 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. Common words such as `some' or `then' are stopwords and do not match if present in the search string. The `IN BOOLEAN MODE' modifier specifies a boolean search. For more information, see *Note 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 *Note fulltext-query-expansion::. The `IN NATURAL LANGUAGE MODE' and `IN NATURAL LANGUAGE MODE WITH QUERY EXPANSION' modifiers were added in MySQL 5.1.7. Constraints on full-text searching are listed in *Note fulltext-restrictions::. The *Note `myisam_ftdump': myisam-ftdump. utility can be used to dump the contents of a full-text index. This may be helpful for debugging full-text queries. See *Note myisam-ftdump::.  File: manual.info, Node: fulltext-natural-language, Next: fulltext-boolean, Prev: fulltext-search, Up: fulltext-search 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=MyISAM; Query OK, 0 rows affected (0.00 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.00 sec) Records: 6 Duplicates: 0 Warnings: 0 mysql> SELECT * FROM articles -> WHERE MATCH (title,body) -> AGAINST ('database' IN NATURAL LANGUAGE MODE); +----+-------------------+------------------------------------------+ | id | title | body | +----+-------------------+------------------------------------------+ | 5 | MySQL vs. YourSQL | In the following database comparison ... | | 1 | MySQL Tutorial | DBMS stands for DataBase ... | +----+-------------------+------------------------------------------+ 2 rows in set (0.00 sec) By default, the search is performed in case-insensitive fashion. However, you can perform a case-sensitive full-text search by using 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, the number of unique words in that row, the total number of words in the collection, and the number of documents (rows) that contain a particular word. 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) However, 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 sorts the results by relevance whereas the second does not. However, the second query performs a full table scan and the first does not. The first may be faster if the search matches few rows; otherwise, the second may be faster because it would read many rows anyway. For natural-language full-text searches, it is a requirement that the columns named in the `MATCH()' function 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. If you wanted to search the `title' or `body' separately, you would need to create separate `FULLTEXT' indexes for each column. It is also possible to perform a boolean search or a search with query expansion. These search types are described in *Note fulltext-boolean::, and *Note 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. 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 *Note `SELECT': 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.65545833110809 | | 2 | 0 | | 3 | 0.66266459226608 | | 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, you should specify `MATCH()' twice: once in the *Note `SELECT': 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) 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 `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 `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, you must preprocess them so that they are separated by some arbitrary delimiter such as ``"''. In MySQL 5.1, it is possible to write a plugin that replaces the built-in full-text parser. For details, see *Note 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 four characters. * 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 overwritten by a user-defined list. The default stopword list is given in *Note fulltext-stopwords::. The default minimum word length and stopword list can be changed as described in *Note fulltext-fine-tuning::. Every correct word in the collection and in the query is weighted according to its significance in the collection or query. Consequently, a word that is present in many documents has a lower weight (and may even have a zero 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. Such a technique works best with large collections (in fact, it was carefully tuned this way). For very small tables, word distribution does not adequately reflect their semantic value, and this model may sometimes produce bizarre results. For example, although the word `MySQL' is present in every row of the `articles' table shown earlier, a search for the word 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. As such, it is effectively treated as a stopword. For large data sets, this is the most desirable behavior: A natural language query should not return every second row from a 1GB table. For small data sets, it may be less desirable. A word that matches half of the rows in a table is less likely to locate relevant documents. In fact, it most likely finds plenty of irrelevant documents. We all know this happens far too often when we are trying to find something on the Internet with a search engine. It is with this reasoning that rows containing the word are assigned a low semantic value for _the particular data set in which they occur_. A given word may reach the 50% threshold in one data set but not another. The 50% threshold has a significant implication when you first try full-text searching to see how it works: If you create a 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. Be sure to insert at least three rows, and preferably many more. Users who need to bypass the 50% limitation can use the boolean search mode; see *Note fulltext-boolean::.  File: manual.info, Node: fulltext-boolean, Next: fulltext-query-expansion, Prev: fulltext-natural-language, Up: fulltext-search 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 is required to 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 use the 50% threshold. * They do not automatically sort rows in order of decreasing relevance. You can see this from the preceding query result: The row with the highest relevance is the one that contains `MySQL' twice, but it is listed last, not first. * They 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. * The stopword list applies. The boolean full-text search capability supports the following operators: * `+' A leading plus sign indicates that this word _must_ be present in each row that is returned. * `-' A leading minus sign indicates that this word must _not_ be present in any of the rows that are returned. 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. * `> <' 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 should be _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 (as determined from the `ft_min_word_len' setting) or a stopword. This occurs because the word is not seen as too short or a stopword, but as a prefix that must be present in the document in the form of a word that begins with the prefix. Suppose that `ft_min_word_len=4'. Then a search for `'+WORD +the*'' will likely return fewer rows than a search for `'+WORD +the'': * The former query remains as is and requires both WORD and `the*' (a word starting with `the') to be present in the document. * The latter query is transformed to `+WORD' (requiring only WORD to be present). `the' is both too short and a stopword, and either condition is enough to cause it to be ignored. * `"' 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 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 SELECT * FROM articles -> WHERE MATCH (title,body) -> AGAINST ('database' IN NATURAL LANGUAGE MODE); +----+-------------------+------------------------------------------+ | id | title | body | +----+-------------------+------------------------------------------+ | 5 | MySQL vs. YourSQL | In the following database comparison ... | | 1 | MySQL Tutorial | DBMS stands for DataBase ... | +----+-------------------+------------------------------------------+ 2 rows in set (0.00 sec) mysql> SELECT * FROM articles -> WHERE MATCH (title,body) -> AGAINST ('database' WITH QUERY EXPANSION); +----+-------------------+------------------------------------------+ | id | title | body | +----+-------------------+------------------------------------------+ | 1 | MySQL Tutorial | DBMS stands for DataBase ... | | 5 | MySQL vs. YourSQL | In the following database comparison ... | | 3 | Optimizing MySQL | In this tutorial we will show ... | +----+-------------------+------------------------------------------+ 3 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, it is meaningful to use only when a search phrase is rather short.  File: manual.info, Node: fulltext-stopwords, Next: fulltext-restrictions, Prev: fulltext-query-expansion, Up: fulltext-search 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 may 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'. The following table shows the default list of full-text stopwords. In a MySQL source distribution, you can find this list in the `storage/myisam/ft_static.c' file. This table shows the default list of full-text stopwords. In a MySQL source distribution, you can find this list in the `myisam/ft_static.c' file. The table lists stopwords in alphabetical order when read from left to right, row by row. 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  File: manual.info, Node: fulltext-restrictions, Next: fulltext-fine-tuning, Prev: fulltext-stopwords, Up: fulltext-search 12.9.5 Full-Text Restrictions ----------------------------- * Full-text searches are supported for `MyISAM' tables only. (In MySQL 5.6 and up, they can also be used with `InnoDB' tables.) * Full-text searches are not supported for partitioned tables. See *Note partitioning-limitations::. * Full-text searches can be used with most multi-byte character sets. The exception is that for Unicode, the `utf8' character set can be used, but not the `ucs2' character set. However, 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. * Ideographic languages such as Chinese and Japanese do not have word delimiters. Therefore, the `FULLTEXT' parser _cannot determine where words begin and end in these and other such languages_. The implications of this and some workarounds for the problem are described in *Note fulltext-search::. * 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'. 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 *Note index-hints::.  File: manual.info, Node: fulltext-fine-tuning, Next: full-text-adding-collation, Prev: fulltext-restrictions, Up: fulltext-search 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 *Note source-installation::. Note that full-text search is carefully tuned for the most 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. * The minimum and maximum lengths of words to be indexed are defined by the `ft_min_word_len' and `ft_max_word_len' system variables. (See *Note server-system-variables::.) The default minimum value is four characters; the default maximum is version dependent. If you change either value, you must rebuild your `FULLTEXT' indexes. For example, if you want three-character words to be searchable, you can set the `ft_min_word_len' variable by putting the following lines in an option file: [mysqld] ft_min_word_len=3 Then restart the server and rebuild your `FULLTEXT' indexes. Note particularly the remarks regarding *Note `myisamchk': myisamchk. in the instructions following this list. * To override the default stopword list, set the `ft_stopword_file' system variable. (See *Note 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. That is, you may use any nonalphanumeric character such as newline, space, or comma to separate stopwords. 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 *Note charset-server::. * 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. * To change the operators used for boolean full-text searches, set the `ft_boolean_syntax' system variable. 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 *Note server-system-variables::, which describes the rules governing how to set this variable. * If you want to change the set of characters that are considered word characters, you can do so in several ways, as described in the following list. After making the modification, you must 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/myisam/ftdefs.h', 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 `' 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 `' array format, see *Note 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 *Note adding-collation::. For an example specific to full-text indexing, see *Note full-text-adding-collation::. 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 indexes in this case, it is sufficient to do a `QUICK' repair operation: mysql> REPAIR TABLE TBL_NAME QUICK; Alternatively, use *Note `ALTER TABLE': alter-table. with the `DROP INDEX' and `ADD INDEX' options to drop and re-create each `FULLTEXT' index. 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. Note that if you use *Note `myisamchk': 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 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 *Note `myisamchk': myisamchk. that you use for *Note `mysqld': mysqld. For example, if you have set the minimum word length to 3, you can repair a table with *Note `myisamchk': myisamchk. like this: shell> myisamchk --recover --ft_min_word_len=3 TBL_NAME.MYI To ensure that *Note `myisamchk': 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 *Note `myisamchk': myisamchk. for index modification is to use the *Note `REPAIR TABLE': repair-table, *Note `ANALYZE TABLE': analyze-table, *Note `OPTIMIZE TABLE': optimize-table, or *Note `ALTER TABLE': alter-table. statements. These statements are performed by the server, which knows the proper full-text parameter values to use.  File: manual.info, Node: full-text-adding-collation, Prev: fulltext-fine-tuning, Up: fulltext-search 12.9.7 Adding a Collation for Full-Text Indexing ------------------------------------------------ This section describes how to add a new collation for full-text searches. 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 *Note 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 this procedure: 1. Add a collation to the `Index.xml' file. The collation ID must be unused, so choose a value different from 62 if that ID is already taken on your system. ... 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': 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 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. 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 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=MyISAM; 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)  File: manual.info, Node: cast-functions, Next: xml-functions, Prev: fulltext-search, Up: functions 12.10 Cast Functions and Operators ================================== *Cast Functions* 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 * `BINARY' The `BINARY' operator casts the string following it to a binary string. This is an easy way to force a column comparison to be done byte by byte rather than character by character. This causes the comparison to be case sensitive even if the column is not defined as *Note `BINARY': binary-varbinary. or *Note `BLOB': blob. `BINARY' also causes trailing spaces 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. `BINARY STR' is shorthand for `CAST(STR AS BINARY)'. Note that in some contexts, if you cast an indexed column to `BINARY', MySQL is not able to use the index efficiently. * `CAST(EXPR AS TYPE)' The `CAST()' function takes an expression of any type and produces a result value of a specified type, similar to `CONVERT()'. See the description of `CONVERT()' for more information. * `CONVERT(EXPR,TYPE)', `CONVERT(EXPR USING TRANSCODING_NAME)' The `CONVERT()' and `CAST()' functions take an expression of any type and produce a result value of a specified type. The TYPE for the result can be one of the following values: * `BINARY[(N)]' * `CHAR[(N)]' * *Note `DATE': datetime. * *Note `DATETIME': datetime. * `DECIMAL[(M[,D])]' * `SIGNED [INTEGER]' * *Note `TIME': time. * `UNSIGNED [INTEGER]' *Note `BINARY': binary-varbinary. produces a string with the *Note `BINARY': binary-varbinary. data type. See *Note 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)' causes the cast to use no more than N characters of the argument. `CAST()' and `CONVERT(... USING ...)' are standard SQL syntax. The non-`USING' form of `CONVERT()' is ODBC syntax. `CONVERT()' with `USING' is used to convert 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); Normally, you cannot compare a *Note `BLOB': blob. value or other binary string in case-insensitive fashion because binary strings have no character set, and thus no concept of lettercase. To perform a case-insensitive comparison, use the `CONVERT()' function to convert the value to a nonbinary string. Comparisons of the result use the string collation. For example, if the character set of the result 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, as described in *Note charset-convert::. For example, to use `latin1_german1_ci': SELECT 'A' LIKE CONVERT(BLOB_COL USING latin1) COLLATE latin1_german1_ci FROM TBL_NAME; `CONVERT()' can be used more generally for comparing strings that are represented in different character sets. `LOWER()' (and `UPPER()') are ineffective when applied to binary strings (*Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, *Note `BLOB': 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 | +-------------+-----------------------------------+ The cast functions are useful when you want to create a column with a specific type in a *Note `CREATE TABLE ... SELECT': create-table. statement: CREATE TABLE new_table SELECT CAST('2000-01-01' AS DATE); The functions also can be useful for sorting *Note `ENUM': enum. columns in lexical order. Normally, sorting of *Note `ENUM': enum. columns occurs using the internal numeric values. Casting the values to *Note `CHAR': char. results in a lexical sort: SELECT ENUM_COL FROM TBL_NAME ORDER BY CAST(ENUM_COL AS CHAR); `CAST(STR AS BINARY)' is the same thing as `BINARY STR'. `CAST(EXPR AS CHAR)' treats the expression as a string with the default character set. `CAST()' also changes the result if you use it as part of a more complex expression such as `CONCAT('Date: ',CAST(NOW() AS DATE))'. You should not use `CAST()' to extract data in different formats but instead use string functions like `LEFT()' or `EXTRACT()'. See *Note date-and-time-functions::. To cast a string to a numeric value in numeric context, you normally do not have to do anything other than to use the string value as though it were a number: mysql> SELECT 1+'1'; -> 2 If you use a string in an arithmetic operation, it is converted to a floating-point number during expression evaluation. If you use a number in string context, the number automatically is converted to a string: mysql> SELECT CONCAT('hello you ',2); -> 'hello you 2' For information about implicit conversion of numbers to strings, see *Note type-conversion::. MySQL supports arithmetic with both signed and unsigned 64-bit values. If you are using numeric operators (such as `+' or `-') and one of the operands is an unsigned integer, the result is unsigned by default (see *Note arithmetic-functions::). You can override this by using the `SIGNED' or `UNSIGNED' cast operator to cast a value to a signed or unsigned 64-bit integer, respectively. 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, *Note `DECIMAL': fixed-point-types. 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. Examples: * If you convert 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. For more information, see *Note server-sql-mode::.  File: manual.info, Node: xml-functions, Next: bit-functions, Prev: cast-functions, Up: functions 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 *Note `mysql': mysql. and *Note `mysqldump': mysqldump. clients by invoking them with the `--xml' option. See *Note mysql::, and *Note mysqldump::. Beginning with MySQL 5.1.5, 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.1 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). Beginning with MySQL 5.1.20, 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 = 'XY'; 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 'XYZ'; -> -> 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]') | +--------------------------+---+------------------------------+ | XYZ | 1 | X | +--------------------------+---+------------------------------+ 1 row in set (0.00 sec) +--------------------------+---+------------------------------+ | xml | i | ExtractValue(xml, '//a[$i]') | +--------------------------+---+------------------------------+ | XYZ | 2 | Y | +--------------------------+---+------------------------------+ 1 row in set (0.01 sec) +--------------------------+---+------------------------------+ | xml | i | ExtractValue(xml, '//a[$i]') | +--------------------------+---+------------------------------+ | XYZ | 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*: Currently, 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 elements or elements matched by the XPath expression. In MySQL 5.1, the XPath expression can contain at most 127 characters. (This limitation is lifted in MySQL 5.6.) Using this function is the equivalent of performing a match using the XPATH_EXPR after appending `/text()'. In other words, `ExtractValue('Sakila', '/a/b')' and `ExtractValue('Sakila', '/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'); +-------------------------------------+ | ExtractValue('', '/a/b') | +-------------------------------------+ | | +-------------------------------------+ 1 row in set (0.00 sec) mysql> SELECT ExtractValue('', '/a/b'); +-------------------------------------+ | ExtractValue('', '/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('', 'count(/a/b)'); +-------------------------------------+ | ExtractValue('', 'count(/a/b)') | +-------------------------------------+ | 1 | +-------------------------------------+ 1 row in set (0.00 sec) mysql> SELECT ExtractValue('', 'count(/a/b)'); +-------------------------------------+ | ExtractValue('', '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('cccddd', '/a') AS val1, -> ExtractValue('cccddd', '/a/b') AS val2, -> ExtractValue('cccddd', '//b') AS val3, -> ExtractValue('cccddd', '/b') AS val4, -> ExtractValue('cccdddeee', '//b') AS val5; +------+------+------+------+---------+ | val1 | val2 | val3 | val4 | val5 | +------+------+------+------+---------+ | ccc | ddd | ddd | | ddd eee | +------+------+------+------+---------+ Beginning with MySQL 5.1.8, 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 *Note charset-collation-expressions::, for an explanation of the rules governing this behavior. (Previously, binary--that is, case-sensitive--comparison was always used.) Beginning with MySQL 5.1.12, `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('cc SHOW WARNINGS; +---------+------+-------------------------------------------------------------------------------------------+ | Level | Code | Message | +---------+------+-------------------------------------------------------------------------------------------+ | Warning | 1523 | 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('c', '//a'); +-------------------------------------+ | ExtractValue('c', '//a') | +-------------------------------------+ | c | +-------------------------------------+ 1 row in set (0.00 sec) Prior to MySQL 5.1.12, an empty string was returned in such cases. (Bug #18201) * `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. In MySQL 5.1, the XPath expression can contain at most 127 characters. (This limitation is lifted in MySQL 5.6.) 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('ccc', '/a', 'fff') AS val1, -> UpdateXML('ccc', '/b', 'fff') AS val2, -> UpdateXML('ccc', '//b', 'fff') AS val3, -> UpdateXML('ccc', '/a/d', 'fff') AS val4, -> UpdateXML('ccc', '/a/d', 'fff') AS val5 -> \G *************************** 1. row *************************** val1: fff val2: ccc val3: fff val4: cccfff val5: ccc *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 `' if and only if `' is the root element. Example: `/a' has a match in `' because it matches the outermost (root) tag. It does not match the inner A element in `' because in this instance it is the child of another element. * `/TAG1/TAG2' Matches `' if and only if it is a child of `', and `' is the root element. Example: `/a/b' matches the B element in the XML fragment `' because it is a child of the root element A. It does not have a match in `' 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 `'; 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 `'. * `//TAG' Matches any instance of `'. Example: `//a' matches the A element in any of the following: `'; `'; `'. `//' can be combined with `/'. For example, `//a/b' matches the B element in either of the fragments `' or `' *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 = 'wxyz'; Query OK, 0 rows affected (0.00 sec) mysql> SELECT @xml; +-----------------------------------------+ | @xml | +-----------------------------------------+ | wxyz | +-----------------------------------------+ 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 `' or `'. However, the expression does not produce a match in the fragment `' 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 `|' (*Note `UNION': 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 `'. 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 `' 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. * Prior to MySQL 5.1.14, equality and inequality (`=' and `!=') were the only supported comparison operators. Beginning with MySQL 5.1.14, 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( -> 'XY', -> '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( -> ' -> X -> X -> ', -> '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 supported. Beginning with MySQL 5.1.32, they are not permitted, and their use results in an error. (Bug #42495) * 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('xy','/a/child::b'); +-------------------------------------------------------+ | ExtractValue('xy','/a/child::b') | +-------------------------------------------------------+ | x | +-------------------------------------------------------+ 1 row in set (0.02 sec) mysql> SELECT ExtractValue('xy','/a/child::*'); +-------------------------------------------------------+ | ExtractValue('xy','/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: * Prior to MySQL 5.1.24, the `boolean()' function did not produce correct results for some string and nodeset values, including the `NULL' string (see Bug #26051). * `id()' * `lang()' * Prior to MySQL 5.1.8, the `last()' function was not supported (see Bug #16318). * `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' Beginning with MySQL 5.1.10, 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 = '111222333444'; 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', '555'); +--------------------------------------------+ | UpdateXML(@xml, '//b:c', '555') | +--------------------------------------------+ | 111555 | +--------------------------------------------+ 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('c', '/&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('cc SHOW WARNINGS; +---------+------+-------------------------------------------------------------------------------------------+ | Level | Code | Message | +---------+------+-------------------------------------------------------------------------------------------+ | Warning | 1523 | 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('c', '//a'); +-------------------------------------+ | ExtractValue('c', '//a') | +-------------------------------------+ | c | +-------------------------------------+ 1 row in set (0.00 sec) Prior to MySQL 5.1.12, an empty string was returned in such cases. (Bug #18201) *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: 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.  File: manual.info, Node: bit-functions, Next: encryption-functions, Prev: xml-functions, Up: functions 12.12 Bit Functions =================== *Bitwise Functions* Name Description `BIT_COUNT()' Return the number of bits that are set `&' Bitwise AND `~' Invert bits `|' Bitwise OR `^' Bitwise XOR `<<' Left shift `>>' Right shift MySQL uses *Note `BIGINT': integer-types. (64-bit) arithmetic for bit operations, so these operators have a maximum range of 64 bits. * `|' Bitwise OR: mysql> SELECT 29 | 15; -> 31 The result is an unsigned 64-bit integer. * `&' Bitwise AND: mysql> SELECT 29 & 15; -> 13 The result is an unsigned 64-bit integer. * `^' Bitwise XOR: mysql> SELECT 1 ^ 1; -> 0 mysql> SELECT 1 ^ 0; -> 1 mysql> SELECT 11 ^ 3; -> 8 The result is an unsigned 64-bit integer. * `<<' Shifts a longlong (*Note `BIGINT': integer-types.) number to the left. mysql> SELECT 1 << 2; -> 4 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. * `>>' Shifts a longlong (*Note `BIGINT': integer-types.) number to the right. mysql> SELECT 4 >> 2; -> 1 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. * `~' Invert all bits. mysql> SELECT 5 & ~1; -> 4 The result is an unsigned 64-bit integer. * `BIT_COUNT(N)' Returns the number of bits that are set in the argument N. mysql> SELECT BIT_COUNT(29), BIT_COUNT(b'101010'); -> 4, 3  File: manual.info, Node: encryption-functions, Next: information-functions, Prev: bit-functions, Up: functions 12.13 Encryption and Compression Functions ========================================== *Encryption Functions* Name Description `AES_DECRYPT()' Decrypt using AES `AES_ENCRYPT()' Encrypt using AES `COMPRESS()' Return result as a binary string `DECODE()' Decodes a string encrypted using ENCODE() `DES_DECRYPT()' Decrypt a string `DES_ENCRYPT()' Encrypt a string `ENCODE()' Encode a string `ENCRYPT()' Encrypt a string `MD5()' Calculate MD5 checksum `OLD_PASSWORD()' Return the value of the pre-4.1 implementation of PASSWORD `PASSWORD()' Calculate and return a password string `SHA1()', `SHA()' Calculate an SHA-1 160-bit checksum `UNCOMPRESS()' Uncompress a string compressed `UNCOMPRESSED_LENGTH()' Return the length of a string before compression 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 *Note `VARBINARY': binary-varbinary. or *Note `BLOB': 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 (*Note `CHAR': char, *Note `VARCHAR': char, *Note `TEXT': blob.). For functions such as `MD5()' or `SHA1()' that return a string of hex digits, the return value cannot be converted to uppercase or compared in case-insensitive fashion as is. You must convert the value to a nonbinary string. See the discussion of binary string conversion in *Note cast-functions::. 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 *Note `BINARY(N)': binary-varbinary. column. Each pair of hex 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. The size penalty for storing the hex string in a *Note `CHAR': char. column is at least two times, up to six times if the value is stored in a column that uses the `utf8' character set (where each character uses 3 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 *Note `CHAR(32)': char. 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 *Note `BINARY(16)': binary-varbinary. 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 one of the other encryption functions described in this section instead. *Caution*: Passwords or other sensitive values supplied as arguments to encryption functions are sent in plaintext 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)' This function decrypts data using the official AES (Advanced Encryption Standard) algorithm. For more information, see the description of `AES_ENCRYPT()'. * `AES_ENCRYPT(STR,KEY_STR)' `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 allows various key sizes. These functions implement AES with a 128-bit key length, but you can extend them to 256 bits by modifying the source. The key length is a trade off between performance and security. `AES_ENCRYPT()' encrypts the string STR using a key KEY_STR and returns a binary string containing the encrypted output. `AES_DECRYPT()' decrypts the encrypted string CRYPT_STR using a key KEY_STR and returns the original plaintext string. If either argument is `NULL', the results of these functions are also `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) 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', SHA1('My secret passphrase'))); 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. * `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 *Note `CHAR': char. or *Note `VARCHAR': char. column. (However, use of nonbinary string data types such as *Note `CHAR': char. or *Note `VARCHAR': char. to store compressed strings is not recommended anyway because character set conversion may occur. Use a *Note `VARBINARY': binary-varbinary. or *Note `BLOB': blob. binary string column instead.) * `DECODE(CRYPT_STR,PASS_STR)' Decrypts the encrypted string CRYPT_STR using PASS_STR as the password. CRYPT_STR should be a string returned from `ENCODE()'. * `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 *Note ssl-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. * `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 *Note ssl-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 *Note `FLUSH DES_KEY_FILE': flush. 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. mysql> SELECT customer_address FROM customer_table > WHERE crypted_credit_card = DES_ENCRYPT('credit_card_number'); * `ENCODE(STR,PASS_STR)' Encrypt 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()'. The `ENCODE()' function 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('plaintext', 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. 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' multi-byte character set 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 binary string of 32 hex 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. 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()' returns the value of the pre-4.1 implementation of `PASSWORD()' as a binary string, and is intended to permit you to reset passwords for any pre-4.1 clients that need to connect to your version 5.1 MySQL server without locking them out. See *Note password-hashing::. * `PASSWORD(STR)' Calculates and returns a hashed password string from the plaintext password STR and returns a binary string, 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 `PASSWORD()' (as well as for the `IDENTIFIED BY' clause of the *Note `CREATE USER': create-user. and *Note `GRANT': grant. statements). The value determines whether or not to use `old' native MySQL password hashing. A value of 0 (or `OFF') causes passwords to be encrypted using the format available from MySQL 4.1 on. A value of 1 (or `ON') causes password encryption to use the older pre-4.1 format. If `old_passwords=1', `PASSWORD('STR')' returns the same value as `OLD_PASSWORD('STR')'. The latter function is not affected by the value of `old_passwords'. Examples: mysql> SET old_passwords = 0; mysql> SELECT PASSWORD('mypass'); +-------------------------------------------+ | PASSWORD('mypass') | +-------------------------------------------+ | *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 | +-------------------------------------------+ mysql> SET old_passwords = 1; mysql> SELECT PASSWORD('mypass'); +--------------------+ | PASSWORD('mypass') | +--------------------+ | 6f8c114b58f2ce9e | +--------------------+ Encryption performed by `PASSWORD()' is one-way (not reversible). It is not the same type of encryption as used for Unix passwords; for that, use `ENCRYPT()'. *Note*: The `PASSWORD()' function is used by the authentication system in MySQL Server; you should _not_ use it in your own applications. For that purpose, consider `MD5()' or `SHA1()' instead. Also see section 2 (Challenge-Response Authentication Mechanism (CRAM)), for more information about handling passwords and authentication securely in your applications. *Caution*: Statements that invoke `PASSWORD()' may be recorded in server logs or in a history file such as `~/.mysql_history', which means that cleartext passwords may be read by anyone having read access to that information. See *Note password-security::. * `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 binary string of 40 hex 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()'. 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. * `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  File: manual.info, Node: information-functions, Next: miscellaneous-functions, Prev: encryption-functions, Up: functions 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()' A 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()' Returns 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 *Note `mysql': mysql. client, which reports query execution times: mysql> SELECT BENCHMARK(1000000,ENCODE('hello','goodbye')); +----------------------------------------------+ | BENCHMARK(1000000,ENCODE('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 The return values have the meanings shown in the following table. Lower values have higher precedence. This table lists collation coercibility return values, the meaning of each value, and provides an example of each. 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 collation local variable `3' System `USER()' return value constant `4' Coercible Literal string `5' Ignorable `NULL' or an expression derived from `NULL' * `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. 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: * *Note `DROP USER': drop-user. * *Note `RENAME USER': rename-user. * *Note `GRANT': grant. * *Note `REVOKE': revoke. * *Note `CREATE FUNCTION': create-function. * *Note `CREATE PROCEDURE': create-procedure. * *Note `CREATE TRIGGER': create-trigger. * *Note `CREATE EVENT': create-event. * *Note `CREATE VIEW': create-view. * *Note `ALTER EVENT': alter-event. * *Note `ALTER VIEW': alter-view. * *Note `SET PASSWORD': set-password. For information about the implications that this expansion of `CURRENT_USER()' has for replication in different releases of MySQL 5.1, see *Note 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 *Note `SELECT': 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 a `SQL_CALC_FOUND_ROWS' option in the *Note `SELECT': 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 *Note `SELECT': select. returns a number indicating how many rows the first *Note `SELECT': 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 *Note `SELECT': 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 *Note `UNION': union. statements than for simple *Note `SELECT': select. statements, because `LIMIT' may occur at multiple places in a *Note `UNION': union. It may be applied to individual *Note `SELECT': select. statements in the *Note `UNION': union, or global to the *Note `UNION': union. result as a whole. The intent of `SQL_CALC_FOUND_ROWS' for *Note `UNION': 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 *Note `UNION': union. are: * The `SQL_CALC_FOUND_ROWS' keyword must appear in the first *Note `SELECT': select. of the *Note `UNION': union. * The value of `FOUND_ROWS()' is exact only if *Note `UNION ALL': union. is used. If *Note `UNION': union. without `ALL' is used, duplicate removal occurs and the value of `FOUND_ROWS()' is only approximate. * If no `LIMIT' is present in the *Note `UNION': union, `SQL_CALC_FOUND_ROWS' is ignored and returns the number of rows in the temporary table that is created to process the *Note `UNION': union. Beyond the cases described here, the behavior of `FOUND_ROWS()' is undefined (for example, its value following a *Note `SELECT': select. statement that fails with an error). *Important*: `FOUND_ROWS()' is not replicated reliably using statement-based replication. Starting with MySQL 5.1.23, this function is automatically replicated using row-based replication. * `LAST_INSERT_ID()', `LAST_INSERT_ID(EXPR)' For MySQL 5.1.12 and later, with no argument, `LAST_INSERT_ID()' returns a 64-bit value representing the first automatically generated value successfully inserted for an `AUTO_INCREMENT' column as a result of the most recently executed *Note `INSERT': insert. statement. The value has a type of `BIGINT UNSIGNED' as of MySQL 5.1.67, `BIGINT' (signed) before that. The value of `LAST_INSERT_ID()' remains unchanged if no rows are successfully inserted. With an argument, `LAST_INSERT_ID()' returns an unsigned integer as of MySQL 5.1.67, a signed integer before that. 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 In MySQL 5.1.11 and earlier, `LAST_INSERT_ID()' (with no argument) returns the first automatically generated value if any rows were successfully inserted or updated. This means that the returned value could be a value that was not successfully inserted into the table. If no rows were successfully inserted, `LAST_INSERT_ID()' returns 0. The value of `LAST_INSERT_ID()' will be consistent across all MySQL versions if all rows in the *Note `INSERT': insert. or *Note `UPDATE': update. statement were successful. if a table contains an `AUTO_INCREMENT' column and *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. updates (rather than inserts) a row, the value of `LAST_INSERT_ID()' is not meaningful prior to MySQL 5.1.12. For a workaround, see *Note insert-on-duplicate::. 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 *Note `INSERT': 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 *Note `ROLLBACK': commit, the value of `LAST_INSERT_ID()' is not restored to that before the transaction; it remains as it was at the point of the *Note `ROLLBACK': commit. 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 *Note `INSERT': 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 *Note `INSERT': insert. statement against some other server. For example: mysql> USE test; Database changed mysql> CREATE TABLE t ( -> id INT AUTO_INCREMENT NOT NULL PRIMARY KEY, -> name VARCHAR(10) NOT NULL -> ); Query OK, 0 rows affected (0.09 sec) mysql> INSERT INTO t VALUES (NULL, 'Bob'); Query OK, 1 row affected (0.01 sec) mysql> SELECT * FROM t; +----+------+ | id | name | +----+------+ | 1 | Bob | +----+------+ 1 row in set (0.01 sec) mysql> SELECT LAST_INSERT_ID(); +------------------+ | LAST_INSERT_ID() | +------------------+ | 1 | +------------------+ 1 row in set (0.00 sec) mysql> INSERT INTO t VALUES -> (NULL, 'Mary'), (NULL, 'Jane'), (NULL, 'Lisa'); Query OK, 3 rows affected (0.00 sec) Records: 3 Duplicates: 0 Warnings: 0 mysql> SELECT * FROM t; +----+------+ | id | name | +----+------+ | 1 | Bob | | 2 | Mary | | 3 | Jane | | 4 | Lisa | +----+------+ 4 rows in set (0.01 sec) mysql> SELECT LAST_INSERT_ID(); +------------------+ | LAST_INSERT_ID() | +------------------+ | 2 | +------------------+ 1 row in set (0.00 sec) Although the second *Note `INSERT': 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 *Note `SELECT': select. statement. If you use *Note `INSERT IGNORE': insert. and the row is ignored, the `AUTO_INCREMENT' counter is not incremented and `LAST_INSERT_ID()' returns `0', which reflects that no row was inserted. 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 *Note `UPDATE': update. statement increments the sequence counter and causes the next call to `LAST_INSERT_ID()' to return the updated value. The *Note `SELECT': select. statement retrieves that value. The *Note `mysql_insert_id()': mysql-insert-id. C API function can also be used to get the value. See *Note 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 *Note `UPDATE': update. statement and get their own sequence value with the *Note `SELECT': select. statement (or *Note `mysql_insert_id()': mysql-insert-id.), without affecting or being affected by other clients that generate their own sequence values. Note that *Note `mysql_insert_id()': mysql-insert-id. is only updated after *Note `INSERT': insert. and *Note `UPDATE': 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 *Note `SELECT': select. or *Note `SET': set-statement. * `ROW_COUNT()' `ROW_COUNT()' returns the number of rows changed, deleted, or inserted by the last statement if it was an *Note `UPDATE': update, *Note `DELETE': delete, or *Note `INSERT': insert. For other statements, the value may not be meaningful. For *Note `UPDATE': update. statements, the affected-rows value by default is the number of rows actually changed. If you specify the `CLIENT_FOUND_ROWS' flag to *Note `mysql_real_connect()': mysql-real-connect. when connecting to *Note `mysqld': mysqld, the affected-rows value is the number of rows `found'; that is, matched by the `WHERE' clause. For *Note `REPLACE': 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 *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. statements, the affected-rows value is 1 if the row is inserted as a new row and 2 if an existing row is updated. The `ROW_COUNT()' value is similar to the value from the *Note `mysql_affected_rows()': mysql-affected-rows. C API function and the row count that the *Note `mysql': 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. Beginning with MySQL 5.1.23, this function is automatically replicated using row-based replication. (Bug #30244) * `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()'. You can extract only the user name part like this: mysql> SELECT SUBSTRING_INDEX(USER(),'@',1); -> 'davida' * `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 *Note server-system-variables::. This function is unsafe for statement-based replication. Beginning with MySQL 5.1.42, a warning is logged if you use this function when `binlog_format' is set to `STATEMENT'. (Bug #47995) mysql> SELECT VERSION(); -> '5.1.73-standard'  File: manual.info, Node: miscellaneous-functions, Next: group-by-functions-and-modifiers, Prev: information-functions, Up: functions 12.15 Miscellaneous Functions ============================= *Miscellaneous Functions* Name Description `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 `IS_FREE_LOCK()' Checks whether the named lock is free `IS_USED_LOCK()' Checks 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_LOCK()' Releases the named lock `SLEEP()' Sleep for a number of seconds `UUID_SHORT()' Return an integer-valued universal identifier `UUID()' Return a Universal Unique Identifier (UUID) `VALUES()' Defines the values to be used during an INSERT * `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 *Note 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. 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 *Note `mysqladmin kill': mysqladmin.). If you have a lock obtained with `GET_LOCK()', it is released when you execute `RELEASE_LOCK()', execute a new `GET_LOCK()', or your connection terminates (either normally or abnormally). Locks obtained with `GET_LOCK()' do not interact with transactions. That is, committing a transaction does not release any such locks obtained during the transaction. This function 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 by one client, `GET_LOCK()' blocks any request by another client 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. mysql> SELECT GET_LOCK('lock1',10); -> 1 mysql> SELECT IS_FREE_LOCK('lock2'); -> 1 mysql> SELECT GET_LOCK('lock2',10); -> 1 mysql> SELECT RELEASE_LOCK('lock2'); -> 1 mysql> SELECT RELEASE_LOCK('lock1'); -> NULL The second `RELEASE_LOCK()' call returns `NULL' because the lock `'lock1'' was automatically released by the second `GET_LOCK()' call. If multiple clients are waiting for a lock, the order in which they will acquire it is undefined and depends on factors such as the thread library in use. In particular, applications should not assume that clients will acquire the lock in the same order that they issued the lock requests. *Note*: If a client attempts to acquire a lock that is already held by another client, it blocks according to the TIMEOUT argument. If the blocked client terminates, its thread does not die until the lock request times out. This is a known bug (fixed in MySQL 5.5). This function is unsafe for statement-based replication. Beginning with MySQL 5.1.42, a warning is logged if you use this function when `binlog_format' is set to `STATEMENT'. (Bug #47995) * `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 *Note `INT': integer-types, 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 *Note out-of-range-and-overflow::. * `INET_NTOA(EXPR)' Given a numeric IPv4 network address in network byte order, returns the dotted-quad representation of the address as a binary string. `INET_NTOA()' returns `NULL' if it does not understand its argument. mysql> SELECT INET_NTOA(167773449); -> '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. Beginning with MySQL 5.1.42, a warning is logged if you use this function when `binlog_format' is set to `STATEMENT'. (Bug #47995) * `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 that holds the lock. Otherwise, it returns `NULL'. This function is unsafe for statement-based replication. Beginning with MySQL 5.1.42, a warning is logged if you use this function when `binlog_format' is set to `STATEMENT'. (Bug #47995) * `MASTER_POS_WAIT(LOG_NAME,LOG_POS[,TIMEOUT])' 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. 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. This function is unsafe for statement-based replication. Beginning with MySQL 5.1.42, a warning is logged if you use this function when `binlog_format' is set to `STATEMENT'. (Bug #47995) * `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 *Note stored-programs-logging::, You might see this function in the output from *Note `mysqlbinlog': mysqlbinlog. * `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 *Note `DO': do. statement is convenient to use with `RELEASE_LOCK()'. See *Note do::. This function is unsafe for statement-based replication. Beginning with MySQL 5.1.42, a warning is logged if you use this function when `binlog_format' is set to `STATEMENT'. (Bug #47995) * `SLEEP(DURATION)' Sleeps (pauses) for the number of seconds given by the DURATION argument, then returns 0. If `SLEEP()' is interrupted, it returns 1. The duration may have a fractional part. This function is unsafe for statement-based replication. Beginning with MySQL 5.1.42, a warning is logged if you use this function when `binlog_format' is set to `STATEMENT'. (Bug #47995) * `UUID()' Returns a Universal Unique Identifier (UUID) generated according to `DCE 1.1: Remote Procedure Call' (Appendix A) CAE (Common Applications Environment) Specifications published by The Open Group in October 1997 (Document Number C706, `http://www.opengroup.org/public/pubs/catalog/c706.htm'). 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 computers that are not connected to each other. A UUID is a 128-bit number represented by a `utf8' string of five hexadecimal numbers in `aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' format: * The first three numbers are generated from a timestamp. * 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 computer has no Ethernet card, or we do not know how to find the hardware address of an interface on your operating system). In this case, spatial uniqueness cannot be guaranteed. Nevertheless, a collision should have _very_ low probability. Currently, 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-0040f4311e29' *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. *Note*: `UUID()' does not work with statement-based replication. * `UUID_SHORT()' Returns a `short' universal identifier as a 64-bit unsigned integer (rather than a string-form 128-bit identifier as returned by the `UUID()' function). The value of `UUID_SHORT()' is guaranteed to be unique if the following conditions hold: * The `server_id' of the current host is unique among your set of master and slave servers * `server_id' is between 0 and 255 * You do not set back your system time for your server between *Note `mysqld': mysqld. restarts * You do not invoke `UUID_SHORT()' on average more than 16 million times per second between *Note `mysqld': 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 that `UUID_SHORT()' does not work with statement-based replication. This function was added in MySQL 5.1.20. * `VALUES(COL_NAME)' In an *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. statement, you can use the `VALUES(COL_NAME)' function in the *Note `UPDATE': update. clause to refer to column values from the *Note `INSERT': insert. portion of the statement. In other words, `VALUES(COL_NAME)' in the *Note `UPDATE': 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 *Note `INSERT': insert. statements and returns `NULL' otherwise. See *Note 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);  File: manual.info, Node: group-by-functions-and-modifiers, Next: spatial-extensions, Prev: miscellaneous-functions, Up: functions 12.16 Functions and Modifiers for Use with `GROUP BY' Clauses ============================================================= * Menu: * group-by-functions:: `GROUP BY' (Aggregate) Functions * group-by-modifiers:: `GROUP BY' Modifiers * group-by-extensions:: MySQL Extensions to `GROUP BY'  File: manual.info, Node: group-by-functions, Next: group-by-modifiers, Prev: group-by-functions-and-modifiers, Up: group-by-functions-and-modifiers 12.16.1 `GROUP BY' (Aggregate) Functions ---------------------------------------- *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(DISTINCT)' Return the count of a number of different values `COUNT()' Return a count of the number of rows returned `GROUP_CONCAT()' Return a concatenated string `MAX()' Return the maximum value `MIN()' Return the minimum value `STD()' Return the population standard deviation `STDDEV_POP()' Return the population standard deviation `STDDEV_SAMP()' Return the sample standard deviation `STDDEV()' Return the population 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 This section describes group (aggregate) functions that operate on sets of values. 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 *Note group-by-extensions::. For numeric arguments, the variance and standard deviation functions return a *Note `DOUBLE': floating-point-types. value. The `SUM()' and `AVG()' functions return a *Note `DECIMAL': fixed-point-types. value for exact-value arguments (integer or *Note `DECIMAL': fixed-point-types.), and a *Note `DOUBLE': floating-point-types. value for approximate-value arguments (*Note `FLOAT': floating-point-types. or *Note `DOUBLE': floating-point-types.). 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 *Note `SET': set. or *Note `ENUM': enum. values, the cast operation causes the underlying numeric value to be used. * `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. `AVG()' returns `NULL' if there were no matching rows. 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 (*Note `BIGINT': integer-types.) precision. This function returns `18446744073709551615' if there were no matching rows. (This is the value of an unsigned *Note `BIGINT': integer-types. value with all bits set to 1.) * `BIT_OR(EXPR)' Returns the bitwise `OR' of all bits in EXPR. The calculation is performed with 64-bit (*Note `BIGINT': integer-types.) precision. This function returns `0' if there were no matching rows. * `BIT_XOR(EXPR)' Returns the bitwise `XOR' of all bits in EXPR. The calculation is performed with 64-bit (*Note `BIGINT': integer-types.) precision. This function returns `0' if there were no matching rows. * `COUNT(EXPR)' Returns a count of the number of non-`NULL' values of EXPR in the rows retrieved by a *Note `SELECT': select. statement. The result is a *Note `BIGINT': integer-types. value. `COUNT()' returns `0' if there were no matching rows. 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. `COUNT(*)' is optimized to return very quickly if the *Note `SELECT': 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 applies only to `MyISAM' tables only, because an exact row count is stored for this storage engine and can be accessed very quickly. For transactional storage engines such as `InnoDB', storing an exact row count is more problematic because multiple transactions may be occurring, each of which may affect the count. * `COUNT(DISTINCT EXPR,[EXPR...])' Returns a count of the number of rows with different non-`NULL' EXPR values. `COUNT(DISTINCT)' returns `0' if there were no matching rows. 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 *Note `TEXT': blob. or *Note `BLOB': blob. unless `group_concat_max_len' is less than or equal to 512, in which case the result type is *Note `VARCHAR': char. or *Note `VARBINARY': binary-varbinary. See also `CONCAT()' and `CONCAT_WS()': *Note string-functions::. * `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 *Note 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'. `MAX()' returns `NULL' if there were no matching rows. mysql> SELECT student_name, MIN(test_score), MAX(test_score) -> FROM student -> GROUP BY student_name; For `MAX()', MySQL currently compares *Note `ENUM': enum. and *Note `SET': 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. This is expected to be rectified in a future MySQL release. * `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 *Note 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'. `MIN()' returns `NULL' if there were no matching rows. mysql> SELECT student_name, MIN(test_score), MAX(test_score) -> FROM student -> GROUP BY student_name; For `MIN()', MySQL currently compares *Note `ENUM': enum. and *Note `SET': 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. This is expected to be rectified in a future MySQL release. * `STD(EXPR)' Returns the population standard deviation of EXPR. This is an extension to standard SQL. The standard SQL function `STDDEV_POP()' can be used instead. This function returns `NULL' if there were no matching rows. * `STDDEV(EXPR)' Returns the population standard deviation of EXPR. This function is provided for compatibility with Oracle. The standard SQL function `STDDEV_POP()' can be used instead. This function returns `NULL' if there were no matching rows. * `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. `STDDEV_POP()' returns `NULL' if there were no matching rows. * `STDDEV_SAMP(EXPR)' Returns the sample standard deviation of EXPR (the square root of `VAR_SAMP()'. `STDDEV_SAMP()' returns `NULL' if there were no matching rows. * `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. `SUM()' returns `NULL' if there were no matching rows. * `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. `VAR_POP()' returns `NULL' if there were no matching rows. * `VAR_SAMP(EXPR)' Returns the sample variance of EXPR. That is, the denominator is the number of rows minus one. `VAR_SAMP()' returns `NULL' if there were no matching rows. * `VARIANCE(EXPR)' Returns the population standard variance of EXPR. This is an extension to standard SQL. The standard SQL function `VAR_POP()' can be used instead. `VARIANCE()' returns `NULL' if there were no matching rows.  File: manual.info, Node: group-by-modifiers, Next: group-by-extensions, Prev: group-by-functions, Up: group-by-functions-and-modifiers 12.16.2 `GROUP BY' Modifiers ---------------------------- The `GROUP BY' clause permits a `WITH ROLLUP' modifier that causes extra rows to be added to the summary output. These rows represent higher-level (or super-aggregate) summary operations. `ROLLUP' thus enables you to answer questions at multiple levels of analysis with a single query. It can be used, for example, to provide support for OLAP (Online Analytical Processing) operations. Suppose that a table named `sales' has `year', `country', `product', and `profit' columns for recording sales profitability: CREATE TABLE sales ( year INT NOT NULL, country VARCHAR(20) NOT NULL, product VARCHAR(32) NOT NULL, profit INT ); The table's contents can be summarized per year with a simple `GROUP BY' like this: mysql> SELECT year, SUM(profit) FROM sales GROUP BY year; +------+-------------+ | year | SUM(profit) | +------+-------------+ | 2000 | 4525 | | 2001 | 3010 | +------+-------------+ This output shows the total profit for each year, but if you also want to 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) FROM sales GROUP BY year WITH ROLLUP; +------+-------------+ | year | SUM(profit) | +------+-------------+ | 2000 | 4525 | | 2001 | 3010 | | NULL | 7535 | +------+-------------+ The grand total super-aggregate line is identified by the value `NULL' in the `year' column. `ROLLUP' has a more complex effect when there are multiple `GROUP BY' columns. In this case, each time there is a `break' (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 on the `sales' table based on `year', `country', and `product' might look like this: mysql> SELECT year, country, product, SUM(profit) -> FROM sales -> GROUP BY year, country, product; +------+---------+------------+-------------+ | year | country | product | SUM(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 | +------+---------+------------+-------------+ The output indicates summary values only at the year/country/product level of analysis. When `ROLLUP' is added, the query produces several extra rows: mysql> SELECT year, country, product, SUM(profit) -> FROM sales -> GROUP BY year, country, product WITH ROLLUP; +------+---------+------------+-------------+ | year | country | product | SUM(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 | +------+---------+------------+-------------+ For this query, adding `ROLLUP' causes the output to include summary information at four levels of analysis, not just one. Here is how to interpret the `ROLLUP' output: * Following each set of product rows for a given year and country, an extra summary row is produced 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 is produced 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 is produced 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 items list 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. However, you still have some control over sort order. `GROUP BY' in MySQL sorts results, and you can use explicit `ASC' and `DESC' keywords with columns named in the `GROUP BY' list to specify sort order for individual columns. (The higher-level summary rows added by `ROLLUP' still appear after the rows from which they are calculated, regardless of the sort order.) `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) -> FROM sales -> GROUP BY year, country, product WITH ROLLUP -> LIMIT 5; +------+---------+------------+-------------+ | year | country | product | SUM(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 you have 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 is a lexical match to any of those names, its value is set to `NULL'. (If you specify grouping columns by column number, the server identifies which columns to set to `NULL' by number.) Because the `NULL' values in the super-aggregate rows are placed into the result set at such a late stage in query processing, you cannot test them as `NULL' values within the query itself. For example, you cannot add `HAVING product IS NULL' to the query to eliminate from the output all but the super-aggregate rows. On the other hand, the `NULL' values do appear as `NULL' on the client side and can be tested as such using any MySQL client programming interface. MySQL permits a column that does not appear in the `GROUP BY' list to be named in the select list. 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 indeterminate: mysql> SELECT year, country, SUM(profit) -> FROM sales GROUP BY year WITH ROLLUP; +------+---------+-------------+ | year | country | SUM(profit) | +------+---------+-------------+ | 2000 | India | 4525 | | 2001 | USA | 3010 | | NULL | USA | 7535 | +------+---------+-------------+ This behavior occurs if 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. For more information about nonaggregated columns and `GROUP BY', see *Note group-by-extensions::.  File: manual.info, Node: group-by-extensions, Prev: group-by-modifiers, Up: group-by-functions-and-modifiers 12.16.3 MySQL Extensions to `GROUP BY' -------------------------------------- In standard SQL, a query that includes a `GROUP BY' clause cannot refer to nonaggregated columns in the select list that are not named in the `GROUP BY' clause. For example, this query is illegal in standard SQL because the `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, the `name' column must be omitted from the select list or named in the `GROUP BY' clause. MySQL extends the use of `GROUP BY' so that the select list can refer to nonaggregated columns not named in the `GROUP BY' clause. This means that the preceding query is legal in MySQL. You can use this feature to get better performance by avoiding unnecessary column sorting and grouping. However, this is useful primarily when all values in each nonaggregated column not named in the `GROUP BY' are the same for each group. The server is free to choose any value from each group, so unless they are the same, the values chosen are indeterminate. Furthermore, the selection of values from each group cannot be influenced by adding an `ORDER BY' clause. Sorting of the result set occurs after values have been chosen, and `ORDER BY' does not affect which values within each group the server chooses. A similar MySQL extension applies to the `HAVING' clause. In standard SQL, a query that includes a `GROUP BY' clause cannot refer to nonaggregated columns in the `HAVING' clause that are not named in the `GROUP BY' clause. A MySQL extension permits references to such columns to simplify calculations. This extension assumes that the nongrouped columns will have the same group-wise values. Otherwise, the result is indeterminate. To disable the MySQL `GROUP BY' extension, enable the `ONLY_FULL_GROUP_BY' SQL mode. This enables standard SQL behavior: Columns not named in the `GROUP BY' clause cannot be used in the select list or `HAVING' clause unless enclosed in an aggregate function. `ONLY_FULL_GROUP_BY' also affects use of aliases in the `HAVING' clauses. 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; MySQL extends this behavior to permit 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; Enabling `ONLY_FULL_GROUP_BY' disables this MySQL extension and a `non-grouping field 'c' is used in HAVING clause' error occurs because the column `c' in the `HAVING' clause is not enclosed in an aggregate function (instead, it _is_ an aggregate function). The select list extension also applies to `ORDER BY'. That is, you can refer to nonaggregated columns in the `ORDER BY' clause that do not appear in the `GROUP BY' clause. (However, as mentioned previously, `ORDER BY' does not affect which values are chosen from nonaggregated columns; it only sorts them after they have been chosen.) This extension does not apply if the `ONLY_FULL_GROUP_BY' SQL mode is enabled. In some cases, you can use `MIN()' and `MAX()' to obtain a specific column value even if it is not unique. If the `sort' column contains integers no larger than 6 digits, the following query gives the value of `column' from the row containing the smallest `sort' value: SUBSTR(MIN(CONCAT(LPAD(sort,6,'0'),column)),7) See *Note example-maximum-column-group-row::. If you are trying to follow standard SQL, you cannot use expressions in `GROUP BY' clauses. As a workaround, use an alias for the expression: SELECT id, FLOOR(value/100) AS val FROM TBL_NAME GROUP BY id, val; MySQL permits expressions in `GROUP BY' clauses, so the alias is unnecessary: SELECT id, FLOOR(value/100) FROM TBL_NAME GROUP BY id, FLOOR(value/100);  File: manual.info, Node: spatial-extensions, Next: precision-math, Prev: group-by-functions-and-modifiers, Up: functions 12.17 Spatial Extensions ======================== * Menu: * gis-introduction:: Introduction to MySQL Spatial Support * opengis-geometry-model:: The OpenGIS Geometry Model * supported-spatial-data-formats:: Supported Spatial Data Formats * creating-a-spatially-enabled-mysql-database:: Creating a Spatially Enabled MySQL Database * spatial-analysis-functions:: Spatial Analysis Functions * optimizing-spatial-analysis:: Optimizing Spatial Analysis * mysql-gis-conformance-and-compatibility:: MySQL Conformance and Compatibility MySQL supports spatial extensions to enable the generation, storage, and analysis of geographic features. These features are available for `MyISAM', `InnoDB', *Note `NDB': mysql-cluster, and `ARCHIVE' tables. For spatial columns, `MyISAM' supports both `SPATIAL' and non-`SPATIAL' indexes. Other storage engines support non-`SPATIAL' indexes, as described in *Note create-index::. This chapter covers the following topics: * The basis of these 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 * Additional Resources * * The Open Geospatial Consortium publishes the `OpenGIS(R) Simple Features Specifications For SQL', a document that proposes several conceptual ways for extending an SQL RDBMS to support spatial data. This specification is available from the OGC Web site at `http://www.opengis.org/docs/99-049.pdf'. * 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'.  File: manual.info, Node: gis-introduction, Next: opengis-geometry-model, Prev: spatial-extensions, Up: spatial-extensions 12.17.1 Introduction to MySQL Spatial Support --------------------------------------------- MySQL implements spatial extensions following the specification of the Open Geospatial Consortium (OGC). This 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 OGC maintains a Web site at `http://www.opengis.org/'. In 1997, the Open Geospatial Consortium published the `OpenGIS(R) Simple Features Specifications For SQL', a document that proposes several conceptual ways for extending an SQL RDBMS to support spatial data. This specification is available from the OGC Web site at `http://www.opengis.org/docs/99-049.pdf'. It contains additional information relevant to this chapter. MySQL implements a subset of the *SQL with Geometry Types* environment proposed by OGC. 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 describe a set of SQL geometry types, as well as functions on those types to create and analyze geometry values. 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. This chapter uses all of these terms synonymously: *geographic feature*, *geospatial feature*, *feature*, or *geometry*. Here, 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_.  File: manual.info, Node: opengis-geometry-model, Next: supported-spatial-data-formats, Prev: gis-introduction, Up: spatial-extensions 12.17.2 The OpenGIS Geometry Model ---------------------------------- * Menu: * gis-geometry-class-hierarchy:: The Geometry Class Hierarchy * gis-class-geometry:: Class `Geometry' * gis-class-point:: Class `Point' * gis-class-curve:: Class `Curve' * gis-class-linestring:: Class `LineString' * gis-class-surface:: Class `Surface' * gis-class-polygon:: Class `Polygon' * gis-class-geometrycollection:: Class `GeometryCollection' * gis-class-multipoint:: Class `MultiPoint' * gis-class-multicurve:: Class `MultiCurve' * gis-class-multilinestring:: Class `MultiLineString' * gis-class-multisurface:: Class `MultiSurface' * gis-class-multipolygon:: Class `MultiPolygon' 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.  File: manual.info, Node: gis-geometry-class-hierarchy, Next: gis-class-geometry, Prev: opengis-geometry-model, Up: opengis-geometry-model 12.17.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.  File: manual.info, Node: gis-class-geometry, Next: gis-class-point, Prev: gis-geometry-class-hierarchy, Up: opengis-geometry-model 12.17.2.2 Class `Geometry' .......................... `Geometry' is the root class of the hierarchy. It is a noninstantiable class but has a number of properties that are common to all geometry values created from any of the `Geometry' subclasses. These properties are described in the following list. 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 just an integer associated with the geometry value. All calculations are done assuming Euclidean (planar) geometry. * 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 *geocentric* 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.  File: manual.info, Node: gis-class-point, Next: gis-class-curve, Prev: gis-class-geometry, Up: opengis-geometry-model 12.17.2.3 Class `Point' ....................... 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.  File: manual.info, Node: gis-class-curve, Next: gis-class-linestring, Prev: gis-class-point, Up: opengis-geometry-model 12.17.2.4 Class `Curve' ....................... 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. * 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'.  File: manual.info, Node: gis-class-linestring, Next: gis-class-surface, Prev: gis-class-curve, Up: opengis-geometry-model 12.17.2.5 Class `LineString' ............................ 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.  File: manual.info, Node: gis-class-surface, Next: gis-class-polygon, Prev: gis-class-linestring, Up: opengis-geometry-model 12.17.2.6 Class `Surface' ......................... 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.  File: manual.info, Node: gis-class-polygon, Next: gis-class-geometrycollection, Prev: gis-class-surface, Up: opengis-geometry-model 12.17.2.7 Class `Polygon' ......................... 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.  File: manual.info, Node: gis-class-geometrycollection, Next: gis-class-multipoint, Prev: gis-class-polygon, Up: opengis-geometry-model 12.17.2.8 Class `GeometryCollection' .................................... A `GeometryCollection' is a geometry that is a collection of one or more geometries of any class. All the elements in a `GeometryCollection' 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 `GeometryCollection', 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  File: manual.info, Node: gis-class-multipoint, Next: gis-class-multicurve, Prev: gis-class-geometrycollection, Up: opengis-geometry-model 12.17.2.9 Class `MultiPoint' ............................ 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.  File: manual.info, Node: gis-class-multicurve, Next: gis-class-multilinestring, Prev: gis-class-multipoint, Up: opengis-geometry-model 12.17.2.10 Class `MultiCurve' ............................. 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 `MultiCurve' elements. * A `MultiCurve' is closed if all of its elements are closed. * The boundary of a closed `MultiCurve' is always empty.  File: manual.info, Node: gis-class-multilinestring, Next: gis-class-multisurface, Prev: gis-class-multicurve, Up: opengis-geometry-model 12.17.2.11 Class `MultiLineString' .................................. 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.  File: manual.info, Node: gis-class-multisurface, Next: gis-class-multipolygon, Prev: gis-class-multilinestring, Up: opengis-geometry-model 12.17.2.12 Class `MultiSurface' ............................... A `MultiSurface' is a geometry collection composed of surface elements. `MultiSurface' is a noninstantiable class. Its only instantiable subclass is `MultiPolygon'. *`MultiSurface' Assertions* * Two `MultiSurface' surfaces have no interiors that intersect. * Two `MultiSurface' elements have boundaries that intersect at most at a finite number of points.  File: manual.info, Node: gis-class-multipolygon, Prev: gis-class-multisurface, Up: opengis-geometry-model 12.17.2.13 Class `MultiPolygon' ............................... 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'.  File: manual.info, Node: supported-spatial-data-formats, Next: creating-a-spatially-enabled-mysql-database, Prev: opengis-geometry-model, Up: spatial-extensions 12.17.3 Supported Spatial Data Formats -------------------------------------- * Menu: * gis-wkt-format:: Well-Known Text (WKT) Format * gis-wkb-format:: Well-Known Binary (WKB) Format This section describes the standard spatial data formats that are used to represent geometry objects in queries. They are: * 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.  File: manual.info, Node: gis-wkt-format, Next: gis-wkb-format, Prev: supported-spatial-data-formats, Up: supported-spatial-data-formats 12.17.3.1 Well-Known Text (WKT) Format ...................................... The Well-Known Text (WKT) representation of Geometry is designed to exchange geometry data in ASCII form. For a Backus-Naur grammar that specifies the formal production rules for writing WKT values, see the OpenGIS specification document referenced in *Note spatial-extensions::. Examples of WKT representations of geometry objects: * A `Point': POINT(15 20) Note that 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 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 `GeomFromText()'. mysql> SELECT X(POINT(15, 20)); +------------------+ | X(POINT(15, 20)) | +------------------+ | 15 | +------------------+ mysql> SELECT X(GeomFromText('POINT(15 20)')); +---------------------------------+ | X(GeomFromText('POINT(15 20)')) | +---------------------------------+ | 15 | +---------------------------------+ * A `LineString' with four points: LINESTRING(0 0, 10 10, 20 25, 50 60) Note that 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) * 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))  File: manual.info, Node: gis-wkb-format, Prev: gis-wkt-format, Up: supported-spatial-data-formats 12.17.3.2 Well-Known Binary (WKB) Format ........................................ The Well-Known Binary (WKB) representation for geometric values is defined by the OpenGIS specification. It is also defined in the ISO `SQL/MM Part 3: Spatial' standard. WKB is used to exchange geometry data as binary streams represented by *Note `BLOB': blob. values containing geometric WKB information. 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 here by two hex digits): 0101000000000000000000F03F000000000000F03F The sequence may be broken down into these components: Byte order : 01 WKB type : 01000000 X : 000000000000F03F Y : 000000000000F03F Component representation is as follows: * The byte order may be either 1 or 0 to indicate 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. Values from 1 through 7 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 are represented by more complex data structures, as detailed in the OpenGIS specification.  File: manual.info, Node: creating-a-spatially-enabled-mysql-database, Next: spatial-analysis-functions, Prev: supported-spatial-data-formats, Up: spatial-extensions 12.17.4 Creating a Spatially Enabled MySQL Database --------------------------------------------------- * Menu: * mysql-spatial-datatypes:: MySQL Spatial Data Types * creating-spatial-values:: Creating Spatial Values * creating-spatial-columns:: Creating Spatial Columns * populating-spatial-columns:: Populating Spatial Columns * fetching-spatial-data:: Fetching Spatial Data This section describes the data types you can use for representing spatial data in MySQL, and the functions available for creating and retrieving spatial values.  File: manual.info, Node: mysql-spatial-datatypes, Next: creating-spatial-values, Prev: creating-a-spatially-enabled-mysql-database, Up: creating-a-spatially-enabled-mysql-database 12.17.4.1 MySQL Spatial Data Types .................................. MySQL has data types that correspond to OpenGIS classes. Some of these 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 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.  File: manual.info, Node: creating-spatial-values, Next: creating-spatial-columns, Prev: mysql-spatial-datatypes, Up: creating-a-spatially-enabled-mysql-database 12.17.4.2 Creating Spatial Values ................................. * Menu: * gis-wkt-functions:: Creating Geometry Values Using WKT Functions * gis-wkb-functions:: Creating Geometry Values Using WKB Functions * gis-mysql-specific-functions:: Creating Geometry Values Using MySQL-Specific Functions This section describes how to create spatial values using Well-Known Text and Well-Known Binary functions that are defined in the OpenGIS standard, and using MySQL-specific functions.  File: manual.info, Node: gis-wkt-functions, Next: gis-wkb-functions, Prev: creating-spatial-values, Up: creating-spatial-values 12.17.4.3 Creating Geometry Values Using WKT Functions ...................................................... MySQL provides a number of functions that take as arguments a Well-Known Text representation and, optionally, a spatial reference system identifier (SRID). They return the corresponding geometry. `GeomFromText()' accepts a WKT of any geometry type as its first argument. An implementation also provides type-specific construction functions for construction of geometry values of each geometry type. * `GeomCollFromText(WKT[,SRID])', `GeometryCollectionFromText(WKT[,SRID])' Constructs a `GEOMETRYCOLLECTION' value using its WKT representation and SRID. * `GeomFromText(WKT[,SRID])', `GeometryFromText(WKT[,SRID])' Constructs a geometry value of any type using its WKT representation and SRID. * `LineFromText(WKT[,SRID])', `LineStringFromText(WKT[,SRID])' Constructs a `LINESTRING' value using its WKT representation and SRID. * `MLineFromText(WKT[,SRID])', `MultiLineStringFromText(WKT[,SRID])' Constructs a `MULTILINESTRING' value using its WKT representation and SRID. * `MPointFromText(WKT[,SRID])', `MultiPointFromText(WKT[,SRID])' Constructs a `MULTIPOINT' value using its WKT representation and SRID. * `MPolyFromText(WKT[,SRID])', `MultiPolygonFromText(WKT[,SRID])' Constructs a `MULTIPOLYGON' value using its WKT representation and SRID. * `PointFromText(WKT[,SRID])' Constructs a `POINT' value using its WKT representation and SRID. * `PolyFromText(WKT[,SRID])', `PolygonFromText(WKT[,SRID])' Constructs a `POLYGON' value using its WKT representation and SRID. The OpenGIS specification also defines the following optional functions, which MySQL does not implement. These functions construct `Polygon' or `MultiPolygon' values based on the WKT representation of a collection of rings or closed `LineString' values. These values may intersect. * `BdMPolyFromText(WKT,SRID)' Constructs a `MultiPolygon' value from a `MultiLineString' value in WKT format containing an arbitrary collection of closed `LineString' values. * `BdPolyFromText(WKT,SRID)' Constructs a `Polygon' value from a `MultiLineString' value in WKT format containing an arbitrary collection of closed `LineString' values.  File: manual.info, Node: gis-wkb-functions, Next: gis-mysql-specific-functions, Prev: gis-wkt-functions, Up: creating-spatial-values 12.17.4.4 Creating Geometry Values Using WKB Functions ...................................................... MySQL provides a number of functions that take as arguments a *Note `BLOB': blob. containing a Well-Known Binary representation and, optionally, a spatial reference system identifier (SRID). They return the corresponding geometry. As of MySQL 5.1.35, these functions also accept geometry objects for compatibility with the changes made in MySQL 5.1.35 to the return value of the functions in *Note gis-mysql-specific-functions::. Thus, those functions may continue to be used to provide the first argument to the functions in this section. * `GeomCollFromWKB(WKB[,SRID])', `GeometryCollectionFromWKB(WKB[,SRID])' Constructs a `GEOMETRYCOLLECTION' value using its WKB representation and SRID. * `GeomFromWKB(WKB[,SRID])', `GeometryFromWKB(WKB[,SRID])' Constructs a geometry value of any type using its WKB representation and SRID. * `LineFromWKB(WKB[,SRID])', `LineStringFromWKB(WKB[,SRID])' Constructs a `LINESTRING' value using its WKB representation and SRID. * `MLineFromWKB(WKB[,SRID])', `MultiLineStringFromWKB(WKB[,SRID])' Constructs a `MULTILINESTRING' value using its WKB representation and SRID. * `MPointFromWKB(WKB[,SRID])', `MultiPointFromWKB(WKB[,SRID])' Constructs a `MULTIPOINT' value using its WKB representation and SRID. * `MPolyFromWKB(WKB[,SRID])', `MultiPolygonFromWKB(WKB[,SRID])' Constructs a `MULTIPOLYGON' value using its WKB representation and SRID. * `PointFromWKB(WKB[,SRID])' Constructs a `POINT' value using its WKB representation and SRID. * `PolyFromWKB(WKB[,SRID])', `PolygonFromWKB(WKB[,SRID])' Constructs a `POLYGON' value using its WKB representation and SRID. The OpenGIS specification also describes optional functions for constructing `Polygon' or `MultiPolygon' values based on the WKB representation of a collection of rings or closed `LineString' values. These values may intersect. MySQL does not implement these functions: * `BdMPolyFromWKB(WKB,SRID)' Constructs a `MultiPolygon' value from a `MultiLineString' value in WKB format containing an arbitrary collection of closed `LineString' values. * `BdPolyFromWKB(WKB,SRID)' Constructs a `Polygon' value from a `MultiLineString' value in WKB format containing an arbitrary collection of closed `LineString' values.  File: manual.info, Node: gis-mysql-specific-functions, Prev: gis-wkb-functions, Up: creating-spatial-values 12.17.4.5 Creating Geometry Values Using MySQL-Specific Functions ................................................................. 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. As of MySQL 5.1.35, 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'. Before MySQL 5.1.35, these functions produce *Note `BLOB': blob. values containing WKB representations of geometry values with no SRID from WKB arguments. The WKB value returned from these functions can be converted to geometry arguments by using them as the first argument to functions in the `GeomFromWKB()' function family. For example, as of MySQL 5.1.35, you can insert the geometry return value from `Point()' directly into a `Point' column: INSERT INTO t1 (pt_col) VALUES(Point(1,2)); Prior to MySQL 5.1.35, convert the WKB return value to a `Point' before inserting it: INSERT INTO t1 (pt_col) VALUES(GeomFromWKB(Point(1,2))); * `GeometryCollection(G1,G2,...)' Constructs a `GeometryCollection'. * `LineString(PT1,PT2,...)' 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(LS1,LS2,...)' Constructs a `MultiLineString' value using `LineString' or WKB `LineString' arguments. * `MultiPoint(PT1,PT2,...)' Constructs a `MultiPoint' value using `Point' or WKB `Point' arguments. * `MultiPolygon(POLY1,POLY2,...)' Constructs a `MultiPolygon' value from a set of `Polygon' or WKB `Polygon' arguments. * `Point(X,Y)' Constructs a `Point' using its coordinates. * `Polygon(LS1,LS2,...)' 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'.  File: manual.info, Node: creating-spatial-columns, Next: populating-spatial-columns, Prev: creating-spatial-values, Up: creating-a-spatially-enabled-mysql-database 12.17.4.6 Creating Spatial Columns .................................. MySQL provides a standard way of creating spatial columns for geometry types, for example, with *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. Currently, spatial columns are supported for `MyISAM', `InnoDB', *Note `NDB': mysql-cluster, and `ARCHIVE' tables. See also the annotations about spatial indexes under *Note creating-spatial-indexes::. * Use the *Note `CREATE TABLE': create-table. statement to create a table with a spatial column: CREATE TABLE geom (g GEOMETRY); * Use the *Note `ALTER TABLE': 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;  File: manual.info, Node: populating-spatial-columns, Next: fetching-spatial-data, Prev: creating-spatial-columns, Up: creating-a-spatially-enabled-mysql-database 12.17.4.7 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 into internal geometry format: * Perform the conversion directly in the *Note `INSERT': insert. statement: INSERT INTO geom VALUES (GeomFromText('POINT(1 1)')); SET @g = 'POINT(1 1)'; INSERT INTO geom VALUES (GeomFromText(@g)); * Perform the conversion prior to the *Note `INSERT': insert.: SET @g = 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 (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 (GeomFromText(@g)); SET @g = 'GEOMETRYCOLLECTION(POINT(1 1),LINESTRING(0 0,1 1,2 2,3 3,4 4))'; INSERT INTO geom VALUES (GeomFromText(@g)); The preceding examples all use `GeomFromText()' to create geometry values. You can also use type-specific functions: SET @g = 'POINT(1 1)'; INSERT INTO geom VALUES (PointFromText(@g)); SET @g = 'LINESTRING(0 0,1 1,2 2)'; INSERT INTO geom VALUES (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 (PolygonFromText(@g)); SET @g = 'GEOMETRYCOLLECTION(POINT(1 1),LINESTRING(0 0,1 1,2 2,3 3,4 4))'; INSERT INTO geom VALUES (GeomCollFromText(@g)); Note that if a client application program wants to use WKB representations of geometry values, it is responsible for sending correctly formed WKB in queries to the server. However, there are several ways of satisfying this requirement. For example: * Inserting a `POINT(1 1)' value with hex literal syntax: mysql> INSERT INTO geom VALUES -> (GeomFromWKB(0x0101000000000000000000F03F000000000000F03F)); * An ODBC application can send a WKB representation, binding it to a placeholder using an argument of *Note `BLOB': blob. type: INSERT INTO geom VALUES (GeomFromWKB(?)) Other programming interfaces may support a similar placeholder mechanism. * In a C program, you can escape a binary value using *Note `mysql_real_escape_string()': mysql-real-escape-string. and include the result in a query string that is sent to the server. See *Note mysql-real-escape-string::.  File: manual.info, Node: fetching-spatial-data, Prev: populating-spatial-columns, Up: creating-a-spatially-enabled-mysql-database 12.17.4.8 Fetching Spatial Data ............................... Geometry values stored in a table can be fetched in internal format. You can also convert them into 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 `AsText()' function converts a geometry from internal format into a WKT string. SELECT AsText(g) FROM geom; * Fetching spatial data in WKB format: The `AsBinary()' function converts a geometry from internal format into a *Note `BLOB': blob. containing the WKB value. SELECT AsBinary(g) FROM geom;  File: manual.info, Node: spatial-analysis-functions, Next: optimizing-spatial-analysis, Prev: creating-a-spatially-enabled-mysql-database, Up: spatial-extensions 12.17.5 Spatial Analysis Functions ---------------------------------- * Menu: * functions-to-convert-geometries-between-formats:: Geometry Format Conversion Functions * geometry-property-functions:: `Geometry' Property Functions * functions-that-create-new-geometries-from-existing-ones:: Functions That Create New Geometries from Existing Ones * functions-for-testing-spatial-relations-between-geometric-objects:: Functions for Testing Spatial Relations Between Geometric Objects After populating spatial columns with values, you are ready to query and analyze them. MySQL provides a set of functions to perform various operations on spatial data. These functions can be grouped into four major categories according to the type of operation they perform: * Functions that convert geometries between various formats * Functions that provide access to qualitative or quantitative properties of a geometry * Functions that describe relations between two geometries * Functions that create new geometries from existing ones Spatial analysis functions can be used in many contexts, such as: * Any interactive SQL program, such as *Note `mysql': mysql. * Application programs written in any language that supports a MySQL client API  File: manual.info, Node: functions-to-convert-geometries-between-formats, Next: geometry-property-functions, Prev: spatial-analysis-functions, Up: spatial-analysis-functions 12.17.5.1 Geometry Format Conversion Functions .............................................. MySQL supports the following functions for converting geometry values between internal format and either WKT or WKB format: * `AsBinary(G)', `AsWKB(G)' Converts a value in internal geometry format to its WKB representation and returns the binary result. SELECT AsBinary(g) FROM geom; * `AsText(G)', `AsWKT(G)' Converts a value in internal geometry format to its WKT representation and returns the string result. mysql> SET @g = 'LineString(1 1,2 2,3 3)'; mysql> SELECT AsText(GeomFromText(@g)); +--------------------------+ | AsText(GeomFromText(@g)) | +--------------------------+ | LINESTRING(1 1,2 2,3 3) | +--------------------------+ * `GeomFromText(WKT[,SRID])' Converts a string value from its WKT representation into internal geometry format and returns the result. A number of type-specific functions are also supported, such as `PointFromText()' and `LineFromText()'. See *Note gis-wkt-functions::. * `GeomFromWKB(WKB[,SRID])' Converts a binary value from its WKB representation into internal geometry format and returns the result. A number of type-specific functions are also supported, such as `PointFromWKB()' and `LineFromWKB()'. See *Note gis-wkb-functions::.  File: manual.info, Node: geometry-property-functions, Next: functions-that-create-new-geometries-from-existing-ones, Prev: functions-to-convert-geometries-between-formats, Up: spatial-analysis-functions 12.17.5.2 `Geometry' Property Functions ....................................... * Menu: * general-geometry-property-functions:: General Geometry Functions * point-property-functions:: `Point' Functions * linestring-property-functions:: `LineString' Functions * multilinestring-property-functions:: `MultiLineString' Functions * polygon-property-functions:: `Polygon' Functions * multipolygon-property-functions:: `MultiPolygon' Functions * geometrycollection-property-functions:: `GeometryCollection' 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, `Area()' returns `NULL' if the object type is neither `Polygon' nor `MultiPolygon'.  File: manual.info, Node: general-geometry-property-functions, Next: point-property-functions, Prev: geometry-property-functions, Up: geometry-property-functions 12.17.5.3 General Geometry Functions .................................... The functions listed in this section do not restrict their argument and accept a geometry value of any type. * `Dimension(G)' Returns the inherent dimension of the geometry value G. The result can be -1, 0, 1, or 2. The meaning of these values is given in *Note gis-class-geometry::. mysql> SELECT Dimension(GeomFromText('LineString(1 1,2 2)')); +------------------------------------------------+ | Dimension(GeomFromText('LineString(1 1,2 2)')) | +------------------------------------------------+ | 1 | +------------------------------------------------+ * `Envelope(G)' Returns the Minimum Bounding Rectangle (MBR) for the geometry value G. The result is returned as a `Polygon' value. The polygon is defined by the corner points of the bounding box: POLYGON((MINX MINY, MAXX MINY, MAXX MAXY, MINX MAXY, MINX MINY)) mysql> SELECT AsText(Envelope(GeomFromText('LineString(1 1,2 2)'))); +-------------------------------------------------------+ | AsText(Envelope(GeomFromText('LineString(1 1,2 2)'))) | +-------------------------------------------------------+ | POLYGON((1 1,2 1,2 2,1 2,1 1)) | +-------------------------------------------------------+ * `GeometryType(G)' Returns as a binary string the name of the geometry type of which the geometry instance G is a member. The name corresponds to one of the instantiable `Geometry' subclasses. mysql> SELECT GeometryType(GeomFromText('POINT(1 1)')); +------------------------------------------+ | GeometryType(GeomFromText('POINT(1 1)')) | +------------------------------------------+ | POINT | +------------------------------------------+ * `SRID(G)' Returns an integer indicating the Spatial Reference System ID for the geometry value G. In MySQL, the SRID value is just an integer associated with the geometry value. All calculations are done assuming Euclidean (planar) geometry. mysql> SELECT SRID(GeomFromText('LineString(1 1,2 2)',101)); +-----------------------------------------------+ | SRID(GeomFromText('LineString(1 1,2 2)',101)) | +-----------------------------------------------+ | 101 | +-----------------------------------------------+ The OpenGIS specification also defines the following functions, which MySQL does not implement: * `Boundary(G)' Returns a geometry that is the closure of the combinatorial boundary of the geometry value G. * `IsEmpty(G)' This function is a placeholder that returns 0 for any valid geometry value, 1 for any invalid geometry value or `NULL'. MySQL does not support GIS `EMPTY' values such as `POINT EMPTY'. * `IsSimple(G)' In MySQL 5.1, this function is a placeholder that always returns 0. The description of each instantiable geometric class given earlier in the chapter includes the specific conditions that cause an instance of that class to be classified as not simple. (See *Note gis-geometry-class-hierarchy::.)  File: manual.info, Node: point-property-functions, Next: linestring-property-functions, Prev: general-geometry-property-functions, Up: geometry-property-functions 12.17.5.4 `Point' Functions ........................... A `Point' consists of X and Y coordinates, which may be obtained using the following functions: * `X(P)' Returns the X-coordinate value for the `Point' object P as a double-precision number. mysql> SELECT X(POINT(56.7, 53.34)); +-----------------------+ | X(POINT(56.7, 53.34)) | +-----------------------+ | 56.7 | +-----------------------+ * `Y(P)' Returns the Y-coordinate value for the `Point' object P as a double-precision number. mysql> SELECT Y(POINT(56.7, 53.34)); +-----------------------+ | Y(POINT(56.7, 53.34)) | +-----------------------+ | 53.34 | +-----------------------+  File: manual.info, Node: linestring-property-functions, Next: multilinestring-property-functions, Prev: point-property-functions, Up: geometry-property-functions 12.17.5.5 `LineString' 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. * `EndPoint(LS)' Returns the `Point' that is the endpoint of the `LineString' value LS. mysql> SET @ls = 'LineString(1 1,2 2,3 3)'; mysql> SELECT AsText(EndPoint(GeomFromText(@ls))); +-------------------------------------+ | AsText(EndPoint(GeomFromText(@ls))) | +-------------------------------------+ | POINT(3 3) | +-------------------------------------+ * `GLength(LS)' Returns as a double-precision number the length of the `LineString' value LS in its associated spatial reference. mysql> SET @ls = 'LineString(1 1,2 2,3 3)'; mysql> SELECT GLength(GeomFromText(@ls)); +----------------------------+ | GLength(GeomFromText(@ls)) | +----------------------------+ | 2.8284271247462 | +----------------------------+ `GLength()' is a nonstandard name. It corresponds to the OpenGIS `Length()' function. * `IsClosed(LS)' Returns 1 if the `LineString' value LS is closed (that is, its `StartPoint()' and `EndPoint()' values are the same) and is simple (does not pass through the same point more than once). Returns 0 if LS is not closed, and -1 if it is `NULL'. mysql> SET @ls1 = '`LineString'(1 1,2 2,3 3,2 2)'; Query OK, 0 rows affected (0.00 sec) mysql> SET @ls2 = 'LineString(1 1,2 2,3 3,1 1)'; Query OK, 0 rows affected (0.00 sec) mysql> SELECT IsClosed(`GeomFromText'(@ls1)); +------------------------------+ | IsClosed(GeomFromText(@ls1)) | +------------------------------+ | 0 | +------------------------------+ 1 row in set (0.00 sec) mysql> SELECT IsClosed(GeomFromText(@ls2)); +------------------------------+ | IsClosed(GeomFromText(@ls2)) | +------------------------------+ | 1 | +------------------------------+ 1 row in set (0.00 sec) * `NumPoints(LS)' Returns the number of `Point' objects in the `LineString' value LS. mysql> SET @ls = 'LineString(1 1,2 2,3 3)'; mysql> SELECT NumPoints(GeomFromText(@ls)); +------------------------------+ | NumPoints(GeomFromText(@ls)) | +------------------------------+ | 3 | +------------------------------+ * `PointN(LS,N)' Returns the N-th `Point' in the `Linestring' value LS. Points are numbered beginning with 1. mysql> SET @ls = 'LineString(1 1,2 2,3 3)'; mysql> SELECT AsText(PointN(GeomFromText(@ls),2)); +-------------------------------------+ | AsText(PointN(GeomFromText(@ls),2)) | +-------------------------------------+ | POINT(2 2) | +-------------------------------------+ * `StartPoint(LS)' Returns the `Point' that is the start point of the `LineString' value LS. mysql> SET @ls = 'LineString(1 1,2 2,3 3)'; mysql> SELECT AsText(StartPoint(GeomFromText(@ls))); +---------------------------------------+ | AsText(StartPoint(GeomFromText(@ls))) | +---------------------------------------+ | POINT(1 1) | +---------------------------------------+  File: manual.info, Node: multilinestring-property-functions, Next: polygon-property-functions, Prev: linestring-property-functions, Up: geometry-property-functions 12.17.5.6 `MultiLineString' Functions ..................................... These functions return properties of `MultiLineString' values. * `GLength(MLS)' Returns as a double-precision number the length of the `MultiLineString' value MLS. The length of MLS is equal to the sum of the lengths of its elements. mysql> SET @mls = 'MultiLineString((1 1,2 2,3 3),(4 4,5 5))'; mysql> SELECT GLength(GeomFromText(@mls)); +-----------------------------+ | GLength(GeomFromText(@mls)) | +-----------------------------+ | 4.2426406871193 | +-----------------------------+ `GLength()' is a nonstandard name. It corresponds to the OpenGIS `Length()' function. * `IsClosed(MLS)' Returns 1 if the `MultiLineString' value MLS is closed (that is, the `StartPoint()' and `EndPoint()' values are the same for each `LineString' in MLS). Returns 0 if MLS is not closed, and -1 if it is `NULL'. mysql> SET @mls = 'MultiLineString((1 1,2 2,3 3),(4 4,5 5))'; mysql> SELECT IsClosed(GeomFromText(@mls)); +------------------------------+ | IsClosed(GeomFromText(@mls)) | +------------------------------+ | 0 | +------------------------------+  File: manual.info, Node: polygon-property-functions, Next: multipolygon-property-functions, Prev: multilinestring-property-functions, Up: geometry-property-functions 12.17.5.7 `Polygon' Functions ............................. These functions return properties of `Polygon' values. * `Area(POLY)' Returns as a double-precision number the area of the `Polygon' value POLY, as measured in its spatial reference system. mysql> SET @poly = 'Polygon((0 0,0 3,3 0,0 0),(1 1,1 2,2 1,1 1))'; mysql> SELECT Area(GeomFromText(@poly)); +---------------------------+ | Area(GeomFromText(@poly)) | +---------------------------+ | 4 | +---------------------------+ * `ExteriorRing(POLY)' Returns the exterior ring of the `Polygon' value POLY as a `LineString'. 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 AsText(ExteriorRing(GeomFromText(@poly))); +-------------------------------------------+ | AsText(ExteriorRing(GeomFromText(@poly))) | +-------------------------------------------+ | LINESTRING(0 0,0 3,3 3,3 0,0 0) | +-------------------------------------------+ * `InteriorRingN(POLY,N)' Returns the N-th interior ring for the `Polygon' value POLY as a `LineString'. Rings are numbered beginning with 1. 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 AsText(InteriorRingN(GeomFromText(@poly),1)); +----------------------------------------------+ | AsText(InteriorRingN(GeomFromText(@poly),1)) | +----------------------------------------------+ | LINESTRING(1 1,1 2,2 2,2 1,1 1) | +----------------------------------------------+ * `NumInteriorRings(POLY)' Returns the number of interior rings in the `Polygon' value POLY. 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 NumInteriorRings(GeomFromText(@poly)); +---------------------------------------+ | NumInteriorRings(GeomFromText(@poly)) | +---------------------------------------+ | 1 | +---------------------------------------+  File: manual.info, Node: multipolygon-property-functions, Next: geometrycollection-property-functions, Prev: polygon-property-functions, Up: geometry-property-functions 12.17.5.8 `MultiPolygon' Functions .................................. These functions return properties of `MultiPolygon' values. * `Area(MPOLY)' Returns as a double-precision number the area of the `MultiPolygon' value MPOLY, as measured in its spatial reference system. 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 Area(GeomFromText(@mpoly)); +----------------------------+ | Area(GeomFromText(@mpoly)) | +----------------------------+ | 8 | +----------------------------+ * `Centroid(MPOLY)' Returns the mathematical centroid for the `MultiPolygon' value MPOLY as a `Point'. The result is not guaranteed to be on the `MultiPolygon'. mysql> SET @poly = -> GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0),(5 5,7 5,7 7,5 7,5 5))'); mysql> SELECT GeometryType(@poly),AsText(Centroid(@poly)); +---------------------+--------------------------------------------+ | GeometryType(@poly) | AsText(Centroid(@poly)) | +---------------------+--------------------------------------------+ | POLYGON | POINT(4.958333333333333 4.958333333333333) | +---------------------+--------------------------------------------+ The OpenGIS specification also defines the following function, which MySQL does not implement: * `PointOnSurface(MPOLY)' Returns a `Point' value that is guaranteed to be on the `MultiPolygon' value MPOLY.  File: manual.info, Node: geometrycollection-property-functions, Prev: multipolygon-property-functions, Up: geometry-property-functions 12.17.5.9 `GeometryCollection' Functions ........................................ These functions return properties of `GeometryCollection' values. * `GeometryN(GC,N)' Returns the N-th geometry in the `GeometryCollection' value GC. Geometries are numbered beginning with 1. mysql> SET @gc = 'GeometryCollection(Point(1 1),LineString(2 2, 3 3))'; mysql> SELECT AsText(GeometryN(GeomFromText(@gc),1)); +----------------------------------------+ | AsText(GeometryN(GeomFromText(@gc),1)) | +----------------------------------------+ | POINT(1 1) | +----------------------------------------+ * `NumGeometries(GC)' Returns the number of geometries in the `GeometryCollection' value GC. mysql> SET @gc = 'GeometryCollection(Point(1 1),LineString(2 2, 3 3))'; mysql> SELECT NumGeometries(GeomFromText(@gc)); +----------------------------------+ | NumGeometries(GeomFromText(@gc)) | +----------------------------------+ | 2 | +----------------------------------+  File: manual.info, Node: functions-that-create-new-geometries-from-existing-ones, Next: functions-for-testing-spatial-relations-between-geometric-objects, Prev: geometry-property-functions, Up: spatial-analysis-functions 12.17.5.10 Functions That Create New Geometries from Existing Ones .................................................................. * Menu: * functions-that-produce-new-geometries:: Geometry Functions That Produce New Geometries * spatial-operators:: Spatial Operators The following sections describe functions that take geometry values as arguments and return new geometry values.  File: manual.info, Node: functions-that-produce-new-geometries, Next: spatial-operators, Prev: functions-that-create-new-geometries-from-existing-ones, Up: functions-that-create-new-geometries-from-existing-ones 12.17.5.11 Geometry Functions That Produce New Geometries ......................................................... *Note geometry-property-functions::, discusses several functions that construct new geometries from existing ones. See that section for descriptions of these functions: * `Envelope(G)' * `StartPoint(LS)' * `EndPoint(LS)' * `PointN(LS,N)' * `ExteriorRing(POLY)' * `InteriorRingN(POLY,N)' * `GeometryN(GC,N)'  File: manual.info, Node: spatial-operators, Prev: functions-that-produce-new-geometries, Up: functions-that-create-new-geometries-from-existing-ones 12.17.5.12 Spatial Operators ............................ OpenGIS proposes a number of other functions that can produce geometries. They are designed to implement spatial operators. These functions are not implemented in MySQL. * `Buffer(G,D)' Returns a geometry that represents all points whose distance from the geometry value G is less than or equal to a distance of D. * `ConvexHull(G)' Returns a geometry that represents the convex hull of the geometry value G. * `Difference(G1,G2)' Returns a geometry that represents the point set difference of the geometry value G1 with G2. * `Intersection(G1,G2)' Returns a geometry that represents the point set intersection of the geometry values G1 with G2. * `SymDifference(G1,G2)' Returns a geometry that represents the point set symmetric difference of the geometry value G1 with G2. * `Union(G1,G2)' Returns a geometry that represents the point set union of the geometry values G1 and G2.  File: manual.info, Node: functions-for-testing-spatial-relations-between-geometric-objects, Prev: functions-that-create-new-geometries-from-existing-ones, Up: spatial-analysis-functions 12.17.5.13 Functions for Testing Spatial Relations Between Geometric Objects ............................................................................ * Menu: * relations-on-geometry-mbr:: Relations on Geometry Minimal Bounding Rectangles (MBRs) * functions-that-test-spatial-relationships-between-geometries:: Functions That Test Spatial Relationships Between Geometries The functions described in these sections take two geometries as input parameters and return a qualitative or quantitative relation between them.  File: manual.info, Node: relations-on-geometry-mbr, Next: functions-that-test-spatial-relationships-between-geometries, Prev: functions-for-testing-spatial-relations-between-geometric-objects, Up: functions-for-testing-spatial-relations-between-geometric-objects 12.17.5.14 Relations on Geometry Minimal Bounding Rectangles (MBRs) ................................................................... MySQL provides several functions that test relations between minimal bounding rectangles of two geometries `g1' and `g2'. The return values 1 and 0 indicate true and false, respectively. * `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 = GeomFromText('Polygon((0 0,0 3,3 3,3 0,0 0))'); mysql> SET @g2 = GeomFromText('Point(1 1)'); mysql> SELECT MBRContains(@g1,@g2), MBRContains(@g2,@g1); ----------------------+----------------------+ | MBRContains(@g1,@g2) | MBRContains(@g2,@g1) | +----------------------+----------------------+ | 1 | 0 | +----------------------+----------------------+ * `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). * `MBREqual(G1,G2)' Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries G1 and G2 are the same. * `MBRIntersects(G1,G2)' Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries G1 and G2 intersect. * `MBROverlaps(G1,G2)' Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries G1 and G2 overlap. The term _spatially overlaps_ is used if two geometries intersect and their intersection results in a geometry of the same dimension but not equal to either of the given geometries. * `MBRTouches(G1,G2)' Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries G1 and G2 touch. Two geometries _spatially touch_ if the interiors of the geometries do not intersect, but the boundary of one of the geometries intersects either the boundary or the interior of the other. * `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 = GeomFromText('Polygon((0 0,0 3,3 3,3 0,0 0))'); mysql> SET @g2 = 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 | +--------------------+--------------------+  File: manual.info, Node: functions-that-test-spatial-relationships-between-geometries, Prev: relations-on-geometry-mbr, Up: functions-for-testing-spatial-relations-between-geometric-objects 12.17.5.15 Functions That Test Spatial Relationships Between Geometries ....................................................................... The OpenGIS specification defines the following functions. They test the relationship between two geometry values `g1' and `g2'. The return values 1 and 0 indicate true and false, respectively. *Note*: Currently, MySQL does not implement these functions according to the specification. Those that are implemented return the same result as the corresponding MBR-based functions. * `Contains(G1,G2)' Returns 1 or 0 to indicate whether G1 completely contains G2. This tests the opposite relationship as `Within()'. * `Crosses(G1,G2)' 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. 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 * `Disjoint(G1,G2)' Returns 1 or 0 to indicate whether G1 is spatially disjoint from (does not intersect) G2. * `Equals(G1,G2)' Returns 1 or 0 to indicate whether G1 is spatially equal to G2. * `Intersects(G1,G2)' Returns 1 or 0 to indicate whether G1 spatially intersects G2. * `Overlaps(G1,G2)' Returns 1 or 0 to indicate whether G1 spatially overlaps G2. The term _spatially overlaps_ is used if two geometries intersect and their intersection results in a geometry of the same dimension but not equal to either of the given geometries. * `Touches(G1,G2)' Returns 1 or 0 to indicate whether G1 spatially touches G2. Two geometries _spatially touch_ if the interiors of the geometries do not intersect, but the boundary of one of the geometries intersects either the boundary or the interior of the other. * `Within(G1,G2)' Returns 1 or 0 to indicate whether G1 is spatially within G2. This tests the opposite relationship as `Contains()'.  File: manual.info, Node: optimizing-spatial-analysis, Next: mysql-gis-conformance-and-compatibility, Prev: spatial-analysis-functions, Up: spatial-extensions 12.17.6 Optimizing Spatial Analysis ----------------------------------- * Menu: * creating-spatial-indexes:: Creating Spatial Indexes * using-a-spatial-index:: Using a Spatial Index For *Note `MyISAM': myisam-storage-engine. tables, Search operations in nonspatial databases can be optimized using `SPATIAL' indexes. This is true for spatial databases as well. With the help of a great variety of multi-dimensional indexing methods that have previously been designed, it is possible to optimize spatial searches. The most typical of these 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 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' supports both `SPATIAL' and non-`SPATIAL' indexes. Other storage engines support non-`SPATIAL' indexes, as described in *Note create-index::.  File: manual.info, Node: creating-spatial-indexes, Next: using-a-spatial-index, Prev: optimizing-spatial-analysis, Up: optimizing-spatial-analysis 12.17.6.1 Creating Spatial Indexes .................................. For *Note `MyISAM': myisam-storage-engine. tables, MySQL can create spatial indexes using syntax similar to that for creating regular indexes, but extended with the `SPATIAL' keyword. Currently, columns in spatial indexes must be declared `NOT NULL'. The following examples demonstrate how to create spatial indexes: * With *Note `CREATE TABLE': create-table.: CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g)) ENGINE=MyISAM; * With *Note `ALTER TABLE': alter-table.: ALTER TABLE geom ADD SPATIAL INDEX(g); * With *Note `CREATE INDEX': create-index.: CREATE SPATIAL INDEX sp_index ON geom (g); For `MyISAM' tables, `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 will be useful for exact-value lookups, but not for range scans. For more information on indexing spatial columns, see *Note create-index::. To drop spatial indexes, use *Note `ALTER TABLE': alter-table. or *Note `DROP INDEX': drop-index.: * With *Note `ALTER TABLE': alter-table.: ALTER TABLE geom DROP INDEX g; * With *Note `DROP INDEX': drop-index.: DROP INDEX sp_index 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  File: manual.info, Node: using-a-spatial-index, Prev: creating-spatial-indexes, Up: optimizing-spatial-analysis 12.17.6.2 Using a Spatial Index ............................... 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,AsText(g) FROM geom WHERE -> MBRContains(GeomFromText(@poly),g); +-----+---------------------------------------------------------------+ | fid | 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 *Note `EXPLAIN': 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,AsText(g) FROM geom WHERE -> MBRContains(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,AsText(g) FROM g IGNORE INDEX (g) WHERE -> MBRContains(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 *Note `SELECT': 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,AsText(g) FROM geom IGNORE INDEX (g) WHERE -> MBRContains(GeomFromText(@poly),g); +-----+---------------------------------------------------------------+ | fid | 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)  File: manual.info, Node: mysql-gis-conformance-and-compatibility, Prev: optimizing-spatial-analysis, Up: spatial-extensions 12.17.7 MySQL Conformance and Compatibility ------------------------------------------- MySQL does not yet 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' currently should be called in MySQL as `GLength()' 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. We need either to solve this somehow, or decide on another function name.  File: manual.info, Node: precision-math, Prev: spatial-extensions, Up: functions 12.18 Precision Math ==================== * Menu: * precision-math-numbers:: Types of Numeric Values * precision-math-decimal-changes:: `DECIMAL' Data Type Changes * precision-math-expressions:: Expression Handling * precision-math-rounding:: Rounding Behavior * precision-math-examples:: Precision Math Examples MySQL 5.1 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 5.1 handles numeric operations precisely. For information about controlling the SQL mode, see *Note server-sql-mode::.  File: manual.info, Node: precision-math-numbers, Next: precision-math-decimal-changes, Prev: precision-math, Up: precision-math 12.18.1 Types of Numeric Values ------------------------------- The scope of precision math for exact-value operations includes the exact-value data types (*Note `DECIMAL': fixed-point-types. and integer 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 *Note `DECIMAL': fixed-point-types. data type is a fixed-point type and calculations are exact. In MySQL, the *Note `DECIMAL': fixed-point-types. type has several synonyms: *Note `NUMERIC': fixed-point-types, *Note `DEC': fixed-point-types, *Note `FIXED': fixed-point-types. The integer types also are exact-value types. The *Note `FLOAT': floating-point-types. and *Note `DOUBLE': floating-point-types. data types are floating-point types and calculations are approximate. In MySQL, types that are synonymous with *Note `FLOAT': floating-point-types. or *Note `DOUBLE': floating-point-types. are *Note `DOUBLE PRECISION': floating-point-types. and *Note `REAL': floating-point-types.  File: manual.info, Node: precision-math-decimal-changes, Next: precision-math-expressions, Prev: precision-math-numbers, Up: precision-math 12.18.2 `DECIMAL' Data Type Changes ----------------------------------- This section discusses the characteristics of the *Note `DECIMAL': fixed-point-types. data type (and its synonyms) in MySQL 5.1, with particular regard to the following topics: * Maximum number of digits * Storage format * Storage requirements * The nonstandard MySQL extension to the upper range of *Note `DECIMAL': fixed-point-types. columns Possible incompatibilities with applications that are written for older versions of MySQL (prior to 5.0.3) are noted throughout this section. The declaration syntax for a *Note `DECIMAL': fixed-point-types. column is `DECIMAL(M,D)'. The ranges of values for the arguments in MySQL 5.1 are as follows: * M is the maximum number of digits (the precision). It has a range of 1 to 65. (Older versions of MySQL permitted a range of 1 to 254.) * 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 *Note `DECIMAL': fixed-point-types. 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. (In older versions of MySQL, decimal values could have up to 254 digits. However, calculations were done using floating-point and thus were approximate, not exact.) Values for *Note `DECIMAL': fixed-point-types. columns in MySQL 5.1 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. This table lists the number of bytes required for remaining/leftover digits. 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. Unlike some older versions of MySQL, *Note `DECIMAL': fixed-point-types. columns in MySQL 5.1 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. Applications that rely on the older behavior must be modified to account for this change. *Note `DECIMAL': fixed-point-types. columns in MySQL 5.1 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 at most M - D digits to the left of the decimal point. This is not compatible with applications relying on older versions of MySQL that permitted storing an extra digit in lieu of a `+' sign. 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 more detailed information about porting applications that rely on the old treatment of the *Note `DECIMAL': fixed-point-types. data type, see the `MySQL 5.0 Reference Manual'.  File: manual.info, Node: precision-math-expressions, Next: precision-math-rounding, Prev: precision-math-decimal-changes, Up: precision-math 12.18.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 *Note `INSERT': insert. into a column with an exact data type (*Note `DECIMAL': fixed-point-types. 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. (Without strict mode, truncation for *Note `INSERT': 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 *Note `DECIMAL': fixed-point-types. 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 *Note `BIGINT': integer-types. (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 *Note server-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 (*Note `DECIMAL': fixed-point-types. 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 *Note 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. By default, division by zero produces a result of `NULL' and no warning. 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. This table shows 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. 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.  File: manual.info, Node: precision-math-rounding, Next: precision-math-examples, Prev: precision-math-expressions, Up: precision-math 12.18.4 Rounding Behavior ------------------------- This section discusses precision math rounding for the `ROUND()' function and for inserts into columns with exact-value types (*Note `DECIMAL': fixed-point-types. 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 *Note `DECIMAL': fixed-point-types. 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 | +------+  File: manual.info, Node: precision-math-examples, Prev: precision-math-rounding, Up: precision-math 12.18.5 Precision Math Examples ------------------------------- This section provides some examples that show precision math query results in MySQL 5.1. These examples demonstrate the principles described in *Note precision-math-expressions::, and *Note 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 (*Note `DECIMAL': fixed-point-types. 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. Prior to MySQL 5.0.3, exact-value and approximate-value literals both are evaluated as double-precision floating-point values: mysql> SELECT VERSION(); +------------+ | VERSION() | +------------+ | 4.1.18-log | +------------+ 1 row in set (0.01 sec) mysql> CREATE TABLE t SELECT 2.5 AS a, 25E-1 AS b; Query OK, 1 row affected (0.07 sec) Records: 1 Duplicates: 0 Warnings: 0 mysql> DESCRIBE t; +-------+-------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------+-------------+------+-----+---------+-------+ | a | double(3,1) | | | 0.0 | | | b | double | | | 0 | | +-------+-------------+------+-----+---------+-------+ 2 rows in set (0.04 sec) As of MySQL 5.0.3, the approximate-value literal is evaluated using floating point, but the exact-value literal is handled as *Note `DECIMAL': fixed-point-types.: mysql> SELECT VERSION(); +-----------------+ | VERSION() | +-----------------+ | 5.1.6-alpha-log | +-----------------+ 1 row in set (0.11 sec) 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; Before MySQL 5.0.3, the result is a double no matter the argument type: mysql> DESCRIBE y; +--------+--------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +--------+--------------+------+-----+---------+-------+ | AVG(i) | double(17,4) | YES | | NULL | | | AVG(d) | double(17,4) | YES | | NULL | | | AVG(f) | double | YES | | NULL | | +--------+--------------+------+-----+---------+-------+ As of MySQL 5.0.3, 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.  File: manual.info, Node: sql-syntax, Next: storage-engines, Prev: functions, Up: Top 13 SQL Statement Syntax *********************** * Menu: * sql-syntax-data-definition:: Data Definition Statements * sql-syntax-data-manipulation:: Data Manipulation Statements * sql-syntax-transactions:: MySQL Transactional and Locking Statements * sql-syntax-replication:: Replication Statements * sql-syntax-prepared-statements:: SQL Syntax for Prepared Statements * sql-syntax-compound-statements:: MySQL Compound-Statement Syntax * sql-syntax-server-administration:: Database Administration Statements * sql-syntax-utility:: MySQL Utility Statements This chapter describes the syntax for the SQL (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_sql) statements supported by MySQL.  File: manual.info, Node: sql-syntax-data-definition, Next: sql-syntax-data-manipulation, Prev: sql-syntax, Up: sql-syntax 13.1 Data Definition Statements =============================== * Menu: * alter-database:: `ALTER DATABASE' Syntax * alter-event:: `ALTER EVENT' Syntax * alter-logfile-group:: `ALTER LOGFILE GROUP' Syntax * alter-function:: `ALTER FUNCTION' Syntax * alter-procedure:: `ALTER PROCEDURE' Syntax * alter-server:: `ALTER SERVER' Syntax * alter-table:: `ALTER TABLE' Syntax * alter-tablespace:: `ALTER TABLESPACE' Syntax * alter-view:: `ALTER VIEW' Syntax * create-database:: `CREATE DATABASE' Syntax * create-event:: `CREATE EVENT' Syntax * create-function:: `CREATE FUNCTION' Syntax * create-index:: `CREATE INDEX' Syntax * create-logfile-group:: `CREATE LOGFILE GROUP' Syntax * create-procedure:: `CREATE PROCEDURE' and `CREATE FUNCTION' Syntax * create-server:: `CREATE SERVER' Syntax * create-table:: `CREATE TABLE' Syntax * create-tablespace:: `CREATE TABLESPACE' Syntax * create-trigger:: `CREATE TRIGGER' Syntax * create-view:: `CREATE VIEW' Syntax * drop-database:: `DROP DATABASE' Syntax * drop-event:: `DROP EVENT' Syntax * drop-function:: `DROP FUNCTION' Syntax * drop-index:: `DROP INDEX' Syntax * drop-logfile-group:: `DROP LOGFILE GROUP' Syntax * drop-procedure:: `DROP PROCEDURE' and `DROP FUNCTION' Syntax * drop-server:: `DROP SERVER' Syntax * drop-table:: `DROP TABLE' Syntax * drop-tablespace:: `DROP TABLESPACE' Syntax * drop-trigger:: `DROP TRIGGER' Syntax * drop-view:: `DROP VIEW' Syntax * rename-database:: `RENAME DATABASE' Syntax * rename-table:: `RENAME TABLE' Syntax * truncate-table:: `TRUNCATE TABLE' Syntax  File: manual.info, Node: alter-database, Next: alter-event, Prev: sql-syntax-data-definition, Up: sql-syntax-data-definition 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 *Note `ALTER DATABASE': 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 *Note `ALTER DATABASE': alter-database, you need the `ALTER' privilege on the database. *Note `ALTER SCHEMA': alter-database. is a synonym for *Note `ALTER DATABASE': 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. *Note charset::, discusses character set and collation names. You can see what character sets and collations are available using, respectively, the *Note `SHOW CHARACTER SET': show-character-set. and *Note `SHOW COLLATION': show-collation. statements. See *Note show-character-set::, and *Note 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 *Note create-procedure::.) * Upgrading from Versions Older than MySQL 5.1 * The syntax that includes the `UPGRADE DATA DIRECTORY NAME' clause was added in MySQL 5.1.23. It 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 *Note 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 *Note `mysqlcheck': mysqlcheck. (as invoked by *Note `mysql_upgrade': 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.  File: manual.info, Node: alter-event, Next: alter-logfile-group, Prev: alter-database, Up: sql-syntax-data-definition 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 'COMMENT'] [DO EVENT_BODY] The *Note `ALTER EVENT': 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 *Note `DO': do. clauses is exactly the same as when used with *Note `CREATE EVENT': create-event. (See *Note create-event::.) Support for the `DEFINER' clause was added in MySQL 5.1.17. Beginning with MySQL 5.1.12, this statement requires the `EVENT' privilege. When a user executes a successful *Note `ALTER EVENT': alter-event. statement, that user becomes the definer for the affected event. (In MySQL 5.1.11 and earlier, an event could be altered only by its definer, or by a user having the `SUPER' privilege.) *Note `ALTER 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 *Note `ALTER EVENT': 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 *Note `ALTER EVENT': alter-event. statement only for those characteristics that you want to change; omitted options keep their existing values. This includes any default values for *Note `CREATE EVENT': create-event. such as `ENABLE'. To disable `myevent', use this *Note `ALTER EVENT': 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 *Note `ALTER EVENT': alter-event. and *Note `CREATE EVENT': create-event. statements. Beginning with MySQL 5.1.13, 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 *Note `ALTER EVENT': alter-event. statement that contains another *Note `ALTER EVENT': alter-event. statement in its *Note `DO': 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 *Note `ALTER EVENT': 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. Beginning with MySQL 5.1.18, a third value may also appear in place of `ENABLED' or `DISABLED'; `DISABLE ON SLAVE' is used on a replication slave to indicate an event which was created on the master and replicated to the slave, but which 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 *Note replication-features-invoked::, for more information.  File: manual.info, Node: alter-logfile-group, Next: alter-function, Prev: alter-event, Up: sql-syntax-data-definition 13.1.3 `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 *Note `ALTER LOGFILE GROUP': alter-logfile-group. statement has one and only one `ADD UNDOFILE' clause. No `DROP UNDOFILE' clause is currently supported. *Note*: All MySQL 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. Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, path and file names for undo log files could not be longer than 128 characters. (Bug #31769) The optional `INITIAL_SIZE' parameter sets the `UNDO' file's initial size in bytes; if not specified, the initial size default to `128M' (128 megabytes). 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' (for megabytes) or `G' (for gigabytes). On 32-bit systems, the maximum supported value for `INITIAL_SIZE' is `4G'. (Bug #29186) Beginning with MySQL Cluster NDB 6.2.18, 6.3.24, and 7.0.4, the minimum permitted value for `INITIAL_SIZE' is `1M'. (Bug #29574) *Note*: `WAIT' is parsed but otherwise ignored. This keyword has no effect in MySQL 5.1, MySQL Cluster NDB 6.x, or MySQL Cluster NDB 7.x, 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. In MySQL 5.1, MySQL Cluster NDB 6.x, and MySQL Cluster NDB 7.x, the only accepted values for ENGINE_NAME are `*Note `NDBCLUSTER': mysql-cluster.' and `*Note `NDB': mysql-cluster.'. The two values are equivalent. Here is an example, which assumes that the log file group `lg_3' has already been created using *Note `CREATE LOGFILE GROUP': create-logfile-group. (see *Note create-logfile-group::): ALTER LOGFILE GROUP lg_3 ADD UNDOFILE 'undo_10.dat' INITIAL_SIZE=32M ENGINE=NDBCLUSTER; When *Note `ALTER LOGFILE GROUP': alter-logfile-group. is used with `ENGINE = NDBCLUSTER' (alternatively, `ENGINE = NDB'), an `UNDO' log file is created on each MySQL Cluster data node. You can verify that the `UNDO' files were created and obtain information about them by querying the *Note `INFORMATION_SCHEMA.FILES': files-table. 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 *Note 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. *Note `ALTER LOGFILE GROUP': alter-logfile-group. was added in MySQL 5.1.6. It is useful only with Disk Data storage for MySQL Cluster. For more information, see *Note mysql-cluster-disk-data::.  File: manual.info, Node: alter-function, Next: alter-procedure, Prev: alter-logfile-group, Up: sql-syntax-data-definition 13.1.4 `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 *Note `ALTER FUNCTION': 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 *Note `DROP FUNCTION': drop-function. and *Note `CREATE FUNCTION': 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 *Note `ALTER FUNCTION': alter-function. statement might also require the `SUPER' privilege, as described in *Note stored-programs-logging::.  File: manual.info, Node: alter-procedure, Next: alter-server, Prev: alter-function, Up: sql-syntax-data-definition 13.1.5 `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 *Note `ALTER PROCEDURE': 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 *Note `DROP PROCEDURE': drop-procedure. and *Note `CREATE PROCEDURE': 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 *Note stored-routines-privileges::.  File: manual.info, Node: alter-server, Next: alter-table, Prev: alter-procedure, Up: sql-syntax-data-definition 13.1.6 `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 *Note `CREATE SERVER': 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' does not cause an automatic commit. In MySQL 5.1, `ALTER SERVER' is written to the binary log only when using row-based logging. It is not logged when `binlog_format' is equal to `STATEMENT' or `MIXED'. `ALTER SERVER' was added in MySQL 5.1.15.  File: manual.info, Node: alter-table, Next: alter-tablespace, Prev: alter-server, Up: sql-syntax-data-definition 13.1.7 `ALTER TABLE' Syntax --------------------------- * Menu: * alter-table-partition-operations:: `ALTER TABLE' Partition Operations * alter-table-online-operations:: `ALTER TABLE' Online Operations in MySQL Cluster * alter-table-examples:: `ALTER TABLE' Examples ALTER [ONLINE | OFFLINE] [IGNORE] 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 | ALTER [COLUMN] COL_NAME {SET DEFAULT LITERAL | DROP DEFAULT} | CHANGE [COLUMN] OLD_COL_NAME NEW_COL_NAME COLUMN_DEFINITION [FIRST|AFTER COL_NAME] | MODIFY [COLUMN] COL_NAME COLUMN_DEFINITION [FIRST | AFTER COL_NAME] | DROP [COLUMN] COL_NAME | DROP PRIMARY KEY | DROP {INDEX|KEY} INDEX_NAME | DROP FOREIGN KEY FK_SYMBOL | DISABLE KEYS | ENABLE KEYS | RENAME [TO|AS] NEW_TBL_NAME | ORDER BY COL_NAME [, COL_NAME] ... | CONVERT TO CHARACTER SET CHARSET_NAME [COLLATE COLLATION_NAME] | [DEFAULT] CHARACTER SET [=] CHARSET_NAME [COLLATE [=] COLLATION_NAME] | DISCARD TABLESPACE | IMPORT TABLESPACE | ADD PARTITION (PARTITION_DEFINITION) | DROP PARTITION PARTITION_NAMES | COALESCE PARTITION NUMBER | REORGANIZE PARTITION [PARTITION_NAMES INTO (PARTITION_DEFINITIONS)] | 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} | PARTITION BY PARTITIONING_EXPRESSION | REMOVE 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 TABLE_OPTIONS: TABLE_OPTION [[,] TABLE_OPTION] ... (see *Note `CREATE TABLE': create-table. options) PARTITION_OPTIONS: (see *Note `CREATE TABLE': create-table. options) *Note `ALTER TABLE': 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. A number of partitioning-related extensions to *Note `ALTER TABLE': alter-table. were added in MySQL 5.1.5. These can be used with partitioned tables for repartitioning, for adding, dropping, merging, and splitting partitions, and for performing partitioning maintenance. It is possible for an *Note `ALTER TABLE': 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 *Note alter-table-partition-operations::. Following the table name, specify the alterations to be made. If none are given, *Note `ALTER TABLE': alter-table. does nothing. The syntax for many of the permissible alterations is similar to clauses of the *Note `CREATE TABLE': create-table. statement. See *Note create-table::, for more information. Some operations may result in warnings if attempted on a table for which the storage engine does not support the operation. These warnings can be displayed with *Note `SHOW WARNINGS': show-warnings. See *Note show-warnings::. For information on troubleshooting *Note `ALTER TABLE': alter-table, see *Note alter-table-problems::. * Storage, Performance, and Concurrency Considerations * In most cases, *Note `ALTER TABLE': alter-table. makes 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 *Note `ALTER TABLE': alter-table. is executing, the original table is readable by other sessions. Updates and writes to the table that begin after the *Note `ALTER TABLE': 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 table is created in the database directory of the new table. This can differ from the database directory of the original table for *Note `ALTER TABLE': alter-table. operations that rename the table to a different database. 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 some operations, an in-place *Note `ALTER TABLE': alter-table. is possible that does not require a temporary table: * For `ALTER TABLE TBL_NAME RENAME TO NEW_TBL_NAME' without any other options, MySQL simply renames any files that correspond to the table TBL_NAME without making a copy. (You can also use the *Note `RENAME TABLE': rename-table. statement to rename tables. See *Note rename-table::.) Any 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 can be made immediately by altering the table's `.frm' file and not touching table contents. The following changes are fast alterations that can be made this way: * Renaming a column, except for the *Note `InnoDB': innodb-storage-engine. storage engine. * Changing the default value of a column (except for *Note `NDB': mysql-cluster. tables; see Limitations of *Note `NDBCLUSTER': mysql-cluster. online operations). * Changing the definition of an *Note `ENUM': enum. or *Note `SET': 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 *Note `SET': set. column that has 8 members changes the required storage per value from 1 byte to 2 bytes; this will require a table copy. Adding members in the middle of the list causes renumbering of existing members, which requires a table copy. * `ALTER TABLE' with `ADD PARTITION', `DROP PARTITION', `COALESCE PARTITION', `REBUILD PARTITION', or `REORGANIZE PARTITION' does not create any temporary tables (except when used with *Note `NDB': mysql-cluster. 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. * Renaming an index, except for *Note `InnoDB': innodb-storage-engine. * Adding or dropping an index, for *Note `InnoDB': innodb-storage-engine. (if `InnoDB Plugin' is used) and *Note `NDB': mysql-cluster. You can force an `ALTER TABLE' operation that would otherwise not require a table copy to use the temporary table method (as supported in MySQL 5.0) by setting the `old_alter_table' system variable to `ON'. For *Note `NDBCLUSTER': mysql-cluster. tables, operations that add and drop indexes on variable-width columns occur online, without any table copying and without blocking concurrent DML actions for most of their duration. See *Note alter-table-online-operations::. * Usage Notes * * To use *Note `ALTER TABLE': 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. * `IGNORE' is a MySQL extension to standard SQL. It controls how *Note `ALTER TABLE': alter-table. works if there are duplicates on unique keys in the new table or if warnings occur when strict mode is enabled. If `IGNORE' is not specified, the copy is aborted and rolled back if duplicate-key errors occur. If `IGNORE' is specified, only the first row is used of rows with duplicates on a unique key. The other conflicting rows are deleted. Incorrect values are truncated to the closest matching acceptable value. * Pending *Note `INSERT DELAYED': insert-delayed. statements are lost if a table is write locked and *Note `ALTER TABLE': alter-table. is used to modify the table structure. * TABLE_OPTION signifies a table option of the kind that can be used in the *Note `CREATE TABLE': create-table. statement, such as `ENGINE', `AUTO_INCREMENT', `AVG_ROW_LENGTH', or `MAX_ROWS'. For a list of all table options and descriptions of each, see *Note create-table::. However, *Note `ALTER TABLE': alter-table. ignores the `DATA DIRECTORY' and `INDEX DIRECTORY' table options. For example, to convert a table to be an `InnoDB' table, use this statement: ALTER TABLE t1 ENGINE = InnoDB; See *Note converting-tables-to-innodb:: for considerations when switching tables to the `InnoDB' storage engine. When you specify an `ENGINE' clause, *Note `ALTER TABLE': alter-table. rebuilds the table. This is true even if the table already has the specified storage engine. The outcome of attempting to change a table's storage engine is affected by whether the desired storage engine is available and the setting of the `NO_ENGINE_SUBSTITUTION' SQL mode, as described in *Note server-sql-mode::. As of MySQL 5.1.11, to prevent inadvertent loss of data, *Note `ALTER TABLE': alter-table. cannot be used to change the storage engine of a table to `MERGE' or `BLACKHOLE'. To change the value of the `AUTO_INCREMENT' counter to be used for new rows, do this: ALTER TABLE t2 AUTO_INCREMENT = VALUE; You cannot reset the counter to a value less than or equal to any that have already been used. For `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 plus one. For `InnoDB', _if the value is less than the current maximum value in the column, no error occurs and the current sequence value is not changed._ * You can issue multiple `ADD', `ALTER', `DROP', and `CHANGE' clauses in a single *Note `ALTER TABLE': alter-table. statement, separated by commas. This is a MySQL extension to standard SQL, which permits only one of each clause per *Note `ALTER TABLE': alter-table. statement. For example, to drop multiple columns in a single statement, do this: ALTER TABLE t2 DROP COLUMN c, DROP COLUMN d; * `CHANGE COL_NAME', `DROP COL_NAME', and `DROP INDEX' are MySQL extensions to standard SQL. * The word `COLUMN' is optional and can be omitted. * COLUMN_DEFINITION clauses use the same syntax for `ADD' and `CHANGE' as for *Note `CREATE TABLE': create-table. See *Note create-table::. * You can rename a column using a `CHANGE OLD_COL_NAME NEW_COL_NAME COLUMN_DEFINITION' clause. To do so, specify the old and new column names and the definition that the column currently has. For example, to rename an *Note `INTEGER': integer-types. column from `a' to `b', you can do this: ALTER TABLE t1 CHANGE a b INTEGER; To change a column's type but not the name, `CHANGE' syntax still requires an old and new column name, even if they are the same. For example: ALTER TABLE t1 CHANGE b b BIGINT NOT NULL; You can also use `MODIFY' to change a column's type without renaming it: ALTER TABLE t1 MODIFY b BIGINT NOT NULL; `MODIFY' is an extension to *Note `ALTER TABLE': alter-table. for Oracle compatibility. When you use `CHANGE' or `MODIFY', COLUMN_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: ALTER TABLE t1 MODIFY col1 BIGINT; The resulting column will be defined as `BIGINT', but will not include the attributes `UNSIGNED DEFAULT 1 COMMENT 'my column''. To retain them, the statement should be: ALTER TABLE t1 MODIFY col1 BIGINT UNSIGNED DEFAULT 1 COMMENT 'my column'; * When you change a data type 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 *Note `ALTER TABLE': alter-table. (see *Note server-sql-mode::). * 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. You can also use `FIRST' and `AFTER' in `CHANGE' or `MODIFY' operations to reorder columns within a table. * `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 *Note data-type-defaults::. * *Note `DROP INDEX': drop-index. removes an index. This is a MySQL extension to standard SQL. See *Note drop-index::. If you are unsure of the index name, use `SHOW INDEX FROM TBL_NAME'. * 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. 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. * If a table contains only one column, the column cannot be dropped. If what you intend is to remove the table, use *Note `DROP TABLE': drop-table. instead. * `DROP PRIMARY KEY' drops the primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 Using Primary Keys (http://dev.mysql.com/doc/refman/5.5/en/optimizing-primary-keys.html). 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. * 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 *Note create-index::. Before MySQL 5.1.10, `USING' can be given only before the index column list. As of 5.1.10, 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. `USING' is one such option. For details about permissible INDEX_OPTION values, see *Note create-index::. * After an *Note `ALTER TABLE': alter-table. statement, it may be necessary to run *Note `ANALYZE TABLE': analyze-table. to update index cardinality information. See *Note show-index::. * `ORDER BY' enables you to create the new table with the rows in a specific order. Note that the table does not remain in this order after inserts and deletes. This option is useful primarily when you know that you are mostly to 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. `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 that contain a user-defined clustered index (`PRIMARY KEY' or `NOT NULL UNIQUE' index). `InnoDB' always orders table rows according to such an index if one is present. *Note*: When used on a partitioned table, `ALTER TABLE ... ORDER BY' orders rows within each partition only. * If you use *Note `ALTER TABLE': alter-table. on a `MyISAM' table, all nonunique indexes are created in a separate batch (as for *Note `REPAIR TABLE': repair-table.). This should make *Note `ALTER TABLE': alter-table. much faster when you have many indexes. This feature can be activated explicitly for a `MyISAM' table. `ALTER TABLE ... DISABLE KEYS' tells MySQL to stop updating nonunique indexes. `ALTER TABLE ... ENABLE KEYS' then should be used to re-create missing indexes. MySQL 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 *Note `SELECT': select. and *Note `EXPLAIN': explain. that otherwise would use them. `ENABLE KEYS' and `DISABLE KEYS' were not supported for partitioned tables prior to MySQL 5.1.11. * If *Note `ALTER TABLE': alter-table. for an `InnoDB' table results in changes to column values (for example, because a column is truncated), `InnoDB''s `FOREIGN KEY' constraint checks do not notice possible violations caused by changing the values. * The `FOREIGN KEY' and `REFERENCES' clauses are supported by the `InnoDB' storage engine, which implements `ADD [CONSTRAINT [SYMBOL]] FOREIGN KEY [INDEX_NAME] (...) REFERENCES ... (...)'. See *Note 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 *Note 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 *Note differences-from-ansi::. For *Note `ALTER TABLE': alter-table, unlike *Note `CREATE TABLE': 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*: The inline `REFERENCES' specifications where the references are defined as part of the column specification are silently ignored by `InnoDB'. InnoDB only accepts `REFERENCES' clauses defined as part of a separate `FOREIGN KEY' specification. *Note*: Partitioned `InnoDB' tables do not support foreign keys. See *Note partitioning-limitations-storage-engines::, for more information. * `InnoDB' supports the use of *Note `ALTER TABLE': alter-table. to drop foreign keys: ALTER TABLE TBL_NAME DROP FOREIGN KEY FK_SYMBOL; For more information, see *Note innodb-foreign-key-constraints::. * You cannot add a foreign key and drop a foreign key in separate clauses of a single *Note `ALTER TABLE': alter-table. statement. You must use separate statements. * For an `InnoDB' table that is created with its own tablespace in an `.ibd' file, that file can be discarded and imported. To discard the `.ibd' file, use this statement: ALTER TABLE TBL_NAME DISCARD TABLESPACE; This deletes the current `.ibd' file, so be sure that you have a backup first. Attempting to access the table while the tablespace file is discarded results in an error. To import the backup `.ibd' file back into the table, copy it into the database directory, and then issue this statement: ALTER TABLE TBL_NAME IMPORT TABLESPACE; The tablespace file must have been created on the server into which it is imported later. *Note*: The *Note `ALTER TABLE ... IMPORT TABLESPACE': alter-table. feature does not enforce foreign key constraints on imported data. See *Note innodb-multiple-tablespaces::. * To change the table default character set and all character columns (*Note `CHAR': char, *Note `VARCHAR': char, *Note `TEXT': blob.) to a new character set, use a statement like this: ALTER TABLE TBL_NAME CONVERT TO CHARACTER SET CHARSET_NAME; For a column that has a data type of *Note `VARCHAR': char. or one of the *Note `TEXT': blob. types, `CONVERT TO CHARACTER SET' will change 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 *Note `TEXT': blob. 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' *Note `TEXT': blob. 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 will not fit in a *Note `TEXT': blob. column's length bytes, so MySQL will convert the data type to *Note `MEDIUMTEXT': blob, which is the smallest string type for which the length bytes can record a value of 196,605. Similarly, a *Note `VARCHAR': char. column might be converted to *Note `MEDIUMTEXT': blob. 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 *Note `CHAR': char, *Note `VARCHAR': char, and *Note `TEXT': blob. columns are converted to their corresponding binary string types (*Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, *Note `BLOB': blob.). This means that the columns no longer will have a character set and a subsequent `CONVERT TO' operation will not apply to them. If CHARSET_NAME is `DEFAULT', the database character set is used. *Warning*: The `CONVERT TO' operation converts column values between the 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 *Note `BLOB': 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'). With the *Note `mysql_info()': mysql-info. C API function, you can find out how many rows were copied by *Note `ALTER TABLE': alter-table, and (when `IGNORE' is used) how many rows were deleted due to duplication of unique key values. See *Note mysql-info::.  File: manual.info, Node: alter-table-partition-operations, Next: alter-table-online-operations, Prev: alter-table, Up: alter-table 13.1.7.1 `ALTER TABLE' Partition Operations ........................................... A number of partitioning-related extensions to *Note `ALTER TABLE': alter-table. were added in MySQL 5.1.5. These can be used with partitioned tables for repartitioning, for adding, dropping, merging, and splitting partitions, and for performing partitioning maintenance. It is possible for an *Note `ALTER TABLE': 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. * Simply using a PARTITION_OPTIONS clause with *Note `ALTER TABLE': 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 *Note `CREATE TABLE': create-table. (see *Note create-table::, for more detailed information), 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; 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 *Note 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'. `ALTER TABLE ... PARTITION BY' became available in MySQL 5.1.6. The PARTITION_DEFINITION clause for `ALTER TABLE ADD PARTITION' supports the same options as the clause of the same name for the *Note `CREATE TABLE': create-table. statement. (See *Note 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)); `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 *Note `NDBCLUSTER': mysql-cluster. storage engine. See *Note partitioning-management-range-list::, and *Note mysql-cluster-limitations::. `ADD PARTITION' and `DROP PARTITION' do not currently support `IF [NOT] EXISTS'. Renames of partitioned table are supported. You can rename individual partitions indirectly using `ALTER TABLE ... REORGANIZE PARTITION'; however, this operation makes a copy of the partition's data.. `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' using the following definition: CREATE TABLE t2 ( name VARCHAR (30), started DATE ) PARTITION BY HASH( YEAR(started) ) PARTITIONS 6; You can reduce the number of partitions used by `t2' from 6 to 4 using 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 can be 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. You can 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'. * 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 *Note `NDBCLUSTER': mysql-cluster. tables are automatically partitioned in this way.) This is useful in MySQL Cluster NDB 7.0 and later where, after you have added new MySQL Cluster data nodes online to an existing MySQL Cluster, you wish to redistribute existing MySQL Cluster table data to the new data nodes. In such cases, you should invoke the statement with the `ONLINE' option; in other words, as shown here: ALTER ONLINE TABLE TABLE REORGANIZE PARTITION; You cannot perform other DDL concurrently with online table reorganization--that is, no other DDL statements can be issued while an `ALTER ONLINE TABLE ... REORGANIZE PARTITION' statement is executing. For more information about adding MySQL Cluster data nodes online, see *Note mysql-cluster-online-add-node::. `ALTER ONLINE TABLE ... 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 *Note `CREATE TABLE': create-table. statement to determine the number of partitions required, so no new partitions are created. Beginning with MySQL Cluster NDB 7.0.32 and MySQL Cluster NDB 7.1.21, you can use `ALTER ONLINE TABLE ... MAX_ROWS=ROWS' to increase the maxmimum number of rows for the table; after this, `ALTER ONLINE TABLE ... REORGANIZE PARTITION' can use this new, larger value to increase the number of partitions. The value of ROWS must be greater than the value specified for `MAX_ROWS' in the original `CREATE TABLE' statement for this to work. 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. As of MySQL 5.1.7, the same is true with regard to subpartitions. For more detailed information about and examples of `ALTER TABLE ... REORGANIZE PARTITION' statements, see *Note partitioning-management-range-list::. * Several additional options were introduced in MySQL 5.1.5 for providing partition maintenance and repair functionality analogous to that implemented for nonpartitioned tables by statements such as *Note `CHECK TABLE': check-table. and *Note `REPAIR TABLE': repair-table. (which are also supported for partitioned tables, beginning with MySQL 5.1.27--see note at the end of this item). 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 partitions in the table. For more information and examples, see *Note partitioning-maintenance::. Prior to MySQL 5.1.68, it was not safe to execute multiple concurrent `REBUILD TABLE' operations operations on partitioned tables, whether on the same or different tables. (Bug #14589559, Bug #66645) Some MySQL storage engines, such as *Note `InnoDB': innodb-storage-engine, do not support per-partition optimization. For a partitioned table using such a storage engine, `ALTER TABLE ... OPTIMIZE PARTITION' rebuilds the entire table. This is a known issue. Beginning with MySQL 5.1.68, running this statement on such a table 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 were disabled in MySQL 5.1.24, and re-enabled in MySQL 5.1.27. (Bug #20129) They are not supported for tables which are not partitioned; beginning with MySQL 5.1.31, they are not permitted for such tables. Beginning with MySQL 5.1.27, you can use the statements *Note `ANALYZE TABLE': analyze-table, *Note `CHECK TABLE': check-table, *Note `OPTIMIZE TABLE': optimize-table, and *Note `REPAIR TABLE': repair-table. on partitioned tables. See *Note table-maintenance-sql::, for more information. * `REMOVE PARTITIONING' was introduced in MySQL 5.1.8 for the purpose of removing a table's partitioning without otherwise affecting the table or its data. (Previously, this was done using the `ENGINE' option.) This option can be combined with other *Note `ALTER TABLE': alter-table. options such as those used to add, drop, or rename drop columns or indexes. * In MySQL 5.1.7 and earlier, using the `ENGINE' option with *Note `ALTER TABLE': alter-table. caused any partitioning that a table might have had to be removed. Beginning with MySQL 5.1.8, this option merely changes the storage engine used by the table and no longer affects partitioning in any way. Only a single instance of any one of the following options can be used in a given *Note `ALTER TABLE': alter-table. statement: `PARTITION BY', `ADD PARTITION', `DROP PARTITION', `TRUNCATE 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;  File: manual.info, Node: alter-table-online-operations, Next: alter-table-examples, Prev: alter-table-partition-operations, Up: alter-table 13.1.7.2 `ALTER TABLE' Online Operations in MySQL Cluster ......................................................... Beginning with MySQL 5.1.17, operations that add and drop indexes on variable-width columns of *Note `NDBCLUSTER': mysql-cluster. 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 a MySQL Cluster (but see `Limitations' later in this section). Such operations do not require single user mode for *Note `NDBCLUSTER': mysql-cluster. table alterations made in a cluster with multiple API nodes; transactions can continue uninterrupted during online DDL operations. The `ONLINE' keyword can be used to perform online `ADD COLUMN', `ADD INDEX' (including `CREATE INDEX' statements), and `DROP INDEX' operations on *Note `NDBCLUSTER': mysql-cluster. tables. Online renaming of *Note `NDBCLUSTER': mysql-cluster. tables is also supported. The `ONLINE' and `OFFLINE' keywords are supported only in MySQL Cluster NDB 6.2 (beginning with 6.2.5) and 6.3 (beginning with 6.3.2) or later. For earlier MySQL Cluster releases or standard MySQL 5.1 releases: * The server determines automatically whether an `ADD INDEX' or `DROP INDEX' operation can be (and is) performed online or offline; if the column is of a variable-width data type, the operation is performed online. It is not possible to override the server behavior in this regard. * Attempting to use the `ONLINE' or `OFFLINE' keyword in an *Note `ALTER TABLE': alter-table, *Note `CREATE INDEX': create-index, or *Note `DROP INDEX': drop-index. statement results in an error. Currently you cannot add disk-based columns to *Note `NDBCLUSTER': mysql-cluster. tables online. This means that, if you wish to add an in-memory column to an *Note `NDBCLUSTER': mysql-cluster. 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 NDBCLUSTER; 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 ONLINE TABLE t1 ADD COLUMN c3 INT COLUMN_FORMAT DYNAMIC STORAGE MEMORY; 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 ONLINE TABLE t1 ADD COLUMN c3 INT COLUMN_FORMAT DYNAMIC; `ERROR 1235 (42000): This version of MySQL doesn't yet support 'ALTER ONLINE TABLE t1 ADD COLUMN c3 INT COLUMN_FORMAT DYNAMIC'' 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 c3 INT STORAGE MEMORY; Query OK, 0 rows affected, 1 warning (1.17 sec) Records: 0 Duplicates: 0 Warnings: 0 mysql> SHOW WARNINGS; +---------+------+---------------------------------------------------------------+ | Level | Code | Message | +---------+------+---------------------------------------------------------------+ | Warning | 1478 | Converted FIXED field to DYNAMIC to enable on-line ADD COLUMN | +---------+------+---------------------------------------------------------------+ 1 row in set (0.00 sec) 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) /*!50120 STORAGE MEMORY */ /*!50120 COLUMN_FORMAT DYNAMIC */ DEFAULT NULL, `t4` int(11) /*!50120 STORAGE MEMORY */ DEFAULT NULL, PRIMARY KEY (`c1`) ) /*!50100 TABLESPACE ts_1 STORAGE DISK */ ENGINE=ndbcluster DEFAULT CHARSET=latin1 1 row in set (0.03 sec) Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, adding in-memory columns to tables that were created using a table-level or column-level `STORAGE DISK' option did not work correctly. (Bug #42549) *Note*: The `STORAGE' and `COLUMN_FORMAT' keywords are supported only in MySQL Cluster; in any other version of MySQL, attempting to use either of these keywords in a *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. statement results in an error. In MySQL Cluster NDB 7.0 and later, it is also possible to use the statement `ALTER ONLINE TABLE ... REORGANIZE PARTITION' with no `PARTITION_NAMES INTO (PARTITION_DEFINITIONS)' option on *Note `NDBCLUSTER': mysql-cluster. tables. This can be used to redistribute MySQL Cluster data among new data nodes that have been added to the cluster online. For more information about this statement, see *Note alter-table-partition-operations:: For more information about adding data nodes online to a MySQL Cluster, see *Note mysql-cluster-online-add-node::. Prior to MySQL Cluster NDB 6.4.3, `ALTER ONLINE TABLE ... REORGANIZE PARTITION' with no `PARTITION_NAMES INTO (PARTITION_DEFINITIONS)' option did not work correctly with Disk Data tables or with in-memory *Note `NDBCLUSTER': mysql-cluster. tables having one or more disk-based columns. (Bug #42549) * Limitations of *Note `NDBCLUSTER': mysql-cluster. online operations * Online `DROP COLUMN' operations are not supported. Online *Note `ALTER TABLE': alter-table, *Note `CREATE INDEX': create-index, or *Note `DROP INDEX': drop-index. statements that add columns or add or drop indexes are subject to the following limitations: * A given online *Note `ALTER TABLE': 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. * An `ALTER TABLE' statement that performs a rename while using the `ONLINE' or `OFFLINE' keyword cannot perform any other operations, including but not limited to `ADD COLUMN', `ADD INDEX', or `DROP INDEX'. Beginning with MySQL Cluster NDB 6.3.52, MySQL Cluster NDB 7.0.38, and MySQL Cluster NDB 7.1.27, such statements are specifically disallowed, and fail with ER_NOT_SUPPORTED_YET. (Bug #16021021) * The table being altered is not locked with respect to API nodes other than the one on which an online *Note `ALTER TABLE': alter-table. `ADD COLUMN', `ADD INDEX', or `DROP INDEX' operation (or *Note `CREATE INDEX': create-index. or *Note `DROP INDEX': 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 *Note `NDBCLUSTER': mysql-cluster. storage engine is not sufficient for this purpose. * The storage engine used by the table cannot be changed online. * When used with MySQL 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 the `OFFLINE' keyword in the statement that adds or drops the index. Columns to be added online cannot use the *Note `BLOB': blob. or *Note `TEXT': blob. 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 t1 ( > c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY > ) ENGINE=NDBCLUSTER; Query OK, 0 rows affected (1.44 sec) mysql> ALTER ONLINE TABLE t1 > ADD COLUMN c2 INT, > ADD COLUMN c3 INT; Query OK, 0 rows affected, 2 warnings (0.93 sec) mysql> SHOW CREATE TABLE t1\G *************************** 1. row *************************** Table: t1 Create Table: CREATE TABLE `t1` ( `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. The preceding limitations do not apply to operations that merely rename tables or columns. For online *Note `ALTER TABLE': alter-table. operations on *Note `NDBCLUSTER': mysql-cluster. tables, fixed-format columns are converted to dynamic when they are added online, or when indexes are created or dropped online, as shown here: mysql> CREATE TABLE t1 ( > c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY > ) ENGINE=NDBCLUSTER; Query OK, 0 rows affected (1.44 sec) mysql> ALTER ONLINE TABLE t1 ADD COLUMN c2 INT, ADD COLUMN c3 INT; Query OK, 0 rows affected, 2 warnings (0.93 sec) Records: 0 Duplicates: 0 Warnings: 0 mysql> SHOW WARNINGS; +---------+------+---------------------------------------------------------------+ | Level | Code | Message | +---------+------+---------------------------------------------------------------+ | Warning | 1475 | Converted FIXED field to DYNAMIC to enable on-line ADD COLUMN | | Warning | 1475 | Converted FIXED field to DYNAMIC to enable on-line ADD COLUMN | +---------+------+---------------------------------------------------------------+ 2 rows in set (0.00 sec) *Note*: Existing columns, including the table's primary key, need not be dynamic; only the column or columns to be added online must be dynamic. mysql> CREATE TABLE t2 ( > c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY COLUMN_FORMAT FIXED > ) ENGINE=NDBCLUSTER; Query OK, 0 rows affected (2.10 sec) mysql> ALTER ONLINE TABLE t2 ADD COLUMN c2 INT; Query OK, 0 rows affected, 1 warning (0.78 sec) Records: 0 Duplicates: 0 Warnings: 0 mysql> SHOW WARNINGS; +---------+------+---------------------------------------------------------------+ | Level | Code | Message | +---------+------+---------------------------------------------------------------+ | Warning | 1475 | Converted FIXED field to DYNAMIC to enable on-line 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 *Note create-table::. The `KEY', `CONSTRAINT', and `IGNORE' keywords are supported in *Note `ALTER TABLE': alter-table. statements using the `ONLINE' keyword.  File: manual.info, Node: alter-table-examples, Prev: alter-table-online-operations, Up: alter-table 13.1.7.3 `ALTER TABLE' Examples ............................... Begin with a table `t1' that is 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 *Note `INTEGER': integer-types. 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 *Note `TIMESTAMP': datetime. 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 *Note `NDB': mysql-cluster. tables, it is also possible to change the storage type used for a table or column. For example, consider an *Note `NDB': mysql-cluster. 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 *Note `ALTER TABLE': 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 *Note `ALTER TABLE': 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 a MySQL Cluster Disk Data table with two columns, using this *Note `CREATE TABLE': 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 *Note `CREATE TABLE': create-table. statement). However, column `c2' uses in-memory storage, as can be seen here in the output of SHOW *Note `CREATE TABLE': 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 *Note `ALTER TABLE': alter-table. or by using the `AUTO_INCREMENT=VALUE' table option. See *Note server-system-variables::. 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 t1; ALTER TABLE t2 RENAME t1;  File: manual.info, Node: alter-tablespace, Next: alter-view, Prev: alter-table, Up: sql-syntax-data-definition 13.1.8 `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 `128M' (128 megabytes). You may optionally follow this integer value 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). *Note*: All MySQL 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 with the same name. Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, path and file names for data files could not be longer than 128 characters. (Bug #31770) On 32-bit systems, the maximum supported value for `INITIAL_SIZE' is `4G'. (Bug #29186) `INITIAL_SIZE' is rounded as for *Note `CREATE TABLESPACE': create-tablespace. Beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.32, MySQL Cluster NDB 7.0.13, and MySQL Cluster NDB 7.1.2, this rounding is done explicitly (also as with *Note `CREATE TABLESPACE': 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 *Note `ALTER TABLESPACE': 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 *Note mysql-cluster-disk-data-objects::. In addition, any data file to be dropped must previously have been added to the tablespace with *Note `CREATE TABLESPACE': create-tablespace. or *Note `ALTER TABLESPACE': 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. In MySQL 5.1, the only accepted values for ENGINE_NAME are *Note `NDB': mysql-cluster. and *Note `NDBCLUSTER': mysql-cluster. `WAIT' is parsed but otherwise ignored, and so has no effect in MySQL 5.1. 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 *Note `INFORMATION_SCHEMA.FILES': files-table. 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 *Note files-table::. *Note `ALTER TABLESPACE': alter-tablespace. was added in MySQL 5.1.6. In MySQL 5.1, it is useful only with Disk Data storage for MySQL Cluster. See *Note mysql-cluster-disk-data::.  File: manual.info, Node: alter-view, Next: create-database, Prev: alter-tablespace, Up: sql-syntax-data-definition 13.1.9 `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 *Note `CREATE VIEW': create-view. and the effect is the same as for *Note `CREATE OR REPLACE VIEW': create-view. See *Note create-view::. This statement requires the `CREATE VIEW' and `DROP' privileges for the view, and some privilege for each column referred to in the *Note `SELECT': select. statement. As of MySQL 5.1.23, *Note `ALTER VIEW': alter-view. is permitted only to the definer or users with the `SUPER' privilege.  File: manual.info, Node: create-database, Next: create-event, Prev: alter-view, Up: sql-syntax-data-definition 13.1.10 `CREATE DATABASE' Syntax -------------------------------- CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] DB_NAME [CREATE_SPECIFICATION] ... CREATE_SPECIFICATION: [DEFAULT] CHARACTER SET [=] CHARSET_NAME | [DEFAULT] COLLATE [=] COLLATION_NAME *Note `CREATE DATABASE': create-database. creates a database with the given name. To use this statement, you need the `CREATE' privilege for the database. *Note `CREATE SCHEMA': create-database. is a synonym for *Note `CREATE DATABASE': create-database. An error occurs if the database exists and you did not specify `IF NOT EXISTS'. 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. *Note 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 *Note `CREATE DATABASE': 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 *Note identifiers::. If a database name contains special characters, the name for the database directory contains encoded versions of those characters as described in *Note 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 *Note `SHOW DATABASES': show-databases. You can also use the *Note `mysqladmin': mysqladmin. program to create databases. See *Note mysqladmin::.  File: manual.info, Node: create-event, Next: create-function, Prev: create-database, Up: sql-syntax-data-definition 13.1.11 `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 'COMMENT'] 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 *Note events-configuration::. *Note `CREATE EVENT': 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 *Note `CREATE EVENT': create-event. statement are as follows: * The keywords *Note `CREATE EVENT': create-event. plus an event name, which uniquely identifies the event within a database schema. (Prior to MySQL 5.1.12, the event name needed to be unique only among events created by the same user within a schema.) * An `ON SCHEDULE' clause, which determines when and how often the event executes. * A *Note `DO': do. clause, which contains the SQL statement to be executed by an event. This is an example of a minimal *Note `CREATE EVENT': 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 *Note 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'' (the same format used in the *Note `GRANT': grant. statement), `CURRENT_USER', or `CURRENT_USER()'. The default `DEFINER' value is the user who executes the *Note `CREATE EVENT': 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 actually 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 *Note stored-programs-security::. The `DEFINER' clause was added in MySQL 5.1.17. 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 *Note account-activity-auditing::. `IF NOT EXISTS' has the same meaning for *Note `CREATE EVENT': create-event. as for *Note `CREATE TABLE': 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 *Note `DATETIME': datetime. or *Note `TIMESTAMP': datetime. 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. *Note `CREATE EVENT': 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 *Note 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 *Note `CREATE EVENT': create-event. and *Note `ALTER EVENT': alter-event. statements. Beginning with MySQL 5.1.13, 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 *Note events-metadata::. See also *Note show-events::, and *Note events-table::. *Note*: Prior to MySQL 5.1.17, the event time zone is not stored. The `mysql.event' table must be updated before events created in earlier releases can be created, altered, viewed, or used in MySQL 5.1.17 or later. You can use *Note `mysql_upgrade': mysql-upgrade. for this (see *Note mysql-upgrade::). 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 *Note `ALTER EVENT': alter-event. (see *Note alter-event::). Beginning with MySQL 5.1.18, a third value may also appear in place of `ENABLED' or `DISABLED'; `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 *Note 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 *Note `DO': 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 *Note 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 *Note `CREATE EVENT': create-event. statement that contains an *Note `ALTER EVENT': alter-event. statement in its *Note `DO': 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 *Note `SELECT': select. or *Note `SHOW': 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 *Note `SELECT ... INTO': select. and *Note `INSERT INTO ... SELECT': insert-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 *Note `DO': do. clause. Any references to tables in other schemas must be qualified with the proper schema name. (In MySQL 5.1.6, all tables referenced in event *Note `DO': do. clauses had to include a reference to the schema.) As with stored routines, you can use compound-statement syntax in the *Note `DO': 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 *Note 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 permitted within stored routines, see *Note stored-routines-syntax::. You can create an event as part of a stored routine, but an event cannot be created by another event.  File: manual.info, Node: create-function, Next: create-index, Prev: create-event, Up: sql-syntax-data-definition 13.1.12 `CREATE FUNCTION' Syntax -------------------------------- The *Note `CREATE FUNCTION': create-function. statement is used to create stored functions and user-defined functions (UDFs): * For information about creating stored functions, see *Note create-procedure::. * For information about creating user-defined functions, see *Note create-function-udf::.  File: manual.info, Node: create-index, Next: create-logfile-group, Prev: create-function, Up: sql-syntax-data-definition 13.1.13 `CREATE INDEX' Syntax ----------------------------- CREATE [ONLINE|OFFLINE] [UNIQUE|FULLTEXT|SPATIAL] INDEX INDEX_NAME [INDEX_TYPE] ON TBL_NAME (INDEX_COL_NAME,...) [INDEX_OPTION] ... 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 *Note `CREATE INDEX': create-index. is mapped to an *Note `ALTER TABLE': alter-table. statement to create indexes. See *Note alter-table::. *Note `CREATE INDEX': create-index. cannot be used to create a `PRIMARY KEY'; use *Note `ALTER TABLE': alter-table. instead. For more information about indexes, see *Note mysql-indexes::. Normally, you create all indexes on a table at the time the table itself is created with *Note `CREATE TABLE': create-table. See *Note create-table::. This guideline is especially important for `InnoDB' tables, where the primary key determines the physical layout of rows in the data file. *Note `CREATE INDEX': 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. 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 *Note `CHAR': char, *Note `VARCHAR': char, *Note `BINARY': binary-varbinary, and *Note `VARBINARY': binary-varbinary. columns. * *Note `BLOB': blob. and *Note `TEXT': blob. 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 *Note `CHAR': char, *Note `VARCHAR': char, and *Note `TEXT': blob. columns, and the first LENGTH bytes of each column value for *Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, and *Note `BLOB': blob. columns. * 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: 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 *Note `INSERT': insert. operations. Prefix support and lengths of prefixes (where supported) are storage engine dependent. For example, a prefix can be up to 1000 bytes long for `MyISAM' tables, and 767 bytes for `InnoDB' tables. The `NDBCLUSTER' storage engine does not support prefixes (see *Note mysql-cluster-limitations-unsupported::). *Note*: Prefix limits are measured in bytes, whereas the prefix length in *Note `CREATE INDEX': create-index. statements is interpreted as number of characters for nonbinary data types (*Note `CHAR': char, *Note `VARCHAR': char, *Note `TEXT': blob.). Take this into account when specifying a prefix length for a column that uses a multi-byte character set. Beginning with MySQL 5.1.17, indexes on variable-width columns of *Note `NDBCLUSTER': mysql-cluster. tables are created online; that is, without any table copying. The table is not locked against access from other MySQL 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. In standard MySQL 5.1 releases, it is not possible to override the server when it determines that an index is to be created without table copying. In MySQL Cluster, you can create indexes offline (which causes the table to be locked to all API nodes in the cluster) using the `OFFLINE' keyword. The rules and limitations governing `CREATE OFFLINE INDEX' and `CREATE ONLINE INDEX' are the same as for `ALTER OFFLINE TABLE ... ADD INDEX' and `ALTER ONLINE TABLE ... ADD INDEX'. You cannot cause the noncopying creation of an index that would normally be created offline by using the `ONLINE' keyword: If it is not possible to perform the *Note `CREATE INDEX': create-index. operation without table copying, the server ignores the `ONLINE' keyword. For more information, see *Note alter-table-online-operations::. *Note*: The `ONLINE' and `OFFLINE' keywords are available only in MySQL Cluster NDB 6.2.5, 6.3.2, and later MySQL Cluster releases; attempting to use these keywords in earlier MySQL Cluster releases or standard MySQL 5.1 releases results in a syntax error. 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. `FULLTEXT' indexes are supported only for `MyISAM' tables and can include only *Note `CHAR': char, *Note `VARCHAR': char, and *Note `TEXT': blob. columns. Indexing always happens over the entire column; column prefix indexing is not supported and any prefix length is ignored if specified. See *Note fulltext-search::, for details of operation. The `MyISAM', `InnoDB', *Note `NDB': mysql-cluster, and `ARCHIVE' storage engines support spatial columns such as (`POINT' and `GEOMETRY'. (*Note spatial-extensions::, 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' tables. Specifying `SPATIAL INDEX' for other storage engines results in an error. * Indexed columns must be `NOT NULL'. * In MySQL 5.1, 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 *Note `BLOB': 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. In MySQL 5.1: * You can add an index on a column that can have `NULL' values only if you are using the `MyISAM', `InnoDB', or `MEMORY' storage engine. * You can add an index on a *Note `BLOB': blob. or *Note `TEXT': blob. column only if you are using the `MyISAM', or `InnoDB' storage engine. 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. As of MySQL 5.1.10, index options can be given following the index column list. An INDEX_OPTION value can be any of the following: * `KEY_BLOCK_SIZE [=] VALUE' For compressed (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_compression) `InnoDB' Plugin tables, optionally specifies the size in bytes to use for pages (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_page). The value is treated as a hint; a different size could be used if necessary. A value of 0 represents the default compressed page size. See InnoDB Data Compression (http://dev.mysql.com/doc/refman/5.5/en/innodb-compression.html) for usage details. *Note*: Oracle recommends enabling `innodb_strict_mode' when using the `KEY_BLOCK_SIZE' clause for `InnoDB' tables. See InnoDB Strict Mode (http://dev.mysql.com/doc/refman/5.5/en/innodb-other-changes-strict-mode.html) for details. * INDEX_TYPE Some storage engines permit you to specify an index type when creating an index. The permissible index type values supported by different storage engines are shown in the following table. Where multiple index types are listed, the first one is the default when no index type specifier is given. This table lists permissible index types for each storage engine. Storage Permissible Index Types Engine `MyISAM' `BTREE' `InnoDB' `BTREE' `MEMORY'/`HEAP'`HASH', `BTREE' *Note `NDB': `BTREE', `HASH' (see note in text) mysql-cluster. Example: CREATE TABLE lookup (id INT) ENGINE = MEMORY; CREATE INDEX id_index ON lookup (id) USING BTREE; `BTREE' indexes are implemented by the *Note `NDBCLUSTER': mysql-cluster. storage engine as T-tree indexes. *Note*: For indexes on *Note `NDB': mysql-cluster. table columns, the `USING' option can be specified only for a unique index or primary key. `USING HASH' prevents the creation of an implicit ordered index; otherwise, creating a unique index or primary key on an *Note `NDB': mysql-cluster. table automatically results in the creation of both an ordered index and a hash index, each of which indexes the same set of columns. This means that a query using a unique index or primary key on a `NULL' column is always handled by *Note `NDB': mysql-cluster. with a full scan of the table. In particular, if you plan to use an `IS NULL' or `IS NOT NULL' condition involving a unique index or primary key column of an *Note `NDB': mysql-cluster. table, you should create any such index without `USING HASH'. The INDEX_TYPE clause cannot be used together with `SPATIAL INDEX'. If you specify an index type that is not valid 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. The parser recognizes `RTREE' as a type name, but currently this cannot be specified for any storage engine. Before MySQL 5.1.10, this option can be given only before the `ON TBL_NAME' clause. Use of the option in this position is deprecated as of 5.1.10 and support for it there 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. * `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. See *Note plugin-api::, for details on creating plugins.  File: manual.info, Node: create-logfile-group, Next: create-procedure, Prev: create-index, Up: sql-syntax-data-definition 13.1.14 `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 [=] COMMENT_TEXT] ENGINE [=] ENGINE_NAME This statement creates a new log file group named LOGFILE_GROUP having a single `UNDO' file named 'UNDO_FILE'. A *Note `CREATE LOGFILE GROUP': create-logfile-group. statement has one and only one `ADD UNDOFILE' clause. For rules covering the naming of log file groups, see *Note identifiers::. *Note*: All MySQL 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. Beginning with MySQL 5.1.8, you can have only one log file group per Cluster at any given time. (See Bug #16386) Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, path and file names for undo log files could not be longer than 128 characters. (Bug #31769) 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). The memory used for both `INITIAL_SIZE' and `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 these options by the setting of the `InitialLogFileGroup' data node configuration parameter. Beginning with MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, the maximum permitted for `UNDO_BUFFER_SIZE' is `600M'; previously, it was `150M'. (Bug #34102) On 32-bit systems, the maximum supported value for `INITIAL_SIZE' is `4G'. (Bug #29186) Beginning with MySQL Cluster NDB 2.1.18, 6.3.24, and 7.0.4, the minimum permitted value for `INITIAL_SIZE' is `1M'. (Bug #29574) 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.1, this must be *Note `NDB': mysql-cluster. (or *Note `NDBCLUSTER': mysql-cluster.). If `ENGINE' is not set, MySQL tries to use the engine specified by the `storage_engine' server system variable. In any case, if the engine is not specified as *Note `NDB': mysql-cluster. or *Note `NDBCLUSTER': mysql-cluster, 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 'MyISAM' 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 MySQL Cluster. REDO_BUFFER_SIZE, `NODEGROUP', `WAIT', and `COMMENT' are parsed but ignored, and so have no effect in MySQL 5.1. 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 *Note `INFORMATION_SCHEMA.FILES': files-table. 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) *Note `CREATE LOGFILE GROUP': create-logfile-group. was added in MySQL 5.1.6. In MySQL 5.1, it is useful only with Disk Data storage for MySQL Cluster. See *Note mysql-cluster-disk-data::.  File: manual.info, Node: create-procedure, Next: create-server, Prev: create-logfile-group, Up: sql-syntax-data-definition 13.1.15 `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 *Note `CREATE FUNCTION': create-function. statement is also used in MySQL to support UDFs (user-defined functions). See *Note adding-functions::. A UDF can be regarded as an external stored function. Stored functions share their namespace with UDFs. See *Note function-resolution::, for the rules describing how the server interprets references to different kinds of functions. To invoke a stored procedure, use the *Note `CALL': call. statement (see *Note call::). To invoke a stored function, refer to it in an expression. The function returns a value during expression evaluation. *Note `CREATE PROCEDURE': create-procedure. and *Note `CREATE FUNCTION': 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, *Note `CREATE FUNCTION': create-function. might require the `SUPER' privilege, as described in *Note 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 *Note 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 *Note `CALL': 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 *Note 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 *Note `mysql': 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 *Note `mysql': mysql. itself. See *Note 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 *Note `RETURN': return. statement returns a value of a different type, the value is coerced to the proper type. For example, if a function specifies an *Note `ENUM': enum. or *Note `SET': set. value in the `RETURNS' clause, but the *Note `RETURN': return. statement returns an integer, the value returned from the function is the string for the corresponding *Note `ENUM': enum. member of set of *Note `SET': 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, except that the `COLLATE' attribute cannot be used. The ROUTINE_BODY consists of a valid SQL routine statement. This can be a simple statement such as *Note `SELECT': select. or *Note `INSERT': 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 *Note 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 *Note `COMMIT': 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 *Note `SELECT': select. statements that do not have an `INTO VAR_LIST' clause and other statements such as *Note `SHOW': show, *Note `EXPLAIN': explain, and *Note `CHECK TABLE': 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'). *Note `USE': 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). This 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 *Note stored-program-restrictions::. For information about invoking stored procedures from within programs written in a language that has a MySQL interface, see *Note 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 *Note `SHOW CREATE PROCEDURE': show-create-procedure. and *Note `SHOW CREATE FUNCTION': 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. Prior to MySQL 5.1.21, the `DETERMINISTIC' characteristic is accepted, but not used by the optimizer. If binary logging is enabled, the `DETERMINISTIC' characteristic affects which routine definitions MySQL accepts. See *Note 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, *Note `SELECT': select.), but not statements that write data. * `MODIFIES SQL DATA' indicates that the routine contains statements that may write data (for example, *Note `INSERT': insert. or *Note `DELETE': 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. The `DEFINER' clause was added in MySQL 5.1.8. If a USER value is given for the `DEFINER' clause, it should be a MySQL account specified as `'USER_NAME'@'HOST_NAME'' (the same format used in the *Note `GRANT': grant. statement), `CURRENT_USER', or `CURRENT_USER()'. The default `DEFINER' value is the user who executes the *Note `CREATE PROCEDURE': create-procedure. or *Note `CREATE FUNCTION': create-function. or 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 actually 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 *Note 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 *Note 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 *Note `DECLARE': 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 are used. If there is no such attribute, the database character set in effect at routine creation time and its default collation are used. (The database character set is given by the value of the `character_set_database' system variable.) The `COLLATE' attribute is not supported. (This includes use of `BINARY', which in this context specifies the binary collation of the character set.) 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.  File: manual.info, Node: create-server, Next: create-table, Prev: create-procedure, Up: sql-syntax-data-definition 13.1.16 `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 *Note `CREATE TABLE': 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 '192.168.1.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 *Note federated-storage-engine::. `CREATE SERVER' causes an implicit commit. In MySQL 5.1, `CREATE SERVER' is written to the binary log only when using row-based logging. It is not logged when `binlog_format' is equal to `STATEMENT' or `MIXED'. `CREATE SERVER' was added in MySQL 5.1.15.  File: manual.info, Node: create-table, Next: create-tablespace, Prev: create-server, Up: sql-syntax-data-definition 13.1.17 `CREATE TABLE' Syntax ----------------------------- * Menu: * create-table-select:: `CREATE TABLE ... SELECT' Syntax * create-table-foreign-keys:: Using `FOREIGN KEY' Constraints * silent-column-changes:: Silent Column Specification Changes CREATE [TEMPORARY] TABLE [IF NOT EXISTS] TBL_NAME (CREATE_DEFINITION,...) [TABLE_OPTIONS] [PARTITION_OPTIONS] Or: CREATE [TEMPORARY] TABLE [IF NOT EXISTS] TBL_NAME [(CREATE_DEFINITION,...)] [TABLE_OPTIONS] [PARTITION_OPTIONS] SELECT_STATEMENT Or: 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: 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 | TIMESTAMP | DATETIME | 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 | MEDIUMBLOB | LONGBLOB | TINYTEXT [BINARY] [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME] | TEXT [BINARY] [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME] | MEDIUMTEXT [BINARY] [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME] | LONGTEXT [BINARY] [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] | 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 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 TABLE_OPTIONS: TABLE_OPTION [[,] TABLE_OPTION] ... TABLE_OPTION: ENGINE [=] ENGINE_NAME | AUTO_INCREMENT [=] VALUE | AVG_ROW_LENGTH [=] VALUE | [DEFAULT] CHARACTER SET [=] CHARSET_NAME | CHECKSUM [=] {0 | 1} | [DEFAULT] COLLATE [=] COLLATION_NAME | COMMENT [=] 'STRING' | CONNECTION [=] 'CONNECT_STRING' | DATA DIRECTORY [=] 'ABSOLUTE PATH TO DIRECTORY' | DELAY_KEY_WRITE [=] {0 | 1} | INDEX DIRECTORY [=] 'ABSOLUTE PATH TO DIRECTORY' | 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} | TABLESPACE TABLESPACE_NAME [STORAGE {DISK|MEMORY|DEFAULT}] | UNION [=] (TBL_NAME[,TBL_NAME]...) PARTITION_OPTIONS: PARTITION BY { [LINEAR] HASH(EXPR) | [LINEAR] KEY(COLUMN_LIST) | RANGE(EXPR) | LIST(EXPR) } [PARTITIONS NUM] [SUBPARTITION BY { [LINEAR] HASH(EXPR) | [LINEAR] KEY(COLUMN_LIST) } [SUBPARTITIONS NUM] ] [(PARTITION_DEFINITION [, PARTITION_DEFINITION] ...)] PARTITION_DEFINITION: PARTITION PARTITION_NAME [VALUES {LESS THAN {(EXPR) | `MAXVALUE'} | IN (VALUE_LIST)}] [[STORAGE] ENGINE [=] ENGINE_NAME] [COMMENT [=] 'COMMENT_TEXT' ] [DATA DIRECTORY [=] '`DATA_DIR''] [INDEX DIRECTORY [=] '`INDEX_DIR''] [MAX_ROWS [=] MAX_NUMBER_OF_ROWS] [MIN_ROWS [=] MIN_NUMBER_OF_ROWS] [TABLESPACE [=] TABLESPACE_NAME] [NODEGROUP [=] NODE_GROUP_ID] [(SUBPARTITION_DEFINITION [, SUBPARTITION_DEFINITION] ...)] SUBPARTITION_DEFINITION: SUBPARTITION LOGICAL_NAME [[STORAGE] ENGINE [=] ENGINE_NAME] [COMMENT [=] 'COMMENT_TEXT' ] [DATA DIRECTORY [=] '`DATA_DIR''] [INDEX DIRECTORY [=] '`INDEX_DIR''] [MAX_ROWS [=] MAX_NUMBER_OF_ROWS] [MIN_ROWS [=] MIN_NUMBER_OF_ROWS] [TABLESPACE [=] TABLESPACE_NAME] [NODEGROUP [=] NODE_GROUP_ID] SELECT_STATEMENT: [IGNORE | REPLACE] [AS] SELECT ... (SOME VALID SELECT STATEMENT) *Note `CREATE TABLE': create-table. creates a table with the given name. You must have the `CREATE' privilege for the table. Rules for permissible table names are given in *Note identifiers::. By default, the table is created in the default database. An error occurs if the table exists, if there is no default database, or if the database does not exist. 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`'. * Temporary Tables * You can use the `TEMPORARY' keyword when creating a table. A `TEMPORARY' table is visible only to the current connection, and is dropped automatically when the connection is closed. This means that two different connections 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.) To create temporary tables, you must have the `CREATE TEMPORARY TABLES' privilege. *Note*: *Note `CREATE TABLE': create-table. does not automatically commit the current active transaction if you use the `TEMPORARY' keyword. * Existing Table with Same Name * The keywords `IF NOT EXISTS' prevent 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 *Note `CREATE TABLE': create-table. statement. * Physical Representation * 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 `InnoDB' tables, the file storage is controlled by the `innodb_file_per_table' configuration option. When this option is turned off, all `InnoDB' tables and indexes are stored in the system tablespace (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_system_tablespace), represented by one or more ibdata* files (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_ibdata_file). For each `InnoDB' table created when this option is turned on, the table data and all associated indexes are stored in a .ibd file (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_ibd_file) located inside the database directory. For `MyISAM' tables, the storage engine creates data and index files. Thus, for each `MyISAM' table TBL_NAME, there are three disk files. This table describes the purpose of `MyISAM' table TBL_NAME disk files. File Purpose `TBL_NAME.frm' Table format (definition) file `TBL_NAME.MYD' Data file `TBL_NAME.MYI' Index file *Note 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 *Note identifier-mapping::. * Data Types and Attributes for Columns * 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 *Note data-types::, and *Note spatial-extensions::. 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 *Note `BLOB': blob. or *Note `TEXT': blob. types. * If neither `NULL' nor `NOT NULL' is specified, the column is treated as though `NULL' had been specified. * 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 *Note `mysql_insert_id()': mysql-insert-id. C API function. See *Note information-functions::, and *Note 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 *Note server-sql-mode::. *Note*: 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 *Note 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 For information about `InnoDB' and `AUTO_INCREMENT', see *Note innodb-auto-increment-handling::. For information about `AUTO_INCREMENT' and MySQL Replication, see *Note replication-features-auto-increment::. * Character data types (*Note `CHAR': char, *Note `VARCHAR': char, *Note `TEXT': blob.) can include `CHARACTER SET' and `COLLATE' attributes to specify the character set and collation for the column. For details, see *Note charset::. `CHARSET' is a synonym for `CHARACTER SET'. Example: CREATE TABLE t (c CHAR(20) CHARACTER SET utf8 COLLATE utf8_bin); MySQL 5.1 interprets length specifications in character column definitions in characters. (Versions before MySQL 4.1 interpreted them in bytes.) Lengths for *Note `BINARY': binary-varbinary. and *Note `VARBINARY': binary-varbinary. are in bytes. * The `DEFAULT' clause 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 *Note `TIMESTAMP': datetime. column. See *Note timestamp-initialization::. If a column definition includes no explicit `DEFAULT' value, MySQL determines the default value as described in *Note data-type-defaults::. *Note `BLOB': blob. and *Note `TEXT': blob. columns cannot be assigned a default value. *Note `CREATE TABLE': create-table. fails if a date-valued default is not correct according to the `NO_ZERO_IN_DATE' SQL mode, even if strict SQL mode is not enabled. For example, `c1 DATE DEFAULT '2010-00-00'' causes *Note `CREATE TABLE': create-table. to fail with `Invalid default value for 'c1''. Native default value handling in MySQL Cluster NDB 7.0.15, MySQL Cluster NDB 7.1.4, and later Starting with MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, default values for table columns are stored by *Note `NDBCLUSTER': mysql-cluster, rather than by the MySQL server as was previously the case. Because less data must be sent from an SQL node to the data nodes, inserts on tables having column value defaults can be performed more efficiently than before. Tables created using MySQL Cluster releases previous to the introduction of native default value support can still be used in MySQL Cluster NDB 7.0.15 and later, as well as well as MySQL Cluster NDB 7.1.4 and later. However, such tables continue to use defaults supplied by the MySQL server until they are upgraded. This upgrade can be done by means of an offline *Note `ALTER TABLE': alter-table. statement. *Important*: You cannot set or change a table column's default value using a noncopying *Note `ALTER TABLE': alter-table. operation. Tables created in versions of MySQL Cluster that support native default values cannot be used with versions of MySQL Cluster that lack this support. *Note `NDBCLUSTER': mysql-cluster. tables supporting native default values are still subject to the restrictions on default values imposed by the MySQL server. For more information, see *Note data-type-defaults::. * A comment for a column can be specified with the `COMMENT' option, up to 255 characters long. The comment is displayed by the *Note `SHOW CREATE TABLE': show-create-table. and *Note `SHOW FULL COLUMNS': show-columns. statements. * In MySQL Cluster--beginning with MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB 6.3.2--it is also possible to specify a data storage format for individual columns of *Note `NDB': mysql-cluster. 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). For *Note `NDB': mysql-cluster. tables, the default value for `COLUMN_FORMAT' is `DEFAULT'. `COLUMN_FORMAT' currently has no effect on columns of tables using storage engines other than *Note `NDB': mysql-cluster. The `COLUMN_FORMAT' keyword is supported only in the build of *Note `mysqld': mysqld. that is supplied with MySQL Cluster; it is not recognized in any other version of MySQL, where attempting to use `COLUMN_FORMAT' causes a syntax error. * For *Note `NDB': mysql-cluster. tables, beginning with MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB 6.3.2, it is also 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 *Note `CREATE TABLE': 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 *Note `NDB': mysql-cluster. tables, `STORAGE DEFAULT' is equivalent to `STORAGE MEMORY'. The `STORAGE' clause has no effect on tables using storage engines other than *Note `NDB': mysql-cluster. The `STORAGE' keyword is supported only in the build of *Note `mysqld': mysqld. that is supplied with MySQL Cluster; it is not recognized in any other version of MySQL, where any attempt to use the `STORAGE' keyword causes a syntax error. * `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. * 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'. * A `PRIMARY KEY' is 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 *Note innodb-table-and-index::.) * 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' or `UNIQUE' index consists of only one column that has an integer type, you can also refer to the column as `_rowid' in *Note `SELECT': 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 *Note show-index::. * 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; Before MySQL 5.1.10, `USING' can be given only before the index column list. As of 5.1.10, 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. `USING' is one such option. For details about permissible INDEX_OPTION values, see *Note create-index::. For more information about indexes, see *Note mysql-indexes::. * In MySQL 5.1, 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. * For *Note `CHAR': char, *Note `VARCHAR': char, *Note `BINARY': binary-varbinary, and *Note `VARBINARY': binary-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. *Note `BLOB': blob. and *Note `TEXT': blob. 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 *Note `CHAR': char, *Note `VARCHAR': char, and *Note `TEXT': blob. columns, and the first LENGTH bytes of each column value for *Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, and *Note `BLOB': blob. columns. Indexing only a prefix of column values like this can make the index file much smaller. See *Note column-indexes::. Only the `InnoDB' and `MyISAM' storage engines support indexing on *Note `BLOB': blob. and *Note `TEXT': blob. columns. 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). Note that prefix limits are measured in bytes, whereas the prefix length in *Note `CREATE TABLE': create-table. statements is interpreted as number of characters for nonbinary data types (*Note `CHAR': char, *Note `VARCHAR': char, *Note `TEXT': blob.). Take this into account when specifying a prefix length for a column that uses a multi-byte character set. * 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. * When you use `ORDER BY' or `GROUP BY' on a column in a *Note `SELECT': select, the server sorts values using only the initial number of bytes indicated by the `max_sort_length' system variable. * You can create special `FULLTEXT' indexes, which are used for full-text searches. Only the `MyISAM' storage engine supports `FULLTEXT' indexes. They can be created only from *Note `CHAR': char, *Note `VARCHAR': char, and *Note `TEXT': blob. columns. Indexing always happens over the entire column; column prefix indexing is not supported and any prefix length is ignored if specified. See *Note 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. See *Note plugin-api::, for details on creating plugins. * You can create `SPATIAL' indexes on spatial data types. Spatial types are supported only for `MyISAM' tables and indexed columns must be declared as `NOT NULL'. See *Note spatial-extensions::. * *Note `InnoDB': innodb-storage-engine. 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. For more detailed information and examples, see *Note create-table-foreign-keys::. For information specific to foreign keys in `InnoDB', see *Note innodb-foreign-key-constraints::. For other storage engines, MySQL Server parses and ignores the `FOREIGN KEY' and `REFERENCES' syntax in *Note `CREATE TABLE': create-table. statements. The `CHECK' clause is parsed but ignored by all storage engines. See *Note 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 does not recognize or support `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. *Note*: Partitioned tables employing the *Note `InnoDB': innodb-storage-engine. storage engine do not support foreign keys. See *Note partitioning-limitations::, for more information. * 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 *Note column-count-limit::. The `TABLESPACE' and `STORAGE' table options were both introduced in MySQL 5.1.6. In MySQL 5.1, they are employed only with *Note `NDBCLUSTER': mysql-cluster. tables. The tablespace named TABLESPACE_NAME must already have been created using *Note `CREATE TABLESPACE': create-tablespace. `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 a MySQL Cluster Disk Data tablespace. See *Note mysql-cluster-disk-data::, for more information. *Important*: A `STORAGE' clause cannot be used in a *Note `CREATE TABLE': create-table. statement without a `TABLESPACE' clause. The `ENGINE' table option specifies the storage engine for the table. * Storage Engines * The `ENGINE' table option 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 equivalent to specifying the default storage engine name. This table lists storage engine names that are taken by the `ENGINE' table option. A description is provided for each name. Storage Engine Description `ARCHIVE' The archiving storage engine. See *Note archive-storage-engine::. `CSV' Tables that store rows in comma-separated values format. See *Note csv-storage-engine::. `EXAMPLE' An example engine. See *Note example-storage-engine::. `FEDERATED' Storage engine that accesses remote tables. See *Note federated-storage-engine::. `HEAP' This is a synonym for `MEMORY'. `InnoDB' Transaction-safe tables with row locking and foreign keys. See *Note innodb-storage-engine::. `MEMORY' The data for this storage engine is stored only in memory. See *Note memory-storage-engine::. `MERGE' A collection of `MyISAM' tables used as one table. Also known as `MRG_MyISAM'. See *Note merge-storage-engine::. `MyISAM' The binary portable storage engine that is the default storage engine used by MySQL. See *Note myisam-storage-engine::. *Note Clustered, fault-tolerant, memory-based tables. `NDBCLUSTER': Also known as *Note `NDB': mysql-cluster. See mysql-cluster. *Note mysql-cluster::. If a storage engine is specified that is not available, MySQL uses the default engine instead. Normally, this is `MyISAM'. For example, if a table definition includes the `ENGINE=INNODB' option but the MySQL server does not support `INNODB' tables, the table is created as a `MyISAM' table. This makes it possible to have a replication setup where you have transactional tables on the master but tables created on the slave are nontransactional (to get more speed). In MySQL 5.1, a warning occurs if the storage engine specification is not honored. Engine substitution can be controlled by the setting of the `NO_ENGINE_SUBSTITUTION' SQL mode, as described in *Note server-sql-mode::. *Note*: The older `TYPE' option was synonymous with `ENGINE'. `TYPE' has been deprecated since MySQL 4.0 but is still supported for backward compatibility in MySQL 5.1 (excepting MySQL 5.1.7). Since MySQL 5.1.8, it produces a warning. It is removed in MySQL 5.5. _You should not use `TYPE' in any new applications, and you should immediately begin conversion of existing applications to use `ENGINE' instead_. (See the Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/) for MySQL 5.1.8.) * Optimizing Performance * The other 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 *Note `ALTER TABLE': alter-table. to convert the table to use a different storage engine. * `AUTO_INCREMENT' The initial `AUTO_INCREMENT' value for the table. In MySQL 5.1, this works for `MyISAM', `MEMORY', and `InnoDB' tables. It also works for `ARCHIVE' tables as of MySQL 5.1.6. 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 *Note `CREATE TABLE': 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 *Note 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' Specify 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 *Note `CHECKSUM TABLE': checksum-table. statement reports the checksum. (`MyISAM' only.) * `[DEFAULT] COLLATE' Specify a default collation for the table. * `COMMENT' A comment for the table, up to 60 characters long. * `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' By using `DATA DIRECTORY='DIRECTORY'' or `INDEX DIRECTORY='DIRECTORY'' you can specify where the `MyISAM' storage engine should put a table's data file and index file. The directory must be the full path name to the directory, not a relative path. *Important*: Beginning with MySQL 5.1.23, 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 *Note 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. As of MySQL 5.1.23, 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*: Beginning with MySQL 5.1.24, 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 *Note server-system-variables::. (`MyISAM' only.) * `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 *Note merge-storage-engine::. * `KEY_BLOCK_SIZE' For compressed (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_compression) `InnoDB' tables, optionally specifies the size in kilobytes to use for pages (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_page). The value is treated as a hint; a different size could be used if necessary. A value of 0 represents that the default compressed page size. See InnoDB Data Compression (http://dev.mysql.com/doc/refman/5.5/en/innodb-compression.html) for usage details. Individual index definitions can specify a `KEY_BLOCK_SIZE' value of their own to override the table value. `KEY_BLOCK_SIZE' was added in MySQL 5.1.10. *Note*: Oracle recommends enabling `innodb_strict_mode' when using the `KEY_BLOCK_SIZE' clause for `InnoDB' tables. See InnoDB Strict Mode (http://dev.mysql.com/doc/refman/5.5/en/innodb-other-changes-strict-mode.html) for details. * `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. The *Note `NDB': mysql-cluster. storage engine treats this value as a maxmimum. If you plan to create very large MySQL Cluster tables (containing millions of rows), you should use this option to insure that *Note `NDB': mysql-cluster. 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. *Note*: This option was incorrectly ignored by MySQL Cluster NDB 7.0 prior to version 7.0.20 and MySQL Cluster NDB 7.1 prior to version 7.1.9 (see Bug #57360). 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 *Note `MEMORY': memory-storage-engine. storage engine uses this option as a hint about memory use. * `PACK_KEYS' `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 *Note `CHAR': char, *Note `VARCHAR': char, *Note `BINARY': binary-varbinary, or *Note `VARBINARY': binary-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. The choices differ depending on the storage engine used for the table. For `InnoDB' tables: * Rows are stored in compact format (`ROW_FORMAT=COMPACT') by default. * The noncompact format used in older versions of MySQL can still be requested by specifying `ROW_FORMAT=REDUNDANT'. * To enable compression for `InnoDB' tables, specify `ROW_FORMAT=COMPRESSED' and follow the procedures in InnoDB Data Compression (http://dev.mysql.com/doc/refman/5.5/en/innodb-compression.html). This feature is available when you use the InnoDB Plugin for MySQL 5.1. * For more efficient `InnoDB' storage of data types, especially *Note `BLOB': blob. types, specify `ROW_FORMAT=DYNAMIC' and follow the procedures in Barracuda File Format: `DYNAMIC' and `COMPRESSED' Row Formats (http://dev.mysql.com/doc/refman/5.5/en/innodb-row-format-dynamic.html). This feature is available when you use the InnoDB Plugin for MySQL 5.1. Both the `COMPRESSED' and `DYNAMIC' row formats require creating the table with the configuration settings `innodb_file_per_table=1' and `innodb_file_format=barracuda'. * When you specify a non-default `ROW_FORMAT' clause, consider also enabling the `innodb_strict_mode' configuration option. See InnoDB Strict Mode (http://dev.mysql.com/doc/refman/5.5/en/innodb-other-changes-strict-mode.html) for details. For `MyISAM' tables, the option value can be `FIXED' or `DYNAMIC' for static or variable-length row format. *Note `myisampack': myisampack. sets the type to `COMPRESSED'. See *Note myisam-table-formats::. *Note*: When executing a *Note `CREATE TABLE': create-table. statement, if you specify a row format which 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 this column in response to *Note `SHOW TABLE STATUS': show-table-status. is the actual row format used. This may differ from the value in the `Create_options' column because the original *Note `CREATE TABLE': create-table. definition is retained during creation. * *Note `UNION': union. *Note `UNION': union. is used when you want to access a collection of identical `MyISAM' tables as one. This works only with `MERGE' tables. See *Note 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. * Partitioning * PARTITION_OPTIONS can be used to control partitioning of the table created with *Note `CREATE TABLE': create-table. *Important*: 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 *Note 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. 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.) The choices that are available for this function in MySQL 5.1 are shown in the following list: * `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 *Note `CREATE TABLE': 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 *Note 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 *Note 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 table columns. 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 *Note partitioning-linear-hash::, and *Note 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; 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. `VALUES LESS THAN' can be used with either a literal value or an expression that evaluates to a single value. Suppose that you have a table that you wish to partition on a column containing year values, according to the following scheme. This table illustrates a table partitioning scheme based on a column containing year values, as described in the preceding text. The table lists partition numbers and corresponding range of years. 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 *Note `CREATE TABLE': 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. Note that `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. * `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*: Currently, the value list used with `VALUES IN' must consist of integer values only. * 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). * 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. * MySQL 5.1.12 introduces rigorous checking of the value used in a `PARTITIONS' or `SUBPARTITIONS' clause. Beginning with this version, 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) *Note*: The expression (EXPR) used in a `PARTITION BY' clause cannot refer to any columns not in the table being created; beginning with MySQL 5.1.23, such references are specifically not permitted and cause the statement to fail with an error. (Bug #29444) Each partition may be individually defined using a PARTITION_DEFINITION clause. The individual parts making up this clause are as follows: * `PARTITION PARTITION_NAME': This specifies a logical name for the partition. * A `VALUES' clause: 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 *Note partitioning::, for syntax examples. * An optional `COMMENT' clause may be used to specify a string that describes the partition. Example: COMMENT = 'Data for the years previous to 1999' * `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. 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 *Note `CREATE TABLE': 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. Beginning with MySQL 5.1.24, these options are ignored on Windows, except that a warning is generated. (Bug #30459) *Note*: Prior to MySQL 5.1.18, `DATA DIRECTORY' and `INDEX DIRECTORY' were permitted even if the `NO_DIR_IN_CREATE' server SQL mode was in effect at the time that a partitioned table was created. Beginning with MySQL 5.1.18, these 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. * The optional `TABLESPACE' clause may be used to designate a tablespace for the partition. Used for MySQL Cluster only. * 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. * The `NODEGROUP' option can be used to make this partition act as part of the node group identified by NODE_GROUP_ID. This option is applicable only to MySQL Cluster. * 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 *Note partitioning-subpartitions::. Partitions can be modified, merged, added to tables, and dropped from tables. For basic information about the MySQL statements to accomplish these tasks, see *Note alter-table::. For more detailed descriptions and examples, see *Note partitioning-management::. *Important*: The original *Note `CREATE TABLE': 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 *Note `ALTER TABLE': alter-table. statement, the original table options specified are retained. This enables you to change between *Note `InnoDB': innodb-storage-engine. and *Note `MyISAM': myisam-storage-engine. 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 *Note `DESCRIBE': describe. or with *Note `SHOW TABLE STATUS': show-table-status.) and the table creation string (accessible through *Note `SHOW CREATE TABLE': show-create-table.) will report different values. * Cloning or Copying a Table * You can create one table from another by adding a *Note `SELECT': select. statement at the end of the *Note `CREATE TABLE': create-table. statement: CREATE TABLE NEW_TBL SELECT * FROM ORIG_TBL; For more information, see *Note create-table-select::. Use `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. `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'. In MySQL 5.1, changes to the SQL mode do not affect *Note `CREATE TABLE ... LIKE': create-table. If the current SQL mode is different from the mode in effect when the original table was created, the statement succeeds even if the table definition is invalid for the new mode.  File: manual.info, Node: create-table-select, Next: create-table-foreign-keys, Prev: create-table, Up: create-table 13.1.17.1 `CREATE TABLE ... SELECT' Syntax .......................................... You can create one table from another by adding a *Note `SELECT': select. statement at the end of the *Note `CREATE TABLE': create-table. statement: CREATE TABLE NEW_TBL [AS] SELECT * FROM ORIG_TBL; MySQL creates new columns for all elements in the *Note `SELECT': 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 *Note `MyISAM': myisam-storage-engine. table with three columns, `a', `b', and `c'. The `ENGINE' option is part of the *Note `CREATE TABLE': create-table. statement, and should not be used following the *Note `SELECT': select.; this would result in a syntax error. The same is true for other *Note `CREATE TABLE': create-table. options such as `CHARSET'. Notice that the columns from the *Note `SELECT': 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 *Note `CREATE TABLE ... SELECT': create-table, columns named only in the *Note `CREATE TABLE': create-table. part come first. Columns named in both parts or only in the *Note `SELECT': select. part come after that. The data type of *Note `SELECT': select. columns can be overridden by also specifying the column in the *Note `CREATE TABLE': 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 *Note `SELECT': select. by `IGNORE' or *Note `REPLACE': replace. to indicate how to handle rows that duplicate unique key values. With `IGNORE', new rows that duplicate an existing row on a unique key value are discarded. With *Note `REPLACE': replace, new rows replace rows that have the same unique key value. If neither `IGNORE' nor *Note `REPLACE': replace. is specified, duplicate unique key values result in an error. *Note `CREATE TABLE ... SELECT': create-table. 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 *Note `SELECT': select. statement: mysql> CREATE TABLE bar (UNIQUE (n)) SELECT n FROM foo; Some conversion of data types might occur. For example, the `AUTO_INCREMENT' attribute is not preserved, and *Note `VARCHAR': char. columns can become *Note `CHAR': 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 *Note `CREATE TABLE ... SELECT': 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 generated column: CREATE TABLE foo (a TINYINT NOT NULL) SELECT b+1 AS a FROM bar; For *Note `CREATE TABLE ... SELECT': create-table, if `IF NOT EXISTS' is given and the destination table already exists, the result is version dependent. Before MySQL 5.5.6, MySQL handles the statement as follows: * The table definition given in the *Note `CREATE TABLE': create-table. part is ignored. No error occurs, even if the definition does not match that of the existing table. MySQL attempts to insert the rows from the *Note `SELECT': select. part anyway. * If there is a mismatch between the number of columns in the table and the number of columns produced by the *Note `SELECT': select. part, the selected values are assigned to the rightmost columns. For example, if the table contains N columns and the *Note `SELECT': select. produces M columns, where M < N, the selected values are assigned to the M rightmost columns in the table. Each of the initial N - M columns is assigned its default value, either that specified explicitly in the column definition or the implicit column data type default if the definition contains no default. If the *Note `SELECT': select. part produces too many columns (M > N), an error occurs. * If strict SQL mode is enabled and any of these initial columns do not have an explicit default value, the statement fails with an error. The following example illustrates `IF NOT EXISTS' handling: mysql> CREATE TABLE t1 (i1 INT DEFAULT 0, i2 INT, i3 INT, i4 INT); Query OK, 0 rows affected (0.05 sec) mysql> CREATE TABLE IF NOT EXISTS t1 (c1 CHAR(10)) SELECT 1, 2; Query OK, 1 row affected, 1 warning (0.01 sec) Records: 1 Duplicates: 0 Warnings: 0 mysql> SELECT * FROM t1; +------+------+------+------+ | i1 | i2 | i3 | i4 | +------+------+------+------+ | 0 | NULL | 1 | 2 | +------+------+------+------+ 1 row in set (0.00 sec) As of MySQL 5.5.6, handling of *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select. statements was changed for the case that the destination table already exists. This change also involves a change in MySQL 5.1 beginning with 5.1.51. * Previously, for *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select, MySQL produced a warning that the table exists, but inserted the rows and wrote the statement to the binary log anyway. By contrast, *Note `CREATE TABLE ... SELECT': create-table-select. (without `IF NOT EXISTS') failed with an error, but MySQL inserted no rows and did not write the statement to the binary log. * MySQL now handles both statements the same way when the destination table exists, in that neither statement inserts rows or is written to the binary log. The difference between them is that MySQL produces a warning when `IF NOT EXISTS' is present and an error when it is not. This change means that, for the preceding example, the *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select. statement inserts nothing into the destination table as of MySQL 5.5.6. This change in handling of `IF NOT EXISTS' results in an incompatibility for statement-based replication from a MySQL 5.1 master with the original behavior and a MySQL 5.5 slave with the new behavior. Suppose that *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select. is executed on the master and the destination table exists. The result is that rows are inserted on the master but not on the slave. (Row-based replication does not have this problem.) To address this issue, statement-based binary logging for *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select. is changed in MySQL 5.1 as of 5.1.51: * If the destination table does not exist, there is no change: The statement is logged as is. * If the destination table does exist, the statement is logged as the equivalent pair of *Note `CREATE TABLE IF NOT EXISTS': create-table-select. and *Note `INSERT ... SELECT': insert-select. statements. (If the *Note `SELECT': select. in the original statement is preceded by `IGNORE' or *Note `REPLACE': replace, the *Note `INSERT': insert. becomes *Note `INSERT IGNORE': insert. or *Note `REPLACE': replace, respectively.) This change provides forward compatibility for statement-based replication from MySQL 5.1 to 5.5 because when the destination table exists, the rows will be inserted on both the master and slave. To take advantage of this compatibility measure, the 5.1 server must be at least 5.1.51 and the 5.5 server must be at least 5.5.6. To upgrade an existing 5.1-to-5.5 replication scenario, upgrade the master first to 5.1.51 or higher. Note that this differs from the usual replication upgrade advice of upgrading the slave first. A workaround for applications that wish to achieve the original effect (rows inserted regardless of whether the destination table exists) is to use *Note `CREATE TABLE IF NOT EXISTS': create-table-select. and *Note `INSERT ... SELECT': insert-select. statements rather than *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select. statements. Along with the change just described, the following related change was made: Previously, if an existing view was named as the destination table for *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table-select, rows were inserted into the underlying base table and the statement was written to the binary log. As of MySQL 5.1.51 and 5.5.6, nothing is inserted or logged. To ensure that the binary log can be used to re-create the original tables, MySQL does not permit concurrent inserts during *Note `CREATE TABLE ... SELECT': create-table.  File: manual.info, Node: create-table-foreign-keys, Next: silent-column-changes, Prev: create-table-select, Up: create-table 13.1.17.2 Using `FOREIGN KEY' Constraints ......................................... MySQL supports foreign keys, which let you cross-reference related data across tables, and foreign key constraints (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_foreign_key_constraint), which help keep this spread-out data consistent. The essential syntax for a foreign key constraint definition in a *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': 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 INDEX_NAME represents a foreign key ID. If given, this is ignored if an index for the foreign key is defined explicitly. Otherwise, if MySQL creates an index for the foreign key, it uses INDEX_NAME for the index name. Foreign keys definitions are subject to the following conditions: * Foreign key relationships involve a parent table (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_parent_table) that holds the central data values, and a child table (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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. * 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. * 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 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. * Index prefixes on foreign key columns are not supported. One consequence of this is that *Note `BLOB': blob. and *Note `TEXT': blob. 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 1005 (HY000): Can't create table 'test.#sql-211d_3' (errno: 121)'. If the clause is not given, or a SYMBOL is not included following the `CONSTRAINT' keyword, a name for the constraint is created automatically. * *Note `InnoDB': innodb-storage-engine. does not currently support foreign keys for tables with user-defined partitioning. This includes both parent and child tables. * Referential Actions * This section describes how foreign keys help guarantee referential integrity (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_referential_integrity). For storage engines supporting foreign keys, MySQL rejects any *Note `INSERT': insert. or *Note `UPDATE': 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 *Note `UPDATE': update. or *Note `DELETE': 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*: Currently, 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 *Note `InnoDB': innodb-storage-engine. rejects 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. * 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 *Note `ALTER TABLE': 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 *Note `ALTER TABLE': alter-table, _remember to create the required indexes first._ * Dropping Foreign Keys * You can also use *Note `ALTER TABLE': 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 *Note `SHOW CREATE TABLE': 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`; You cannot add a foreign key and drop a foreign key in the same *Note `ALTER TABLE': alter-table. statement. A separate statements is required for each operation. If an *Note `ALTER TABLE': alter-table. statement results in changes to column values (for example, because a column is truncated), MySQL's foreign key constraint checks do not notice possible violations caused by changing the values. * 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 *Note `SHOW CREATE TABLE': show-create-table. statement: SHOW CREATE TABLE TBL_NAME; You can also obtain information about foreign keys by querying the *Note `INFORMATION_SCHEMA.KEY_COLUMN_USAGE': key-column-usage-table. table. *Note `mysqldump': 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, *Note `mysqldump': 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 *Note `LOAD DATA': load-data. and *Note `ALTER TABLE': 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, *Note `ALTER TABLE': 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 *Note `DROP TABLE': 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 *Note `ALTER TABLE': 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 *Note `SHOW ENGINE INNODB STATUS': show-engine. *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 *Note `UPDATE': update. or `DELETE CASCADE'. You are advised to use foreign keys that reference only `UNIQUE' (including `PRIMARY') and `NOT NULL' keys. Furthermore, MySQL does not recognize or support `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 *Note `MyISAM': myisam-storage-engine.), MySQL Server parses and ignores foreign key specifications.  File: manual.info, Node: silent-column-changes, Prev: create-table-foreign-keys, Up: create-table 13.1.17.3 Silent Column Specification Changes ............................................. In some cases, MySQL silently changes column specifications from those given in a *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': 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 *Note column-count-limit::. * *Note `TIMESTAMP': datetime. display sizes are discarded. Also note that *Note `TIMESTAMP': datetime. columns are `NOT NULL' by default. * Columns that are part of a `PRIMARY KEY' are made `NOT NULL' even if not declared that way. * Trailing spaces are automatically deleted from *Note `ENUM': enum. and *Note `SET': set. member values when the table is created. * MySQL maps certain data types used by other SQL database vendors to MySQL types. See *Note 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 *Note `VARCHAR': char. column with a length specification greater than 65535 is converted to *Note `TEXT': blob, and a *Note `VARBINARY': binary-varbinary. column with a length specification greater than 65535 is converted to *Note `BLOB': 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: *Note `CHAR': char. becomes *Note `BINARY': binary-varbinary, *Note `VARCHAR': char. becomes *Note `VARBINARY': binary-varbinary, and *Note `TEXT': blob. becomes *Note `BLOB': blob. For the *Note `ENUM': enum. and *Note `SET': 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 *Note `DESCRIBE': describe. or *Note `SHOW CREATE TABLE': show-create-table. statement after creating or altering the table. Certain other data type changes can occur if you compress a table using *Note `myisampack': myisampack. See *Note compressed-format::.  File: manual.info, Node: create-tablespace, Next: create-trigger, Prev: create-table, Up: sql-syntax-data-definition 13.1.18 `CREATE TABLESPACE' Syntax ---------------------------------- CREATE TABLESPACE TABLESPACE_NAME ADD DATAFILE 'FILE_NAME' 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 [=] COMMENT_TEXT] ENGINE [=] ENGINE_NAME This statement is used to create a tablespace, which can contain one or more data files, providing storage space for tables. 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 *Note `ALTER TABLESPACE': alter-tablespace. statement (see *Note alter-tablespace::). For rules covering the naming of tablespaces, see *Note identifiers::. *Note*: All MySQL 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. Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, path and file names for data files could not be longer than 128 characters. (Bug #31770) 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 *Note `CREATE LOGFILE GROUP': create-logfile-group. (see *Note create-logfile-group::). Multiple tablespaces may use the same log file group for `UNDO' logging. The `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' 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 *Note `INFORMATION_SCHEMA.FILES': files-table. table, and so derive an estimate for how much space remains free in the file. For further discussion and examples, see *Note files-table::. The `INITIAL_SIZE' parameter sets the data file's total size in bytes. Once the file has been created, its size cannot be changed; however, you can add more data files to the tablespace using `ALTER TABLESPACE ... ADD DATAFILE'. See *Note alter-tablespace::. `INITIAL_SIZE' is optional; its default value is `128M'. On 32-bit systems, the maximum supported value for `INITIAL_SIZE' is `4G'. (Bug #29186) When setting `EXTENT_SIZE' or `INITIAL_SIZE' (either or both), 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', `EXTENT_SIZE', and `UNDO_BUFFER_SIZE' are subject to rounding as follows: * `EXTENT_SIZE' and `UNDO_BUFFER_SIZE' are each rounded up to the nearest whole multiple of 32K. * `INITIAL_SIZE' is rounded _down_ to the nearest whole multiple of 32K. For data files, _INITIAL_SIZE_ is subject to further rounding; the result just obtained is rounded up to the nearest whole multiple of `EXTENT_SIZE' (after any rounding). The rounding just described has always (since Disk Data tablespaces were introduced in MySQL 5.1.6) been performed implicitly, but beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.32, MySQL Cluster NDB 7.0.13, and MySQL Cluster NDB 7.1.2, this rounding 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 *Note `INFORMATION_SCHEMA.FILES': files-table. 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. `AUTOEXTEND_SIZE', `MAX_SIZE', `NODEGROUP', `WAIT', and `COMMENT' are parsed but ignored, and so currently have no effect. These options are intended for future expansion. The `ENGINE' parameter determines the storage engine which uses this tablespace, with ENGINE_NAME being the name of the storage engine. In MySQL 5.1, ENGINE_NAME must be one of the values *Note `NDB': mysql-cluster. or *Note `NDBCLUSTER': mysql-cluster. When *Note `CREATE TABLESPACE': 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 *Note `INFORMATION_SCHEMA.FILES': files-table. table. For example: 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 | +--------------------+-------------+----------------+ 2 rows in set (0.01 sec) (See *Note files-table::.) *Note `CREATE TABLESPACE': create-tablespace. was added in MySQL 5.1.6. In MySQL 5.1, it is useful only with Disk Data storage for MySQL Cluster. See *Note mysql-cluster-disk-data::.  File: manual.info, Node: create-trigger, Next: create-view, Prev: create-tablespace, Up: sql-syntax-data-definition 13.1.19 `CREATE TRIGGER' Syntax ------------------------------- CREATE [DEFINER = { USER | CURRENT_USER }] TRIGGER TRIGGER_NAME TRIGGER_TIME TRIGGER_EVENT ON TBL_NAME FOR EACH ROW TRIGGER_BODY TRIGGER_TIME: { BEFORE | AFTER } TRIGGER_EVENT: { INSERT | UPDATE | DELETE } 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 *Note `CREATE TRIGGER': create-trigger. syntax. For additional discussion, see *Note trigger-syntax::. *Note `CREATE TRIGGER': 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, *Note `CREATE TRIGGER': create-trigger. might require the `SUPER' privilege, as described in *Note stored-programs-logging::. (Before MySQL 5.1.6, there is no `TRIGGER' privilege and this statement requires the `SUPER' privilege in all cases.) 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. TRIGGER_EVENT indicates the kind of operation that activates the trigger. These TRIGGER_EVENT values are permitted: * *Note `INSERT': insert.: The trigger activates whenever a new row is inserted into the table; for example, through *Note `INSERT': insert, *Note `LOAD DATA': load-data, and *Note `REPLACE': replace. statements. * *Note `UPDATE': update.: The trigger activates whenever a row is modified; for example, through *Note `UPDATE': update. statements. * *Note `DELETE': delete.: The trigger activates whenever a row is deleted from the table; for example, through *Note `DELETE': delete. and *Note `REPLACE': replace. statements. *Note `DROP TABLE': drop-table. and *Note `TRUNCATE TABLE': truncate-table. statements on the table do _not_ activate this trigger, because they do not use *Note `DELETE': delete. Dropping a partition does not activate *Note `DELETE': 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 *Note `INSERT': insert. trigger activates not only for *Note `INSERT': insert. statements but also *Note `LOAD DATA': 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. 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. But you can have a `BEFORE UPDATE' and a `BEFORE INSERT' trigger, or a `BEFORE UPDATE' and an `AFTER UPDATE' trigger. TRIGGER_BODY is the statement to execute when the trigger activates. To execute multiple statements, use the *Note `BEGIN ... END': begin-end. compound statement construct. This also enables you to use the same statements that are permissible within stored routines. See *Note begin-end::. Some statements are not permitted in triggers; see *Note 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. 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'' (the same format used in the *Note `GRANT': grant. statement), `CURRENT_USER', or `CURRENT_USER()'. The default `DEFINER' value is the user who executes the *Note `CREATE TRIGGER': 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 actually 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. Note: Prior to MySQL 5.1.6, *Note `CREATE TRIGGER': create-trigger. always requires the `SUPER' privilege, so only the second of the preceding rules applies. MySQL takes the `DEFINER' user into account when checking trigger privileges as follows: * At *Note `CREATE TRIGGER': create-trigger. time, the user who issues the statement must have the `TRIGGER' privilege. (`SUPER' prior to MySQL 5.1.6.) * At trigger activation time, privileges are checked against the `DEFINER' user. This user must have these privileges: * The `TRIGGER' privilege. (`SUPER' prior to MySQL 5.1.6.) * 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 *Note 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 *Note account-activity-auditing::. If you use *Note `LOCK TABLES': lock-tables. to lock a table that has triggers, the tables used within the trigger are also locked, as described in *Note lock-tables-and-triggers::. For additional discussion of trigger use, see *Note trigger-syntax::.  File: manual.info, Node: create-view, Next: drop-database, Prev: create-trigger, Up: sql-syntax-data-definition 13.1.20 `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 *Note `CREATE VIEW': create-view. statement creates a new view, or replaces an existing one if the `OR REPLACE' clause is given. If the view does not exist, *Note `CREATE OR REPLACE VIEW': create-view. is the same as *Note `CREATE VIEW': create-view. If the view does exist, *Note `CREATE OR REPLACE VIEW': create-view. is the same as *Note `ALTER VIEW': alter-view. The SELECT_STATEMENT is a *Note `SELECT': select. statement that provides the definition of the view. (When you select from the view, you select in effect using the *Note `SELECT': select. statement.) SELECT_STATEMENT can select from base tables or other views. The view definition is `frozen' at creation time, so changes to the underlying tables afterward do not affect the view definition. 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. 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 *Note `CREATE VIEW': create-view. statement requires the `CREATE VIEW' privilege for the view, and some privilege for each column selected by the *Note `SELECT': select. statement. For columns used elsewhere in the *Note `SELECT': 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. *Note `CREATE 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, specify the name as DB_NAME.VIEW_NAME when you create it: mysql> CREATE VIEW test.v AS SELECT * FROM t; 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 *Note `SELECT': select. statement can be simple references to table columns. They can also be expressions that use functions, constant values, operators, and so forth. Views must have unique column names with no duplicates, just like base tables. By default, the names of the columns retrieved by the *Note `SELECT': select. statement are used for the view column names. To define explicit names for the view columns, the optional COLUMN_LIST clause can be given 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 *Note `SELECT': select. statement. *Note*: Prior to MySQL 5.1.29, when you modify an existing view, the server saves a backup of the current view definition under the view database directory, in a subdirectory named `arc'. The backup file for a view `v' is named `v.frm-00001'. If you alter the view again, the next backup is named `v.frm-00002'. The three latest view backup definitions are stored. Backed up view definitions are not preserved by *Note `mysqldump': mysqldump, or any other such programs, but you can retain them using a file copy operation. However, they are not needed for anything but to provide you with a backup of your previous view definition. It is safe to remove these backup definitions, but only while *Note `mysqld': mysqld. is not running. If you delete the `arc' subdirectory or its files while *Note `mysqld': mysqld. is running, an error occurs the next time you try to alter the view: mysql> ALTER VIEW v AS SELECT * FROM t; ERROR 6 (HY000): Error on delete of '.\test\arc/v.frm-0004' (Errcode: 2) Unqualified table or view names in the *Note `SELECT': select. statement are 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 proper database name. A view can be created from many kinds of *Note `SELECT': select. statements. It can refer to base tables or other views. It can use joins, *Note `UNION': union, and subqueries. The *Note `SELECT': 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); 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 *Note `SELECT': select. statement cannot contain a subquery in the `FROM' clause. * The *Note `SELECT': select. statement cannot refer to system or user variables. * Within a stored program, the definition cannot refer to program parameters or local variables. * The *Note `SELECT': select. statement cannot refer to prepared statement parameters. * Any table or view referred to in the definition must exist. However, after a view has been created, it is possible to drop a table or view that the definition refers to. In this case, use of the view results in an error. To check a view definition for problems of this kind, use the *Note `CHECK TABLE': check-table. statement. * The definition cannot refer to a `TEMPORARY' table, and you cannot create a `TEMPORARY' view. * Any tables named in the view definition must exist at definition time. * You cannot associate a trigger with a view. * As of MySQL 5.1.23, aliases for column names in the *Note `SELECT': 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 *Note `SELECT': select. keyword, and to clauses such as `INTO', `FOR UPDATE', `LOCK IN SHARE MODE', and `PROCEDURE'. If you create a view and then change the query processing environment by changing system variables, that may affect the results that you get from the view: 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. These clauses were added in MySQL 5.1.2. The valid `SQL SECURITY' characteristic values are `DEFINER' and `INVOKER'. These indicate that the required privileges must be held by the user who defined or invoked the view, respectively. The default `SQL SECURITY' value is `DEFINER'. If a USER value is given for the `DEFINER' clause, it should be a MySQL account specified as `'USER_NAME'@'HOST_NAME'' (the same format used in the *Note `GRANT': grant. statement), `CURRENT_USER', or `CURRENT_USER()'. The default `DEFINER' value is the user who executes the *Note `CREATE VIEW': create-view. 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 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 actually 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 *Note stored-programs-security::. Within a view definition, `CURRENT_USER' returns the view's `DEFINER' value by default as of MySQL 5.1.12. For older versions, and 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 *Note 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'. As of MySQL 5.1.2 (when the `DEFINER' and `SQL SECURITY' clauses were implemented), view privileges are checked 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. Prior to MySQL 5.1.2 (before the `DEFINER' and `SQL SECURITY' clauses were implemented), privileges required for objects used in a view are checked at view creation time. 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. If you invoke a view that was created before MySQL 5.1.2, it is treated as though it was created with a `SQL SECURITY DEFINER' characteristic and with a `DEFINER' value that is the same as your account. However, because the actual definer is unknown, MySQL issues a warning. To eliminate the warning, it is sufficient to re-create the view so that the view definition includes a `DEFINER' clause. 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'. The default algorithm is `UNDEFINED' if no `ALGORITHM' clause is present. For more information, see *Note view-algorithms::. Some views are updatable. That is, you can use them in statements such as *Note `UPDATE': update, *Note `DELETE': delete, or *Note `INSERT': 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. 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 *Note view-updatability::.  File: manual.info, Node: drop-database, Next: drop-event, Prev: create-view, Up: sql-syntax-data-definition 13.1.21 `DROP DATABASE' Syntax ------------------------------ DROP {DATABASE | SCHEMA} [IF EXISTS] DB_NAME *Note `DROP DATABASE': drop-database. drops all tables in the database and deletes the database. Be _very_ careful with this statement! To use *Note `DROP DATABASE': drop-database, you need the `DROP' privilege on the database. *Note `DROP SCHEMA': drop-database. is a synonym for *Note `DROP DATABASE': drop-database. *Important*: When a database is dropped, user privileges on the database are _not_ automatically dropped. See *Note 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 *Note `DROP DATABASE': drop-database. on a symbolically linked database, both the link and the original database are deleted. *Note `DROP DATABASE': drop-database. returns the number of tables that were removed. This corresponds to the number of `.frm' files removed. The *Note `DROP DATABASE': 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. The *Note `DROP DATABASE': drop-database. statement removes files with extension types shown in this table. Extensions are listed in alphabetical order from left to right. `.BAK' `.DAT' `.HSH' `.MRG' `.MYD' `.MYI' `.TRG' `.TRN' `.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 *Note `DROP DATABASE': drop-database. statement again. You can also drop databases with *Note `mysqladmin': mysqladmin. See *Note mysqladmin::.  File: manual.info, Node: drop-event, Next: drop-function, Prev: drop-database, Up: sql-syntax-data-definition 13.1.22 `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'. Beginning with MySQL 5.1.12, this statement requires the `EVENT' privilege for the schema to which the event to be dropped belongs. (In MySQL 5.1.11 and earlier, an event could be dropped only by its definer, or by a user having the `SUPER' privilege.)  File: manual.info, Node: drop-function, Next: drop-index, Prev: drop-event, Up: sql-syntax-data-definition 13.1.23 `DROP FUNCTION' Syntax ------------------------------ The *Note `DROP FUNCTION': drop-function. statement is used to drop stored functions and user-defined functions (UDFs): * For information about dropping stored functions, see *Note drop-procedure::. * For information about dropping user-defined functions, see *Note drop-function-udf::.  File: manual.info, Node: drop-index, Next: drop-logfile-group, Prev: drop-function, Up: sql-syntax-data-definition 13.1.24 `DROP INDEX' Syntax --------------------------- DROP [ONLINE|OFFLINE] INDEX INDEX_NAME ON TBL_NAME *Note `DROP INDEX': drop-index. drops the index named INDEX_NAME from the table TBL_NAME. This statement is mapped to an *Note `ALTER TABLE': alter-table. statement to drop the index. See *Note 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; Beginning with MySQL 5.1.17, indexes on variable-width columns of *Note `NDBCLUSTER': mysql-cluster. tables are dropped online; that is, without any table copying. The table is not locked against access from other MySQL 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. In standard MySQL 5.1 releases, it is not possible to override the server when it determines that an index is to be dropped without table copying. In MySQL Cluster, you can drop indexes offline (which causes the table to be locked for all API nodes in the cluster) using the `OFFLINE' keyword. The rules and limitations governing `DROP OFFLINE INDEX' and `DROP ONLINE INDEX' are the same as for `ALTER OFFLINE TABLE ... DROP INDEX' and `ALTER ONLINE TABLE ... DROP INDEX'. You cannot cause the noncopying dropping of an index that would normally be dropped offline by using the `ONLINE' keyword: If it is not possible to perform the `DROP' operation without table copying, the server ignores the `ONLINE' keyword. For more information, see *Note alter-table-online-operations::. *Note*: The `ONLINE' and `OFFLINE' keywords are available only in MySQL Cluster NDB 6.2.5, 6.3.2, and later MySQL Cluster releases; attempting to use these keywords in earlier MySQL Cluster releases or standard MySQL 5.1 releases results in a syntax error.  File: manual.info, Node: drop-logfile-group, Next: drop-procedure, Prev: drop-index, Up: sql-syntax-data-definition 13.1.25 `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 *Note 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. In MySQL 5.1, the only permitted values for ENGINE_NAME are *Note `NDB': mysql-cluster. and *Note `NDBCLUSTER': mysql-cluster. *Note `DROP LOGFILE GROUP': drop-logfile-group. was added in MySQL 5.1.6. In MySQL 5.1, it is useful only with Disk Data storage for MySQL Cluster. See *Note mysql-cluster-disk-data::.  File: manual.info, Node: drop-procedure, Next: drop-server, Prev: drop-logfile-group, Up: sql-syntax-data-definition 13.1.26 `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 *Note 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 *Note `SHOW WARNINGS': show-warnings. *Note `DROP FUNCTION': drop-function. is also used to drop user-defined functions (see *Note drop-function-udf::).  File: manual.info, Node: drop-server, Next: drop-table, Prev: drop-procedure, Up: sql-syntax-data-definition 13.1.27 `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 *Note create-server::. `DROP SERVER' does not cause an automatic commit. In MySQL 5.1, `DROP SERVER' is written to the binary log only when using row-based logging. It is not logged when `binlog_format' is equal to `STATEMENT' or `MIXED'. *Note `DROP SERVER': drop-server. was added in MySQL 5.1.15.  File: manual.info, Node: drop-table, Next: drop-tablespace, Prev: drop-server, Up: sql-syntax-data-definition 13.1.28 `DROP TABLE' Syntax --------------------------- DROP [TEMPORARY] TABLE [IF EXISTS] TBL_NAME [, TBL_NAME] ... [RESTRICT | CASCADE] *Note `DROP TABLE': drop-table. removes one or more tables. You must have the `DROP' privilege for each table. All table data and the table definition are _removed_, so _be careful_ with this statement! If any of the tables named in the argument list do not exist, MySQL returns an error indicating by name which nonexisting tables it was unable to drop, but it also drops all of the tables in the list that do exist. *Important*: When a table is dropped, user privileges on the table are _not_ automatically dropped. See *Note grant::. Note that for a partitioned table, *Note `DROP TABLE': drop-table. permanently removes the table definition, all of its partitions, and all of the data which was stored in those partitions. It also removes the partitioning definition (`.par') file associated with the dropped table. Use `IF EXISTS' to prevent an error from occurring for tables that do not exist. A `NOTE' is generated for each nonexistent table when using `IF EXISTS'. See *Note show-warnings::. `RESTRICT' and `CASCADE' are permitted to make porting easier. In MySQL 5.1, they do nothing. *Note*: *Note `DROP TABLE': drop-table. automatically commits the current active transaction, unless you use the `TEMPORARY' keyword. The `TEMPORARY' keyword has the following effects: * The statement drops only `TEMPORARY' tables. * The statement does not end an ongoing transaction. * No access rights are checked. (A `TEMPORARY' table is visible only to 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.  File: manual.info, Node: drop-tablespace, Next: drop-trigger, Prev: drop-table, Up: sql-syntax-data-definition 13.1.29 `DROP TABLESPACE' Syntax -------------------------------- DROP TABLESPACE TABLESPACE_NAME ENGINE [=] ENGINE_NAME This statement drops a tablespace that was previously created using *Note `CREATE TABLESPACE': create-tablespace. (see *Note create-tablespace::). *Important*: The tablespace to be dropped must not contain any data files; in other words, before you can drop a tablespace, you must first drop each of its data files using `ALTER TABLESPACE ... DROP DATAFILE' (see *Note alter-tablespace::). The `ENGINE' clause (required) specifies the storage engine used by the tablespace. In MySQL 5.1, the only accepted values for ENGINE_NAME are *Note `NDB': mysql-cluster. and *Note `NDBCLUSTER': mysql-cluster. *Note `DROP TABLESPACE': drop-tablespace. was added in MySQL 5.1.6. In MySQL 5.1, it is useful only with Disk Data storage for MySQL Cluster. See *Note mysql-cluster-disk-data::.  File: manual.info, Node: drop-trigger, Next: drop-view, Prev: drop-tablespace, Up: sql-syntax-data-definition 13.1.30 `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. *Note `DROP TRIGGER': drop-trigger. requires the `TRIGGER' privilege for the table associated with the trigger. (This statement requires the `SUPER' privilege prior to MySQL 5.1.6.) 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 *Note show-warnings::. The `IF EXISTS' clause was added in MySQL 5.1.14. Triggers for a table are also dropped if you drop the table. *Note*: When upgrading from a version of MySQL older than MySQL 5.0.10 to 5.0.10 or newer--including all MySQL 5.1 releases--you must drop all triggers and re-create them. Otherwise, *Note `DROP TRIGGER': drop-trigger. does not work for older triggers after the upgrade. See *Note upgrading-from-previous-series::, for a suggested upgrade procedure.  File: manual.info, Node: drop-view, Next: rename-database, Prev: drop-trigger, Up: sql-syntax-data-definition 13.1.31 `DROP VIEW' Syntax -------------------------- DROP VIEW [IF EXISTS] VIEW_NAME [, VIEW_NAME] ... [RESTRICT | CASCADE] *Note `DROP VIEW': drop-view. removes one or more views. You must have the `DROP' privilege for each view. If any of the views named in the argument list do not exist, MySQL returns an error indicating by name which nonexisting views it was unable to drop, but it also drops all of the views in the list that do exist. 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 *Note show-warnings::. `RESTRICT' and `CASCADE', if given, are parsed and ignored.  File: manual.info, Node: rename-database, Next: rename-table, Prev: drop-view, Up: sql-syntax-data-definition 13.1.32 `RENAME DATABASE' Syntax -------------------------------- RENAME {DATABASE | SCHEMA} DB_NAME TO NEW_DB_NAME; This statement was added in MySQL 5.1.7 but was found to be dangerous and was removed in MySQL 5.1.23. It was intended to enable upgrading pre-5.1 databases to use the encoding implemented in 5.1 for mapping database names to database directory names (see *Note identifier-mapping::). However, use of this statement could result in loss of database contents, which is why it was removed. Do not use `RENAME DATABASE' in earlier versions in which it is present. To perform the task of upgrading database names with the new encoding, use `ALTER DATABASE DB_NAME UPGRADE DATA DIRECTORY NAME' instead (see *Note alter-database::).  File: manual.info, Node: rename-table, Next: truncate-table, Prev: rename-database, Up: sql-syntax-data-definition 13.1.33 `RENAME TABLE' Syntax ----------------------------- RENAME TABLE TBL_NAME TO NEW_TBL_NAME [, TBL_NAME2 TO NEW_TBL_NAME2] ... This statement renames one or more tables. The rename operation is done atomically, which means that no other session can access any of the tables while the rename is running. For example, if you have an existing table `old_table', you can create another table `new_table' that has the same structure but is empty, and then replace the existing table with the empty one as follows (assuming that `backup_table' does not already exist): CREATE TABLE new_table (...); RENAME TABLE old_table TO backup_table, new_table TO old_table; If the statement renames more than one table, renaming operations are done from left to right. If you want to swap two table names, you can do so like this (assuming that `tmp_table' does not already exist): RENAME TABLE old_table TO tmp_table, new_table TO old_table, tmp_table TO new_table; As long as two databases are on the same file system, you can use *Note `RENAME TABLE': rename-table. to move a table from one database to another: RENAME TABLE CURRENT_DB.TBL_NAME TO OTHER_DB.TBL_NAME; If there are any triggers associated with a table which is moved to a different database using *Note `RENAME TABLE': rename-table, then the statement fails with the error `Trigger in wrong schema'. *Note `RENAME TABLE': rename-table. also works for views, as long as you do not try to rename a view into a different database. Any privileges granted specifically for the renamed table or view are not migrated to the new name. They must be changed manually. When you execute `RENAME', you cannot have any locked tables or active transactions. You must also have the `ALTER' and `DROP' privileges on the original table, and the `CREATE' and `INSERT' privileges on the new table. If MySQL encounters any errors in a multiple-table rename, it does a reverse rename for all renamed tables to return everything to its original state. You cannot use `RENAME' to rename a `TEMPORARY' table. However, you can use *Note `ALTER TABLE': alter-table. instead: mysql> ALTER TABLE orig_name RENAME new_name;  File: manual.info, Node: truncate-table, Prev: rename-table, Up: sql-syntax-data-definition 13.1.34 `TRUNCATE TABLE' Syntax ------------------------------- TRUNCATE [TABLE] TBL_NAME *Note `TRUNCATE TABLE': truncate-table. empties a table completely. It requires the `DROP' privilege as of MySQL 5.1.16. (Before 5.1.16, it requires the `DELETE' privilege). Logically, *Note `TRUNCATE TABLE': truncate-table. is equivalent to a *Note `DELETE': delete. statement that deletes all rows, but there are practical differences under some circumstances. For an `InnoDB' table: * If there are no `FOREIGN KEY' constraints, `InnoDB' performs fast truncation by dropping the original table and creating an empty one with the same definition, which is much faster than deleting rows one by one. * When you use this fast truncation technique with the `innodb_file_per_table' option enabled, the operating system can reuse the freed disk space. For users of the InnoDB Plugin, the space is reclaimed automatically, as described in `TRUNCATE TABLE' Reclaims Space (http://dev.mysql.com/doc/refman/5.5/en/innodb-other-changes-truncate.html). If you do not have the InnoDB Plugin installed, issue the *Note `OPTIMIZE TABLE': optimize-table. statement to free the disk space for the table. * If there are any `FOREIGN KEY' constraints that reference the table, `InnoDB' processes *Note `TRUNCATE TABLE': truncate-table. by deleting rows one by one, processing the constraints as it proceeds. If the `FOREIGN KEY' constraint specifies `DELETE CASCADE', rows from the child (referenced) table are deleted, and the truncated table becomes empty. If the `FOREIGN KEY' constraint does _not_ specify `CASCADE', the *Note `TRUNCATE TABLE': truncate-table. statement deletes rows one by one and stops if it encounters a parent row that is referenced by the child, returning this error: ERROR 1451 (23000): Cannot delete or update a parent row: a foreign key constraint fails (`test`.`child`, CONSTRAINT `child_ibfk_1` FOREIGN KEY (`parent_id`) REFERENCES `parent` (`id`)) *Note*: In MySQL 5.5 and higher, *Note `TRUNCATE TABLE': truncate-table. is not allowed for `InnoDB' tables referenced by foreign keys. For ease of upgrading, rewrite such statements to use `DELETE' instead. * The `AUTO_INCREMENT' counter is reset to zero by *Note `TRUNCATE TABLE': truncate-table, regardless of whether there is a `FOREIGN KEY' constraint. This is the same as a *Note `DELETE': delete. statement with no `WHERE' clause. The count of rows affected by *Note `TRUNCATE TABLE': truncate-table. is accurate only when it is mapped to a *Note `DELETE': delete. statement. For other storage engines, *Note `TRUNCATE TABLE': truncate-table. differs from *Note `DELETE': delete. in the following ways in MySQL 5.1: * 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. * Truncation operations cannot be performed if the session holds an active table lock. * 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 *Note `TRUNCATE TABLE': truncate-table, even if the data or index files have become corrupted. * The table handler does not remember the last used `AUTO_INCREMENT' value, but starts counting from the beginning. This is true even for `MyISAM' and `InnoDB', which normally do not reuse sequence values. * When used with partitioned tables, *Note `TRUNCATE TABLE': 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. * Since truncation of a table does not make any use of *Note `DELETE': delete, the *Note `TRUNCATE TABLE': truncate-table. statement does not invoke `ON DELETE' triggers. As of MySQL 5.1.39, *Note `TRUNCATE TABLE': truncate-table. for a table closes all handlers for the table that were opened with *Note `HANDLER OPEN': handler. Beginning with MySQL 5.1.32, *Note `TRUNCATE TABLE': truncate-table. is treated for purposes of binary logging and replication as *Note `DROP TABLE': drop-table. followed by *Note `CREATE TABLE': create-table.--that is, as DDL rather than DML. This is due to the fact that, when using *Note `InnoDB': innodb-storage-engine. 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 *Note `InnoDB': innodb-storage-engine. in the manner described previously.  File: manual.info, Node: sql-syntax-data-manipulation, Next: sql-syntax-transactions, Prev: sql-syntax-data-definition, Up: sql-syntax 13.2 Data Manipulation Statements ================================= * Menu: * call:: `CALL' Syntax * delete:: `DELETE' Syntax * do:: `DO' Syntax * handler:: `HANDLER' Syntax * insert:: `INSERT' Syntax * load-data:: `LOAD DATA INFILE' Syntax * replace:: `REPLACE' Syntax * select:: `SELECT' Syntax * subqueries:: Subquery Syntax * update:: `UPDATE' Syntax  File: manual.info, Node: call, Next: delete, Prev: sql-syntax-data-manipulation, Up: sql-syntax-data-manipulation 13.2.1 `CALL' Syntax -------------------- CALL SP_NAME([PARAMETER[,...]]) CALL SP_NAME[()] The *Note `CALL': call. statement invokes a stored procedure that was defined previously with *Note `CREATE PROCEDURE': create-procedure. As of MySQL 5.1.13, stored procedures that take no arguments can be invoked without parentheses. That is, `CALL p()' and `CALL p' are equivalent. *Note `CALL': 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 *Note `mysql_affected_rows()': 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.1.32-log | 11 | +------------+------------+ In prepared *Note `CALL': call. statements used with *Note `PREPARE': prepare. and *Note `EXECUTE': execute, placeholder support is available in MySQL 5.1 for `IN' parameters, but not for `OUT' or `INOUT' parameters. To work around this limitation for `OUT' and `INOUT' parameters, forego the use of placeholders; instead, refer to user variables in the *Note `CALL': call. statement itself and do not specify them in the *Note `EXECUTE': execute. statement: mysql> SET @increment = 10; mysql> PREPARE s FROM 'CALL p(@version, @increment)'; mysql> EXECUTE s; mysql> SELECT @version, @increment; +------------+------------+ | @version | @increment | +------------+------------+ | 5.1.32-log | 11 | +------------+------------+ To write C programs that use the *Note `CALL': call. SQL statement to execute stored procedures that produce result sets, the `CLIENT_MULTI_RESULTS' flag must be enabled. This is because each *Note `CALL': 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 *Note `CALL': 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 *Note `mysql_real_connect()': 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'). To process the result of a *Note `CALL': call. statement executed using *Note `mysql_query()': mysql-query. or *Note `mysql_real_query()': mysql-real-query, use a loop that calls *Note `mysql_next_result()': mysql-next-result. to determine whether there are more results. For an example, see *Note c-api-multiple-queries::. For programs written in a language that provides a MySQL interface, there is no native method for directly retrieving the results of `OUT' or `INOUT' parameters from *Note `CALL': call. statements. To get the parameter values, pass user-defined variables to the procedure in the *Note `CALL': call. statement and then execute a *Note `SELECT': select. statement to produce a result set containing the variable values. To handle an `INOUT' parameter, execute a statement prior to the *Note `CALL': call. that sets the corresponding user variable to the value to be passed to the procedure. The following example illustrates the technique (without error checking) for the stored procedure `p' described earlier that has an `OUT' parameter and an `INOUT' parameter: mysql_query(mysql, "SET @increment = 10"); mysql_query(mysql, "CALL p(@version, @increment)"); mysql_query(mysql, "SELECT @version, @increment"); result = mysql_store_result(mysql); row = mysql_fetch_row(result); mysql_free_result(result); After the preceding code executes, `row[0]' and `row[1]' contain the values of `@version' and `@increment', respectively.  File: manual.info, Node: delete, Next: do, Prev: call, Up: sql-syntax-data-manipulation 13.2.2 `DELETE' Syntax ---------------------- Single-table syntax: DELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROM TBL_NAME [WHERE WHERE_CONDITION] [ORDER BY ...] [LIMIT ROW_COUNT] Multiple-table syntax: DELETE [LOW_PRIORITY] [QUICK] [IGNORE] TBL_NAME[.*] [, TBL_NAME[.*]] ... FROM TABLE_REFERENCES [WHERE WHERE_CONDITION] Or: DELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROM TBL_NAME[.*] [, TBL_NAME[.*]] ... USING TABLE_REFERENCES [WHERE WHERE_CONDITION] For the single-table syntax, the *Note `DELETE': delete. statement deletes rows from TBL_NAME and returns a count of the number of deleted rows. This count can be obtained by calling the `ROW_COUNT()' function (see *Note information-functions::). The `WHERE' clause, if given, specifies the conditions that identify which rows to delete. With no `WHERE' clause, all rows are deleted. 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. For the multiple-table syntax, *Note `DELETE': delete. deletes from each TBL_NAME the rows that satisfy the conditions. In this case, `ORDER BY' and `LIMIT' cannot be used. WHERE_CONDITION is an expression that evaluates to true for each row to be deleted. It is specified as described in *Note select::. Currently, you cannot delete from a table and select from the same table in a subquery. 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. As stated, a *Note `DELETE': delete. statement with no `WHERE' clause deletes all rows. A faster way to do this, when you do not need to know the number of deleted rows, is to use *Note `TRUNCATE TABLE': truncate-table. However, within a transaction or if you have a lock on the table, *Note `TRUNCATE TABLE': truncate-table. cannot be used whereas *Note `DELETE': delete. can. See *Note truncate-table::, and *Note lock-tables::. 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 *Note 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 *Note example-auto-increment::. The *Note `DELETE': delete. statement supports the following modifiers: * If you specify `LOW_PRIORITY', the server delays execution of the *Note `DELETE': 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' keyword, the storage engine does not merge index leaves during delete, which may speed up some kinds of delete operations. * The `IGNORE' keyword causes MySQL to ignore all 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. The speed of delete operations may also be affected by factors discussed in *Note delete-speed::. In `MyISAM' tables, deleted rows are maintained in a linked list and subsequent *Note `INSERT': insert. operations reuse old row positions. To reclaim unused space and reduce file sizes, use the *Note `OPTIMIZE TABLE': optimize-table. statement or the *Note `myisamchk': myisamchk. utility to reorganize tables. *Note `OPTIMIZE TABLE': optimize-table. is easier to use, but *Note `myisamchk': myisamchk. is faster. See *Note optimize-table::, and *Note 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 *Note `DELETE': 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 *Note `OPTIMIZE TABLE': optimize-table. If you are going to delete many rows from a table, it might be faster to use `DELETE QUICK' followed by *Note `OPTIMIZE TABLE': optimize-table. This rebuilds the index rather than performing many index block merge operations. The MySQL-specific `LIMIT ROW_COUNT' option to *Note `DELETE': delete. tells the server the maximum number of rows to be deleted before control is returned to the client. This can be used to ensure that a given *Note `DELETE': delete. statement does not take too much time. You can simply repeat the *Note `DELETE': delete. statement until the number of affected rows is less than the `LIMIT' value. If the *Note `DELETE': 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' may also be useful in some cases to delete rows in an order required to avoid referential integrity violations. 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 *Note `DELETE': 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 *Note `RENAME TABLE': 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 *Note `RENAME TABLE': rename-table. executes, so the rename operation is not subject to concurrency problems. See *Note rename-table::. You can specify multiple tables in a *Note `DELETE': delete. statement to delete rows from one or more tables depending on the particular condition in the `WHERE' clause. However, you cannot use `ORDER BY' or `LIMIT' in a multiple-table *Note `DELETE': delete. The TABLE_REFERENCES clause lists the tables involved in the join. Its syntax is described in *Note 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 *Note `DELETE': delete. statements can use other types of join permitted in *Note `SELECT': 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 *Note `DELETE': 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 *Note `DELETE': delete. should be declared only in the TABLE_REFERENCES part of the statement. 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; Declaration of aliases other than in the TABLE_REFERENCES part of the statement should be avoided because that can lead to ambiguous statements that have unexpected results such as deleting rows from the wrong table. This is such a statement: DELETE t1 AS a2 FROM t1 AS a1 INNER JOIN t2 AS a2; As of MySQL 5.1.23, alias declarations outside the TABLE_REFERENCES part of the statement are disallowed for the `USING' variant of multiple-table *Note `DELETE': delete. syntax. (In MySQL 5.5, alias declarations outside TABLE_REFERENCES are disallowed for all multiple-table *Note `DELETE': delete. statements.) For alias references in the list of tables from which to delete rows in a multiple-table delete, the default database is used unless one is specified explicitly. For example, if the default database is `db1', the following statement does not work because the unqualified alias reference `a2' is interpreted as having a database of `db1': DELETE a1, a2 FROM db1.t1 AS a1 INNER JOIN db2.t2 AS a2 WHERE a1.id=a2.id; To correctly match an alias that refers to a table outside the default database, you must explicitly qualify the reference with the name of the proper database: DELETE a1, db2.a2 FROM db1.t1 AS a1 INNER JOIN db2.t2 AS a2 WHERE a1.id=a2.id;  File: manual.info, Node: do, Next: handler, Prev: delete, Up: sql-syntax-data-manipulation 13.2.3 `DO' Syntax ------------------ DO EXPR [, EXPR] ... *Note `DO': do. executes the expressions but does not return any results. In most respects, *Note `DO': do. is shorthand for `SELECT EXPR, ...', but has the advantage that it is slightly faster when you do not care about the result. *Note `DO': do. is useful primarily with functions that have side effects, such as `RELEASE_LOCK()'.  File: manual.info, Node: handler, Next: insert, Prev: do, Up: sql-syntax-data-manipulation 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. 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 *Note `SELECT': select. statement. See *Note select::. `HANDLER ... CLOSE' closes a table that was opened with `HANDLER ... OPEN'. There are several reasons to use the `HANDLER' interface instead of normal *Note `SELECT': select. statements: * `HANDLER' is faster than *Note `SELECT': 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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_dirty_read) are permitted), so the storage engine can use optimizations that *Note `SELECT': select. does not normally permit. * `HANDLER' makes it easier to port to MySQL applications that use a low-level `ISAM'-like interface. * `HANDLER' enables you to traverse a database in a manner that is difficult (or even impossible) to accomplish with *Note `SELECT': 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 *Note `FLUSH TABLES': flush. or DDL statements on the handler's table. * The session in which the handler is open executes non-`HANDLER' statements that use tables. As of MySQL 5.1.39, *Note `TRUNCATE TABLE': truncate-table. for a table closes all handlers for the table that were opened with *Note `HANDLER OPEN': handler. `HANDLER' is not supported with partitioned tables.  File: manual.info, Node: insert, Next: load-data, Prev: handler, Up: sql-syntax-data-manipulation 13.2.5 `INSERT' Syntax ---------------------- * Menu: * insert-select:: `INSERT ... SELECT' Syntax * insert-delayed:: `INSERT DELAYED' Syntax * insert-on-duplicate:: `INSERT ... ON DUPLICATE KEY UPDATE' Syntax INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE] [INTO] TBL_NAME [(COL_NAME,...)] {VALUES | VALUE} ({EXPR | DEFAULT},...),(...),... [ ON DUPLICATE KEY UPDATE COL_NAME=EXPR [, COL_NAME=EXPR] ... ] Or: INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE] [INTO] TBL_NAME SET COL_NAME={EXPR | DEFAULT}, ... [ ON DUPLICATE KEY UPDATE COL_NAME=EXPR [, COL_NAME=EXPR] ... ] Or: INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE] [INTO] TBL_NAME [(COL_NAME,...)] SELECT ... [ ON DUPLICATE KEY UPDATE COL_NAME=EXPR [, COL_NAME=EXPR] ... ] *Note `INSERT': insert. inserts new rows into an existing table. The *Note `INSERT ... VALUES': insert. and *Note `INSERT ... SET': insert. forms of the statement insert rows based on explicitly specified values. The *Note `INSERT ... SELECT': insert-select. form inserts rows selected from another table or tables. *Note `INSERT ... SELECT': insert-select. is discussed further in *Note insert-select::. You can use *Note `REPLACE': replace. instead of *Note `INSERT': insert. to overwrite old rows. *Note `REPLACE': replace. is the counterpart to *Note `INSERT IGNORE': insert. in the treatment of new rows that contain unique key values that duplicate old rows: The new rows are used to replace the old rows rather than being discarded. See *Note replace::. TBL_NAME is the table into which rows should be inserted. The columns for which the statement provides values can be specified as follows: * You can provide a comma-separated list of column names following the table name. In this case, a value for each named column must be provided by the `VALUES' list or the *Note `SELECT': select. statement. * If you do not specify a list of column names for *Note `INSERT ... VALUES': insert. or *Note `INSERT ... SELECT': insert-select, values for every column in the table must be provided by the `VALUES' list or the *Note `SELECT': select. statement. If you do not know the order of the columns in the table, use `DESCRIBE TBL_NAME' to find out. * The `SET' clause indicates the column names explicitly. Column values can be given in several ways: * If you are not running in strict SQL mode, 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 *Note data-type-defaults::. See also *Note constraint-invalid-data::. If you want an *Note `INSERT': insert. statement to generate an error unless you explicitly specify values for all columns that do not have a default value, you should use strict mode. See *Note server-sql-mode::. * Use the keyword `DEFAULT' to set a column explicitly to its default value. This makes it easier to write *Note `INSERT': 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 would have to write out the list of column names corresponding to each value in the `VALUES' list. You can also use `DEFAULT(COL_NAME)' as a more general form that can be used in expressions to produce a given column's default value. * If both the column list and the `VALUES' list are empty, *Note `INSERT': insert. creates a row with each column set to its default value: INSERT INTO TBL_NAME () VALUES(); In strict mode, an error occurs if any column doesn't have a default value. Otherwise, MySQL uses the implicit default value for any column that does not have an explicitly defined default. * You can specify an expression EXPR to provide a column value. This might involve type conversion if the type of the expression does not match the type of the column, and conversion of a given value can result in different inserted values depending on the data type. For example, inserting the string `'1999.0e-2'' into an *Note `INT': integer-types, *Note `FLOAT': floating-point-types, `DECIMAL(10,6)', or *Note `YEAR': year. column results in the values `1999', `19.9921', `19.992100', and `1999' being inserted, respectively. The reason the value stored in the *Note `INT': integer-types. and *Note `YEAR': year. columns is `1999' is that the string-to-integer conversion looks only at as much of the initial part of the string as may be considered a valid integer or year. For the floating-point and fixed-point columns, the string-to-floating-point conversion considers the entire string a valid floating-point 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); One exception involves columns that contain `AUTO_INCREMENT' values. Because the `AUTO_INCREMENT' value is generated after other value assignments, any reference to an `AUTO_INCREMENT' column in the assignment returns a `0'. *Note `INSERT': insert. statements that use `VALUES' syntax can insert multiple rows. To do this, include multiple lists of column values, each 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); The values list for each row must be enclosed within parentheses. The following statement is illegal because the number of values in the list does not match the number of column names: 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, and either may be used whether there is a single values list or multiple lists. The affected-rows value for an *Note `INSERT': insert. can be obtained using the `ROW_COUNT()' function (see *Note information-functions::), or the *Note `mysql_affected_rows()': mysql-affected-rows. C API function (see *Note mysql-affected-rows::). If you use an *Note `INSERT ... VALUES': insert. statement with multiple value lists or *Note `INSERT ... SELECT': insert-select, the statement returns an information string in this format: Records: 100 Duplicates: 0 Warnings: 0 `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 *Note `INSERT': insert. statements or *Note `INSERT INTO ... SELECT': insert-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. *Note `INSERT INTO ... SELECT': insert-select. statements are handled the same way as multiple-row inserts because the server does not examine the result set from the *Note `SELECT': select. to see whether it returns a single row. (For a single-row *Note `INSERT': 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 (*Note `CHAR': char, *Note `VARCHAR': char, *Note `TEXT': blob, or *Note `BLOB': 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 you are using the C API, the information string can be obtained by invoking the *Note `mysql_info()': mysql-info. function. See *Note mysql-info::. If *Note `INSERT': 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 SQL `LAST_INSERT_ID()' function. From within the C API, use the *Note `mysql_insert_id()': mysql-insert-id. function. However, you should note that the two functions do not always behave identically. The behavior of *Note `INSERT': insert. statements with respect to `AUTO_INCREMENT' columns is discussed further in *Note information-functions::, and *Note mysql-insert-id::. The *Note `INSERT': insert. statement supports the following modifiers: * If you use the `DELAYED' keyword, the server puts the row or rows to be inserted into a buffer, and the client issuing the *Note `INSERT DELAYED': insert-delayed. statement can then continue immediately. If the table is in use, the server holds the rows. When the table is free, the server begins inserting rows, checking periodically to see whether there are any new read requests for the table. If there are, the delayed row queue is suspended until the table becomes free again. See *Note insert-delayed::. `DELAYED' is ignored with *Note `INSERT ... SELECT': insert-select. or *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. Beginning with MySQL 5.1.19, `DELAYED' is also disregarded for an *Note `INSERT': insert. that uses functions accessing tables or triggers, or that is called from a function or a trigger. * If you use the `LOW_PRIORITY' keyword, execution of the *Note `INSERT': 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 (or even forever) in a read-heavy environment. (This is in contrast to *Note `INSERT DELAYED': insert-delayed, which lets the client continue at once.) Note that `LOW_PRIORITY' should normally not be used with `MyISAM' tables because doing so disables concurrent inserts. See *Note 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 *Note concurrent-inserts::. `LOW_PRIORITY' and `HIGH_PRIORITY' affect only storage engines that use only table-level locking (such as `MyISAM', `MEMORY', and `MERGE'). * If you use the `IGNORE' keyword, errors that occur while executing the *Note `INSERT': 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 still is not inserted, but no error occurs. Ignored errors may generate warnings instead, although duplicate-key errors do not. `IGNORE' has a similar effect on inserts into partitioned tables where no partition matching a given value is found. Without `IGNORE', such *Note `INSERT': insert. statements are aborted with an error; however, when *Note `INSERT IGNORE': insert. is used, the insert operation fails silently for the row containing the unmatched value, but any rows that are matched are inserted. For an example, see *Note 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 *Note `mysql_info()': mysql-info. C API function how many rows were actually inserted into the table. * 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 *Note `UPDATE': update. of the old row is performed. The affected-rows value per row is 1 if the row is inserted as a new row and 2 if an existing row is updated. See *Note insert-on-duplicate::. 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 *Note `UPDATE': 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). An `INSERT'statement that acts on a partitioned table using a storage engine such as *Note `MyISAM': myisam-storage-engine. that employs table-level locks locks all partitions of the table. This does not occur with tables using storage engines such as *Note `InnoDB': innodb-storage-engine. that employ row-level locking. This issue is resolved in MySQL 5.6. See *Note partitioning-limitations-locking::, for more information.  File: manual.info, Node: insert-select, Next: insert-delayed, Prev: insert, Up: insert 13.2.5.1 `INSERT ... SELECT' Syntax ................................... INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE] [INTO] TBL_NAME [(COL_NAME,...)] SELECT ... [ ON DUPLICATE KEY UPDATE COL_NAME=EXPR, ... ] With *Note `INSERT ... SELECT': insert-select, you can quickly insert many rows into a table 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 a *Note `INSERT ... SELECT': insert-select. statements: * Specify `IGNORE' to ignore rows that would cause duplicate-key violations. * `DELAYED' is ignored with *Note `INSERT ... SELECT': insert-select. * The target table of the *Note `INSERT': insert. statement may appear in the `FROM' clause of the *Note `SELECT': select. part of the query. (This was not possible in some older versions of MySQL.) However, you cannot insert into a table and select from the same table in a subquery. When selecting from and inserting into a table at the same time, MySQL creates a temporary table to hold the rows from the *Note `SELECT': select. and then inserts those rows into the target table. However, it remains true that 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 *Note 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 *Note `INSERT ... SELECT': insert-select. statements. * To avoid ambiguous column reference problems when the *Note `SELECT': select. and the *Note `INSERT': insert. refer to the same table, provide a unique alias for each table used in the *Note `SELECT': select. part, and qualify column names in that part with the appropriate alias. In the values part of `ON DUPLICATE KEY UPDATE', you can refer to columns in other tables, as long as you do not use `GROUP BY' in the *Note `SELECT': select. part. One side effect is that you must qualify nonunique column names in the values part. The order in which rows are returned by a *Note `SELECT': select. statement with no `ORDER BY' clause is not determined. 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; this can lead to inconsistencies between them. To prevent this from occurring, you should always write `INSERT ... SELECT' statements that are to be replicated as `INSERT ... SELECT ... ORDER BY COLUMN'. The choice of COLUMN does not matter as long as the same order for returning the rows is enforced on both the master and the slave. See also *Note replication-features-limit::. An `INSERT ... SELECT' statement that acts on partitioned tables using a storage engine such as *Note `MyISAM': myisam-storage-engine. that employs table-level locks locks all partitions of the source and target tables. This does not occur with tables using storage engines such as *Note `InnoDB': innodb-storage-engine. that employ row-level locking. This issue is resolved in MySQL 5.6. See *Note partitioning-limitations-locking::, for more information.  File: manual.info, Node: insert-delayed, Next: insert-on-duplicate, Prev: insert-select, Up: insert 13.2.5.2 `INSERT DELAYED' Syntax ................................ INSERT DELAYED ... The `DELAYED' option for the *Note `INSERT': insert. statement is a MySQL extension to standard SQL that is very useful if you have clients that cannot or need not wait for the *Note `INSERT': insert. to complete. This is a common situation when you use MySQL for logging and you also periodically run *Note `SELECT': select. and *Note `UPDATE': update. statements that take a long time to complete. When a client uses *Note `INSERT DELAYED': 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. Another major benefit of using *Note `INSERT DELAYED': insert-delayed. is that inserts from many clients are bundled together and written in one block. This is much faster than performing many separate inserts. Note that *Note `INSERT DELAYED': insert-delayed. is slower than a normal *Note `INSERT': insert. if the table is not otherwise in use. There is also the additional overhead for the server to handle a separate thread for each table for which there are delayed rows. This means that you should use *Note `INSERT DELAYED': insert-delayed. only when you are really sure that you need it. The queued rows are held only in memory until they are inserted into the table. This means that if you terminate *Note `mysqld': mysqld. forcibly (for example, with `kill -9') or if *Note `mysqld': mysqld. dies unexpectedly, _any queued rows that have not been written to disk are lost_. There are some constraints on the use of `DELAYED': * *Note `INSERT DELAYED': insert-delayed. works only with `MyISAM', `MEMORY', `ARCHIVE', and (as of MySQL 5.1.19) `BLACKHOLE' tables. For engines that do not support `DELAYED', an error occurs. * An error occurs for *Note `INSERT DELAYED': insert-delayed. if used with a table that has been locked with `LOCK TABLES' because the insert must be handled by a separate thread, not by the session that holds the lock. * For `MyISAM' tables, if there are no free blocks in the middle of the data file, concurrent *Note `SELECT': select. and *Note `INSERT': insert. statements are supported. Under these circumstances, you very seldom need to use *Note `INSERT DELAYED': insert-delayed. with `MyISAM'. * *Note `INSERT DELAYED': insert-delayed. should be used only for *Note `INSERT': insert. statements that specify value lists. The server ignores `DELAYED' for *Note `INSERT ... SELECT': insert-select. or *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. statements. * Because the *Note `INSERT DELAYED': insert-delayed. statement returns immediately, before the rows are inserted, you cannot use `LAST_INSERT_ID()' to get the `AUTO_INCREMENT' value that the statement might generate. * `DELAYED' rows are not visible to *Note `SELECT': select. statements until they actually have been inserted. * *Note `INSERT DELAYED': insert-delayed. is treated as a normal *Note `INSERT': insert. if the statement inserts multiple rows and binary logging is enabled and the global logging format is to use statement-based logging (`binlog_format' is set to `STATEMENT'). This restriction does not apply to row-based binary logging. * `DELAYED' is ignored on slave replication servers, so that *Note `INSERT DELAYED': insert-delayed. is treated as a normal *Note `INSERT': insert. on slaves. This is because `DELAYED' could cause the slave to have different data than the master. * Pending *Note `INSERT DELAYED': insert-delayed. statements are lost if a table is write locked and *Note `ALTER TABLE': alter-table. is used to modify the table structure. * *Note `INSERT DELAYED': insert-delayed. is not supported for views. * *Note `INSERT DELAYED': insert-delayed. is not supported for partitioned tables. The following describes in detail what happens when you use the `DELAYED' option to *Note `INSERT': insert. or *Note `REPLACE': replace. In this description, the `thread' is the thread that received an *Note `INSERT DELAYED': insert-delayed. statement and `handler' is the thread that handles all *Note `INSERT DELAYED': insert-delayed. statements for a particular table. * When a thread executes a `DELAYED' statement for a table, a handler thread is created to process all `DELAYED' statements for the table, if no such handler already exists. * The thread checks whether the handler has previously acquired a `DELAYED' lock; if not, it tells the handler thread to do so. The `DELAYED' lock can be obtained even if other threads have a `READ' or `WRITE' lock on the table. However, the handler waits for all *Note `ALTER TABLE': alter-table. locks or *Note `FLUSH TABLES': flush. statements to finish, to ensure that the table structure is up to date. * The thread executes the *Note `INSERT': insert. statement, but instead of writing the row to the table, it puts a copy of the final row into a queue that is managed by the handler thread. Any syntax errors are noticed by the thread and reported to the client program. * The client cannot obtain from the server the number of duplicate rows or the `AUTO_INCREMENT' value for the resulting row, because the *Note `INSERT': insert. returns before the insert operation has been completed. (If you use the C API, the *Note `mysql_info()': mysql-info. function does not return anything meaningful, for the same reason.) * The binary log is updated by the handler thread when the row is inserted into the table. In case of multiple-row inserts, the binary log is updated when the first row is inserted. * Each time that `delayed_insert_limit' rows are written, the handler checks whether any *Note `SELECT': select. statements are still pending. If so, it permits these to execute before continuing. * When the handler has no more rows in its queue, the table is unlocked. If no new *Note `INSERT DELAYED': insert-delayed. statements are received within `delayed_insert_timeout' seconds, the handler terminates. * If more than `delayed_queue_size' rows are pending in a specific handler queue, the thread requesting *Note `INSERT DELAYED': insert-delayed. waits until there is room in the queue. This is done to ensure that *Note `mysqld': mysqld. does not use all memory for the delayed memory queue. * The handler thread shows up in the MySQL process list with `delayed_insert' in the `Command' column. It is killed if you execute a *Note `FLUSH TABLES': flush. statement or kill it with `KILL THREAD_ID'. However, before exiting, it first stores all queued rows into the table. During this time it does not accept any new *Note `INSERT': insert. statements from other threads. If you execute an *Note `INSERT DELAYED': insert-delayed. statement after this, a new handler thread is created. Note that this means that *Note `INSERT DELAYED': insert-delayed. statements have higher priority than normal *Note `INSERT': insert. statements if there is an *Note `INSERT DELAYED': insert-delayed. handler running. Other update statements have to wait until the *Note `INSERT DELAYED': insert-delayed. queue is empty, someone terminates the handler thread (with `KILL THREAD_ID'), or someone executes a *Note `FLUSH TABLES': flush. * The following status variables provide information about *Note `INSERT DELAYED': insert-delayed. statements. This table lists status variables for *Note `INSERT DELAYED': insert-delayed. statements and describes the meaning of each. Status Variable Meaning `Delayed_insert_threads' Number of handler threads `Delayed_writes' Number of rows written with *Note `INSERT DELAYED': insert-delayed. `Not_flushed_delayed_rows' Number of rows waiting to be written You can view these variables by issuing a *Note `SHOW STATUS': show-status. statement or by executing a *Note `mysqladmin extended-status': mysqladmin. command.  File: manual.info, Node: insert-on-duplicate, Prev: insert-delayed, Up: insert 13.2.5.3 `INSERT ... ON DUPLICATE KEY UPDATE' Syntax .................................................... 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', MySQL performs an *Note `UPDATE': update. of the old row. For example, if column `a' is declared as `UNIQUE' and contains the value `1', the following two statements have similar effect: INSERT INTO table (a,b,c) VALUES (1,2,3) ON DUPLICATE KEY UPDATE c=c+1; UPDATE table 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.) The `ON DUPLICATE KEY UPDATE' clause can contain multiple column assignments, separated by commas. With `ON DUPLICATE KEY UPDATE', the affected-rows value per row is 1 if the row is inserted as a new row, and 2 if an existing row is updated. If column `b' is also unique, the *Note `INSERT': insert. is equivalent to this *Note `UPDATE': update. statement instead: UPDATE table 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. You can use the `VALUES(COL_NAME)' function in the *Note `UPDATE': update. clause to refer to column values from the *Note `INSERT': insert. portion of the *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. 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 `INSERT ... UPDATE' statements and returns `NULL' otherwise. Example: INSERT INTO table (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 table (a,b,c) VALUES (1,2,3) ON DUPLICATE KEY UPDATE c=3; INSERT INTO table (a,b,c) VALUES (4,5,6) ON DUPLICATE KEY UPDATE c=9; If a table contains an `AUTO_INCREMENT' column and *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. inserts or updates a row, the `LAST_INSERT_ID()' function returns the `AUTO_INCREMENT' value. Exception: For updates, `LAST_INSERT_ID()' is not meaningful prior to MySQL 5.1.12. However, you can work around this by using `LAST_INSERT_ID(EXPR)'. Suppose that `id' is the `AUTO_INCREMENT' column. To make `LAST_INSERT_ID()' meaningful for updates, insert rows as follows: INSERT INTO table (a,b,c) VALUES (1,2,3) ON DUPLICATE KEY UPDATE id=LAST_INSERT_ID(id), c=3; The `DELAYED' option is ignored when you use `ON DUPLICATE KEY UPDATE'. An `INSERT ... ON DUPLICATE KEY UPDATE' on a partitioned table using a storage engine such as *Note `MyISAM': myisam-storage-engine. that employs table-level locks locks all partitions of the table. This does not occur with tables using storage engines such as *Note `InnoDB': innodb-storage-engine. that employ row-level locking. This issue is resolved in MySQL 5.6. See *Note partitioning-limitations-locking::, for more information.  File: manual.info, Node: load-data, Next: replace, Prev: insert, Up: sql-syntax-data-manipulation 13.2.6 `LOAD DATA INFILE' Syntax -------------------------------- LOAD DATA [LOW_PRIORITY | CONCURRENT] [LOCAL] INFILE 'FILE_NAME' [REPLACE | IGNORE] INTO TABLE TBL_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] [(COL_NAME_OR_USER_VAR,...)] [SET COL_NAME = EXPR,...] The *Note `LOAD DATA INFILE': load-data. statement reads rows from a text file into a table at a very high speed. *Note `LOAD DATA INFILE': load-data. is the complement of *Note `SELECT ... INTO OUTFILE': select-into. (See *Note select-into::.) To write data from a table to a file, use *Note `SELECT ... INTO OUTFILE': select-into. To read the file back into a table, use *Note `LOAD DATA INFILE': load-data. 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 *Note `mysqlimport': mysqlimport. utility; it operates by sending a *Note `LOAD DATA INFILE': load-data. statement to the server. The `--local' option causes *Note `mysqlimport': 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 *Note mysqlimport::. For more information about the efficiency of *Note `INSERT': insert. versus *Note `LOAD DATA INFILE': load-data. and speeding up *Note `LOAD DATA INFILE': load-data, see *Note insert-speed::. The file name must be given as a literal string. On Windows, specify backslashes in path names as forward slashes or doubled backslashes. As of MySQL 5.1.6, the `character_set_filesystem' system variable controls the interpretation of the file name. The character set indicated by the `character_set_database' system variable is used 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, which is available as of MySQL 5.1.17. A character set of `binary' specifies `no conversion.' *Note `LOAD DATA INFILE': load-data. 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 *Note `mysqldump -T': mysqldump. or by issuing a *Note `SELECT ... INTO OUTFILE': select-into. statement in *Note `mysql': 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 *Note `LOAD DATA INFILE': load-data. *Note*: It is not possible to load data files that use the `ucs2' character set. If you use `LOW_PRIORITY', execution of the *Note `LOAD DATA': 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 *Note `LOAD DATA': load-data. is executing. This option affects the performance of *Note `LOAD DATA': 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.1.43 (see Bug #34628). For more information, see *Note replication-features-load-data::. *Note*: Prior to MySQL 5.1.23, *Note `LOAD DATA': load-data. performed very poorly when importing into partitioned tables. The statement now uses buffering to improve performance; however, the buffer uses 130KB memory per partition to achieve this. (Bug #26527) 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 *Note `mysqld': mysqld. was started with `--local-infile=0', `LOCAL' does not work. See *Note 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 *Note `LOAD DATA': 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 *Note `LOAD DATA LOCAL': load-data. 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 *Note `LOAD DATA': 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; *Note*: A regression in MySQL 5.1.40 caused the database referenced in a fully qualified table name to be ignored by *Note `LOAD DATA': load-data. when using replication with either `STATEMENT' or `MIXED' as the binary logging format; this could lead to problems if the table was not in the current database. As a workaround, you can specify the correct database with the *Note `USE': use. statement prior to executing *Note `LOAD DATA': load-data. If necessary, you can reset the default database with a second *Note `USE': use. statement following the *Note `LOAD DATA': load-data. statement. This issue was fixed in MySQL 5.1.41. (Bug #48297) For security reasons, when reading text files located on the server, the files must either reside in the database directory or be readable by all. Also, to use *Note `LOAD DATA INFILE': load-data. on server files, you must have the `FILE' privilege. See *Note privileges-provided::. For non-`LOCAL' load operations, 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. 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 *Note `LOAD DATA INFILE': load-data, data-interpretation and duplicate-key errors terminate the operation. * With *Note `LOAD DATA LOCAL INFILE': load-data, 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 *Note replace::. * 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, 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 *Note `LOAD DATA': load-data. If you use *Note `LOAD DATA INFILE': load-data. on an empty `MyISAM' table, all nonunique indexes are created in a separate batch (as for *Note `REPAIR TABLE': repair-table.). Normally, this makes *Note `LOAD DATA INFILE': load-data. 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 *Note insert-speed::. For both the *Note `LOAD DATA INFILE': load-data. and *Note `SELECT ... INTO OUTFILE': select-into. 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 *Note `LOAD DATA INFILE': load-data. 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 *Note `SELECT ... INTO OUTFILE': select-into. 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 *Note `SELECT ... INTO OUTFILE': select-into. in tandem with *Note `LOAD DATA INFILE': load-data. 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, *Note `LOAD DATA INFILE': load-data. will not interpret the contents of the file properly. Suppose that you use *Note `SELECT ... INTO OUTFILE': select-into. 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 *Note `LOAD DATA INFILE': load-data. 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. *Note `LOAD DATA INFILE': load-data. 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 (*Note `SELECT ... INTO OUTFILE': select-into.), 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 *Note `CHAR': char, *Note `BINARY': binary-varbinary, *Note `TEXT': blob, or *Note `ENUM': 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 Note that occurrences of the `ENCLOSED BY' character within a field value are escaped by prefixing them with the `ESCAPED BY' character. Also note that if you specify an empty `ESCAPED BY' value, it is possible to inadvertently generate output that cannot be read properly by *Note `LOAD DATA INFILE': load-data. 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. This table lists two-character sequences for which the first character (a ``\'') is the escape character. Character Escape Sequence `\0' An ASCII NUL (`0x00') 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 *Note 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 *Note `TINYINT': integer-types, *Note `SMALLINT': integer-types, *Note `MEDIUMINT': integer-types, *Note `INT': integer-types, and *Note `BIGINT': integer-types, 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 that fixed-size format does not work if you are using a multi-byte 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. Note that 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 *Note data-type-defaults::. Some cases are not supported by *Note `LOAD DATA INFILE': load-data.: * Fixed-size rows (`FIELDS TERMINATED BY' and `FIELDS ENCLOSED BY' both empty) and *Note `BLOB': blob. or *Note `TEXT': blob. columns. * If you specify one separator that is the same as or a prefix of another, *Note `LOAD DATA INFILE': load-data. 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 *Note `LOAD DATA INFILE': load-data. to stop reading a field or line too early. This happens because *Note `LOAD DATA INFILE': load-data. 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 *Note `LOAD DATA INFILE': load-data. 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 (col1,col2,...); 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. The column list can contain either column names or user variables. 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, *Note `LOAD DATA': 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 *Note 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 *Note 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 *Note `INSERT': insert. or *Note `UPDATE': 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='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', warnings occur rather than errors, even with a restrictive `sql_mode' value, because the server has no way to stop transmission of the file in the middle of the operation.) *Note `TIMESTAMP': datetime. 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 *Note `TIMESTAMP': datetime. column's default value is the current timestamp and it is omitted from the field list when a field list is specified. *Note `LOAD DATA INFILE': load-data. regards all input as strings, so you cannot use numeric values for *Note `ENUM': enum. or *Note `SET': set. columns the way you can with *Note `INSERT': insert. statements. All *Note `ENUM': enum. and *Note `SET': set. values must be specified as strings. *Note `BIT': bit-type. values cannot be loaded using binary notation (for example, `b'011010''). To work around this, specify the values as regular integers and use the `SET' clause to convert them so that MySQL performs a numeric type conversion and loads them into the *Note `BIT': bit-type. column properly: shell> cat /tmp/bit_test.txt 2 127 shell> mysql test mysql> LOAD DATA INFILE '/tmp/bit_test.txt' -> INTO TABLE bit_test (@var1) SET b = CAST(@var1 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) On Unix, if you need *Note `LOAD DATA': 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 Note that you must run the command that generates the data to be loaded and the *Note `mysql': 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 *Note `mysql': mysql. process. When the *Note `LOAD DATA INFILE': load-data. 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 *Note `INSERT': insert. statement (see *Note insert::), except that *Note `LOAD DATA INFILE': load-data. also generates warnings when there are too few or too many fields in the input row. You can use *Note `SHOW WARNINGS': show-warnings. to get a list of the first `max_error_count' warnings as information about what went wrong. See *Note show-warnings::. If you are using the C API, you can get information about the statement by calling the *Note `mysql_info()': mysql-info. function. See *Note mysql-info::. For partitioned tables using storage engines that employ table locks, such as *Note `MyISAM': myisam-storage-engine, any locks caused by `LOAD DATA' perform locks on all partitions of the table. This does not apply to tables using storage engines which employ row-level locking, such as *Note `InnoDB': innodb-storage-engine. For more information, see *Note partitioning-limitations-locking::.  File: manual.info, Node: replace, Next: select, Prev: load-data, Up: sql-syntax-data-manipulation 13.2.7 `REPLACE' Syntax ----------------------- REPLACE [LOW_PRIORITY | DELAYED] [INTO] TBL_NAME [(COL_NAME,...)] {VALUES | VALUE} ({EXPR | DEFAULT},...),(...),... Or: REPLACE [LOW_PRIORITY | DELAYED] [INTO] TBL_NAME SET COL_NAME={EXPR | DEFAULT}, ... Or: REPLACE [LOW_PRIORITY | DELAYED] [INTO] TBL_NAME [(COL_NAME,...)] SELECT ... *Note `REPLACE': replace. works exactly like *Note `INSERT': 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 *Note insert::. *Note `REPLACE': 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 *Note insert-on-duplicate::. Note that unless the table has a `PRIMARY KEY' or `UNIQUE' index, using a *Note `REPLACE': replace. statement makes no sense. It becomes equivalent to *Note `INSERT': 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 *Note `REPLACE': replace. statement. Any missing columns are set to their default values, just as happens for *Note `INSERT': 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 *Note `REPLACE': replace, you must have both the `INSERT' and `DELETE' privileges for the table. The *Note `REPLACE': 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 *Note `REPLACE': 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 *Note `REPLACE': 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 *Note `mysql_affected_rows()': mysql-affected-rows. function. Currently, you cannot replace into a table and select from the same table in a subquery. MySQL uses the following algorithm for *Note `REPLACE': 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. A `REPLACE' statement that acts on a partitioned table using a storage engine such as *Note `MyISAM': myisam-storage-engine. that employs table-level locks locks all partitions of the table. This does not occur with tables using storage engines such as *Note `InnoDB': innodb-storage-engine. that employ row-level locking. This issue is resolved in MySQL 5.6. See *Note partitioning-limitations-locking::, for more information.  File: manual.info, Node: select, Next: subqueries, Prev: replace, Up: sql-syntax-data-manipulation 13.2.8 `SELECT' Syntax ---------------------- * Menu: * select-into:: `SELECT ... INTO' Syntax * join:: `JOIN' Syntax * index-hints:: Index Hint Syntax * union:: `UNION' 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 [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]] *Note `SELECT': select. is used to retrieve rows selected from one or more tables, and can include *Note `UNION': union. statements and subqueries. See *Note union::, and *Note subqueries::. The most commonly used clauses of *Note `SELECT': 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 *Note join::. * 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 *Note expressions::, and *Note functions::. *Note `SELECT': 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 *Note `SELECT': 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 *Note 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 *Note 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 *Note 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 *Note 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 *Note 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 *Note 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; * 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 *Note group-by-functions-and-modifiers::. * `GROUP BY' permits a `WITH ROLLUP' modifier. See *Note 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 *Note `SELECT': 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 *Note `SELECT': select. statement. `LIMIT' takes one or two numeric arguments, which must both be nonnegative integer constants (except when using prepared statements). 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 *Note 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. * The *Note `SELECT ... INTO': select-into. form of *Note `SELECT': select. enables the query result to be written to a file or stored in variables. For more information, see *Note 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 *Note innodb-locking-reads::. Following the *Note `SELECT': select. keyword, you can use a number of options that affect the operation of the statement. `HIGH_PRIORITY', `STRAIGHT_JOIN', and options beginning with `SQL_' are MySQL extensions to standard SQL. * The `ALL' and `DISTINCT' options 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 options. `DISTINCTROW' is a synonym for `DISTINCT'. * `HIGH_PRIORITY' gives the *Note `SELECT': 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 *Note `SELECT': select. statements that are part of a *Note `UNION': 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 *Note 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 *Note `EXPLAIN': explain. See *Note 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 needed, and prefers sorting to using a temporary table with a key on the `GROUP BY' elements. For `SQL_SMALL_RESULT', MySQL uses fast 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 option can be used only for top-level *Note `SELECT': select. statements, not for subqueries or following *Note `UNION': 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 *Note information-functions::. * The `SQL_CACHE' and `SQL_NO_CACHE' options affect caching of query results in the query cache (see *Note 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. (Due to a limitation in the parser, a space character must precede and follow the `SQL_NO_CACHE' keyword; a nonspace such as a newline causes the server to check the query cache to see whether the result is already cached.) For a query that uses *Note `UNION': union, subqueries, or views, the following rules apply: * `SQL_NO_CACHE' applies if it appears in any *Note `SELECT': select. in the query. * For a cacheable query, `SQL_CACHE' applies if it appears in the first *Note `SELECT': select. of the query, or in the first *Note `SELECT': select. of a view referred to by the query. A `SELECT' from a partitioned table using a storage engine such as *Note `MyISAM': myisam-storage-engine. that employs table-level locks locks all partitions of the table. This does not occur with tables using storage engines such as *Note `InnoDB': innodb-storage-engine. that employ row-level locking. This issue is resolved in MySQL 5.6. See *Note partitioning-limitations-locking::, for more information.  File: manual.info, Node: select-into, Next: join, Prev: select, Up: select 13.2.8.1 `SELECT ... INTO' Syntax ................................. The *Note `SELECT ... INTO': select-into. form of *Note `SELECT': 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 *Note `SELECT': select. syntax description (see *Note 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 *Note `SELECT': select. because such a *Note `SELECT': 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 *Note 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 *Note user-variables::. The *Note `SELECT ... INTO OUTFILE 'FILE_NAME'': select-into. form of *Note `SELECT': 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. As of MySQL 5.1.6, the `character_set_filesystem' system variable controls the interpretation of the file name. The *Note `SELECT ... INTO OUTFILE': select-into. 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 *Note `SELECT ... INTO OUTFILE': select-into. 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 *Note `mysql': mysql. (or some other MySQL client program) is not required on the target host. *Note `SELECT ... INTO OUTFILE': select-into. is the complement of *Note `LOAD DATA INFILE': load-data. Column values are written converted to the character set specified in the `CHARACTER SET' clause, which is available as of MySQL 5.1.38. Prior to 5.1.38 or 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 *Note `LOAD DATA INFILE': load-data. statement. See *Note 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 *Note `BLOB': 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 *Note `mysqld': 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 *Note `SELECT ... INTO': 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 *Note events-status-info::.  File: manual.info, Node: join, Next: index-hints, Prev: select-into, Up: select 13.2.8.2 `JOIN' Syntax ...................... MySQL supports the following `JOIN' syntaxes for the TABLE_REFERENCES part of *Note `SELECT': select. statements and multiple-table *Note `DELETE': delete. and *Note `UPDATE': 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 [[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. 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, `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 *Note nested-join-optimization::). Index hints can be specified to affect how the MySQL optimizer makes use of indexes. For more information, see *Note index-hints::. 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 subquery in the `FROM' clause. Such subqueries _must_ include an alias to give the subquery result a table name. A trivial example follows; see also *Note from-clause-subqueries::. 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 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, you should use the `ON' clause for conditions that specify how to join tables, and the `WHERE' clause to restrict which rows you want 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'). This assumes that `right_tbl.id' is declared `NOT NULL'. See *Note 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; As of MySQL 5.1.24, 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. A consequence of this change is that the parser does not permit nested `{ OJ ... }' constructs (which are not legal ODBC syntax, anyway). Queries that use such constructs should be rewritten. For example, this query is now produces an error: SELECT * FROM {OJ {OJ a LEFT OUTER JOIN b ON a.a1=b.a1} LEFT OUTER JOIN c ON b.b1 = c.b1}; That can be replaced by any of the following rewrites: SELECT * FROM {OJ a LEFT OUTER JOIN b LEFT OUTER JOIN c ON b.b1 = c.b1 ON a.a1=b.a1}; SELECT * FROM {OJ a LEFT OUTER JOIN b ON a.a1=b.a1 LEFT OUTER JOIN c ON b.b1 = c.b1}; SELECT * FROM a LEFT OUTER JOIN b ON a.a1=b.a1 LEFT OUTER JOIN c ON b.b1 = c.b1; The first two are legal according to ODBC, and you nest the joins inside a single `{ OJ ...}' clause. The third is standard SQL syntax, without ODBC decoration. It can be used with parentheses to emphasize the evaluation order: SELECT * FROM ((a LEFT OUTER JOIN b ON a.a1=b.a1) LEFT OUTER JOIN c ON b.b1 = c.b1); * `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 puts the tables in the wrong 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; *Join Processing Changes in MySQL 5.0.12* *Note*: Natural joins and joins with `USING', including outer join variants, are processed according to the SQL:2003 standard. The goal was to align the syntax and semantics of MySQL with respect to `NATURAL JOIN' and `JOIN ... USING' according to SQL:2003. However, these changes in join processing can result in different output columns for some joins. Also, some queries that appeared to work correctly in older versions (prior to 5.0.12) must be rewritten to comply with the standard. These changes have five main aspects: * The way that MySQL determines the result columns of `NATURAL' or `USING' join operations (and thus the result of the entire `FROM' clause). * Expansion of `SELECT *' and `SELECT TBL_NAME.*' into a list of selected columns. * Resolution of column names in `NATURAL' or `USING' joins. * Transformation of `NATURAL' or `USING' joins into `JOIN ... ON'. * Resolution of column names in the `ON' condition of a `JOIN ... ON'. The following list provides more detail about several effects of current join processing versus join processing in older versions. The term `previously' means `prior to MySQL 5.0.12.' * The columns of a `NATURAL' join or a `USING' join may be different from previously. Specifically, redundant output columns no longer appear, and the order of columns for `SELECT *' expansion may be different from before. 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); Previously, the statements produced this output: +------+------+------+------+ | i | j | k | j | +------+------+------+------+ | 1 | 1 | 1 | 1 | +------+------+------+------+ +------+------+------+------+ | i | j | k | j | +------+------+------+------+ | 1 | 1 | 1 | 1 | +------+------+------+------+ In the first *Note `SELECT': 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. But in both cases, the redundant column is not eliminated. Also, the order of the columns is not correct according to standard SQL. Now the statements produce this output: +------+------+------+ | j | i | k | +------+------+------+ | 1 | 1 | 1 | +------+------+------+ +------+------+------+ | j | i | k | +------+------+------+ | 1 | 1 | 1 | +------+------+------+ The redundant column is eliminated and the column order is correct according to standard SQL: * 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 V1 IS NOT NULL THEN V1 ELSE V2 END) If the join operation is any other join, the result columns of the join consists of the concatenation of all columns of the joined tables. This is the same as previously. 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: mysql> SELECT * FROM t1 NATURAL LEFT JOIN t2; +------+------+------+ | a | b | c | +------+------+------+ | 1 | x | NULL | | 2 | y | z | +------+------+------+ Here column `a' contains the values of `t1.a'. mysql> SELECT * FROM t1 NATURAL RIGHT JOIN t2; +------+------+------+ | a | c | b | +------+------+------+ | 2 | z | y | | 3 | w | NULL | +------+------+------+ Here column `a' contains the values of `t2.a'. Compare these 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 | +------+------+------+------+ * Previously, a `USING' clause could be rewritten as an `ON' clause that compares corresponding columns. For example, the following two clauses were semantically identical: 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 Now the two clauses no longer are quite the same: * With respect to determining which rows satisfy the join condition, both joins remain 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 preceding `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 will be omitted from the result. * The evaluation of multi-way natural joins differs in a very important way that affects the result of `NATURAL' or `USING' joins and that can require query rewriting. Suppose that you have three tables `t1(a,b)', `t2(c,b)', and `t3(a,c)' that each have one row: `t1(1,2)', `t2(10,2)', and `t3(7,10)'. Suppose also that you have this `NATURAL JOIN' on the three tables: SELECT ... FROM t1 NATURAL JOIN t2 NATURAL JOIN t3; Previously, the left operand of the second join was considered to be `t2', whereas it should be the nested join `(t1 NATURAL JOIN t2)'. As a result, the columns of `t3' are checked for common columns only in `t2', and, if `t3' has common columns with `t1', these columns are not used as equi-join columns. Thus, previously, the preceding query was transformed to the following equi-join: SELECT ... FROM t1, t2, t3 WHERE t1.b = t2.b AND t2.c = t3.c; That join is missing one more equi-join predicate `(t1.a = t3.a)'. As a result, it produces one row, not the empty result that it should. The correct equivalent query is this: SELECT ... FROM t1, t2, t3 WHERE t1.b = t2.b AND t2.c = t3.c AND t1.a = t3.a; If you require the same query result in current versions of MySQL as in older versions, rewrite the natural join as the first equi-join. * Previously, the comma operator (`,') and `JOIN' both had the same precedence, so the join expression `t1, t2 JOIN t3' was interpreted as `((t1, t2) JOIN t3)'. Now `JOIN' has higher precedence, so the expression is interpreted as `(t1, (t2 JOIN t3))'. This change affects statements that use an `ON' clause, because that clause can refer only to columns in the operands of the join, and the change in precedence changes 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); Previously, the *Note `SELECT': select. was legal due to the implicit grouping of `t1,t2' as `(t1,t2)'. Now the `JOIN' takes precedence, 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 allow the join to be processed, 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); Alternatively, avoid the use of the comma operator and use `JOIN' instead: SELECT * FROM t1 JOIN t2 JOIN t3 ON (t1.i1 = t3.i3); This change also applies to statements that mix the comma operator with `INNER JOIN', `CROSS JOIN', `LEFT JOIN', and `RIGHT JOIN', all of which now have higher precedence than the comma operator. * Previously, the `ON' clause could refer to columns in tables named to its right. Now 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; Previously, the *Note `SELECT': select. statement was legal. Now 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. The statement should be rewritten as follows: SELECT * FROM t1 JOIN t2 JOIN t3 ON (i1 = i3); * Resolution of column names in `NATURAL' or `USING' joins is different than previously. For column names that are outside the `FROM' clause, MySQL now handles a superset of the queries compared to previously. That is, in cases when MySQL formerly issued an error that some column is ambiguous, the query now is handled correctly. This is due to the fact that MySQL now treats the common columns of `NATURAL' or `USING' joins as a single column, so when a query refers to such columns, the query compiler does not consider them as ambiguous. Example: SELECT * FROM t1 NATURAL JOIN t2 WHERE b > 1; Previously, this query would produce an error `ERROR 1052 (23000): Column 'b' in where clause is ambiguous'. Now the query produces the correct result: +------+------+------+ | b | c | y | +------+------+------+ | 4 | 2 | 3 | +------+------+------+ One extension of MySQL compared to the SQL:2003 standard is that MySQL enables you to qualify the common (coalesced) columns of `NATURAL' or `USING' joins (just as previously), while the standard disallows that.  File: manual.info, Node: index-hints, Next: union, Prev: join, Up: select 13.2.8.3 Index Hint Syntax .......................... You can provide hints to give the optimizer information about how to choose indexes during query processing. *Note join::, describes the general syntax for specifying tables in a *Note `SELECT': select. statement. The syntax for an individual table, including that for 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] ... By specifying `USE INDEX (INDEX_LIST)', you can tell MySQL to use only one of the named indexes to find rows in the table. The alternative syntax `IGNORE INDEX (INDEX_LIST)' can be used to tell MySQL to not use some particular index or indexes. These hints are useful if *Note `EXPLAIN': explain. shows that MySQL is using the wrong index from the list of possible indexes. You can also use `FORCE INDEX', which acts like `USE INDEX (INDEX_LIST)' but 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 given indexes to find rows in the table. Each hint requires the names of _indexes_, not the names of columns. The name of a `PRIMARY KEY' is `PRIMARY'. To see the index names for a table, use *Note `SHOW INDEX': show-index. 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. Prior to MySQL 5.1.17, `USE INDEX', `IGNORE INDEX', and `FORCE INDEX' affect only which indexes are used when MySQL decides how to find rows in the table and how to process joins. They do not affect whether an index is used when resolving an `ORDER BY' or `GROUP BY' clause. 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; As of MySQL 5.1.17, the syntax for index hints is extended in the following ways: * It is syntactically valid to specify an empty INDEX_LIST for `USE INDEX', which means `use no indexes.' Specifying an empty INDEX_LIST for `FORCE INDEX' or `IGNORE INDEX' is a syntax error. * You can specify the scope of a index hint by adding a `FOR' clause to the hint. This provides more fine-grained control over the optimizer's 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'. (However, if there is a covering index for the table and it is used to access the table, the optimizer will ignore `IGNORE INDEX FOR {ORDER BY|GROUP BY}' hints that disable that index.) * You can specify multiple index hints: SELECT * FROM t1 USE INDEX (i1) IGNORE INDEX FOR ORDER BY (i2) ORDER BY a; It is not a 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); The default scope of index hints also is changed as of MySQL 5.1.17. Formerly, index hints applied only to how indexes are used for retrieval of records and not during resolution of `ORDER BY' or `GROUP BY' clauses. As of 5.1.17, if you specify no `FOR' clause for an index hint, the hint by default applies 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) To cause the server to use the older behavior for hint scope when no `FOR' clause is present (so that hints apply only to row retrieval), 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 (*Note `USE': 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 do not work before MySQL 5.1.31. As of 5.1.31, index hints work as follows: * For natural language mode searches, index hints are silently ignored. For example, `IGNORE INDEX(i)' 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 ... ;  File: manual.info, Node: union, Prev: index-hints, Up: select 13.2.8.4 `UNION' Syntax ....................... SELECT ... UNION [ALL | DISTINCT] SELECT ... [UNION [ALL | DISTINCT] SELECT ...] *Note `UNION': union. is used to combine the result from multiple *Note `SELECT': select. statements into a single result set. The column names from the first *Note `SELECT': select. statement are used as the column names for the results returned. Selected columns listed in corresponding positions of each *Note `SELECT': 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 *Note `SELECT': select. columns do not match, the types and lengths of the columns in the *Note `UNION': union. result take into account the values retrieved by all of the *Note `SELECT': select. statements. For example, consider the following: mysql> SELECT REPEAT('a',1) UNION SELECT REPEAT('b',10); +---------------+ | REPEAT('a',1) | +---------------+ | a | | bbbbbbbbbb | +---------------+ (In some earlier versions of MySQL, only the type and length from the first *Note `SELECT': select. would have been used and the second row would have been truncated to a length of 1.) The *Note `SELECT': select. statements are normal select statements, but with the following restrictions: * Only the last *Note `SELECT': select. statement can use `INTO OUTFILE'. (However, the entire *Note `UNION': union. result is written to the file.) * `HIGH_PRIORITY' cannot be used with *Note `SELECT': select. statements that are part of a *Note `UNION': union. If you specify it for the first *Note `SELECT': select, it has no effect. If you specify it for any subsequent *Note `SELECT': select. statements, a syntax error results. The default behavior for *Note `UNION': 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 *Note `SELECT': select. statements. You can mix *Note `UNION ALL': union. and *Note `UNION DISTINCT': union. in the same query. Mixed *Note `UNION': 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 *Note `UNION DISTINCT': union. or implicitly by using *Note `UNION': union. with no following `DISTINCT' or `ALL' keyword. To apply `ORDER BY' or `LIMIT' to an individual *Note `SELECT': select, place the clause inside the parentheses that enclose the *Note `SELECT': 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); However, use of `ORDER BY' for individual *Note `SELECT': select. statements implies nothing about the order in which the rows appear in the final result because *Note `UNION': 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 *Note `SELECT': select, even though it does not necessarily affect the order of those rows in the final *Note `UNION': union. result. If `ORDER BY' appears without `LIMIT' in a *Note `SELECT': 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 *Note `UNION': union. result, parenthesize the individual *Note `SELECT': 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 *Note `SELECT': 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 *Note `UNION': union. result to consist of the sets of rows retrieved by each *Note `SELECT': select. one after the other, select an additional column in each *Note `SELECT': select. to use as a sort column and add an `ORDER BY' following the last *Note `SELECT': 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 *Note `SELECT': 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 *Note `SELECT': select. each row comes from. Extra columns can provide other identifying information as well, such as a string that indicates a table name.  File: manual.info, Node: subqueries, Next: update, Prev: select, Up: sql-syntax-data-manipulation 13.2.9 Subquery Syntax ---------------------- * Menu: * scalar-subqueries:: The Subquery as Scalar Operand * comparisons-using-subqueries:: Comparisons Using Subqueries * any-in-some-subqueries:: Subqueries with `ANY', `IN', or `SOME' * all-subqueries:: Subqueries with `ALL' * row-subqueries:: Row Subqueries * exists-and-not-exists-subqueries:: Subqueries with `EXISTS' or `NOT EXISTS' * correlated-subqueries:: Correlated Subqueries * from-clause-subqueries:: Subqueries in the `FROM' Clause * subquery-errors:: Subquery Errors * optimizing-subqueries:: Optimizing Subqueries * rewriting-subqueries:: Rewriting Subqueries as Joins A subquery is a *Note `SELECT': select. statement within another statement. Starting with MySQL 4.1, 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 *Note `SELECT': select. can contain: `DISTINCT', `GROUP BY', `ORDER BY', `LIMIT', joins, index hints, *Note `UNION': union. constructs, comments, functions, and so on. A subquery's outer statement can be any one of: *Note `SELECT': select, *Note `INSERT': insert, *Note `UPDATE': update, *Note `DELETE': delete, *Note `SET': set-statement, or *Note `DO': do. In MySQL, you cannot modify a table and select from the same table in a subquery. This applies to statements such as *Note `DELETE': delete, *Note `INSERT': insert, *Note `REPLACE': replace, *Note `UPDATE': update, and (because subqueries can be used in the `SET' clause) *Note `LOAD DATA INFILE': load-data. For information about how the optimizer handles subqueries, see *Note subquery-optimization-with-exists::. For a discussion of restrictions on subquery use, including performance issues for certain forms of subquery syntax, see *Note subquery-restrictions::.  File: manual.info, Node: scalar-subqueries, Next: comparisons-using-subqueries, Prev: subqueries, Up: subqueries 13.2.9.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 *Note `SELECT': select. returns a single value (`'abcde'') that has a data type of *Note `CHAR': char, a length of 5, a character set and collation equal to the defaults in effect at *Note `CREATE TABLE': 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 *Note `LOAD DATA INFILE': load-data. 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 *Note `SELECT': 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;  File: manual.info, Node: comparisons-using-subqueries, Next: any-in-some-subqueries, Prev: scalar-subqueries, Up: subqueries 13.2.9.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 *Note row-subqueries::.  File: manual.info, Node: any-in-some-subqueries, Next: all-subqueries, Prev: comparisons-using-subqueries, Up: subqueries 13.2.9.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 *Note comparison-operators::. `NOT IN' is not an alias for `<> ANY', but for `<> ALL'. See *Note 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.  File: manual.info, Node: all-subqueries, Next: row-subqueries, Prev: any-in-some-subqueries, Up: subqueries 13.2.9.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);  File: manual.info, Node: row-subqueries, Next: exists-and-not-exists-subqueries, Prev: all-subqueries, Up: subqueries 13.2.9.5 Row Subqueries ....................... The discussion to this point has been of scalar or column subqueries; that is, subqueries that 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. 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: SELECT * FROM t1 WHERE (column1,column2) = (1,1); SELECT * FROM t1 WHERE column1 = 1 AND column2 = 1; Prior to MySQL 5.1.12, only the second of the preceding two expressions could be optimized. 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);  File: manual.info, Node: exists-and-not-exists-subqueries, Next: correlated-subqueries, Prev: row-subqueries, Up: subqueries 13.2.9.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 *Note `SELECT': 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?'  File: manual.info, Node: correlated-subqueries, Next: from-clause-subqueries, Prev: exists-and-not-exists-subqueries, Up: subqueries 13.2.9.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.  File: manual.info, Node: from-clause-subqueries, Next: subquery-errors, Prev: correlated-subqueries, Up: subqueries 13.2.9.8 Subqueries in the `FROM' Clause ........................................ Subqueries are legal in a *Note `SELECT': select. statement's `FROM' clause. The actual syntax is: SELECT ... FROM (SUBQUERY) [AS] NAME ... The `[AS] 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. Subqueries in the `FROM' clause can return a scalar, column, row, or table. Subqueries in the `FROM' clause cannot be correlated subqueries, unless used within the `ON' clause of a `JOIN' operation. Subqueries in the `FROM' clause are executed even for the *Note `EXPLAIN': explain. statement (that is, derived temporary tables are materialized). This occurs because upper-level queries need information about all tables during the optimization phase, and the table represented by a subquery in the `FROM' clause is unavailable unless the subquery is executed. It is possible under certain circumstances to modify table data using *Note `EXPLAIN SELECT': explain. 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', created as shown here: mysql> CREATE DATABASE d1; Query OK, 1 row affected (0.00 sec) mysql> USE d1; Database changed mysql> CREATE TABLE t1 (c1 INT); Query OK, 0 rows affected (0.15 sec) mysql> CREATE TABLE t2 (c1 INT); Query OK, 0 rows affected (0.08 sec) Now we create a stored function `f1' which modifies `t2': mysql> DELIMITER // mysql> CREATE FUNCTION f1(p1 INT) RETURNS INT mysql> BEGIN mysql> INSERT INTO t2 VALUES (p1); mysql> RETURN p1; mysql> END // Query OK, 0 rows affected (0.01 sec) mysql> DELIMITER ; Referencing the function directly in an *Note `EXPLAIN SELECT': explain. does not have any effect on `t2', as shown here: mysql> SELECT * FROM t2; Empty set (0.00 sec) mysql> EXPLAIN SELECT f1(5); +----+-------------+-------+------+---------------+------+---------+------+------+----------------+ | id | select_type | table | type | possible_keys | key | key_len | ref | rows | Extra | +----+-------------+-------+------+---------------+------+---------+------+------+----------------+ | 1 | SIMPLE | NULL | NULL | NULL | NULL | NULL | NULL | NULL | No tables used | +----+-------------+-------+------+---------------+------+---------+------+------+----------------+ 1 row in set (0.00 sec) mysql> SELECT * FROM t2; Empty set (0.00 sec) This is because the *Note `SELECT': 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 *Note `SELECT': select.: mysql> EXPLAIN SELECT NOW() AS a1, (SELECT f1(5)) AS a2; +----+-------------+-------+------+---------------+------+---------+------+------+----------------+ | id | select_type | table | type | possible_keys | key | key_len | ref | rows | Extra | +----+-------------+-------+------+---------------+------+---------+------+------+----------------+ | 1 | PRIMARY | NULL | NULL | NULL | NULL | NULL | NULL | NULL | 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 *Note `SELECT': 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; +----+-------------+------------+--------+---------------+------+---------+------+------+---------------------+ | id | select_type | table | type | possible_keys | key | key_len | ref | rows | Extra | +----+-------------+------------+--------+---------------+------+---------+------+------+---------------------+ | 1 | PRIMARY | a1 | system | NULL | NULL | NULL | NULL | 0 | const row not found | | 1 | PRIMARY | | system | NULL | NULL | NULL | NULL | 1 | | | 2 | DERIVED | NULL | NULL | NULL | NULL | NULL | NULL | NULL | 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 *Note `EXPLAIN SELECT': explain. 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())));  File: manual.info, Node: subquery-errors, Next: optimizing-subqueries, Prev: from-clause-subqueries, Up: subqueries 13.2.9.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 *Note 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 *Note `UPDATE': update. statement because subqueries are legal in *Note `UPDATE': update. and *Note `DELETE': delete. statements as well as in *Note `SELECT': 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.  File: manual.info, Node: optimizing-subqueries, Next: rewriting-subqueries, Prev: subquery-errors, Up: subqueries 13.2.9.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: * 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 *Note 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 *Note information-functions::. Some optimizations that MySQL itself makes are: * MySQL executes uncorrelated subqueries only once. Use *Note `EXPLAIN': 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 *Note `EXPLAIN': 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).  File: manual.info, Node: rewriting-subqueries, Prev: optimizing-subqueries, Up: subqueries 13.2.9.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 *Note `DELETE': 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 *Note `UPDATE': update. statements are also supported. See *Note delete::, and *Note update::.  File: manual.info, Node: update, Prev: subqueries, Up: sql-syntax-data-manipulation 13.2.10 `UPDATE' Syntax ----------------------- Single-table syntax: UPDATE [LOW_PRIORITY] [IGNORE] TABLE_REFERENCE SET COL_NAME1={EXPR1|DEFAULT} [, COL_NAME2={EXPR2|DEFAULT}] ... [WHERE WHERE_CONDITION] [ORDER BY ...] [LIMIT ROW_COUNT] Multiple-table syntax: UPDATE [LOW_PRIORITY] [IGNORE] TABLE_REFERENCES SET COL_NAME1={EXPR1|DEFAULT} [, COL_NAME2={EXPR2|DEFAULT}] ... [WHERE WHERE_CONDITION] For the single-table syntax, the *Note `UPDATE': 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, *Note `UPDATE': update. updates rows in each table named in TABLE_REFERENCES that satisfy the conditions. In this case, `ORDER BY' and `LIMIT' cannot be used. WHERE_CONDITION is an expression that evaluates to true for each row to be updated. For expression syntax, see *Note expressions::. TABLE_REFERENCES and WHERE_CONDITION are is specified as described in *Note select::. You need the `UPDATE' privilege only for columns referenced in an *Note `UPDATE': update. that are actually updated. You need only the `SELECT' privilege for any columns that are read but not modified. The *Note `UPDATE': update. statement supports the following modifiers: * With the `LOW_PRIORITY' keyword, execution of the *Note `UPDATE': 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' keyword, the update statement does not abort even if errors occur during the update. Rows for which duplicate-key conflicts occur are not updated. Rows for which columns are updated to values that would cause data conversion errors are updated to the closest valid values instead. If you access a column from the table to be updated in an expression, *Note `UPDATE': 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 *Note `UPDATE': 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 *Note data-type-defaults::. *Note `UPDATE': update. returns the number of rows that were actually changed. The *Note `mysql_info()': mysql-info. C API function returns the number of rows that were matched and updated and the number of warnings that occurred during the *Note `UPDATE': update. You can use `LIMIT ROW_COUNT' to restrict the scope of the *Note `UPDATE': 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 *Note `UPDATE': 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 *Note `UPDATE': update. operations covering multiple tables. However, you cannot use `ORDER BY' or `LIMIT' with a multiple-table *Note `UPDATE': update. The TABLE_REFERENCES clause lists the tables involved in the join. Its syntax is described in *Note 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 *Note `UPDATE': update. statements can use any type of join permitted in *Note `SELECT': select. statements, such as `LEFT JOIN'. If you use a multiple-table *Note `UPDATE': 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 *Note innodb-foreign-key-constraints::. Currently, you cannot update a table and select from the same table in a subquery. Index hints (see *Note index-hints::) are accepted but ignored for *Note `UPDATE': update. statements. An `UPDATE' on a partitioned table using a storage engine such as *Note `MyISAM': myisam-storage-engine. that employs table-level locks locks all partitions of the table. This does not occur with tables using storage engines such as *Note `InnoDB': innodb-storage-engine. that employ row-level locking. This issue is resolved in MySQL 5.6. See *Note partitioning-limitations-locking::, for more information.  File: manual.info, Node: sql-syntax-transactions, Next: sql-syntax-replication, Prev: sql-syntax-data-manipulation, Up: sql-syntax 13.3 MySQL Transactional and Locking Statements =============================================== * Menu: * commit:: `START TRANSACTION', `COMMIT', and `ROLLBACK' Syntax * cannot-roll-back:: Statements That Cannot Be Rolled Back * implicit-commit:: Statements That Cause an Implicit Commit * savepoint:: `SAVEPOINT', `ROLLBACK TO SAVEPOINT', and `RELEASE SAVEPOINT' Syntax * lock-tables:: `LOCK TABLES' and `UNLOCK TABLES' Syntax * set-transaction:: `SET TRANSACTION' Syntax * xa:: XA Transactions MySQL supports local transactions (within a given client session) through statements such as *Note `SET autocommit': commit, *Note `START TRANSACTION': commit, *Note `COMMIT': commit, and *Note `ROLLBACK': commit. See *Note commit::. XA transaction support enables MySQL to participate in distributed transactions as well. See *Note xa::.  File: manual.info, Node: commit, Next: cannot-roll-back, Prev: sql-syntax-transactions, Up: sql-syntax-transactions 13.3.1 `START TRANSACTION', `COMMIT', and `ROLLBACK' Syntax ----------------------------------------------------------- START TRANSACTION [WITH CONSISTENT SNAPSHOT] 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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction): * `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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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. You can also begin a transaction like this: START TRANSACTION WITH CONSISTENT SNAPSHOT; The `WITH CONSISTENT SNAPSHOT' option starts a consistent read (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 *Note `SELECT': select. from any `InnoDB' table. See *Note innodb-consistent-read::. The `WITH CONSISTENT SNAPSHOT' option does not change the current transaction isolation level (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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. *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 *Note 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 *Note `InnoDB': innodb-storage-engine. or *Note `NDBCLUSTER': mysql-cluster.) 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 *Note server-system-variables::. `BEGIN' and `BEGIN WORK' are supported as aliases of `START TRANSACTION' for initiating a transaction. `START TRANSACTION' is standard SQL syntax and is the recommended way to start an ad-hoc transaction. The *Note `BEGIN': commit. statement differs from the use of the `BEGIN' keyword that starts a *Note `BEGIN ... END': begin-end. compound statement. The latter does not begin a transaction. See *Note begin-end::. *Note*: Within all stored programs (stored procedures and functions, triggers, and events), the parser treats `BEGIN [WORK]' as the beginning of a *Note `BEGIN ... END': 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 *Note 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 `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 *Note implicit-commit::, for more information. Beginning a transaction also causes table locks acquired with *Note `LOCK TABLES': lock-tables. to be released, as though you had executed *Note `UNLOCK TABLES': lock-tables. Beginning a transaction does not release a global read lock acquired with *Note `FLUSH TABLES WITH READ LOCK': flush. 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 *Note `SET TRANSACTION ISOLATION LEVEL': set-transaction. 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 *Note `ROLLBACK': commit. 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 *Note `COMMIT': 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 *Note `ROLLBACK': commit. statement at the end to ensure that modifications to the nontransactional tables are replicated.) See *Note binary-log::. You can change the isolation level for transactions with the *Note `SET TRANSACTION': set-transaction. statement. See *Note 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, *Note `SHOW PROCESSLIST': show-processlist. displays `Rolling back' in the `State' column for the session, not only for explicit rollbacks performed with the *Note `ROLLBACK': commit. statement but also for implicit rollbacks. *Note*: Beginning with MySQL 5.1.36, `BEGIN', `COMMIT', and `ROLLBACK' are no longer affected by `--replicate-do-db' or `--replicate-ignore-db' rules. (Bug #43263)  File: manual.info, Node: cannot-roll-back, Next: implicit-commit, Prev: commit, Up: sql-syntax-transactions 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 *Note `ROLLBACK': commit. statement.  File: manual.info, Node: implicit-commit, Next: savepoint, Prev: cannot-roll-back, Up: sql-syntax-transactions 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 *Note `COMMIT': commit. before executing the statement. * *Data definition language (DDL) statements that define or modify database objects.* `ALTER DATABASE ... UPGRADE DATA DIRECTORY NAME', *Note `ALTER EVENT': alter-event, *Note `ALTER PROCEDURE': alter-procedure, *Note `ALTER SERVER': alter-server, *Note `ALTER TABLE': alter-table, *Note `CREATE DATABASE': create-database, *Note `CREATE EVENT': create-event, *Note `CREATE INDEX': create-index, *Note `CREATE PROCEDURE': create-procedure, *Note `CREATE SERVER': create-server, *Note `CREATE TABLE': create-table, *Note `DROP DATABASE': drop-database, *Note `DROP EVENT': drop-event, *Note `DROP INDEX': drop-index, *Note `DROP PROCEDURE': drop-procedure, *Note `DROP SERVER': drop-server, *Note `DROP TABLE': drop-table, *Note `RENAME TABLE': rename-table, *Note `TRUNCATE TABLE': truncate-table. *Note `ALTER FUNCTION': alter-function, *Note `CREATE FUNCTION': create-function. and *Note `DROP FUNCTION': drop-function. also cause an implicit commit when used with stored functions, but not with UDFs. (*Note `ALTER FUNCTION': alter-function. can only be used with stored functions.) *Note `ALTER TABLE': alter-table, *Note `CREATE TABLE': create-table, and *Note `DROP TABLE': drop-table. do not commit a transaction if the `TEMPORARY' keyword is used. (This does not apply to other operations on temporary tables such as *Note `CREATE INDEX': create-index, which do cause a commit.) However, although no implicit commit occurs, neither can the statement be rolled back. Therefore, use of such statements will violate transaction atomicity: For example, if you use *Note `CREATE TEMPORARY TABLE': create-table. and then roll back the transaction, the table remains in existence. The *Note `CREATE TABLE': create-table. statement in `InnoDB' is processed as a single transaction. This means that a *Note `ROLLBACK': commit. from the user does not undo *Note `CREATE TABLE': create-table. statements the user made during that transaction. Beginning with MySQL 5.1.3, *Note `ALTER VIEW': alter-view, *Note `CREATE TRIGGER': create-trigger, *Note `CREATE VIEW': create-view, *Note `DROP TRIGGER': drop-trigger, and *Note `DROP VIEW': drop-view. cause an implicit commit. Beginning with MySQL 5.1.15, *Note `CREATE TABLE ... SELECT': create-table. 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'.) This is to prevent an issue during replication where the table could be created on the master after a rollback, but fail to be recorded in the binary log, and therefore not replicated to the slave. For more information, see Bug #22865. * *Statements that implicitly use or modify tables in the `mysql' database.* Beginning with MySQL 5.1.3, *Note `CREATE USER': create-user, *Note `DROP USER': drop-user, and *Note `RENAME USER': rename-user. cause an implicit commit. Beginning with MySQL 5.1.23, *Note `GRANT': grant, *Note `REVOKE': revoke, and *Note `SET PASSWORD': set-password. statements cause an implicit commit. * *Transaction-control and locking statements.* *Note `BEGIN': commit, *Note `LOCK TABLES': lock-tables, `SET autocommit = 1' (if the value is not already 1), *Note `START TRANSACTION': commit, *Note `UNLOCK TABLES': lock-tables. *Note `UNLOCK TABLES': lock-tables. commits a transaction only if any tables currently have been locked with *Note `LOCK TABLES': lock-tables. This does not occur for *Note `UNLOCK TABLES': lock-tables. following *Note `FLUSH TABLES WITH READ LOCK': flush. 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 *Note `START TRANSACTION': commit. 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 *Note `BEGIN': commit. statement differs from the use of the `BEGIN' keyword that starts a *Note `BEGIN ... END': begin-end. compound statement. The latter does not cause an implicit commit. See *Note begin-end::. * *Data loading statements.* *Note `LOAD DATA INFILE': load-data. Before MySQL 5.1.12, *Note `LOAD DATA INFILE': load-data. caused an implicit commit for all storage engines. As of MySQL 5.1.12, it causes an implicit commit only for tables using the *Note `NDB': mysql-cluster. storage engine. For more information, see Bug #11151. * *Administrative statements.* *Note `CACHE INDEX': cache-index, *Note `LOAD INDEX INTO CACHE': load-index. Beginning with MySQL 5.1.10, *Note `ANALYZE TABLE': analyze-table, *Note `CHECK TABLE': check-table, *Note `OPTIMIZE TABLE': optimize-table, and *Note `REPAIR TABLE': repair-table. cause an implicit commit.  File: manual.info, Node: savepoint, Next: lock-tables, Prev: implicit-commit, Up: sql-syntax-transactions 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 *Note `SAVEPOINT': savepoint, *Note `ROLLBACK TO SAVEPOINT': savepoint, *Note `RELEASE SAVEPOINT': savepoint. and the optional `WORK' keyword for *Note `ROLLBACK': commit. The *Note `SAVEPOINT': 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 *Note `ROLLBACK TO SAVEPOINT': 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 *Note `ROLLBACK TO SAVEPOINT': 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 *Note `RELEASE SAVEPOINT': 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 *Note `COMMIT': commit, or a *Note `ROLLBACK': commit. 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.  File: manual.info, Node: lock-tables, Next: set-transaction, Prev: savepoint, Up: sql-syntax-transactions 13.3.5 `LOCK TABLES' and `UNLOCK TABLES' Syntax ----------------------------------------------- * Menu: * lock-tables-and-transactions:: Interaction of Table Locking and Transactions * lock-tables-and-triggers:: `LOCK TABLES' and Triggers * lock-tables-restrictions:: Table-Locking Restrictions and Conditions 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. *Note `LOCK TABLES': 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, *Note `LOCK TABLES': 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 *Note `LOCK TABLES': lock-tables, any tables used in triggers are also locked implicitly, as described in *Note lock-tables-and-triggers::. *Note `UNLOCK TABLES': lock-tables. explicitly releases any table locks held by the current session. *Note `LOCK TABLES': lock-tables. implicitly releases any table locks held by the current session before acquiring new locks. Another use for *Note `UNLOCK TABLES': lock-tables. is to release the global read lock acquired with the *Note `FLUSH TABLES WITH READ LOCK': flush. statement, which enables you to lock all tables in all databases. See *Note 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. The session holding the lock, even a read lock, can perform table-level operations such as *Note `DROP TABLE': drop-table. Truncate operations are not transaction-safe, so an error occurs if the session attempts one during an active transaction or while holding a table lock. The following discussion applies only to non-`TEMPORARY' tables. *Note `LOCK 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 *Note `LOCK TABLES': lock-tables. and statements that cannot be used while *Note `LOCK TABLES': lock-tables. is in effect, see *Note lock-tables-restrictions:: *Rules for Lock Acquisition* To acquire table locks within the current session, use the *Note `LOCK TABLES': 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 *Note `INSERT': insert. statements (concurrent inserts) by other sessions to execute while the lock is held. (See *Note 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 affects lock scheduling if the `WRITE' lock request must wait, as described later. If the *Note `LOCK TABLES': 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 *Note `LOCK TABLES': 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 *Note `LOCK TABLES': 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 *Note `LOCK TABLES': 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 *Note `INSERT': insert. because there are two references to the same name for a locked table. The second *Note `INSERT': 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. A request for a `LOW_PRIORITY WRITE' lock, by contrast, permits subsequent `READ' lock requests by other sessions to be satisfied first if they occur while the `LOW_PRIORITY WRITE' request is waiting. You should use `LOW_PRIORITY WRITE' locks only if you are sure that eventually there will be a time when no sessions have a `READ' lock. For `InnoDB' tables in transactional mode (autocommit = 0), a waiting `LOW_PRIORITY WRITE' lock acts like a regular `WRITE' lock and causes subsequent `READ' lock requests to wait. *Note `LOCK TABLES': 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. There are, however, other things you need to be aware of about this policy: If you are using a `LOW_PRIORITY WRITE' lock for a table, it means only that MySQL waits for this particular lock until there are no other sessions that want a `READ' lock. When the session has gotten the `WRITE' lock and is waiting to get the lock for the next table in the lock table list, all other sessions wait for the `WRITE' lock to be released. If this becomes a serious problem with your application, you should consider converting some of your tables to transaction-safe tables. *Note*: `LOCK TABLES' or `UNLOCK TABLES', when applied to a partitioned table, always locks or unlocks the entire table. See *Note 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 *Note `UNLOCK TABLES': lock-tables. * If a session issues a *Note `LOCK TABLES': 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 *Note `START TRANSACTION': commit.), an implicit *Note `UNLOCK TABLES': lock-tables. is performed, which causes existing locks to be released. (For additional information about the interaction between table locking and transactions, see *Note 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 *Note auto-reconnect::. *Note*: If you use *Note `ALTER TABLE': alter-table. on a locked table, it may become unlocked. For example, if you attempt a second *Note `ALTER TABLE': 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 *Note alter-table-problems::.  File: manual.info, Node: lock-tables-and-transactions, Next: lock-tables-and-triggers, Prev: lock-tables, Up: lock-tables 13.3.5.1 Interaction of Table Locking and Transactions ...................................................... *Note `LOCK TABLES': lock-tables. and *Note `UNLOCK TABLES': lock-tables. interact with the use of transactions as follows: * *Note `LOCK TABLES': lock-tables. is not transaction-safe and implicitly commits any active transaction before attempting to lock the tables. * *Note `UNLOCK TABLES': lock-tables. implicitly commits any active transaction, but only if *Note `LOCK TABLES': lock-tables. has been used to acquire table locks. For example, in the following set of statements, *Note `UNLOCK TABLES': lock-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 *Note `START TRANSACTION': commit.) implicitly commits any current transaction and releases existing table locks. * *Note `FLUSH TABLES WITH READ LOCK': flush. acquires a global read lock and not table locks, so it is not subject to the same behavior as *Note `LOCK TABLES': lock-tables. and *Note `UNLOCK TABLES': lock-tables. with respect to table locking and implicit commits. For example, *Note `START TRANSACTION': commit. does not release the global read lock. See *Note flush::. * Other statements that implicitly cause transactions to be committed do not release existing table locks. For a list of such statements, see *Note implicit-commit::. * The correct way to use *Note `LOCK TABLES': lock-tables. and *Note `UNLOCK TABLES': lock-tables. with transactional tables, such as `InnoDB' tables, is to begin a transaction with `SET autocommit = 0' (not *Note `START TRANSACTION': commit.) followed by *Note `LOCK TABLES': lock-tables, and to not call *Note `UNLOCK TABLES': lock-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 *Note `LOCK TABLES': 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 *Note `UNLOCK TABLES': lock-tables. You should not have `autocommit = 1', because then `InnoDB' releases its internal table lock immediately after the call of *Note `LOCK TABLES': 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. * *Note `ROLLBACK': commit. does not release table locks.  File: manual.info, Node: lock-tables-and-triggers, Next: lock-tables-restrictions, Prev: lock-tables-and-transactions, Up: lock-tables 13.3.5.2 `LOCK TABLES' and Triggers ................................... If you lock a table explicitly with *Note `LOCK TABLES': 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 *Note `LOCK TABLES': 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 *Note `LOCK TABLES': 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 *Note `LOCK TABLES': 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.  File: manual.info, Node: lock-tables-restrictions, Prev: lock-tables-and-triggers, Up: lock-tables 13.3.5.3 Table-Locking Restrictions and Conditions .................................................. You can safely use *Note `KILL': kill. to terminate a session that is waiting for a table lock. See *Note kill::. You should _not_ lock any tables that you are using with *Note `INSERT DELAYED': insert-delayed. An *Note `INSERT DELAYED': insert-delayed. in this case results in an error because the insert must be handled by a separate thread, not by the session which holds the lock. *Note `LOCK TABLES': lock-tables. and *Note `UNLOCK TABLES': lock-tables. cannot be used within stored programs. For some operations, system tables in the `mysql' database must be accessed. For example, the *Note `HELP': help. statement requires the contents of the server-side help tables, and `CONVERT_TZ()' might need to read the time zone tables. Before MySQL 5.1.17, to perform such operations while a *Note `LOCK TABLES': lock-tables. statement is in effect, you must also lock the requisite system tables explicitly or a lock error occurs. As of 5.1.17, 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 *Note `LOCK TABLES': 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 *Note `UPDATE': 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 *Note `UNLOCK TABLES': lock-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 *Note `LOCK TABLES': lock-tables. if you want to ensure that no other session modifies the tables between a *Note `SELECT': select. and an *Note `UPDATE': update. The example shown here requires *Note `LOCK TABLES': 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 *Note `LOCK TABLES': lock-tables, it is possible that another session might insert a new row in the `trans' table between execution of the *Note `SELECT': select. and *Note `UPDATE': update. statements. You can avoid using *Note `LOCK TABLES': lock-tables. in many cases by using relative updates (`UPDATE customer SET VALUE=VALUE+NEW_VALUE') or the `LAST_INSERT_ID()' function. See *Note ansi-diff-transactions::. 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 *Note miscellaneous-functions::. See *Note internal-locking::, for more information on locking policy.  File: manual.info, Node: set-transaction, Next: xa, Prev: lock-tables, Up: sql-syntax-transactions 13.3.6 `SET TRANSACTION' Syntax ------------------------------- SET [GLOBAL | SESSION] TRANSACTION ISOLATION LEVEL { REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED | SERIALIZABLE } This statement sets the transaction isolation level, used for operations on *Note `InnoDB': innodb-storage-engine. tables. * Scope of the Isolation Level * You can set the isolation level globally, for the current session, or for the next transaction: * With the `GLOBAL' keyword, the statement sets the default transaction level globally for all subsequent sessions. Existing sessions are unaffected. * With the `SESSION' keyword, the statement sets the default transaction level for all subsequent transactions performed within the current session. * Without any `SESSION' or `GLOBAL' keyword, the statement sets the isolation level for the next (not started) transaction performed within the current session. A change to the global default isolation level requires the `SUPER' privilege. Any session is free to change its session isolation level (even in the middle of a transaction), or the isolation level for its next transaction. *Note `SET TRANSACTION ISOLATION LEVEL': 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 isolation level 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 *Note `mysqld': 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 `tx_isolation' system variable: SELECT @@GLOBAL.tx_isolation, @@tx_isolation; SET GLOBAL tx_isolation='REPEATABLE-READ'; SET SESSION tx_isolation='SERIALIZABLE'; * Details and Usage of Isolation Levels * `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. For full information about how these isolation levels work with `InnoDB' transactions, see *Note innodb-transaction-model::. In particular, for additional information about `InnoDB' record-level locks and how it uses them to execute various types of statements, see *Note innodb-record-level-locks:: and *Note innodb-locks-set::. 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'. For consistent reads, there is an important difference from the `READ COMMITTED' isolation level: All consistent reads within the same transaction read the snapshot established by the first read. This convention means that if you issue several plain (nonlocking) *Note `SELECT': select. statements within the same transaction, these *Note `SELECT': select. statements are consistent also with respect to each other. See *Note innodb-consistent-read::. For locking reads (*Note `SELECT': select. with `FOR UPDATE' or `LOCK IN SHARE MODE'), *Note `UPDATE': update, and *Note `DELETE': 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 (gap plus index-record) locks to block insertions by other sessions into the gaps covered by the range. * `READ COMMITTED' A somewhat Oracle-like isolation level with respect to consistent (nonlocking) reads: Each consistent read, even within the same transaction, sets and reads its own fresh snapshot. See *Note innodb-consistent-read::. For locking reads (*Note `SELECT': select. with `FOR UPDATE' or `LOCK IN SHARE MODE'), *Note `UPDATE': update. statements, and *Note `DELETE': 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. *Note*: In MySQL 5.1, when `READ COMMITTED' isolation level is used or the `innodb_locks_unsafe_for_binlog' system variable is enabled, there is no `InnoDB' gap locking except for foreign-key constraint checking and duplicate-key checking. Also, record locks for nonmatching rows are released after MySQL has evaluated the `WHERE' condition. As of MySQL 5.1, if you use `READ COMMITTED' or enable `innodb_locks_unsafe_for_binlog', you _must_ use row-based binary logging. * `READ UNCOMMITTED' *Note `SELECT': 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 *Note `SELECT': select. statements to *Note `SELECT ... LOCK IN SHARE MODE': select. if autocommit is disabled. If autocommit is enabled, the *Note `SELECT': 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 *Note `SELECT': select. to block if other transactions have modified the selected rows, disable autocommit.)  File: manual.info, Node: xa, Prev: set-transaction, Up: sql-syntax-transactions 13.3.7 XA Transactions ---------------------- * Menu: * xa-statements:: XA Transaction SQL Syntax * xa-states:: XA Transaction States 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 *Note 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. Currently, among the MySQL Connectors, MySQL Connector/J 5.0.0 supports XA directly (by means of a class interface that handles the Xan 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. (However, for a distributed transaction, you must use the `SERIALIZABLE' isolation level to achieve ACID properties. It is enough to use `REPEATABLE READ' for a nondistributed transaction, but not for a distributed transaction.) 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 MySQL 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.  File: manual.info, Node: xa-statements, Next: xa-states, Prev: xa, Up: xa 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 For *Note `XA START': xa-statements, the `JOIN' and `RESUME' clauses are not supported. For *Note `XA END': xa-statements. 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 (`0x6162', `X'ab''), 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 *Note `XA RECOVER': xa-statements. statement. `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 *Note `XA START': xa-statements. 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 *Note `XA RECOVER': xa-statements. statement returns information for those XA transactions on the MySQL server that are in the `PREPARED' state. (See *Note xa-states::.) The output includes a row for each such XA transaction on the server, regardless of which client started it. *Note `XA RECOVER': xa-statements. 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  File: manual.info, Node: xa-states, Prev: xa-statements, Up: xa 13.3.7.2 XA Transaction States .............................. An XA transaction progresses through the following states: 1. Use *Note `XA START': xa-statements. 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 *Note `XA END': xa-statements. statement. *Note `XA END': xa-statements. puts the transaction in the `IDLE' state. 3. For an `IDLE' XA transaction, you can issue either an *Note `XA PREPARE': xa-statements. statement or an `XA COMMIT ... ONE PHASE' statement: * *Note `XA PREPARE': xa-statements. puts the transaction in the `PREPARED' state. An *Note `XA RECOVER': xa-statements. statement at this point will include the transaction's XID value in its output, because *Note `XA RECOVER': xa-statements. 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 *Note `XA RECOVER': xa-statements. because the transaction terminates. 4. For a `PREPARED' XA transaction, you can issue an *Note `XA COMMIT': xa-statements. statement to commit and terminate the transaction, or *Note `XA ROLLBACK': xa-statements. 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 *Note `XA START': xa-statements. 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 *Note `START TRANSACTION': commit, no XA statements can be used until the transaction has been committed or rolled back. Note that 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 *Note implicit-commit::.  File: manual.info, Node: sql-syntax-replication, Next: sql-syntax-prepared-statements, Prev: sql-syntax-transactions, Up: sql-syntax 13.4 Replication Statements =========================== * Menu: * replication-master-sql:: SQL Statements for Controlling Master Servers * replication-slave-sql:: SQL Statements for Controlling Slave Servers Replication can be controlled through the SQL interface using the statements described in this section. One group of statements controls master servers, the other controls slave servers.  File: manual.info, Node: replication-master-sql, Next: replication-slave-sql, Prev: sql-syntax-replication, Up: sql-syntax-replication 13.4.1 SQL Statements for Controlling Master Servers ---------------------------------------------------- * Menu: * purge-binary-logs:: `PURGE BINARY LOGS' Syntax * reset-master:: `RESET MASTER' Syntax * set-sql-log-bin:: `SET sql_log_bin' Syntax This section discusses statements for managing master replication servers. *Note replication-slave-sql::, discusses statements for managing slave servers. In addition to the statements described here, the following *Note `SHOW': show. statements are used with master servers in replication. For information about these statements, see *Note show::. * *Note `SHOW BINARY LOGS': show-binary-logs. * *Note `SHOW BINLOG EVENTS': show-binlog-events. * *Note `SHOW MASTER STATUS': show-master-status. * *Note `SHOW SLAVE HOSTS': show-slave-hosts.  File: manual.info, Node: purge-binary-logs, Next: reset-master, Prev: replication-master-sql, Up: replication-master-sql 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 *Note binary-log::). The *Note `PURGE BINARY LOGS': 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 *Note `DATETIME': 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 nothing and fails with an error. 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 *Note `SHOW SLAVE STATUS': 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 *Note `SHOW BINARY LOGS': 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 *Note 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. Prior to MySQL 5.1.24, `PURGE BINARY LOGS TO' and `PURGE BINARY LOGS BEFORE' did not behave in the same way (and neither one behaved correctly) 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). Beginning with MySQL 5.1.24, both variants of the statement fail with an error in such cases. (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 *Note `PURGE BINARY LOGS': purge-binary-logs. statement that failed.  File: manual.info, Node: reset-master, Next: set-sql-log-bin, Prev: purge-binary-logs, Up: replication-master-sql 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. This statement is intended to be used only when the master is started for the first time. *Important*: The effects of *Note `RESET MASTER': reset-master. differ from those of *Note `PURGE BINARY LOGS': purge-binary-logs. in 2 key ways: 1. *Note `RESET MASTER': 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 *Note `PURGE BINARY LOGS': purge-binary-logs. 2. *Note `RESET MASTER': reset-master. is _not_ intended to be used while any replication slaves are running. The behavior of *Note `RESET MASTER': reset-master. when used while slaves are running is undefined (and thus unsupported), whereas *Note `PURGE BINARY LOGS': purge-binary-logs. may be safely used while replication slaves are running. See also *Note purge-binary-logs::. *Note `RESET MASTER': 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 *Note 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 *Note `STOP SLAVE': stop-slave. followed by *Note `RESET SLAVE': reset-slave. on the slave, then verify that any unwanted data no longer exists on the slave. 5. Issue *Note `RESET MASTER': reset-master. on the master to clean up the test queries. After verifying the setup and getting rid of any unwanted and log files generated by testing, you can start the slave and begin replicating.  File: manual.info, Node: set-sql-log-bin, Prev: reset-master, Up: replication-master-sql 13.4.1.3 `SET sql_log_bin' Syntax ................................. SET sql_log_bin = {0|1} Disables or enables binary logging for the current session (`sql_log_bin' is a session variable) if the client has the `SUPER' privilege. The statement fails with an error if the client does not have that privilege.  File: manual.info, Node: replication-slave-sql, Prev: replication-master-sql, Up: sql-syntax-replication 13.4.2 SQL Statements for Controlling Slave Servers --------------------------------------------------- * Menu: * change-master-to:: `CHANGE MASTER TO' Syntax * load-data-from-master:: `LOAD DATA FROM MASTER' Syntax * load-table-from-master:: `LOAD TABLE TBL_NAME FROM MASTER' Syntax * master-pos-wait:: `MASTER_POS_WAIT()' Syntax * reset-slave:: `RESET SLAVE' Syntax * set-global-sql-slave-skip-counter:: `SET GLOBAL sql_slave_skip_counter' Syntax * start-slave:: `START SLAVE' Syntax * stop-slave:: `STOP SLAVE' Syntax This section discusses statements for managing slave replication servers. *Note replication-master-sql::, discusses statements for managing master servers. In addition to the statements described here, *Note `SHOW SLAVE STATUS': show-slave-status. is also used with replication slaves. For information about this statement, see *Note show-slave-status::.  File: manual.info, Node: change-master-to, Next: load-data-from-master, Prev: replication-slave-sql, Up: replication-slave-sql 13.4.2.1 `CHANGE MASTER TO' Syntax .................................. CHANGE MASTER TO OPTION [, 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_HEARTBEAT_PERIOD = INTERVAL | MASTER_LOG_FILE = 'MASTER_LOG_NAME' | MASTER_LOG_POS = MASTER_LOG_POS | 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_KEY = 'KEY_FILE_NAME' | MASTER_SSL_CIPHER = 'CIPHER_LIST' | MASTER_SSL_VERIFY_SERVER_CERT = {0|1} | IGNORE_SERVER_IDS = (SERVER_ID_LIST) SERVER_ID_LIST: [SERVER_ID [, SERVER_ID] ... ] *Note `CHANGE MASTER TO': 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' files. To use *Note `CHANGE MASTER TO': change-master-to, the slave replication threads must be stopped (use *Note `STOP SLAVE': stop-slave. if necessary). 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, you just need to issue these statements to tell the slave about the new password: STOP SLAVE; -- if replication was running CHANGE MASTER TO MASTER_PASSWORD='new3cret'; START SLAVE; -- if you want to restart replication `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. Setting this option to an empty string causes *Note `START SLAVE': start-slave. subsequently to fail. This issue is addressed in MySQL 5.5. (Bug #28796) * `MASTER_USER' and `MASTER_PASSWORD' are the user name and password of the account to use for connecting to the master. Currently, a password used for a replication slave account is effectively limited to 32 characters in length; the password can be longer, but 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.) The text of a running *Note `CHANGE MASTER TO': change-master-to. statement, including values for `MASTER_USER' and `MASTER_PASSWORD', can be seen in the output of a concurrent *Note `SHOW PROCESSLIST': show-processlist. statement. The `MASTER_SSL_XXX' options provide information about using SSL for the connection. They correspond to the `--ssl-XXX' options described in *Note ssl-options::, and *Note replication-solutions-ssl::. `MASTER_SSL_VERIFY_SERVER_CERT' was added in MySQL 5.1.18. These options can be changed even on slaves that are compiled without SSL support. They are saved to the `master.info' file, but are ignored if the slave does not have SSL support enabled. `MASTER_CONNECT_RETRY' specifies how many seconds to wait between connect retries. The default is 60. The _number_ of reconnection attempts is limited by the `--master-retry-count' server option; for more information, see *Note replication-options::. The next two options (`MASTER_BIND' and `MASTER_HEARTBEAT_PERIOD') are available in MySQL Cluster NDB 6.3 and later, but are not supported in mainline MySQL 5.1: `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 ability to bind a replication slave to specific network interface was added in MySQL Cluster NDB 6.3.4. `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. 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 *Note `RESET SLAVE': reset-slave. on the heartbeat interval is to reset it to the default value. `MASTER_HEARTBEAT_PERIOD' was added in MySQL Cluster NDB 6.3.4. `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 neither of `MASTER_LOG_FILE' or `MASTER_LOG_POS' is specified, the slave uses the last coordinates of the _slave SQL thread_ before *Note `CHANGE MASTER TO': 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. *Note `CHANGE MASTER TO': 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. `IGNORE_SERVER_IDS' was added in MySQL Cluster NDB 6.1.29, MySQL Cluster NDB 6.3.31, MySQL Cluster NDB 7.0.11, and MySQL Cluster NDB 7.1.0 (see Bug #47037). This option 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 *Note `CHANGE MASTER TO': 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 *Note `CHANGE MASTER TO': change-master-to. statement is issued without any `IGNORE_SERVER_IDS' option, any existing list is preserved; *Note `RESET SLAVE': reset-slave. also has no effect on the server ID list. To clear the list of ignored servers, it is necessary to use the option with an empty list: CHANGE MASTER TO IGNORE_SERVER_IDS = (); 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. Beginning with MySQL 5.1.47, invoking *Note `CHANGE MASTER TO': 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. *Note `CHANGE MASTER TO': 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 to the slave, 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.mycompany.com', MASTER_USER='replication', MASTER_PASSWORD='bigs3cret', 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 *Note `CHANGE MASTER TO': 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 *Note `STOP SLAVE': stop-slave, shut down the server, delete the `master.info' and `relay-log.info' files, 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. This table shows the maximum permissible length for `MASTER_POS_WAIT()' 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_KEY'255 `MASTER_SSL_CIPHER'511  File: manual.info, Node: load-data-from-master, Next: load-table-from-master, Prev: change-master-to, Up: replication-slave-sql 13.4.2.2 `LOAD DATA FROM MASTER' Syntax ....................................... LOAD DATA FROM MASTER *This feature is deprecated and should be avoided. It is subject to removal in a future version of MySQL.* Since the current implementation of `LOAD DATA FROM MASTER' and `LOAD TABLE FROM MASTER' is very limited, these statements are deprecated as of MySQL 4.1 and removed in MySQL 5.5. The recommended alternative solution to using `LOAD DATA FROM MASTER' or `LOAD TABLE FROM MASTER' is using *Note `mysqldump': mysqldump. or *Note `mysqlhotcopy': mysqlhotcopy. The latter requires Perl and two Perl modules (`DBI' and `DBD:mysql') and works for `MyISAM' and `ARCHIVE' tables only. With *Note `mysqldump': mysqldump, you can create SQL dumps on the master and pipe (or copy) these to a *Note `mysql': mysql. client on the slave. This has the advantage of working for all storage engines, but can be quite slow, since it works using *Note `SELECT': select. This statement takes a snapshot of the master and copies it to the slave. It updates the values of `MASTER_LOG_FILE' and `MASTER_LOG_POS' so that the slave starts replicating from the correct position. Any table and database exclusion rules specified with the `--replicate-*-do-*' and `--replicate-*-ignore-*' options are honored. `--replicate-rewrite-db' is _not_ taken into account because a user could use this option to set up a nonunique mapping such as `--replicate-rewrite-db="db1->db3"' and `--replicate-rewrite-db="db2->db3"', which would confuse the slave when loading tables from the master. Use of this statement is subject to the following conditions: * It works only for `MyISAM' tables. Attempting to load a non-`MyISAM' table results in the following error: ERROR 1189 (08S01): Net error reading from master * It acquires a global read lock on the master while taking the snapshot, which prevents updates on the master during the load operation. If you are loading large tables, you might have to increase the values of `net_read_timeout' and `net_write_timeout' on both the master and slave servers. See *Note server-system-variables::. Note that `LOAD DATA FROM MASTER' does _not_ copy any tables from the `mysql' database. This makes it easy to have different users and privileges on the master and the slave. To use `LOAD DATA FROM MASTER', the replication account that is used to connect to the master must have the `RELOAD' and `SUPER' privileges on the master and the `SELECT' privilege for all master tables you want to load. All master tables for which the user does not have the *Note `SELECT': select. privilege are ignored by `LOAD DATA FROM MASTER'. This is because the master hides them from the user: `LOAD DATA FROM MASTER' calls *Note `SHOW DATABASES': show-databases. to know the master databases to load, but *Note `SHOW DATABASES': show-databases. returns only databases for which the user has some privilege. See *Note show-databases::. On the slave side, the user that issues `LOAD DATA FROM MASTER' must have privileges for dropping and creating the databases and tables that are copied.  File: manual.info, Node: load-table-from-master, Next: master-pos-wait, Prev: load-data-from-master, Up: replication-slave-sql 13.4.2.3 `LOAD TABLE TBL_NAME FROM MASTER' Syntax ................................................. LOAD TABLE TBL_NAME FROM MASTER *This feature is deprecated and should be avoided. It is subject to removal in a future version of MySQL.* Since the current implementation of `LOAD DATA FROM MASTER' and `LOAD TABLE FROM MASTER' is very limited, these statements are deprecated as of MySQL 4.1 and removed in MySQL 5.5. The recommended alternative solution to using `LOAD DATA FROM MASTER' or `LOAD TABLE FROM MASTER' is using *Note `mysqldump': mysqldump. or *Note `mysqlhotcopy': mysqlhotcopy. The latter requires Perl and two Perl modules (`DBI' and `DBD:mysql') and works for `MyISAM' and `ARCHIVE' tables only. With *Note `mysqldump': mysqldump, you can create SQL dumps on the master and pipe (or copy) these to a *Note `mysql': mysql. client on the slave. This has the advantage of working for all storage engines, but can be quite slow, since it works using *Note `SELECT': select. Transfers a copy of the table from the master to the slave. This statement is implemented mainly debugging `LOAD DATA FROM MASTER' operations. To use `LOAD TABLE', the account used for connecting to the master server must have the `RELOAD' and `SUPER' privileges on the master and the `SELECT' privilege for the master table to load. On the slave side, the user that issues `LOAD TABLE FROM MASTER' must have privileges for dropping and creating the table. The conditions for `LOAD DATA FROM MASTER' apply here as well. For example, `LOAD TABLE FROM MASTER' works only for `MyISAM' tables. The timeout notes for `LOAD DATA FROM MASTER' apply as well.  File: manual.info, Node: master-pos-wait, Next: reset-slave, Prev: load-table-from-master, Up: replication-slave-sql 13.4.2.4 `MASTER_POS_WAIT()' Syntax ................................... SELECT MASTER_POS_WAIT('MASTER_LOG_FILE', MASTER_LOG_POS [, TIMEOUT]) 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 *Note miscellaneous-functions::, for a full description.  File: manual.info, Node: reset-slave, Next: set-global-sql-slave-skip-counter, Prev: master-pos-wait, Up: replication-slave-sql 13.4.2.5 `RESET SLAVE' Syntax ............................. RESET SLAVE *Note `RESET SLAVE': 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 deletes the `master.info' and `relay-log.info' files, all the relay log files, and starts a new relay log file. To use *Note `RESET SLAVE': reset-slave, the slave replication threads must be stopped (use *Note `STOP SLAVE': stop-slave. if necessary). *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 *Note `STOP SLAVE': stop-slave. statement or if the slave is highly loaded.) If any startup options for setting connection parameters (such as master host, master port, master user, and master password) are in use, then any corresponding connection information stored in the `master.info' file is immediately reset using the values specified for these options. Options for which values are not specified are cleared. However, since these options are deprecated in MySQL 5.1 and removed altogether from MySQL 5.5, you are encouraged to use a *Note `CHANGE MASTER TO': change-master-to. statement instead to reset the connection parameters. (If you do not use the startup options, you must issue *Note `CHANGE MASTER TO': change-master-to. in such cases if you do not want the connection settings to be cleared.) If the slave SQL thread was in the middle of replicating temporary tables when it was stopped, and *Note `RESET SLAVE': reset-slave. is issued, these replicated temporary tables are deleted on the slave.  File: manual.info, Node: set-global-sql-slave-skip-counter, Next: start-slave, Prev: reset-slave, Up: replication-slave-sql 13.4.2.6 `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 *Note `SET GLOBAL sql_slave_skip_counter': 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. Beginning with MySQL 5.1.47, issuing this statement causes the previous values of `RELAY_LOG_FILE', `RELAY_LOG_POS', and `sql_slave_skip_counter' to be written to the error log.  File: manual.info, Node: start-slave, Next: stop-slave, Prev: set-global-sql-slave-skip-counter, Up: replication-slave-sql 13.4.2.7 `START SLAVE' Syntax ............................. START SLAVE [THREAD_TYPES] START SLAVE [SQL_THREAD] UNTIL MASTER_LOG_FILE = 'LOG_NAME', MASTER_LOG_POS = LOG_POS START SLAVE [SQL_THREAD] UNTIL RELAY_LOG_FILE = 'LOG_NAME', RELAY_LOG_POS = LOG_POS THREAD_TYPES: [THREAD_TYPE [, THREAD_TYPE] ... ] THREAD_TYPE: IO_THREAD | SQL_THREAD *Note `START SLAVE': 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. *Note `START SLAVE': start-slave. requires the `SUPER' privilege. If *Note `START SLAVE': 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). *Note `START SLAVE': 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 *Note `SHOW SLAVE STATUS': show-slave-status. *Note `START SLAVE': 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 *Note `START SLAVE': start-slave. causes *Note `SHOW SLAVE STATUS': 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 *Note show-slave-status::, and *Note replication-administration-status::. You can add `IO_THREAD' and `SQL_THREAD' options to the statement to name which of the threads to start. An `UNTIL' clause 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 or in the slave relay log. When the SQL thread reaches that point, 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. For an `UNTIL' clause, you must specify both a log file name and position. Do not mix master and relay log options. Any `UNTIL' condition is reset by a subsequent *Note `STOP SLAVE': stop-slave. statement, a *Note `START SLAVE': start-slave. statement that includes no `UNTIL' clause, or a server restart. 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 *Note `DROP TABLE': 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 *Note `mysqlbinlog': mysqlbinlog. with the master binary log or slave relay log, or by using a *Note `SHOW BINLOG EVENTS': 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 *Note `SHOW SLAVE STATUS': show-slave-status. statement includes output fields that display the current values of the `UNTIL' condition. In old versions of MySQL (before 4.0.5), this statement was called `SLAVE START'. This usage is still accepted in MySQL 5.1 for backward compatibility, but is deprecated and is removed in MySQL 5.6.  File: manual.info, Node: stop-slave, Prev: start-slave, Up: replication-slave-sql 13.4.2.8 `STOP SLAVE' Syntax ............................ STOP SLAVE [THREAD_TYPES] THREAD_TYPES: [THREAD_TYPE [, THREAD_TYPE] ... ] THREAD_TYPE: IO_THREAD | SQL_THREAD Stops the slave threads. *Note `STOP SLAVE': stop-slave. requires the `SUPER' privilege. Recommended best practice is to execute `STOP SLAVE' on the slave before stopping the slave server (see *Note server-shutdown::, for more information). _When using the row-based logging format_: Prior to MySQL 5.1.35, you should _always_ execute `STOP SLAVE' on the slave before stopping the slave server to help avoid the possibility of an inconsistent slave; in MySQL 5.1.35 and later, you should execute this statement 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). In MySQL 5.1.55 and later, you can also use `STOP SLAVE SQL_THREAD' for this purpose. Like *Note `START SLAVE': start-slave, this statement may be used with the `IO_THREAD' and `SQL_THREAD' options to name the thread or threads to be stopped. *Note*: The transactional behavior of *Note `STOP SLAVE': stop-slave. changed in MySQL 5.1.35. Previously, it took effect immediately. Beginning with MySQL 5.1.35, it waits until any current replication event group affecting one or more nontransactional tables has finished executing (if there is any such replication group), or until the user issues a *Note `KILL QUERY': kill. or *Note `KILL CONNECTION': kill. statement. (Bug #319, Bug #38205) In old versions of MySQL (before 4.0.5), this statement was called `SLAVE STOP'. This usage is still accepted in MySQL 5.1 for backward compatibility, but is deprecated and is removed in MySQL 5.6.  File: manual.info, Node: sql-syntax-prepared-statements, Next: sql-syntax-compound-statements, Prev: sql-syntax-replication, Up: sql-syntax 13.5 SQL Syntax for Prepared Statements ======================================= * Menu: * prepare:: `PREPARE' Syntax * execute:: `EXECUTE' Syntax * deallocate-prepare:: `DEALLOCATE PREPARE' Syntax * statement-repreparation:: Automatic Prepared Statement Repreparation MySQL 5.1 provides support for server-side prepared statements. This support takes advantage of the efficient client/server binary protocol implemented in MySQL 4.1, provided that you use an appropriate client programming interface. Candidate interfaces include the MySQL C API client library (for C programs), MySQL Connector/J (for Java programs), and MySQL Connector/Net. For example, the C API provides a set of function calls that make up its prepared statement API. See *Note 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. 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 enables you to send SQL statements to the server to be executed, such as the *Note `mysql': mysql. client program. * You can use it even if the client is using an old version of the client library. The only requirement is that you be able to connect to a server that is recent enough to support SQL syntax for prepared statements. SQL syntax for prepared statements is intended to be used for situations such as these: * You want to test how prepared statements work in your application before coding it. * An application has problems executing prepared statements and you want to determine interactively what the problem is. * You want to create a test case that describes a problem you are having with prepared statements, so that you can file a bug report. * You need to use prepared statements but do not have access to a programming API that supports them. SQL syntax for prepared statements is based on three SQL statements: * *Note `PREPARE': prepare. prepares a statement for execution (see *Note prepare::). * *Note `EXECUTE': execute. executes a prepared statement (see *Note execute::). * *Note `DEALLOCATE PREPARE': deallocate-prepare. releases a prepared statement (see *Note 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. The following SQL statements can be used in prepared statements: ALTER TABLE CALL COMMIT {CREATE | DROP} INDEX {CREATE | DROP} TABLE DELETE DO INSERT RENAME TABLE REPLACE SELECT SET SHOW (most variants) TRUNCATE TABLE UPDATE As of MySQL 5.1.10, the following additional statements are supported: ANALYZE TABLE OPTIMIZE TABLE REPAIR TABLE As of MySQL 5.1.12, the following additional statements are supported: CACHE INDEX CHANGE MASTER CHECKSUM {TABLE | TABLES} {CREATE | RENAME | DROP} DATABASE {CREATE | RENAME | DROP} USER FLUSH {TABLE | TABLES | TABLES WITH READ LOCK | HOSTS | PRIVILEGES | LOGS | STATUS | MASTER | SLAVE | DES_KEY_FILE | USER_RESOURCES} GRANT INSTALL PLUGIN KILL LOAD INDEX INTO CACHE RESET {MASTER | SLAVE | QUERY CACHE} REVOKE SHOW {AUTHORS | CONTRIBUTORS | WARNINGS | ERRORS} SHOW BINLOG EVENTS SHOW CREATE {PROCEDURE | FUNCTION | EVENT | TABLE | VIEW} SHOW {MASTER | BINARY} LOGS SHOW {MASTER | SLAVE} STATUS SLAVE {START | STOP} UNINSTALL PLUGIN Other statements are not supported in MySQL 5.1. Generally, statements not permitted in SQL prepared statements are also not permitted in stored programs. Exceptions are noted in *Note 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 *Note statement-repreparation::. Placeholders can be used for the arguments of the `LIMIT' clause when using prepared statements. See *Note select::. In prepared *Note `CALL': call. statements used with *Note `PREPARE': prepare. and *Note `EXECUTE': execute, placeholder support for `OUT' and `INOUT' parameters is not available in MySQL 5.1. See *Note call::, for an example and a workaround. 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 *Note `PREPARE': prepare. cannot itself be a *Note `PREPARE': prepare, *Note `EXECUTE': execute, or *Note `DEALLOCATE PREPARE': deallocate-prepare. statement. SQL syntax for prepared statements is distinct from using prepared statement API calls. For example, you cannot use the *Note `mysql_stmt_prepare()': mysql-stmt-prepare. C API function to prepare a *Note `PREPARE': prepare, *Note `EXECUTE': execute, or *Note `DEALLOCATE PREPARE': 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 *Note `PREPARE': prepare. and *Note `EXECUTE': 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). Before MySQL 5.1.17, prepared statements do not use the query cache. As of 5.1.17, prepared statements use the query cache under the conditions described in *Note query-cache-operation::. To write C programs that use the *Note `CALL': call. SQL statement to execute stored procedures that contain prepared statements, the `CLIENT_MULTI_RESULTS' flag must be enabled. This is because each *Note `CALL': 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 *Note `mysql_real_connect()': 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 *Note call::.  File: manual.info, Node: prepare, Next: execute, Prev: sql-syntax-prepared-statements, Up: sql-syntax-prepared-statements 13.5.1 `PREPARE' Syntax ----------------------- PREPARE STMT_NAME FROM PREPARABLE_STMT The *Note `PREPARE': 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 *Note `EXECUTE': execute. and released with *Note `DEALLOCATE PREPARE': deallocate-prepare. For examples, see *Note 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 *Note 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 *Note user-variables::.  File: manual.info, Node: execute, Next: deallocate-prepare, Prev: prepare, Up: sql-syntax-prepared-statements 13.5.2 `EXECUTE' Syntax ----------------------- EXECUTE STMT_NAME [USING @VAR_NAME [, @VAR_NAME] ...] After preparing a statement with *Note `PREPARE': prepare, you execute it with an *Note `EXECUTE': 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 *Note sql-syntax-prepared-statements::.  File: manual.info, Node: deallocate-prepare, Next: statement-repreparation, Prev: execute, Up: sql-syntax-prepared-statements 13.5.3 `DEALLOCATE PREPARE' Syntax ---------------------------------- {DEALLOCATE | DROP} PREPARE STMT_NAME To deallocate a prepared statement produced with *Note `PREPARE': prepare, use a *Note `DEALLOCATE PREPARE': deallocate-prepare. statement that refers to the prepared statement name. Attempting to execute a prepared statement after deallocating it results in an error. For examples, see *Note sql-syntax-prepared-statements::.  File: manual.info, Node: statement-repreparation, Prev: deallocate-prepare, Up: sql-syntax-prepared-statements 13.5.4 Automatic Prepared Statement Repreparation ------------------------------------------------- As of MySQL 5.1.25, 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. This applies to prepared statements processed at the SQL level (using the *Note `PREPARE': prepare. statement) and those processed using the binary client/server protocol (using the *Note `mysql_stmt_prepare()': mysql-stmt-prepare. C API function). The server attempts repreparation up to three times. An error occurs if all attempts fail. Metadata changes occur for DDL statements such as those that create, drop, alter, rename, or truncate tables, or that analyze, optimize, or repair tables. Repreparation 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 *Note `FLUSH TABLES': flush. Table content changes (for example, with *Note `INSERT': insert. or *Note `UPDATE': update.) do not cause repreparation, nor do *Note `SELECT': select. statements. Repreparation is automatic, but to the extent that it occurs, diminishes prepared statement performance. Repreparation uses the default database and SQL mode that were in effect for the original preparation. The `Com_stmt_reprepare' status variable tracks the number of repreparations. An incompatibility with older versions of MySQL (before 5.1.25) is that a prepared statement may return a different set of columns or different column types from one execution to the next. For example, if the prepared statement is `SELECT * FROM t1', altering `t1' to contain a different number of columns causes the next execution to return a number of columns different from the previous execution. Older versions of the client library cannot handle this change in behavior. For applications that use prepared statements with a server that performs automatic repreparation, an upgrade to the new client library is strongly recommended.  File: manual.info, Node: sql-syntax-compound-statements, Next: sql-syntax-server-administration, Prev: sql-syntax-prepared-statements, Up: sql-syntax 13.6 MySQL Compound-Statement Syntax ==================================== * Menu: * begin-end:: `BEGIN ... END' Compound-Statement Syntax * statement-labels:: Statement Label Syntax * declare:: `DECLARE' Syntax * stored-program-variables:: Variables in Stored Programs * flow-control-statements:: Flow Control Statements * cursors:: Cursors * condition-handling:: Condition Handling This section describes the syntax for the *Note `BEGIN ... END': 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 *Note 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.  File: manual.info, Node: begin-end, Next: statement-labels, Prev: sql-syntax-compound-statements, Up: sql-syntax-compound-statements 13.6.1 `BEGIN ... END' Compound-Statement Syntax ------------------------------------------------ [BEGIN_LABEL:] BEGIN [STATEMENT_LIST] END [END_LABEL] *Note `BEGIN ... END': 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. *Note `BEGIN ... END': 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 *Note `mysql': 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 *Note stored-programs-defining::. A *Note `BEGIN ... END': begin-end. block can be labeled. See *Note 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 *Note `BEGIN [WORK]': commit. as the beginning of a *Note `BEGIN ... END': begin-end. block. To begin a transaction in this context, use *Note `START TRANSACTION': commit. instead.  File: manual.info, Node: statement-labels, Next: declare, Prev: begin-end, Up: sql-syntax-compound-statements 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 *Note `BEGIN ... END': begin-end. blocks and for the *Note `LOOP': loop, *Note `REPEAT': repeat, and *Note `WHILE': 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 *Note `ITERATE': iterate. or *Note `LEAVE': 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 *Note declare-handler::.  File: manual.info, Node: declare, Next: stored-program-variables, Prev: statement-labels, Up: sql-syntax-compound-statements 13.6.3 `DECLARE' Syntax ----------------------- The *Note `DECLARE': declare. statement is used to define various items local to a program: * Local variables. See *Note stored-program-variables::. * Conditions and handlers. See *Note condition-handling::. * Cursors. See *Note cursors::. *Note `DECLARE': declare. is permitted only inside a *Note `BEGIN ... END': 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.  File: manual.info, Node: stored-program-variables, Next: flow-control-statements, Prev: declare, Up: sql-syntax-compound-statements 13.6.4 Variables in Stored Programs ----------------------------------- * Menu: * declare-local-variable:: Local Variable `DECLARE' Syntax * local-variable-scope:: Local Variable Scope and Resolution 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 *Note `DECLARE': declare-local-variable. statement, as described in *Note declare-local-variable::. * Variables can be set directly with the *Note `SET': set-statement. statement. See *Note set-statement::. * Results from queries can be retrieved into local variables using *Note `SELECT ... INTO VAR_LIST': select-into. or by opening a cursor and using *Note `FETCH ... INTO VAR_LIST': fetch. See *Note select-into::, and *Note cursors::. For information about the scope of local variables and how MySQL resolves ambiguous names, see *Note local-variable-scope::.  File: manual.info, Node: declare-local-variable, Next: local-variable-scope, Prev: stored-program-variables, Up: stored-program-variables 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 *Note 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 *Note identifiers::. The scope of a local variable is the *Note `BEGIN ... END': 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.  File: manual.info, Node: local-variable-scope, Prev: declare-local-variable, Up: stored-program-variables 13.6.4.2 Local Variable Scope and Resolution ............................................ The scope of a local variable is the *Note `BEGIN ... END': 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 *Note prepare::. A local variable should not have the same name as a table column. If an SQL statement, such as a *Note `SELECT ... INTO': select. 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 *Note `SELECT': 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 *Note `SELECT': 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 *Note stored-program-restrictions::.  File: manual.info, Node: flow-control-statements, Next: cursors, Prev: stored-program-variables, Up: sql-syntax-compound-statements 13.6.5 Flow Control Statements ------------------------------ * Menu: * case:: `CASE' Syntax * if:: `IF' Syntax * iterate:: `ITERATE' Syntax * leave:: `LEAVE' Syntax * loop:: `LOOP' Syntax * repeat:: `REPEAT' Syntax * return:: `RETURN' Syntax * while:: `WHILE' Syntax MySQL supports the *Note `IF': if, *Note `CASE': case, *Note `ITERATE': iterate, *Note `LEAVE': leave. *Note `LOOP': loop, *Note `WHILE': while, and *Note `REPEAT': repeat. constructs for flow control within stored programs. It also supports *Note `RETURN': 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 *Note `IF': if. statement might contain a *Note `WHILE': while. loop, which itself contains a *Note `CASE': case. statement. MySQL does not support `FOR' loops.  File: manual.info, Node: case, Next: if, Prev: flow-control-statements, Up: flow-control-statements 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 *Note `CASE': case. statement for stored programs implements a complex conditional construct. *Note*: There is also a `CASE' _expression_, which differs from the *Note `CASE': case. _statement_ described here. See *Note control-flow-functions::. The *Note `CASE': 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 *Note 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 *Note `CASE': 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 *Note `BEGIN ... END': 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; |  File: manual.info, Node: if, Next: iterate, Prev: case, Up: flow-control-statements 13.6.5.2 `IF' Syntax .................... IF SEARCH_CONDITION THEN STATEMENT_LIST [ELSEIF SEARCH_CONDITION THEN STATEMENT_LIST] ... [ELSE STATEMENT_LIST] END IF The *Note `IF': if. statement for stored programs implements a basic conditional construct. *Note*: There is also an `IF()' _function_, which differs from the *Note `IF': if. _statement_ described here. See *Note control-flow-functions::. The *Note `IF': 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 *Note `IF': if. statements. Each *Note `IF': 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 *Note `IF': if. is evaluated only if `n' is not equal to `m'.  File: manual.info, Node: iterate, Next: leave, Prev: if, Up: flow-control-statements 13.6.5.3 `ITERATE' Syntax ......................... ITERATE LABEL *Note `ITERATE': iterate. can appear only within *Note `LOOP': loop, *Note `REPEAT': repeat, and *Note `WHILE': while. statements. *Note `ITERATE': iterate. means `start the loop again.' For an example, see *Note loop::.  File: manual.info, Node: leave, Next: loop, Prev: iterate, Up: flow-control-statements 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, *Note `LEAVE': leave. exits the program. *Note `LEAVE': leave. can be used within *Note `BEGIN ... END': begin-end. or loop constructs (*Note `LOOP': loop, *Note `REPEAT': repeat, *Note `WHILE': while.). For an example, see *Note loop::.  File: manual.info, Node: loop, Next: repeat, Prev: leave, Up: flow-control-statements 13.6.5.5 `LOOP' Syntax ...................... [BEGIN_LABEL:] LOOP STATEMENT_LIST END LOOP [END_LABEL] *Note `LOOP': 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 *Note `LEAVE': leave. statement. Within a stored function, *Note `RETURN': return. can also be used, which exits the function entirely. Neglecting to include a loop-termination statement results in an infinite loop. A *Note `LOOP': loop. statement can be labeled. For the rules regarding label use, see *Note 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;  File: manual.info, Node: repeat, Next: return, Prev: loop, Up: flow-control-statements 13.6.5.6 `REPEAT' Syntax ........................ [BEGIN_LABEL:] REPEAT STATEMENT_LIST UNTIL SEARCH_CONDITION END REPEAT [END_LABEL] The statement list within a *Note `REPEAT': repeat. statement is repeated until the SEARCH_CONDITION expression is true. Thus, a *Note `REPEAT': repeat. always enters the loop at least once. STATEMENT_LIST consists of one or more statements, each terminated by a semicolon (`;') statement delimiter. A *Note `REPEAT': repeat. statement can be labeled. For the rules regarding label use, see *Note 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)  File: manual.info, Node: return, Next: while, Prev: repeat, Up: flow-control-statements 13.6.5.7 `RETURN' Syntax ........................ RETURN EXPR The *Note `RETURN': return. statement terminates execution of a stored function and returns the value EXPR to the function caller. There must be at least one *Note `RETURN': 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 *Note `LEAVE': leave. statement can be used to exit a stored program of those types.  File: manual.info, Node: while, Prev: return, Up: flow-control-statements 13.6.5.8 `WHILE' Syntax ....................... [BEGIN_LABEL:] WHILE SEARCH_CONDITION DO STATEMENT_LIST END WHILE [END_LABEL] The statement list within a *Note `WHILE': 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 *Note `WHILE': while. statement can be labeled. For the rules regarding label use, see *Note statement-labels::. Example: CREATE PROCEDURE dowhile() BEGIN DECLARE v1 INT DEFAULT 5; WHILE v1 > 0 DO ... SET v1 = v1 - 1; END WHILE; END;  File: manual.info, Node: cursors, Next: condition-handling, Prev: flow-control-statements, Up: sql-syntax-compound-statements 13.6.6 Cursors -------------- * Menu: * close:: Cursor `CLOSE' Syntax * declare-cursor:: Cursor `DECLARE' Syntax * fetch:: Cursor `FETCH' Syntax * open:: Cursor `OPEN' Syntax 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;  File: manual.info, Node: close, Next: declare-cursor, Prev: cursors, Up: cursors 13.6.6.1 Cursor `CLOSE' Syntax .............................. CLOSE CURSOR_NAME This statement closes a previously opened cursor. For an example, see *Note cursors::. An error occurs if the cursor is not open. If not closed explicitly, a cursor is closed at the end of the *Note `BEGIN ... END': begin-end. block in which it was declared.  File: manual.info, Node: declare-cursor, Next: fetch, Prev: close, Up: cursors 13.6.6.2 Cursor `DECLARE' Syntax ................................ DECLARE CURSOR_NAME CURSOR FOR SELECT_STATEMENT This statement declares a cursor and associates it with a *Note `SELECT': select. statement that retrieves the rows to be traversed by the cursor. To fetch the rows later, use a *Note `FETCH': fetch. statement. The number of columns retrieved by the *Note `SELECT': select. statement must match the number of output variables specified in the *Note `FETCH': fetch. statement. The *Note `SELECT': 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 *Note cursors::. For information available through *Note `SHOW': show. statements, it is possible in many cases to obtain equivalent information by using a cursor with an `INFORMATION_SCHEMA' table.  File: manual.info, Node: fetch, Next: open, Prev: declare-cursor, Up: cursors 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 *Note `SELECT': 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 *Note `SELECT': select. statement must match the number of output variables specified in the *Note `FETCH': 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 *Note cursors::.  File: manual.info, Node: open, Prev: fetch, Up: cursors 13.6.6.4 Cursor `OPEN' Syntax ............................. OPEN CURSOR_NAME This statement opens a previously declared cursor. For an example, see *Note cursors::.  File: manual.info, Node: condition-handling, Prev: cursors, Up: sql-syntax-compound-statements 13.6.7 Condition Handling ------------------------- * Menu: * declare-condition:: `DECLARE ... CONDITION' Syntax * declare-handler:: `DECLARE ... HANDLER' Syntax 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 *Note `DECLARE ... CONDITION': declare-condition. statement. To declare a handler, use the *Note `DECLARE ... HANDLER': declare-handler. statement. See *Note declare-condition::, and *Note declare-handler::. Other statements related to conditions are `SIGNAL', `RESIGNAL', and `GET DIAGNOSTICS'. The `SIGNAL' and `RESIGNAL' statements are not supported until MySQL 5.5. The `GET DIAGNOSTICS' statement is not supported until MySQL 5.6. Before MySQL 5.6.3, if a statement that generates a warning or error causes a condition handler to be invoked, the handler may not clear the diagnostic area. This might lead to the appearance that the handler was not invoked. The following discussion demonstrates the issue and provides a workaround. Suppose that a table `t1' is empty. The following procedure selects from it, raising a No Data condition: CREATE PROCEDURE p1() BEGIN DECLARE a INT; DECLARE CONTINUE HANDLER FOR NOT FOUND BEGIN SET @handler_invoked = 1; END; SELECT c1 INTO a FROM t1; END; As can be seen from the following sequence of statements, the condition is not cleared by handler invocation (otherwise, the *Note `SHOW WARNINGS': show-warnings. output would be empty). But as can be seen by the value of `@handler_invoked', the handler was indeed invoked (otherwise its value would be 0). mysql> SET @handler_invoked = 0; Query OK, 0 rows affected (0.00 sec) mysql> CALL p1(); Query OK, 0 rows affected, 1 warning (0.00 sec) mysql> SHOW WARNINGS; +---------+------+-----------------------------------------------------+ | Level | Code | Message | +---------+------+-----------------------------------------------------+ | Warning | 1329 | No data - zero rows fetched, selected, or processed | +---------+------+-----------------------------------------------------+ 1 row in set (0.00 sec) mysql> SELECT @handler_invoked; +------------------+ | @handler_invoked | +------------------+ | 1 | +------------------+ 1 row in set (0.00 sec) There are two ways to work around this issue: * Add an extra dummy statement that clears warnings at the end of the condition handler: CREATE PROCEDURE p1() BEGIN DECLARE a INT; DECLARE CONTINUE HANDLER FOR NOT FOUND BEGIN SET @handler_invoked = 1; SELECT 1 FROM (SELECT 1) AS t; END; SELECT c1 INTO a FROM t1; END; This works for `CONTINUE' and `EXIT' handlers. * Put an extra dummy statement that clears warnings following the statement that causes handler activation: CREATE PROCEDURE p1() BEGIN DECLARE a INT; DECLARE CONTINUE HANDLER FOR NOT FOUND BEGIN SET @handler_invoked = 1; SELECT 1 FROM (SELECT 1) AS t; END; SELECT c1 INTO a FROM t1; END; This works only for `CONTINUE' handlers. This issue is resolved as of MySQL 5.6.3 and no workaround is needed.  File: manual.info, Node: declare-condition, Next: declare-handler, Prev: condition-handling, Up: condition-handling 13.6.7.1 `DECLARE ... CONDITION' Syntax ....................................... DECLARE CONDITION_NAME CONDITION FOR CONDITION_VALUE CONDITION_VALUE: MYSQL_ERROR_CODE | SQLSTATE [VALUE] SQLSTATE_VALUE The *Note `DECLARE ... CONDITION': 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 *Note `DECLARE ... HANDLER': declare-handler. statement (see *Note declare-handler::). Condition declarations must appear before cursor or handler declarations. The CONDITION_VALUE for *Note `DECLARE ... CONDITION': declare-condition. can be a MySQL error code (a number) or an SQLSTATE value (a 5-character string literal). You should not use MySQL error code 0 or SQLSTATE values that begin with `'00'', because those indicate success rather than an error condition. For a list of MySQL error codes and SQLSTATE values, see *Note error-messages-server::. 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 the meaning of MySQL error code 1051: 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;  File: manual.info, Node: declare-handler, Prev: declare-condition, Up: condition-handling 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 *Note `DECLARE ... HANDLER': 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 *Note 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 *Note `BEGIN ... END': 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 *Note `DECLARE ... HANDLER': declare-handler. indicates the specific condition or class of conditions that activates the handler: * A MySQL error code (a number) or an SQLSTATE value (a 5-character string literal). You should not use MySQL error code 0 or SQLSTATE values that begin with `'00'', because those indicate success rather than an error condition. For a list of MySQL error codes and SQLSTATE values, see *Note error-messages-server::. * A condition name previously specified with *Note `DECLARE ... CONDITION': declare-condition. A condition name can be associated with a MySQL error code or SQLSTATE value. See *Note declare-condition::. * `SQLWARNING' is shorthand for the class of SQLSTATE values that begin with `'01''. * `NOT FOUND' is 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). For an example, see *Note cursors::. This condition also occurs for `SELECT ... INTO VAR_LIST' statements that retrieve no rows. * `SQLEXCEPTION' is shorthand for the class of SQLSTATE values that do not begin with `'00'', `'01'', or `'02''. 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' or `NOT FOUND' conditions, the program continues executing, as if there were a `CONTINUE' handler. 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 *Note `DECLARE ... HANDLER': declare-handler. statement had not been present, MySQL would have taken the default action (`EXIT') after the second *Note `INSERT': 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 *Note `ITERATE': iterate. or *Note `LEAVE': leave. to refer to labels for blocks that enclose the handler declaration. Consider the following example, where the *Note `REPEAT': 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 *Note `IF': 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 *Note `BEGIN ... END': 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;  File: manual.info, Node: sql-syntax-server-administration, Next: sql-syntax-utility, Prev: sql-syntax-compound-statements, Up: sql-syntax 13.7 Database Administration Statements ======================================= * Menu: * account-management-sql:: Account Management Statements * table-maintenance-sql:: Table Maintenance Statements * plugin-sql:: Plugin and User-Defined Function Statements * set-statement:: `SET' Syntax * show:: `SHOW' Syntax * other-administrative-sql:: Other Administrative Statements  File: manual.info, Node: account-management-sql, Next: table-maintenance-sql, Prev: sql-syntax-server-administration, Up: sql-syntax-server-administration 13.7.1 Account Management Statements ------------------------------------ * Menu: * create-user:: `CREATE USER' Syntax * drop-user:: `DROP USER' Syntax * grant:: `GRANT' Syntax * rename-user:: `RENAME USER' Syntax * revoke:: `REVOKE' Syntax * set-password:: `SET PASSWORD' Syntax MySQL account information is stored in the tables of the `mysql' database. This database and the access control system are discussed extensively in *Note server-administration::, which you should consult for additional details. *Important*: Some releases of MySQL introduce changes to the structure of the grant tables to add new privileges or features. Whenever you update to a new version of MySQL, you should update your grant tables to make sure that they have the current structure so that you can take advantage of any new capabilities. See *Note mysql-upgrade::.  File: manual.info, Node: create-user, Next: drop-user, Prev: account-management-sql, Up: account-management-sql 13.7.1.1 `CREATE USER' Syntax ............................. CREATE USER USER_SPECIFICATION [, USER_SPECIFICATION] ... USER_SPECIFICATION: USER [IDENTIFIED BY [PASSWORD] 'PASSWORD'] The *Note `CREATE USER': create-user. statement creates new MySQL accounts. To use it, you must have the global `CREATE USER' privilege or the `INSERT' privilege for the `mysql' database. For each account, *Note `CREATE USER': create-user. creates a new row in the `mysql.user' table and assigns the account no privileges. An error occurs if the account already exists. Each account name uses the format described in *Note account-names::. For example: CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY 'mypass'; If you specify only the user name part of the account name, a host name part of `'%'' is used. The user specification may indicate how the user should authenticate when connecting to the server: * To enable the user to connect with no password (which is _insecure_), include no `IDENTIFIED BY' clause: CREATE USER 'jeffrey'@'localhost'; * To assign a password, use `IDENTIFIED BY' with the literal plaintext password value: CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY 'mypass'; * To avoid specifying the plaintext password if you know its hash value (the value that `PASSWORD()' would return for the password), specify the hash value preceded by the keyword `PASSWORD': CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY PASSWORD '*90E462C37378CED12064BB3388827D2BA3A9B689'; For additional information about setting passwords, see *Note assigning-passwords::. *Important*: *Note `CREATE USER': create-user. may be recorded in server logs or in a history file such as `~/.mysql_history', which means that cleartext passwords may be read by anyone having read access to that information. See *Note password-security::. *Important*: Some releases of MySQL introduce changes to the structure of the grant tables to add new privileges or features. Whenever you update to a new version of MySQL, you should update your grant tables to make sure that they have the current structure so that you can take advantage of any new capabilities. See *Note mysql-upgrade::.  File: manual.info, Node: drop-user, Next: grant, Prev: create-user, Up: account-management-sql 13.7.1.2 `DROP USER' Syntax ........................... DROP USER USER [, USER] ... The *Note `DROP USER': 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 this statement, you must have the global `CREATE USER' privilege or the `DELETE' privilege for the `mysql' database. Each account name uses the format described in *Note account-names::. For example: DROP USER 'jeffrey'@'localhost'; If you specify only the user name part of the account name, a host name part of `'%'' is used. *Important*: *Note `DROP USER': 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_. *Note `DROP USER': 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 *Note stored-programs-security::.)  File: manual.info, Node: grant, Next: rename-user, Prev: drop-user, Up: account-management-sql 13.7.1.3 `GRANT' Syntax ....................... GRANT PRIV_TYPE [(COLUMN_LIST)] [, PRIV_TYPE [(COLUMN_LIST)]] ... ON [OBJECT_TYPE] PRIV_LEVEL TO USER_SPECIFICATION [, USER_SPECIFICATION] ... [REQUIRE {NONE | SSL_OPTION [[AND] SSL_OPTION] ...}] [WITH WITH_OPTION ...] OBJECT_TYPE: TABLE | FUNCTION | PROCEDURE PRIV_LEVEL: * | *.* | DB_NAME.* | DB_NAME.TBL_NAME | TBL_NAME | DB_NAME.ROUTINE_NAME USER_SPECIFICATION: USER [IDENTIFIED BY [PASSWORD] 'PASSWORD'] SSL_OPTION: SSL | X509 | CIPHER 'CIPHER' | ISSUER 'ISSUER' | SUBJECT 'SUBJECT' WITH_OPTION: GRANT OPTION | MAX_QUERIES_PER_HOUR COUNT | MAX_UPDATES_PER_HOUR COUNT | MAX_CONNECTIONS_PER_HOUR COUNT | MAX_USER_CONNECTIONS COUNT The *Note `GRANT': grant. statement grants privileges to MySQL user accounts. *Note `GRANT': grant. also serves to specify other account characteristics such as use of secure connections and limits on access to server resources. To use *Note `GRANT': grant, you must have the `GRANT OPTION' privilege, and you must have the privileges that you are granting. Normally, a database administrator first uses *Note `CREATE USER': create-user. to create an account, then *Note `GRANT': grant. to define its privileges and characteristics. For example: CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY 'mypass'; GRANT ALL ON db1.* TO 'jeffrey'@'localhost'; GRANT SELECT ON db2.invoice TO 'jeffrey'@'localhost'; GRANT USAGE ON *.* TO 'jeffrey'@'localhost' WITH MAX_QUERIES_PER_HOUR 90; However, if an account named in a *Note `GRANT': grant. statement does not already exist, *Note `GRANT': grant. may create it under the conditions described later in the discussion of the `NO_AUTO_CREATE_USER' SQL mode. The *Note `REVOKE': revoke. statement is related to *Note `GRANT': grant. and enables administrators to remove account privileges. See *Note revoke::. When successfully executed from the *Note `mysql': mysql. program, *Note `GRANT': grant. responds with `Query OK, 0 rows affected'. To determine what privileges result from the operation, use *Note `SHOW GRANTS': show-grants. See *Note show-grants::. There are several aspects to the `GRANT' statement, described under the following topics in this section: * Privileges Supported by MySQL * Global Privileges * Database Privileges * Table Privileges * Column Privileges * Stored Routine Privileges * Account Names and Passwords * Other Account Characteristics * MySQL and Standard SQL Versions of *Note `GRANT': grant. *Important*: Some releases of MySQL introduce changes to the structure of the grant tables to add new privileges or features. Whenever you update to a new version of MySQL, you should update your grant tables to make sure that they have the current structure so that you can take advantage of any new capabilities. See *Note mysql-upgrade::. * Privileges Supported by MySQL * The following table summarizes the permissible PRIV_TYPE privilege types that can be specified for the *Note `GRANT': grant. and *Note `REVOKE': revoke. statements. For additional information about these privileges, see *Note privileges-provided::. *Permissible Privileges for `GRANT' and `REVOKE'* Privilege Meaning `ALL [PRIVILEGES]' Grant all privileges at specified access level except `GRANT OPTION' `ALTER' Enable use of *Note `ALTER TABLE': alter-table. `ALTER ROUTINE' Enable stored routines to be altered or dropped `CREATE' Enable database and table creation `CREATE ROUTINE' Enable stored routine creation `CREATE TEMPORARY Enable use of *Note `CREATE TEMPORARY TABLE': TABLES' create-table. `CREATE USER' Enable use of *Note `CREATE USER': create-user, *Note `DROP USER': drop-user, *Note `RENAME USER': rename-user, and *Note `REVOKE ALL PRIVILEGES': revoke. `CREATE VIEW' Enable views to be created or altered `DELETE' Enable use of *Note `DELETE': delete. `DROP' Enable databases, tables, and views to be dropped `EVENT' Enable use of events for the Event Scheduler `EXECUTE' Enable the user to execute stored routines `FILE' Enable the user to cause the server to read or write files `GRANT OPTION' Enable privileges to be granted to or removed from other accounts `INDEX' Enable indexes to be created or dropped `INSERT' Enable use of *Note `INSERT': insert. `LOCK TABLES' Enable use of *Note `LOCK TABLES': lock-tables. on tables for which you have the *Note `SELECT': select. privilege `PROCESS' Enable the user to see all processes with *Note `SHOW PROCESSLIST': show-processlist. `REFERENCES' Not implemented `RELOAD' Enable use of *Note `FLUSH': flush. operations `REPLICATION CLIENT' Enable the user to ask where master or slave servers are `REPLICATION SLAVE' Enable replication slaves to read binary log events from the master `SELECT' Enable use of *Note `SELECT': select. `SHOW DATABASES' Enable *Note `SHOW DATABASES': show-databases. to show all databases `SHOW VIEW' Enable use of *Note `SHOW CREATE VIEW': show-create-view. `SHUTDOWN' Enable use of *Note `mysqladmin shutdown': mysqladmin. `SUPER' Enable use of other administrative operations such as *Note `CHANGE MASTER TO': change-master-to, *Note `KILL': kill, *Note `PURGE BINARY LOGS': purge-binary-logs, *Note `SET GLOBAL': set-statement, and *Note `mysqladmin debug': mysqladmin. command `TRIGGER' Enable trigger operations `UPDATE' Enable use of *Note `UPDATE': update. `USAGE' Synonym for `no privileges' The `EVENT' and `TRIGGER' privileges were added in MySQL 5.1.6. A trigger is associated with a table, so to create or drop a trigger, you must have the `TRIGGER' privilege for the table, not the trigger. (Before MySQL 5.1.6, the `SUPER' privilege was required to create or drop triggers.) In *Note `GRANT': grant. statements, the `ALL [PRIVILEGES]' privilege is named by itself and cannot be specified along with other privileges. It stands for all privileges available for the level at which privileges are to be granted except for the `GRANT OPTION' privilege. `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. MySQL account information is stored in the tables of the `mysql' database. This database and the access control system are discussed extensively in *Note privilege-system::, which you should consult for additional details. 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, *Note `REVOKE': revoke. cannot be used to revoke these privileges. It will be necessary to manipulate the grant tables directly. (*Note `GRANT': 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 *Note `REVOKE': revoke, the same `ON' syntax specifies which privileges to take away. The examples shown here include no `IDENTIFIED BY 'PASSWORD'' clause for brevity, but you should include one if the account does not already exist, to avoid creating an insecure account that has no password. * 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'; Before MySQL 5.1.12, privileges also are assigned at the global level if you use `ON *' syntax and you have _not_ selected a default database. As of 5.1.12, `ON *' requires a default database and produces an error if there is none. The `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. MySQL stores global privileges in the `mysql.user' 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 *.*') and you have selected a default database, 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', and `LOCK TABLES' 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' 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', `SELECT', `SHOW VIEW', `TRIGGER', and `UPDATE'. MySQL stores table privileges in the `mysql.tables_priv' 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', `SELECT', and `UPDATE'. MySQL stores column privileges in the `mysql.columns_priv' 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 this privilege to create a routine in the first place. MySQL stores routine-level privileges in the `mysql.procs_priv' table. For the global, database, table, and routine levels, *Note `GRANT ALL': grant. 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'. 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 for a database, table, column, or routine are formed additively as the logical `OR' of the 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 *Note request-access::. 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 * The USER value indicates the MySQL account to which the *Note `GRANT': grant. statement applies. To accommodate granting rights to users from arbitrary hosts, MySQL supports specifying the USER value in the form `USER_NAME@HOST_NAME'. If a USER_NAME or HOST_NAME value 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. 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@'192.168.1.%'' applies to USER_NAME for any host in the `192.168.1' 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 *Note `GRANT': 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 *Note account-names::. 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 *Note string-literals::, and *Note identifiers::. The ``_'' and ``%'' wildcards are permitted when specifying database names in *Note `GRANT': grant. statements that grant privileges at the global or database levels. This means, for example, that if you want to use a ``_'' character as part of a database name, you should specify it as ``\_'' in the *Note `GRANT': grant. statement, to prevent the user from being able to access additional databases matching the wildcard pattern; for example, `GRANT ... ON `foo\_bar`.* TO ...'. *Warning*: If you permit 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' table (created during MySQL installation) is used when named users try to log in to the MySQL server from the local machine. For details, see *Note connection-access::. To determine whether the preceding warning 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'; *Note `GRANT': grant. supports host names up to 60 characters long. Database, table, column, and routine names can be up to 64 characters. User names can be up to 16 characters. *Warning*: _The permissible length for user names cannot be changed by altering the `mysql.user' table. Attempting to do so results in unpredictable behavior which may even make it impossible for users to log in to the MySQL server_. You should never alter any of the tables in the `mysql' database in any manner whatsoever except by means of the procedure described in *Note mysql-upgrade::. The user specification may indicate how the user should authenticate when connecting to the server, through inclusion of an `IDENTIFIED BY' clause. The syntax is the same as for the *Note `CREATE USER': create-user. statement. See *Note create-user::. When the `IDENTIFIED BY' clause is present and you have global grant privileges, the password becomes the new password for the account, even if the account exists and already has a password. With no `IDENTIFIED BY' clause, the account password remains unchanged. If the `NO_AUTO_CREATE_USER' SQL mode is not enabled and the account named in a *Note `GRANT': grant. statement does not exist in the `mysql.user' table, *Note `GRANT': grant. creates it. If you specify no `IDENTIFIED BY' clause or provide an empty password, the user has no password. _This is very insecure._ If `NO_AUTO_CREATE_USER' is enabled and the account does not exist, *Note `GRANT': grant. fails and does not create the account unless the `IDENTIFIED BY' clause is given to provide a nonempty password. *Important*: *Note `GRANT': grant. may be recorded in server logs or in a history file such as `~/.mysql_history', which means that cleartext passwords may be read by anyone having read access to that information. See *Note password-security::. * Other Account Characteristics * The `WITH' clause is used for several purposes: * To enable a user to grant privileges to other users * To specify resource limits for a user * To specify whether and how a user must use secure connections to the server 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. You should 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 *Note privileges-provided::. Several `WITH' clause options specify limits on use of server resources by an account: * The `MAX_QUERIES_PER_HOUR COUNT', `MAX_UPDATES_PER_HOUR COUNT', and `MAX_CONNECTIONS_PER_HOUR COUNT' limits restrict the number of queries, updates, and connections to the server 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. * The `MAX_USER_CONNECTIONS COUNT' limit 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. To specify resource limits for an existing user without affecting existing privileges, use *Note `GRANT USAGE': grant. at the global level (`ON *.*') and name the limits to be changed. For example: GRANT USAGE ON *.* TO ... WITH MAX_QUERIES_PER_HOUR 500 MAX_UPDATES_PER_HOUR 100; Limits not specified retain their current values. For more information on restricting access to server resources, see *Note user-resources::. MySQL can check X509 certificate attributes in addition to the usual authentication that is based on the user name and password. To specify SSL-related options for a MySQL account, use the `REQUIRE' clause of the *Note `GRANT': grant. statement. (For background information on the use of SSL with MySQL, see *Note ssl-connections::.) There are a number of different possibilities for limiting connection types for a given account: * `REQUIRE NONE' indicates that the account has no SSL or X509 requirements. This is the default if no SSL-related `REQUIRE' options are specified. Unencrypted connections are permitted if the user name and password are valid. However, encrypted connections can also be used, at the client's option, if the client has the proper certificate and key files. That is, the client need not specify any SSL command options, in which case the connection will be unencrypted. To use an encrypted connection, the client must specify either the `--ssl-ca' option, or all three of the `--ssl-ca', `--ssl-key', and `--ssl-cert' options. * The `REQUIRE SSL' option tells the server to permit only SSL-encrypted connections for the account. GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE SSL; To connect, the client must specify the `--ssl-ca' option to authenticate the server certificate, and may additionally specify the `--ssl-key' and `--ssl-cert' options. If neither `--ssl-ca' option nor `--ssl-capath' option is specified, the client does not authenticate the server certificate. * `REQUIRE X509' means that the client must have a valid certificate but that 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. GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE X509; To connect, the client must specify the `--ssl-ca', `--ssl-key', and `--ssl-cert' options. This is also true for `ISSUER' and `SUBJECT' because those `REQUIRE' options imply `X509'. * `REQUIRE ISSUER 'ISSUER'' places the restriction on connection attempts that the client must present a valid X509 certificate issued by CA `'ISSUER''. If the 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. GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE ISSUER '/C=FI/ST=Some-State/L=Helsinki/ O=MySQL Finland AB/CN=Tonu Samuel/emailAddress=tonu@example.com'; The `'ISSUER'' value should be entered as a single string. *Note*: If MySQL is linked against a version of OpenSSL older than 0.9.6h, use `Email' rather than `emailAddress' in the `'ISSUER'' value. * `REQUIRE SUBJECT 'SUBJECT'' places the restriction on connection attempts that the client must present a valid X509 certificate containing the subject SUBJECT. If the client presents a certificate that is valid but has a different subject, the server rejects the connection. GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/ O=MySQL demo client certificate/ CN=Tonu Samuel/emailAddress=tonu@example.com'; The `'SUBJECT'' value should be entered as a single string. MySQL does a simple string comparison of this value to the value in the certificate, so lettercase and component ordering must be given exactly as present in the certificate. *Note*: Regarding `emailAddress', see the note in the description of `REQUIRE ISSUER'. * `REQUIRE CIPHER 'CIPHER'' is needed to ensure that ciphers and key lengths of sufficient strength are used. SSL itself can be weak if old algorithms using short encryption keys are used. Using this option, you can ask that a specific cipher method is used for a connection. GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA'; The `SUBJECT', `ISSUER', and `CIPHER' options can be combined in the `REQUIRE' clause like this: GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/ O=MySQL demo client certificate/ CN=Tonu Samuel/emailAddress=tonu@example.com' AND ISSUER '/C=FI/ST=Some-State/L=Helsinki/ O=MySQL Finland AB/CN=Tonu Samuel/emailAddress=tonu@example.com' AND CIPHER 'EDH-RSA-DES-CBC3-SHA'; The order of the options does not matter, but no option can be specified twice. The `AND' keyword is optional between `REQUIRE' options. 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 and Standard SQL Versions of *Note `GRANT': grant. * The biggest differences between the MySQL and standard SQL versions of *Note `GRANT': 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 *Note `DROP USER': drop-user. See *Note 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 only with explicit *Note `DROP USER': drop-user. or *Note `REVOKE': revoke. statements or by manipulating the MySQL grant tables directly. * 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 *Note `INSERT': 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.) *Note server-sql-mode::, discusses strict mode. *Note data-type-defaults::, discusses implicit default values.  File: manual.info, Node: rename-user, Next: revoke, Prev: grant, Up: account-management-sql 13.7.1.4 `RENAME USER' Syntax ............................. RENAME USER OLD_USER TO NEW_USER [, OLD_USER TO NEW_USER] ... The *Note `RENAME USER': rename-user. statement renames existing MySQL accounts. To use it, you must have the global `CREATE USER' privilege or the `UPDATE' privilege for the `mysql' database. An error occurs if any old account does not exist or any new account exists. Each account name uses the format described in *Note account-names::. For example: RENAME USER 'jeffrey'@'localhost' TO 'jeff'@'127.0.0.1'; If you specify only the user name part of the account name, a host name part of `'%'' is used. *Note `RENAME USER': rename-user. causes the privileges held by the old user to be those held by the new user. However, *Note `RENAME USER': 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 *Note stored-programs-security::.) The privilege changes take effect as indicated in *Note privilege-changes::.  File: manual.info, Node: revoke, Next: set-password, Prev: rename-user, Up: account-management-sql 13.7.1.5 `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] ... The *Note `REVOKE': revoke. statement enables system administrators to revoke privileges from MySQL accounts. Each account name uses the format described in *Note account-names::. For example: REVOKE INSERT ON *.* FROM 'jeffrey'@'localhost'; If you specify only the user name part of the account name, a host name part of `'%'' is used. For details on the levels at which privileges exist, the permissible PRIV_TYPE and PRIV_LEVEL values, and the syntax for specifying users and passwords, see *Note grant:: To use the first *Note `REVOKE': 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 *Note `REVOKE': revoke. syntax, you must have the global `CREATE USER' privilege or the `UPDATE' privilege for the `mysql' database. *Note `REVOKE': revoke. removes privileges, but does not drop `mysql.user' table entries. To remove a user account entirely, use *Note `DROP USER': drop-user. (see *Note drop-user::) or *Note `DELETE': delete. 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, *Note `REVOKE': revoke. cannot be used to revoke these privileges. It will be necessary to manipulate the grant tables directly. (*Note `GRANT': 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 *Note `mysql': mysql. program, *Note `REVOKE': revoke. responds with `Query OK, 0 rows affected'. To determine what privileges result from the operation, use *Note `SHOW GRANTS': show-grants. See *Note show-grants::.  File: manual.info, Node: set-password, Prev: revoke, Up: account-management-sql 13.7.1.6 `SET PASSWORD' Syntax .............................. SET PASSWORD [FOR USER] = { PASSWORD('CLEARTEXT PASSWORD') | OLD_PASSWORD('CLEARTEXT PASSWORD') | 'ENCRYPTED PASSWORD' } The *Note `SET PASSWORD': set-password. statement assigns a password to an existing MySQL user account. In MySQL 5.1 and later, when the `read_only' system variable is enabled, the `SUPER' privilege is required to use *Note `SET PASSWORD': set-password, in addition to whatever other privileges might be required. If the password is specified using the `PASSWORD()' or `OLD_PASSWORD()' function, the cleartext (unencrypted) password should be given as the argument to the function, which hashes the password and returns the encrypted password string. If the password is specified without using either function, it should be the already encrypted password value as a literal string. In all cases, the encrypted password string must be in the format required by the authentication method used for the account. With no `FOR USER' clause, this statement sets the password for the current user. (To see which account the server authenticated you as, invoke the `CURRENT_USER()' function.) Any client who successfully connects to the server using a nonanonymous account can change the password for that account. With a `FOR USER' clause, this statement sets the password for the named user. You must have the *Note `UPDATE': update. privilege for the `mysql' database to do this. The user account name uses the format described in *Note account-names::. The USER value should be given as `'USER_NAME'@'HOST_NAME'', where `'USER_NAME'' and `'HOST_NAME'' are exactly as listed in the `User' and `Host' columns of the `mysql.user' table row. (If you specify only a user name, a host name of `'%'' is used.) For example, to set the password for an account with `User' and `Host' column values of `'bob'' and `'%.example.org'', write the statement like this: SET PASSWORD FOR 'bob'@'%.example.org' = PASSWORD('CLEARTEXT PASSWORD'); That is equivalent to the following statements: UPDATE mysql.user SET Password=PASSWORD('CLEARTEXT PASSWORD') WHERE User='bob' AND Host='%.example.org'; FLUSH PRIVILEGES; Another way to set the password is to use *Note `GRANT': grant.: GRANT USAGE ON *.* TO 'bob'@'%.example.org' IDENTIFIED BY 'CLEARTEXT PASSWORD'; The `old_passwords' system variable value determines the hashing method used by `PASSWORD()'. If you specify the password using that function and *Note `SET PASSWORD': set-password. rejects the password as not being in the correct format, it may be necessary to set `old_passwords' to change the hashing method. For descriptions of the permitted values, see *Note server-system-variables::. For more information about setting passwords, see *Note assigning-passwords:: *Important*: *Note `SET PASSWORD': set-password. may be recorded in server logs or in a history file such as `~/.mysql_history', which means that cleartext passwords may be read by anyone having read access to that information. See *Note password-security::. *Caution*: If you are connecting to a MySQL 4.1 or later server using a pre-4.1 client program, do not change your password without first reading *Note password-hashing::. The default password hashing format changed in MySQL 4.1, and if you change your password, it might be stored using a hashing format that pre-4.1 clients cannot generate, thus preventing you from connecting to the server afterward. If you are using MySQL Replication, be aware that, currently, a password used by a replication slave as part of a *Note `CHANGE MASTER TO': change-master-to. statement is effectively limited to 32 characters in length; the password can be longer, but 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.)  File: manual.info, Node: table-maintenance-sql, Next: plugin-sql, Prev: account-management-sql, Up: sql-syntax-server-administration 13.7.2 Table Maintenance Statements ----------------------------------- * Menu: * analyze-table:: `ANALYZE TABLE' Syntax * backup-table:: `BACKUP TABLE' Syntax * check-table:: `CHECK TABLE' Syntax * checksum-table:: `CHECKSUM TABLE' Syntax * optimize-table:: `OPTIMIZE TABLE' Syntax * repair-table:: `REPAIR TABLE' Syntax * restore-table:: `RESTORE TABLE' Syntax  File: manual.info, Node: analyze-table, Next: backup-table, Prev: table-maintenance-sql, Up: table-maintenance-sql 13.7.2.1 `ANALYZE TABLE' Syntax ............................... ANALYZE [NO_WRITE_TO_BINLOG | LOCAL] TABLE TBL_NAME [, TBL_NAME] ... `ANALYZE TABLE' analyzes and stores the key distribution for a table. During the analysis, the table is locked with a read lock for `InnoDB' and `MyISAM'. This statement works with `InnoDB', `NDB', and `MyISAM' tables. For `MyISAM' tables, this statement is equivalent to using *Note `myisamchk --analyze': myisamchk. For more information on how the analysis works within `InnoDB', see *Note innodb-restrictions::. MySQL uses the stored key distribution to decide the order in which tables should be joined when you perform a join 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. This statement requires `SELECT' and `INSERT' privileges for the table. Beginning with MySQL 5.1.27, `ANALYZE TABLE' is also supported for partitioned tables. Also beginning with MySQL 5.1.27, you can use `ALTER TABLE ... ANALYZE PARTITION' to analyze one or more partitions; for more information, see *Note alter-table::, and *Note partitioning-maintenance::. `ANALYZE TABLE' returns a result set with the following columns. This table describes the columns of the *Note `ANALYZE TABLE': analyze-table. result set. Column Value `Table' The table name `Op' Always `analyze' `Msg_type' `status', `error', `info', `note', or `warning' `Msg_text' An informational message You can check the stored key distribution with the *Note `SHOW INDEX': show-index. statement. See *Note show-index::. If the table has not changed since the last `ANALYZE TABLE' statement, the table is not analyzed again. By default, the server writes *Note `ANALYZE TABLE': 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'.  File: manual.info, Node: backup-table, Next: check-table, Prev: analyze-table, Up: table-maintenance-sql 13.7.2.2 `BACKUP TABLE' Syntax .............................. BACKUP TABLE TBL_NAME [, TBL_NAME] ... TO '/PATH/TO/BACKUP/DIRECTORY' *Note*: This statement is deprecated and is removed in MySQL 5.5. As an alternative, *Note `mysqldump': mysqldump. or *Note `mysqlhotcopy': mysqlhotcopy. can be used instead. *Note `BACKUP TABLE': backup-table. copies to the backup directory the minimum number of table files needed to restore the table, after flushing any buffered changes to disk. The statement works only for `MyISAM' tables. It copies the `.frm' definition and `.MYD' data files. The `.MYI' index file can be rebuilt from those two files. The directory should be specified as a full path name. To restore the table, use *Note `RESTORE TABLE': restore-table. During the backup, a read lock is held for each table, one at time, as they are being backed up. If you want to back up several tables as a snapshot (preventing any of them from being changed during the backup operation), issue a *Note `LOCK TABLES': lock-tables. statement first, to obtain a read lock for all tables in the group. *Note `BACKUP TABLE': backup-table. returns a result set with the following columns. This table describes the columns of the *Note `BACKUP TABLE': backup-table. result set. Column Value `Table' The table name `Op' Always `backup' `Msg_type' `status', `error', `info', `note', or `warning' `Msg_text' An informational message  File: manual.info, Node: check-table, Next: checksum-table, Prev: backup-table, Up: table-maintenance-sql 13.7.2.3 `CHECK TABLE' Syntax ............................. CHECK TABLE TBL_NAME [, TBL_NAME] ... [OPTION] ... OPTION = {FOR UPGRADE | QUICK | FAST | MEDIUM | EXTENDED | CHANGED} *Note `CHECK TABLE': check-table. checks a table or tables for errors. *Note `CHECK TABLE': check-table. works for *Note `InnoDB': innodb-storage-engine, *Note `MyISAM': myisam-storage-engine, and *Note `ARCHIVE': archive-storage-engine. tables. Starting with MySQL 5.1.9, *Note `CHECK TABLE': check-table. is also valid for *Note `CSV': csv-storage-engine. tables, see *Note csv-storage-engine::. For `MyISAM' tables, the key statistics are updated as well. *Note `CHECK TABLE': check-table. can also check views for problems, such as tables that are referenced in the view definition that no longer exist. Beginning with MySQL 5.1.27, *Note `CHECK TABLE': check-table. is also supported for partitioned tables. Also beginning with MySQL 5.1.27, you can use `ALTER TABLE ... CHECK PARTITION' to check one or more partitions; for more information, see *Note alter-table::, and *Note partitioning-maintenance::. * Output * *Note `CHECK TABLE': check-table. returns a result set with the following columns. This table describes the columns of the *Note `CHECK TABLE': check-table. result set. Column Value `Table' The table name `Op' Always `check' `Msg_type' `status', `error', `info', `note', or `warning' `Msg_text' An informational message Note that 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'. If you don't get `OK', or `Table is already up to date' you should normally run a repair of the table. See *Note 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. This option was added in MySQL 5.1.7. 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. Currently, `FOR UPGRADE' discovers these incompatibilities: * The indexing order for end-space in *Note `TEXT': blob. columns for `InnoDB' and `MyISAM' tables changed between MySQL 4.1 and 5.0. * The storage method of the new *Note `DECIMAL': fixed-point-types. data type changed between MySQL 5.0.3 and 5.0.5. * As of MySQL 5.1.25, 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 *Note `CHECK TABLE': 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 these changes and when `FOR UPGRADE' detects them, see *Note checking-table-incompatibilities::. * Checking Data Consistency * The other check options that can be given are shown in the following table. These options are passed to the storage engine, which may use them or not. This table describes other *Note `CHECK TABLE': check-table. options. 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. Applies only to `MyISAM' tables and views; ignored for `InnoDB'. `CHANGED' Check only tables that have been changed since the last check or that have not been closed properly. Applies only to `MyISAM' tables and views; ignored for `InnoDB'. `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. Applies only to `MyISAM' tables and views; ignored for `InnoDB'. `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. Applies only to `MyISAM' tables and views; ignored for `InnoDB'. 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 *Note `myisamchk --medium-check TBL_NAME': myisamchk. 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*: In some cases, *Note `CHECK TABLE': check-table. changes the table. This happens if the table is marked as `corrupted' or `not closed properly' but *Note `CHECK TABLE': check-table. does not find any problems in the table. In this case, *Note `CHECK TABLE': check-table. marks the table as okay. If a table is corrupted, it is most likely that the problem is 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. If you just want to check a table that you assume is okay, you should 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') if you want to check tables from time to time. 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 strange 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 *Note `CHECK TABLE ... EXTENDED': check-table. might influence the execution plan generated by the query optimizer. Some problems reported by *Note `CHECK TABLE': 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 *Note `UPDATE': 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 *Note `ALTER TABLE': 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, simply execute an *Note `UPDATE': update. statement to set the column to some value other than 0. * InnoDB Tables * The following notes apply to *Note `InnoDB': innodb-storage-engine. tables: * If *Note `CHECK TABLE': check-table. finds a problem for an `InnoDB' table, the server may shut down to prevent error propagation. Details of the error will be written to the error log. * If *Note `CHECK TABLE': check-table. encounters corruptions or errors in `InnoDB' tables or indexes, it reports an error. It does not shut down the server. Starting with MySQL 5.5, *Note `CHECK TABLE': check-table. usually marks the index and sometimes marks the table as corrupted, preventing further use of the index or table. * If *Note `CHECK TABLE': check-table. finds the wrong number of entries in a secondary index, it will report an error but will not shut down the server or prevent access to the file. * *Note `CHECK TABLE': 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 *Note `BLOB': blob. pointers. * When an `InnoDB' table is stored in its own .ibd file (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_ibd_file) in file-per-table (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_file_per_table) mode, the first 3 pages (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_page) of the `.ibd' contain header information rather than table or index data. The `CHECK TABLE' statement does not detect inconsistencies that only affect the header data. To verify the entire contents of an `InnoDB' `.ibd' file, use the *Note `innochecksum': 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' will abort the process. To avoid the possibility of a semaphore wait timeout entirely, you can run `CHECK TABLE QUICK' instead of `CHECK TABLE'.  File: manual.info, Node: checksum-table, Next: optimize-table, Prev: check-table, Up: table-maintenance-sql 13.7.2.4 `CHECKSUM TABLE' Syntax ................................ CHECKSUM TABLE TBL_NAME [, TBL_NAME] ... [ QUICK | EXTENDED ] *Note `CHECKSUM TABLE': checksum-table. reports a table checksum. With `QUICK', the live table checksum is reported if it is available, or `NULL' otherwise. This is very fast. A live checksum is enabled by specifying the `CHECKSUM=1' table option when you create the table; currently, this is supported only for `MyISAM' tables. See *Note create-table::. With `EXTENDED', the entire table is read row by row and the checksum is calculated. This can be very slow for large tables. If neither `QUICK' nor `EXTENDED' is specified, MySQL returns a live checksum if the table storage engine supports it and scans the table otherwise. For a nonexistent table, *Note `CHECKSUM TABLE': checksum-table. returns `NULL' and generates a warning. In MySQL 5.1, *Note `CHECKSUM TABLE': checksum-table. returns 0 for partitioned tables unless you include the `EXTENDED' option. This issue is resolved in MySQL 5.6. (Bug #11933226, Bug #60681) The checksum value depends on the table row format. If the row format changes, the checksum also changes. For example, the storage format for *Note `VARCHAR': char. changed between MySQL 4.1 and 5.0, so if a 4.1 table is upgraded to MySQL 5.0, 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 *Note `CHECKSUM TABLE': 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.  File: manual.info, Node: optimize-table, Next: repair-table, Prev: checksum-table, Up: table-maintenance-sql 13.7.2.5 `OPTIMIZE TABLE' Syntax ................................ OPTIMIZE [NO_WRITE_TO_BINLOG | LOCAL] TABLE TBL_NAME [, TBL_NAME] ... 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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_storage_engine) used by that table. Use *Note `OPTIMIZE TABLE': 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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 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 *Note `VARCHAR': char, *Note `VARBINARY': binary-varbinary, *Note `BLOB': blob, or *Note `TEXT': blob. columns). Deleted rows are maintained in a linked list and subsequent *Note `INSERT': insert. operations reuse old row positions. You can use *Note `OPTIMIZE TABLE': 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. Beginning with MySQL 5.1.27, *Note `OPTIMIZE TABLE': optimize-table. is also supported for partitioned tables. For information about using this statement with partitioned tables and table partitions, see *Note partitioning-maintenance::. *Note `OPTIMIZE TABLE': optimize-table. works for *Note `MyISAM': myisam-storage-engine, *Note `InnoDB': innodb-storage-engine, and *Note `ARCHIVE': archive-storage-engine. tables. Beginning with MySQL Cluster NDB 6.3.7, *Note `OPTIMIZE TABLE': optimize-table. is also supported for dynamic columns of in-memory *Note `NDB': mysql-cluster. tables. It does not work for Disk Data tables. The performance of `OPTIMIZE' on Cluster tables can be tuned by adjusting the value of the `ndb_optimization_delay' system variable, which controls the number of milliseconds to wait between processing batches of rows by *Note `OPTIMIZE TABLE': optimize-table. For more information, see *Note mysql-cluster-limitations-resolved::. Beginning with MySQL Cluster NDB 6.3.8, *Note `OPTIMIZE TABLE': optimize-table. can be interrupted by (for example) killing the SQL thread performing the `OPTIMIZE' operation. By default, *Note `OPTIMIZE TABLE': 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 *Note `OPTIMIZE TABLE': optimize-table. work for other storage engines by starting *Note `mysqld': mysqld. with the `--skip-new' option. In this case, *Note `OPTIMIZE TABLE': optimize-table. is just mapped to *Note `ALTER TABLE': alter-table. For `MyISAM' tables, *Note `OPTIMIZE TABLE': 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. For `InnoDB' tables, *Note `OPTIMIZE TABLE': optimize-table. is mapped to *Note `ALTER TABLE': alter-table, which rebuilds the table to update index statistics and free unused space in the clustered index. Beginning with MySQL 5.1.27, this is displayed in the output of *Note `OPTIMIZE TABLE': 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 | +----------+----------+----------+-------------------------------------------------------------------+ You can make *Note `OPTIMIZE TABLE': optimize-table. work on other storage engines by starting *Note `mysqld': mysqld. `--skip-new' option. In this case, *Note `OPTIMIZE TABLE': optimize-table. is just mapped to *Note `ALTER TABLE': alter-table. *Note `OPTIMIZE TABLE': optimize-table. returns a result set with the following columns. This table describes columns of the *Note `OPTIMIZE TABLE': optimize-table. result set. Column Value `Table' The table name `Op' Always `optimize' `Msg_type' `status', `error', `info', `note', or `warning' `Msg_text' An informational message Note that MySQL locks the table during the time *Note `OPTIMIZE TABLE': optimize-table. is running. By default, the server writes *Note `OPTIMIZE TABLE': 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'. *Note `OPTIMIZE TABLE': optimize-table. does not sort R-tree indexes, such as spatial indexes on `POINT' columns. (Bug #23578) As of MySQL 5.1.50, *Note `OPTIMIZE TABLE': 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 *Note `mysqld': mysqld. process, *Note `OPTIMIZE TABLE': optimize-table. generates a "cannot change ownership of the file" error unless *Note `mysqld': mysqld. is started by the `root' user.  File: manual.info, Node: repair-table, Next: restore-table, Prev: optimize-table, Up: table-maintenance-sql 13.7.2.6 `REPAIR TABLE' Syntax .............................. REPAIR [NO_WRITE_TO_BINLOG | LOCAL] TABLE TBL_NAME [, TBL_NAME] ... [QUICK] [EXTENDED] [USE_FRM] *Note `REPAIR TABLE': repair-table. repairs a possibly corrupted table. By default, it has the same effect as *Note `myisamchk --recover TBL_NAME': myisamchk. *Note `REPAIR TABLE': repair-table. works for `MyISAM' and for `ARCHIVE' tables. Starting with MySQL 5.1.9, `REPAIR' is also valid for `CSV' tables. See *Note myisam-storage-engine::, and *Note archive-storage-engine::, and *Note csv-storage-engine:: This statement requires `SELECT' and `INSERT' privileges for the table. Beginning with MySQL 5.1.27, *Note `REPAIR TABLE': repair-table. is also supported for partitioned tables. However, the `USE_FRM' option cannot be used with this statement on a partitioned table. Also beginning with MySQL 5.1.27, you can use `ALTER TABLE ... REPAIR PARTITION' to repair one or more partitions; for more information, see *Note alter-table::, and *Note partitioning-maintenance::. Normally, you should never have to run *Note `REPAIR TABLE': repair-table. However, if disaster strikes, this statement is very likely to get back all your data from a `MyISAM' table. If your tables become corrupted often, you should try to find the reason for it, to eliminate the need to use *Note `REPAIR TABLE': repair-table. See *Note crashing::, and *Note myisam-table-problems::. *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. See *Note backup-and-recovery::. *Warning*: If the server crashes during a *Note `REPAIR TABLE': repair-table. operation, it is essential after restarting it that you immediately execute another *Note `REPAIR TABLE': 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. *Note `REPAIR TABLE': repair-table. returns a result set with the following columns. This table describes columns of the *Note `REPAIR TABLE': repair-table. result set. Column Value `Table' The table name `Op' Always `repair' `Msg_type' `status', `error', `info', `note', or `warning' `Msg_text' An informational message The *Note `REPAIR TABLE': 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'. If you do not get `OK' for a `MyISAM' table, you should try repairing it with *Note `myisamchk --safe-recover': myisamchk. (*Note `REPAIR TABLE': repair-table. does not implement all the options of *Note `myisamchk': myisamchk.) With *Note `myisamchk --safe-recover': myisamchk, you can also use options that *Note `REPAIR TABLE': repair-table. does not support, such as `--max-record-length'. If you use the `QUICK' option, *Note `REPAIR TABLE': repair-table. tries to repair only the index file, and not the data file. This type of repair is like that done by *Note `myisamchk --recover --quick': myisamchk. 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 *Note `myisamchk --safe-recover': myisamchk. 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 *Note `myisamchk': myisamchk. *Note*: 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. *Caution*: As of MySQL 5.1.25, 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, *Note `REPAIR TABLE': repair-table. will not attempt to repair the table. In this case, the result set returned by *Note `REPAIR TABLE': repair-table. contains a line with a `Msg_type' value of `error' and a `Msg_text' value of `Failed repairing incompatible .FRM file'. Prior to MySQL 5.1.25, _do not use_ `USE_FRM' if your table was created by a different version of the MySQL server. Doing so risks the loss of all rows in the table. It is particularly dangerous to use `USE_FRM' after the server returns this message: Table upgrade required. Please do "REPAIR TABLE `TBL_NAME`" or dump/reload to fix it! If `USE_FRM' is _not_ used, *Note `REPAIR TABLE': repair-table. checks the table to see whether an upgrade is required. If so, it performs the upgrade, following the same rules as *Note `CHECK TABLE ... FOR UPGRADE': check-table. See *Note check-table::, for more information. As of MySQL 5.1.25, *Note `REPAIR TABLE': repair-table. without `USE_FRM' upgrades the `.frm' file to the current version. By default, the server writes *Note `REPAIR TABLE': 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'. *Important*: In the event that a table on the master becomes corrupted and you run *Note `REPAIR TABLE': repair-table. on it, any resulting changes to the original table are _not_ propagated to slaves. You may be able to increase *Note `REPAIR TABLE': repair-table. performance by setting certain system variables. See *Note repair-table-speed::. As of MySQL 5.1.50, *Note `REPAIR TABLE': 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 *Note `mysqld': mysqld. process, *Note `REPAIR TABLE': repair-table. generates a "cannot change ownership of the file" error unless *Note `mysqld': mysqld. is started by the `root' user.  File: manual.info, Node: restore-table, Prev: repair-table, Up: table-maintenance-sql 13.7.2.7 `RESTORE TABLE' Syntax ............................... RESTORE TABLE TBL_NAME [, TBL_NAME] ... FROM '/PATH/TO/BACKUP/DIRECTORY' *Note*: This statement is deprecated and is removed in MySQL 5.5. *Note `RESTORE TABLE': restore-table. restores the table or tables from a backup that was made with *Note `BACKUP TABLE': backup-table. The directory should be specified as a full path name. Existing tables are not overwritten; if you try to restore over an existing table, an error occurs. Just as for *Note `BACKUP TABLE': backup-table, *Note `RESTORE TABLE': restore-table. currently works only for `MyISAM' tables. Restored tables are not replicated from master to slave. The backup for each table consists of its `.frm' format file and `.MYD' data file. The restore operation restores those files, and then uses them to rebuild the `.MYI' index file. Restoring takes longer than backing up due to the need to rebuild the indexes. The more indexes the table has, the longer it takes. *Note `RESTORE TABLE': restore-table. returns a result set with the following columns. This table describes columns of the *Note `RESTORE TABLE': restore-table. result set. Column Value `Table' The table name `Op' Always `restore' `Msg_type' `status', `error', `info', `note', or `warning' `Msg_text' An informational message  File: manual.info, Node: plugin-sql, Next: set-statement, Prev: table-maintenance-sql, Up: sql-syntax-server-administration 13.7.3 Plugin and User-Defined Function Statements -------------------------------------------------- * Menu: * create-function-udf:: `CREATE FUNCTION' Syntax for User-Defined Functions * drop-function-udf:: `DROP FUNCTION' Syntax * install-plugin:: `INSTALL PLUGIN' Syntax * uninstall-plugin:: `UNINSTALL PLUGIN' Syntax  File: manual.info, Node: create-function-udf, Next: drop-function-udf, Prev: plugin-sql, Up: plugin-sql 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. *Note `DECIMAL': fixed-point-types. is a legal value after `RETURNS', but currently *Note `DECIMAL': fixed-point-types. functions return string values and should be written like `STRING' functions. SHARED_LIBRARY_NAME is the basename of the shared object 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. *Note*: This is a change in MySQL 5.1. For earlier versions of MySQL, the shared object can be located in any directory that is searched by your system's dynamic linker. For more information, see *Note udf-compiling::. To create a function, you must have the `INSERT' privilege for the `mysql' database. This is necessary because *Note `CREATE FUNCTION': 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 *Note `mysql_upgrade': mysql-upgrade. command to create it. See *Note mysql-upgrade::. An active function is one that has been loaded with *Note `CREATE FUNCTION': create-function. and not removed with *Note `DROP FUNCTION': drop-function. All active functions are reloaded each time the server starts, unless you start *Note `mysqld': 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 *Note 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 *Note `mysqld': 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 *Note `mysql_upgrade': mysql-upgrade. program to create it (see *Note mysql-upgrade::). *Note*: To upgrade the shared library associated with a UDF, issue a *Note `DROP FUNCTION': drop-function. statement, upgrade the shared library, and then issue a *Note `CREATE FUNCTION': create-function. statement. If you upgrade the shared library first and then use *Note `DROP FUNCTION': drop-function, the server may crash.  File: manual.info, Node: drop-function-udf, Next: install-plugin, Prev: create-function-udf, Up: plugin-sql 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 *Note `DROP FUNCTION': 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 *Note `DROP FUNCTION': drop-function. statement, upgrade the shared library, and then issue a *Note `CREATE FUNCTION': create-function. statement. If you upgrade the shared library first and then use *Note `DROP FUNCTION': drop-function, the server may crash. *Note `DROP FUNCTION': drop-function. is also used to drop stored functions (see *Note drop-procedure::).  File: manual.info, Node: install-plugin, Next: uninstall-plugin, Prev: drop-function-udf, Up: plugin-sql 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' table. PLUGIN_NAME is the name of the plugin as defined in the plugin descriptor structure contained in the library file (see *Note 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). *Note `INSTALL PLUGIN': 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 change to perform any final cleanup. *Note `INSTALL PLUGIN': 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 *Note `INSTALL PLUGIN': 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 *Note `INSTALL PLUGIN': install-plugin. statement. Each statement names a different plugin, but all of them specify the same library name. As of MySQL 5.1.33, *Note `INSTALL PLUGIN': 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. Before MySQL 5.1.33, a plugin is started with each option set to its default value. For options that control individual plugin loading at server startup, see *Note 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 *Note server-options::. To remove a plugin, use the *Note `UNINSTALL PLUGIN': uninstall-plugin. statement. For additional information about plugin loading, see *Note server-plugin-loading::. To see what plugins are installed, use the *Note `SHOW PLUGINS': show-plugins. statement or query the *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. table. If you recompile a plugin library and need to reinstall it, you can use either of the following methods: * Use *Note `UNINSTALL PLUGIN': uninstall-plugin. to uninstall all plugins in the library, install the new plugin library file in the plugin directory, and then use *Note `INSTALL PLUGIN': 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 *Note `INSTALL PLUGIN': install-plugin. and *Note `UNINSTALL PLUGIN': uninstall-plugin. statements. * Stop the server, install the new plugin library file in the plugin directory, and restart the server.  File: manual.info, Node: uninstall-plugin, Prev: install-plugin, Up: plugin-sql 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' table. 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. *Note `UNINSTALL 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 *Note `mysqldump': mysqldump. and remove the `WITH PARSER' clause from the dumped *Note `CREATE TABLE': create-table. statement so that you can reload the table later. If you do not care about the table, *Note `DROP TABLE': drop-table. can be used even if any plugins associated with the table are missing. For additional information about plugin loading, see *Note server-plugin-loading::.  File: manual.info, Node: set-statement, Next: show, Prev: plugin-sql, Up: sql-syntax-server-administration 13.7.4 `SET' Syntax ------------------- SET VARIABLE_ASSIGNMENT [, VARIABLE_ASSIGNMENT] ... VARIABLE_ASSIGNMENT: USER_VAR_NAME = EXPR | [GLOBAL | SESSION] SYSTEM_VAR_NAME = EXPR | [@@global. | @@session. | @@]SYSTEM_VAR_NAME = EXPR The *Note `SET': set-statement. statement assigns values to different types of variables that affect the operation of the server or your client. Older versions of MySQL employed `SET OPTION', but this syntax is deprecated in favor of *Note `SET': set-statement. without `OPTION'. This section describes use of *Note `SET': set-statement. for assigning values to variables. The *Note `SET': set-statement. statement can be used to assign values to these types of variables: * System variables. See *Note server-system-variables::. System variables also can be set at server startup, as described in *Note using-system-variables::. User-defined variables. See *Note user-variables::. * Stored procedure and function parameters, and stored program local variables. See *Note stored-program-variables::. Some variants of *Note `SET': set-statement. syntax are used in other contexts: * `SET CHARACTER SET' and `SET NAMES' assign values to character set and collation variables associated with the connection to the server. `SET ONE_SHOT' is used for replication. These variants are described later in this section. * *Note `SET PASSWORD': set-password. assigns account passwords. See *Note set-password::. * *Note `SET TRANSACTION ISOLATION LEVEL': set-transaction. sets the isolation level for transaction processing. See *Note set-transaction::. The following discussion shows the different *Note `SET': set-statement. syntaxes that you can use to set variables. The examples use the `=' assignment operator, but you can also use the `:=' assignment operator for this purpose. A user variable is written as `@VAR_NAME' and can be set as follows: SET @VAR_NAME = EXPR; Many system variables are dynamic and can be changed while the server runs by using the *Note `SET': set-statement. statement. For a list, see *Note dynamic-system-variables::. To change a system variable with *Note `SET': set-statement, refer to it as VAR_NAME, optionally preceded by a modifier: * To indicate explicitly that a variable is a global variable, precede its name by `GLOBAL' or `@@global.'. The `SUPER' privilege is required to set global variables. * To indicate explicitly that a variable is a session variable, precede its name by `SESSION', `@@session.', or `@@'. Setting a session variable requires no special privilege, but a client can change only its own session variables, not those of any other client. * `LOCAL' and `@@local.' are synonyms for `SESSION' and `@@session.'. * If no modifier is present, *Note `SET': set-statement. changes the session variable. A *Note `SET': set-statement. statement can contain multiple variable assignments, separated by commas. For example, the statement can assign values to a user-defined variable and a system variable. If you set several system variables, the most recent `GLOBAL' or `SESSION' modifier in the statement is used for following variables that have no modifier specified. Examples: SET sort_buffer_size=10000; SET @@local.sort_buffer_size=10000; SET GLOBAL sort_buffer_size=1000000, SESSION sort_buffer_size=1000000; SET @@sort_buffer_size=1000000; SET @@global.sort_buffer_size=1000000, @@local.sort_buffer_size=1000000; The `@@VAR_NAME' syntax for system variables is supported for compatibility with some other database systems. If you change a session system variable, the value remains in effect until your session ends or until you change the variable to a different value. The change is not visible to other clients. If you change a global system variable, the value is remembered and used for new connections until the server restarts. (To make a global system variable setting permanent, you should set it in an option file.) The change is visible to any client that accesses that 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 client that is currently connected (not even that of the client that issues the *Note `SET GLOBAL': set-statement. statement). To prevent incorrect usage, MySQL produces an error if you use *Note `SET GLOBAL': set-statement. with a variable that can only be used with *Note `SET SESSION': set-statement. or if you do not specify `GLOBAL' (or `@@global.') when setting a global variable. To set a `SESSION' variable to the `GLOBAL' value or a `GLOBAL' value to the compiled-in MySQL default value, use the `DEFAULT' keyword. For example, the following two statements are identical in setting the session value of `max_join_size' to the global value: SET 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, use of `DEFAULT' results in an error. It is not permitted to assign the value `DEFAULT' to user-defined variables, and not supported for stored procedure or function parameters or stored program local variables. This results in a syntax error for user-defined variables, and the results are undefined for parameters or local variables. You can refer to the values of specific global or session system variables in expressions by using one of the `@@'-modifiers. For example, you can retrieve values in a *Note `SELECT': select. statement like this: SELECT @@global.sql_mode, @@session.sql_mode, @@sql_mode; When you refer to a system variable in an expression as `@@VAR_NAME' (that is, when you do not specify `@@global.' or `@@session.'), MySQL returns the session value if it exists and the global value otherwise. (This differs from `SET @@VAR_NAME = VALUE', which always refers to the session value.) *Note*: Some variables displayed by `SHOW VARIABLES' may not be available using `SELECT @@VAR_NAME' syntax; an `Unknown system variable' occurs. As a workaround in such cases, you can use `SHOW VARIABLES LIKE 'VAR_NAME''. Suffixes for specifying a value multiplier can be used when setting a variable at server startup, but not to set the value with *Note `SET': set-statement. at runtime. On the other hand, with *Note `SET': set-statement. 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; To display system variables names and values, use the *Note `SHOW VARIABLES': show-variables. statement. (See *Note show-variables::.) The following list describes *Note `SET': set-statement. options that have nonstandard syntax (that is, options that are not set with `NAME = VALUE' syntax). * `CHARACTER SET {CHARSET_NAME | DEFAULT}' This maps all strings from and to the client with the given mapping. You can add new mappings by editing `sql/convert.cc' in the MySQL source distribution. `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 *Note charset-connection::. The default mapping can be restored by using the value `DEFAULT'. The default depends on the server configuration. `ucs2' cannot be used as a client character set, which means that it does not work for `SET CHARACTER SET'. * `NAMES {'CHARSET_NAME' [COLLATE 'COLLATION_NAME'] | DEFAULT}' `SET NAMES' 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'. The optional `COLLATE' clause may be used to specify a collation explicitly. See *Note charset-connection::. The default mapping can be restored by using a value of `DEFAULT'. The default depends on the server configuration. `ucs2' cannot be used as a client character set, which means that it does not work for `SET NAMES'. * `ONE_SHOT' This option is a modifier, not a variable. It is _only_ for internal use for replication: *Note `mysqlbinlog': mysqlbinlog. uses `SET ONE_SHOT' to modify temporarily the values of character set, collation, and time zone variables to reflect at rollforward what they were originally. `ONE_SHOT' is for internal use only and is deprecated for MySQL 5.0 and up. `ONE_SHOT' is intended for use only with the permitted set of variables. With other variables, an error occurs: mysql> SET ONE_SHOT max_allowed_packet = 1; ERROR 1382 (HY000): The 'SET ONE_SHOT' syntax is reserved for purposes internal to the MySQL server If `ONE_SHOT' is used with the permitted variables, it changes the variables as requested, but only for the next non-*Note `SET': set-statement. statement. After that, the server resets all character set, collation, and time zone-related system variables to their previous values. Example: mysql> SET ONE_SHOT character_set_connection = latin5; mysql> SET ONE_SHOT collation_connection = latin5_turkish_ci; mysql> SHOW VARIABLES LIKE '%_connection'; +--------------------------+-------------------+ | Variable_name | Value | +--------------------------+-------------------+ | character_set_connection | latin5 | | collation_connection | latin5_turkish_ci | +--------------------------+-------------------+ mysql> SHOW VARIABLES LIKE '%_connection'; +--------------------------+-------------------+ | Variable_name | Value | +--------------------------+-------------------+ | character_set_connection | latin1 | | collation_connection | latin1_swedish_ci | +--------------------------+-------------------+  File: manual.info, Node: show, Next: other-administrative-sql, Prev: set-statement, Up: sql-syntax-server-administration 13.7.5 `SHOW' Syntax -------------------- * Menu: * show-authors:: `SHOW AUTHORS' Syntax * show-binary-logs:: `SHOW BINARY LOGS' Syntax * show-binlog-events:: `SHOW BINLOG EVENTS' Syntax * show-character-set:: `SHOW CHARACTER SET' Syntax * show-collation:: `SHOW COLLATION' Syntax * show-columns:: `SHOW COLUMNS' Syntax * show-contributors:: `SHOW CONTRIBUTORS' Syntax * show-create-database:: `SHOW CREATE DATABASE' Syntax * show-create-event:: `SHOW CREATE EVENT' Syntax * show-create-function:: `SHOW CREATE FUNCTION' Syntax * show-create-procedure:: `SHOW CREATE PROCEDURE' Syntax * show-create-table:: `SHOW CREATE TABLE' Syntax * show-create-trigger:: `SHOW CREATE TRIGGER' Syntax * show-create-view:: `SHOW CREATE VIEW' Syntax * show-databases:: `SHOW DATABASES' Syntax * show-engine:: `SHOW ENGINE' Syntax * show-engines:: `SHOW ENGINES' Syntax * show-errors:: `SHOW ERRORS' Syntax * show-events:: `SHOW EVENTS' Syntax * show-function-code:: `SHOW FUNCTION CODE' Syntax * show-function-status:: `SHOW FUNCTION STATUS' Syntax * show-grants:: `SHOW GRANTS' Syntax * show-index:: `SHOW INDEX' Syntax * show-innodb-status:: `SHOW INNODB STATUS' Syntax * show-master-status:: `SHOW MASTER STATUS' Syntax * show-open-tables:: `SHOW OPEN TABLES' Syntax * show-plugins:: `SHOW PLUGINS' Syntax * show-privileges:: `SHOW PRIVILEGES' Syntax * show-procedure-code:: `SHOW PROCEDURE CODE' Syntax * show-procedure-status:: `SHOW PROCEDURE STATUS' Syntax * show-processlist:: `SHOW PROCESSLIST' Syntax * show-profile:: `SHOW PROFILE' Syntax * show-profiles:: `SHOW PROFILES' Syntax * show-scheduler-status:: `SHOW SCHEDULER STATUS' Syntax * show-slave-hosts:: `SHOW SLAVE HOSTS' Syntax * show-slave-status:: `SHOW SLAVE STATUS' Syntax * show-status:: `SHOW STATUS' Syntax * show-table-status:: `SHOW TABLE STATUS' Syntax * show-tables:: `SHOW TABLES' Syntax * show-triggers:: `SHOW TRIGGERS' Syntax * show-variables:: `SHOW VARIABLES' Syntax * show-warnings:: `SHOW WARNINGS' Syntax *Note `SHOW': show. has many forms that provide information about databases, tables, columns, or status information about the server. This section describes those following: SHOW AUTHORS 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 CONTRIBUTORS 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 INNODB STATUS 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 SCHEDULER STATUS SHOW SLAVE HOSTS SHOW SLAVE STATUS 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 *Note `SHOW': 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 *Note `SHOW': show. statements also accept a `WHERE' clause that provides more flexibility in specifying which rows to display. See *Note extended-show::. Many MySQL APIs (such as PHP) enable you to treat the result returned from a *Note `SHOW': show. statement as you would a result set from a *Note `SELECT': select.; see *Note 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 *Note `SHOW': show. statements. See *Note information-schema::.  File: manual.info, Node: show-authors, Next: show-binary-logs, Prev: show, Up: show 13.7.5.1 `SHOW AUTHORS' Syntax .............................. SHOW AUTHORS The *Note `SHOW AUTHORS': show-authors. statement displays information about the people who work on MySQL. For each author, it displays `Name', `Location', and `Comment' values. This statement was added in MySQL 5.1.3.  File: manual.info, Node: show-binary-logs, Next: show-binlog-events, Prev: show-authors, Up: show 13.7.5.2 `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 *Note 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 | +---------------+-----------+ *Note `SHOW MASTER LOGS': show-binary-logs. is equivalent to *Note `SHOW BINARY LOGS': show-binary-logs. In MySQL 5.1.63 and earlier, the `SUPER' privilege was required to use this statement. Starting with MySQL 5.1.64, a user with the `REPLICATION CLIENT' privilege may also execute this statement.  File: manual.info, Node: show-binlog-events, Next: show-character-set, Prev: show-binary-logs, Up: show 13.7.5.3 `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 *Note `SELECT': select. statement. See *Note select::. *Note*: Issuing a *Note `SHOW BINLOG EVENTS': 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 *Note `SHOW BINLOG EVENTS': show-binlog-events, use the *Note `mysqlbinlog': mysqlbinlog. utility to save the binary log to a text file for later examination and analysis. See *Note mysqlbinlog::. *Note*: Some events relating to the setting of user and system variables are not included in the output from *Note `SHOW BINLOG EVENTS': show-binlog-events. To get complete coverage of events within a binary log, use *Note `mysqlbinlog': mysqlbinlog.  File: manual.info, Node: show-character-set, Next: show-collation, Prev: show-binlog-events, Up: show 13.7.5.4 `SHOW CHARACTER SET' Syntax .................................... SHOW CHARACTER SET [LIKE 'PATTERN' | WHERE EXPR] The *Note `SHOW CHARACTER SET': 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 *Note 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.  File: manual.info, Node: show-collation, Next: show-columns, Prev: show-character-set, Up: show 13.7.5.5 `SHOW COLLATION' Syntax ................................ SHOW COLLATION [LIKE 'PATTERN' | WHERE EXPR] This statement lists collations supported by the server. By default, the output from *Note `SHOW COLLATION': 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 *Note extended-show::. For example: mysql> SHOW COLLATION LIKE 'latin1%'; +-------------------+---------+----+---------+----------+---------+ | Collation | Charset | Id | Default | Compiled | Sortlen | +-------------------+---------+----+---------+----------+---------+ | latin1_german1_ci | latin1 | 5 | | | 0 | | latin1_swedish_ci | latin1 | 8 | Yes | Yes | 0 | | latin1_danish_ci | latin1 | 15 | | | 0 | | latin1_german2_ci | latin1 | 31 | | Yes | 2 | | latin1_bin | latin1 | 47 | | Yes | 0 | | latin1_general_ci | latin1 | 48 | | | 0 | | latin1_general_cs | latin1 | 49 | | | 0 | | latin1_spanish_ci | latin1 | 94 | | | 0 | +-------------------+---------+----+---------+----------+---------+ 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 | ...  File: manual.info, Node: show-columns, Next: show-contributors, Prev: show-collation, Up: show 13.7.5.6 `SHOW COLUMNS' Syntax .............................. SHOW [FULL] COLUMNS {FROM | IN} TBL_NAME [{FROM | IN} DB_NAME] [LIKE 'PATTERN' | WHERE EXPR] *Note `SHOW COLUMNS': show-columns. displays information about the columns in a given table. It also works for views. 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 *Note 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 | | | | | Country | char(3) | NO | UNI | | | | District | char(20) | YES | MUL | | | | Population | int(11) | NO | | 0 | | +------------+----------+------+-----+---------+----------------+ 5 rows in set (0.00 sec) If the data types differ from what you expect them to be based on a *Note `CREATE TABLE': create-table. statement, note that MySQL sometimes changes data types when you create or alter a table. The conditions under which this occurs are described in *Note silent-column-changes::. The `FULL' keyword causes the output to include the column collation and comments, as well as the privileges you have for each column. 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: mysql> SHOW COLUMNS FROM mytable FROM mydb; mysql> SHOW COLUMNS FROM mydb.mytable; *Note `SHOW COLUMNS': show-columns. displays the following values for each table column: `Field' indicates the column name. `Type' indicates the column data type. `Collation' indicates the collation for nonbinary string columns, or `NULL' for other columns. This value is displayed only if you use the `FULL' keyword. The `Null' field contains `YES' if `NULL' values can be stored in the column, `NO' if not. The `Key' field indicates 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. The `Default' field indicates the default value that is assigned to the column. This is `NULL' if the column has an explicit default of `NULL'. As of MySQL 5.1.23, `Default' is also `NULL' if the column definition has no `DEFAULT' clause. The `Extra' field contains 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; as of MySQL 5.1.23, `on update CURRENT_TIMESTAMP' for *Note `TIMESTAMP': datetime. columns that have the `ON UPDATE CURRENT_TIMESTAMP' attribute. `Privileges' indicates the privileges you have for the column. This value is displayed only if you use the `FULL' keyword. `Comment' indicates any comment the column has. This value is displayed only if you use the `FULL' keyword. `SHOW FIELDS' is a synonym for *Note `SHOW COLUMNS': show-columns. You can also list a table's columns with the *Note `mysqlshow DB_NAME TBL_NAME': mysqlshow. command. The *Note `DESCRIBE': describe. statement provides information similar to *Note `SHOW COLUMNS': show-columns. See *Note describe::. The *Note `SHOW CREATE TABLE': show-create-table, *Note `SHOW TABLE STATUS': show-table-status, and *Note `SHOW INDEX': show-index. statements also provide information about tables. See *Note show::.  File: manual.info, Node: show-contributors, Next: show-create-database, Prev: show-columns, Up: show 13.7.5.7 `SHOW CONTRIBUTORS' Syntax ................................... SHOW CONTRIBUTORS The *Note `SHOW CONTRIBUTORS': show-contributors. statement displays information about the people who contribute to MySQL source or to causes that we support. For each contributor, it displays `Name', `Location', and `Comment' values. This statement was added in MySQL 5.1.12.  File: manual.info, Node: show-create-database, Next: show-create-event, Prev: show-contributors, Up: show 13.7.5.8 `SHOW CREATE DATABASE' Syntax ...................................... SHOW CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] DB_NAME Shows the *Note `CREATE DATABASE': 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. *Note `SHOW CREATE SCHEMA': show-create-database. is a synonym for *Note `SHOW CREATE DATABASE': 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 */ *Note `SHOW CREATE DATABASE': show-create-database. quotes table and column names according to the value of the `sql_quote_show_create' option. See *Note server-system-variables::.  File: manual.info, Node: show-create-event, Next: show-create-function, Prev: show-create-database, Up: show 13.7.5.9 `SHOW CREATE EVENT' Syntax ................................... SHOW CREATE EVENT EVENT_NAME This statement displays the *Note `CREATE EVENT': 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 *Note 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. These columns were added in MySQL 5.1.21. Note that the output reflects the current status of the event (`ENABLE') rather than the status with which it was created. This statement was implemented in MySQL 5.1.6.  File: manual.info, Node: show-create-function, Next: show-create-procedure, Prev: show-create-event, Up: show 13.7.5.10 `SHOW CREATE FUNCTION' Syntax ....................................... SHOW CREATE FUNCTION FUNC_NAME This statement is similar to *Note `SHOW CREATE PROCEDURE': show-create-procedure. but for stored functions. See *Note show-create-procedure::.  File: manual.info, Node: show-create-procedure, Next: show-create-table, Prev: show-create-function, Up: show 13.7.5.11 `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, *Note `SHOW CREATE FUNCTION': show-create-function, displays information about stored functions (see *Note show-create-function::). Both statements require that you be the owner of the routine or have *Note `SELECT': 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. These columns were added in MySQL 5.1.21.  File: manual.info, Node: show-create-table, Next: show-create-trigger, Prev: show-create-procedure, Up: show 13.7.5.12 `SHOW CREATE TABLE' Syntax .................................... SHOW CREATE TABLE TBL_NAME Shows the *Note `CREATE TABLE': 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) default NULL auto_increment, s char(60) default NULL, PRIMARY KEY (id) ) ENGINE=MyISAM *Note `SHOW CREATE TABLE': show-create-table. quotes table and column names according to the value of the `sql_quote_show_create' option. See *Note server-system-variables::.  File: manual.info, Node: show-create-trigger, Next: show-create-view, Prev: show-create-table, Up: show 13.7.5.13 `SHOW CREATE TRIGGER' Syntax ...................................... SHOW CREATE TRIGGER TRIGGER_NAME This statement shows the *Note `CREATE TRIGGER': create-trigger. statement that creates the named trigger. mysql> SHOW CREATE TRIGGER ins_sum\G *************************** 1. row *************************** Trigger: ins_sum sql_mode: 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: latin1 collation_connection: latin1_swedish_ci Database Collation: latin1_swedish_ci *Note `SHOW CREATE TRIGGER': 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 *Note `CREATE TRIGGER': 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. *Note `SHOW CREATE TRIGGER': 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 statement to be executed when the trigger activates. * `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. *Note `SHOW CREATE TRIGGER': show-create-trigger. was added in MySQL 5.1.21. You can also obtain information about trigger objects from `INFORMATION_SCHEMA', which contains a *Note `TRIGGERS': triggers-table. table. See *Note triggers-table::.  File: manual.info, Node: show-create-view, Next: show-databases, Prev: show-create-trigger, Up: show 13.7.5.14 `SHOW CREATE VIEW' Syntax ................................... SHOW CREATE VIEW VIEW_NAME This statement shows the *Note `CREATE VIEW': 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. These columns were added in MySQL 5.1.21. Use of *Note `SHOW CREATE VIEW': 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 *Note `VIEWS': views-table. table. See *Note 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 *Note `SELECT': select. are stripped from the definition by the server.  File: manual.info, Node: show-databases, Next: show-engine, Prev: show-create-view, Up: show 13.7.5.15 `SHOW DATABASES' Syntax ................................. SHOW {DATABASES | SCHEMAS} [LIKE 'PATTERN' | WHERE EXPR] *Note `SHOW DATABASES': show-databases. lists the databases on the MySQL server host. *Note `SHOW SCHEMAS': show-databases. is a synonym for *Note `SHOW DATABASES': 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 *Note extended-show::. You see only those databases for which you have some kind of privilege, unless you have the global *Note `SHOW DATABASES': show-databases. privilege. You can also get this list using the *Note `mysqlshow': 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.  File: manual.info, Node: show-engine, Next: show-engines, Prev: show-databases, Up: show 13.7.5.16 `SHOW ENGINE' Syntax .............................. SHOW ENGINE ENGINE_NAME {STATUS | MUTEX} *Note `SHOW ENGINE': show-engine. displays operational information about a storage engine. The following statements currently are supported: SHOW ENGINE INNODB STATUS SHOW ENGINE INNODB MUTEX SHOW ENGINE {NDB | NDBCLUSTER} STATUS Older (and now deprecated) synonyms are *Note `SHOW INNODB STATUS': show-innodb-status. for *Note `SHOW ENGINE INNODB STATUS': show-engine. and `SHOW MUTEX STATUS' for *Note `SHOW ENGINE INNODB MUTEX': show-engine. *Note `SHOW INNODB STATUS': show-innodb-status. and `SHOW MUTEX STATUS' are removed in MySQL 5.5. In MySQL 5.0, *Note `SHOW ENGINE INNODB MUTEX': show-engine. is invoked as `SHOW MUTEX STATUS'. The latter statement displays similar information but in a somewhat different output format. *Note `SHOW ENGINE BDB LOGS': show-engine. formerly displayed status information about `BDB' log files. As of MySQL 5.1.12, the `BDB' storage engine is not supported, and this statement produces a warning. *Note `SHOW ENGINE INNODB STATUS': show-engine. 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 *Note innodb-monitors::. *Note `SHOW ENGINE INNODB MUTEX': show-engine. displays `InnoDB' mutex statistics. From MySQL 5.1.2 to 5.1.14, the statement displays the following output fields: * `Type' Always `InnoDB'. * `Name' The mutex name and the source file where it is implemented. Example: `&pool->mutex:mem0pool.c' The mutex name indicates its purpose. For example, the `log_sys' mutex is used by the `InnoDB' logging subsystem and indicates how intensive logging activity is. The `buf_pool' mutex protects the `InnoDB' buffer pool. * `Status' The mutex status. The fields contains several values: * `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 the 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, if the `timed_mutexes' system variable is 1 (`ON'). If `timed_mutexes' is 0 (`OFF'), timing is disabled, so `os_wait_times' is 0. `timed_mutexes' is off by default. From MySQL 5.1.15 on, the statement displays the following output fields: * `Type' Always `InnoDB'. * `Name' The source file where the mutex is implemented, and the line number in the file where the mutex is created. The line number may change depending on your version of MySQL. * `Status' This field displays the same values as previously described (`count', `spin_waits', `spin_rounds', `os_waits', `os_yields', `os_wait_times'), but only if `UNIV_DEBUG' was defined at MySQL compilation time (for example, in `include/univ.i' in the `InnoDB' part of the MySQL source tree). If `UNIV_DEBUG' was not defined, the statement displays only the `os_waits' value. In the latter case (without `UNIV_DEBUG'), the information on which the output is based is insufficient to distinguish regular mutexes and mutexes that protect rw-locks (which permit multiple readers or a single writer). Consequently, the output may appear to contain multiple rows for the same mutex. Information from this statement can be used to diagnose system problems. For example, large values of `spin_waits' and `spin_rounds' may indicate scalability problems. If the server has the *Note `NDBCLUSTER': mysql-cluster. storage engine enabled, *Note `SHOW ENGINE NDB STATUS': show-engine. displays cluster status information such as the number of connected data nodes, the cluster connectstring, and cluster binlog 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=192.168.0.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 rows with `connection' and `binlog' in the `Name' column were added to the output of this statement in MySQL 5.1. 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. This table describes name and value pairs found in the `connection' row `Status' column in the output of the *Note `SHOW ENGINE NDB STATUS': show-engine. command. 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 *Note `mysqld': mysqld. has connected or reconnected to cluster data nodes The `binlog' row's `Status' column contains information relating to MySQL Cluster Replication. The name/value pairs it contains are described in the following table. This table describes name and value pairs found in the binlog row Status column in the output of the SHOW ENGINE NDB STATUS command. 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 binlog thread `latest_handled_binlog_epoch' The most recent epoch processed by the binlog thread (for writing to the binlog) `latest_applied_binlog_epoch' The most recent epoch actually written to the binlog See *Note mysql-cluster-replication::, for more information. The remaining rows from the output of *Note `SHOW ENGINE NDB STATUS': show-engine. 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 *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table.) is performed on an *Note `NDB': mysql-cluster. 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 *Note `BLOB': blob. column in an *Note `NDB': mysql-cluster. 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*: *Note `SHOW ENGINE NDB STATUS': show-engine. returns an empty result if no operations involving *Note `NDB': mysql-cluster. tables have been performed during the current session by the MySQL client accessing the SQL node on which this statement is run.  File: manual.info, Node: show-engines, Next: show-errors, Prev: show-engine, Up: show 13.7.5.17 `SHOW ENGINES' Syntax ............................... SHOW [STORAGE] ENGINES *Note `SHOW 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. `SHOW TABLE TYPES' is a synonym, but is deprecated and is removed in MySQL 5.5. mysql> SHOW ENGINES\G *************************** 1. row *************************** Engine: MEMORY Support: YES Comment: Hash based, stored in memory, useful for temporary tables Transactions: NO XA: NO Savepoints: NO *************************** 2. row *************************** Engine: MyISAM Support: DEFAULT Comment: Default engine as of MySQL 3.23 with great performance Transactions: NO XA: NO Savepoints: NO *************************** 3. row *************************** Engine: InnoDB Support: YES Comment: Supports transactions, row-level locking, and foreign keys Transactions: YES XA: YES Savepoints: YES *************************** 4. row *************************** Engine: EXAMPLE Support: YES Comment: Example storage engine Transactions: NO XA: NO Savepoints: NO *************************** 5. row *************************** Engine: ARCHIVE Support: YES Comment: Archive 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: BLACKHOLE Support: YES Comment: /dev/null storage engine (anything you write » to it disappears) Transactions: NO XA: NO Savepoints: NO *************************** 8. row *************************** Engine: FEDERATED Support: YES Comment: Federated MySQL storage engine Transactions: NO XA: NO Savepoints: NO *************************** 9. row *************************** Engine: MRG_MYISAM Support: YES Comment: Collection of identical MyISAM tables Transactions: NO XA: NO Savepoints: NO The output from *Note `SHOW ENGINES': 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. This table describes values for the `Support' column in the output of the *Note `SHOW ENGINES': show-engines. command. 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 file should contain a reason indicating why the option is disabled. See *Note 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. For the *Note `NDBCLUSTER': mysql-cluster. storage engine, `DISABLED' means the server was compiled with support for MySQL Cluster, but was not started with the `--ndbcluster' option. All MySQL servers support `MyISAM' tables, because `MyISAM' is the default storage engine. It is not possible to disable `MyISAM'. The `Transactions', `XA', and `Savepoints' columns were added in MySQL 5.1.2. They indicate whether the storage engine supports transactions, XA transactions, and savepoints, respectively.  File: manual.info, Node: show-errors, Next: show-events, Prev: show-engines, Up: show 13.7.5.18 `SHOW ERRORS' Syntax .............................. SHOW ERRORS [LIMIT [OFFSET,] ROW_COUNT] SHOW COUNT(*) ERRORS *Note `SHOW ERRORS': show-errors. is a diagnostic statement that is similar to *Note `SHOW WARNINGS': 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 *Note `SELECT': select. statement. See *Note select::. The *Note `SHOW COUNT(*) ERRORS': show-errors. statement displays the number of errors. You can also retrieve this number from the `error_count' variable: SHOW COUNT(*) ERRORS; SELECT @@error_count; *Note `SHOW ERRORS': show-errors. and `error_count' apply only to errors, not warnings or notes. In other respects, they are similar to *Note `SHOW WARNINGS': show-warnings. and `warning_count'. In particular, *Note `SHOW ERRORS': 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 *Note show-warnings::.  File: manual.info, Node: show-events, Next: show-function-code, Prev: show-errors, Up: show 13.7.5.19 `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, *Note `SHOW EVENTS': 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 *Note extended-show::. *Note `SHOW EVENTS': 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'. This column was added in MySQL 5.1.17. See the Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/) for MySQL 5.1.17 for important information if you are using the Event Scheduler and are upgrading to MySQL 5.1.17 or later from an earlier version. * `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 *Note `DATETIME': 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 *Note `DATETIME': datetime. value, and is `NULL' if no start date and time are defined for the event. (Prior to MySQL 5.1.8, it defaulted to `'0000-00-00 00:00:00'' in such cases.) For a transient event, this column is always `NULL'. * `Ends': The end date and time for a recurring event. This is displayed as a *Note `DATETIME': 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' was added in MySQL 5.1.18. This value 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. This column was added in MySQL 5.1.18. * `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. These columns were added in MySQL 5.1.21. For more information about `SLAVE_DISABLED' and the `Originator' column, see *Note replication-features-invoked::. The event action statement is not shown in the output of *Note `SHOW EVENTS': show-events. Use *Note `SHOW CREATE EVENT': show-create-event. or the *Note `INFORMATION_SCHEMA.EVENTS': events-table. table. Times displayed by *Note `SHOW EVENTS': show-events. are given in the event time zone (or UTC prior to MySQL 5.1.17), as discussed in *Note events-metadata::. The columns in the output of *Note `SHOW EVENTS': show-events. are similar to, but not identical to the columns in the *Note `INFORMATION_SCHEMA.EVENTS': events-table. table. See *Note events-table::. *Note `SHOW EVENTS': show-events. was added in MySQL 5.1.6. *Note*: In MySQL 5.1.11 and earlier, *Note `SHOW EVENTS': show-events. displayed only those events for which the current user was the definer, and the *Note `SHOW FULL EVENTS': show-events. statement was used for viewing events defined by all users on a given schema. *Note `SHOW FULL EVENTS': show-events. was removed in MySQL 5.1.12.  File: manual.info, Node: show-function-code, Next: show-function-status, Prev: show-events, Up: show 13.7.5.20 `SHOW FUNCTION CODE' Syntax ..................................... SHOW FUNCTION CODE FUNC_NAME This statement is similar to *Note `SHOW PROCEDURE CODE': show-procedure-code. but for stored functions. See *Note show-procedure-code::.  File: manual.info, Node: show-function-status, Next: show-grants, Prev: show-function-code, Up: show 13.7.5.21 `SHOW FUNCTION STATUS' Syntax ....................................... SHOW FUNCTION STATUS [LIKE 'PATTERN' | WHERE EXPR] This statement is similar to *Note `SHOW PROCEDURE STATUS': show-procedure-status. but for stored functions. See *Note show-procedure-status::.  File: manual.info, Node: show-grants, Next: show-index, Prev: show-function-status, Up: show 13.7.5.22 `SHOW GRANTS' Syntax .............................. SHOW GRANTS [FOR USER] This statement lists the *Note `GRANT': grant. statement or statements that must be issued to duplicate the privileges that are granted to a MySQL user account. The account is named using the same format as for the *Note `GRANT': grant. statement; for example, `'jeffrey'@'localhost''. If you specify only the user name part of the account name, a host name part of `'%'' is used. For additional information about specifying account names, see *Note grant::. mysql> SHOW GRANTS FOR 'root'@'localhost'; +---------------------------------------------------------------------+ | Grants for root@localhost | +---------------------------------------------------------------------+ | GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' WITH GRANT OPTION | +---------------------------------------------------------------------+ To list the privileges granted to the account that 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(); As of MySQL 5.1.12, if `SHOW GRANTS FOR CURRENT_USER' (or any of the equivalent syntaxes) is used in `DEFINER' context, such as within a stored procedure that is defined with `SQL SECURITY DEFINER'), the grants displayed are those of the definer and not the invoker. *Note `SHOW GRANTS': show-grants. displays only the privileges granted explicitly to the named account. Other privileges might be available to the account, but they are not displayed. For example, if an anonymous account exists, the named account might be able to use its privileges, but *Note `SHOW GRANTS': show-grants. will not display them. *Note `SHOW GRANTS': show-grants. requires the `SELECT' privilege for the `mysql' database, except to see the privileges for the current user.  File: manual.info, Node: show-index, Next: show-innodb-status, Prev: show-grants, Up: show 13.7.5.23 `SHOW INDEX' Syntax ............................. SHOW {INDEX | INDEXES | KEYS} {FROM | IN} TBL_NAME [{FROM | IN} DB_NAME] [WHERE EXPR] *Note `SHOW INDEX': show-index. returns table index information. The format resembles that of the `SQLStatistics' call in ODBC. *Note `SHOW INDEX': 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. In MySQL, this can have values ``A'' (Ascending) or `NULL' (Not sorted). * `Cardinality' An estimate of the number of unique values in the index. This is updated by running *Note `ANALYZE TABLE': analyze-table. or *Note `myisamchk -a': myisamchk. `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 number of indexed characters if the column is only partly indexed, `NULL' if the entire column is indexed. * `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. 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 *Note extended-show::. You can also list a table's indexes with the *Note `mysqlshow -k DB_NAME TBL_NAME': mysqlshow. command.  File: manual.info, Node: show-innodb-status, Next: show-master-status, Prev: show-index, Up: show 13.7.5.24 `SHOW INNODB STATUS' Syntax ..................................... SHOW INNODB STATUS In MySQL 5.1, this is a deprecated synonym for *Note `SHOW ENGINE INNODB STATUS': show-engine. See *Note show-engine::. *Note `SHOW INNODB STATUS': show-innodb-status. is removed in MySQL 5.5.  File: manual.info, Node: show-master-status, Next: show-open-tables, Prev: show-innodb-status, Up: show 13.7.5.25 `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; +---------------+----------+--------------+------------------+ | File | Position | Binlog_Do_DB | Binlog_Ignore_DB | +---------------+----------+--------------+------------------+ | mysql-bin.003 | 73 | test | manual,mysql | +---------------+----------+--------------+------------------+  File: manual.info, Node: show-open-tables, Next: show-plugins, Prev: show-master-status, Up: show 13.7.5.26 `SHOW OPEN TABLES' Syntax ................................... SHOW OPEN TABLES [{FROM | IN} DB_NAME] [LIKE 'PATTERN' | WHERE EXPR] *Note `SHOW OPEN TABLES': show-open-tables. lists the non-`TEMPORARY' tables that are currently open in the table cache. See *Note table-cache::. The `WHERE' clause can be given to select rows using more general conditions, as discussed in *Note extended-show::. The `FROM' and `LIKE' clauses may be used beginning with MySQL 5.1.24. The `LIKE' clause, if present, indicates which table names to match. The `FROM' clause, if present, restricts the tables shown to those present in the DB_NAME database. *Note `SHOW OPEN TABLES': 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 *Note `HANDLER ... OPEN': handler. statement and decreased by *Note `HANDLER ... CLOSE': handler. * `Name_locked' Whether the table name is locked. Name locking is used for operations such as dropping or renaming tables.  File: manual.info, Node: show-plugins, Next: show-privileges, Prev: show-open-tables, Up: show 13.7.5.27 `SHOW PLUGINS' Syntax ............................... SHOW PLUGINS *Note `SHOW PLUGINS': show-plugins. displays information about server plugins. Plugin information is also available in the `INFORMATION_SCHEMA.PLUGINS' table. See *Note plugins-table::. Example of *Note `SHOW PLUGINS': 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 ... *Note `SHOW PLUGINS': show-plugins. output has the following columns: * `Name': The name used to refer to the plugin in statements such as *Note `INSTALL PLUGIN': install-plugin. and *Note `UNINSTALL PLUGIN': uninstall-plugin. * `Status': The plugin status, one of `ACTIVE', `INACTIVE', `DISABLED', or `DELETED'. * `Type': The type of plugin, such as `STORAGE ENGINE' or `INFORMATION_SCHEMA'. * `Library': The name of the plugin shared object file. This is the name used to refer to the plugin file in statements such as *Note `INSTALL PLUGIN': install-plugin. and *Note `UNINSTALL PLUGIN': 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 *Note `UNINSTALL PLUGIN': uninstall-plugin. * `License': How the plugin is licensed; for example, `GPL'. For plugins installed with *Note `INSTALL PLUGIN': 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 *Note `SHOW PLUGINS': show-plugins, see *Note plugin-api::. `SHOW PLUGIN' was added in MySQL 5.1.5 and renamed to *Note `SHOW PLUGINS': show-plugins. in 5.1.9. `SHOW PLUGIN' is deprecated as of 5.1.9 and generates a warning, and is removed in MySQL 5.5.)  File: manual.info, Node: show-privileges, Next: show-procedure-code, Prev: show-plugins, Up: show 13.7.5.28 `SHOW PRIVILEGES' Syntax .................................. SHOW PRIVILEGES *Note `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 *Note `SHOW GRANTS': show-grants. statement. See *Note show-grants::, for more information.  File: manual.info, Node: show-procedure-code, Next: show-procedure-status, Prev: show-privileges, Up: show 13.7.5.29 `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, *Note `SHOW FUNCTION CODE': show-function-code, displays information about stored functions (see *Note show-function-code::). Both statements require that you be the owner of the routine or have *Note `SELECT': 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 *Note `INSERT': insert, and so on). The final row contains an instruction `jump 2', meaning `GOTO instruction #2'. These statements were added in MySQL 5.1.3.  File: manual.info, Node: show-procedure-status, Next: show-processlist, Prev: show-procedure-code, Up: show 13.7.5.30 `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, *Note `SHOW FUNCTION STATUS': show-function-status, displays information about stored functions (see *Note 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 *Note 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. These columns were added in MySQL 5.1.21. You can also get information about stored routines from the *Note `ROUTINES': routines-table. table in `INFORMATION_SCHEMA'. See *Note routines-table::.  File: manual.info, Node: show-processlist, Next: show-profile, Prev: show-procedure-status, Up: show 13.7.5.31 `SHOW PROCESSLIST' Syntax ................................... SHOW [FULL] PROCESSLIST *Note `SHOW PROCESSLIST': show-processlist. shows you which threads are running. You can also get this information from the `INFORMATION_SCHEMA' *Note `PROCESSLIST': processlist-table. table or the *Note `mysqladmin processlist': mysqladmin. 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. This 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 *Note `KILL': kill. statement. See *Note kill::. Here is an example of *Note `SHOW PROCESSLIST': 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 *Note `SHOW PROCESSLIST': show-processlist. have the following meanings: * `Id' The connection identifier. * `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). *Note `SHOW PROCESSLIST': 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 *Note thread-information::. The value of this column corresponds to the `COM_XXX' commands of the client/server protocol and `Com_XXX' status variables. See *Note server-status-variables:: * `Time' The time in seconds that the thread has been in its current state. * `State' An action, event, or state that indicates what the thread is doing. Descriptions for `State' values can be found at *Note 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 *Note `SHOW PROCESSLIST': 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 *Note `SELECT': select. statement, the `Info' value shows the *Note `SELECT': select. statement.  File: manual.info, Node: show-profile, Next: show-profiles, Prev: show-processlist, Up: show 13.7.5.32 `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 *Note `SHOW PROFILE': show-profile. and *Note `SHOW PROFILES': show-profiles. statements display profiling information that indicates resource usage for statements executed during the course of the current session. 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; *Note `SHOW PROFILES': 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 *Note `SHOW PROFILE': show-profile. and *Note `SHOW PROFILES': 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. *Note `SHOW PROFILE': 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, *Note `SHOW PROFILE': show-profile. displays information for statement N. The values of N correspond to the `Query_ID' values displayed by *Note `SHOW PROFILES': 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, *Note `SHOW PROFILE': show-profile. displays `Status' and `Duration' columns. The `Status' values are like the `State' values displayed by *Note `SHOW PROCESSLIST': show-processlist, although there might be some minor differences in interpretion for the two statements for some status values (see *Note 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. *Note `SHOW PROFILES': show-profiles. and *Note `SHOW PROFILE': show-profile. were added in MySQL 5.1.24 (but were not added to binary distributions by default until 5.1.28). You can also get profiling information from the *Note `PROFILING': profiling-table. table in `INFORMATION_SCHEMA'. See *Note 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;  File: manual.info, Node: show-profiles, Next: show-scheduler-status, Prev: show-profile, Up: show 13.7.5.33 `SHOW PROFILES' Syntax ................................ SHOW PROFILES The *Note `SHOW PROFILES': show-profiles. statement, together with *Note `SHOW PROFILE': show-profile, displays profiling information that indicates resource usage for statements executed during the course of the current session. For more information, see *Note show-profile::.  File: manual.info, Node: show-scheduler-status, Next: show-slave-hosts, Prev: show-profiles, Up: show 13.7.5.34 `SHOW SCHEDULER STATUS' Syntax ........................................ SHOW SCHEDULER STATUS This statement provides debugging information regarding the Event Scheduler's state. It is supported only in `-debug' builds of MySQL 5.1.11, and was removed in 5.1.12 and subsequent releases. Sample output is shown here: +--------------------------------+---------------------+ | Name | Value | +--------------------------------+---------------------+ | scheduler state | INITIALIZED | | thread_id | NULL | | scheduler last locked at | init_scheduler::313 | | scheduler last unlocked at | init_scheduler::318 | | scheduler waiting on condition | 0 | | scheduler workers count | 0 | | scheduler executed events | 0 | | scheduler data locked | 0 | | queue element count | 1 | | queue data locked | 0 | | queue data attempting lock | 0 | | queue last locked at | create_event::218 | | queue last unlocked at | create_event::222 | | queue last attempted lock at | ::0 | | queue waiting on condition | 0 | | next activation at | 0-00-00 00:00:00 | +--------------------------------+---------------------+ In MySQL 5.1.12 and later, this information can be obtained using *Note `mysqladmin debug': mysqladmin. (See *Note mysqladmin::.) For more information about obtaining Event Scheduler status information, see *Note events-status-info::.  File: manual.info, Node: show-slave-hosts, Next: show-slave-status, Prev: show-scheduler-status, Up: show 13.7.5.35 `SHOW SLAVE HOSTS' Syntax ................................... SHOW SLAVE HOSTS Displays a list of replication slaves currently registered with the master. Only slaves started with the `--report-host=HOST_NAME' option are visible in this list. The list is displayed on any server (not just the master server). The output looks like this: mysql> SHOW SLAVE HOSTS; +------------+-----------+------+-----------+ | Server_id | Host | Port | Master_id | +------------+-----------+------+-----------+ | 192168010 | iconnect2 | 3306 | 192168011 | | 1921680101 | athena | 3306 | 192168011 | +------------+-----------+------+-----------+ * `Server_id': The unique server ID of the slave server, as configured in the server's option file, or on the command line with `--server-id=VALUE'. * `Host': The host name of the slave server, as configured in the server's option file, or on the command line with `--report-host=HOST_NAME'. Note that this can differ from the machine name as configured in the operating system. * `Port': The port the slave server is listening on. * `Master_id': The unique server ID of the master server that the slave server is replicating from. Some MySQL versions report another variable, `Rpl_recovery_rank'. This variable was never used, and was eventually removed. (Bug #13963)  File: manual.info, Node: show-slave-status, Next: show-status, Prev: show-slave-hosts, Up: show 13.7.5.36 `SHOW SLAVE STATUS' Syntax .................................... SHOW SLAVE STATUS 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 *Note `mysql': 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: root Master_Port: 3306 Connect_Retry: 3 Master_Log_File: gbichot-bin.005 Read_Master_Log_Pos: 79 Relay_Log_File: gbichot-relay-bin.005 Relay_Log_Pos: 548 Relay_Master_Log_File: gbichot-bin.005 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: 79 Relay_Log_Space: 552 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: 8 Master_SSL_Verify_Server_Cert: No Last_IO_Errno: 0 Last_IO_Error: Last_SQL_Errno: 0 Last_SQL_Error: The following list describes the fields returned by *Note `SHOW SLAVE STATUS': show-slave-status. For additional information about interpreting their meanings, see *Note replication-administration-status::. * `Slave_IO_State' A copy of the `State' field of the *Note `SHOW PROCESSLIST': 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 *Note 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 *Note `CHANGE MASTER TO': change-master-to. statement or `--master-connect-retry' option. * `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' depends on the server version as shown in the following table. For the `MYSQL_SLAVE_RUN_NOT_CONNECT' state, `Slave_IO_Running' depends on the MySQL server version. This table shows MySQL version dependency for `Slave_IO_Running'. MySQL Version `Slave_IO_Running' 4.1 (4.1.13 and earlier); 5.0 `Yes' (5.0.11 and earlier) 4.1 (4.1.14 and later); 5.0 `No' (5.0.12 and later) 5.1 (5.1.45 and earlier) `No' 5.1 (5.1.46 and later); 5.5 `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'. Beginning with MySQL 5.1.46, the value of the `Slave_running' system status variable corresponds with this value. (Bug #30703) * `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' As of MySQL 5.1.20, these columns are aliases for `Last_SQL_Errno' and `Last_SQL_Error'. Before 5.1.20, they indicate the error number and error message returned by the most recently executed statement. An error number of 0 and message of the empty string mean `no error.' If the `Last_Error' value is not empty, the error values also appear in the slave's error log. Beginning with MySQL 5.1.37, and with MySQL Cluster NDB 6.2.17, MySQL Cluster NDB 6.3.23, and MySQL Cluster NDB 6.4.3: Issuing *Note `RESET MASTER': reset-master. or *Note `RESET SLAVE': reset-slave. resets the values shown in these columns. (Bug #34654, Bug #44270) *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 *Note `SHOW SLAVE STATUS': 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 *Note 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 *Note `CHANGE MASTER TO': 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. * `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 *Note `START SLAVE': 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 `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. * `Master_SSL_Allowed', `Master_SSL_CA_File', `Master_SSL_CA_Path', `Master_SSL_Cert', `Master_SSL_Cipher', `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_KEY', and `MASTER_SSL_VERIFY_SERVER_CERT' options to the *Note `CHANGE MASTER TO': change-master-to. statement. See *Note change-master-to::. `MASTER_SSL_VERIFY_SERVER_CERT' was added in MySQL 5.1.18. * `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 most 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. This field is `NULL' (undefined or unknown) if the slave SQL thread is not running, or if the slave I/O thread is not running or is not connected to the master. For example, if the slave I/O thread is running but is not connected to the master and is sleeping for the number of seconds given by the *Note `CHANGE MASTER TO': change-master-to. statement or `--master-connect-retry' option (default 60) before reconnecting, the value is `NULL'. This is because the slave cannot know what the master is doing, and so cannot say reliably how late it is. 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 *Note `TIMESTAMP': datetime. 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. * `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. These columns were added in MySQL 5.1.20. MySQL Cluster Beginning with MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3: Issuing *Note `RESET MASTER': reset-master. or *Note `RESET SLAVE': reset-slave. resets the values shown in these columns. This applies to MySQL Cluster only. (Bug #34654) * `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. These columns were added in MySQL 5.1.20. Example: Last_SQL_Errno: 1051 Last_SQL_Error: error 'Unknown table 'z'' on query 'drop table z' The message indicates that the table `z' existed on the master and was dropped there, but it did not exist on the slave, so *Note `DROP TABLE': drop-table. failed on the slave. (This might occur, for example, if you forget to copy the table to the slave when setting up replication.) MySQL Cluster Beginning with MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3: Issuing *Note `RESET MASTER': reset-master. or *Note `RESET SLAVE': reset-slave. resets the values shown in these columns. This applies to MySQL Cluster only. (Bug #34654) * `Replicate_Ignore_Server_Ids' (MySQL Cluster only) Beginning with MySQL Cluster NDB 6.1.29, MySQL Cluster NDB 6.3.31, MySQL Cluster NDB 7.0.11, and MySQL Cluster NDB 7.1.0, you can tell a slave to ignore events from 0 or more masters using the `IGNORE_SERVER_IDS' option in a *Note `CHANGE MASTER TO': change-master-to. statement. (See Bug #47037.) This is normally of interest only when using a circular or other multi-master replication setup. The message shown for `Replicate_Ignore_Server_Ids' consists of a space-delimited list of one or more numbers, the first value indicating the number of servers to be ignored; if not 0 (the default), this server-count value is followed by the actual server IDs. For example, if a *Note `CHANGE MASTER TO': 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: Replicate_Ignore_Server_Ids: 3 2 6 9  File: manual.info, Node: show-status, Next: show-table-status, Prev: show-slave-status, Up: show 13.7.5.37 `SHOW STATUS' Syntax .............................. SHOW [GLOBAL | SESSION] STATUS [LIKE 'PATTERN' | WHERE EXPR] *Note `SHOW STATUS': show-status. provides server status information. This information also can be obtained using the *Note `mysqladmin extended-status': mysqladmin. command. The `LIKE' clause, if present, indicates which variable names to match. The `WHERE' clause can be given to select rows using more general conditions, as discussed in *Note extended-show::. This statement does not require any privilege. It requires only the ability to connect to the server. Partial output is shown here. The list of names and values may be different for your server. The meaning of each variable is given in *Note 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 | +--------------------+----------+ With the `GLOBAL' modifier, *Note `SHOW STATUS': show-status. displays the status values for all connections to MySQL. With `SESSION', it displays the status values for the current connection. If no modifier is present, the default is `SESSION'. `LOCAL' is a synonym for `SESSION'. Some status variables have only a global value. For these, you get the same value for both `GLOBAL' and `SESSION'. The scope for each status variable is listed at *Note server-status-variables::. Each invocation of the *Note `SHOW STATUS': show-status. statement uses an internal temporary table and increments the global `Created_tmp_tables' value.  File: manual.info, Node: show-table-status, Next: show-tables, Prev: show-status, Up: show 13.7.5.38 `SHOW TABLE STATUS' Syntax .................................... SHOW TABLE STATUS [{FROM | IN} DB_NAME] [LIKE 'PATTERN' | WHERE EXPR] *Note `SHOW TABLE STATUS': show-table-status. works likes *Note `SHOW TABLES': show-tables, but provides a lot of information about each non-`TEMPORARY' table. You can also get this list using the *Note `mysqlshow --status DB_NAME': mysqlshow. 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 *Note extended-show::. This statement also displays information about views. *Note `SHOW TABLE STATUS': show-table-status. output has the following columns: * `Name' The name of the table. * `Engine' The storage engine for the table. See *Note 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 *Note `myisamchk -dvv': myisamchk. reports as `Packed'. The format of `InnoDB' tables is reported as `Redundant' or `Compact'. For the `Barracuda' file format of the `InnoDB Plugin', the format may be `Compressed' or `Dynamic'. * `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' The length of the data file. * `Max_data_length' The 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. * `Index_length' The length of the index file. * `Data_free' The number of allocated but unused bytes. Beginning with MySQL 5.1.24, 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 completely free 1MB 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 *Note 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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_system_tablespace) and the data file timestamp does not apply. Even with file-per-table (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_file_per_table) mode with each `InnoDB' table in a separate `.ibd' file, change buffering (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 *Note `CREATE TABLE': create-table. The original options supplied when *Note `CREATE TABLE': 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). Before MySQL 5.1.24, free space for `InnoDB' tables is reported in the comment. As of 5.1.24, it is reported in the `Data_free' column. 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 *Note `NDBCLUSTER': mysql-cluster. tables, the output of this statement shows appropriate values for the `Avg_row_length' and `Data_length' columns, with the exception that *Note `BLOB': blob. columns are not taken into account. Prior to MySQL 5.1.21, the number of MySQL Cluster replicas was shown in the `Comment' column as `number_of_replicas' (Bug #11379). For views, all the fields displayed by *Note `SHOW TABLE STATUS': show-table-status. are `NULL' except that `Name' indicates the view name and `Comment' says `view'.  File: manual.info, Node: show-tables, Next: show-triggers, Prev: show-table-status, Up: show 13.7.5.39 `SHOW TABLES' Syntax .............................. SHOW [FULL] TABLES [{FROM | IN} DB_NAME] [LIKE 'PATTERN' | WHERE EXPR] *Note `SHOW TABLES': show-tables. lists the non-`TEMPORARY' tables in a given database. You can also get this list using the *Note `mysqlshow DB_NAME': mysqlshow. 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 *Note 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 `FULL' modifier is supported such that *Note `SHOW FULL TABLES': show-tables. displays a second output column. Values for the second column are `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 *Note `SHOW TABLES': show-tables. or *Note `mysqlshow db_name': mysqlshow.  File: manual.info, Node: show-triggers, Next: show-variables, Prev: show-tables, Up: show 13.7.5.40 `SHOW TRIGGERS' Syntax ................................ SHOW TRIGGERS [{FROM | IN} DB_NAME] [LIKE 'PATTERN' | WHERE EXPR] *Note `SHOW TRIGGERS': 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, or (prior to MySQL 5.1.23) if you have the `SUPER' 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 *Note extended-show::. For the trigger `ins_sum' as defined in *Note 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: NULL sql_mode: Definer: me@localhost character_set_client: latin1 collation_connection: latin1_swedish_ci Database Collation: latin1_swedish_ci *Note `SHOW TRIGGERS': 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': Currently, the value of this column is always `NULL'. * `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. This column was added in MySQL 5.1.21. * `collation_connection': The session value of the `collation_connection' system variable when the trigger was created. This column was added in MySQL 5.1.21. * `Database Collation': The collation of the database with which the trigger is associated. This column was added in MySQL 5.1.21. You can also obtain information about trigger objects from `INFORMATION_SCHEMA', which contains a *Note `TRIGGERS': triggers-table. table. See *Note triggers-table::.  File: manual.info, Node: show-variables, Next: show-warnings, Prev: show-triggers, Up: show 13.7.5.41 `SHOW VARIABLES' Syntax ................................. SHOW [GLOBAL | SESSION] VARIABLES [LIKE 'PATTERN' | WHERE EXPR] *Note `SHOW VARIABLES': show-variables. shows the values of MySQL system variables. This information also can be obtained using the *Note `mysqladmin variables': mysqladmin. command. The `LIKE' clause, if present, indicates which variable names to match. The `WHERE' clause can be given to select rows using more general conditions, as discussed in *Note extended-show::. This statement does not require any privilege. It requires only the ability to connect to the server. With the `GLOBAL' modifier, *Note `SHOW VARIABLES': show-variables. displays the values that are used for new connections to MySQL. If a variable has no global value, the session value is displayed. With `SESSION', *Note `SHOW VARIABLES': show-variables. displays the values that are in effect for the current connection. If no modifier is present, the default is `SESSION'. `LOCAL' is a synonym for `SESSION'. *Note `SHOW VARIABLES': show-variables. is subject to a version-dependent display-width limit. For variables with very long values that are not completely displayed, use *Note `SELECT': select. as a workaround. For example: SELECT @@GLOBAL.innodb_data_file_path; If the default system variable values are unsuitable, you can set them using command options when *Note `mysqld': mysqld. starts, and most can be changed at runtime with the *Note `SET': set-statement. statement. See *Note using-system-variables::, and *Note set-statement::. Partial output is shown here. The list of names and values may be different for your server. *Note server-system-variables::, describes the meaning of each variable, and *Note server-parameters::, provides information about tuning them. mysql> SHOW VARIABLES; +---------------------------------+---------------------------+ | Variable_name | Value | +---------------------------------+---------------------------+ | auto_increment_increment | 1 | | auto_increment_offset | 1 | | automatic_sp_privileges | ON | | back_log | 50 | | basedir | /home/jon/bin/mysql-5.1/ | | binlog_cache_size | 32768 | | bulk_insert_buffer_size | 8388608 | | character_set_client | latin1 | | character_set_connection | latin1 | ... | max_user_connections | 0 | | max_write_lock_count | 4294967295 | | multi_range_count | 256 | | myisam_data_pointer_size | 6 | | myisam_max_sort_file_size | 2147483647 | | myisam_recover_options | OFF | | myisam_repair_threads | 1 | | myisam_sort_buffer_size | 8388608 | | ndb_autoincrement_prefetch_sz | 32 | | ndb_cache_check_time | 0 | | ndb_force_send | ON | ... | time_zone | SYSTEM | | timed_mutexes | OFF | | tmp_table_size | 33554432 | | tmpdir | | | transaction_alloc_block_size | 8192 | | transaction_prealloc_size | 4096 | | tx_isolation | REPEATABLE-READ | | updatable_views_with_limit | YES | | version | 5.1.6-alpha-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 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.  File: manual.info, Node: show-warnings, Prev: show-variables, Up: show 13.7.5.42 `SHOW WARNINGS' Syntax ................................ SHOW WARNINGS [LIMIT [OFFSET,] ROW_COUNT] SHOW COUNT(*) WARNINGS *Note `SHOW 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 *Note `INSERT': insert, *Note `UPDATE': update, and *Note `LOAD DATA INFILE': load-data. as well as DDL statements such as *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': alter-table. The `LIMIT' clause has the same syntax as for the *Note `SELECT': select. statement. See *Note select::. *Note `SHOW WARNINGS': show-warnings. is also used following *Note `EXPLAIN EXTENDED': explain-extended, to display the extra information generated by *Note `EXPLAIN': explain. when the `EXTENDED' keyword is used. See *Note explain-extended::. *Note `SHOW WARNINGS': show-warnings. displays information about the conditions resulting from the most recent statement in the current session that generated messages. It shows nothing if the most recent statement used a table and generated no messages. (That is, statements that use a table but generate no messages clear the message list.) Statements that do not use tables and do not generate messages have no effect on the message list. The *Note `SHOW COUNT(*) WARNINGS': show-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 related diagnostic statement, *Note `SHOW ERRORS': show-errors, shows only error conditions (it excludes warnings and notes), and *Note `SHOW COUNT(*) ERRORS': show-warnings. statement displays the total number of errors. See *Note show-errors::. Here is a simple example that shows data-conversion warnings for *Note `INSERT': 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 *Note `SHOW WARNINGS': 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 *Note `ALTER TABLE': 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 '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 *Note `mysql_warning_count()': mysql-warning-count. See *Note mysql-warning-count::.  File: manual.info, Node: other-administrative-sql, Prev: show, Up: sql-syntax-server-administration 13.7.6 Other Administrative Statements -------------------------------------- * Menu: * binlog:: `BINLOG' Syntax * cache-index:: `CACHE INDEX' Syntax * flush:: `FLUSH' Syntax * kill:: `KILL' Syntax * load-index:: `LOAD INDEX INTO CACHE' Syntax * reset:: `RESET' Syntax  File: manual.info, Node: binlog, Next: cache-index, Prev: other-administrative-sql, Up: other-administrative-sql 13.7.6.1 `BINLOG' Syntax ........................ BINLOG 'STR' *Note `BINLOG': binlog. is an internal-use statement. It is generated by the *Note `mysqlbinlog': mysqlbinlog. program as the printable representation of certain events in binary log files. (See *Note 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. It was added in MySQL 5.1.5.  File: manual.info, Node: cache-index, Next: flush, Prev: binlog, Up: other-administrative-sql 13.7.6.2 `CACHE INDEX' Syntax ............................. CACHE INDEX TBL_INDEX_LIST [, TBL_INDEX_LIST] ... IN KEY_CACHE_NAME TBL_INDEX_LIST: TBL_NAME [[INDEX|KEY] (INDEX_NAME[, INDEX_NAME] ...)] The *Note `CACHE INDEX': 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 *Note `LOAD INDEX INTO CACHE': load-index. 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 *Note `CACHE INDEX': 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 *Note `CACHE INDEX': 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 *Note 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.  File: manual.info, Node: flush, Next: kill, Prev: cache-index, Up: other-administrative-sql 13.7.6.3 `FLUSH' Syntax ....................... FLUSH [NO_WRITE_TO_BINLOG | LOCAL] FLUSH_OPTION [, FLUSH_OPTION] ... The *Note `FLUSH': flush. statement has several variant forms that clear or reload various internal caches, flush tables, or acquire locks. To execute *Note `FLUSH': flush, you must have the `RELOAD' privilege. By default, the server writes *Note `FLUSH': 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*: *Note `FLUSH LOGS': flush, *Note `FLUSH MASTER': flush, *Note `FLUSH SLAVE': flush, and *Note `FLUSH TABLES WITH READ LOCK': flush. are not written to the binary log in any case because they would cause problems if replicated to a slave. Sending a `SIGHUP' signal to the server causes several flush operations to occur that are similar to various forms of the *Note `FLUSH': flush. statement. See *Note server-signal-response::. The *Note `FLUSH': flush. statement causes an implicit commit. See *Note implicit-commit::. The *Note `RESET': reset. statement is similar to *Note `FLUSH': flush. See *Note reset::, for information about using the *Note `RESET': reset. statement with replication. FLUSH_OPTION can be any of the following items: * `DES_KEY_FILE' Reloads the DES keys from the file that was specified with the `--des-key-file' option at server startup time. * `HOSTS' Empties the host cache. You should flush the host cache if some of your hosts change IP address or if the error message `Host 'HOST_NAME' is blocked' occurs. (See *Note 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 10. To avoid this error message, start the server with `max_connect_errors' set to a large value. * `LOGS' Closes and reopens all log files. If binary logging is enabled, the sequence number of the binary log file is incremented by one relative to the previous file. Prior to MySQL 5.1.51, if you flush the logs using *Note `FLUSH LOGS': flush. and *Note `mysqld': mysqld. is writing the error log to a file (for example, if it was started with the `--log-error' option), log file renaming may occur, as described in *Note error-log::. * `MASTER' Deletes all binary logs, resets the binary log index file and creates a new binary log. *Note `FLUSH MASTER': flush. is deprecated in favor of *Note `RESET MASTER': reset-master. *Note `FLUSH MASTER': flush. is still accepted in MySQL 5.1 for backward compatibility, but is removed in MySQL 5.6. See *Note reset-master::. * `PRIVILEGES' Reloads the privileges from the grant tables in the `mysql' database. The server caches information in memory as a result of *Note `GRANT': grant, *Note `CREATE USER': create-user, *Note `CREATE SERVER': create-server, and *Note `INSTALL PLUGIN': install-plugin. statements. This memory is not released by the corresponding *Note `REVOKE': revoke, *Note `DROP USER': drop-user, *Note `DROP SERVER': drop-server, and *Note `UNINSTALL PLUGIN': 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 *Note `FLUSH PRIVILEGES': flush. * `QUERY CACHE' Defragment the query cache to better utilize its memory. *Note `FLUSH QUERY CACHE': flush. does not remove any queries from the cache, unlike *Note `FLUSH TABLES': flush. or `RESET QUERY CACHE'. * `SLAVE' Resets all replication slave parameters, including relay log files and replication position in the master's binary logs. *Note `FLUSH SLAVE': flush. is deprecated in favor of *Note `RESET SLAVE': reset-slave. *Note `FLUSH SLAVE': flush. is still accepted in MySQL 5.1 for backward compatibility, but is removed in MySQL 5.6. See *Note reset-slave::. * `STATUS' 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 is something you should use only when debugging a query. See *Note bug-reports::. * `TABLES' *Note `FLUSH TABLES': flush. flushes tables, and, depending on the variant used, acquires locks. The permitted syntax is discussed later in this section. * `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. *Note `FLUSH USER_RESOURCES': flush. does not apply to the limit on maximum simultaneous connections. See *Note user-resources::. The *Note `mysqladmin': 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 *Note mysqladmin::. *Note*: It is not possible to issue *Note `FLUSH': flush. statements within stored functions or triggers. However, you may use *Note `FLUSH': flush. in stored procedures, so long as these are not called from stored functions or triggers. See *Note stored-program-restrictions::. * `FLUSH TABLES' Syntax * *Note `FLUSH TABLES': flush. has several forms, described following. *Note `FLUSH TABLE': flush. is a synonym for *Note `FLUSH TABLES': flush, except that `TABLE' does not work with the `WITH READ LOCK' variant. * `FLUSH TABLES' Closes all open tables, forces all tables in use to be closed, and flushes the query cache. *Note `FLUSH TABLES': flush. also removes all query results from the query cache, like the `RESET QUERY CACHE' statement. * `FLUSH TABLES TBL_NAME [, TBL_NAME] ...' With a list of one or more comma-separated table names, this statement is like *Note `FLUSH TABLES': flush. with no names except that the server flushes only the named tables. No error occurs if a named table does not exist. * `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 *Note `UNLOCK TABLES': lock-tables. to release the lock. *Note `FLUSH TABLES WITH READ LOCK': flush. acquires a global read lock and not table locks, so it is not subject to the same behavior as *Note `LOCK TABLES': lock-tables. and *Note `UNLOCK TABLES': lock-tables. with respect to table locking and implicit commits: * *Note `UNLOCK TABLES': lock-tables. implicitly commits any active transaction only if any tables currently have been locked with *Note `LOCK TABLES': lock-tables. The commit does not occur for *Note `UNLOCK TABLES': lock-tables. following *Note `FLUSH TABLES WITH READ LOCK': flush. because the latter statement does not acquire table locks. * Beginning a transaction causes table locks acquired with *Note `LOCK TABLES': lock-tables. to be released, as though you had executed *Note `UNLOCK TABLES': lock-tables. Beginning a transaction does not release a global read lock acquired with *Note `FLUSH TABLES WITH READ LOCK': flush. *Note `FLUSH TABLES WITH READ LOCK': flush. does not prevent the server from inserting rows into the log tables (see *Note log-destinations::).  File: manual.info, Node: kill, Next: load-index, Prev: flush, Up: other-administrative-sql 13.7.6.4 `KILL' Syntax ...................... KILL [CONNECTION | QUERY] THREAD_ID Each connection to *Note `mysqld': mysqld. runs in a separate thread. You can see which threads are running with the *Note `SHOW PROCESSLIST': show-processlist. statement and kill a thread with the `KILL THREAD_ID' statement. *Note `KILL': kill. permits an optional `CONNECTION' or `QUERY' modifier: * *Note `KILL CONNECTION': kill. is the same as *Note `KILL': kill. with no modifier: It terminates the connection associated with the given THREAD_ID. * *Note `KILL QUERY': kill. terminates the statement that 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 *Note `mysqladmin processlist': mysqladmin. and *Note `mysqladmin kill': mysqladmin. commands to examine and kill threads. *Note*: You cannot use *Note `KILL': 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 *Note `KILL': 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: * In *Note `SELECT': select, `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. * During *Note `ALTER TABLE': alter-table, the kill flag is checked before each block of rows are read from the original table. If the kill flag was set, the statement is aborted and the temporary table is deleted. * During *Note `UPDATE': update. or *Note `DELETE': 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. Note that if you are not using transactions, the changes are not rolled back. * `GET_LOCK()' aborts and returns `NULL'. * An *Note `INSERT DELAYED': insert-delayed. thread quickly flushes (inserts) all rows it has in memory and then terminates. * 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 *Note `REPAIR TABLE': repair-table. or *Note `OPTIMIZE TABLE': 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).  File: manual.info, Node: load-index, Next: reset, Prev: kill, Up: other-administrative-sql 13.7.6.5 `LOAD INDEX INTO CACHE' Syntax ....................................... LOAD INDEX INTO CACHE TBL_INDEX_LIST [, TBL_INDEX_LIST] ... TBL_INDEX_LIST: TBL_NAME [[INDEX|KEY] (INDEX_NAME[, INDEX_NAME] ...)] [IGNORE LEAVES] The *Note `LOAD INDEX INTO CACHE': load-index. statement preloads a table index into the key cache to which it has been assigned by an explicit *Note `CACHE INDEX': cache-index. statement, or into the default key cache otherwise. *Note `LOAD INDEX INTO CACHE': load-index. is used only for `MyISAM' tables. It is not supported for tables having user-defined partitioning (see *Note partitioning-limitations::.) The `IGNORE LEAVES' modifier causes only blocks for the nonleaf nodes of the index to be preloaded. 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 *Note `LOAD INDEX INTO CACHE': load-index. 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. *Note `LOAD INDEX INTO CACHE ... IGNORE LEAVES': load-index. fails unless all indexes in a table have the same block size. (Prior to MySQL 5.1.19, it fails even without `IGNORE LEAVES'.) You can determine index block sizes for a table by using *Note `myisamchk -dv': myisamchk. and checking the `Blocksize' column.  File: manual.info, Node: reset, Prev: load-index, Up: other-administrative-sql 13.7.6.6 `RESET' Syntax ....................... RESET RESET_OPTION [, RESET_OPTION] ... The *Note `RESET': reset. statement is used to clear the state of various server operations. You must have the `RELOAD' privilege to execute *Note `RESET': reset. *Note `RESET': reset. acts as a stronger version of the *Note `FLUSH': flush. statement. See *Note flush::. The *Note `RESET': reset. statement causes an implicit commit. See *Note implicit-commit::. RESET_OPTION can be any of the following: * `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. * `QUERY CACHE' Removes all query results from the query cache. * `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.  File: manual.info, Node: sql-syntax-utility, Prev: sql-syntax-server-administration, Up: sql-syntax 13.8 MySQL Utility Statements ============================= * Menu: * describe:: `DESCRIBE' Syntax * explain:: `EXPLAIN' Syntax * help:: `HELP' Syntax * use:: `USE' Syntax  File: manual.info, Node: describe, Next: explain, Prev: sql-syntax-utility, Up: sql-syntax-utility 13.8.1 `DESCRIBE' Syntax ------------------------ The *Note `DESCRIBE': describe. and *Note `EXPLAIN': explain. statements are synonyms, used either to obtain information about table structure or query execution plans. For more information, see *Note show-columns::, and *Note explain::.  File: manual.info, Node: explain, Next: help, Prev: describe, Up: sql-syntax-utility 13.8.2 `EXPLAIN' Syntax ----------------------- {EXPLAIN | DESCRIBE | DESC} TBL_NAME [COL_NAME | WILD] {EXPLAIN | DESCRIBE | DESC} [EXPLAIN_TYPE] SELECT SELECT_OPTIONS EXPLAIN_TYPE: {EXTENDED | PARTITIONS} The *Note `DESCRIBE': describe. and *Note `EXPLAIN': explain. statements are synonyms. In practice, the *Note `DESCRIBE': describe. keyword is more often used to obtain information about table structure, whereas *Note `EXPLAIN': 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 *Note `DESCRIBE': describe. and *Note `EXPLAIN': explain. keywords in accordance with those uses, but the MySQL parser treats them as completely synonymous. * Obtaining Table Structure Information * *Note `DESCRIBE': 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 | | +------------+----------+------+-----+---------+----------------+ *Note `DESCRIBE': describe. is a shortcut for *Note `SHOW COLUMNS': show-columns. These statements also display information for views. The description for *Note `SHOW COLUMNS': show-columns. provides more information about the output columns. See *Note show-columns::. By default, *Note `DESCRIBE': 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 *Note `DESCRIBE': describe. statement is provided for compatibility with Oracle. The *Note `SHOW CREATE TABLE': show-create-table, *Note `SHOW TABLE STATUS': show-table-status, and *Note `SHOW INDEX': show-index. statements also provide information about tables. See *Note show::. * Obtaining Execution Plan Information * The *Note `EXPLAIN': explain. statement provides information about how MySQL executes statements: * When you precede a *Note `SELECT': select. statement with the keyword *Note `EXPLAIN': explain, 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 *Note `EXPLAIN': explain. to obtain execution plan information, see *Note explain-output::. * *Note `EXPLAIN EXTENDED': explain-extended. can be used to obtain additional execution plan information. See *Note explain-extended::. * As of MySQL 5.1.5, *Note `EXPLAIN PARTITIONS': explain. is useful for examining queries involving partitioned tables. See *Note partitioning-info::. With the help of *Note `EXPLAIN': 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 *Note `EXPLAIN': 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 *Note `SELECT': select. statement, begin the statement with `SELECT STRAIGHT_JOIN' rather than just *Note `SELECT': select. (See *Note select::.) If you have a problem with indexes not being used when you believe that they should be, run *Note `ANALYZE TABLE': analyze-table. to update table statistics, such as cardinality of keys, that can affect the choices the optimizer makes. See *Note analyze-table::.  File: manual.info, Node: help, Next: use, Prev: explain, Up: sql-syntax-utility 13.8.3 `HELP' Syntax -------------------- HELP 'SEARCH_STRING' The *Note `HELP': 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 *Note server-side-help-support::). The *Note `HELP': 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 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 *Note `CREATE TABLE': 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 *Note `HELP': 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 *Note `mysql': mysql. client, but note that *Note `mysql': mysql. itself reformats *Note `HELP': 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 *Note `HELP': 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 INNODB STATUS | 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 *Note `HELP': 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 | +----------------------+-------------------------+----------------+ Before MySQL 5.1.17, if you intend to use the *Note `HELP': help. statement while other tables are locked with *Note `LOCK TABLES': lock-tables, you must also lock the required `mysql.help_XXX' tables. See *Note lock-tables::.  File: manual.info, Node: use, Prev: help, Up: sql-syntax-utility 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 *Note `USE': 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 *Note `USE': 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;  File: manual.info, Node: storage-engines, Next: ha-overview, Prev: sql-syntax, Up: Top 14 Storage Engines ****************** * Menu: * storage-engine-compare-transactions:: Comparing Transaction and Nontransaction Engines * storage-engines-other:: Other Storage Engines * storage-engine-setting:: Setting the Storage Engine * pluggable-storage-overview:: Overview of MySQL Storage Engine Architecture * myisam-storage-engine:: The `MyISAM' Storage Engine * innodb-storage-engine:: The `InnoDB' Storage Engine * se-db2:: The `IBMDB2I' Storage Engine * merge-storage-engine:: The `MERGE' Storage Engine * memory-storage-engine:: The `MEMORY' Storage Engine * example-storage-engine:: The `EXAMPLE' Storage Engine * federated-storage-engine:: The `FEDERATED' Storage Engine * archive-storage-engine:: The `ARCHIVE' Storage Engine * csv-storage-engine:: The `CSV' Storage Engine * blackhole-storage-engine:: The `BLACKHOLE' Storage Engine MySQL supports several storage engines that act as handlers for different table types. MySQL storage engines include both those that handle transaction-safe tables and those that handle nontransaction-safe tables. As of MySQL 5.1, MySQL Server uses a pluggable storage engine architecture that enables storage engines to be loaded into and unloaded from a running MySQL server. *Note*: Prior to MySQL 5.1.38, the pluggable storage engine architecture is supported on Unix platforms only and pluggable storage engines are not supported on Windows. To determine which storage engines your server supports by using the *Note `SHOW ENGINES': 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: FEDERATED Support: NO Comment: Federated MySQL storage engine Transactions: NULL XA: NULL Savepoints: NULL *************************** 2. row *************************** Engine: MRG_MYISAM Support: YES Comment: Collection of identical MyISAM tables Transactions: NO XA: NO Savepoints: NO *************************** 3. row *************************** Engine: MyISAM Support: DEFAULT Comment: Default engine as of MySQL 3.23 with great performance Transactions: NO XA: NO Savepoints: NO ... This chapter describes each of the MySQL storage engines except for *Note `NDBCLUSTER': mysql-cluster, which is covered in *Note mysql-cluster::. It also contains a description of the pluggable storage engine architecture (see *Note pluggable-storage-overview::). For information about storage engine support offered in commercial MySQL Server binaries, see `MySQL Enterprise Server 5.1' (http://www.mysql.com/products/enterprise/server.html), on the MySQL Web site. The storage engines available might depend on which edition of Enterprise Server you are using. For answers to some commonly asked questions about MySQL storage engines, see *Note faqs-storage-engines::. *MySQL 5.1 supported storage engines* * *Note `MyISAM': myisam-storage-engine.: The default MySQL storage engine and the one that is used the most in Web, data warehousing, and other application environments. `MyISAM' is supported in all MySQL configurations, and is the default storage engine unless you have configured MySQL to use a different one by default. * *Note `InnoDB': innodb-storage-engine.: 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. * *Note `Memory': memory-storage-engine.: Stores all data in RAM for extremely fast access in environments that require quick lookups of reference and other like data. This engine was formerly known as the `HEAP' engine. * *Note `Merge': merge-storage-engine.: 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. * *Note `Archive': archive-storage-engine.: Provides the perfect solution for storing and retrieving large amounts of seldom-referenced historical, archived, or security audit information. * *Note `Federated': federated-storage-engine.: 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. * *Note `NDB': mysql-cluster. (also known as *Note `NDBCLUSTER': mysql-cluster.)--This clustered database engine is particularly suited for applications that require the highest possible degree of uptime and availability. *Note*: The *Note `NDB': mysql-cluster. storage engine is not supported in standard MySQL 5.1 releases. Currently supported MySQL Cluster releases include MySQL Cluster NDB 7.0 and MySQL Cluster NDB 7.1, which are based on MySQL 5.1, and MySQL Cluster NDB 7.2, which is based on MySQL 5.5. While based on MySQL Server, these releases also contain support for *Note `NDB': mysql-cluster. * *Note `CSV': csv-storage-engine.: The CSV storage engine stores data in text files using comma-separated values format. You can use the CSV engine to easily exchange data between other software and applications that can import and export in CSV format. * *Note `Blackhole': blackhole-storage-engine.: The Blackhole storage engine accepts but does not store data and retrievals always return an empty set. The functionality can be used in distributed database design where data is automatically replicated, but not stored locally. * *Note `Example': example-storage-engine.: The Example storage engine is `stub' engine that does nothing. You can create tables with this engine, but no data can be stored in them or retrieved from them. The purpose of this engine 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. It is important to remember that you are not restricted to using the same storage engine for an entire server or schema: you can use a different storage engine for each table in your schema. *Choosing a Storage Engine* The various storage engines provided with MySQL are designed with different use cases in mind. To use the pluggable storage architecture effectively, it is good to have an idea of the advantages and disadvantages of the various storage engines. The following table provides an overview of some storage engines provided with MySQL: *Storage Engine Features* Feature MyISAM Memory InnoDB Archive NDB Storage 256TB RAM 64TB None 384EB limits TransactionsNo No Yes No Yes Locking Table Table Row Table Row granularity MVCC No No Yes No No GeospatialYes No Yes Yes Yes data type support GeospatialYes No No No No indexing support B-tree Yes Yes Yes No No indexes T-tree No No No No Yes indexes Hash No Yes No InnoDB No Yes indexes utilizes hash indexes internally for its Adaptive Hash Index feature. Full-textYes No Yes InnoDB No No search support for indexes FULLTEXT indexes is available in MySQL 5.6.4 and higher. ClusteredNo No Yes No No indexes Data No N/A Yes No Yes caches Index Yes N/A Yes No Yes caches CompressedYes No Yes Yes No data Compressed Compressed MyISAM InnoDB tables are tables supported require the only when InnoDB using the Barracuda compressed file format. row format. Tables using the compressed row format with MyISAM are read only. EncryptedYes Yes Yes Yes Yes data Implemented in the server (via encryption functions), rather than in the storage engine. Cluster No No No No Yes database support ReplicationYes Yes Yes Yes Yes support Implemented in the server, rather than in the storage engine. Foreign No No Yes No No key support Backup Yes Yes Yes Yes Yes / point-in-time recovery Implemented in the server, rather than in the storage engine. Query Yes Yes Yes Yes Yes cache support Update Yes Yes Yes Yes Yes statistics for data dictionary  File: manual.info, Node: storage-engine-compare-transactions, Next: storage-engines-other, Prev: storage-engines, Up: storage-engines 14.1 Comparing Transaction and Nontransaction Engines ===================================================== Transaction-safe tables (TSTs) have several advantages over nontransaction-safe tables (NTSTs): * They are safer. Even if MySQL crashes or you get hardware problems, you can get your data back, either by automatic recovery or from a backup plus the transaction log. * You can combine many statements and accept them all at the same time with the *Note `COMMIT': commit. statement (if autocommit is disabled). * You can execute *Note `ROLLBACK': commit. to ignore your changes (if autocommit is disabled). * If an update fails, all of your changes are reverted. (With nontransaction-safe tables, all changes that have taken place are permanent.) * Transaction-safe storage engines can provide better concurrency for tables that get many updates concurrently with reads. You can combine transaction-safe and nontransaction-safe tables in the same statements to get the best of both worlds. However, although MySQL supports several transaction-safe storage engines, for best results, you should not mix different storage engines within a transaction with autocommit disabled. For example, if you do this, changes to nontransaction-safe tables still are committed immediately and cannot be rolled back. For information about this and other problems that can occur in transactions that use mixed storage engines, see *Note commit::. Nontransaction-safe tables have several advantages of their own, all of which occur because there is no transaction overhead: * Much faster * Lower disk space requirements * Less memory required to perform updates  File: manual.info, Node: storage-engines-other, Next: storage-engine-setting, Prev: storage-engine-compare-transactions, Up: storage-engines 14.2 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).  File: manual.info, Node: storage-engine-setting, Next: pluggable-storage-overview, Prev: storage-engines-other, Up: storage-engines 14.3 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 *Note `CREATE TABLE': create-table. statement: CREATE TABLE t (i INT) ENGINE = INNODB; If you omit the `ENGINE' option, the default storage engine is used. Normally, this is `MyISAM', but you can change it 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 to be used during the current session by setting the `storage_engine' variable: SET storage_engine=MYISAM; When MySQL is installed on Windows using the MySQL Configuration Wizard, the `InnoDB' or `MyISAM' storage engine can be selected as the default. See *Note mysql-config-wizard-database-usage::. To convert a table from one storage engine to another, use an *Note `ALTER TABLE': alter-table. statement that indicates the new engine: ALTER TABLE t ENGINE = MYISAM; See *Note create-table::, and *Note 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. This behavior is convenient when you want to copy tables between MySQL servers that support different storage engines. (For example, in a replication setup, perhaps your master server supports transactional storage engines for increased safety, but the slave servers use only nontransactional storage engines for greater speed.) This automatic substitution of the default storage engine for unavailable engines can be confusing for new MySQL users. A warning is generated whenever a storage engine is automatically changed. To prevent this from happening if the desired engine is unavailable, enable the `NO_ENGINE_SUBSTITUTION' SQL mode. In this case, an error occurs instead of a warning and the table is not created or altered if the desired engine is unavailable. See *Note server-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 *Note identifier-mapping::. A database may contain tables of different types. That is, tables need not all be created with the same storage engine.  File: manual.info, Node: pluggable-storage-overview, Next: myisam-storage-engine, Prev: storage-engine-setting, Up: storage-engines 14.4 Overview of MySQL Storage Engine Architecture ================================================== * Menu: * pluggable-storage:: Pluggable Storage Engine Architecture * pluggable-storage-common-layer:: The Common Database Server Layer 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.  File: manual.info, Node: pluggable-storage, Next: pluggable-storage-common-layer, Prev: pluggable-storage-overview, Up: pluggable-storage-overview 14.4.1 Pluggable Storage Engine Architecture -------------------------------------------- As of MySQL 5.1, MySQL Server uses a pluggable storage engine architecture that enables storage engines to be loaded into and unloaded from a running MySQL server. *Note*: Prior to MySQL 5.1.38, the pluggable storage engine architecture is supported on Unix platforms only and pluggable storage engines are not supported on Windows. *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 *Note `INSTALL PLUGIN': 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: mysql> 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 *Note `INSTALL PLUGIN': 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 *Note `UNINSTALL PLUGIN': uninstall-plugin. statement: mysql> 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.  File: manual.info, Node: pluggable-storage-common-layer, Prev: pluggable-storage, Up: pluggable-storage-overview 14.4.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.  File: manual.info, Node: myisam-storage-engine, Next: innodb-storage-engine, Prev: pluggable-storage-overview, Up: storage-engines 14.5 The `MyISAM' Storage Engine ================================ * Menu: * myisam-start:: `MyISAM' Startup Options * key-space:: Space Needed for Keys * myisam-table-formats:: `MyISAM' Table Storage Formats * myisam-table-problems:: `MyISAM' Table Problems `MyISAM' is the default storage engine. It is based on the older (and no longer available) `ISAM' storage engine but has many useful extensions. *`MyISAM' Storage Engine Features* *Storage limits* 256TB *Transactions* No *Locking Table granularity* *MVCC* No *Geospatial Yes *Geospatial Yes data type indexing support* support* *B-tree indexes* Yes *T-tree indexes* No *Hash indexes* No *Full-text Yes *Clustered No *Data caches* No search indexes* indexes* *Index caches* Yes *Compressed Yes *Encrypted data Yes data* CompressedImplemented in MyISAM the server (via tables encryption are functions), supportedrather than in only the storage when engine.* using the compressed row format. Tables using the compressed row format with MyISAM are read only. *Cluster No *Replication Yes *Foreign key No database support support* support* Implemented in the server, rather than in the storage engine.* *Backup / Yes *Query cache Yes *Update Yes point-in-time support* statistics for recovery data dictionary* Implemented in the server, rather than in the storage engine.* 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; Normally, it is unnecessary to use `ENGINE' to specify the `MyISAM' storage engine. `MyISAM' is the default engine unless the default has been changed. To ensure that `MyISAM' is used in situations where the default might have been changed, include the `ENGINE' option explicitly. You can check or repair `MyISAM' tables with the *Note `mysqlcheck': mysqlcheck. client or *Note `myisamchk': myisamchk. utility. You can also compress `MyISAM' tables with *Note `myisampack': myisampack. to take up much less space. See *Note mysqlcheck::, *Note myisamchk::, and *Note 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 (~4.295E+09) rows in a `MyISAM' table. If you build MySQL with the `--with-big-tables' option, the row limitation is increased to (2^32)^2 (1.844E+19) rows. See *Note source-configuration-options::. Binary distributions for Unix and Linux are built with this option. * The maximum number of indexes per `MyISAM' table is 64. This can be changed by recompiling. Beginning with MySQL 5.1.4, you can configure the build by invoking `configure' with the `--with-max-indexes=N' option, where N is the maximum number of indexes to permit per `MyISAM' table. N must be less than or equal to 128. Before MySQL 5.1.4, you must change the source. 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 *Note `INSERT': insert. and *Note `UPDATE': 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 *Note `ALTER TABLE': alter-table. or *Note `myisamchk': 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 *Note `INSERT': 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 *Note 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 *Note `CREATE TABLE': create-table. See *Note create-table::. * *Note `BLOB': blob. and *Note `TEXT': blob. 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 *Note charset::. * There is a flag in the `MyISAM' index file that indicates whether the table was closed correctly. If *Note `mysqld': mysqld. is started with the `--myisam-recover' option, `MyISAM' tables are automatically checked when opened, and are repaired if the table wasn't closed properly. * *Note `myisamchk': myisamchk. marks tables as checked if you run it with the `--update-state' option. *Note `myisamchk --fast': myisamchk. checks only those tables that don't have this mark. * *Note `myisamchk --analyze': myisamchk. stores statistics for portions of keys, as well as for entire keys. * *Note `myisampack': myisampack. can pack *Note `BLOB': blob. and *Note `VARCHAR': char. columns. `MyISAM' also supports the following features: * Support for a true *Note `VARCHAR': char. type; a *Note `VARCHAR': char. column starts with a length stored in one or two bytes. * Tables with *Note `VARCHAR': char. columns may have fixed or dynamic row length. * The sum of the lengths of the *Note `VARCHAR': char. and *Note `CHAR': 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'.  File: manual.info, Node: myisam-start, Next: key-space, Prev: myisam-storage-engine, Up: myisam-storage-engine 14.5.1 `MyISAM' Startup Options ------------------------------- The following options to *Note `mysqld': mysqld. can be used to change the behavior of `MyISAM' tables. For additional information, see *Note server-options::. *MyISAM Option/Variable Reference* Name Cmd-Line Option file System Var Status Var Var Scope Dynamic bulk_insert_buffer_sizeYes Yes Yes Both Yes concurrent_insertYes Yes Yes Global Yes delay-key-writeYes Yes Global Yes - _Variable_: Yes Global Yes 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_sizeYes Yes Yes Global Yes myisam_max_sort_file_sizeYes Yes Yes Global Yes myisam_mmap_sizeYes Yes Yes Global No myisam-recover Yes 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=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 *Note `myisamchk': 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 *Note 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 *Note `REPAIR TABLE': repair-table, *Note `ALTER TABLE': alter-table, or *Note `LOAD DATA INFILE': load-data.). 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 *Note `mysqld': mysqld. with the `--myisam-recover' 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' 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 Note that 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.  File: manual.info, Node: key-space, Next: myisam-table-formats, Prev: myisam-start, Up: myisam-storage-engine 14.5.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 *Note `VARCHAR': char. 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.  File: manual.info, Node: myisam-table-formats, Next: myisam-table-problems, Prev: key-space, Up: myisam-storage-engine 14.5.3 `MyISAM' Table Storage Formats ------------------------------------- * Menu: * static-format:: Static (Fixed-Length) Table Characteristics * dynamic-format:: Dynamic Table Characteristics * compressed-format:: Compressed Table Characteristics `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 *Note `myisampack': myisampack. utility (see *Note myisampack::). When you use *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. for a table that has no *Note `BLOB': blob. or *Note `TEXT': blob. columns, you can force the table format to `FIXED' or `DYNAMIC' with the `ROW_FORMAT' table option. See *Note create-table::, for information about `ROW_FORMAT'. You can decompress (unpack) compressed `MyISAM' tables using *Note `myisamchk `--unpack'': myisamchk.; see *Note myisamchk::, for more information.  File: manual.info, Node: static-format, Next: dynamic-format, Prev: myisam-table-formats, Up: myisam-table-formats 14.5.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 (*Note `VARCHAR': char, *Note `VARBINARY': binary-varbinary, *Note `BLOB': blob, or *Note `TEXT': blob.). 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, *Note `myisamchk': myisamchk. can easily determine where each row starts and ends, so it can usually reclaim all rows except the partially written one. Note that `MyISAM' table indexes can always be reconstructed based on the data rows. *Note*: Fixed-length row format is only available for tables without *Note `BLOB': blob. or *Note `TEXT': blob. 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: * *Note `CHAR': char. and *Note `VARCHAR': char. columns are space-padded to the specified column width, although the column type is not altered. *Note `BINARY': binary-varbinary. and *Note `VARBINARY': binary-varbinary. columns are padded with `0x00' bytes to the column width. * 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 *Note `OPTIMIZE TABLE': optimize-table. or *Note `myisamchk -r': myisamchk. * Usually require more disk space than dynamic-format tables.  File: manual.info, Node: dynamic-format, Next: compressed-format, Prev: static-format, Up: myisam-table-formats 14.5.3.2 Dynamic Table Characteristics ...................................... Dynamic storage format is used if a `MyISAM' table contains any variable-length columns (*Note `VARCHAR': char, *Note `VARBINARY': binary-varbinary, *Note `BLOB': blob, or *Note `TEXT': blob.), 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 *Note `OPTIMIZE TABLE': optimize-table. or *Note `myisamchk -r': myisamchk. 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). Note that 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. * 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 *Note `OPTIMIZE TABLE': optimize-table. or *Note `myisamchk -r': myisamchk. from time to time to improve performance. Use *Note `myisamchk -ei': myisamchk. 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 *Note `myisamchk -ed': myisamchk. All links may be removed with *Note `OPTIMIZE TABLE': optimize-table. or *Note `myisamchk -r': myisamchk.  File: manual.info, Node: compressed-format, Prev: dynamic-format, Up: myisam-table-formats 14.5.3.3 Compressed Table Characteristics ......................................... Compressed storage format is a read-only format that is generated with the *Note `myisampack': myisampack. tool. Compressed tables can be uncompressed with *Note `myisamchk': 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 *Note `BIGINT': integer-types. column (eight bytes) can be stored as a *Note `TINYINT': integer-types. 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 *Note `ENUM': 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 *Note `TRUNCATE TABLE': truncate-table. to empty the table.  File: manual.info, Node: myisam-table-problems, Prev: myisam-table-formats, Up: myisam-storage-engine 14.5.4 `MyISAM' Table Problems ------------------------------ * Menu: * corrupted-myisam-tables:: Corrupted `MyISAM' Tables * myisam-table-close:: Problems from Tables Not Being Closed Properly 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.  File: manual.info, Node: corrupted-myisam-tables, Next: myisam-table-close, Prev: myisam-table-problems, Up: myisam-table-problems 14.5.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 *Note `mysqld': 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 *Note `myisamchk': 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 *Note `CHECK TABLE': check-table. statement, and repair a corrupted `MyISAM' table with *Note `REPAIR TABLE': repair-table. When *Note `mysqld': mysqld. is not running, you can also check or repair a table with the *Note `myisamchk': myisamchk. command. See *Note check-table::, *Note repair-table::, and *Note 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 *Note crashing::, and *Note porting::.  File: manual.info, Node: myisam-table-close, Prev: corrupted-myisam-tables, Up: myisam-table-problems 14.5.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 *Note `CHECK TABLE': check-table. or *Note `myisamchk': 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 *Note `FLUSH TABLES': flush. 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 *Note `LOCK TABLES': lock-tables. and *Note `FLUSH TABLES': flush. * MySQL has crashed between an update and the final close. (Note that the table may still be okay, because MySQL always issues writes for everything between each statement.) * A table was modified by *Note `myisamchk --recover': myisamchk. or *Note `myisamchk --update-state': myisamchk. at the same time that it was in use by *Note `mysqld': mysqld. * Multiple *Note `mysqld': mysqld. servers are using the table and one server performed a *Note `REPAIR TABLE': repair-table. or *Note `CHECK TABLE': check-table. on the table while it was in use by another server. In this setup, it is safe to use *Note `CHECK TABLE': check-table, although you might get the warning from other servers. However, *Note `REPAIR TABLE': 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 *Note multiple-servers::, for additional discussion.  File: manual.info, Node: innodb-storage-engine, Next: se-db2, Prev: myisam-storage-engine, Up: storage-engines 14.6 The `InnoDB' Storage Engine ================================ * Menu: * innodb-configuration:: Configuring `InnoDB' * innodb-parameters:: `InnoDB' Startup Options and System Variables * using-innodb-tables:: Creating and Using `InnoDB' Tables * innodb-data-log-reconfiguration:: Adding, Removing, or Resizing `InnoDB' Data and Log Files * innodb-backup:: Backing Up and Recovering an `InnoDB' Database * innodb-migration:: Moving or Copying `InnoDB' Tables to Another Machine * innodb-transaction-model:: The `InnoDB' Transaction Model and Locking * innodb-multi-versioning:: `InnoDB' Multi-Versioning * innodb-table-and-index:: `InnoDB' Table and Index Structures * innodb-disk-management:: `InnoDB' Disk I/O and File Space Management * innodb-error-handling:: `InnoDB' Error Handling * innodb-tuning-troubleshooting:: `InnoDB' Performance Tuning and Troubleshooting * innodb-restrictions:: Limits on `InnoDB' Tables `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. You can freely mix `InnoDB' tables with tables from other MySQL storage engines, even within the same statement. To determine whether your server supports `InnoDB' use the *Note `SHOW ENGINES': show-engines. statement. See *Note show-engines::. *`InnoDB' Storage Engine Features* *Storage limits* 64TB *Transactions* Yes *Locking Row granularity* *MVCC* Yes *Geospatial Yes *Geospatial No data type indexing support* support* *B-tree indexes* Yes *T-tree indexes* No *Hash indexes* No InnoDB utilizes hash indexes internally for its Adaptive Hash Index feature. *Full-text Yes *Clustered Yes *Data caches* Yes search indexes* InnoDB indexes* support for FULLTEXT indexes is available in MySQL 5.6.4 and higher. *Index caches* Yes *Compressed Yes *Encrypted data Yes data* CompressedImplemented in InnoDB the server (via tables encryption require functions), the rather than in InnoDB the storage Barracudaengine.* file format. *Cluster No *Replication Yes *Foreign key Yes database support support* support* Implemented in the server, rather than in the storage engine.* *Backup / Yes *Query cache Yes *Update Yes point-in-time support* statistics for recovery data dictionary* Implemented in the server, rather than in the storage engine.* `InnoDB' has been designed for maximum performance when processing large data volumes. Its CPU efficiency is probably not matched by any other disk-based relational database engine. The `InnoDB' storage engine maintains its own buffer pool for caching data and indexes in main memory. `InnoDB' stores its tables and indexes in a tablespace, which may consist of several files (or raw disk partitions). This is different from, for example, `MyISAM' tables where each table is stored using separate files. `InnoDB' tables can be very large even on operating systems where file size is limited to 2GB. The Windows Essentials installer makes `InnoDB' the MySQL default storage engine on Windows, if the server being installed supports `InnoDB'. `InnoDB' is used in production at numerous large database sites requiring high performance. The famous Internet news site Slashdot.org runs on `InnoDB'. Mytrix, Inc. stores more than 1TB of data in `InnoDB', and another site handles an average load of 800 inserts/updates per second in `InnoDB'. `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/. * Additional Resources * * A forum dedicated to the `InnoDB' storage engine is available at `http://forums.mysql.com/list.php?22'. * At the 2008 MySQL User Conference, Innobase announced availability of an `InnoDB' Plugin for MySQL. This plugin for MySQL exploits the `pluggable storage engine' architecture of MySQL, to permit users to replace the `built-in' version of `InnoDB' in MySQL 5.1. As of MySQL 5.1.38, the `InnoDB Plugin' is included in MySQL 5.1 releases, in addition to the built-in version of `InnoDB' that has been included in previous releases. MySQL 5.1.42 through 5.1.45 include `InnoDB Plugin' 1.0.6, which is considered of Release Candidate (RC) quality. MySQL 5.1.46 and up include `InnoDB Plugin' 1.0.7 or higher, which is considered of General Availability (GA) quality. Prior to MySQL Cluster NDB 7.1.11, MySQL Cluster was not compatible with the `InnoDB Plugin'. The `InnoDB Plugin' offers new features, improved performance and scalability, enhanced reliability and new capabilities for flexibility and ease of use. Among the features of the `InnoDB Plugin' are `Fast index creation,' table and index compression, file format management, new `INFORMATION_SCHEMA' tables, capacity tuning, multiple background I/O threads, and group commit. For information about these features, see InnoDB Plugin 1.0 for MySQL 5.1 User's Guide (http://dev.mysql.com/doc/innodb-plugin/1.0/en/index.html). The `InnoDB Plugin' is included in source and binary distributions, except RHEL3, RHEL4, SuSE 9 (x86, x86_64, ia64), and generic Linux RPM packages. For instructions on replacing the built-in version of `InnoDB' with `InnoDB Plugin', see *Note replacing-builtin-innodb::. * The MySQL Enterprise Backup product lets you back up a running MySQL database, including `InnoDB' and `MyISAM' tables, with minimal disruption to operations while producing a consistent snapshot of the database. When MySQL Enterprise Backup is copying `InnoDB' tables, reads and writes to both `InnoDB' and `MyISAM' tables can continue. During the copying of `MyISAM' and other non-InnoDB tables, reads (but not writes) to those tables are permitted. In addition, MySQL Enterprise Backup can create compressed backup files, and back up subsets of `InnoDB' 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 a more complete description of MySQL Enterprise Backup, see MySQL Enterprise Backup User's Guide (Version 3.8.2) (http://dev.mysql.com/doc/mysql-enterprise-backup/3.8/en/index.html).  File: manual.info, Node: innodb-configuration, Next: innodb-parameters, Prev: innodb-storage-engine, Up: innodb-storage-engine 14.6.1 Configuring `InnoDB' --------------------------- * Menu: * replacing-builtin-innodb:: Using `InnoDB Plugin' Instead of the Built-In `InnoDB' * innodb-multiple-tablespaces:: Using Per-Table Tablespaces * innodb-raw-devices:: Using Raw Disk Partitions for the Shared Tablespace * innodb-init:: Creating the `InnoDB' Tablespace * error-creating-innodb:: Dealing with `InnoDB' Initialization Problems The first decisions to make about InnoDB configuration involve how to lay out InnoDB data files, and how much memory to allocate for the InnoDB storage engine. You record these choices either by recording them in a configuration file that MySQL reads at startup, or by specifying them as command-line options in a startup script. The full list of options, descriptions, and allowed parameter values is at *Note innodb-parameters::. * Overview of InnoDB Tablespace and Log Files * Two important disk-based resources managed by the `InnoDB' storage engine are its tablespace data files and its log files. If you specify no `InnoDB' configuration options, MySQL creates an auto-extending data file, slightly larger than 10MB, named `ibdata1' and two log files named `ib_logfile0' and `ib_logfile1' in the MySQL data directory. Their size is given by the size of the `innodb_log_file_size' system variable. To get good performance, explicitly provide `InnoDB' parameters as discussed in the following examples. Naturally, edit the settings to suit your hardware and requirements. The examples shown here are representative. See *Note innodb-parameters:: for additional information about `InnoDB'-related configuration parameters. * Considerations for Storage Devices * 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. The example illustrates how to do this. It places the two data files on different disks and places the log files on the third disk. `InnoDB' fills the tablespace beginning with the first data file. You can also use raw disk partitions (raw devices) as `InnoDB' data files, which may speed up I/O. See *Note innodb-raw-devices::. *Caution*: `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 Mac OS X 10.3 and up, `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.* *Caution*: If reliability is a consideration for your data, do not configure `InnoDB' to use data files or log files on NFS volumes. Potential problems vary according to OS and version of NFS, and include such issues as lack of protection from conflicting writes, and limitations on maximum file sizes. * Specifying the Location and Size for InnoDB Tablespace Files * To set up the `InnoDB' tablespace files, use the `innodb_data_file_path' option in the `[mysqld]' section of the `my.cnf' option file. On Windows, you can use `my.ini' instead. The value of `innodb_data_file_path' should be a list of one or more data file specifications. If you name more than one data file, separate them by semicolon (``;'') characters: innodb_data_file_path=DATAFILE_SPEC1[;DATAFILE_SPEC2]... For example, the following setting explicitly creates a tablespace having the same characteristics as the default: [mysqld] innodb_data_file_path=ibdata1:10M:autoextend This setting configures a single 10MB 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. Sizes are specified using `K', `M', or `G' suffix letters to indicate units of KB, MB, or GB. A tablespace containing a fixed-size 50MB data file named `ibdata1' and a 50MB auto-extending file named `ibdata2' in the data directory 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, its size, and several optional attributes: FILE_NAME:FILE_SIZE[:autoextend[:max:MAX_FILE_SIZE]] The `autoextend' and `max' attributes can be used only for the last data file in the `innodb_data_file_path' line. 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 increment is 8MB 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 tablespace reconfiguration instructions, see *Note innodb-data-log-reconfiguration::. `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 including a crash. The following configuration permits `ibdata1' to grow up to a limit of 500MB: [mysqld] innodb_data_file_path=ibdata1:10M:autoextend:max:500M `InnoDB' creates tablespace files in the MySQL data directory by default. To specify a location explicitly, use the `innodb_data_home_dir' option. For example, to use two files named `ibdata1' and `ibdata2' but create them in the `/ibdata' directory, configure `InnoDB' like this: [mysqld] innodb_data_home_dir = /ibdata innodb_data_file_path=ibdata1:50M;ibdata2:50M:autoextend *Note*: `InnoDB' does not create directories, so make sure that the `/ibdata' directory exists before you start the server. This is also true of any log file directories that you configure. 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 data directory. More generally, the server must have access rights in any directory where it needs to create data files or log 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, adding a path name separator (slash or backslash) between values if necessary. If the `innodb_data_home_dir' option is not specified in `my.cnf' at all, 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 the 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=/ibdata/ibdata1:50M;/ibdata/ibdata2:50M:autoextend * Specifying InnoDB Configuration Options * *Sample `my.cnf' file for small systems.* Suppose that you have a computer with 512MB RAM and one hard disk. The following example shows possible configuration parameters in `my.cnf' or `my.ini' for `InnoDB', including the `autoextend' attribute. The example suits most users, both on Unix and Windows, who do not want to distribute `InnoDB' data files and log files onto several disks. It creates an auto-extending data file `ibdata1' and two `InnoDB' log files `ib_logfile0' and `ib_logfile1' in the MySQL data directory. [mysqld] # You can write your other MySQL server options here # ... # Data files must be able to hold your data and indexes. # Make sure that you have enough free disk space. innodb_data_file_path = ibdata1:10M:autoextend # # Set buffer pool size to 50-80% of your computer's memory innodb_buffer_pool_size=256M innodb_additional_mem_pool_size=20M # # Set the log file size to about 25% of the buffer pool size innodb_log_file_size=64M innodb_log_buffer_size=8M # innodb_flush_log_at_trx_commit=1 Note that data files must be less than 2GB in some file systems. The combined size of the log files must be less than 4GB. The combined size of data files must be at least slightly larger than 10MB. * Setting Up the InnoDB System Tablespace * When you create an `InnoDB' system tablespace for the first time, it is best that you start the MySQL server from the command prompt. `InnoDB' then prints the information about the database creation to the screen, so you can see what is happening. For example, on Windows, if *Note `mysqld': mysqld. is located in `C:\Program Files\MySQL\MySQL Server 5.1\bin', you can start it like this: C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqld" --console If you do not send server output to the screen, check the server's error log to see what `InnoDB' prints during the startup process. For an example of what the information displayed by `InnoDB' should look like, see *Note innodb-init::. * Editing the MySQL Configuration File * You can place `InnoDB' options in the `[mysqld]' group of any option file that your server reads when it starts. The locations for option files are described in *Note option-files::. If you installed MySQL on Windows using the installation and configuration wizards, the option file will be the `my.ini' file located in your MySQL installation directory. See *Note mysql-config-wizard-starting::. If your PC uses a boot loader where the `C:' drive is not the boot drive, your only option is to use the `my.ini' file in your Windows directory (typically `C:\WINDOWS'). You can use the `SET' command at the command prompt in a console window to print the value of `WINDIR': C:\> SET WINDIR windir=C:\WINDOWS To make sure that *Note `mysqld': 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=YOUR_PATH_TO_MY_CNF *Sample `my.cnf' file for large systems.* Suppose that you have a Linux computer with 2GB RAM and three 60GB hard disks at directory paths `/', `/dr2' and `/dr3'. The following example shows possible configuration parameters in `my.cnf' for `InnoDB'. [mysqld] # You can write your other MySQL server options here # ... innodb_data_home_dir = # # Data files must be able to hold your data and indexes innodb_data_file_path = /db/ibdata1:2000M;/dr2/db/ibdata2:2000M:autoextend # # Set buffer pool size to 50-80% of your computer's memory, # but make sure on Linux x86 total memory usage is < 2GB innodb_buffer_pool_size=1G innodb_additional_mem_pool_size=20M innodb_log_group_home_dir = /dr3/iblogs # # Set the log file size to about 25% of the buffer pool size innodb_log_file_size=250M innodb_log_buffer_size=8M # innodb_flush_log_at_trx_commit=1 innodb_lock_wait_timeout=50 # # Uncomment the next line if you want to use it #innodb_thread_concurrency=5 * Determining the Maximum Memory Allocation for InnoDB * *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 value of the following expression is close to or exceeds 2GB: 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. *Tuning other *Note `mysqld': mysqld. server parameters.* The following values are typical and suit most users: [mysqld] skip-external-locking max_connections=200 read_buffer_size=1M sort_buffer_size=1M # # Set key_buffer to 5 - 50% of your RAM depending on how much # you use MyISAM tables, but keep key_buffer_size + InnoDB # buffer pool size < 80% of your RAM key_buffer_size=VALUE On Linux, if the kernel is enabled for large page support, `InnoDB' can use large pages to allocate memory for its buffer pool and additional memory pool. See *Note large-page-support::. * Enabling the InnoDB Plugin * If you want to use `InnoDB Plugin' rather than the built-in version of `InnoDB', to get the latest performance improvements and new features such as table compression and fast index creation, see *Note replacing-builtin-innodb::. * Turning Off InnoDB * If you do not want to use `InnoDB' tables, start the server with the `--innodb=OFF' or `--skip-innodb' option to disable the `InnoDB' storage engine. In this case, the server will not start if the default storage engine is set to *Note `InnoDB': innodb-storage-engine. Use `--default-storage-engine' to set the default to some other engine if necessary.  File: manual.info, Node: replacing-builtin-innodb, Next: innodb-multiple-tablespaces, Prev: innodb-configuration, Up: innodb-configuration 14.6.1.1 Using `InnoDB Plugin' Instead of the Built-In `InnoDB' ............................................................... To use `InnoDB Plugin' in MySQL 5.1, you must disable the built-in version of `InnoDB' that is also included and instruct the server to use `InnoDB Plugin' instead. To accomplish this, use the following lines in your `my.cnf' file: [mysqld] ignore-builtin-innodb plugin-load=innodb=ha_innodb_plugin.so For the `plugin-load' option, `innodb' is the name to associate with the plugin and `ha_innodb_plugin.so' is the name of the shared object library that contains the plugin code. The extension of `.so' applies for Unix (and similar) systems. For HP-UX on HPPA (11.11) or Windows, the extension should be `.sl' or `.dll', respectively, rather than `.so'. If the server has problems finding the plugin when it starts up, specify the pathname to the plugin directory. For example, if plugins are located in the `lib/mysql/plugin' directory under the MySQL installation directory and you have installed MySQL at `/usr/local/mysql', use these lines in your `my.cnf' file: [mysqld] ignore-builtin-innodb plugin-load=innodb=ha_innodb_plugin.so plugin_dir=/usr/local/mysql/lib/mysql/plugin The previous examples show how to activate the storage engine part of `InnoDB Plugin,' but the plugin also implements several InnoDB-related `INFORMATION_SCHEMA' tables. (For information about these tables, see InnoDB `INFORMATION_SCHEMA' tables (http://dev.mysql.com/doc/refman/5.5/en/innodb-information-schema.html).) To enable these tables, include additional `NAME=LIBRARY' pairs in the value of the `plugin-load' option: [mysqld] ignore-builtin-innodb plugin-load=innodb=ha_innodb_plugin.so ;innodb_trx=ha_innodb_plugin.so ;innodb_locks=ha_innodb_plugin.so ;innodb_lock_waits=ha_innodb_plugin.so ;innodb_cmp=ha_innodb_plugin.so ;innodb_cmp_reset=ha_innodb_plugin.so ;innodb_cmpmem=ha_innodb_plugin.so ;innodb_cmpmem_reset=ha_innodb_plugin.so The `plugin-load' option value as shown here is formatted on multiple lines for display purposes but should be written in `my.cnf' using a single line without spaces in the option value. On Windows, substitute `.dll' for each instance of the `.so' extension. After the server starts, verify that `InnoDB Plugin' has been loaded by using the *Note `SHOW PLUGINS': show-plugins. statement. For example, if you have loaded the storage engine and the `INFORMATION_SCHEMA' tables, the output should include lines similar to these: mysql> SHOW PLUGINS; +---------------------+--------+--------------------+... | Name | Status | Type |... +---------------------+--------+--------------------+... ... | InnoDB | ACTIVE | STORAGE ENGINE |... | INNODB_TRX | ACTIVE | INFORMATION SCHEMA |... | INNODB_LOCKS | ACTIVE | INFORMATION SCHEMA |... | INNODB_LOCK_WAITS | ACTIVE | INFORMATION SCHEMA |... | INNODB_CMP | ACTIVE | INFORMATION SCHEMA |... | INNODB_CMP_RESET | ACTIVE | INFORMATION SCHEMA |... | INNODB_CMPMEM | ACTIVE | INFORMATION SCHEMA |... | INNODB_CMPMEM_RESET | ACTIVE | INFORMATION SCHEMA |... +---------------------+--------+--------------------+... An alternative to using the `plugin-load' option at server startup is to use the *Note `INSTALL PLUGIN': install-plugin. statement at runtime. First start the server with the `ignore-builtin-innodb' option to disable the built-in version of `InnoDB': [mysqld] ignore-builtin-innodb Then issue an *Note `INSTALL PLUGIN': install-plugin. statement for each plugin that you want to load: mysql> INSTALL PLUGIN InnoDB SONAME 'ha_innodb_plugin.so'; mysql> INSTALL PLUGIN INNODB_TRX SONAME 'ha_innodb_plugin.so'; mysql> INSTALL PLUGIN INNODB_LOCKS SONAME 'ha_innodb_plugin.so'; ... *Note `INSTALL PLUGIN': install-plugin. need be issued only once for each plugin. Installed plugins will be loaded automatically on subsequent server restarts. If you build MySQL from a source distribution, `InnoDB Plugin' is one of the storage engines that is built by default. Build MySQL the way you normally do; for example, by using the instructions at *Note source-installation::. After the build completes, you should find the plugin shared object file under the `storage/innodb_plugin' directory, and `make install' should install it in the plugin directory. Configure MySQL to use `InnoDB Plugin' as described earlier for binary distributions. If you use `gcc', `InnoDB Plugin' cannot be compiled with `gcc' 3.x; you must use `gcc' 4.x instead. *Note*: In MySQL 5.5, the `InnoDB Plugin' is also included, but it becomes the built-in version of `InnoDB' in MySQL Server, replacing the version previously included as the built-in `InnoDB' engine. This means that if you use `InnoDB Plugin' in MySQL 5.1 using the instructions just given, you will need to remove `ignore-builtin-innodb' and `plugin-load' from your startup options after an upgrade to MySQL 5.5 or the server will fail to start.  File: manual.info, Node: innodb-multiple-tablespaces, Next: innodb-raw-devices, Prev: replacing-builtin-innodb, Up: innodb-configuration 14.6.1.2 Using Per-Table Tablespaces .................................... You can store each `InnoDB' table and its indexes in its own file. This feature is called `multiple tablespaces' because in effect each table has its own tablespace. * Advantages of Per-Table Tablespaces * * You can reclaim disk space when truncating or dropping a table. For tables created when file-per-table mode is turned off, truncating or dropping them creates free space internally in the ibdata files (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_ibdata_file). That free space can only be used for new `InnoDB' data. * The *Note `TRUNCATE TABLE': truncate-table. operation is faster when run on individual `.ibd' files. * You can store specific tables on separate storage devices, for I/O optimization, space management, or backup purposes. * You can run *Note `OPTIMIZE TABLE': optimize-table. to compact or recreate a tablespace. When you run an *Note `OPTIMIZE TABLE': optimize-table, `InnoDB' will create 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 `.ibd' file. If the previous `.ibd' file had grown significantly but actual data only accounted for a portion of its size, running *Note `OPTIMIZE TABLE': optimize-table. allows you to reclaim the unused space. * You can move individual `InnoDB' tables rather than entire databases. * You can enable compression (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_compression) for table and index data, using the compressed row format (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_compressed_row_format). * You can enable more efficient storage for tables with large BLOB or text columns using the dynamic row format (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_dynamic_row_format). * Using `innodb_file_per_table' may improve chances for a successful recovery and save time if a corruption occurs, a server cannot be restarted, or backup and binary logs are unavailable. * You can back up or restore a single table quickly, without interrupting the use of other `InnoDB' tables, using the MySQL Enterprise Backup product. See Backing Up and Restoring a Single `.ibd' File (http://dev.mysql.com/doc/mysql-enterprise-backup/3.8/en/partial.restoring.single.html) for the procedure and restrictions. * File-per-table mode allows you to excluded tables from a backup. This is beneficial if you have tables that require backup less frequently or on a different schedule. * File-per-table mode is convenient for per-table status reporting when copying or backing up tables. * File-per-table mode allows you to 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 `innodb_file_per_table' in conjunction with `innodb_flush_method'. * If `innodb_file_per_table' is disabled, there is one shared tablespace (the system tablespace) for tables, the data dictionary, and undo logs. This single tablespace has a 64TB size limit. If `innodb_file_per_table' is enabled, each table has its own tablespace, each with a 64TB size limit. See *Note table-size-limit:: for related information. * Potential Disadvantages of Per-Table Tablespaces * * With `innodb_file_per_table', each table may have unused table space, which can only be utilized by rows of the same table. This could lead to more rather than less wasted table 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. * *Note `mysqld': mysqld. must keep 1 open file handle per table, which may impact performance if you have numerous tables. * More file descriptors are used. * If backward compatibility with MySQL 5.1 is a concern, be aware that enabling `innodb_file_per_table' means that *Note `ALTER TABLE': alter-table. will move `InnoDB' tables from the system tablespace to individual `.ibd' files. * If many tables are growing there is potential for more fragmentation which can impede *Note `DROP TABLE': 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 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 shared 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 per-table tablespace files. Per-table tablespace files are auto-extending regardless of the value of `innodb_autoextend_increment'. The initial extensions are by small amounts, after which extensions occur in increments of 4MB. * Enabling and Disabling Multiple Tablespaces * To enable multiple tablespaces, start the server with the `--innodb_file_per_table' option. For example, add a line to the `[mysqld]' section of `my.cnf': [mysqld] innodb_file_per_table With multiple tablespaces enabled, `InnoDB' stores each newly created table into its own `TBL_NAME.ibd' file in the database directory where the table belongs. This is similar to what the `MyISAM' storage engine does, but `MyISAM' divides the table into a `TBL_NAME.MYD' data file and an `TBL_NAME.MYI' index file. For `InnoDB', the data and the indexes are stored together in the `.ibd' file. The `TBL_NAME.frm' file is still created as usual. You cannot freely move `.ibd' files between database directories as you can with `MyISAM' table files. This is because the table definition that is stored in the `InnoDB' shared tablespace includes the database name, and because `InnoDB' must preserve the consistency of transaction IDs and log sequence numbers. If you remove the `innodb_file_per_table' line from `my.cnf' and restart the server, `InnoDB' creates tables inside the shared tablespace files again. The `--innodb_file_per_table' option affects only table creation, not access to existing tables. If you start the server with this option, new tables are created using `.ibd' files, but you can still access tables that exist in the shared tablespace. If you start the server without this option, new tables are created in the shared tablespace, but you can still access any tables that were created using multiple tablespaces. *Note*: `InnoDB' always needs the shared tablespace because it puts its internal data dictionary and undo logs there. The `.ibd' files are not sufficient for `InnoDB' to operate. To move an `.ibd' file and the associated table from one database to another, use a *Note `RENAME TABLE': 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. Issue this *Note `ALTER TABLE': alter-table. statement to delete the current `.ibd' file: ALTER TABLE TBL_NAME DISCARD TABLESPACE; 2. Copy the backup `.ibd' file to the proper database directory. 3. Issue this *Note `ALTER TABLE': alter-table. statement to tell `InnoDB' to use the new `.ibd' file for the table: ALTER TABLE TBL_NAME IMPORT TABLESPACE; 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. * *Note `mysqld': 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 *Note `mysqld': mysqld. server and commit all transactions. 2. Wait until *Note `SHOW ENGINE INNODB STATUS': show-engine. 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 commercial `InnoDB Hot Backup' tool: 1. Use `InnoDB Hot Backup' to back up the `InnoDB' installation. 2. Start a second *Note `mysqld': mysqld. server on the backup and let it clean up the `.ibd' files in the backup.  File: manual.info, Node: innodb-raw-devices, Next: innodb-init, Prev: innodb-multiple-tablespaces, Up: innodb-configuration 14.6.1.3 Using Raw Disk Partitions for the Shared Tablespace ............................................................ You can use raw disk partitions as data files in the `InnoDB' system tablespace (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 create a new data file, put the keyword `newraw' immediately after the data file size in `innodb_data_file_path'. 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 The next time you start 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.) 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 Then restart the server and `InnoDB' permits changes to be made. On Windows, you can allocate a disk partition as a data file like this: [mysqld] innodb_data_home_dir= innodb_data_file_path=//./D::10Gnewraw The `//./' corresponds to the Windows syntax of `\\.\' for accessing physical drives. 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'.  File: manual.info, Node: innodb-init, Next: error-creating-innodb, Prev: innodb-raw-devices, Up: innodb-configuration 14.6.1.4 Creating the `InnoDB' Tablespace ......................................... Suppose that you have installed MySQL and have edited your option file so that it contains the necessary `InnoDB' configuration parameters. Before starting MySQL, verify that the directories you have specified for `InnoDB' data files and log files exist and that the MySQL server has access rights to those directories. `InnoDB' does not create directories, only files. Check also that you have enough disk space for the data and log files. It is best to run the MySQL server *Note `mysqld': mysqld. from the command prompt when you first start the server with `InnoDB' enabled, not from *Note `mysqld_safe': mysqld-safe. or as a Windows service. When you run from a command prompt you see what *Note `mysqld': mysqld. prints and what is happening. On Unix, just invoke *Note `mysqld': mysqld. On Windows, start *Note `mysqld': mysqld. with the `--console' option to direct the output to the console window. When you start the MySQL server after initially configuring `InnoDB' in your option file, `InnoDB' creates your data files and log files, and prints something like this: InnoDB: The first specified datafile /home/heikki/data/ibdata1 did not exist: InnoDB: a new database to be created! InnoDB: Setting file /home/heikki/data/ibdata1 size to 134217728 InnoDB: Database physically writes the file full: wait... InnoDB: datafile /home/heikki/data/ibdata2 did not exist: new to be created InnoDB: Setting file /home/heikki/data/ibdata2 size to 262144000 InnoDB: Database physically writes the file full: wait... InnoDB: Log file /home/heikki/data/logs/ib_logfile0 did not exist: new to be created InnoDB: Setting log file /home/heikki/data/logs/ib_logfile0 size to 5242880 InnoDB: Log file /home/heikki/data/logs/ib_logfile1 did not exist: new to be created InnoDB: Setting log file /home/heikki/data/logs/ib_logfile1 size to 5242880 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 InnoDB: Started mysqld: ready for connections At this point `InnoDB' has initialized its tablespace and log files. You can connect to the MySQL server with the usual MySQL client programs like *Note `mysql': mysql. When you shut down the MySQL server with *Note `mysqladmin shutdown': mysqladmin, the output is like this: 010321 18:33:34 mysqld: Normal shutdown 010321 18:33:34 mysqld: Shutdown Complete InnoDB: Starting shutdown... InnoDB: Shutdown completed You can look at the data file and log directories and you see the files created there. When MySQL is started again, the data files and log files have been created already, so the output is much briefer: InnoDB: Started mysqld: ready for connections If you add the `innodb_file_per_table' option to `my.cnf', `InnoDB' stores each table in its own `.ibd' file in the same MySQL database directory where the `.frm' file is created. See *Note innodb-multiple-tablespaces::.  File: manual.info, Node: error-creating-innodb, Prev: innodb-init, Up: innodb-configuration 14.6.1.5 Dealing with `InnoDB' Initialization Problems ...................................................... If `InnoDB' prints an operating system error during a file operation, usually the problem has one of the following causes: * You did not create the `InnoDB' data file directory or the `InnoDB' log directory. * *Note `mysqld': mysqld. does not have access rights to create files in those directories. * *Note `mysqld': mysqld. cannot read the proper `my.cnf' or `my.ini' option file, and consequently does not see the options that you specified. * The disk is full or a disk quota is exceeded. * You have created a subdirectory whose name is equal to a data file that you specified, so the name cannot be used as a file name. * There is a syntax error in the `innodb_data_home_dir' or `innodb_data_file_path' value. If something goes wrong when `InnoDB' attempts to initialize its tablespace or its log files, delete all files created by `InnoDB'. This means all `ibdata' files and all `ib_logfile' files. In case you have already created some `InnoDB' tables, delete the corresponding `.frm' files for these tables (and any `.ibd' files if you are using multiple tablespaces) from the MySQL database directories as well. Then you can try the `InnoDB' database creation again. It is best to start the MySQL server from a command prompt so that you see what is happening.  File: manual.info, Node: innodb-parameters, Next: using-innodb-tables, Prev: innodb-configuration, Up: innodb-storage-engine 14.6.2 `InnoDB' Startup Options and System Variables ---------------------------------------------------- This section describes the `InnoDB'-related command 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 `InnoDB' checksums, you can use `--innodb_checksums' or `--skip-innodb_checksums' on the command line, or `innodb_checksums' or `skip-innodb_checksums' 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. For more information on specifying options and system variables, see *Note program-options::. Many of the system variables can be changed at runtime (see *Note dynamic-system-variables::). *`InnoDB' Option/Variable Reference* Name Cmd-Line Option file System Var Status Var Var Scope Dynamic foreign_key_checks Yes Session Yes have_innodb Yes Global No ignore-builtin-innodbYes Yes Global No - _Variable_: Yes Global No ignore_builtin_innodb innodb Yes Yes innodb_adaptive_flushingYes Yes Yes Global Yes innodb_adaptive_hash_indexYes Yes Yes Global No innodb_additional_mem_pool_sizeYes Yes Yes Global No innodb_autoextend_incrementYes Yes Yes Global Yes innodb_autoinc_lock_modeYes Yes Yes Global No innodb_buffer_pool_awe_mem_mbYes Yes 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_ahead_seq Yes Global No Innodb_buffer_pool_read_requests Yes Global No Innodb_buffer_pool_reads Yes Global No innodb_buffer_pool_sizeYes Yes Yes Global No Innodb_buffer_pool_wait_free Yes Global No Innodb_buffer_pool_write_requests Yes Global No innodb_change_bufferingYes Yes Yes Global Yes innodb_checksumsYes Yes Yes Global No innodb_commit_concurrencyYes Yes Yes Global Yes innodb_concurrency_ticketsYes Yes 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_doublewriteYes Yes Yes Global No innodb_fast_shutdownYes Yes Yes Global Yes innodb_file_formatYes Yes Yes Global Yes innodb_file_format_checkYes Yes Yes Global Yes innodb_file_io_threadsYes Yes Yes Global No innodb_file_per_tableYes Yes Yes Global No innodb_flush_log_at_trx_commitYes Yes Yes Global Yes innodb_flush_methodYes Yes Yes Global No innodb_force_recoveryYes Yes Yes Global No Innodb_have_atomic_builtins Yes Global No innodb_io_capacityYes Yes Yes Global No innodb_lock_wait_timeoutYes Yes Yes Both Yes innodb_locks_unsafe_for_binlogYes Yes Yes Global No innodb_log_arch_dirYes Yes Yes Global No innodb_log_archiveYes Yes Yes Global No innodb_log_buffer_sizeYes Yes Yes Global No innodb_log_file_sizeYes Yes Yes Global No innodb_log_files_in_groupYes Yes Yes Global No innodb_log_group_home_dirYes Yes Yes Global No Innodb_log_waits Yes Global No Innodb_log_write_requests Yes Global No Innodb_log_writes Yes Global No innodb_max_dirty_pages_pctYes Yes Yes Global Yes innodb_max_purge_lagYes Yes Yes Global Yes innodb_mirrored_log_groupsYes Yes Yes Global No innodb_old_blocks_pctYes Yes Yes Global Yes innodb_old_blocks_timeYes Yes Yes Global Yes innodb_open_filesYes Yes Yes Global No 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_size Yes Global No Innodb_pages_created Yes Global No Innodb_pages_read Yes Global No Innodb_pages_written Yes Global No innodb_random_read_aheadYes Yes Yes Global Yes innodb_read_ahead_thresholdYes Yes Yes Global Yes innodb_read_io_threadsYes Yes Yes Global No innodb_replication_delayYes Yes Yes Global Yes innodb_rollback_on_timeoutYes Yes Yes Global No 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_spin_wait_delayYes Yes Yes Global Yes innodb_stats_methodYes Yes Yes Global Yes innodb_stats_on_metadataYes Yes Yes Global Yes innodb_stats_sample_pagesYes Yes Yes Global Yes innodb-status-fileYes Yes innodb_strict_modeYes Yes Yes Both Yes innodb_support_xaYes Yes Yes Both Yes innodb_sync_spin_loopsYes Yes Yes Global Yes innodb_table_locksYes Yes Yes Both Yes innodb_thread_concurrencyYes Yes Yes Global Yes innodb_thread_sleep_delayYes Yes Yes Global Yes innodb_use_legacy_cardinality_algorithmYes Yes Yes Global Yes 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 Session Yes * `InnoDB' Command Options * * `--ignore-builtin-innodb' Options for ignore-builtin-innodb *Introduced* 5.1.33 *Command-Line `--ignore-builtin-innodb' Format* *Option-File Format* `ignore-builtin-innodb' *System Variable `ignore_builtin_innodb' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' This option causes the server to behave as if the built-in `InnoDB' is not present, which enables `InnoDB Plugin' to be used instead. See *Note replacing-builtin-innodb::. If this option is given but `InnoDB Plugin' is not used in place of the built-in `InnoDB', it has the following effects: * Other *Note `InnoDB': innodb-storage-engine. options (including `--innodb' and `--skip-innodb') will not be recognized and should not be used. * The server will not start if the default storage engine is set to *Note `InnoDB': innodb-storage-engine. Use `--default-storage-engine' to set the default to some other engine if necessary. * *Note `InnoDB': innodb-storage-engine. will not appear in the output of *Note `SHOW ENGINES': show-engines. This option was added in MySQL 5.1.33. * `--innodb[=VALUE]' Controls loading of the `InnoDB' storage engine, if the server was compiled with `InnoDB' support. As of MySQL 5.1.36, this option has a tristate format, with possible values of `OFF', `ON', or `FORCE'. Before MySQL 5.1.36, this is a boolean option. See *Note server-plugin-loading::. To disable `InnoDB', use `--innodb=OFF' or `--skip-innodb'. In this case, the server will not start if the default storage engine is set to *Note `InnoDB': innodb-storage-engine. Use `--default-storage-engine' to set the default to some other engine if necessary. * `--innodb-status-file' Options for innodb-status-file *Command-Line `--innodb-status-file' Format* *Option-File Format* `innodb-status-file' *Permitted Values* *Type* `boolean' *Default* `OFF' Controls whether `InnoDB' creates a file named `innodb_status.' in the MySQL data directory. If enabled, `InnoDB' periodically writes the output of *Note `SHOW ENGINE INNODB STATUS': show-engine. to this file. By default, the file is not created. To create it, start *Note `mysqld': 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 * * `ignore_builtin_innodb' Options for ignore-builtin-innodb *Introduced* 5.1.33 *Command-Line `--ignore-builtin-innodb' Format* *Option-File Format* `ignore-builtin-innodb' *System Variable `ignore_builtin_innodb' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' Whether the server was started with the `--ignore-builtin-innodb' option, which causes the server to behave as if the built-in `InnoDB' is not present. For more information, see the description of `--ignore-builtin-innodb' under ``InnoDB' Command Options' earlier in this section. This variable was added in MySQL 5.1.33. * `innodb_adaptive_flushing' Options for innodb_adaptive_flushing *Introduced* 5.1.38 *Command-Line `--innodb_adaptive_flushing=#' Format* *Option-File Format* `innodb_adaptive_flushing' *System Variable `innodb_adaptive_flushing' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `ON' (`InnoDB Plugin' only) `InnoDB Plugin' 1.0.4 and up uses a heuristic to determine when to flush dirty pages (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_dirty_page) in the buffer pool (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_buffer_pool). This heuristic is designed to avoid bursts of I/O activity and is used when `innodb_adaptive_flushing' is enabled (which is the default). * `innodb_adaptive_hash_index' Options for innodb_adaptive_hash_index *Introduced* 5.1.24 *Command-Line `--innodb_adaptive_hash_index=#' Format* *Option-File Format* `innodb_adaptive_hash_index' *System Variable `innodb_adaptive_hash_index' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `ON' Whether the `InnoDB' adaptive hash index (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_adaptive_hash_index) is enabled or disabled. The adaptive hash index feature is useful for some workloads, and not for others; conduct benchmarks with it both enabled and disabled, using realistic workloads. See *Note innodb-adaptive-hash:: for details. This variable is enabled by default. Use `--skip-innodb_adaptive_hash_index' at server startup to disable it. This variable was added in MySQL 5.1.24. * `innodb_additional_mem_pool_size' Options for innodb_additional_mem_pool_size *Command-Line `--innodb_additional_mem_pool_size=#' Format* *Option-File Format* `innodb_additional_mem_pool_size' *System Variable `innodb_additional_mem_pool_size' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `1048576' *Range* `524288 .. 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 need to 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 1MB for the built-in *Note `InnoDB': innodb-storage-engine, 8MB for `InnoDB Plugin'. This variable relates to the `InnoDB' internal memory allocator, which is unused if `innodb_use_sys_malloc' is enabled. * `innodb_autoextend_increment' Options for innodb_autoextend_increment *Command-Line `--innodb_autoextend_increment=#' Format* *Option-File Format* `innodb_autoextend_increment' *System Variable `innodb_autoextend_increment' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `8' *Range* `1 .. 1000' The increment size (in MB) for extending the size of an auto-extending shared tablespace file when it becomes full. The default value is 8. This variable does not affect the per-table tablespace files that are created if you use `innodb_file_per_table=1'. Those files are auto-extending regardless of the value of `innodb_autoextend_increment'. The initial extensions are by small amounts, after which extensions occur in increments of 4MB. * `innodb_buffer_pool_awe_mem_mb' Options for innodb_buffer_pool_awe_mem_mb *Removed* 5.1.13 *Command-Line `--innodb_buffer_pool_awe_mem_mb=#' Format* *Option-File Format* `innodb_buffer_pool_awe_mem_mb' *System Variable `innodb_buffer_pool_awe_mem_mb' Name* *Variable Scope* Global *Dynamic Variable* No *Platform Specific* windows *Permitted Values* *Type* (windows) `numeric' *Default* `0' *Range* `0 .. 63000' The size of the buffer pool (in MB), if it is placed in the AWE memory. If it is greater than 0, `innodb_buffer_pool_size' is the window in the 32-bit address space of *Note `mysqld': mysqld. where `InnoDB' maps that AWE memory. A good value for `innodb_buffer_pool_size' is 500MB. The maximum possible value is 63000. To take advantage of AWE memory, you will need to recompile MySQL yourself. The current project settings needed for doing this can be found in the `storage/innobase/os/os0proc.c' source file. This variable was removed in MySQL 5.1.13. Before that, it is relevant only in 32-bit Windows. If your 32-bit Windows operating system supports more than 4GB memory, using so-called `Address Windowing Extensions,' you can allocate the `InnoDB' buffer pool into the AWE physical memory using this variable. * `innodb_autoinc_lock_mode' Options for innodb_autoinc_lock_mode *Introduced* 5.1.22 *Command-Line `--innodb_autoinc_lock_mode=#' Format* *Option-File Format* `innodb_autoinc_lock_mode' *System Variable `innodb_autoinc_lock_mode' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `1' *Valid Values* `0' `1' `2' The locking mode to use for generating auto-increment values. The permissible values are 0, 1, or 2, for `traditional', `consecutive', or `interleaved' lock mode, respectively. *Note innodb-auto-increment-handling::, describes the characteristics of these modes. This variable was added in MySQL 5.1.22 with a default of 1 (`consecutive' lock mode). Before 5.1.22, `InnoDB' uses `traditional' lock mode. * `innodb_buffer_pool_size' Options for innodb_buffer_pool_size *Command-Line `--innodb_buffer_pool_size=#' Format* *Option-File Format* `innodb_buffer_pool_size' *System Variable `innodb_buffer_pool_size' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values (<= 5.1.27)* *Type* `numeric' *Default* `8388608' *Min Value* `1048576' *Permitted Values (>= 5.1.28)* *Platform Bit Size* `32' *Type* `numeric' *Default* `134217728' *Range* `1048576 .. 2**32-1' *Permitted Values (>= 5.1.28)* *Platform Bit Size* `64' *Type* `numeric' *Default* `134217728' *Range* `1048576 .. 2**64-1' The size in bytes of the memory buffer `InnoDB' uses to cache data and indexes of its tables. The default value is 128MB, increased from a historical default of 8MB. In MySQL 5.1.28 and later, 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. The larger you set this value, the less disk I/O is needed to access data in tables. On a dedicated database server, you may set this to up to 80% of the machine physical memory size. Be prepared to scale back this value if these other issues occur: * Competition for physical memory might 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 size. * The address space 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 large installations, this initialization time may be significant. For example, on a modern Linux x86_64 server, initialization of a 10GB buffer pool takes approximately 6 seconds. See *Note innodb-buffer-pool::. * `innodb_change_buffering' Options for innodb_change_buffering *Introduced* 5.1.38 *Command-Line `--innodb_change_buffering=#' Format* *Option-File Format* `innodb_change_buffering' *System Variable `innodb_change_buffering' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `inserts' *Valid Values* `inserts' `none' (`InnoDB Plugin' only) Whether *Note `InnoDB': innodb-storage-engine. performs insert buffering. The permitted values `none' (do not buffer any operations) and `inserts' (buffer insert operations). The default is `inserts'. For details, see Controlling InnoDB Change Buffering (http://dev.mysql.com/doc/refman/5.5/en/innodb-performance-change_buffering.html). * `innodb_checksums' Options for innodb_checksums *Command-Line `--innodb_checksums' Format* *Option-File Format* `innodb_checksums' *System Variable `innodb_checksums' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `ON' `InnoDB' can use checksum validation on all pages read from the disk to ensure extra fault tolerance against broken hardware or data files. This validation is enabled by default. However, under some rare circumstances (such as when running benchmarks) this extra safety feature is unneeded and can be disabled with `--skip-innodb-checksums'. * `innodb_commit_concurrency' Options for innodb_commit_concurrency *Command-Line `--innodb_commit_concurrency=#' Format* *Option-File Format* `innodb_commit_concurrency' *System Variable `innodb_commit_concurrency' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 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. As of MySQL 5.1.36, the value of `innodb_commit_concurrency' cannot be changed at runtime from zero to nonzero or vice versa. The value can still be changed from one nonzero value to another. * `innodb_concurrency_tickets' Options for innodb_concurrency_tickets *Command-Line `--innodb_concurrency_tickets=#' Format* *Option-File Format* `innodb_concurrency_tickets' *System Variable `innodb_concurrency_tickets' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `500' *Range* `1 .. 4294967295' The number of threads that can enter `InnoDB' concurrently is determined by the `innodb_thread_concurrency' variable. 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 `free 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 500. * `innodb_data_file_path' Options for innodb_data_file_path *Command-Line `--innodb_data_file_path=name' Format* *Option-File Format* `innodb_data_file_path' *System Variable `innodb_data_file_path' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' *Default* `ibdata1:10M:autoextend' The paths to individual data files and their sizes. The full directory path to each data file is formed by concatenating `innodb_data_home_dir' to each path specified here. The file sizes are 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 at least slightly larger than 10MB. If you do not specify `innodb_data_file_path', the default behavior is to create a single auto-extending data file, slightly larger than 10MB, named `ibdata1'. The size limit of individual files is determined by your operating system. You can set the file size to more than 4GB on those operating systems that support big files. You can also use raw disk partitions as data files. For detailed information on configuring `InnoDB' tablespace files, see *Note innodb-configuration::. * `innodb_data_home_dir' Options for innodb_data_home_dir *Command-Line `--innodb_data_home_dir=path' Format* *Option-File Format* `innodb_data_home_dir' *System Variable `innodb_data_home_dir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The common part of the directory path for all `InnoDB' data files in the shared tablespace. This setting does not affect the location of per-file 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 use absolute file paths in `innodb_data_file_path'. * `innodb_doublewrite' Options for innodb_doublewrite *Command-Line `--innodb-doublewrite' Format* *Option-File Format* `innodb_doublewrite' *System Variable `innodb_doublewrite' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' If this variable is enabled (the default), `InnoDB' stores all data twice, first to the doublewrite buffer, and 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. * `innodb_fast_shutdown' Options for innodb_fast_shutdown *Command-Line `--innodb_fast_shutdown[=#]' Format* *Option-File Format* `innodb_fast_shutdown' *System Variable `innodb_fast_shutdown' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `1' *Valid Values* `0' `1' `2' The `InnoDB' shutdown mode. By default, the value is 1, which causes a `fast' shutdown (the normal type of shutdown). If the value is 0, `InnoDB' does a full purge and an insert buffer merge before a shutdown. These operations can take minutes, or even hours in extreme cases. If the value is 1, `InnoDB' skips these operations at shutdown. If the value is 2, `InnoDB' will just flush its logs and then shut down cold, as if MySQL had crashed; no committed transaction will be lost, but crash recovery will be done at the next startup. A value of 2 cannot be used on NetWare. * `innodb_file_format' Options for innodb_file_format *Introduced* 5.1.38 *Command-Line `--innodb_file_format=#' Format* *Option-File Format* `innodb_file_format' *System Variable `innodb_file_format' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values (>= 5.1.38)* *Type* `string' *Default* `Antelope' (`InnoDB Plugin' only) The file format to use for new *Note `InnoDB': innodb-storage-engine. tables. Currently `Antelope' and `Barracuda' are supported. This applies only for tables that have their own tablespace, so for it to have an effect `innodb_file_per_table' must be enabled. * `innodb_file_format_check' Options for innodb_file_format_check *Introduced* 5.1.38 *Command-Line `--innodb_file_format_check=#' Format* *Option-File Format* `innodb_file_format_check' *System Variable `innodb_file_format_check' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values (<= 5.1.41)* *Type* `string' *Default* `Antelope' *Permitted Values (>= 5.1.42)* *Type* `string' *Default* `Barracuda' (`InnoDB Plugin' only) 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 shared 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_check' to the file format tag, which is the value seen at runtime. * `innodb_file_io_threads' Options for innodb_file_io_threads *Command-Line `--innodb_file_io_threads=#' Format* *Option-File Format* `innodb_file_io_threads' *System Variable `innodb_file_io_threads' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `4' *Range* `4 .. 64' The number of file I/O threads in `InnoDB'. Normally, this should be left at the default value of 4, but disk I/O on Windows may benefit from a larger number. On Unix, increasing the number has no effect; `InnoDB' always uses the default value. With `InnoDB Plugin', this variable is unused. Use `innodb_read_io_threads' and `innodb_write_io_threads' instead. * `innodb_file_per_table' Options for innodb_file_per_table *Command-Line `--innodb_file_per_table' Format* *Option-File Format* `innodb_file_per_table' *System Variable `innodb_file_per_table' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `OFF' If `innodb_file_per_table' is disabled (the default), `InnoDB' creates tables in the system tablespace (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_system_tablespace). If `innodb_file_per_table' is enabled, `InnoDB' creates each new table using its own `.ibd' file (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_ibd_file) for storing data and indexes, rather than in the system tablespace. See *Note innodb-multiple-tablespaces:: for information about advantages, disadvantages, and features, such as `InnoDB' table compression, that only work for tables stored in separate tablespaces. * `innodb_flush_log_at_trx_commit' Options for innodb_flush_log_at_trx_commit *Command-Line `--innodb_flush_log_at_trx_commit[=#]' Format* *Option-File Format* `innodb_flush_log_at_trx_commit' *System Variable `innodb_flush_log_at_trx_commit' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `1' *Valid Values* `0' `1' `2' If the value of `innodb_flush_log_at_trx_commit' is 0, the log buffer is written out to the log file once per second and the flush to disk operation is performed on the log file, but nothing is done at a transaction commit. When the value is 1 (the default), the log buffer is written out to the log file at each transaction commit and the flush to disk operation is performed on the log file. When the value is 2, the log buffer is written out to the file at each commit, but the flush to disk operation is not performed on it. However, the flushing on the log file takes place once per second also when the value is 2. Note that the once-per-second flushing is not 100% guaranteed to happen every second, due to process scheduling issues. The default value of 1 is required for full ACID compliance. You can achieve better performance by setting the value different from 1, but then you can lose up to one second worth of transactions in a crash. With a value of 0, any *Note `mysqld': mysqld. process crash can erase the last second of transactions. With a value of 2, only an operating system crash or a power outage can erase the last second of transactions. `InnoDB''s crash recovery (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_crash_recovery) works regardless of the value. For the greatest possible durability and consistency in a replication setup using `InnoDB' with transactions, use `innodb_flush_log_at_trx_commit=1' and `sync_binlog=1' in your master server `my.cnf' file. *Caution*: Many operating systems and some disk hardware fool the flush-to-disk operation. They may tell *Note `mysqld': mysqld. that the flush has taken place, even though it has not. Then the durability of transactions is not guaranteed even with the setting 1, and in the worst case a power outage can even corrupt the `InnoDB' database. 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 using the Unix command `hdparm' to disable the caching of disk writes in hardware caches, or use some other command specific to the hardware vendor. * `innodb_flush_method' Options for innodb_flush_method *Command-Line `--innodb_flush_method=name' Format* *Option-File Format* `innodb_flush_method' *System Variable `innodb_flush_method' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values (<= 5.1.23)* *Type* (linux) `enumeration' *Default* `fdatasync' *Valid Values* `fdatasync' `O_DSYNC' `O_DIRECT' *Permitted Values (<= 5.1.23)* *Type* (hpux) `enumeration' *Default* `fdatasync' *Valid Values* `fdatasync' `O_DSYNC' `O_DIRECT' *Permitted Values (<= 5.1.23)* *Type* (solaris) `enumeration' *Default* `fdatasync' *Valid Values* `fdatasync' `O_DSYNC' `O_DIRECT' By default, `InnoDB' uses the `fsync()' system call to flush both the data and log files. If `innodb_flush_method' option is set to `O_DSYNC', `InnoDB' uses `O_SYNC' to open and flush the log files, and `fsync()' to flush the data files. If `O_DIRECT' is specified (available on some GNU/Linux versions, FreeBSD, and Solaris), `InnoDB' uses `O_DIRECT' (or `directio()' on Solaris) to open the data files, and uses `fsync()' to flush both the data and log files. Note that `InnoDB' uses `fsync()' instead of `fdatasync()', and it does not use `O_DSYNC' by default because there have been problems with it on many varieties of Unix. This variable is relevant only for Unix. On Windows, the flush method is always `async_unbuffered' and cannot be changed. Depending on hardware configuration, setting `innodb_flush_method' to `O_DIRECT' can either have either a positive or negative effect on performance. Benchmark your particular configuration to decide which setting to use. The mix of read and write operations in your workload can also affect which setting performs better for you. 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's filesystem 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 the same type of hardware and workload that reflects your production environment. Formerly it was possible to explicitly specify a value of `fdatasync' to obtain the default behavior. This is no longer possible as of MySQL 5.1.24 because it can be confusing that a value of `fdatasync' causes use of `fsync()' rather than `fdatasync()' for flushing. To obtain the default value now, do not set `innodb_flush_method' at startup. * `innodb_force_recovery' Options for innodb_force_recovery *Command-Line `--innodb_force_recovery=#' Format* *Option-File Format* `innodb_force_recovery' *System Variable `innodb_force_recovery' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `enumeration' *Default* `0' *Valid Values* `0' `1' `2' `3' `4' `5' `6' The crash recovery mode. Possible values are from 0 to 6. The meanings of these values are described in *Note forcing-innodb-recovery::. *Warning*: Only set this variable greater than 0 in an emergency situation, to dump your tables from a corrupt database. As a safety measure, `InnoDB' prevents any changes to its data when this variable is greater than 0. This restriction also prohibits some queries that use `WHERE' or `ORDER BY' clauses, because high values can prevent queries from using indexes. * `innodb_io_capacity' Options for innodb_io_capacity *Introduced* 5.1.38 *Command-Line `--innodb_io_capacity=#' Format* *Option-File Format* `innodb_io_capacity' *System Variable `innodb_io_capacity' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `200' *Range* `100 .. 2**32-1' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `200' *Range* `100 .. 2**64-1' (`InnoDB Plugin' only) An upper limit on the I/O activity performed by the `InnoDB' background tasks, such as flushing pages from the buffer pool (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_buffer_pool) and merging data from the insert buffer (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_insert_buffer). The default value is 200. For busy systems capable of higher I/O rates, you can set a higher value at server startup, to help the server handle the background maintenance work associated with a high rate of row changes. For systems with individual 5400 RPM or 7200 RPM drives, you might lower the value to the former default of `100'. This parameter should be set to approximately the number of I/O operations that the system can perform per second. Ideally, keep this setting as low as practical, but not so low that these background activities fall behind. If the value is too high, data is removed from the buffer pool and insert buffer too quickly to provide significant benefit from the caching. The value represents an estimated proportion of the I/O operations per second (IOPS) available to older-generation disk drives that could perform about 100 IOPS. The current default of 200 reflects that modern storage devices are capable of much higher I/O rates. In general, you can increase the value as a function of the number of drives used for *Note `InnoDB': innodb-storage-engine. I/O, particularly fast drives capable of high numbers of IOPS. For example, systems that use multiple disks or solid-state disks for *Note `InnoDB': innodb-storage-engine. are likely to benefit from the ability to control this parameter. Although you can specify a very high number, in practice such large values have little if any benefit; for example, a value of one million would be considered very high. You can set the `innodb_io_capacity' value to any number 100 or greater, and the default value is `200'. 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. See Controlling the Master Thread I/O Rate (http://dev.mysql.com/doc/refman/5.5/en/innodb-performance-thread_io_rate.html) for more guidelines about this option. For general information about InnoDB I/O performance, see Optimizing `InnoDB' Disk I/O (http://dev.mysql.com/doc/refman/5.5/en/optimizing-innodb-diskio.html). This variable was added in MySQL 5.1.38. * `innodb_lock_wait_timeout' Options for innodb_lock_wait_timeout *Command-Line `--innodb_lock_wait_timeout=#' Format* *Option-File Format* `innodb_lock_wait_timeout' *System Variable `innodb_lock_wait_timeout' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `50' *Range* `1 .. 1073741824' The timeout 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 *Note innodb-error-handling::. You might decrease this value for highly interactive applications or OLTP (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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. `InnoDB' does detect transaction deadlocks in its own lock table immediately and rolls back one transaction. The lock wait timeout value does not apply to such a wait. For the built-in `InnoDB', this variable can be set only at server startup. For `InnoDB Plugin', it can be set at startup or changed at runtime, and has both global and session values. * `innodb_locks_unsafe_for_binlog' Options for innodb_locks_unsafe_for_binlog *Command-Line `--innodb_locks_unsafe_for_binlog' Format* *Option-File Format* `innodb_locks_unsafe_for_binlog' *System Variable `innodb_locks_unsafe_for_binlog' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `OFF' This variable affects how `InnoDB' uses gap locking for searches and index scans. 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, 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. See *Note innodb-record-level-locks::. 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 effect of enabling `innodb_locks_unsafe_for_binlog' is similar to but not identical to setting the transaction isolation level to `READ COMMITTED': * 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 additional details about the effect of isolation level on gap locking, see *Note set-transaction::. 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 `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 *Note `SELECT': 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 additional information about phantoms, see *Note innodb-next-key-locking::. Enabling `innodb_locks_unsafe_for_binlog' has additional effects: * For *Note `UPDATE': update. or *Note `DELETE': 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 *Note `UPDATE': 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 *Note `UPDATE': 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 *Note innodb-index-types::). Suppose that one client performs an *Note `UPDATE': update. using these statements: SET autocommit = 0; UPDATE t SET b = 5 WHERE b = 3; Suppose also that a second client performs an *Note `UPDATE': update. by executing these statements following those of the first client: SET autocommit = 0; UPDATE t SET b = 4 WHERE b = 2; As *Note `InnoDB': innodb-storage-engine. executes each *Note `UPDATE': update, it first acquires an exclusive lock for each row, and then determines whether to modify it. If *Note `InnoDB': innodb-storage-engine. does not modify the row and `innodb_locks_unsafe_for_binlog' is enabled, it releases the lock. Otherwise, *Note `InnoDB': innodb-storage-engine. 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 *Note `UPDATE': 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 *Note `UPDATE': 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 *Note `UPDATE': 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 *Note `UPDATE': 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 *Note `UPDATE': 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 Semi-consistent read is available as of MySQL 5.1.5. Before 5.1.5, the second *Note `UPDATE': update. proceeds part way before it blocks. It begins acquiring x-locks, and blocks when it tries to acquire one for a row still locked by first *Note `UPDATE': update. The second *Note `UPDATE': update. does not proceed until the first *Note `UPDATE': update. commits or rolls back: x-lock(1,2); update(1,2) to (1,4); retain x-lock x-lock(2,3); block and wait for first UPDATE to commit or roll back In this case, the second *Note `UPDATE': update. must wait for a commit or rollback of the first *Note `UPDATE': update, even though it affects different rows. The first *Note `UPDATE': update. has an exclusive lock on row (2,3) that it has not released. As the second *Note `UPDATE': update. scans rows, it tries to acquire an exclusive lock for that same row, which it cannot have. Thus, before MySQL 5.1.5, enabling `innodb_locks_unsafe_for_binlog' still does not permit operations such as *Note `UPDATE': update. to overtake other similar operations (such as another *Note `UPDATE': update.) even when they affect different rows. * `innodb_log_arch_dir' This variable is deprecated, and was removed in MySQL 5.1.21. * `innodb_log_archive' This variable is deprecated, and was removed in MySQL 5.1.18. * `innodb_log_buffer_size' Options for innodb_log_buffer_size *Command-Line `--innodb_log_buffer_size=#' Format* *Option-File Format* `innodb_log_buffer_size' *System Variable `innodb_log_buffer_size' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `1048576' *Range* `1048576 .. 4294967295' The size in bytes of the buffer that `InnoDB' uses to write to the log files on disk. The default value is 1MB for the built-in *Note `InnoDB': innodb-storage-engine, 8MB for `InnoDB Plugin'. Sensible values range from 1MB to 8MB. 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 big transactions, making the log buffer larger saves disk I/O. * `innodb_log_file_size' Options for innodb_log_file_size *Command-Line `--innodb_log_file_size=#' Format* *Option-File Format* `innodb_log_file_size' *System Variable `innodb_log_file_size' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `5242880' *Range* `1048576 .. 4294967295' The size in bytes of each log file in a log group. The combined size of log files cannot exceed 3.99999999068677 GB which is equal to the 4294967295 range limit. A pair of 2047 MB log files, for example, would allow you to approach the range limit but not exceed it. The default value is 5MB. Sensible values range from 1MB to 1/N-th of the size of the buffer pool, where N is the number of log files in the group. The larger the value, the less checkpoint flush activity is needed in the buffer pool, saving disk I/O. But larger log files also mean that recovery is slower in case of a crash. * `innodb_log_files_in_group' Options for innodb_log_files_in_group *Command-Line `--innodb_log_files_in_group=#' Format* *Option-File Format* `innodb_log_files_in_group' *System Variable `innodb_log_files_in_group' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `2' *Range* `2 .. 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. * `innodb_log_group_home_dir' Options for innodb_log_group_home_dir *Command-Line `--innodb_log_group_home_dir=path' Format* *Option-File Format* `innodb_log_group_home_dir' *System Variable `innodb_log_group_home_dir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The directory path to the `InnoDB' log files. 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. Their size is given by the size of the `innodb_log_file_size' system variable. * `innodb_max_dirty_pages_pct' Options for innodb_max_dirty_pages_pct *Command-Line `--innodb_max_dirty_pages_pct=#' Format* *Option-File Format* `innodb_max_dirty_pages_pct' *System Variable `innodb_max_dirty_pages_pct' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `90' *Range* `0 .. 100' This is an integer in the range from 0 to 100. The default value is 90 for the built-in *Note `InnoDB': innodb-storage-engine, 75 for `InnoDB Plugin'. The main thread in `InnoDB' tries to write pages from the buffer pool so that the percentage of dirty (not yet written) pages will not exceed this value. * `innodb_max_purge_lag' Options for innodb_max_purge_lag *Command-Line `--innodb_max_purge_lag=#' Format* *Option-File Format* `innodb_max_purge_lag' *System Variable `innodb_max_purge_lag' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 4294967295' This variable controls how to delay *Note `INSERT': insert, *Note `UPDATE': update, and *Note `DELETE': delete. operations when purge operations are lagging (see *Note innodb-multi-versioning::). The default value 0 (no delays). The `InnoDB' transaction system maintains a list of transactions that have index records delete-marked by *Note `UPDATE': update. or *Note `DELETE': delete. operations. Let the length of this list be PURGE_LAG. When PURGE_LAG exceeds `innodb_max_purge_lag', each *Note `INSERT': insert, *Note `UPDATE': update, and *Note `DELETE': delete. operation is delayed by ((PURGE_LAG/`innodb_max_purge_lag')x10)-5 milliseconds. The delay is computed in the beginning of a purge batch, every ten seconds. The operations are not delayed if purge cannot run because of an old consistent read view that could see the rows to be purged. 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. For example, if the output includes the following lines, the lag value is 20: ------------ TRANSACTIONS ------------ Trx id counter 0 290328385 Purge done for trx's n:o < 0 290315608 undo n:o < 0 17 History list length 20 * `innodb_mirrored_log_groups' Has no effect. * `innodb_old_blocks_pct' Options for innodb_old_blocks_pct *Introduced* 5.1.41 *Command-Line `--innodb_old_blocks_pct=#' Format* *Option-File Format* `innodb_old_blocks_pct' *System Variable `innodb_old_blocks_pct' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `37' *Range* `5 .. 95' (`InnoDB Plugin' only) Specifies the approximate percentage of the `InnoDB' buffer pool (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_buffer_pool) used for the old block sublist (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_sublist). The range of values is 5 to 95. The default value is 37 (that is, 3/8 of the pool). See *Note innodb-buffer-pool:: for information about buffer pool management, such as the LRU (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_lru) algorithm and eviction (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_eviction) policies. This variable was added in MySQL 5.1.41. * `innodb_old_blocks_time' Options for innodb_old_blocks_time *Introduced* 5.1.41 *Command-Line `--innodb_old_blocks_time=#' Format* *Option-File Format* `innodb_old_blocks_time' *System Variable `innodb_old_blocks_time' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 2**32-1' (`InnoDB Plugin' only) Specifies how long in milliseconds (ms) a block inserted into the old sublist (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_sublist) must stay there after its first access before it can be moved to the new sublist. The default 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 ms 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. See *Note innodb-buffer-pool::. This variable was added in MySQL 5.1.41. * `innodb_open_files' Options for innodb_open_files *Command-Line `--innodb_open_files=#' Format* *Option-File Format* `innodb_open_files' *System Variable `innodb_open_files' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `300' *Range* `10 .. 4294967295' This variable is relevant only 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. 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. * `innodb_random_read_ahead' Options for innodb_random_read_ahead *Introduced* 5.1.59 *Command-Line `--innodb_random_read_ahead=#' Format* *Option-File Format* `innodb_random_read_ahead' *System Variable `innodb_random_read_ahead' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' Enables the random read-ahead (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_read_ahead) technique for optimizing `InnoDB' I/O. This is a setting that was originally on by default, then was removed in MySQL 5.5, and now is available but turned off by default. See Changes in the Read-Ahead Algorithm (http://dev.mysql.com/doc/refman/5.5/en/innodb-performance-read_ahead.html) for details about the performance considerations for the different types of read-ahead requests. For general I/O tuning advice, see Optimizing `InnoDB' Disk I/O (http://dev.mysql.com/doc/refman/5.5/en/optimizing-innodb-diskio.html). * `innodb_read_ahead_threshold' Options for innodb_read_ahead_threshold *Introduced* 5.1.38 *Command-Line `--innodb_read_ahead_threshold=#' Format* *Option-File Format* `innodb_read_ahead_threshold' *System Variable `innodb_read_ahead_threshold' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `56' *Range* `0 .. 64' (`InnoDB Plugin' only) Controls the sensitivity of linear read-ahead (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_extent) (64 pages), it initiates an asynchronous read for the entire following extent. The permissible range of values is 0 to 64. The default is 56: `InnoDB' must read at least 56 pages sequentially from an extent to initiate an asynchronous read for the following extent. This variable was added in MySQL 5.1.38. * `innodb_read_io_threads' Options for innodb_read_io_threads *Introduced* 5.1.38 *Command-Line `--innodb_read_io_threads=#' Format* *Option-File Format* `innodb_read_io_threads' *System Variable `innodb_read_io_threads' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `4' *Range* `1 .. 64' (`InnoDB Plugin' only) The number of I/O threads for read operations in `InnoDB'. The default value is 4. *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. This variable was added in MySQL 5.1.38. * `innodb_replication_delay' Options for innodb_replication_delay *Introduced* 5.1.38 *Command-Line `--innodb_replication_delay=#' Format* *Option-File Format* `innodb_replication_delay' *System Variable `innodb_replication_delay' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 4294967295' (`InnoDB Plugin' only) The replication thread delay (in ms) on a slave server if `innodb_thread_concurrency' is reached. This variable was added in MySQL 5.1.38. * `innodb_rollback_on_timeout' Options for innodb_rollback_on_timeout *Introduced* 5.1.15 *Command-Line `--innodb_rollback_on_timeout' Format* *Option-File Format* `innodb_rollback_on_timeout' *System Variable `innodb_rollback_on_timeout' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `OFF' In MySQL 5.1, `InnoDB' rolls back (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_rollback) 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 (the same behavior as in MySQL 4.1). This variable was added in MySQL 5.1.15. * `innodb_spin_wait_delay' Options for innodb_spin_wait_delay *Introduced* 5.1.38 *Command-Line `--innodb_spin_wait_delay=#' Format* *Option-File Format* `innodb_spin_wait_delay' *System Variable `innodb_spin_wait_delay' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `6' *Range* `0 .. 4294967295' (`InnoDB Plugin' only) The maximum delay between polls for a spin (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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. The default value is 6. This variable was added in MySQL 5.1.38. * `innodb_stats_method' Options for innodb_stats_method *Introduced* 5.1.56 *Command-Line `--innodb_stats_method=name' Format* *Option-File Format* `innodb_stats_method' *System Variable `innodb_stats_method' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `nulls_equal' *Valid Values* `nulls_equal' `nulls_unequal' `nulls_ignored' How the server treats `NULL' values when collecting statistics (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_statistics) about the distribution of index values for `InnoDB' 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 *Note myisam-index-statistics::. * `innodb_stats_on_metadata' Options for innodb_stats_on_metadata *Introduced* 5.1.17 *Command-Line `--innodb_stats_on_metadata' Format* *Option-File Format* `innodb_stats_on_metadata' *System Variable `innodb_stats_on_metadata' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `ON' When this variable is enabled (which is the default, as before the variable was created), `InnoDB' updates statistics (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_statistics) during metadata statements such as *Note `SHOW TABLE STATUS': show-table-status. or *Note `SHOW INDEX': show-index, or when accessing the `INFORMATION_SCHEMA' tables *Note `TABLES': tables-table. or *Note `STATISTICS': statistics-table. (These updates are similar to what happens for *Note `ANALYZE TABLE': analyze-table.) When disabled, `InnoDB' does not update statistics during these operations. Disabling this variable 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. This variable was added in MySQL 5.1.17. * `innodb_stats_sample_pages' Options for innodb_stats_sample_pages *Introduced* 5.1.38 *Command-Line `--innodb_stats_sample_pages=#' Format* *Option-File Format* `innodb_stats_sample_pages' *System Variable `innodb_stats_sample_pages' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `8' *Range* `1 .. 2**64-1' (`InnoDB Plugin' only) The number of index pages to sample for index distribution statistics (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_statistics) such as are calculated by *Note `ANALYZE TABLE': analyze-table. The default value is 8. For more information, see Ease of Use and Reliability. This variable was added in MySQL 5.1.38. * `innodb_strict_mode' Options for innodb_strict_mode *Introduced* 5.1.38 *Command-Line `--innodb_strict_mode=#' Format* *Option-File Format* `innodb_strict_mode' *System Variable `innodb_strict_mode' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' (`InnoDB Plugin' only) Whether `InnoDB' returns errors rather than warnings for certain conditions. This is analogous to strict SQL mode. The default value is `OFF'. See InnoDB Strict Mode (http://dev.mysql.com/doc/refman/5.5/en/innodb-other-changes-strict-mode.html) for a list of the conditions that are affected. This variable was added in MySQL 5.1.38. * `innodb_support_xa' Options for innodb_support_xa *Command-Line `--innodb_support_xa' Format* *Option-File Format* `innodb_support_xa' *System Variable `innodb_support_xa' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `TRUE' Enables `InnoDB' support for two-phase commit in XA (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_xa) transactions, causing an extra disk flush for transaction preparation. This setting is the default. 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 turn it off, transactions can be written to the binary log in a different order from the one in which the live database is committing them. This can produce different data when the binary log is replayed in disaster recovery or on a replication slave. Do not turn it off on a replication master server unless you have an unusual setup where only one thread is able to change data. For a server that is accepting data changes from only one thread, it is safe and recommended to turn off this option to improve performance for *Note `InnoDB': innodb-storage-engine. tables. For example, you can turn it off on replication slaves where only the replication SQL thread is changing data. You can also turn off this option if you do not need it for safe binary logging or replication, and you also do not use an external XA transaction manager. * `innodb_sync_spin_loops' Options for innodb_sync_spin_loops *Command-Line `--innodb_sync_spin_loops=#' Format* *Option-File Format* `innodb_sync_spin_loops' *System Variable `innodb_sync_spin_loops' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `20' *Range* `0 .. 4294967295' The number of times a thread waits for an `InnoDB' mutex to be freed before the thread is suspended. The default value is 20 for the built-in *Note `InnoDB': innodb-storage-engine, 30 for `InnoDB Plugin'. * `innodb_table_locks' Options for innodb_table_locks *Command-Line `--innodb_table_locks' Format* *Option-File Format* `innodb_table_locks' *System Variable `innodb_table_locks' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `TRUE' If `autocommit = 0', `InnoDB' honors *Note `LOCK TABLES': 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 *Note `LOCK TABLES': lock-tables. causes InnoDB to lock a table internally if `autocommit = 0'. * `innodb_thread_concurrency' Options for innodb_thread_concurrency *Command-Line `--innodb_thread_concurrency=#' Format* *Option-File Format* `innodb_thread_concurrency' *System Variable `innodb_thread_concurrency' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `8' *Range* `0 .. 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. Once the number of threads reaches this limit, additional threads are placed into a wait state within a FIFO queue for execution. Threads waiting for locks are not counted in the number of concurrently executing threads. The correct value for this variable is dependent on environment and workload. You will need to try a range of different values to determine what value works for your applications. A recommended value is 2 times the number of CPUs plus the number of disks. The range of this variable is 0 to 1000. A value of 20 or higher is interpreted as infinite concurrency before MySQL 5.1.12. From 5.1.12 on, you can disable thread concurrency checking by setting the value to 0. 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. The default value for the built-in *Note `InnoDB': innodb-storage-engine. is 20 before MySQL 5.1.11 and 8 from 5.1.11 on. The default for the `InnoDB Plugin' is 0. * `innodb_thread_sleep_delay' Options for innodb_thread_sleep_delay *Command-Line `--innodb_thread_sleep_delay=#' Format* *Option-File Format* `innodb_thread_sleep_delay' *System Variable `innodb_thread_sleep_delay' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `10000' How long `InnoDB' threads sleep before joining the `InnoDB' queue, in microseconds. The default value is 10,000. A value of 0 disables sleep. * `innodb_use_legacy_cardinality_algorithm' Options for innodb_use_legacy_cardinality_algorithm *Introduced* 5.1.35 *Command-Line `--innodb_use_legacy_cardinality_algorithm=#' Format* *Option-File Format* `innodb_use_legacy_cardinality_algorithm' *System Variable `innodb_use_legacy_cardinality_algorithm' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `ON' *Note `InnoDB': innodb-storage-engine. uses random numbers to generate dives into indexes for calculating index cardinality. However, under certain conditions, the algorithm does not generate random numbers, so *Note `ANALYZE TABLE': analyze-table. sometimes does not update cardinality estimates properly. An alternative algorithm was introduced in MySQL 5.1.35 with better randomization properties, and the `innodb_use_legacy_cardinality_algorithm', system variable which algorithm to use. The default value of the variable is 1 (`ON'), to use the original algorithm for compatibility with existing applications. The variable can be set to 0 (`OFF') to use the new algorithm with improved randomness. This variable is not used in `InnoDB Plugin' because the improved algorithm is used by default. Also, the number of random dives can be changed by modifying the `innodb_stats_sample_pages' system variable. * `innodb_use_sys_malloc' Options for innodb_use_sys_malloc *Introduced* 5.1.38 *Command-Line `--innodb_use_sys_malloc=#' Format* *Option-File Format* `innodb_use_sys_malloc' *System Variable `innodb_use_sys_malloc' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `ON' (`InnoDB Plugin' only) Whether `InnoDB' uses the operating system memory allocator (`ON') or its own (`OFF'). The default value is `ON'. This variable was added in MySQL 5.1.38. * `innodb_version' (`InnoDB Plugin' only) The *Note `InnoDB': innodb-storage-engine. version number. Starting in 5.1.68, the separate numbering for `InnoDB' is discontinued and this value is the same as for the `version' variable. This variable was added in MySQL 5.1.38. * `innodb_write_io_threads' Options for innodb_write_io_threads *Introduced* 5.1.38 *Command-Line `--innodb_write_io_threads=#' Format* *Option-File Format* `innodb_write_io_threads' *System Variable `innodb_write_io_threads' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `4' *Range* `1 .. 64' (`InnoDB Plugin' only) The number of I/O threads for write operations in `InnoDB'. The default value is 4. *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. This variable was added in MySQL 5.1.38. * `sync_binlog' Options for sync_binlog *Command-Line `--sync-binlog=#' Format* *Option-File Format* `sync_binlog' *System Variable `sync_binlog' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `0' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `0' *Range* `0 .. 18446744073709547520' If the value of this variable is greater than 0, the MySQL server synchronizes its binary log to disk (using `fdatasync()') after every `sync_binlog' writes to the binary log. There is one write to the binary log per statement if autocommit is enabled, and one write per transaction otherwise. The default value of `sync_binlog' is 0, which does no synchronizing to disk. A value of 1 is the safest choice, because in the event of a crash you lose at most one statement or transaction from the binary log. However, it is also the slowest choice (unless the disk has a battery-backed cache, which makes synchronization very fast).  File: manual.info, Node: using-innodb-tables, Next: innodb-data-log-reconfiguration, Prev: innodb-parameters, Up: innodb-storage-engine 14.6.3 Creating and Using `InnoDB' Tables ----------------------------------------- * Menu: * innodb-transactions-with-different-apis:: Using `InnoDB' with Different APIs * converting-tables-to-innodb:: Converting Tables from `MyISAM' to `InnoDB' * innodb-auto-increment-handling:: `AUTO_INCREMENT' Handling in `InnoDB' * innodb-foreign-key-constraints:: `InnoDB' and `FOREIGN KEY' Constraints * innodb-and-mysql-replication:: `InnoDB' and MySQL Replication To create an `InnoDB' table, specify an `ENGINE=InnoDB' option in the *Note `CREATE TABLE': create-table. statement: CREATE TABLE customers (a INT, b CHAR (20), INDEX (a)) ENGINE=InnoDB; The statement creates a table and an index on column `a' in the `InnoDB' tablespace that consists of the data files that you specified in `my.cnf'. In addition, MySQL creates a file `customers.frm' in the `test' directory under the MySQL database directory. Internally, `InnoDB' adds an entry for the table to its own data dictionary. The entry includes the database name. For example, if `test' is the database in which the `customers' table is created, the entry is for `'test/customers''. This means you can create a table of the same name `customers' in some other database, and the table names do not collide inside `InnoDB'. You can query the amount of free space in the `InnoDB' tablespace by issuing a *Note `SHOW TABLE STATUS': show-table-status. statement for any `InnoDB' table. The amount of free space in the tablespace appears in the `Data_free' section in the output of *Note `SHOW TABLE STATUS': show-table-status. (or the `Comment' section prior to MySQL 5.1.24). For example: SHOW TABLE STATUS FROM test LIKE 'customers' The statistics (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_statistics) *Note `SHOW': show. displays for `InnoDB' tables are only approximate. They are used in SQL optimization. Table and index reserved sizes in bytes are accurate, though.  File: manual.info, Node: innodb-transactions-with-different-apis, Next: converting-tables-to-innodb, Prev: using-innodb-tables, Up: using-innodb-tables 14.6.3.1 Using `InnoDB' with Different APIs ........................................... * Transactions in SQL * By default, each client that connects to the MySQL server begins with autocommit (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_autocommit) mode enabled, which automatically commits every SQL statement as you execute it. To use multiple-statement transactions, you can switch autocommit off with the SQL statement `SET autocommit = 0' and end each transaction with either *Note `COMMIT': commit. or *Note `ROLLBACK': commit. If you want to leave autocommit on, you can begin your transactions within *Note `START TRANSACTION': commit. and end them with *Note `COMMIT': commit. or *Note `ROLLBACK': commit. 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)) -> ENGINE=InnoDB; Query OK, 0 rows affected (0.00 sec) 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> 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> 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 *Note `COMMIT': commit. to the MySQL server as strings just like any other SQL statements such as *Note `SELECT': select. or *Note `INSERT': insert. Some APIs also offer separate special transaction commit and rollback functions or methods.  File: manual.info, Node: converting-tables-to-innodb, Next: innodb-auto-increment-handling, Prev: innodb-transactions-with-different-apis, Up: using-innodb-tables 14.6.3.2 Converting Tables from `MyISAM' to `InnoDB' .................................................... To convert a non-`InnoDB' table to use `InnoDB' use *Note `ALTER TABLE': alter-table.: ALTER TABLE TABLE_NAME ENGINE=InnoDB; *Important*: Do not convert MySQL system tables in the `mysql' database (such as `user' or `host') to the `InnoDB' type. This is an unsupported operation. The system tables must always be of the `MyISAM' type. `InnoDB' does not have a special optimization for separate index creation the way the `MyISAM' storage engine does. Therefore, it does not pay to export and import the table and create indexes afterward. The fastest way to alter a table to `InnoDB' is to do the inserts directly to an `InnoDB' table. That is, use `ALTER TABLE ... ENGINE=INNODB', or create an empty `InnoDB' table with identical definitions and insert the rows with `INSERT INTO ... SELECT * FROM ...'. 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 insert buffer (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_insert_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. To get better control over the insertion process, you might insert big tables in pieces: INSERT INTO newtable SELECT * FROM oldtable WHERE yourkey > SOMETHING AND yourkey <= SOMETHINGELSE; After all records have been 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 sizes of the `InnoDB' log files. Make sure that you do not fill up the tablespace: `InnoDB' tables require a lot more disk space than `MyISAM' tables. If an *Note `ALTER TABLE': 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 *Note forcing-innodb-recovery::. If you want all new user-created tables to use the `InnoDB' storage engine, add the line `default-storage-engine=innodb' to the `[mysqld]' section of your server option file.  File: manual.info, Node: innodb-auto-increment-handling, Next: innodb-foreign-key-constraints, Prev: converting-tables-to-innodb, Up: using-innodb-tables 14.6.3.3 `AUTO_INCREMENT' Handling in `InnoDB' .............................................. * Menu: * innodb-auto-increment-traditional:: Traditional `InnoDB' Auto-Increment Locking * innodb-auto-increment-configurable:: Configurable `InnoDB' Auto-Increment Locking Beginning with MySQL 5.1.22, `InnoDB' provides a locking strategy that significantly improves 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 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. This section provides background information on the original (`traditional') implementation of auto-increment locking in `InnoDB', explains the configurable locking mechanism, documents the parameter for configuring the mechanism, and describes its behavior and interaction with replication.  File: manual.info, Node: innodb-auto-increment-traditional, Next: innodb-auto-increment-configurable, Prev: innodb-auto-increment-handling, Up: innodb-auto-increment-handling 14.6.3.4 Traditional `InnoDB' Auto-Increment Locking .................................................... The original implementation of auto-increment handling in `InnoDB' uses the following strategy to prevent problems when using the binary log for statement-based replication or for certain recovery scenarios. 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. `InnoDB' uses the following algorithm to initialize the auto-increment counter for a table `t' that contains an `AUTO_INCREMENT' column named `ai_col': After a server startup, for the first insert into a table `t', `InnoDB' executes the equivalent of this statement: SELECT MAX(ai_col) FROM t 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 one. 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 *Note `SHOW TABLE STATUS': show-table-status. statement examines the table `t' before the auto-increment counter is initialized, `InnoDB' initializes but does not increment the value and stores it 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 freshly 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 bigger than the current counter value, the counter is set to the specified column value. If a user specifies `NULL' or `0' for the `AUTO_INCREMENT' column in an *Note `INSERT': insert, `InnoDB' treats the row as if the value was not specified and generates a new value for it. The behavior of the auto-increment mechanism is not defined if you assign a negative value to the column, or if the value becomes bigger than the maximum integer that can be stored in the specified integer type. When accessing the auto-increment counter, `InnoDB' uses a special table-level `AUTO-INC' lock that it keeps to the end of the current SQL statement, not to the end of the transaction. The special lock release strategy was introduced to improve concurrency for inserts into a table containing an `AUTO_INCREMENT' column. Nevertheless, two transactions cannot have the `AUTO-INC' lock on the same table simultaneously, which can have a performance impact if the `AUTO-INC' lock is held for a long time. That might be the case for a statement such as `INSERT INTO t1 ... SELECT ... FROM t2' that inserts all rows from one table into another. `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 *Note `INSERT': insert. to the table, as described earlier. A server restart also cancels the effect of the `AUTO_INCREMENT = N' table option in *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': alter-table. statements, which you can use with `InnoDB' tables to set the initial counter value or alter the current counter value. You may see gaps in the sequence of values assigned to the `AUTO_INCREMENT' column if you roll back transactions that have generated numbers using the counter.  File: manual.info, Node: innodb-auto-increment-configurable, Prev: innodb-auto-increment-traditional, Up: innodb-auto-increment-handling 14.6.3.5 Configurable `InnoDB' Auto-Increment Locking ..................................................... As described in the previous section, `InnoDB' uses a special lock called the 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 numbers are assigned in a predictable and repeatable order for a given sequence of *Note `INSERT': insert. statements. 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 *Note `INSERT': insert. statements is deterministic, and the slave reproduces the same data as on the master. If auto-increment values generated by multiple *Note `INSERT': insert. statements were interleaved, the result of two concurrent *Note `INSERT': 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 *Note `INSERT ... SELECT': insert-select. statement that inserts 1000 rows, and another is using a simple *Note `INSERT': 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 will be retrieved from the *Note `SELECT': select. in the *Note `INSERT': 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 *Note `INSERT': 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 *Note `INSERT ... SELECT': insert-select. statement will be consecutive, and the (single) auto-increment value used by the *Note `INSERT': insert. statement in Tx2 will 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 will be the same as they were when Tx1 and Tx2 first ran. Thus, table-level locks held until the end of a statement make *Note `INSERT': insert. statements using auto-increment safe for use with statement-based replication. However, those 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 *Note `INSERT': insert. in Tx2 depends on precisely when the statement executes. If the *Note `INSERT': insert. of Tx2 executes while the *Note `INSERT': insert. of Tx1 is running (rather than before it starts or after it completes), the specific auto-increment values assigned by the two *Note `INSERT': insert. statements are nondeterministic, and may vary from run to run. As of MySQL 5.1.22, `InnoDB' can avoid using the table-level `AUTO-INC' lock for a class of *Note `INSERT': insert. statements where the number of rows is known in advance, and still preserve deterministic execution and safety for statement-based replication. Further, if you are not using the binary log to replay SQL statements as part of recovery or replication, you can entirely eliminate use of the table-level `AUTO-INC' lock 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. For *Note `INSERT': insert. statements where the number of rows to be inserted is known at the beginning of processing the statement, `InnoDB' quickly allocates the required number of auto-increment values without taking any lock, but only if there is no concurrent session already holding the table-level `AUTO-INC' lock (because that other statement will be allocating auto-increment values one-by-one as it proceeds). More precisely, such an *Note `INSERT': insert. statement obtains auto-increment values under the control of a mutex (a light-weight lock) that is _not_ held until the statement completes, but only for the duration of the allocation process. This new locking scheme enables much greater scalability, but it does introduce some subtle differences in how auto-increment values are assigned compared to the original mechanism. To describe the way auto-increment works in `InnoDB', the following discussion defines some terms, and explains how `InnoDB' behaves using different settings of the `innodb_autoinc_lock_mode' configuration parameter, which you can set at server startup as of MySQL 5.1.22. Additional considerations are described following the explanation of auto-increment locking behavior. First, some definitions: * `*Note `INSERT': insert.-like' statements All statements that generate new rows in a table, including *Note `INSERT': insert, *Note `INSERT ... SELECT': insert-select, *Note `REPLACE': replace, *Note `REPLACE ... SELECT': replace, and *Note `LOAD DATA': load-data. * `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 *Note `INSERT': insert. and *Note `REPLACE': replace. statements that do not have a nested subquery, but not *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. * `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 *Note `INSERT ... SELECT': insert-select, *Note `REPLACE ... SELECT': replace, and *Note `LOAD DATA': load-data. statements, but not plain `INSERT'. `InnoDB' will assign 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 *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate, which in the worst case is in effect an *Note `INSERT': insert. followed by a *Note `UPDATE': 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' parameter: * `innodb_autoinc_lock_mode = 0' (`traditional' lock mode) This lock mode provides the same behavior as before `innodb_autoinc_lock_mode' existed. For all `*Note `INSERT': insert.-like' statements, a special table-level `AUTO-INC' lock is obtained and held to the end of the statement. This assures that the auto-increment values assigned by any given statement are consecutive. This lock mode is provided for: * Backward compatibility. * Performance testing. * Working around issues with `mixed-mode inserts', due to the possible differences in semantics described later. * `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 *Note `INSERT ... SELECT': insert-select, *Note `REPLACE ... SELECT': replace, and *Note `LOAD DATA': load-data. statements. Only one statement holding the `AUTO-INC' lock can execute at a time. With this lock mode, `simple inserts' (only) use a new locking model where a light-weight mutex is used during the allocation of auto-increment values, and no table-level `AUTO-INC' lock is used, unless an `AUTO-INC' lock is held by another transaction. If another transaction does hold an `AUTO-INC' lock, a `simple insert' waits for the `AUTO-INC' lock, as if it too were a `bulk insert'. This lock mode ensures that, in the presence of *Note `INSERT': 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 `*Note `INSERT': insert.-like' statement are consecutive, and operations are safe for statement-based replication. Simply put, the important impact of this lock mode is significantly better scalability. This mode is safe for use with statement-based replication. Further, as with `traditional' lock mode, auto-increment numbers assigned by any given statement are _consecutive_. In this mode, 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' will allocate 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 `*Note `INSERT': 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 `*Note `INSERT': 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 will be 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. The auto-increment locking modes provided by `innodb_autoinc_lock_mode' have several 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 replication, all of the auto-increment lock modes are safe. Row-based replication is not sensitive to the order of execution of the SQL statements. * `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 `*Note `INSERT': 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. * 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 will be 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 `*Note `INSERT': 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 will behave 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. Consider the following `mixed-mode insert' statement: 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 will be: +-----+------+ | c1 | c2 | +-----+------+ | 1 | a | | 101 | b | | 5 | c | | 102 | d | +-----+------+ The next available auto-increment value will be 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 `*Note `INSERT': insert.-like' statements (of any type). With `innodb_autoinc_lock_mode' set to 1 (`consecutive'), the four new rows will also be: +-----+------+ | c1 | c2 | +-----+------+ | 1 | a | | 101 | b | | 5 | c | | 102 | d | +-----+------+ However, in this case, the next available auto-increment value will be 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 `*Note `INSERT': insert.-like' statements (of any type). With `innodb_autoinc_lock_mode' set to mode 2 (`interleaved'), the four new rows will be: +-----+------+ | c1 | c2 | +-----+------+ | 1 | a | | X | b | | 5 | c | | Y | d | +-----+------+ The values of X and Y will be unique and larger than any previously generated rows. However, the specific values of X and Y will 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 was the value 4: INSERT INTO t1 (c1,c2) VALUES (1,'a'), (NULL,'b'), (5,'c'), (NULL,'d'); With any `innodb_autoinc_lock_mode' setting, this statement will generate a duplicate-key error 23000 (`Can't write; duplicate key in table') because 5 will be allocated for the row `(NULL, 'b')' and insertion of the row `(5, 'c')' will fail.  File: manual.info, Node: innodb-foreign-key-constraints, Next: innodb-and-mysql-replication, Prev: innodb-auto-increment-handling, Up: using-innodb-tables 14.6.3.6 `InnoDB' and `FOREIGN KEY' Constraints ............................................... This section describes differences in the InnoDB storage engine' handling of foreign keys as compared with that of the MySQL Server. * 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. * *Note `InnoDB': innodb-storage-engine. 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 non-unique 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'. *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': 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 will be impossible, such as deleting a record that refers to itself using a foreign key. * Foreign Key Usage and Error Information * You can obtain general information about foreign keys and their usage from querying the *Note `INFORMATION_SCHEMA.KEY_COLUMN_USAGE': key-column-usage-table. table, and more information more specific to `InnoDB' tables can be found in the `INNODB_SYS_FOREIGN' (http://dev.mysql.com/doc/refman/5.6/en/innodb-sys-foreign-table.html) and `INNODB_SYS_FOREIGN_COLS' (http://dev.mysql.com/doc/refman/5.6/en/innodb-sys-foreign-cols-table.html) tables, also in the `INFORMATION_SCHEMA' database. See also *Note create-table-foreign-keys::. In addition to *Note `SHOW ERRORS': 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 *Note `SHOW ENGINE INNODB STATUS': show-engine.  File: manual.info, Node: innodb-and-mysql-replication, Prev: innodb-foreign-key-constraints, Up: using-innodb-tables 14.6.3.7 `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. To set up a new slave for a master, make a copy of the `InnoDB' tablespace and the log files, as well as the `.frm' files of the `InnoDB' tables, and move the copies to the slave. If the `innodb_file_per_table' option is enabled, copy the `.ibd' files as well. For the proper procedure to do this, see *Note innodb-backup::. To make a new slave without taking down the master or an existing slave, use the *Note MySQL Enterprise Backup: mysql-enterprise-backup. product. If you can shut down the master or an existing slave, take a cold backup (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_cold_backup) of the `InnoDB' tablespaces and log files and use that to set up a slave. You cannot set up replication for `InnoDB' using the *Note `LOAD TABLE FROM MASTER': load-table-from-master. statement, which works only for `MyISAM' tables. There are two possible workarounds: * Dump the table on the master and import the dump file into the slave. * Use `ALTER TABLE TBL_NAME ENGINE=MyISAM' on the master before setting up replication with `LOAD TABLE TBL_NAME FROM MASTER', and then use *Note `ALTER TABLE': alter-table. to convert the master table back to `InnoDB' afterward. However, this should not be done for tables that have foreign key definitions because the definitions will be lost. 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 *Note 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 *Note `CREATE TABLE': 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 *Note `DELETE': 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 *Note `DELETE': 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.  File: manual.info, Node: innodb-data-log-reconfiguration, Next: innodb-backup, Prev: using-innodb-tables, Up: innodb-storage-engine 14.6.4 Adding, Removing, or Resizing `InnoDB' Data and Log Files ---------------------------------------------------------------- This section describes what you can do when your `InnoDB' system tablespace (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_system_tablespace) runs out of room or when you want to change the size of the redo log (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_redo_log) files. 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 8MB 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. Alternatively, you can increase the size of your tablespace by adding another data file. To do this, you have to shut down the MySQL server, change the tablespace configuration to add a new data file to the end of `innodb_data_file_path', and start the server again. If your last data file was defined with the keyword `autoextend', the procedure for reconfiguring the tablespace must take into account the size to which the last data file has grown. Obtain the size of the data file, round it down to the closest multiple of 1024 x 1024 bytes (= 1MB), and specify the rounded size explicitly in `innodb_data_file_path'. Then you can add another data file. Remember that only the last data file in the `innodb_data_file_path' can be specified as auto-extending. 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. Currently, you cannot remove a data file from the tablespace. To decrease the size of your tablespace, use this procedure: 1. Use *Note `mysqldump': mysqldump. to dump all your `InnoDB' tables. 2. Stop the server. 3. Remove all the existing tablespace files, including the `ibdata' and `ib_log' files. If you want to keep a backup copy of the information, then copy all the `ib*' files to another location before the removing the files in your MySQL installation. 4. Remove any `.frm' files for `InnoDB' tables. 5. Configure a new tablespace. 6. Restart the server. 7. Import the dump files. If you want to change the number or the size of your `InnoDB' log files, use the following instructions. The procedure to use depends on the value of `innodb_fast_shutdown': * If `innodb_fast_shutdown' is not set to 2: Stop the MySQL server and make sure that it shuts down without errors (to ensure that there is no information for outstanding transactions in the log). Copy the old log files into a safe place in case something went wrong during the shutdown and you need them to recover the tablespace. Delete the old log files from the log file directory, edit `my.cnf' to change the log file configuration, and start the MySQL server again. *Note `mysqld': mysqld. sees that no *Note `InnoDB': innodb-storage-engine. log files exist at startup and creates new ones. * If `innodb_fast_shutdown' is set to 2: Set `innodb_fast_shutdown' to 1: mysql> SET GLOBAL innodb_fast_shutdown = 1; Then follow the instructions in the previous item.  File: manual.info, Node: innodb-backup, Next: innodb-migration, Prev: innodb-data-log-reconfiguration, Up: innodb-storage-engine 14.6.5 Backing Up and Recovering an `InnoDB' Database ----------------------------------------------------- * Menu: * innodb-recovery:: The `InnoDB' Recovery Process * forcing-innodb-recovery:: Forcing `InnoDB' Recovery * innodb-checkpoints:: `InnoDB' Checkpoints 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 techniques, alone or in combination: hot backup (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_hot_backup) with MySQL Enterprise Backup; cold backup (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_cold_backup) by copying files while the MySQL server is shut down; physical backup (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_physical_backup) for fast operation (especially for restore); logical backup (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_logical_backup) with *Note `mysqldump': mysqldump. for smaller data volumes or to record the structure of schema objects. * Hot Backups * The `mysqlbackup' command, part of the MySQL Enterprise Backup component, lets you back up a running MySQL instance, including `InnoDB' and *Note `MyISAM': myisam-storage-engine. tables, with minimal disruption to operations while producing a consistent snapshot of the database. When `mysqlbackup' is copying `InnoDB' tables, reads and writes to both `InnoDB' and `MyISAM' tables can continue. During the copying of `MyISAM' tables, reads (but not writes) to those tables are permitted. MySQL Enterprise Backup can also create compressed backup files, and back up subsets of tables and databases. In conjunction with MySQL's binary log, users can perform point-in-time recovery. MySQL Enterprise Backup is part of the MySQL Enterprise subscription. For more details, see *Note mysql-enterprise-backup::. * Cold Backups * If you can shut down your MySQL server, you can make a binary backup that consists of all files used by `InnoDB' to manage its tables. Use the following procedure: 1. Do a slow shutdown (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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. * Alternative Backup Types * In addition to making binary backups as just described, regularly make dumps of your tables with *Note `mysqldump': 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. *Note `mysqldump': mysqldump. also has a `--single-transaction' option for making a consistent snapshot without locking out other clients. See *Note backup-policy::. Replication works with *Note `InnoDB': innodb-storage-engine. tables, so you can use MySQL replication capabilities to keep a copy of your database at database sites requiring high availability. * Performing Recovery * To recover your `InnoDB' database to the present from the time at which the binary backup was made, you must run your MySQL server with binary logging turned on, 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 *Note point-in-time-recovery::. To recover from a crash of your MySQL server, the only requirement is to restart it. `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, *Note `mysqld': mysqld. displays output something like this: 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 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 *Note `mysqlbinlog': mysqlbinlog. and *Note `mysql': mysql. to restore the changes that occurred after the backup was made. In some cases of database corruption, it is enough just to dump, drop, and re-create one or a few corrupt tables. You can use the *Note `CHECK TABLE': check-table. SQL statement to check whether a table is corrupt, although *Note `CHECK TABLE': check-table. naturally cannot detect every possible kind of corruption. You can use the Tablespace Monitor to check the integrity of the file space management inside the tablespace files. 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 first to try restarting your computer. Doing so may eliminate errors that appeared to be database page corruption. If MySQL still has trouble starting because of `InnoDB' consistency problems, see *Note forcing-innodb-recovery:: for steps to start the instance in a diagnostic mode where you can dump the data.  File: manual.info, Node: innodb-recovery, Next: forcing-innodb-recovery, Prev: innodb-backup, Up: innodb-backup 14.6.5.1 The `InnoDB' Recovery Process ...................................... `InnoDB' crash recovery consists of several steps. The first step, redo log application, is performed during the initialization, before accepting any connections. If all changes were flushed from the buffer pool to the tablespaces (`ibdata*' and `*.ibd' files) at the time of the shutdown or crash, the redo log application can be skipped. If the redo log files are missing at startup, `InnoDB' skips the redo log application. The remaining steps after redo log application do not depend on the redo log (other than for logging the writes) and are performed in parallel with normal processing. These include: * Rolling back incomplete transactions: Any transactions that were active at the time of crash or fast shutdown. * Insert buffer merge: Applying changes from the insert buffer tree (from the shared 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 for any active transaction. Of these, only rollback of incomplete transactions is special to crash recovery. The insert buffer merge and the purge are performed during normal processing.  File: manual.info, Node: forcing-innodb-recovery, Next: innodb-checkpoints, Prev: innodb-recovery, Up: innodb-backup 14.6.5.2 Forcing `InnoDB' Recovery .................................. If there is database page corruption, you may want to dump your tables from the database with *Note `SELECT ... INTO OUTFILE': select-into. Usually, most of the data obtained in this way is intact. However, it is possible that the 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 = 4 `innodb_force_recovery' is 0 by default (normal startup without forced recovery). The permissible nonzero values for `innodb_force_recovery' follow. A larger number includes all precautions of smaller numbers. If you can dump your tables with an option value of at most 4, then you are relatively safe that only some data on corrupt individual pages is lost. A value of 6 is more drastic because database pages are left in an obsolete state, which in turn may introduce more corruption into B-trees and other database structures. * `1' (`SRV_FORCE_IGNORE_CORRUPT') Let the server run even if it detects a corrupt page (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_page). Try to make `SELECT * FROM TBL_NAME' jump over corrupt index records and pages, which helps in dumping tables. * `2' (`SRV_FORCE_NO_BACKGROUND') Prevent the master thread (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_master_thread) from running. If a crash would occur during the purge (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_purge) operation, this recovery value prevents it. * `3' (`SRV_FORCE_NO_TRX_UNDO') Do not run transaction rollbacks (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_rollback) after crash recovery (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_crash_recovery). * `4' (`SRV_FORCE_NO_IBUF_MERGE') Prevent insert buffer (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_insert_buffer) merge operations. If they would cause a crash, do not do them. Do not calculate table statistics (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_statistics). * `5' (`SRV_FORCE_NO_UNDO_LOG_SCAN') Do not look at undo logs (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_undo_log) when starting the database: `InnoDB' treats even incomplete transactions as committed. * `6' (`SRV_FORCE_NO_LOG_REDO') Do not do the redo log (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_redo_log) roll-forward in connection with recovery. With this value, you might not be able to do queries other than a basic `SELECT * FROM t', with no `WHERE', `ORDER BY', or other clauses. More complex queries could encounter corrupted data structures and fail. 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. _The database must not otherwise be used with any nonzero value of `innodb_force_recovery'_. As a safety measure, `InnoDB' prevents users from performing *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': delete. operations when `innodb_force_recovery' is greater than 0. You can *Note `SELECT': select. from tables to dump them, or `DROP' or `CREATE' tables even if forced recovery is used. If you know that a given table is causing a crash on rollback, you can drop it. You can also use this to stop a runaway rollback caused by a failing mass import or *Note `ALTER TABLE': alter-table. You can kill the *Note `mysqld': mysqld. process and set `innodb_force_recovery' to `3' to bring the database up without the rollback, then `DROP' the table that is causing the runaway rollback.  File: manual.info, Node: innodb-checkpoints, Prev: forcing-innodb-recovery, Up: innodb-backup 14.6.5.3 `InnoDB' Checkpoints ............................. `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 in practice stop 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. `InnoDB' writes to its log files on a rotating basis. It also writes checkpoint information to the first log file at each checkpoint. All committed modifications that make the database pages in the buffer pool different from the images on disk must be available in the log files in case `InnoDB' has to do a recovery. This means that when `InnoDB' starts to reuse a log file, it has to make sure that the database page images on disk contain the modifications logged in the log file that `InnoDB' is going to reuse. In other words, `InnoDB' must create a checkpoint and this often involves flushing of modified database pages to disk. The preceding description explains why making your log files very large may reduce disk I/O in checkpointing. It often makes sense to set the total size of the log files as large as the buffer pool or even larger. The disadvantage of using large log files is that crash recovery can take longer because there is more logged information to apply to the database.  File: manual.info, Node: innodb-migration, Next: innodb-transaction-model, Prev: innodb-backup, Up: innodb-storage-engine 14.6.6 Moving or Copying `InnoDB' Tables to Another Machine ----------------------------------------------------------- This section explains various techniques for moving or copying some or all `InnoDB' tables to a different server. 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 server to development 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 Like `MyISAM' data files, `InnoDB' data and log files are binary-compatible on all platforms having the same floating-point number format. You can move an `InnoDB' database simply by copying all the relevant files listed in *Note innodb-backup::. If the floating-point formats differ but you have not used *Note `FLOAT': floating-point-types. or *Note `DOUBLE': floating-point-types. data types in your tables, then the procedure is the same: simply copy the relevant files. If you use *Note `mysqldump': mysqldump. to dump your tables on one machine and then import the dump files on the other machine, it does not matter whether the formats differ or your tables contain floating-point data. One way to increase performance 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.  File: manual.info, Node: innodb-transaction-model, Next: innodb-multi-versioning, Prev: innodb-migration, Up: innodb-storage-engine 14.6.7 The `InnoDB' Transaction Model and Locking ------------------------------------------------- * Menu: * innodb-lock-modes:: `InnoDB' Lock Modes * innodb-consistent-read:: Consistent Nonlocking Reads * innodb-locking-reads:: `SELECT ... FOR UPDATE' and `SELECT ... LOCK IN SHARE MODE' Locking Reads * innodb-record-level-locks:: `InnoDB' Record, Gap, and Next-Key Locks * innodb-next-key-locking:: Avoiding the Phantom Problem Using Next-Key Locking * innodb-locks-set:: Locks Set by Different SQL Statements in `InnoDB' * innodb-implicit-commit:: Implicit Transaction Commit and Rollback * innodb-deadlock-detection:: Deadlock Detection and Rollback * innodb-deadlocks:: How to Cope with Deadlocks To implement a large-scale, busy, or highly reliable database application, to port substantial code from a different database system, or to push MySQL performance to the limits of the laws of physics, you must understand the notions of transactions (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction) and locking (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_locking) as they relate to the InnoDB storage engine. In the `InnoDB' transaction model, the goal is to combine the best properties of a multi-versioning database with traditional two-phase locking. `InnoDB' does locking on the row level and runs queries as nonlocking consistent reads by default, in the style of Oracle. The lock information in `InnoDB' is stored so space-efficiently 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. 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 *Note innodb-error-handling::. A session that has autocommit enabled can perform a multiple-statement transaction by starting it with an explicit *Note `START TRANSACTION': commit. or *Note `BEGIN': commit. statement and ending it with a *Note `COMMIT': commit. or *Note `ROLLBACK': commit. statement. See *Note commit::. If autocommit mode is disabled within a session with `SET autocommit = 0', the session always has a transaction open. A *Note `COMMIT': commit. or *Note `ROLLBACK': commit. statement ends the current transaction and a new one starts. A *Note `COMMIT': commit. means that the changes made in the current transaction are made permanent and become visible to other sessions. A *Note `ROLLBACK': commit. statement, on the other hand, cancels all modifications made by the current transaction. Both *Note `COMMIT': commit. and *Note `ROLLBACK': commit. release all `InnoDB' locks that were set during the current transaction. In terms of the SQL:1992 transaction isolation levels, the default `InnoDB' level is `REPEATABLE READ'. `InnoDB' offers all four transaction isolation levels described by the SQL standard: `READ UNCOMMITTED', `READ COMMITTED', `REPEATABLE READ', and `SERIALIZABLE'. A user can change the isolation level for a single session or for all subsequent connections with the *Note `SET TRANSACTION': 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 *Note set-transaction::. In row-level locking, `InnoDB' normally uses next-key locking. That means that besides index records, `InnoDB' can also lock the `gap' preceding an index record to block insertions by other sessions in the gap immediately before the index record. A next-key lock refers to a lock that locks an index record and the gap before it. A gap lock refers to a lock that locks only the gap before some index record. For more information about row-level locking, and the circumstances under which gap locking is disabled, see *Note innodb-record-level-locks::.  File: manual.info, Node: innodb-lock-modes, Next: innodb-consistent-read, Prev: innodb-transaction-model, Up: innodb-transaction-model 14.6.7.1 `InnoDB' Lock Modes ............................ `InnoDB' implements standard row-level locking where there are two types of locks, shared (S) locks (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_shared_lock) and exclusive (X) locks (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_exclusive_lock). For information about record, gap, and next-key lock types, see *Note innodb-record-level-locks::. * A shared (S) lock permits a transaction to read a row. * An exclusive (X) lock permits a transaction 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 * Additionally, `InnoDB' supports _multiple granularity locking_ which permits coexistence of record locks and locks on entire tables. To make locking at multiple granularity levels practical, additional types of locks called _intention locks_ are used. Intention locks are table locks in `InnoDB'. The idea behind intention locks is for a transaction to indicate which type of lock (shared or exclusive) it will require later for a row in that table. There are two types of intention locks used in `InnoDB' (assume that transaction `T' has requested a lock of the indicated type on table `t'): * Intention shared (IS): Transaction `T' intends to set S locks on individual rows in table `t'. * Intention exclusive (IX): Transaction `T' intends to set X locks on those rows. For example, *Note `SELECT ... LOCK IN SHARE MODE': select. sets an IS lock and *Note `SELECT ... FOR UPDATE': select. sets an IX lock. The intention locking protocol is as follows: * Before a transaction can acquire an S lock on a row in table `t', it must first acquire an IS or stronger lock on `t'. * Before a transaction can acquire an X lock on a row, it must first acquire an IX lock on `t'. These rules can be conveniently summarized by means of the following _lock type compatibility matrix_. Compatibility matrix showing which combinations of lock types X, IX, S, and IS are allowed. Each cell in the matrix is marked as either "Compatible" or "Conflict". 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. Thus, intention locks do not block anything except full table requests (for example, `LOCK TABLES ... WRITE'). The main purpose of IX and IS locks is to show that someone is locking a row, or going to lock a row in the table. * 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 | +------+ 1 row in set (0.10 sec) 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. *Note*: 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, which is defined by `LOCK_MAX_DEPTH_IN_DEADLOCK_CHECK'. 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 the transactions on the wait-for list. The limit of 1,000,000 locks is defined by `LOCK_MAX_N_STEPS_IN_DEADLOCK_CHECK'.  File: manual.info, Node: innodb-consistent-read, Next: innodb-locking-reads, Prev: innodb-lock-modes, Up: innodb-transaction-model 14.6.7.2 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 *Note `SELECT': 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 *Note `SELECT': 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 *Note `SELECT': 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 *Note `SELECT': select. statements within a transaction, not necessarily to DML (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_dml) statements. If you insert or modify some rows and then commit that transaction, a *Note `DELETE': delete. or *Note `UPDATE': 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 *Note `SELECT': select. or *Note `START TRANSACTION WITH CONSISTENT SNAPSHOT': commit. 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 | --------------------- 1 row in set 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 LOCK IN SHARE MODE; 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 *Note innodb-locking-reads::). Consistent read does not work over certain DDL statements: * Consistent read does not work over *Note `DROP TABLE': drop-table, because MySQL cannot use a table that has been dropped and `InnoDB' destroys the table. * Consistent read does not work over *Note `ALTER TABLE': 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. The type of read varies for selects in clauses like *Note `INSERT INTO ... SELECT': insert, *Note `UPDATE ... (SELECT)': update, and *Note `CREATE TABLE ... SELECT': create-table. that do not specify `FOR UPDATE' or `LOCK IN SHARE MODE': * By default, `InnoDB' uses stronger locks and the *Note `SELECT': 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.  File: manual.info, Node: innodb-locking-reads, Next: innodb-record-level-locks, Prev: innodb-consistent-read, Up: innodb-transaction-model 14.6.7.3 `SELECT ... FOR UPDATE' and `SELECT ... LOCK IN SHARE MODE' 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: * *Note `SELECT ... LOCK IN SHARE MODE': select. 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. * *Note `SELECT ... FOR UPDATE': select. 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 *Note `SELECT ... LOCK IN SHARE MODE': select, 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. 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 *Note `START TRANSACTION': commit. or by setting `autocommit' to 0. If autocommit is enabled, the rows matching the specification are not locked. * Usage 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 *Note `SELECT': 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 read or write to the applicable row in the `PARENT' table waits until you are finished, that is, 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. Here are two ways to implement reading and incrementing the counter without interference from another transaction: * First update the counter by incrementing it by 1, then read it and use the new value in the `CHILD' table. Any other transaction that tries to read the counter waits until your transaction commits. If another transaction is in the middle of this same sequence, your transaction waits until the other one commits. * First perform a locking read of the counter using `FOR UPDATE', and then increment the counter: SELECT counter_field FROM child_codes FOR UPDATE; UPDATE child_codes SET counter_field = counter_field + 1; A *Note `SELECT ... FOR UPDATE': select. reads the latest available data, setting exclusive locks on each row it reads. Thus, it sets the same locks a searched SQL *Note `UPDATE': update. would set on the rows. The preceding description is merely an example of how *Note `SELECT ... FOR UPDATE': select. 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 *Note `SELECT': select. statement merely retrieves the identifier information (specific to the current connection). It does not access any table.  File: manual.info, Node: innodb-record-level-locks, Next: innodb-next-key-locking, Prev: innodb-locking-reads, Up: innodb-transaction-model 14.6.7.4 `InnoDB' Record, Gap, and Next-Key Locks ................................................. `InnoDB' has several types of record-level locks including record locks, gap locks, and next-key locks. For information about shared locks, exclusive locks, and intention locks, see *Note innodb-lock-modes::. * Record lock: This is a lock on an index record. * Gap lock: This is a lock on a gap between index records, or a lock on the gap before the first or after the last index record. * Next-key lock: This is a combination of a record lock on the index record and a gap lock on the gap before the index record. * Record Locks * 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 *Note innodb-index-types::. * Next-key Locks * By default, `InnoDB' operates in `REPEATABLE READ' transaction isolation level and with the `innodb_locks_unsafe_for_binlog' system variable disabled. In this case, `InnoDB' uses next-key locks for searches and index scans, which prevents phantom rows (see *Note innodb-next-key-locking::). Next-key locking 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. 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 `(' or `)' denote exclusion of the interval endpoint and `[' or `]' denote 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. * Gap Locks * The next-key locking example in the previous section shows that a gap might span a single index value, multiple index values, or even be empty. 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. A type of gap lock called an insertion intention gap lock is set by *Note `INSERT': 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 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. For more information about intention locks, see *Note innodb-lock-modes::. 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. Thus, a gap X-lock has the same effect as a gap S-lock. * Disabling Gap Locking * 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. 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 *Note `UPDATE': update.  File: manual.info, Node: innodb-next-key-locking, Next: innodb-locks-set, Prev: innodb-record-level-locks, Up: innodb-transaction-model 14.6.7.5 Avoiding the Phantom Problem Using Next-Key Locking ............................................................ 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 *Note `SELECT': 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 *Note `SELECT': 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 *Note innodb-record-level-locks::. This may cause phantom problems because other sessions can insert new rows into the gaps when gap locking is disabled.  File: manual.info, Node: innodb-locks-set, Next: innodb-implicit-commit, Prev: innodb-next-key-locking, Up: innodb-transaction-model 14.6.7.6 Locks Set by Different SQL Statements in `InnoDB' .......................................................... A locking read, an *Note `UPDATE': update, or a *Note `DELETE': 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 *Note innodb-record-level-locks::. The transaction isolation level also can affect which locks are set; see *Note set-transaction::. 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 *Note innodb-lock-modes::. 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 *Note `SELECT ... FOR UPDATE': select. or *Note `SELECT ... LOCK IN SHARE MODE': select, 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 *Note `UNION': 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. * *Note `SELECT ... FROM': select. 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. * *Note `SELECT ... FROM ... LOCK IN SHARE MODE': select. sets shared next-key locks on all index records the search encounters. * For index records the search encounters, *Note `SELECT ... FROM ... FOR UPDATE': select. blocks other sessions from doing *Note `SELECT ... FROM ... LOCK IN SHARE MODE': select. or from reading in certain transaction isolation levels. Consistent reads will ignore any locks set on the records that exist in the read view. * *Note `UPDATE ... WHERE ...': update. sets an exclusive next-key lock on every record the search encounters. * *Note `DELETE FROM ... WHERE ...': delete. sets an exclusive next-key lock on every record the search encounters. * *Note `INSERT': 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 insertion 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. * *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. differs from a simple *Note `INSERT': insert. in that an exclusive next-key lock rather than a shared lock is placed on the row to be updated when a duplicate-key error occurs. * *Note `REPLACE': replace. is done like an *Note `INSERT': 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 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. *Note `CREATE TABLE ... SELECT ...': create-table. performs the *Note `SELECT': select. with shared next-key locks or as a consistent read, as for *Note `INSERT ... SELECT': 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 *Note 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. * *Note `LOCK TABLES': 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 *Note innodb-deadlock-detection::. See also *Note innodb-restrictions::.  File: manual.info, Node: innodb-implicit-commit, Next: innodb-deadlock-detection, Prev: innodb-locks-set, Up: innodb-transaction-model 14.6.7.7 Implicit Transaction Commit and Rollback ................................................. By default, MySQL starts the session for each new connection with autocommit mode 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 *Note innodb-error-handling::. 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 *Note `COMMIT': commit. before executing the statement. For details, see *Note implicit-commit::.  File: manual.info, Node: innodb-deadlock-detection, Next: innodb-deadlocks, Prev: innodb-implicit-commit, Up: innodb-transaction-model 14.6.7.8 Deadlock Detection and Rollback ........................................ `InnoDB' automatically detects transaction deadlocks (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_deadlock) 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 *Note `LOCK TABLES': 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. As of MySQL 5.1.24, if a *Note `SELECT': select. calls a stored function in a transaction, and a statement within the function fails, that statement rolls back. Furthermore, if *Note `ROLLBACK': commit. is executed after that, the entire transaction rolls back. Before 5.1.24, the failed statement did not roll back when it failed (even though it might ultimately get rolled back by a *Note `ROLLBACK': commit. later that rolls back the entire transaction). For techniques to organize database operations to avoid deadlocks, see *Note innodb-deadlocks::.  File: manual.info, Node: innodb-deadlocks, Prev: innodb-deadlock-detection, Up: innodb-transaction-model 14.6.7.9 How to Cope with Deadlocks ................................... This section builds on the conceptual information about deadlocks in *Note innodb-deadlock-detection::. It explains how to organize database operations to minimize deadlocks and the subsequent error handling required in applications. Deadlocks (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_deadlock) 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: * Use *Note `SHOW ENGINE INNODB STATUS': show-engine. to determine the cause of the latest deadlock. That can help you to tune your application to avoid deadlocks. * Always be prepared to re-issue a transaction if it fails due to deadlock. Deadlocks are not dangerous. Just try again. * Commit your transactions immediately after making a set of related changes. Small transactions are less prone to collision. In particular, do not leave an interactive *Note `mysql': mysql. session open for a long time with an uncommitted transaction. * If you are using locking reads (*Note `SELECT ... FOR UPDATE': select. 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 *Note `EXPLAIN SELECT': explain. 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 *Note `SELECT': 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 *Note `LOCK TABLES': lock-tables. with transactional tables, such as `InnoDB' tables, is to begin a transaction with `SET autocommit = 0' (not *Note `START TRANSACTION': commit.) followed by *Note `LOCK TABLES': lock-tables, and to not call *Note `UNLOCK TABLES': lock-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.  File: manual.info, Node: innodb-multi-versioning, Next: innodb-table-and-index, Prev: innodb-transaction-model, Up: innodb-storage-engine 14.6.8 `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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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. * Internal Details of Multi-Versioning * 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. * Guidelines for Managing Rollback Segments * 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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 *Note innodb-parameters:: for more information.  File: manual.info, Node: innodb-table-and-index, Next: innodb-disk-management, Prev: innodb-multi-versioning, Up: innodb-storage-engine 14.6.9 `InnoDB' Table and Index Structures ------------------------------------------ * Menu: * innodb-index-types:: Clustered and Secondary Indexes * innodb-physical-structure:: Physical Structure of an InnoDB Index * innodb-insert-buffering:: Insert Buffering * innodb-adaptive-hash:: Adaptive Hash Indexes * innodb-physical-record:: Physical Row Structure * Role of the .frm File * MySQL stores its data dictionary information for tables in `.frm' files in database directories. This is true for all MySQL storage engines, but every `InnoDB' table also has its own entry in the `InnoDB' internal data dictionary inside the tablespace. When MySQL drops a table or a database, it has to delete one or more `.frm' files as well as the corresponding entries inside the `InnoDB' data dictionary. Consequently, you cannot move `InnoDB' tables between databases simply by moving the `.frm' files.  File: manual.info, Node: innodb-index-types, Next: innodb-physical-structure, Prev: innodb-table-and-index, Up: innodb-table-and-index 14.6.9.1 Clustered and Secondary Indexes ........................................ Every `InnoDB' table has a special index called the clustered index (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_clustered_index) where the data for the rows is stored. Typically, the clustered index is synonymous with the primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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. * If you define a `PRIMARY KEY' on your table, `InnoDB' uses it as the clustered index. * If you do not define a `PRIMARY KEY' for your table, MySQL picks the first `UNIQUE' index that has only `NOT NULL' columns as the primary key 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 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 row data is on the same page where the index search leads. 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. (For example, `MyISAM' uses one file for data rows and another for index records.) * How Secondary Indexes Relate to the Clustered Index * All indexes other than the clustered index are known as secondary indexes (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_secondary_index). 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.  File: manual.info, Node: innodb-physical-structure, Next: innodb-insert-buffering, Prev: innodb-index-types, Up: innodb-table-and-index 14.6.9.2 Physical Structure of an InnoDB Index .............................................. All `InnoDB' indexes are B-trees where the index records are stored in the leaf pages of the tree. The default size of an index page is 16KB. When new records are inserted, `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. If the fill factor (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_fill_factor) of an index page drops below 1/2, `InnoDB' tries to contract the index tree to free the page. *Note*: Changing the page size is not a supported operation and there is no guarantee that `InnoDB' will function normally with a page size other than 16KB. Problems compiling or running InnoDB may occur. In particular, `ROW_FORMAT=COMPRESSED' in the `InnoDB Plugin' assumes that the page size is at most 16KB and uses 14-bit pointers. A version of `InnoDB' built for one page size cannot use data files or log files from a version built for a different page size.  File: manual.info, Node: innodb-insert-buffering, Next: innodb-adaptive-hash, Prev: innodb-physical-structure, Up: innodb-table-and-index 14.6.9.3 Insert Buffering ......................... It is a common situation in database applications that the primary key is a unique identifier and new rows are inserted in the ascending order of the primary key. Thus, insertions into the clustered index do not require random reads from a disk. On the other hand, secondary indexes are usually nonunique, and insertions into secondary indexes happen in a relatively random order. This would cause a lot of random disk I/O operations without a special mechanism used in `InnoDB'. If an index record should be inserted into a nonunique secondary index, `InnoDB' checks whether the secondary index page is in the buffer pool. If that is the case, `InnoDB' does the insertion directly to the index page. If the index page is not found in the buffer pool, `InnoDB' inserts the record to a special insert buffer structure. The insert buffer is kept so small that it fits entirely in the buffer pool, and insertions can be done very fast. * Disk I/O for Flushing the Insert Buffer * Periodically, the insert buffer is merged into the secondary index trees in the database. Often, it is possible to merge several changes into the same page of the index tree, saving disk I/O operations. It has been measured that the insert buffer can speed up insertions into a table up to 15 times. The insert buffer merging may continue to happen _after_ the transaction has been committed. In fact, it may continue to happen after a server shutdown and restart (see *Note forcing-innodb-recovery::). Insert buffer merging may take many hours when many secondary indexes must be updated and many rows have been inserted. During this time, disk I/O will be increased, which can cause significant slowdown on disk-bound queries. Another significant background I/O operation is the purge thread (see *Note innodb-multi-versioning::).  File: manual.info, Node: innodb-adaptive-hash, Next: innodb-physical-record, Prev: innodb-insert-buffering, Up: innodb-table-and-index 14.6.9.4 Adaptive Hash Indexes .............................. If a table fits almost entirely in main memory, the fastest way to perform queries on it is to use hash indexes. `InnoDB' has a mechanism that monitors index searches made to the indexes defined for a table. If `InnoDB' notices that queries could benefit from building a hash index, it does so automatically. 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: It is not required that the whole B-tree index is cached in the buffer pool. `InnoDB' builds hash indexes on demand for those pages of the index that are often accessed. In a sense, `InnoDB' tailors itself through the adaptive hash index mechanism to ample main memory, coming closer to the architecture of main-memory databases.  File: manual.info, Node: innodb-physical-record, Prev: innodb-adaptive-hash, Up: innodb-table-and-index 14.6.9.5 Physical Row Structure ............................... The physical row structure for an `InnoDB' table depends on the row format specified when the table was created. For MySQL 5.1, `InnoDB' uses the `COMPACT' format by default, but the `REDUNDANT' format is available to retain compatibility with older versions of MySQL. To check the row format of an `InnoDB' table, use *Note `SHOW TABLE STATUS': show-table-status. The compact row format decreases row storage space by about 20% 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 `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 *Note `CHAR(10)': char. in a fixed-length format. `InnoDB' does not truncate trailing spaces from *Note `VARCHAR': char. columns. * 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. 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 15 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 will only be 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 will have a variable-length part to record their lengths, even if the secondary index is defined on fixed-length columns. * Internally, `InnoDB' stores fixed-length, fixed-width character columns such as *Note `CHAR(10)': char. in a fixed-length format. `InnoDB' does not truncate trailing spaces from *Note `VARCHAR': char. columns. * Internally, `InnoDB' attempts to store UTF-8 *Note `CHAR(N)': char. columns in N bytes by trimming trailing spaces. (With `REDUNDANT' row format, such columns occupy 3 x N bytes.) Reserving the minimum space N in many cases enables column updates to be done in place without causing fragmentation of the index page.  File: manual.info, Node: innodb-disk-management, Next: innodb-error-handling, Prev: innodb-table-and-index, Up: innodb-storage-engine 14.6.10 `InnoDB' Disk I/O and File Space Management --------------------------------------------------- * Menu: * innodb-disk-io:: `InnoDB' Disk I/O * innodb-file-space:: File Space Management * innodb-file-defragmenting:: Defragmenting a Table  File: manual.info, Node: innodb-disk-io, Next: innodb-file-space, Prev: innodb-disk-management, Up: innodb-disk-management 14.6.10.1 `InnoDB' Disk I/O ........................... `InnoDB' uses simulated asynchronous disk I/O: `InnoDB' creates a number of threads to take care of I/O operations, such as read-ahead. 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. `InnoDB' uses a novel file flush technique called _doublewrite_. It adds safety to recovery following an operating system crash or a power outage, and improves performance on most varieties of Unix by reducing the need for `fsync()' operations. Doublewrite means that 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 the operating system crashes in the middle of a page write, `InnoDB' can later find a good copy of the page from the doublewrite buffer during recovery.  File: manual.info, Node: innodb-file-space, Next: innodb-file-defragmenting, Prev: innodb-disk-io, Up: innodb-disk-management 14.6.10.2 File Space Management ............................... The data files that you define in the configuration file form the `InnoDB' tablespace. The files are logically concatenated to form the tablespace. There is no striping in use. Currently, you cannot define where within the tablespace your tables are allocated. However, in a newly created tablespace, `InnoDB' allocates space starting from the first data file. The tablespace consists of database pages with a default size of 16KB. The pages are grouped into extents of size 1MB (64 consecutive pages). The `files' inside a tablespace are called _segments_ in `InnoDB'. The term `rollback segment' is somewhat confusing because it actually contains many tablespace segments. When a segment grows inside the tablespace, `InnoDB' allocates the first 32 pages to it individually. 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. The idea here is to achieve better sequentiality for the leaf nodes, which contain the 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 *Note `SHOW TABLE STATUS': 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 in an (automatic) purge operation after they are no longer needed for transaction rollbacks or consistent reads. (See *Note innodb-multi-versioning::.) To see information about the tablespace, use the Tablespace Monitor. See *Note innodb-monitors::. The maximum row length, except for variable-length columns (*Note `VARBINARY': binary-varbinary, *Note `VARCHAR': char, *Note `BLOB': blob. and *Note `TEXT': blob.), is slightly less than half of a database page. That is, the maximum row length is about 8000 bytes. *Note `LONGBLOB': blob. and *Note `LONGTEXT': blob. columns must be less than 4GB, and the total row length, including *Note `BLOB': blob. and *Note `TEXT': blob. 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. For a column chosen for 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.  File: manual.info, Node: innodb-file-defragmenting, Prev: innodb-file-space, Up: innodb-disk-management 14.6.10.3 Defragmenting a Table ............................... If there are random insertions into or deletions from the indexes of a table, the indexes may 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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 a_non_indexed_column <> 12345; (In the preceding query, we are `fooling' the SQL optimizer into scanning the clustered index rather than a secondary index.) Most disks can read 10MB/s to 50MB/s, which can be used to estimate how fast a table scan should be. It can speed up index scans if you periodically perform a `null' *Note `ALTER TABLE': alter-table. operation, which causes MySQL to rebuild the table: ALTER TABLE TBL_NAME ENGINE=INNODB Another way to perform a defragmentation operation is to use *Note `mysqldump': 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.  File: manual.info, Node: innodb-error-handling, Next: innodb-tuning-troubleshooting, Prev: innodb-disk-management, Up: innodb-storage-engine 14.6.11 `InnoDB' Error Handling ------------------------------- * Menu: * innodb-error-codes:: `InnoDB' Error Codes * operating-system-error-codes:: Operating System Error Codes Error handling in `InnoDB' is not always the same as specified in the SQL standard. According to the standard, any error during an SQL statement should cause rollback of that statement. `InnoDB' sometimes rolls back only part of the statement, or the whole transaction. The following items describe how `InnoDB' performs error handling: * If you run out of file space in the 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, available as of MySQL 5.1.15.) 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 *Note `START TRANSACTION': commit. or *Note `BEGIN': commit. statement, rollback does not cancel that statement. Further SQL statements become part of the transaction until the occurrence of *Note `COMMIT': commit, *Note `ROLLBACK': commit, 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 *Note `ROLLBACK': commit. SQL statement, *Note `SHOW PROCESSLIST': show-processlist. displays `Rolling back' in the `State' column for the relevant connection.  File: manual.info, Node: innodb-error-codes, Next: operating-system-error-codes, Prev: innodb-error-handling, Up: innodb-error-handling 14.6.11.1 `InnoDB' Error Codes .............................. The following is a nonexhaustive list of common `InnoDB'-specific errors that you may encounter, with information about why each occurs and how to resolve the problem. * `1005 (ER_CANT_CREATE_TABLE)' Cannot create table. 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. * `1016 (ER_CANT_OPEN_FILE)' Cannot find the `InnoDB' table from the `InnoDB' data files, although the `.frm' file for the table exists. See *Note innodb-troubleshooting-datadict::. * `1114 (ER_RECORD_FILE_FULL)' `InnoDB' has run out of free space in the tablespace. Reconfigure the tablespace to add a new data file. * `1205 (ER_LOCK_WAIT_TIMEOUT)' Lock wait timeout expired. The statement that waited too long was rolled back (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_rollback) (not the entire transaction (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_locking) problems and reducing concurrency (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_concurrency) on a busy system. * `1206 (ER_LOCK_TABLE_FULL)' The total number of locks exceeds the lock table size. 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 *Note `INSERT': insert, perform several smaller *Note `INSERT': insert. operations. * `1213 (ER_LOCK_DEADLOCK)' The transaction (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction) encountered a deadlock (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_deadlock) and was automatically rolled back (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_rollback) so that your application could 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 *Note innodb-deadlocks:: for details. * `1216 (ER_NO_REFERENCED_ROW)' You are trying to add a row but there is no parent row, and a foreign key constraint fails. Add the parent row first. * `1217 (ER_ROW_IS_REFERENCED)' You are trying to delete a parent row that has children, and a foreign key constraint fails. Delete the children first.  File: manual.info, Node: operating-system-error-codes, Prev: innodb-error-codes, Up: innodb-error-handling 14.6.11.2 Operating System Error Codes ...................................... To print the meaning of an operating system error number, use the *Note `perror': perror. program that comes with the MySQL distribution. * *Linux System Error Codes* The following table provides a list of some common Linux system error codes. For a more complete list, see Linux source code (http://www.finalcog.com/c-error-codes-include-errno). Linux error codes associated with InnoDB file operations and other system calls. Number Macro Description 1 `EPERM' Operation not permitted 2 `ENOENT' No such file or directory 3 `ESRCH' No such process 4 `EINTR' Interrupted system call 5 `EIO' I/O error 6 `ENXIO' No such device or address 7 `E2BIG' Arg list too long 8 `ENOEXEC' Exec format error 9 `EBADF' Bad file number 10 `ECHILD' No child processes 11 `EAGAIN' Try again 12 `ENOMEM' Out of memory 13 `EACCES' Permission denied 14 `EFAULT' Bad address 15 `ENOTBLK' Block device required 16 `EBUSY' Device or resource busy 17 `EEXIST' File exists 18 `EXDEV' Cross-device link 19 `ENODEV' No such device 20 `ENOTDIR' Not a directory 21 `EISDIR' Is a directory 22 `EINVAL' Invalid argument 23 `ENFILE' File table overflow 24 `EMFILE' Too many open files 25 `ENOTTY' Inappropriate ioctl for device 26 `ETXTBSY' Text file busy 27 `EFBIG' File too large 28 `ENOSPC' No space left on device 29 `ESPIPE' File descriptor does not allow seeking 30 `EROFS' Read-only file system 31 `EMLINK' Too many links * *Windows System Error Codes* The following table provides a list of some common Windows system error codes. For a complete list, see the Microsoft Web site (http://msdn.microsoft.com/en-us/library/ms681381.aspx). Windows error codes associated with InnoDB file operations and other system calls. Number Macro Description 1 `ERROR_INVALID_FUNCTION'Incorrect function. 2 `ERROR_FILE_NOT_FOUND'The system cannot find the file specified. 3 `ERROR_PATH_NOT_FOUND'The system cannot find the path specified. 4 `ERROR_TOO_MANY_OPEN_FILES'The system cannot open the file. 5 `ERROR_ACCESS_DENIED'Access is denied. 6 `ERROR_INVALID_HANDLE'The handle is invalid. 7 `ERROR_ARENA_TRASHED'The storage control blocks were destroyed. 8 `ERROR_NOT_ENOUGH_MEMORY'Not enough storage is available to process this command. 9 `ERROR_INVALID_BLOCK'The storage control block address is invalid. 10 `ERROR_BAD_ENVIRONMENT'The environment is incorrect. 11 `ERROR_BAD_FORMAT'An attempt was made to load a program with an incorrect format. 12 `ERROR_INVALID_ACCESS'The access code is invalid. 13 `ERROR_INVALID_DATA'The data is invalid. 14 `ERROR_OUTOFMEMORY'Not enough storage is available to complete this operation. 15 `ERROR_INVALID_DRIVE'The system cannot find the drive specified. 16 `ERROR_CURRENT_DIRECTORY'The directory cannot be removed. 17 `ERROR_NOT_SAME_DEVICE'The system cannot move the file to a different disk drive. 18 `ERROR_NO_MORE_FILES'There are no more files. 19 `ERROR_WRITE_PROTECT'The media is write protected. 20 `ERROR_BAD_UNIT'The system cannot find the device specified. 21 `ERROR_NOT_READY'The device is not ready. 22 `ERROR_BAD_COMMAND'The device does not recognize the command. 23 `ERROR_CRC' Data error (cyclic redundancy check). 24 `ERROR_BAD_LENGTH'The program issued a command but the command length is incorrect. 25 `ERROR_SEEK' The drive cannot locate a specific area or track on the disk. 26 `ERROR_NOT_DOS_DISK'The specified disk or diskette cannot be accessed. 27 `ERROR_SECTOR_NOT_FOUND'The drive cannot find the sector requested. 28 `ERROR_OUT_OF_PAPER'The printer is out of paper. 29 `ERROR_WRITE_FAULT'The system cannot write to the specified device. 30 `ERROR_READ_FAULT'The system cannot read from the specified device. 31 `ERROR_GEN_FAILURE'A device attached to the system is not functioning. 32 `ERROR_SHARING_VIOLATION'The process cannot access the file because it is being used by another process. 33 `ERROR_LOCK_VIOLATION'The process cannot access the file because another process has locked a portion of the file. 34 `ERROR_WRONG_DISK'The wrong diskette is in the drive. Insert %2 (Volume Serial Number: %3) into drive %1. 36 `ERROR_SHARING_BUFFER_EXCEEDED'Too many files opened for sharing. 38 `ERROR_HANDLE_EOF'Reached the end of the file. 39 `ERROR_HANDLE_DISK_FULL'The disk is full. 87 `ERROR_INVALID_PARAMETER'The parameter is incorrect. 112 `ERROR_DISK_FULL'The disk is full. 123 `ERROR_INVALID_NAME'The file name, directory name, or volume label syntax is incorrect. 1450 `ERROR_NO_SYSTEM_RESOURCES'Insufficient system resources exist to complete the requested service.  File: manual.info, Node: innodb-tuning-troubleshooting, Next: innodb-restrictions, Prev: innodb-error-handling, Up: innodb-storage-engine 14.6.12 `InnoDB' Performance Tuning and Troubleshooting ------------------------------------------------------- * Menu: * innodb-tuning:: `InnoDB' Performance Tuning Tips * innodb-monitors:: `SHOW ENGINE INNODB STATUS' and the `InnoDB' Monitors * innodb-troubleshooting:: `InnoDB' General Troubleshooting * innodb-troubleshooting-datadict:: Troubleshooting `InnoDB' Data Dictionary Operations  File: manual.info, Node: innodb-tuning, Next: innodb-monitors, Prev: innodb-tuning-troubleshooting, Up: innodb-tuning-troubleshooting 14.6.12.1 `InnoDB' Performance Tuning Tips .......................................... The followings tips are grouped by category. Some of them can apply in multiple categories, so it is useful to read them all. *Storage Layout Tips* * In `InnoDB', having a long `PRIMARY KEY' wastes a lot of disk space because its value must be stored with every secondary index record. (See *Note innodb-table-and-index::.) Create an `AUTO_INCREMENT' column as the primary key if your primary key is long. * Use the *Note `VARCHAR': char. data type instead of *Note `CHAR': char. if you are storing variable-length strings or if the column may contain many `NULL' values. A *Note `CHAR(N)': char. 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 in MySQL 5.1) and variable-length character sets, such as `utf8' or `sjis', *Note `CHAR(N)': char. will occupy a variable amount of space, at least N bytes. *Transaction Management Tips* * Wrap several modifications into a single transaction to reduce the number of flush operations. `InnoDB' must flush the log to disk at each transaction commit if that transaction made modifications to the database. The rotation speed of a disk is typically at most 167 revolutions/second (for a 10,000RPM disk), which constrains the number of commits to the same 167^th of a second if the disk does not `fool' the operating system. * 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. *Disk I/O Tips* * `innodb_buffer_pool_size' specifies the size of the buffer pool. If your buffer pool is small and you have sufficient memory, making the pool larger can improve performance by reducing the amount of disk I/O needed as queries access *Note `InnoDB': innodb-storage-engine. tables. For more information about the pool, see *Note innodb-buffer-pool::. * Beware of big rollbacks of mass inserts: `InnoDB' uses the insert buffer to save disk I/O in inserts, but no such mechanism is used in a corresponding rollback. A disk-bound rollback can take 30 times as long to perform as the corresponding insert. Killing the database process does not help because the rollback starts again on server startup. The only way to get rid of a runaway rollback is to increase the buffer pool so that the rollback becomes CPU-bound and runs fast, or to use a special procedure. See *Note forcing-innodb-recovery::. * Beware also of other big disk-bound operations. Use *Note `DROP TABLE': drop-table. and *Note `CREATE TABLE': create-table. to empty a table, not `DELETE FROM TBL_NAME'. * In some versions of GNU/Linux and Unix, flushing files to disk with the Unix `fsync()' call (which `InnoDB' uses by default) and other similar methods is surprisingly slow. If you are dissatisfied with database write performance, you might try setting the `innodb_flush_method' parameter to `O_DSYNC'. The `O_DSYNC' flush method seems to perform slower on most systems, but yours might not be one of them. * When using the `InnoDB' storage engine on Solaris 10 for x86_64 architecture (AMD Opteron), it is important to use direct I/O for `InnoDB'-related files. Failure to do so may cause degradation of `InnoDB''s speed and performance on this platform. 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.) Alternatively, as of MySQL 5.1.18 you can set `innodb_flush_method = O_DIRECT' if you do not want to affect the entire file system. This causes `InnoDB' to call `directio()' instead of `fcntl()'. However, setting `innodb_flush_method' to `O_DIRECT' causes `InnoDB' to use direct I/O only for data files, not the log files. 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), a significant performance gain might be achieved by placing `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. You are advised to perform tests with and without raw partitions or direct I/O file systems to verify whether performance is improved on your system. Other MySQL data files, such as those for `MyISAM' tables, should not be placed on a direct I/O file system. Executables or libraries _must not_ be placed on a direct I/O file system. * 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. Maybe you are making too many transaction commits, or the buffer pool is too small. Making the buffer pool bigger can help, but do not set it equal to more than 80% of physical memory. *Logging Tips* * Make your log files big, even as big as the buffer pool. When `InnoDB' has written the log files full, it must write the modified contents of the buffer pool to disk in a checkpoint. Small log files cause many unnecessary disk writes. The disadvantage of big log files is that the recovery time is longer. * Make the log buffer quite large as well (on the order of 8MB). *Bulk Data Loading Tips* * When importing data into `InnoDB', make sure that MySQL does not have autocommit mode enabled because that requires a log flush to disk for every insert. To disable autocommit during your import operation, surround it with *Note `SET autocommit': commit. and *Note `COMMIT': commit. statements: SET autocommit=0;... SQL IMPORT STATEMENTS ... COMMIT; If you use the *Note `mysqldump': mysqldump. option `--opt', you get dump files that are fast to import into an `InnoDB' table, even without wrapping them with the *Note `SET autocommit': commit. and *Note `COMMIT': 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 insert 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 the foreign key checks off 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. *Other Tips* * Unlike `MyISAM', `InnoDB' does not store an index cardinality value in its tables. Instead, `InnoDB' computes a cardinality for a table the first time it accesses it after startup. With a large number of tables, this might take significant time. It is the initial table open operation that is important, so 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'. * Use the multiple-row *Note `INSERT': 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. * If you often have recurring queries for tables that are not updated frequently, enable the query cache: [mysqld] query_cache_type = 1 query_cache_size = 10M  File: manual.info, Node: innodb-monitors, Next: innodb-troubleshooting, Prev: innodb-tuning, Up: innodb-tuning-troubleshooting 14.6.12.2 `SHOW ENGINE INNODB STATUS' and the `InnoDB' Monitors ............................................................... * Menu: * innodb-standard-monitor:: `InnoDB' Standard Monitor and Lock Monitor Output * innodb-tablespace-monitor:: `InnoDB' Tablespace Monitor Output * innodb-table-monitor:: `InnoDB' Table Monitor Output `InnoDB' Monitors provide information about the `InnoDB' internal state. This information is useful for performance tuning. Each Monitor can be enabled by creating a table with a special name, which causes `InnoDB' to write Monitor output periodically. Also, output for the standard `InnoDB' Monitor is available on demand through the *Note `SHOW ENGINE INNODB STATUS': show-engine. SQL statement. There are several types of `InnoDB' Monitors: * The standard `InnoDB' Monitor displays the following types of information: * Table and record locks held by each active transaction. * Lock waits of a transaction. * Semaphore waits of threads. * Pending file I/O requests. * Buffer pool statistics. * Purge and insert buffer merge activity of the main `InnoDB' thread. For a discussion of `InnoDB' lock modes, see *Note innodb-lock-modes::. To enable the standard `InnoDB' Monitor for periodic output, create a table named `innodb_monitor'. To obtain Monitor output on demand, use the *Note `SHOW ENGINE INNODB STATUS': show-engine. SQL statement to fetch the output to your client program. If you are using the *Note `mysql': mysql. interactive client, the output is more readable if you replace the usual semicolon statement terminator with `\G': mysql> SHOW ENGINE INNODB STATUS\G * The `InnoDB' Lock Monitor is like the standard Monitor but also provides extensive lock information. To enable this Monitor for periodic output, create a table named `innodb_lock_monitor'. * The `InnoDB' Tablespace Monitor prints a list of file segments in the shared tablespace and validates the tablespace allocation data structures. To enable this Monitor for periodic output, create a table named `innodb_tablespace_monitor'. * The `InnoDB' Table Monitor prints the contents of the `InnoDB' internal data dictionary. To enable this Monitor for periodic output, create a table named `innodb_table_monitor'. To enable an `InnoDB' Monitor for periodic output, use a `CREATE TABLE' statement to create the table associated with the Monitor. For example, to enable the standard `InnoDB' Monitor, create the `innodb_monitor' table: CREATE TABLE innodb_monitor (a INT) ENGINE=INNODB; To stop the Monitor, drop the table: DROP TABLE innodb_monitor; The *Note `CREATE TABLE': create-table. syntax is just a way to pass a command to the `InnoDB' engine through MySQL's SQL parser: The only things that matter are the table name `innodb_monitor' and that it be an `InnoDB' table. The structure of the table is not relevant at all for the `InnoDB' Monitor. If you shut down the server, the Monitor does not restart automatically when you restart the server. Drop the Monitor table and issue a new *Note `CREATE TABLE': create-table. statement to start the Monitor. (This syntax may change in a future release.) As of MySQL 5.1.24, the `PROCESS' privilege is required to start or stop the `InnoDB' Monitor tables. When you enable `InnoDB' Monitors for periodic output, `InnoDB' writes their output to the *Note `mysqld': mysqld. server standard error output (`stderr'). In this case, no output is sent to clients. When switched on, `InnoDB' Monitors print data about every 15 seconds. Server output usually is directed to the error log (see *Note error-log::). This data is useful in performance tuning. On Windows, start the server from a command prompt in a console window with the `--console' option if you want to direct the output to the window rather than to the error log. `InnoDB' sends diagnostic output to `stderr' or to files rather than to `stdout' or fixed-size memory buffers, to avoid potential buffer overflows. As a side effect, the output of *Note `SHOW ENGINE INNODB STATUS': show-engine. 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 for a normal shutdown. If abnormal shutdowns have occurred, instances of these status files may be present and must be removed manually. Before removing them, you might want to examine them to see whether they contain useful information about the cause of abnormal shutdowns. The `innodb_status.PID' file is created only if the configuration option `innodb-status-file=1' is set. `InnoDB' Monitors should be enabled only when you actually want to see Monitor information because output generation does result in some performance decrement. Also, if you enable monitor output by creating the associated table, your error log may become quite large if you forget to remove the table later. For additional information about `InnoDB' monitors, see: * Mark Leith: InnoDB Table and Tablespace Monitors (http://www.markleith.co.uk/?p=25) Each monitor begins with a header containing a timestamp and the monitor name. For example: ================================================ 090407 12:06:19 INNODB TABLESPACE MONITOR OUTPUT ================================================ The header for the standard 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 following sections describe the output for each Monitor.  File: manual.info, Node: innodb-standard-monitor, Next: innodb-tablespace-monitor, Prev: innodb-monitors, Up: innodb-monitors 14.6.12.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 by creating the associated `InnoDB' table turns on the same output stream, but the stream includes the extra information if the Lock Monitor is enabled. For example, if you create the `innodb_monitor' and `innodb_lock_monitor' tables, that turns on a single output stream. The stream includes extra lock information until you disable the Lock Monitor by removing the `innodb_lock_monitor' table. Example `InnoDB' Monitor output: mysql> SHOW ENGINE INNODB STATUS\G *************************** 1. row *************************** Status: ===================================== 030709 13:00:59 INNODB MONITOR OUTPUT ===================================== Per second averages calculated from the last 18 seconds ---------- BACKGROUND THREAD ---------- srv_master_thread loops: 53 1_second, 44 sleeps, 5 10_second, 7 background, 7 flush srv_master_thread log flush and writes: 48 ---------- SEMAPHORES ---------- OS WAIT ARRAY INFO: reservation count 413452, signal count 378357 --Thread 32782 has waited at btr0sea.c line 1477 for 0.00 seconds the semaphore: X-lock on RW-latch at 41a28668 created in file btr0sea.c line 135 a writer (thread id 32782) has reserved it in mode wait exclusive number of readers 1, waiters flag 1 Last time read locked in file btr0sea.c line 731 Last time write locked in file btr0sea.c line 1347 Mutex spin waits 0, rounds 0, OS waits 0 RW-shared spins 108462, OS waits 37964; RW-excl spins 681824, OS waits 375485 Spin rounds per wait: 0.00 mutex, 20.00 RW-shared, 0.00 RW-excl ------------------------ LATEST FOREIGN KEY ERROR ------------------------ 030709 13:00:59 Transaction: TRANSACTION 0 290328284, ACTIVE 0 sec, process no 3195, OS thread id 34831 inserting 15 lock struct(s), heap size 2496, undo log entries 9 MySQL thread id 25, query id 4668733 localhost heikki update insert into ibtest11a (D, B, C) values (5, 'khDk' ,'khDk') Foreign key constraint fails for table test/ibtest11a: , CONSTRAINT `0_219242` FOREIGN KEY (`A`, `D`) REFERENCES `ibtest11b` (`A`, `D`) ON DELETE CASCADE ON UPDATE CASCADE Trying to add in child table, in index PRIMARY tuple: 0: len 4; hex 80000101; asc ....;; 1: len 4; hex 80000005; asc ....;; 2: len 4; hex 6b68446b; asc khDk;; 3: len 6; hex 0000114e0edc; asc ...N..;; 4: len 7; hex 00000000c3e0a7; asc .......;; 5: len 4; hex 6b68446b; asc khDk;; But in parent table test/ibtest11b, in index PRIMARY, the closest match we can find is record: RECORD: info bits 0 0: len 4; hex 8000015b; asc ...[;; 1: len 4; hex 80000005; asc ....;; 2: len 3; hex 6b6864; asc khd;; 3: len 6; hex 0000111ef3eb; asc ......;; 4: len 7; hex 800001001e0084; asc .......;; 5: len 3; hex 6b6864; asc khd;; ------------------------ LATEST DETECTED DEADLOCK ------------------------ 030709 12:59:58 *** (1) TRANSACTION: TRANSACTION 0 290252780, ACTIVE 1 sec, process no 3185, OS thread id 30733 inserting LOCK WAIT 3 lock struct(s), heap size 320, undo log entries 146 MySQL thread id 21, query id 4553379 localhost heikki update INSERT INTO alex1 VALUES(86, 86, 794,'aA35818','bb','c79166','d4766t', 'e187358f','g84586','h794',date_format('2001-04-03 12:54:22','%Y-%m-%d %H:%i'),7 *** (1) WAITING FOR THIS LOCK TO BE GRANTED: RECORD LOCKS space id 0 page no 48310 n bits 568 table test/alex1 index symbole trx id 0 290252780 lock mode S waiting Record lock, heap no 324 RECORD: info bits 0 0: len 7; hex 61613335383138; asc aa35818;; 1: *** (2) TRANSACTION: TRANSACTION 0 290251546, ACTIVE 2 sec, process no 3190, OS thread id 32782 inserting 130 lock struct(s), heap size 11584, undo log entries 437 MySQL thread id 23, query id 4554396 localhost heikki update REPLACE INTO alex1 VALUES(NULL, 32, NULL,'aa3572','','c3572','d6012t','', NULL,'h396', NULL, NULL, 7.31,7.31,7.31,200) *** (2) HOLDS THE LOCK(S): RECORD LOCKS space id 0 page no 48310 n bits 568 table test/alex1 index symbole trx id 0 290251546 lock_mode X locks rec but not gap Record lock, heap no 324 RECORD: info bits 0 0: len 7; hex 61613335383138; asc aa35818;; 1: *** (2) WAITING FOR THIS LOCK TO BE GRANTED: RECORD LOCKS space id 0 page no 48310 n bits 568 table test/alex1 index symbole trx id 0 290251546 lock_mode X locks gap before rec insert intention waiting Record lock, heap no 82 RECORD: info bits 0 0: len 7; hex 61613335373230; asc aa35720;; 1: *** WE ROLL BACK TRANSACTION (1) ------------ TRANSACTIONS ------------ Trx id counter 0 290328385 Purge done for trx's n:o < 0 290315608 undo n:o < 0 17 History list length 20 Total number of lock structs in row lock hash table 70 LIST OF TRANSACTIONS FOR EACH SESSION: ---TRANSACTION 0 0, not started, process no 3491, OS thread id 42002 MySQL thread id 32, query id 4668737 localhost heikki show innodb status ---TRANSACTION 0 290328384, ACTIVE 0 sec, process no 3205, OS thread id 38929 inserting 1 lock struct(s), heap size 320 MySQL thread id 29, query id 4668736 localhost heikki update insert into speedc values (1519229,1, 'hgjhjgghggjgjgjgjgjggjgjgjgjgjgggjgjg jlhhgghggggghhjhghgggggghjhghghghghghhhhghghghjhhjghjghjkghjghjghjghjfhjfh ---TRANSACTION 0 290328383, ACTIVE 0 sec, process no 3180, OS thread id 28684 committing 1 lock struct(s), heap size 320, undo log entries 1 MySQL thread id 19, query id 4668734 localhost heikki update insert into speedcm values (1603393,1, 'hgjhjgghggjgjgjgjgjggjgjgjgjgjgggjgj gjlhhgghggggghhjhghgggggghjhghghghghghhhhghghghjhhjghjghjkghjghjghjghjfhjf ---TRANSACTION 0 290328327, ACTIVE 0 sec, process no 3200, OS thread id 36880 starting index read LOCK WAIT 2 lock struct(s), heap size 320 MySQL thread id 27, query id 4668644 localhost heikki Searching rows for update update ibtest11a set B = 'kHdkkkk' where A = 89572 ------- TRX HAS BEEN WAITING 0 SEC FOR THIS LOCK TO BE GRANTED: RECORD LOCKS space id 0 page no 65556 n bits 232 table test/ibtest11a index PRIMARY trx id 0 290328327 lock_mode X waiting Record lock, heap no 1 RECORD: info bits 0 0: len 9; hex 73757072656d756d00; asc supremum.;; ------------------ ---TRANSACTION 0 290328284, ACTIVE 0 sec, process no 3195, OS thread id 34831 rollback of SQL statement ROLLING BACK 14 lock struct(s), heap size 2496, undo log entries 9 MySQL thread id 25, query id 4668733 localhost heikki update insert into ibtest11a (D, B, C) values (5, 'khDk' ,'khDk') ---TRANSACTION 0 290327208, ACTIVE 1 sec, process no 3190, OS thread id 32782 58 lock struct(s), heap size 5504, undo log entries 159 MySQL thread id 23, query id 4668732 localhost heikki update REPLACE INTO alex1 VALUES(86, 46, 538,'aa95666','bb','c95666','d9486t', 'e200498f','g86814','h538',date_format('2001-04-03 12:54:22','%Y-%m-%d %H:%i'), ---TRANSACTION 0 290323325, ACTIVE 3 sec, process no 3185, OS thread id 30733 inserting 4 lock struct(s), heap size 1024, undo log entries 165 MySQL thread id 21, query id 4668735 localhost heikki update INSERT INTO alex1 VALUES(NULL, 49, NULL,'aa42837','','c56319','d1719t','', NULL,'h321', NULL, NULL, 7.31,7.31,7.31,200) -------- FILE I/O -------- I/O thread 0 state: waiting for i/o request (insert buffer thread) I/O thread 1 state: waiting for i/o request (log thread) I/O thread 2 state: waiting for i/o request (read thread) I/O thread 3 state: waiting for i/o request (write thread) Pending normal aio reads: 0, aio writes: 0, ibuf aio reads: 0, log i/o's: 0, sync i/o's: 0 Pending flushes (fsync) log: 0; buffer pool: 0 151671 OS file reads, 94747 OS file writes, 8750 OS fsyncs 25.44 reads/s, 18494 avg bytes/read, 17.55 writes/s, 2.33 fsyncs/s ------------------------------------- INSERT BUFFER AND ADAPTIVE HASH INDEX ------------------------------------- Ibuf for space 0: size 1, free list len 19, seg size 21, 85004 inserts, 85004 merged recs, 26669 merges Hash table size 207619, used cells 14461, node heap has 16 buffer(s) 1877.67 hash searches/s, 5121.10 non-hash searches/s --- LOG --- Log sequence number 18 1212842764 Log flushed up to 18 1212665295 Last checkpoint at 18 1135877290 0 pending log writes, 0 pending chkp writes 4341 log i/o's done, 1.22 log i/o's/second ---------------------- BUFFER POOL AND MEMORY ---------------------- Total memory allocated 84966343; in additional pool allocated 1402624 Buffer pool size 3200 Free buffers 110 Database pages 3074 Modified db pages 2674 Pending reads 0 Pending writes: LRU 0, flush list 0, single page 0 Pages read 171380, created 51968, written 194688 28.72 reads/s, 20.72 creates/s, 47.55 writes/s Buffer pool hit rate 999 / 1000 -------------- ROW OPERATIONS -------------- 0 queries inside InnoDB, 0 queries in queue Main thread process no. 3004, id 7176, state: purging Number of rows inserted 3738558, updated 127415, deleted 33707, read 755779 1586.13 inserts/s, 50.89 updates/s, 28.44 deletes/s, 107.88 reads/s ---------------------------- END OF INNODB MONITOR OUTPUT ============================ `InnoDB' Monitor output is limited to 64,000 bytes when produced using the *Note `SHOW ENGINE INNODB STATUS': show-engine. statement. This limit does not apply to output written to the server's error output. Some notes on the output sections: *`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. This section is displayed only by `InnoDB Plugin'. *`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 (`InnoDB Plugin' only) shows the number of spinlock rounds per OS wait for a 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 *Note innodb-lock-modes::. *`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. On Unix, the number of threads is always 4. On Windows, the number depends on the setting of the `innodb_file_io_threads' system variable. *`INSERT BUFFER AND ADAPTIVE HASH INDEX'* This section shows the status of the `InnoDB' insert buffer and adaptive hash index. (See *Note innodb-insert-buffering::, and *Note innodb-adaptive-hash::.) The contents include the number of operations performed for each, plus statistics for hash index performance. *`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 *Note 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 additional information about the operation of the buffer pool, see *Note 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.  File: manual.info, Node: innodb-tablespace-monitor, Next: innodb-table-monitor, Prev: innodb-standard-monitor, Up: innodb-monitors 14.6.12.4 `InnoDB' Tablespace Monitor Output ............................................ The `InnoDB' Tablespace Monitor prints information about the file segments in the shared tablespace and validates the tablespace allocation data structures. If you use individual tablespaces by enabling `innodb_file_per_table', the Tablespace Monitor does not describe those tablespaces. Example `InnoDB' Tablespace Monitor output: ================================================ 090408 21:28:09 INNODB TABLESPACE MONITOR OUTPUT ================================================ FILE SPACE INFO: id 0 size 13440, free limit 3136, free extents 28 not full frag extents 2: used pages 78, full frag extents 3 first seg id not used 0 23845 SEGMENT id 0 1 space 0; page 2; res 96 used 46; full ext 0 fragm pages 32; free extents 0; not full extents 1: pages 14 SEGMENT id 0 2 space 0; page 2; res 1 used 1; full ext 0 fragm pages 1; free extents 0; not full extents 0: pages 0 SEGMENT id 0 3 space 0; page 2; res 1 used 1; full ext 0 fragm pages 1; free extents 0; not full extents 0: pages 0 ... SEGMENT id 0 15 space 0; page 2; res 160 used 160; full ext 2 fragm pages 32; free extents 0; not full extents 0: pages 0 SEGMENT id 0 488 space 0; page 2; res 1 used 1; full ext 0 fragm pages 1; free extents 0; not full extents 0: pages 0 SEGMENT id 0 17 space 0; page 2; res 1 used 1; full ext 0 fragm pages 1; free extents 0; not full extents 0: pages 0 ... SEGMENT id 0 171 space 0; page 2; res 592 used 481; full ext 7 fragm pages 16; free extents 0; not full extents 2: pages 17 SEGMENT id 0 172 space 0; page 2; res 1 used 1; full ext 0 fragm pages 1; free extents 0; not full extents 0: pages 0 SEGMENT id 0 173 space 0; page 2; res 96 used 44; full ext 0 fragm pages 32; free extents 0; not full extents 1: pages 12 ... SEGMENT id 0 601 space 0; page 2; res 1 used 1; full ext 0 fragm pages 1; free extents 0; not full extents 0: pages 0 NUMBER of file segments: 73 Validating tablespace Validation ok --------------------------------------- END OF INNODB TABLESPACE MONITOR OUTPUT ======================================= The Tablespace Monitor output includes information about the shared tablespace as a whole, followed by a list containing a breakdown for each segment within the tablespace. The tablespace consists of database pages with a default size of 16KB. The pages are grouped into extents of size 1MB (64 consecutive pages). The initial part of the output that displays overall tablespace information has this format: FILE SPACE INFO: id 0 size 13440, free limit 3136, free extents 28 not full frag extents 2: used pages 78, full frag extents 3 first seg id not used 0 23845 Overall tablespace information includes these values: * `id': The tablespace ID. A value of 0 refers to the shared tablespace. * `size': The current tablespace size in pages. * `free limit': The minimum page number for which the free list has not been initialized. Pages at or above this limit are free. * `free extents': The number of free extents. * `not full frag extents', `used pages': The number of fragment extents that are not completely filled, and the number of pages in those extents that have been allocated. * `full frag extents': The number of completely full fragment extents. * `first seg id not used': The first unused segment ID. Individual segment information has this format: SEGMENT id 0 15 space 0; page 2; res 160 used 160; full ext 2 fragm pages 32; free extents 0; not full extents 0: pages 0 Segment information includes these values: `id': The segment ID. `space', `page': The tablespace number and page within the tablespace where the segment `inode' is located. A tablespace number of 0 indicates the shared tablespace. `InnoDB' uses inodes to keep track of segments in the tablespace. The other fields displayed for a segment (`id', `res', and so forth) are derived from information in the inode. `res': The number of pages allocated (reserved) for the segment. `used': The number of allocated pages in use by the segment. `full ext': The number of extents allocated for the segment that are completely used. `fragm pages': The number of initial pages that have been allocated to the segment. `free extents': The number of extents allocated for the segment that are completely unused. `not full extents': The number of extents allocated for the segment that are partially used. `pages': The number of pages used within the not-full extents. When a segment grows, it starts as a single page, and `InnoDB' allocates the first pages for it individually, up to 32 pages (this is the `fragm pages' value). After that, `InnoDB' allocates complete 64-page extents. `InnoDB' can add up to 4 extents at a time to a large segment to ensure good sequentiality of data. For the example segment shown earlier, it has 32 fragment pages, plus 2 full extents (64 pages each), for a total of 160 pages used out of 160 pages allocated. The following segment has 32 fragment pages and one partially full extent using 14 pages for a total of 46 pages used out of 96 pages allocated: SEGMENT id 0 1 space 0; page 2; res 96 used 46; full ext 0 fragm pages 32; free extents 0; not full extents 1: pages 14 It is possible for a segment that has extents allocated to it to have a `fragm pages' value less than 32 if some of the individual pages have been deallocated subsequent to extent allocation.  File: manual.info, Node: innodb-table-monitor, Prev: innodb-tablespace-monitor, Up: innodb-monitors 14.6.12.5 `InnoDB' Table Monitor Output ....................................... The `InnoDB' Table Monitor prints the contents of the `InnoDB' internal data dictionary. The output contains one section per table. The `SYS_FOREIGN' and `SYS_FOREIGN_COLS' sections are for internal data dictionary tables that maintain information about foreign keys. There are also sections for the Table Monitor table and each user-created `InnoDB' table. Suppose that the following two tables have been created in the `test' database: CREATE TABLE parent ( par_id INT NOT NULL, fname CHAR(20), lname CHAR(20), PRIMARY KEY (par_id), UNIQUE INDEX (lname, fname) ) ENGINE = INNODB; CREATE TABLE child ( par_id INT NOT NULL, child_id INT NOT NULL, name VARCHAR(40), birth DATE, weight DECIMAL(10,2), misc_info VARCHAR(255), last_update TIMESTAMP, PRIMARY KEY (par_id, child_id), INDEX (name), FOREIGN KEY (par_id) REFERENCES parent (par_id) ON DELETE CASCADE ON UPDATE CASCADE ) ENGINE = INNODB; Then the Table Monitor output will look something like this (reformatted slightly): =========================================== 090420 12:09:32 INNODB TABLE MONITOR OUTPUT =========================================== -------------------------------------- TABLE: name SYS_FOREIGN, id 0 11, columns 7, indexes 3, appr.rows 1 COLUMNS: ID: DATA_VARCHAR DATA_ENGLISH len 0; FOR_NAME: DATA_VARCHAR DATA_ENGLISH len 0; REF_NAME: DATA_VARCHAR DATA_ENGLISH len 0; N_COLS: DATA_INT len 4; DB_ROW_ID: DATA_SYS prtype 256 len 6; DB_TRX_ID: DATA_SYS prtype 257 len 6; INDEX: name ID_IND, id 0 11, fields 1/6, uniq 1, type 3 root page 46, appr.key vals 1, leaf pages 1, size pages 1 FIELDS: ID DB_TRX_ID DB_ROLL_PTR FOR_NAME REF_NAME N_COLS INDEX: name FOR_IND, id 0 12, fields 1/2, uniq 2, type 0 root page 47, appr.key vals 1, leaf pages 1, size pages 1 FIELDS: FOR_NAME ID INDEX: name REF_IND, id 0 13, fields 1/2, uniq 2, type 0 root page 48, appr.key vals 1, leaf pages 1, size pages 1 FIELDS: REF_NAME ID -------------------------------------- TABLE: name SYS_FOREIGN_COLS, id 0 12, columns 7, indexes 1, appr.rows 1 COLUMNS: ID: DATA_VARCHAR DATA_ENGLISH len 0; POS: DATA_INT len 4; FOR_COL_NAME: DATA_VARCHAR DATA_ENGLISH len 0; REF_COL_NAME: DATA_VARCHAR DATA_ENGLISH len 0; DB_ROW_ID: DATA_SYS prtype 256 len 6; DB_TRX_ID: DATA_SYS prtype 257 len 6; INDEX: name ID_IND, id 0 14, fields 2/6, uniq 2, type 3 root page 49, appr.key vals 1, leaf pages 1, size pages 1 FIELDS: ID POS DB_TRX_ID DB_ROLL_PTR FOR_COL_NAME REF_COL_NAME -------------------------------------- TABLE: name test/child, id 0 14, columns 10, indexes 2, appr.rows 201 COLUMNS: par_id: DATA_INT DATA_BINARY_TYPE DATA_NOT_NULL len 4; child_id: DATA_INT DATA_BINARY_TYPE DATA_NOT_NULL len 4; name: DATA_VARCHAR prtype 524303 len 40; birth: DATA_INT DATA_BINARY_TYPE len 3; weight: DATA_FIXBINARY DATA_BINARY_TYPE len 5; misc_info: DATA_VARCHAR prtype 524303 len 255; last_update: DATA_INT DATA_UNSIGNED DATA_BINARY_TYPE DATA_NOT_NULL len 4; DB_ROW_ID: DATA_SYS prtype 256 len 6; DB_TRX_ID: DATA_SYS prtype 257 len 6; INDEX: name PRIMARY, id 0 17, fields 2/9, uniq 2, type 3 root page 52, appr.key vals 201, leaf pages 5, size pages 6 FIELDS: par_id child_id DB_TRX_ID DB_ROLL_PTR name birth weight misc_info last_update INDEX: name name, id 0 18, fields 1/3, uniq 3, type 0 root page 53, appr.key vals 210, leaf pages 1, size pages 1 FIELDS: name par_id child_id FOREIGN KEY CONSTRAINT test/child_ibfk_1: test/child ( par_id ) REFERENCES test/parent ( par_id ) -------------------------------------- TABLE: name test/innodb_table_monitor, id 0 15, columns 4, indexes 1, appr.rows 0 COLUMNS: i: DATA_INT DATA_BINARY_TYPE len 4; DB_ROW_ID: DATA_SYS prtype 256 len 6; DB_TRX_ID: DATA_SYS prtype 257 len 6; INDEX: name GEN_CLUST_INDEX, id 0 19, fields 0/4, uniq 1, type 1 root page 193, appr.key vals 0, leaf pages 1, size pages 1 FIELDS: DB_ROW_ID DB_TRX_ID DB_ROLL_PTR i -------------------------------------- TABLE: name test/parent, id 0 13, columns 6, indexes 2, appr.rows 299 COLUMNS: par_id: DATA_INT DATA_BINARY_TYPE DATA_NOT_NULL len 4; fname: DATA_CHAR prtype 524542 len 20; lname: DATA_CHAR prtype 524542 len 20; DB_ROW_ID: DATA_SYS prtype 256 len 6; DB_TRX_ID: DATA_SYS prtype 257 len 6; INDEX: name PRIMARY, id 0 15, fields 1/5, uniq 1, type 3 root page 50, appr.key vals 299, leaf pages 2, size pages 3 FIELDS: par_id DB_TRX_ID DB_ROLL_PTR fname lname INDEX: name lname, id 0 16, fields 2/3, uniq 2, type 2 root page 51, appr.key vals 300, leaf pages 1, size pages 1 FIELDS: lname fname par_id FOREIGN KEY CONSTRAINT test/child_ibfk_1: test/child ( par_id ) REFERENCES test/parent ( par_id ) ----------------------------------- END OF INNODB TABLE MONITOR OUTPUT ================================== For each table, Table Monitor output contains a section that displays general information about the table and specific information about its columns, indexes, and foreign keys. The general information for each table includes the table name (in `DB_NAME/TBL_NAME' format except for internal tables), its ID, the number of columns and indexes, and an approximate row count. The `COLUMNS' part of a table section lists each column in the table. Information for each column indicates its name and data type characteristics. Some internal columns are added by `InnoDB', such as `DB_ROW_ID' (row ID), `DB_TRX_ID' (transaction ID), and `DB_ROLL_PTR' (a pointer to the rollback/undo data). * `DATA_XXX': These symbols indicate the data type. There may be multiple `DATA_XXX' symbols for a given column. * `prtype': The column's `precise' type. This field includes information such as the column data type, character set code, nullability, signedness, and whether it is a binary string. This field is described in the `innobase/include/data0type.h' source file. * `len': The column length in bytes. Each `INDEX' part of the table section provides the name and characteristics of one table index: * `name': The index name. If the name is `PRIMARY', the index is a primary key. If the name is `GEN_CLUST_INDEX', the index is the clustered index that is created automatically if the table definition doesn't include a primary key or non-`NULL' unique index. See *Note innodb-index-types::. * `id': The index ID. * `fields': The number of fields in the index, as a value in `M/N' format: * M is the number of user-defined columns; that is, the number of columns you would see in the index definition in a `CREATE TABLE' statement. * N is the total number of index columns, including those added internally. For the clustered index, the total includes the other columns in the table definition, plus any columns added internally. For a secondary index, the total includes the columns from the primary key that are not part of the secondary index. * `uniq': The number of leading fields that are enough to determine index values uniquely. * `type': The index type. This is a bit field. For example, 1 indicates a clustered index and 2 indicates a unique index, so a clustered index (which always contains unique values), will have a `type' value of 3. An index with a `type' value of 0 is neither clustered nor unique. The flag values are defined in the `innobase/include/dict0mem.h' source file. * `root page': The index root page number. * `appr. key vals': The approximate index cardinality. * `leaf pages': The approximate number of leaf pages in the index. * `size pages': The approximate total number of pages in the index. * `FIELDS': The names of the fields in the index. For a clustered index that was generated automatically, the field list begins with the internal `DB_ROW_ID' (row ID) field. `DB_TRX_ID' and `DB_ROLL_PTR' are always added internally to the clustered index, following the fields that comprise the primary key. For a secondary index, the final fields are those from the primary key that are not part of the secondary index. The end of the table section lists the `FOREIGN KEY' definitions that apply to the table. This information appears whether the table is a referencing or referenced table.  File: manual.info, Node: innodb-troubleshooting, Next: innodb-troubleshooting-datadict, Prev: innodb-monitors, Up: innodb-tuning-troubleshooting 14.6.12.6 `InnoDB' General 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 *Note error-log::). * Issues relating to the `InnoDB' data dictionary include failed *Note `CREATE TABLE': create-table. statements (orphaned 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 *Note innodb-troubleshooting-datadict::. * When troubleshooting, it is usually best to run the MySQL server from the command prompt, rather than through *Note `mysqld_safe': mysqld-safe. or as a Windows service. You can then see what *Note `mysqld': mysqld. prints to the console, and so have a better grasp of what is going on. On Windows, start *Note `mysqld': mysqld. with the `--console' option to direct the output to the console window. * Use the `InnoDB' Monitors to obtain information about a problem (see *Note innodb-monitors::). If the problem is performance-related, or your server appears to be hung, you should use the standard Monitor to print information about the internal state of `InnoDB'. If the problem is with locks, use the Lock Monitor. If the problem is in creation of tables or other data dictionary operations, use the Table Monitor to print the contents of the `InnoDB' internal data dictionary. To see tablespace information use the Tablespace Monitor. * If you suspect that a table is corrupt, run *Note `CHECK TABLE': check-table. on that table.  File: manual.info, Node: innodb-troubleshooting-datadict, Prev: innodb-troubleshooting, Up: innodb-tuning-troubleshooting 14.6.12.7 Troubleshooting `InnoDB' Data Dictionary Operations ............................................................. A specific issue with tables is that the MySQL server keeps data dictionary information in `.frm' files it stores in the database directories, whereas `InnoDB' also stores the information into its own data dictionary inside the tablespace files. If you move `.frm' files around, or if the server crashes in the middle of a data dictionary operation, the locations of the `.frm' files may end up out of synchrony with the locations recorded in the `InnoDB' internal data dictionary. * Problem with CREATE TABLE * A symptom of an out-of-sync data dictionary is that a *Note `CREATE TABLE': 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 orphaned 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 orphaned table by following the instructions given in the error message. If you are still unable to use *Note `DROP TABLE': drop-table. successfully, the problem may be due to name completion in the *Note `mysql': mysql. client. To work around this problem, start the *Note `mysql': mysql. client with the `--skip-auto-rehash' option and try *Note `DROP TABLE': drop-table. again. (With name completion on, *Note `mysql': mysql. tries to construct a list of table names, which fails when a problem such as just described exists.) * Problem Opening Table * Another symptom of an out-of-sync data dictionary is that MySQL prints an error that it cannot open a `.InnoDB' file: ERROR 1016: Can't open file: 'child2.InnoDB'. (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 orphaned `.frm' file without a corresponding table inside `InnoDB'. You can drop the orphaned `.frm' file by deleting it manually. * Problem with Temporary Table * If MySQL crashes in the middle of an *Note `ALTER TABLE': alter-table. operation, you may end up with an orphaned temporary table inside the `InnoDB' tablespace. Using the Table Monitor, you can see listed a table with a name that begins with `#sql-'. You can perform SQL statements on tables whose name contains the character ``#'' if you enclose the name within backticks. Thus, you can drop such an orphaned table like any other orphaned table using the method described earlier. To copy or rename a file in the Unix shell, you need to put the file name in double quotation marks if the file name contains ``#''. * Problem with Missing Tablespace * 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 *Note `DROP TABLE': 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.  File: manual.info, Node: innodb-restrictions, Prev: innodb-tuning-troubleshooting, Up: innodb-storage-engine 14.6.13 Limits on `InnoDB' Tables --------------------------------- *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 re-generate them with the *Note `mysql_install_db': mysql-install-db. script. *Warning*: It is not a good idea to configure `InnoDB' to use data files or log files on NFS volumes. Otherwise, the files might be locked by other processes and become unavailable for use by MySQL. * Maximums and Minimums * * A table can contain a maximum of 1000 columns. * A table can contain a maximum of 64 secondary indexes (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_secondary_index). * An index key for a single-column index can be up to 767 bytes. The same length limit applies to any index key prefix. See *Note create-index::. * The `InnoDB' internal maximum key length is 3500 bytes, but MySQL itself restricts this to 3072 bytes. This limit applies to the length of the combined index key in a multi-column index. * The maximum row length, except for variable-length columns (*Note `VARBINARY': binary-varbinary, *Note `VARCHAR': char, *Note `BLOB': blob. and *Note `TEXT': blob.), is slightly less than half of a database page. That is, the maximum row length is about 8000 bytes. *Note `LONGBLOB': blob. and *Note `LONGTEXT': blob. columns must be less than 4GB, and the total row length, including *Note `BLOB': blob. and *Note `TEXT': blob. 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 *Note 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 *Note 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, you will need to configure it using several smaller data files rather than one or a file large data files. * The combined size of the `InnoDB' log files must be less than 4GB. * The minimum tablespace size is 10MB. The maximum tablespace size is four billion database pages (64TB). This is also the maximum size for a table. * The default database page size in `InnoDB' is 16KB. *Note*: Changing the page size is not a supported operation and there is no guarantee that *Note `InnoDB': innodb-storage-engine. will function normally with a page size other than 16KB. Problems compiling or running InnoDB may occur. In particular, `ROW_FORMAT=COMPRESSED' in the `InnoDB Plugin' assumes that the page size is at most 16KB and uses 14-bit pointers. A version of *Note `InnoDB': innodb-storage-engine. built for one page size cannot use data files or log files from a version built for a different page size. This limitation could affect restore or downgrade operations using data from MySQL 5.6, which does support page sizes other than 16KB. * Index Types * * `InnoDB' tables do not support `FULLTEXT' indexes. * `InnoDB' tables support spatial data types, but not indexes on them. * Restrictions on InnoDB Tables * * *Note `ANALYZE TABLE': analyze-table. determines index cardinality (as displayed in the `Cardinality' column of *Note `SHOW INDEX': show-index. output) by doing eight random dives to each of the index trees and updating index cardinality estimates accordingly. Because these are only estimates, repeated runs of *Note `ANALYZE TABLE': analyze-table. may produce different numbers. This makes *Note `ANALYZE TABLE': analyze-table. fast on `InnoDB' tables but not 100% accurate because it does not take all rows into account. For `InnoDB Plugin', you can change the number of random dives by modifying the `innodb_stats_sample_pages' system variable. For more information, see Ease of Use and Reliability. MySQL uses index cardinality estimates only in join optimization. If some join is not optimized in the right way, you can try using *Note `ANALYZE TABLE': analyze-table. In the few cases that *Note `ANALYZE TABLE': 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 *Note server-system-variables::, and *Note optimizer-issues::. * *Note `SHOW TABLE STATUS': show-table-status. does not give accurate statistics (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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. To process a `SELECT COUNT(*) FROM t' statement, `InnoDB' scans an index of the table, which takes some time if the index is not entirely in the buffer pool. If your table does not change often, using the MySQL query cache is a good solution. To get a fast count, you have to use a counter table you create yourself and let your application update it according to the inserts and deletes it does. If an approximate row count is sufficient, *Note `SHOW TABLE STATUS': show-table-status. can be used. See *Note innodb-tuning::. * 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. * 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. While 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 clients cannot insert into the table while the `AUTO-INC' table lock is held. See *Note 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, similar to how `MyISAM' works. * `DELETE FROM TBL_NAME' does not regenerate the table but instead deletes all rows, one by one. * Under some conditions, `TRUNCATE TBL_NAME' for an `InnoDB' table is mapped to `DELETE FROM TBL_NAME'. See *Note truncate-table::. * The *Note `LOAD TABLE FROM MASTER': load-table-from-master. statement for setting up replication slave servers does not work for `InnoDB' tables. A workaround is to alter the table to `MyISAM' on the master, then do the load, and after that alter the master table back to `InnoDB'. Do not do this if the tables use `InnoDB'-specific features such as foreign keys. * Currently, 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'). In versions of MySQL before 5.1.10 this would cause a crash, since 5.1.10 the server will report error 1005 and refers to error -1 in the error message. This restriction applies only to use of the names in uppercase. * Locking and Transactions * * *Note `LOCK TABLES': 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, *Note `LOCK TABLES': lock-tables. completes even if some records of the tables are being locked by other transactions. * 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 *Note `LOCK TABLES': 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 *Note `LOCK TABLES': lock-tables. performs an implicit *Note `COMMIT': commit. and *Note `UNLOCK TABLES': lock-tables. * `InnoDB' has a limit of 1023 concurrent transactions that have created undo records by modifying data. Workarounds include keeping transactions as small and fast as possible, delaying changes until near the end of the transaction, and using stored routines to reduce client/server latency delays. Applications should commit transactions before doing time-consuming client-side operations.  File: manual.info, Node: se-db2, Next: merge-storage-engine, Prev: innodb-storage-engine, Up: storage-engines 14.7 The `IBMDB2I' Storage Engine ================================= * Menu: * se-db2-installation:: Installation * se-db2-configuration:: Configuration Options * se-db2-creating-tables:: Creating schemas and tables * se-db2-metadata:: Database/metadata management * se-db2-transactions:: Transaction behavior * se-db2-terms:: Principles and Terminology * se-db2-notes:: Notes and Limitations * se-db2-collations:: Character sets and collations * se-db2-errors:: Error codes and trouble-shooting information The `IBMDB2I' storage engine is designed as a fully featured transaction-capable storage engine that enables MySQL to store its data in DB2 tables running on IBM i. With the `IBMDB2I' storage engine, data can be shared between MySQL applications and applications coded for native DB2 for i interfaces. `IBMDB2I' provides ACID-compliant transactions, support for foreign key constraints, full crash recovery, radix-tree-based indexes, and the unique ability to enable DB2 for i applications to see and update table data in real time. More information about the storage engine and its interaction with DB2 for i can be found in IBM's _Using DB2 for i as a Storage Engine for MySQL_ Redbook publication, at IBM DB2 for i a Storage Engine for MySQL Redbook (http://www.redbooks.ibm.com/abstracts/sg247705.html). *Note*: The `IBMDB2I' storage engine was introduced in MySQL 5.1.33 and considered GA in MySQL 5.1.35. It was removed in MySQL 5.1.54.  File: manual.info, Node: se-db2-installation, Next: se-db2-configuration, Prev: se-db2, Up: se-db2 14.7.1 Installation ------------------- Because it relies on features specific to the IBM i operating system running on IBM Power systems, the `IBMDB2I' storage engine is only available on builds of MySQL specifically created for the IBM i operating system. IBM i 5.4 or later is required to run ``IBMDB2I''. Some features may require IBM i 6.1 or later versions. As well, a set of program temporary fixes (PTFs) must be installed. Information about the specific PTF numbers can be obtained from http://www-912.ibm.com/n_dir/nas4apar.nsf/c79815e083182fec862564c00079d117/67d12878076e4827862574e2003c6d4a?OpenDocument (http://www-912.ibm.com/n_dir/nas4apar.nsf/c79815e083182fec862564c00079d117/67d12878076e4827862574e2003c6d4a?OpenDocument). The engine is built as a dynamic plugin and so must be installed by using the following command: mysql> INSTALL PLUGIN ibmdb2i SONAME ha_ibmdb2i.so;  File: manual.info, Node: se-db2-configuration, Next: se-db2-creating-tables, Prev: se-db2-installation, Up: se-db2 14.7.2 Configuration Options ---------------------------- *`IBMDB2I' Storage Engine Features* Name Cmd-Line Option file System Var Status Var Var Scope Dynamic ibmdb2i_assume_exclusive_useYes Yes Yes Global Yes ibmdb2i_async_enabledYes Yes Yes Both Yes ibmdb2i_compat_opt_allow_zero_date_valsYes Yes Yes Both Yes ibmdb2i_compat_opt_blob_colsYes Yes Yes Both Yes ibmdb2i_compat_opt_time_as_durationYes Yes Yes Both Yes ibmdb2i_compat_opt_year_as_intYes Yes Yes Both Yes ibmdb2i_create_index_optionYes Yes Yes Both Yes ibmdb2i_lob_alloc_sizeYes Yes Yes Both Yes ibmdb2i_max_read_buffer_sizeYes Yes Yes Both Yes ibmdb2i_max_write_buffer_sizeYes Yes Yes Both Yes ibmdb2i_propogate_default_col_valsYes Yes Yes Both Yes ibmdb2i_rdb_nameYes Yes Yes Global No ibmdb2i_system_trace_levelYes Yes Yes Global Yes ibmdb2i_transaction_unsafeYes Yes Yes Both Yes * `ibmdb2i_assume_exclusive_use' Options for ibmdb2i_assume_exclusive_use *Introduced* 5.1.33 *Command-Line `ibmdb2i_assume_exclusive_use' Format* *Option-File Format* `ibmdb2i_assume_exclusive_use' *System Variable `ibmdb2i_assume_exclusive_use' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `boolean' *Default* `off' Specifies whether an external interface (such as DB2 for i) may be altering the data accessible by the `IBMDB2I' engine. This is an advisory value that may improve performance when correctly set to ON. When the value is ON, `IBMDB2I' may perform some internal caching of table statistics. When the value is set to OFF, `IBMDB2I' must assume that the table rows could be inserted and deleted without its direct knowledge and must call DB2 to obtain accurate statistics before each operation. Default Value: OFF * `ibmdb2i_async_enabled' Options for ibmdb2i_async_enabled *Introduced* 5.1.33 *Command-Line `ibmdb2i_async_enabled' Format* *Option-File Format* `ibmdb2i_async_enabled' *System Variable `ibmdb2i_async_enabled' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `boolean' *Default* `on' Specifies whether buffering between `IBMDB2I' and the QSQSRVR jobs responsible for fetching row data should be done in an asynchronous manner. Asynchronous reads are enabled by default and provide optimal performance.Under normal circumstances, this value will never need to be modified. Default Value: ON * `ibmdb2i_create_index_option' Options for ibmdb2i_create_index_option *Introduced* 5.1.33 *Command-Line `ibmdb2i_create_index_option' Format* *Option-File Format* `ibmdb2i_create_index_option' *System Variable `ibmdb2i_create_index_option' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `numeric' *Default* `0' Controls whether additional indexes are created for use by traditional DB2 for i interfaces. When the value is 0, no additional indexes will be created. When the value is 1 and the index created on behalf of MySQL is ASCII-based, an additional index is created based on EBCDIC hexadecimal sorting. The additional index may be useful for traditional DB2 for i interfaces which expect indexes to use EBCDIC-based sort sequences. Default Value: 0 * `ibmdb2i_compat_opt_time_as_duration' Options for ibmdb2i_compat_opt_time_as_duration *Introduced* 5.1.33 *Command-Line `ibmdb2i_compat_opt_time_as_duration' Format* *Option-File Format* `ibmdb2i_compat_opt_time_as_duration' *System Variable `ibmdb2i_compat_opt_time_as_duration' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `boolean' *Default* `off' Controls how MySQL TIME columns are mapped to DB2 data types when creating or altering an `IBMDB2I' table. When the value is `ON', the column is mapped to an `INTEGER' type in DB2 and supports the full range of values defined by MySQL for `TIME' types. When the value is `OFF', the column is mapped to a DB2 `TIME' type and supports values in the range of '00:00:00' to '23:59:59'. This option is provided to provide enhanced interoperability with DB2 for i interfaces. Default Value: OFF * `ibmdb2i_system_trace_level' Options for ibmdb2i_system_trace_level *Introduced* 5.1.33 *Command-Line `ibmdb2i_system_trace_level' Format* *Option-File Format* `ibmdb2i_system_trace_level' *System Variable `ibmdb2i_system_trace_level' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `boolean' *Default* `0' Specifies what kind of debugging information is to be gathered for `QSQSRVR' jobs servicing MySQL connections. Multiple sources of information may be specified by summing the respective values. Changes to this option only affect new connections. Valid values include * `0': No information (Default) * `2': `STRDBMON' * `4': `STRDBG' * `8': `DSPJOBLOG' * `16': `STRTRC' * `32': `PRTSQLINF' The most useful sources of information are `DSPJOBLOG', which will capture the job log for each `QSQSRVR' job in a spoolfile, and `STRDBG', which will increase the diagnostic information in each job log. Default Value: 0 * `ibmdb2i_compat_opt_allow_zero_date_vals' Options for ibmdb2i_compat_opt_allow_zero_date_vals *Introduced* 5.1.33 *Command-Line `ibmdb2i_compat_opt_allow_zero_date_vals' Format* *Option-File Format* `ibmdb2i_compat_opt_allow_zero_date_vals' *System Variable `ibmdb2i_compat_opt_allow_zero_date_vals' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `boolean' *Default* `0' Specifies whether the storage engine should permit the `0000-00-00' date in `DATETIME', `TIMESTAMP' and `DATE' columns. When the option is 0, attempts to insert a row containing this zero date into an `IBMDB2I' table will fail. As well, a warning will be generated when creating a column with this zero value as the default value. When this option is 1, the zero value will be substituted with `0001-01-01' when stored in DB2, and a `0001-01-01' value will be translated to `0000-00-00' when read from DB2. Similarly, when a column with a default zero value is created, the DB2 default value will be '0001-01-01'. Users must be aware that, when this option is 1, all values of `0001-01-01' in DB2 will be interpreted as `0000-00-00'. This option is primarily added for compatibility with applications which rely on the zero date. Default Value: 0 * `ibmdb2i_propagate_default_col_vals' Options for ibmdb2i_propogate_default_col_vals *Introduced* 5.1.33 *Command-Line `ibmdb2i_propogate_default_col_vals' Format* *Option-File Format* `ibmdb2i_propogate_default_col_vals' *System Variable `ibmdb2i_propogate_default_col_vals' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `boolean' *Default* `on' Specifies whether `DEFAULT' value associated with each column should be propagated to the DB2 definition of the table when a table is created or altered. The default value is ON. This ensures that rows inserted from a standard DB2 interface will use the same default values as when inserted from MySQL. Default Value: ON * `ibmdb2i_compat_opt_year_as_int' Options for ibmdb2i_compat_opt_year_as_int *Introduced* 5.1.33 *Command-Line `ibmdb2i_compat_opt_year_as_int' Format* *Option-File Format* `ibmdb2i_compat_opt_year_as_int' *System Variable `ibmdb2i_compat_opt_year_as_int' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `boolean' *Default* `0' Controls how YEAR columns are stored in DB2. The default is 0 and causes `YEAR' columns to be created as `CHAR(4) CCSID 1208' columns in DB2. Setting this option to 1 causes the YEAR columns to be created as `SMALLINT' columns. This provides a slight performance increase and enables indexes that combine a `YEAR' column with a character column. Default Value: 0 * `ibmdb2i_lob_alloc_size' Options for ibmdb2i_lob_alloc_size *Introduced* 5.1.33 *Command-Line `ibmdb2i_lob_alloc_size' Format* *Option-File Format* `ibmdb2i_lob_alloc_size' *System Variable `ibmdb2i_lob_alloc_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `numeric' *Default* `2MB' Controls how much space is allocated by default for reading data from a `BLOB' or `TEXT' field. If an application consistently uses `BLOB' or `TEXT' fields that contain more than 2 MB of data, read performance may be improved if this value is increased. Conversely, an application which uses smaller `BLOB' or `TEXT' fields may find that the MySQL memory footprint is reduced if a smaller value is specified for this option. Default Value: 2 MB * `ibmdb2i_compat_opt_blob_cols' Options for ibmdb2i_compat_opt_blob_cols *Introduced* 5.1.33 *Command-Line `ibmdb2i_compat_opt_blob_cols' Format* *Option-File Format* `ibmdb2i_compat_opt_blob_cols' *System Variable `ibmdb2i_compat_opt_blob_cols' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `numeric' *Default* `0' Specifies how MySQL `TEXT' and `BLOB' columns larger than 255 characters are mapped when creating `IBMDB2I' tables. When the value is 0, `TEXT' columns are mapped to `CLOB' or `DBCLOB' columns for DB2 for i. This enables the column to contain the maximum size documented for `TEXT' columns (64K characters), but the column can not be included in an index. When the value is 1, `TEXT' columns are mapped to `LONG VARCHAR'/`VARGRAPHIC' columns, and `BLOB' columns are mapped to `LONG VARBINARY'. This permits indexes to be created over the column, but it reduces the amount of storage available to the column below the documented maximum for `TEXT' columns. This option was provided to enable applications which relied on the ability to create prefix indexes over `TEXT' columns. Default Value: 0 * `ibmdb2i_max_read_buffer_size' Options for ibmdb2i_max_read_buffer_size *Introduced* 5.1.33 *Command-Line `ibmdb2i_max_read_buffer_size' Format* *Option-File Format* `ibmdb2i_max_read_buffer_size' *System Variable `ibmdb2i_max_read_buffer_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `numeric' *Default* `1MB' Controls the maximum amount of memory allocated for buffering row data when doing reads from an `IBMDB2I' table. This buffering is done independently of any row buffering done within MySQL proper. Setting this value too low may reduce read performance, while setting it too high may increase memory usage and may also reduce read performance. Default Value: 1 MB * `ibmdb2i_max_write_buffer_size' Options for ibmdb2i_max_write_buffer_size *Introduced* 5.1.33 *Command-Line `ibmdb2i_max_write_buffer_size' Format* *Option-File Format* `ibmdb2i_max_write_buffer_size' *System Variable `ibmdb2i_max_write_buffer_size' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `numeric' *Default* `8MB' Controls the maximum amount of memory allocated for buffering row data when inserting multiple rows into an `IBMDB2I' table. This buffering is done independently of any row buffering done within MySQL proper. Setting this value too low may reduce write performance, while setting it too high may increase memory usage. Default Value: 8 MB * `ibmdb2i_rdb_name' Options for ibmdb2i_rdb_name *Introduced* 5.1.33 *Command-Line `ibmdb2i_rdb_name' Format* *Option-File Format* `ibmdb2i_rdb_name' *System Variable `ibmdb2i_rdb_name' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* (ibmsystemi) `string' *Default* `' The name of a local DB2 for i relational database that will act as a container for all `IBMDB2I' tables. This enables an independent auxiliary storage pool (IASP) to be selected for usage. If no value is specified, the system database (*SYSBAS) is used. Default Value: * `ibmdb2i_transaction_unsafe' Options for ibmdb2i_transaction_unsafe *Introduced* 5.1.33 *Command-Line `ibmdb2i_transaction_unsafe' Format* *Option-File Format* `ibmdb2i_transaction_unsafe' *System Variable `ibmdb2i_transaction_unsafe' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* (ibmsystemi) `boolean' *Default* `off' Controls whether `IBMDB2I' honors the transactional commands and isolation levels specified for MySQL. If the value is OFF, transactions are fully supported. If the value is ON, transactional behavior is not implemented. This may provide a moderate performance increase for applications that do not rely on transactional guarantees. Default Value: OFF The values specified for `ibmdb2i_create_index_option', `ibmdb2i_create_time_columns_as_tod', `ibmdb2i_map_blob_to_varchar', `ibmdb2i_compat_opt_allow_zero_date_vals', `ibmdb2i_propagate_default_col_vals', and `ibmdb2i_propagate_default_col_val' will be applied whenever an `IBMDB2I' table is created. Tables are implicitly destroyed and re-created when an `offline' `ALTER TABLE' is performed on an `IBMDB2I' table. Therefore it is highly recommended that the values of these variables be consistent across the lifetime of a table to prevent an `ALTER TABLE' from running under a different set of options than were used to originally create the table. If this recommendation is not followed, the `ALTER TABLE' may fail upon encountering incompatible data when re-creating the table.  File: manual.info, Node: se-db2-creating-tables, Next: se-db2-metadata, Prev: se-db2-configuration, Up: se-db2 14.7.3 Creating schemas and tables ---------------------------------- * Menu: * se-db2-creating-tables-identifiers:: Identifier names * se-db2-creating-tables-indexnames:: Index names `IBMDB2I' tables are created by specifying the `ENGINE=IBMDB2I' option on a `CREATE TABLE' or `ALTER TABLE' statement. These tables are stored as DB2 for i objects in the QSYS.LIB file system. Therefore, in contrast to the behavior of other storage engines, `IBMDB2I' table and index data does not reside beneath the datadir directory with other MySQL table data. When the first `IBMDB2I' table is created in a MySQL schema, the corresponding DB2 schema will be created (if it does not already exist). Note that if the user profile running MySQL has sufficient authority dropping a MySQL schema will drop a DB2 schema of the same name even if the schema never contained any `IBMDB2I' tables and contains objects not related to MySQL. Therefore, it is recommended that extreme caution be used when dropping MySQL schemas when the `IBMDB2I' plugin is installed.  File: manual.info, Node: se-db2-creating-tables-identifiers, Next: se-db2-creating-tables-indexnames, Prev: se-db2-creating-tables, Up: se-db2-creating-tables 14.7.3.1 Identifier names ......................... DB2 for i file objects have both a short (10-character) system name and an SQL name. The DB2 for i SQL name is always the same as the MySQL name. However, because MySQL's sensitivity to the lettercase of schema and table names depends on the file system containing the datadir, mapping the MySQL name to the system name of the corresponding DB2 for i object must account for several factors, described below. When MySQL is operating in a case-sensitive mode (that is, datadir is in a case-sensitive file-system like (/QOpenSys), the case of the system name of the `IBMDB2I' object reflects the case of the name specified to MySQL. If the object has all uppercase characters and is equal to or less than 10 characters in length, the system name will be undelimited and in uppercase.If the object name has mixed or lower-case letters, the IBM i system name will contain up to 8 characters of the name in the specified case and will be delimited by surrounding quotation marks. If the MySQL name has more characters than can fit in the delimited system name, the system name will be generated as a mangled name delimited by surrounding quotation marks. Examples of this naming behavior are given below: *Naming Behavior in DB2 Storage Engine* MySQL name DB2 for i SQL name IBM i System name mytable mytable "mytable" mylongertable mylongertable "mylo0001" UPPERTABLE UPPERTABLE UPPERTABLE UPPERLONGTABLE UPPERLONGTABLE UPPER00001 MixedTab MixedTab "MixedTab" MixedlongerTab MixedlongerTab "Mixe0001" If MySQL is operating in a case-insensitive mode, the IBM i system name will contain up to 8 characters of the name in lower case and will be delimited by surrounding quotation marks. If the MySQL name has more characters than can fit in the delimited system name, the system name will be generated as a mangled name delimited by surrounding quotation marks. Note that IBM i system names are not changed when a RENAME TABLE command is executed. Only the DB2 for i SQL name changes.  File: manual.info, Node: se-db2-creating-tables-indexnames, Prev: se-db2-creating-tables-identifiers, Up: se-db2-creating-tables 14.7.3.2 Index names .................... * Menu: * se-db2-data-type-mapping:: Data type mapping Unlike MySQL, DB2 for i requires that index names be unique to an entire schema. To support MySQL indexes, `IBMDB2I' creates the DB2 for i indexes with modified file names. The generated name is a concatenation of the index name, three underscores (_), and the table name. For example, `CREATE INDEX idx1 ON tab1 (a, b)' would create a DB2 index named `idx___tab1'. If the ibmdb2i_create_index_option value is set to 1, an additional index may be created which is named with an additional `H_' marker between the index and table names (for example, idx___H_tab1). These generated names are then mangled to create the an IBM i system name, as described above. If a table is renamed, the indexes will also be renamed. This index name generation scheme also has implications for the length of index and table names; to permit the generated name and allow for delimiting quotation marks, the combined length of the index and table names must be less than or equal to 121 characters.  File: manual.info, Node: se-db2-data-type-mapping, Prev: se-db2-creating-tables-indexnames, Up: se-db2-creating-tables-indexnames 14.7.3.3 Data type mapping .......................... When creating a table, `IBMDB2I' may map the MySQL types specified on a `CREATE TABLE' statement into a corresponding or compatible DB2 for i type. Examples include the `BIT' type, which is stored as a `BINARY' field, or the `MEDIUMINT' type, which is stored as an `INTEGER' field. For most data types, this mapping is transparent. Data types which have restrictions unique to `IBMDB2I' are documented in *Note se-db2-notes::.  File: manual.info, Node: se-db2-metadata, Next: se-db2-transactions, Prev: se-db2-creating-tables, Up: se-db2 14.7.4 Database/metadata management ----------------------------------- When an `IBMDB2I' table is created, a File Level ID (FID) file is created in the database directory. This file has an extension .FID and contains the last known FID of the associated DB2 for i physical file. The `IBMDB2I' engine uses this FID value to determine whether incompatible changes have been made to the table by an external (non-MySQL) interface. If the physical file is altered, DB2 for i automatically generates a new FID. The next time `IBMDB2I' attempts to access the file, it will detect that the new FID does not match the known FID, and it will prevent MySQL from using the table. In some cases, the changes to the physical file that cause the FID to be updated may not adversely affect access through MySQL and `IBMDB2I'. In this case, a user may wish to override the FID check that `IBMDB2I' performs. A user with appropriate permissions may do so simply by deleting the `.FID' file associated with the table and performing a `FLUSH TABLE' statement against the table. `IBMDB2I' will then regenerate the file with the new FID the next time the table is accessed from MySQL. If triggers or constraints are applied to the table from a native DB2 interface, they will be respected when accessing the table from MySQL, but MySQL will have no knowledge of the triggers or constraints. Likewise, views and indexes can be created over the tables from a DB2 interface, but the indexes will not be accessible from MySQL.  File: manual.info, Node: se-db2-transactions, Next: se-db2-terms, Prev: se-db2-metadata, Up: se-db2 14.7.5 Transaction behavior --------------------------- The `IBMDB2I' storage engine supports row-level transaction management. All MySQL isolation levels are supported by the engine, and where highest performance is required, transaction support can be disabled globally or per session by modifying the ibmdb2i_transaction_unsafe configuration option. `IBMDB2I' uses the underlying DB2 for i transaction support to implement MySQL isolation levels. DB2 for i uses table and row locks to implement the various isolation levels, as described below: *`IBMDB2I' Isolation Levels* Isolation Read-only Read-write level (SELECT) (UPDATE, DELETE) Lock enforcement Visibility of Lock Visibility of uncommitted enforcement uncommitted work on behalf work on behalf of other of other connections connections SERIALIZABLETable is locked N/A Table is N/A until end of locked until transaction.Other end of connections may transaction.Other read rows while connections locked. may read rows while locked. REPEATABLE Rows that have Rows cannot be Rows that have Rows cannot be READ been read are read until been read are read until locked until work is locked until work is end of committed. end of committed. transaction.Other transaction.Other connections may connections read and insert may read and rows while insert rows locked. while locked. READ Row is locked Rows cannot be Row is locked Rows cannot be COMMITTED while cursor is read until while cursor read until positioned on work is is positioned work is that row.Other committed. on that committed. connections may row.Other read and insert connections rows while may read and locked. insert rows while locked. READ Row is locked Rows can be Row is locked Rows can be UNCOMMITTED while cursor is read before while cursor read before positioned on work is is positioned work is that row.Other committed. on that committed. connections may row.Other read and insert connections rows while may read and locked. insert rows while locked. transaction_unsafeNo locks Full access Table is Unrestricted locked until access end of transaction.Other connections may read rows while locked. Attempts to access locked rows time out according to the timeout value associated with the underlying DB2 physical file. This timeout wait is 30 seconds by default. Refer to http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/dbp/rbafoconcrec.htm (http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/dbp/rbafoconcrec.htm) for more information. Because `IBMDB2I' does not multi-version rows under commitment control, row lock contention may occur under certain scenarios. In particular, when multiple connections attempt to read overlapping ranges of rows while performing a statement that does updates, the connections may contend for the same row locks. This may lead to delays until the row lock timeout expires. Creating appropriate indexes and increasing query selectivity to reduce range overlap may help to alleviate this contention.  File: manual.info, Node: se-db2-terms, Next: se-db2-notes, Prev: se-db2-transactions, Up: se-db2 14.7.6 Principles and Terminology --------------------------------- `AUTO_INCREMENT' The MySQL auto_increment column attribute can be used to generate a unique identity for new rows.The `IBMDB2I' storage engine maps the MySQL auto_increment attribute to the DB2 for i identity attribute For most MySQL storage engines, the auto_increment value is determined by adding one to the maximum value stored in the table for the column.For the `IBMDB2I' storage engine, DB2 for i generates the identity value by adding one to the last generated value. Following are some example MySQL statements to illustrate the point. create table t1 (a int auto increment, primary key(a)) engine = ibmdb2i; insert into t1 values(3); insert into t1 values(null),(null); For the first INSERT statement, an explicit value of 3 is specified for the auto_increment column, so the value 3 is stored in the inserted row.For the second INSERT statement null is specified, so generated values 1 and 2 will be stored in the rows. Duplicate key failures can occur in DB2 for i if a MySQL application mixes explicit auto_increment values with generated values within a table. For the example above, if one more record is inserted into the table for which an auto_increment value is generated, a duplicate key error will occur because the value 3 (that is, the last generated value plus one) already exists in the table.To effect the MySQL behavior for auto_increment columns, the `IBMDB2I' storage engine will detect a duplicate key error, alter the restart value for the DB2 identity column to the maximum value plus one, and retry the failed insert, but only if the following conditions are true: * The duplicate key error occurred on an index for which the auto_increment column is a key field * An exclusive (LENR) lock can be acquired on the table * The error occurred on the first or only row of the `INSERT' statement. The `IBMDB2I' storage engine does not support the following usage of auto_increment columns: 1. Any MySQL global or session variable that affects the start, increment, or offset for generated auto_increment values. 2. Any MySQL feature that returns the _next value to be used_ for an auto_increment column. 3. An auto_increment column on a MySQL partitioned table.  File: manual.info, Node: se-db2-notes, Next: se-db2-collations, Prev: se-db2-terms, Up: se-db2 14.7.7 Notes and Limitations ---------------------------- * When using multiples instances of MySQL on a single i5 host you should be aware that the two independent instances will access the same database within the DB2 environment. This can lead to namespace collisions and issues. To get round this limitation, you should configure different IBM i independent auxiliary storage pools (ISAPs) for each MySQL server, and then use the `ibmdb2i_rdb_name' option to MySQL to configure which IASP should be used for each MySQL instance. * Indexes over `VARBINARY' columns may not provide accurate estimates the optimizer. Queries over such indexes may produce error 2027 in the error log but will succeed. This affects only the performance of these queries, not the correctness of the results. * Setting `ibmdb2i_system_trace_level = 16 (STRTRC)' may cause unpredictable failures including error 2088 on some operations. This is unlikely to affect any users, as this value is recommended only for serviceability purposes. * `IBMDB2I' honors the `CASCADE'/`RESTRICT' option on the `DROP TABLE' statement. * The use of `FLUSH TABLES WITH READ LOCK' is discouraged when using `IBMDB2I' tables. Due to differences in internal locking implementations, `FLUSH TABLES WITH READ LOCK' may produce deadlocks on `IBMDB2I' tables. * Row-based replication is supported by `IBMDB2I'. Statement-based replication is not supported. * Schema name lengths are limited to 10 characters in IBM i 5.4 and 30 characters in IBM i 6.1. If the schema name is mixed- or lower-case, two characters must be subtracted from the limit to account for surrounding quotation marks. * The RENAME TABLE command cannot be used to move `IBMDB2I' tables from one database to another. * The maximum length of the internal row format for `IBMDB2I' is 32767 bytes. Because the internal row format may differ from the MySQL row format due to data mapping differences (see Creating schemas and tables section), anticipating this limit may be difficult. * The combined length of the index and table names must be less than or equal to 121 characters. * Indexes over TEXT or BLOB columns with a maximum length greater than 255 characters are not supported. The ibmdb2i_map_blob_to_varchar option can be used to work around this limitation for TEXT fields up to 64K characters. * Specific restrictions apply to certain data types as described in the following chart: *Data Type Restrictions in `IBMDB2I'* MySQL data Restriction type `LONGBLOB' The maximum length of a DB2 BLOB data type is 2GB. or `LONGTEXT' `DATE' `IBMDB2I' does not support the special date value of '0000-00-00'. The restrictions on `DATE' and `DATETIME' columns can be removed by setting the value of `ibmdb2i_compat_opt_allow_zero_date_vals' to 1. `DATETIME' `IBMDB2I' does not support the special datetime value of '0000-00-00 00:00:00'. The restrictions on `DATE' and `DATETIME' columns can be removed by setting the value of `ibmdb2i_compat_opt_allow_zero_date_vals' to 1. `DECIMAL(p, If p is greater than 63 and s is greater than (p-63), s)' or the field definition is truncated to `DECIMAL(63, `NUMERIC(p, s-(p-63))'. If p is greater than 63 and s is less s)' than or equal to (p-63), the definition is not supported. `TIME' By default, `IBMDB2I' only supports times in the range '00:00:00' to '23:59:59.' See the ibmdb2i_create_time_columns_as_tod option for more information. * These MySQL statements are not supported by the `IBMDB2I' Engine: * `CACHE INDEX' and `LOAD INDEX INTO CACHE' * `HANDLER' * `CHECK TABLE' * `REPAIR TABLE' * ` BACKUP-RESTORE TABLE' * The `ucs2_spanish2_ci' and `utf8_spanish2_ci' collations are not supported by `IBMDB2I'. There are no plans to support these collations. * The `ucs2_swedish_ci' and `utf8_swedish_ci' collations were added in MySQL 5.1.35. supported by `IBMDB2I'. As with other language-specific unicode collations, the support will be only be available on IBM i 6.1 and later releases.  File: manual.info, Node: se-db2-collations, Next: se-db2-errors, Prev: se-db2-notes, Up: se-db2 14.7.8 Character sets and collations ------------------------------------ DB2 for i only supports a single collation per index or foreign key constraint. A foreign key constraint must have the same collation as a primary key constraint, if one exists.. Character sets and collations supported by `IBMDB2I' are described in the list below. IBM i 6.1 is required for the most comprehensive collation support. Note that Chinese, Japanese, and Korean character sets are converted to UTF-16 for storage in DB2 for i; `utf8_general_ci' is converted to `UCS2' for storage in DB2 for i. *Collation Compatibility in `IBMDB2I' and MySQL* MySQL SupportedSupported Collation in IBM in IBM i 5.4 i 6.1 `armscii8_general_ci' `armscii8_bin' `ascii_general_ci' Yes `ascii_bin' Yes `big5_chinese_ci'Yes Yes `big5_bin' Yes Yes `cp1250_croatian_ci' Yes `cp1250_czech_cs' Yes `cp1250_general_ci' Yes `cp1250_polish_ci' Yes `cp1250_bin' Yes `cp1251_bulgarian_ci' Yes `cp1251_general_ci' Yes `cp1251_general_cs' Yes `cp1251_ukrainian_ci' `cp1251_bin' Yes `cp1256_general_ci' Yes `cp1256_bin' Yes `cp1257_general_ci' `cp1257_lithuanian_ci' `cp1257_bin' `cp850_general_ci'Yes Yes `cp850_bin' Yes Yes `cp852_general_ci' Yes `cp852_bin' Yes `cp866_general_ci' `cp866_bin' `cp932_japanese_ci'Yes Yes `cp932_bin' Yes Yes `dec8_swedish_ci' `dec8_bin' `eucjpms_japanese_ci' `eucjpms_bin' `euckr_korean_ci'Yes Yes `euckr_bin' Yes Yes `gb2312_chinese_ci'Yes Yes `gb2312_bin' Yes Yes `gbk_chinese_ci'Yes Yes `gbk_bin' Yes Yes `geostd8_general_ci' `geostd8_bin' `greek_general_ci'Yes Yes `greek_bin' Yes Yes `hebrew_general_ci'Yes Yes `hebrew_bin' Yes Yes `hp8_english_ci' `hp8_bin' `keybcs2_general_ci' `keybcs2_bin' `koi8r_general_ci' `koi8r_bin' `koi8u_general_ci' `koi8u_bin' `latin1_danish_ci'Yes Yes `latin1_general_ci'Yes Yes `latin1_general_cs'Yes Yes `latin1_german1_ci'Yes Yes `latin1_german2_ci' `latin1_spanish_ci'Yes Yes `latin1_swedish_ci'Yes Yes `latin1_bin' Yes Yes `latin2_croatian_ci'Yes Yes `latin2_czech_cs'Yes Yes `latin2_general_ci'Yes Yes `latin2_hungarian_ci'Yes Yes `latin2_bin' Yes Yes `latin5_turkish_ci'Yes Yes `latin5_bin' Yes Yes `latin7_estonian_cs' `latin7_general_ci' `latin7_general_cs' `latin7_bin' `macce_general_ci' Yes `macce_bin' Yes `macroman_general_ci' `macroman_bin' `sjis_japanese_ci'Yes Yes `sjis_bin' Yes Yes `swe7_swedish_ci' `swe7_bin' `tis620_thai_ci'Yes Yes `tis620_bin' Yes Yes `ucs2_czech_ci' Yes `ucs2_danish_ci' Yes `ucs2_esperanto_ci' Yes `ucs2_estonian_ci' Yes `ucs2_general_ci'Yes Yes `ucs2_hungarian_ci' Yes `ucs2_icelandic_ci' Yes `ucs2_latvian_ci' Yes `ucs2_lithuanian_ci' Yes `ucs2_persian_ci' Yes `ucs2_polish_ci' Yes `ucs2_roman_ci' `ucs2_romanian_ci' Yes `ucs2_slovak_ci' Yes `ucs2_slovenian_ci' Yes `ucs2_spanish_ci' Yes `ucs2_spanish2_ci' Yes `ucs2_turkish_ci' Yes `ucs2_unicode_ci'Yes Yes `ucs2_bin' Yes Yes `ujis_japanese_ci'Yes Yes `ujis_bin' Yes Yes `utf8_czech_ci' Yes `utf8_danish_ci' Yes `utf8_esperanto_ci' Yes `utf8_estonian_ci' Yes `utf8_general_ci'Yes Yes `utf8_hungarian_ci' Yes `utf8_icelandic_ci' Yes `utf8_latvian_ci' Yes `utf8_lithuanian_ci' Yes `utf8_persian_ci' Yes `utf8_polish_ci' Yes `utf8_roman_ci' `utf8_romanian_ci' Yes `utf8_slovak_ci' Yes `utf8_slovenian_ci' Yes `utf8_spanish_ci' Yes `utf8_spanish2_ci' Yes `utf8_turkish_ci' Yes `utf8_unicode_ci' Yes `utf8_bin' Yes Yes  File: manual.info, Node: se-db2-errors, Prev: se-db2-collations, Up: se-db2 14.7.9 Error codes and trouble-shooting information --------------------------------------------------- Errors reported by the `IBMDB2I' engine may originate from two locations. Error values under 2500 originate in DB2 for i. Error values over 2500 originate in the storage engine itself. Occasionally, errors are reported by `IBMDB2I' but, due to the architecture of MySQL, cannot be directly exposed to MySQL client interfaces. In these cases, issuing a `SHOW ERRORS' statement or referring to the MySQL error log may be necessary to determine the cause of a failure. Errors which originate in DB2 for i are usually encountered in the DB2 for i SQL Server Mode job (QSQSRVR) which services the MySQL client connection; additional information about failures can often be found by looking in the job log of the associated QSQSRVR job. Following is the list of codes and messages for errors that occur in DB2 for i that are reported by the `IBMDB2I' engine. %d and %s represent numbers and strings, respectively, that are replaced when the message is displayed. *Error Codes from `IBMDB2I'* Error Error Message Text Code Number 0 Successful 2016 Thread ID is too long 2017 Error creating a SPACE memory object 2018 Error creating a FILE memory object 2019 Error creating a SPACE synchronization token 2020 Error creating a FILE synchronization token 2021 See message %-.7s in joblog for job %-.6s/%-.10s/%-.10s. 2022 Error unlocking a synchronization token when closing a connection 2023 Invalid action specified for an 'object lock' request 2024 Invalid action specified for a savepoint request 2025 Partial keys are not supported with an ICU sort sequence 2026 Error retrieving an ICU sort key 2027 Error converting single-byte sort sequence to UCS-2 2028 An unsupported collation was specified 2029 Validation failed for referenced table of foreign key constraint 2030 Error extracting table for constraint information 2031 Error extracting referenced table for constraint information 2032 Invalid action specified for a 'commitment control' request 2033 Invalid commitment control isolation level specified on 'open' request 2034 Invalid file handle 2036 Invalid option specified for returning data on 'read' request 2037 Invalid orientation specified for 'read' request 2038 Invalid option type specified for 'read' request 2039 Invalid isolation level for starting commitment control 2040 Error unlocking a synchronization token in module QMYALC 2041 Length of space for returned format is not long enough 2042 SQL XA transactions are currently unsupported by this interface 2043 The associated QSQSRVR job was killed or ended unexpectedly. 2044 Error unlocking a synchronization token in module QMYSEI 2045 Error unlocking a synchronization token in module QMYSPO 2046 Error converting input CCSID from short form to long form 2048 Error getting associated CCSID for CCSID conversion 2049 Error converting a string from one CCSID to another 2050 Error unlocking a synchronization token 2051 Error destroying a synchronization token 2052 Error locking a synchronization token 2053 Error recreating a synchronization token 2054 A space handle was not specified for a constraint request 2055 An SQL cursor was specified for a delete request 2057 Error on delete request because current UFCB for connection is not open 2058 An SQL cursor was specified for an object initialization request 2059 An SQL cursor was specified for an object override request 2060 A space handle was not specified for an object override request 2061 An SQL cursor was specified for an information request 2062 An SQL cursor was specified for an object lock request 2063 An SQL cursor was specified for an optimize request 2064 A data handle was not specified for a read request 2065 A row number handle was not specified for a read request 2066 A key handle was not specified for a read request 2067 An SQL cursor was specified for an row estimation request 2068 A space handle was not specified for a row estimation request 2069 An SQL cursor was specified for a release record request 2070 A statement handle was not specified for an 'execute immediate' request 2071 A statement handle was not specified for a 'prepare open' request 2072 An SQL cursor was specified for an update request 2073 The UFCB was not open for read 2074 Error on update request because current UFCB for connection is not open 2075 A data handle was not specified for an update request 2076 An SQL cursor was specified for a write request 2077 A data handle was not specified for a write request 2078 An unknown function was specified on a process request 2079 A share definition was not specified for an 'allocate share' request 2080 A share handle was not specified for an 'allocate share' request 2081 A use count handle was not specified for an 'allocate share' request 2082 A 'records per key' handle was not specified for an information request 2083 Error resolving LOB address 2084 Length of a LOB space is too small 2085 An unknown function was specified for a server request 2086 Object authorization failed. See message %-.7s in joblog for job %-.6s/%-.10s/%-.10s. for more information. 2088 Error locking mutex on server 2089 Error unlocking mutex on server 2090 Error checking for RDB name in RDB Directory 2091 Error creating mutex on server 2094 Error unlocking mutex 2095 Error connecting to server job 2096 Error connecting to server job 2098 Function check occurred while registering parameter spaces. See job log. 2101 End of block 2102 The file has changed and might not be compatible with the MySQL table definition 2103 Error giving pipe to server job 2104 There are open object locks when attempting to deallocate 2105 There is no open lock 2108 The maximum value for the auto_increment data type was exceeded 2109 Error occurred closing the pipe 2110 Error occurred taking a descriptor for the pipe 2111 Error writing to pipe 2112 Server was interrupted 2113 No pipe descriptor exists for reuse 2114 Error occurred during an SQL prepare statement 2115 Error occurred during an SQL open 2122 An unspecified error was returned from the system. Following is the list of error codes and messages that occur within the `IBMDB2I' storage engine. *Error Codes and Messages in `IBMDB2I'* Error Error Message Text Code Number 2501 Error opening codeset conversion from %.64s to %.64s (errno = %d). * Resolution:* Alter the table definition to specify a character set that is supported by the `IBMDB2I' engine. 2502 Invalid %-.10s name '%-.128s. * Resolution:* If a field name, ensure that it is less than the maximum length of 126 characters.If an index name, ensure that the length of the index name plus the length of the table name is less than 121 characters. 2503 Unsupported move from '%-.128s' to '%-.128s' on RENAME TABLE statement. * Resolution:* Moving a table from one schema to another is not supported by the `IBMDB2I' engine. Create a new table in the 'to' schema, copy the data to the new table, and then drop the old table. 2504 The %-.64s character set is not supported. * Resolution:* Try using another character set. 2505 Auto_increment is not allowed for a partitioned table. * Resolution:* Remove the auto_increment attribute from the table or do not partition the table. 2506 Character set conversion error due to unknown encoding scheme %d. * Resolution:* Alter the table definition to ensure that character sets assigned to columns are supported by the `IBMDB2I' engine. 2508 Table '%-.128s' was not found by the storage engine. * Resolution:* A table definition exists in MySQL, but the correspondingtable in DB2 for i is not found. Delete the MySQL table or restore the DB2 table. 2509 Could not resolve to %-.128s in library %-.10s type %-.10s (errno = %d). * Resolution:* Restore the missing IBM i object to the system. 2510 Error on _PGMCALL for program %-.10s in library %-.10s (error = %d). * Resolution:* This is an internal error. 2511 Error on _ILECALL for API '%.128s' (error = %d). *Resolution:* This is an internal error. 2512 Error in iconv() function during character set conversion (errno = %d). *Resolution:* Ensure the text being inserted contains only valid code points for the associated character set. This may be caused by using ENCRYPT or COMPRESS on a text field, resulting in binary data containing invalid characters. 2513 Error from Get Encoding Scheme (QTQGESP) API: %d, %d, %d *Resolution:* This is an internal error. 2514 Error from Get Related Default CCSID (QTQGRDC) API: %d, %d, %d. * Resolution:* This is an internal error. 2515 Data out of range for column '%.192s'. * Resolution:* DB2 for i does not support a zero value for DATE and DATETIME data types. Specify a new value for the column. 2516 Schema name '%.128s' exceeds maximum length of %d characters. * Resolution:* Change the schema name so that its length does not exceed the maximum. For mixed case or lowercase names, permit 2 characters for outer quotation marks. 2517 Multiple collations not supported in a single index. * Resolution:* DB2 for i only supports sort sequences at the table or index level, so all character-based columns in the primary key or index must be using the same collation. Alter the table definition so that all columns use the same collation. 2518 Sort sequence was not found. * Resolution:* Alter the table to use a collation that is supported by the `IBMDB2I' engine. 2519 One or more characters in column %.128s were substituted during conversion. * Resolution:* This is a warning that during the conversion of data from MySQL to DB2 some characters were replaced with substitute characters. 2520 A decimal column exceeded the maximum precision. Data may be truncated. * Resolution:* A decimal column specified on a CREATE TABLE or ALTER TABLE command has greater precision than DB2 permits. Data stored in this column may be truncated. Change the column specification to have a precision less than or equal to 63. 2521 Some data returned by DB2 for table %s could not be converted for MySQL. * Resolution:* This is a warning that some data could not be converted from DB2 to MySQL. Data was likely inserted into the table using DB2 interfaces that is valid data for DB2 but is invalid for MySQL. 2523 Column %.128s contains characters that cannot be converted. * Resolution:* An error occurred converting data from the MySQL character set to the associated DB2 coded character set identifier (CCSID).Omit the incompatible characters or alter the table to specify a different character set for the column. 2524 An invalid name was specified for ibmdb2i_rdb_name. * Resolution:* Specify a valid relational database (RDB) name. 2525 A duplicate key was encountered for index '%.128s'. *Resolution:* : Specify a unique key value for the row. Generally, this error occurs if a unique constraint or index has been applied to the table from a non-MySQL interface. 2528 Some attribute(s) defined for column '%.128s' may not be honored by accesses from DB2.  File: manual.info, Node: merge-storage-engine, Next: memory-storage-engine, Prev: se-db2, Up: storage-engines 14.8 The `MERGE' Storage Engine =============================== * Menu: * merge-table-advantages:: `MERGE' Table Advantages and Disadvantages * merge-table-problems:: `MERGE' Table Problems 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 and index information. You cannot merge `MyISAM' tables in which the columns are listed in a different order, do not have exactly the same columns, or have the indexes in different order. However, any or all of the `MyISAM' tables can be compressed with *Note `myisampack': myisampack. See *Note myisampack::. Differences in table options such as `AVG_ROW_LENGTH', `MAX_ROWS', or `PACK_KEYS' do not matter. 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 *Note 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 *Note `SELECT': select, *Note `DELETE': delete, *Note `UPDATE': update, and *Note `INSERT': 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 *Note `DROP TABLE': 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; Note that 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. Beginning with MySQL 5.1.24, it is also possible to use `ALTER TABLE ... UNION=()' (that is, with an empty *Note `UNION': union. clause) to remove all of the underlying tables. As of MySQL 5.1.15, the underlying table definitions and indexes must conform more closely than previously 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'. For information about the table checks applied prior to MySQL 5.1.15, see *Note merge-table-problems::. As of MySQL 5.1.20, if a `MERGE' table cannot be opened or used because of a problem with an underlying table, *Note `CHECK TABLE': 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'.  File: manual.info, Node: merge-table-advantages, Next: merge-table-problems, Prev: merge-storage-engine, Up: merge-storage-engine 14.8.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 *Note `myisampack': 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 *Note explain::.  File: manual.info, Node: merge-table-problems, Prev: merge-table-advantages, Up: merge-storage-engine 14.8.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 *Note `ALTER TABLE': 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 *Note `INSERT': 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, *Note `REPLACE': replace. does not work as expected. The two key facts are: * *Note `REPLACE': 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 *Note `REPLACE': 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 *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. * `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 *Note `ANALYZE TABLE': analyze-table, *Note `REPAIR TABLE': repair-table, *Note `OPTIMIZE TABLE': optimize-table, *Note `ALTER TABLE': alter-table, *Note `DROP TABLE': drop-table, *Note `DELETE': delete. without a `WHERE' clause, or *Note `TRUNCATE TABLE': 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 *Note `FLUSH TABLES': flush. 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 *Note `FLUSH TABLES': flush. statement after modifying the `MyISAM' tables. * *Note `DROP TABLE': 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 *Note `FLUSH TABLES': flush.) or drop the `MERGE' table before dropping the table. * As of MySQL 5.1.15, the definition of the `MyISAM' tables and the `MERGE' table are checked when the tables are accessed (for example, as part of a *Note `SELECT': select. or *Note `INSERT': 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. Prior to MySQL 5.1.15, table checks are applied as follows: * When you create or alter `MERGE' table, there is no check to ensure that the underlying tables are existing `MyISAM' tables and have identical structures. When the `MERGE' table is used, MySQL checks that the row length for all mapped tables is equal, but this is not foolproof. If you create a `MERGE' table from dissimilar `MyISAM' tables, you are very likely to run into strange problems. * Similarly, if you create a `MERGE' table from non-`MyISAM' tables, or if you drop an underlying table or alter it to be a non-`MyISAM' table, no error for the `MERGE' table occurs until later when you attempt to use it. * Because the underlying `MyISAM' tables need not exist when the `MERGE' table is created, you can create the tables in any order, as long as you do not use the `MERGE' table until all of its underlying tables are in place. Also, if you can ensure that a `MERGE' table will not be used during a given period, you can perform maintenance operations on the underlying tables, such as backing up or restoring them, altering them, or dropping and recreating them. It is not necessary to redefine the `MERGE' table temporarily to exclude the underlying tables while you are operating on them. * The order of indexes in the `MERGE' table and its underlying tables should be the same. If you use *Note `ALTER TABLE': alter-table. to add a `UNIQUE' index to a table used in a `MERGE' table, and then use *Note `ALTER TABLE': 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 *Note `ALTER TABLE': 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), provided that the server was built using the `--with-big-tables' option. (All standard MySQL 5.1 standard binaries are built with this option; for more information, see *Note source-configuration-options::.) It is not possible to merge multiple `MyISAM' tables into a single `MERGE' table that would have more than this number of rows. * The `MERGE' storage engine does not support *Note `INSERT DELAYED': insert-delayed. statements. * Use of underlying `MyISAM' tables of differing row formats with a parent `MERGE' table is currently known to fail. See Bug #32364. * As of MySQL 5.1.23, you cannot change the union list of a nontemporary `MERGE' table when *Note `LOCK TABLES': 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. * As of MySQL 5.1.23, 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)  File: manual.info, Node: memory-storage-engine, Next: example-storage-engine, Prev: merge-storage-engine, Up: storage-engines 14.9 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* *Storage limits* RAM *Transactions* No *Locking Table granularity* *MVCC* No *Geospatial No *Geospatial No data type indexing support* support* *B-tree indexes* Yes *T-tree indexes* No *Hash indexes* Yes *Full-text No *Clustered No *Data caches* N/A search indexes* indexes* *Index caches* N/A *Compressed No *Encrypted data Yes data* Implemented in the server (via encryption functions), rather than in the storage engine.* *Cluster No *Replication Yes *Foreign key No database support support* support* Implemented in the server, rather than in the storage engine.* *Backup / Yes *Query cache Yes *Update Yes point-in-time support* statistics for recovery data dictionary* Implemented in the server, rather than in the storage engine.* When to Use `MEMORY' or MySQL Cluster Developers looking to deploy applications that use the `MEMORY' storage engine for important, highly available, or frequently updated data should consider whether MySQL 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). MySQL 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 *Note `BLOB': blob. and *Note `TEXT': blob.) not supported by `MEMORY'. For a white paper with more detailed comparison of the `MEMORY' storage engine and MySQL Cluster, see Scaling Web Services with MySQL Cluster: An Alternative to the MySQL Memory Storage Engine (http://www.mysql.com/why-mysql/white-papers/mysql-wp_cluster-7.0_Cluster_MEMORY.php). This white paper includes a performance study of the two technologies and a step-by-step guide describing how existing `MEMORY' users can migrate to MySQL Cluster. * 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 *Note `InnoDB': innodb-storage-engine. 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. * Physical 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 *Note `VARCHAR': char. are stored using a fixed length. * `MEMORY' tables cannot contain *Note `BLOB': blob. or *Note `TEXT': blob. 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 *Note `CREATE TABLE': 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 *Note `CREATE TABLE': create-table, or a subsequent *Note `ALTER TABLE': alter-table. or *Note `TRUNCATE TABLE': 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 *Note 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 *Note 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 *Note `INSERT INTO ... SELECT': insert-select. or *Note `LOAD DATA INFILE': load-data. into this file to load the table from a persistent data source. See *Note server-options::, and *Note load-data::. For loading data into `MEMORY' tables accessed by other sessions concurrently, `MEMORY' supports *Note `INSERT DELAYED': insert-delayed. See *Note insert-delayed::. * `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 *Note `DELETE': 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 *Note `DELETE': delete. or *Note `TRUNCATE TABLE': truncate-table. to remove all rows, or remove the table altogether using *Note `DROP TABLE': 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 *Note `CREATE TABLE': 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'.  File: manual.info, Node: example-storage-engine, Next: federated-storage-engine, Prev: memory-storage-engine, Up: storage-engines 14.10 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 `configure' with the `--with-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.  File: manual.info, Node: federated-storage-engine, Next: archive-storage-engine, Prev: example-storage-engine, Up: storage-engines 14.11 The `FEDERATED' Storage Engine ==================================== * Menu: * federated-description:: `FEDERATED' Storage Engine Overview * federated-create:: How to Create `FEDERATED' Tables * federated-usagenotes:: `FEDERATED' Storage Engine Notes and Tips * federated-storage-engine-resources:: `FEDERATED' Storage Engine Resources 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 `configure' with the `--with-federated-storage-engine' option. Beginning with MySQL 5.1.26, 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.  File: manual.info, Node: federated-description, Next: federated-create, Prev: federated-storage-engine, Up: federated-storage-engine 14.11.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 *Note 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 *Note `mysql_real_query()': mysql-real-query. to send the statement. To read a result set, it uses *Note `mysql_store_result()': mysql-store-result. and fetches rows one at a time using *Note `mysql_fetch_row()': mysql-fetch-row.  File: manual.info, Node: federated-create, Next: federated-usagenotes, Prev: federated-description, Up: federated-storage-engine 14.11.2 How to Create `FEDERATED' Tables ---------------------------------------- * Menu: * federated-create-connection:: Creating a `FEDERATED' Table Using `CONNECTION' * federated-create-server:: Creating a `FEDERATED' Table Using `CREATE SERVER' 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 *Note `SHOW CREATE TABLE': 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 *Note `CREATE SERVER': 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.  File: manual.info, Node: federated-create-connection, Next: federated-create-server, Prev: federated-create, Up: federated-create 14.11.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 *Note `CREATE TABLE': 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 (*Note `SELECT': select, *Note `INSERT': insert, *Note `UPDATE': 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'  File: manual.info, Node: federated-create-server, Prev: federated-create-connection, Up: federated-create 14.11.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 *Note `CREATE SERVER': create-server. statement to define the server connection parameters, just as you would with the `CONNECTION' string. The format of the *Note `CREATE SERVER': create-server. statement is: CREATE SERVERSERVER_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 *Note `CREATE SERVER': 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 *Note `CREATE SERVER': create-server, see *Note create-server::. The *Note `CREATE SERVER': create-server. statement accepts the same arguments as the `CONNECTION' string. The *Note `CREATE SERVER': 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 *Note `CREATE SERVER': 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 This table describes the correspondence between parameters in a connection string, options in the *Note `CREATE SERVER': create-server. statement, and the columns in the `mysql.servers' table. Description `CONNECTION' *Note `CREATE `mysql.servers' string SERVER': column create-server. option Connection scheme SCHEME `wrapper_name' `Wrapper' 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'  File: manual.info, Node: federated-usagenotes, Next: federated-storage-engine-resources, Prev: federated-create, Up: federated-storage-engine 14.11.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 per se. Because access to the table is handled remotely, it is the remote table that supports the indexes. 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 *Note `VARCHAR': char, *Note `TEXT': blob. or *Note `BLOB': 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 *Note `SELECT': select, *Note `INSERT': insert, *Note `UPDATE': update, and *Note `DELETE': delete, but not *Note `HANDLER': handler. * The `FEDERATED' storage engine supports *Note `SELECT': select, *Note `INSERT': insert, *Note `UPDATE': update, *Note `DELETE': delete, *Note `TRUNCATE TABLE': truncate-table, and indexes. It does not support *Note `ALTER TABLE': alter-table, or any Data Definition Language statements that directly affect the structure of the table, other than *Note `DROP TABLE': drop-table. The current implementation does not use prepared statements. * `FEDERATED' accepts *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. statements, but if a duplicate-key violation occurs, the statement fails with an error. * Performance on a `FEDERATED' table when performing bulk inserts (for example, on a *Note `INSERT INTO ... SELECT ...': insert-select. statement) is slower than with other table types because each selected row is treated as an individual *Note `INSERT': insert. statement on the `FEDERATED' table. * Transactions are not supported. * Before MySQL 5.1.21, for a multiple-row insert into a `FEDERATED' table that refers to a remote transactional table, if the insert failed for a row due to constraint failure, the remote table would contain a partial commit (the rows preceding the failed one) instead of rolling back the statement completely. This occurred because the rows were treated as individual inserts. As of MySQL 5.1.21, `FEDERATED' performs bulk-insert handling such that multiple rows are sent to the remote table in a batch. This provides a performance improvement and enables the remote table to perform improvement. 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 *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. * 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 *Note `CREATE SERVER': create-server. statement to create a server connection. * The `insert_id' and `timestamp' options are not propagated to the data provider. * Any *Note `DROP TABLE': 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. Beginning with MySQL 5.1.15, it is no longer possible to create such tables at all.  File: manual.info, Node: federated-storage-engine-resources, Prev: federated-usagenotes, Up: federated-storage-engine 14.11.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'.  File: manual.info, Node: archive-storage-engine, Next: csv-storage-engine, Prev: federated-storage-engine, Up: storage-engines 14.12 The `ARCHIVE' Storage Engine ================================== The `ARCHIVE' storage engine is used for storing large amounts of data without indexes in a very small footprint. *`ARCHIVE' Storage Engine Features* *Storage limits* None *Transactions* No *Locking Table granularity* *MVCC* No *Geospatial Yes *Geospatial No data type indexing support* support* *B-tree indexes* No *T-tree indexes* No *Hash indexes* No *Full-text No *Clustered No *Data caches* No search indexes* indexes* *Index caches* No *Compressed Yes *Encrypted data Yes data* Implemented in the server (via encryption functions), rather than in the storage engine.* *Cluster No *Replication Yes *Foreign key No database support support* support* Implemented in the server, rather than in the storage engine.* *Backup / Yes *Query cache Yes *Update Yes point-in-time support* statistics for recovery data dictionary* Implemented in the server, rather than in the storage engine.* The `ARCHIVE' storage engine is included in MySQL binary distributions. To enable this storage engine if you build MySQL from source, invoke `configure' with the `--with-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 *Note `SHOW ENGINES': 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'. (Prior to MySQL 5.1.15, a metadata file with an extension of `.ARM' is created as well.) An `.ARN' file may appear during optimization operations. The `ARCHIVE' engine supports *Note `INSERT': insert. and *Note `SELECT': select, but not *Note `DELETE': delete, *Note `REPLACE': replace, or *Note `UPDATE': update. It does support `ORDER BY' operations, *Note `BLOB': blob. columns, and basically all but spatial data types (see *Note mysql-spatial-datatypes::). The `ARCHIVE' engine uses row-level locking. As of MySQL 5.1.6, 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 *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': alter-table. statements to specify the initial sequence value for a new table or reset the sequence value for an existing table, respectively. As of MySQL 5.1.6, the `ARCHIVE' engine ignores *Note `BLOB': blob. columns if they are not requested and scans past them while reading. Formerly, the following two statements had the same cost, but as of 5.1.6, the second is much more efficient than the first: SELECT a, b, blob_col FROM archive_table; SELECT a, b FROM archive_table; *Storage:* Rows are compressed as they are inserted. The `ARCHIVE' engine uses `zlib' lossless data compression (see `http://www.zlib.net/'). You can use *Note `OPTIMIZE TABLE': optimize-table. to analyze the table and pack it into a smaller format (for a reason to use *Note `OPTIMIZE TABLE': optimize-table, see later in this section). The engine also supports *Note `CHECK TABLE': check-table. There are several types of insertions that are used: * An *Note `INSERT': 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 *Note `SELECT': select. forces a flush to occur, unless the only insertions that have come in were *Note `INSERT DELAYED': insert-delayed. (those flush as necessary). See *Note insert-delayed::. * 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 *Note `SELECT': 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 *Note `SELECT': select. operation performs a complete table scan: When a *Note `SELECT': select. occurs, it finds out how many rows are currently available and reads that number of rows. *Note `SELECT': select. is performed as a consistent read. Note that lots of *Note `SELECT': select. statements during insertion can deteriorate the compression, unless only bulk or delayed inserts are used. To achieve better compression, you can use *Note `OPTIMIZE TABLE': optimize-table. or *Note `REPAIR TABLE': repair-table. The number of rows in `ARCHIVE' tables reported by *Note `SHOW TABLE STATUS': show-table-status. is always accurate. See *Note optimize-table::, *Note repair-table::, and *Note show-table-status::. *Warning*: *Known issue*: After a binary upgrade to MySQL 5.1 from a MySQL 5.0 installation that contains *Note `ARCHIVE': archive-storage-engine. tables: * Before MySQL 5.1.42, accessing those tables will cause the server to crash, even if you have run *Note `mysql_upgrade': mysql-upgrade. or *Note `CHECK TABLE ... FOR UPGRADE': check-table. * As of MySQL 5.1.42, the server will not open 5.0 *Note `ARCHIVE': archive-storage-engine. tables at all. In either case, the solution is to use *Note `mysqldump': mysqldump. to dump all 5.0 *Note `ARCHIVE': archive-storage-engine. tables before upgrading, and reload them into MySQL 5.1 after upgrading. This problem is fixed in MySQL 5.6.4: The server can open *Note `ARCHIVE': archive-storage-engine. tables created in MySQL 5.0. However, it remains the recommended upgrade procedure to dump 5.0 *Note `ARCHIVE': archive-storage-engine. tables before upgrading and reload after upgrading. * Additional Resources * * A forum dedicated to the `ARCHIVE' storage engine is available at `http://forums.mysql.com/list.php?112'.  File: manual.info, Node: csv-storage-engine, Next: blackhole-storage-engine, Prev: archive-storage-engine, Up: storage-engines 14.13 The `CSV' Storage Engine ============================== * Menu: * se-csv-repair:: Repairing and Checking CSV Tables * se-csv-limitations:: CSV Limitations The `CSV' storage engine stores data in text files using comma-separated values format. To enable the `CSV' storage engine if you build MySQL from source, invoke `configure' with the `--with-csv-storage-engine' option. 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) Starting with MySQL 5.1.9, 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.  File: manual.info, Node: se-csv-repair, Next: se-csv-limitations, Prev: csv-storage-engine, Up: csv-storage-engine 14.13.1 Repairing and Checking CSV Tables ----------------------------------------- *Functionality introduced in version 5.1.9* 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 *Note `SELECT': 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*: Note that 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.  File: manual.info, Node: se-csv-limitations, Prev: se-csv-repair, Up: csv-storage-engine 14.13.2 CSV Limitations ----------------------- The `CSV' storage engine does not support indexing. Partitioning is not supported for tables using the `CSV' storage engine. Beginning with MySQL 5.1.12, it is no longer possible to create partitioned `CSV' tables. (See Bug #19307) Beginning with MySQL 5.1.23, 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)  File: manual.info, Node: blackhole-storage-engine, Prev: csv-storage-engine, Up: storage-engines 14.14 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 `configure' with the `--with-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 *Note `SHOW ENGINES': 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. *Note*: When using the row based format for the binary log, updates and deletes are skipped, and neither logged nor applied. For this reason, you should use STATEMENT for the binary logging format, and not ROW or MIXED. 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: Replication using `BLACKHOLE' for filtering The master writes to its binary log. The `dummy' *Note `mysqld': 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 *Note 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 *Note `mysqld': mysqld. process on the replication master host. This type of setup can be repeated with additional replication slaves. *Note `INSERT': insert. triggers for `BLACKHOLE' tables work as expected. However, because the `BLACKHOLE' table does not actually store any data, *Note `UPDATE': update. and *Note `DELETE': 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' storage engine does not support *Note `INSERT DELAYED': insert-delayed, *Note `LOCK TABLES': lock-tables, or *Note `UNLOCK TABLES': lock-tables. statements prior to MySQL 5.1.19. As of MySQL 5.1.4, 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 *Note 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;  File: manual.info, Node: ha-overview, Next: replication, Prev: storage-engines, Up: Top 15 High Availability and Scalability ************************************ * Menu: * ha-ovm-template:: Oracle VM Template for MySQL Enterprise Edition * ha-drbd:: Overview of MySQL with DRBD/Pacemaker/Corosync/Oracle Linux * ha-wfc:: Overview of MySQL with Windows Failover Clustering * ha-vm:: Using MySQL within an Amazon EC2 Instance * ha-zfs-replication:: Using ZFS Replication * ha-memcached:: Using MySQL with `memcached' * mysql-proxy:: MySQL Proxy Data is the currency of today's web, mobile, social, enterprise and cloud applications. Ensuring data is always available is a top priority for any organization. Minutes of downtime can result in significant loss of revenue and reputation. There is no `one size fits all' approach to delivering High Availability (HA). Unique application attributes, business requirements, operational capabilities and legacy infrastructure can all influence HA technology selection. And technology is only one element in delivering HA: people and processes are just as critical as the technology itself. MySQL is deployed into many applications demanding availability and scalability. *Availability* refers to 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. Scalability (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_scalability) refers to the ability to spread both the database and the load of your application queries across multiple MySQL servers. Because each application has different operational and availability requirements, MySQL offers a range of certified and supported solutions, delivering the appropriate levels of High Availability (HA) and scalability to meet service level requirements. Such solutions extend from replication, through virtualization and geographically redundant, multi-data center solutions delivering 99.999% uptime. Selecting the right high availability solution for an application largely depends on: * The level of availability required. * The type of application being deployed. * Accepted best practices within your own environment. The primary solutions supported by MySQL include: * MySQL Replication. Learn more: *Note replication:: * MySQL Cluster. Learn more: *Note mysql-cluster:: * Oracle VM Template for MySQL. Learn more: *Note ha-ovm-template::. * MySQL with DRBD with Corosync and Pacemaker. Learn more: *Note ha-drbd::. * MySQL with Windows Failover Clustering. Learn more: *Note ha-wfc::. * MySQL with Solaris Cluster. Learn more about Solaris Cluster. (http://www.oracle.com/technetwork/server-storage/solaris-cluster/overview/index.html) Further options are available using third-party solutions. Each architecture used to achieve highly available database services is differentiated by the levels of uptime it offers. These architectures can be grouped into three main categories: * Data Replication. * Clustered & Virtualized Systems. * Shared-Nothing, Geographically-Replicated Clusters. As illustrated in the following figure, each of these architectures offers progressively higher levels of uptime, which must be balanced against potentially greater levels of cost and complexity that each can incur. Simply deploying a high availability architecture is not a guarantee of actually delivering HA. In fact, a poorly implemented and maintained shared-nothing cluster could easily deliver lower levels of availability than a simple data replication solution. FIGURE GOES HERE: Tradeoffs: Cost and Complexity versus Availability The following table compares the HA and Scalability capabilities of the various MySQL solutions: *Feature Comparison of MySQL HA Solutions* Requirement MySQL DRBD Oracle VM MySQL Cluster Replication Template *Availability* Platform All Supported Linux Oracle Linux All Supported Support by MySQL by MySQL Server Cluster (http://www.mysql.com/support/supportedplatforms/database.html) (http://www.mysql.com/support/supportedplatforms/cluster.html) Automated IP No Yes Yes Depends on Failover Connector and Configuration Automated No Yes Yes Yes Database Failover Automatic No Yes N/A - Shared Yes Data Storage Resynchronization Typical User / Script Configuration Configuration 1 Second and Failover Time Dependent Dependent, 60 Dependent, 60 Less seconds and seconds and Above Above Synchronous No, Yes N/A - Shared Yes Replication Asynchronous Storage and Semisynchronous Shared Storage No, No, Yes No, Distributed Distributed Distributed Geographic Yes Yes, via Yes, via Yes, via redundancy MySQL MySQL MySQL support Replication Replication Replication Update Schema No No No Yes On-Line *Scalability* Number of One Master, One Active One Active 255 Nodes Multiple (primary), (primary), Slaves one Passive one Passive (secondary) (secondary) Node Node Built-in Load Reads, via Reads, via Reads, via Yes, Reads Balancing MySQL MySQL MySQL and Writes Replication Replication Replication & During Failover Supports Yes Yes Yes Yes Read-Intensive Workloads Supports Yes, via Yes, via Yes, via Yes, via Write-IntensiveApplication-LevelApplication-LevelApplication-LevelAuto-Sharding Workloads Sharding Sharding to Sharding to Multiple Multiple Active/Passive Active/Passive Pairs Pairs Scale On-Line No No No Yes (add nodes, repartition, etc.)  File: manual.info, Node: ha-ovm-template, Next: ha-drbd, Prev: ha-overview, Up: ha-overview 15.1 Oracle VM Template for MySQL Enterprise Edition ==================================================== Virtualization is a key technology to enable data center efficiency and high availability while providing the foundation for cloud computing. Integrating MySQL Enterprise Edition with Oracle Linux, the Oracle VM Template is the fastest, easiest, and most reliable way to provision virtualized MySQL instances, enabling users to meet the explosive demand for highly available services. The Oracle VM Template enables rapid deployment and eliminates manual configuration efforts. It provides a preinstalled and pre-configured virtualized MySQL 5.5 Enterprise Edition software image running on Oracle Linux and Oracle VM, certified for production use. The MySQL software image has undergone extensive integration and quality assurance testing as part of the development process. In addition to rapid provisioning, MySQL users also benefit from the integrated high availability features of Oracle VM which are designed to enable organizations to meet stringent SLA (Service Level Agreement) demands through a combination of: * *Automatic recovery from failures*, with Oracle VM automatically restarting failed instances on available servers in the server pool after outages of the physical server, VM or MySQL database. * *Live Migration*, enabling operations staff to move running instances of MySQL to alternative hosts within a server pool during maintenance operations. Instructions for the creation, deployment and use of the Oracle VM Template for MySQL Enterprise Edition are available from: * The Oracle VM Template for MySQL Enterprise Edition whitepaper: `http://www.mysql.com/why-mysql/white-papers/mysql_wp_oracle-vm-template-for-mee.php'. * The README file accompanying the download of the Template. To download the Oracle VM Template for MySQL Enterprise, go to `http://edelivery.oracle.com/oraclevm' and follow these instructions: * Complete your registration information (Name, Company Name, Email Address and Country) and click on the download agreement. * Select "Oracle VM Templates" from the "Select a Product Pack" pull-down menu and click "Go". * Select MySQL Enterprise from the list of Oracle VM Templates. * Download and unzip the files and refer to the README for further instructions.  File: manual.info, Node: ha-drbd, Next: ha-wfc, Prev: ha-ovm-template, Up: ha-overview 15.2 Overview of MySQL with DRBD/Pacemaker/Corosync/Oracle Linux ================================================================ DRBD (Distributed Replication Block Device) is one of the leading solutions for MySQL HA (High Availability). When combined with Pacemaker and Corosync, users have: * An end-to-end, integrated stack of mature and proven open source technologies, fully supported by Oracle (as part of MySQL Enterprise Edition). * Automatic failover and recovery for service continuity. * Mirroring, via synchronous replication, to ensure failover between nodes without the risk of losing committed transactions. * Building of HA clusters from commodity hardware, without the requirement for shared-storage. The following figure illustrates the stack that can be used to deliver a level of High Availability for the MySQL service. At the lowest level, 2 hosts are required in order to provide physical redundancy; if using a virtual environment, those 2 hosts should be on different physical machines. It is an important feature that no shared storage is required. At any point in time, the services will be active on one host and in standby mode on the other. Pacemaker and Corosync combine to provide the clustering layer that sits between the services and the underlying hosts and operating systems. Pacemaker is responsible for starting and stopping services, ensuring that they are running on exactly one host, thus delivering high availability and avoiding data corruption. Corosync provides the underlying messaging infrastructure between the nodes that enables Pacemaker to do its job; it also handles the nodes membership within the cluster and informs Pacemaker of any changes. FIGURE GOES HERE: MySQL, DRBD, Pacemaker, and Corosync Stack The core Pacemaker process does not have built-in knowledge of the specific services to be managed; instead, it uses agents that provide a wrapper for the service-specific actions. For example, in this solution we use agents for Virtual IP Addresses, MySQL and DRBD: these are all existing agents and come packaged with Pacemaker. The essential services managed by Pacemaker in this configuration are DRBD, MySQL and the Virtual IP Address that applications use to connect to the active MySQL service. DRBD synchronizes data at the block device (typically a spinning or solid state disk) - transparent to the application, database and even the file system. DRBD requires the use of a journaling file system such as `ext3' or `ext4'. For this solution, it acts in an active-standby mode: at any point in time, the directories being managed by DRBD are accessible for reads and writes on exactly one of the two hosts and inaccessible (even for reads) on the other. Any changes made on the active host are synchronously replicated to the standby host by DRBD. Download the following guide for detailed instructions on installing, configuring, provisioning and testing the complete MySQL and DRBD stack, including: * MySQL Database. * DRBD kernel module and userland utilities. * Pacemaker and Corosync cluster messaging and management processes. * Oracle Linux operating system. Download the guide at: `http://www.mysql.com/why-mysql/white-papers/mysql-high-availability-drbd-configuration-deployment-guide/'. * Support for DRBD * The complete DRBD stack for MySQL has been certified by Oracle, and commercial support is available as part of MySQL Enterprise Edition (http://www.mysql.com/products/enterprise/) and Oracle Linux Premier Support (http://www.oracle.com/us/technologies/linux/support/overview/index.html), providing a single point of contact for the entire stack, whether issues relate to the operating system, DRBD, clustering software or MySQL.  File: manual.info, Node: ha-wfc, Next: ha-vm, Prev: ha-drbd, Up: ha-overview 15.3 Overview of MySQL with Windows Failover Clustering ======================================================= Microsoft Windows is consistently ranked as the top development platform for MySQL, based on surveys of the MySQL user community. MySQL Enterprise Edition is certified and supported with Windows Server 2008 R2 Failover Clustering (WSFC), enabling organizations to safely deploy business-critical applications demanding high levels of availability using Microsoft's native Windows clustering services. The following figure illustrates the integration of MySQL with Windows Server Failover Clustering to provide a highly available service: FIGURE GOES HERE: Typical MySQL HA Configuration with Windows Server Failover Clustering In this architecture, MySQL is deployed in an Active / Passive configuration. Failures of either MySQL or the underlying server are automatically detected and the MySQL instance is restarted on the Passive node. Applications accessing the database, as well as any MySQL replication slaves, can automatically reconnect to the new MySQL process using the same Virtual IP address once MySQL recovery has completed and it starts accepting connections. MySQL with Windows Failover Clustering requires at least 2 servers within the cluster together with shared storage (for example, FC-AL SAN or iSCSI disks). The MySQL binaries and data files are stored in the shared storage and Windows Failover Clustering ensures that only one of the cluster nodes will access those files at any point in time. Clients connect to the MySQL service through a Virtual IP Address (VIP). In the event of failover they experience a brief loss of connection, but otherwise do not need to be aware that the failover has happened, other than to handle the failure of any transactions that were active when the failover occurred. You can learn more about configuring MySQL with Windows Server Failover Clustering from the whitepaper posted here: `http://www.mysql.com/why-mysql/white-papers/mysql_wp_windows_failover_clustering.php' For background and usage information about Windows Server Failover Clustering, see these pages on the Microsoft Technet site: * Failover Clustering (http://technet.microsoft.com/en-us/library/cc725923(v=ws.10).aspx) * Failover Clusters in Windows Server 2008 R2 (http://technet.microsoft.com/en-us/library/ff182338(v=ws.10).aspx)  File: manual.info, Node: ha-vm, Next: ha-zfs-replication, Prev: ha-wfc, Up: ha-overview 15.4 Using MySQL within an Amazon EC2 Instance ============================================== * Menu: * ha-vm-aws-setup:: Setting Up MySQL on an EC2 AMI * ha-vm-aws-instance:: EC2 Instance Limitations * ha-vm-aws-deploy:: Deploying a MySQL Database Using EC2 The Amazon Elastic Compute Cloud (EC2) service provides virtual servers that you can build and deploy to run a variety of different applications and services, including MySQL. The EC2 service is based around the Xen framework, supporting x86, Linux based, platforms with individual instances of a virtual machine referred to as an Amazon Machine Image (AMI). You have complete (root) access to the AMI instance that you create, enabling you to configure and install your AMI in any way you choose. To use EC2, you create an AMI based on the configuration and applications that you intend to use, and upload the AMI to the Amazon Simple Storage Service (S3). From the S3 resource, you can deploy one or more copies of the AMI to run as an instance within the EC2 environment. The EC2 environment provides management and control of the instance and contextual information about the instance while it is running. Because you can create and control the AMI, the configuration, and the applications, you can deploy and create any environment you choose. This includes a basic MySQL server in addition to more extensive replication, HA and scalability scenarios that enable you to take advantage of the EC2 environment, and the ability to deploy additional instances as the demand for your MySQL services and applications grow. To aid the deployment and distribution of work, three different Amazon EC2 instances are available, small (identified as `m1.small'), large (`m1.large') and extra large (`m1.xlarge'). The different types provide different levels of computing power measured in EC2 computer units (ECU). A summary of the different instance configurations is shown in the following table. This table lists EC2 instance attributes and outlines attribute configuration settings for Small, Large, and Extra Large EC2 instances. EC2 Attribute Small Large Extra Large Platform 32-bit 64-bit 64-bit CPU cores 1 2 4 ECUs 1 4 8 RAM 1.7GB 7.5GB 15GB Storage 150GB 840GB 1680GB I/O Performance Medium High High The typical model for deploying and using MySQL within the EC2 environment is to create a basic AMI that you can use to hold your database data and application. Once the basic environment for your database and application has been created you can then choose to deploy the AMI to a suitable instance. Here the flexibility of having an AMI that can be re-deployed from the small to the large or extra large EC2 instance makes it easy to upgrade the hardware environment without rebuilding your application or database stack. To get started with MySQL on EC2, including information on how to set up and install MySQL within an EC2 installation and how to port and migrate your data to the running instance, see *Note ha-vm-aws-setup::. For tips and advice on how to create a scalable EC2 environment using MySQL, including guides on setting up replication, see *Note ha-vm-aws-deploy::.  File: manual.info, Node: ha-vm-aws-setup, Next: ha-vm-aws-instance, Prev: ha-vm, Up: ha-vm 15.4.1 Setting Up MySQL on an EC2 AMI ------------------------------------- There are many different ways of setting up an EC2 AMI with MySQL, including using any of the pre-configured AMIs supplied by Amazon. The default _Getting Started_ AMI provided by Amazon uses Fedora Core 4, and you can install MySQL by using `yum': shell> yum install mysql This installs both the MySQL server and the Perl DBD::mysql driver for the Perl DBI API. Alternatively, you can use one of the AMIs that include MySQL within the standard installation. Finally, you can also install a standard version of MySQL downloaded from the MySQL Web site. The installation process and instructions are identical to any other installation of MySQL on Linux. See *Note installing::. The standard configuration for MySQL places the data files in the default location, `/var/lib/mysql'. The default data directory on an EC2 instance is `/mnt' (although on the large and extra large instance you can alter this configuration). You must edit `/etc/my.cnf' to set the `datadir' option to point to the larger storage area. *Important*: The first time you use the main storage location within an EC2 instance it needs to be initialized. The initialization process starts automatically the first time you write to the device. You can start using the device right away, but the write performance of the new device is significantly lower on the initial writes until the initialization process has finished. To avoid this problem when setting up a new instance, you should start the initialization process before populating your MySQL database. One way to do this is to use `dd' to write to the file system: root-shell> dd if=/dev/zero of=initialize bs=1024M count=50 The preceding creates a 50GB on the file system and starts the initialization process. Delete the file once the process has finished. The initialization process can be time-consuming. On the small instance, initialization takes between two and three hours. For the large and extra large drives, the initialization can be 10 or 20 hours, respectively. In addition to configuring the correct storage location for your MySQL data files, also consider setting the following other settings in your instance before you save the instance configuration for deployment: * Set the MySQL server ID, so that when you use it for replication, the ID information is set correctly. * Enabling binary logging, so that replication can be initialized without starting and stopping the server. * Set the caching and memory parameters for your storage engines. There are no limitations or restrictions on what storage engines you use in your EC2 environment. Choose a configuration, possibly using one of the standard configurations provided with MySQL appropriate for the instance on which you expect to deploy. The large and extra large instances have RAM that can be dedicated to caching. Be aware that if you choose to install `memcached' on the servers as part of your application stack you must ensure there is enough memory for both MySQL and `memcached'. Once you have configured your AMI with MySQL and the rest of your application stack, save the AMI so that you can deploy and reuse the instance. Once you have your application stack configured in an AMI, populating your MySQL database with data should be performed by creating a dump of your database using `mysqldump', transferring the dump to the EC2 instance, and then reloading the information into the EC2 instance database. Before using your instance with your application in a production situation, be aware of the limitations of the EC2 instance environment. See *Note ha-vm-aws-instance::. To begin using your MySQL AMI, consult the notes on deployment. See *Note ha-vm-aws-deploy::.  File: manual.info, Node: ha-vm-aws-instance, Next: ha-vm-aws-deploy, Prev: ha-vm-aws-setup, Up: ha-vm 15.4.2 EC2 Instance Limitations ------------------------------- Be aware of the following limitations of the EC2 instances before deploying your applications. Although these shouldn't affect your ability to deploy within the Amazon EC2 environment, they may alter the way you setup and configure your environment to support your application. * Data stored within instances is not persistent. If you create an instance and populate the instance with data, then the data only remains in place while the machine is running, and does not survive a reboot. If you shut down the instance, any data it contained is lost. To ensure that you do not lose information, take regular backups using *Note `mysqldump': mysqldump. If the data being stored is critical, consider using replication to keep a `live' backup of your data in the event of a failure. When creating a backup, write the data to the Amazon S3 service to avoid the transfer charges applied when copying data offsite. * EC2 instances are not persistent. If the hardware on which an instance is running fails, the instance is shut down. This can lead to loss of data or service. However, if you use EBS, you can attach an EBS storage volume to an EC2 instance, and that EBS volume is persistent. Like a disk, an EBS volume can fail, but it is possible to create point-in-time snapshots of the volume. Snapshots are persisted to Amazon S3 and can be used to restore data in the event of volume failure. * To replicate your EC2 instances to a non-EC2 environment, be aware of the transfer costs to and from the EC2 service. Data transfer between different EC2 instances is free, so using replication within the EC2 environment does not incur additional charges. * Certain HA features are either not directly supported, or have limiting factors or problems that could reduce their utility. For example, using DRBD or MySQL Cluster might not work. The default storage configuration is also not redundant. You can use software-based RAID to improve redundancy, but this implies a further performance hit.  File: manual.info, Node: ha-vm-aws-deploy, Prev: ha-vm-aws-instance, Up: ha-vm 15.4.3 Deploying a MySQL Database Using EC2 ------------------------------------------- Because you cannot guarantee the uptime and availability of your EC2 instances, when deploying MySQL within the EC2 environment, use an approach that enables you to easily distribute work among your EC2 instances. There are a number of ways of doing this. Using sharding techniques, where you split the application across multiple servers dedicating specific blocks of your dataset and users to different servers is an effective way of doing this. As a general rule, it is easier to create more EC2 instances to support more users than to upgrade the instance to a larger machine. The EC2 architecture works best when you treat the EC2 instances as temporary, cache-based solutions, rather than as a long-term, high availability solution. In addition to using multiple machines, take advantage of other services, such as `memcached' to provide additional caching for your application to help reduce the load on the MySQL server so that it can concentrate on writes. On the large and extra large instances within EC2, the RAM available can provide a large memory cache for data. Most types of scale-out topology that you would use with your own hardware can be used and applied within the EC2 environment. However, use the limitations and advice already given to ensure that any potential failures do not lose you any data. Also, because the relative power of each EC2 instance is so low, be prepared to alter your application to use sharding and add further EC2 instances to improve the performance of your application. For example, take the typical scale-out environment shown following, where a single master replicates to one or more slaves (three in this example), with a web server running on each replication slave. Typical standard scale-out structure You can reproduce this structure completely within the EC2 environment, using an EC2 instance for the master, and one instance for each of the web and MySQL slave servers. *Note*: Within the EC2 environment, internal (private) IP addresses used by the EC2 instances are constant. Always use these internal addresses and names when communicating between instances. Only use public IP addresses when communicating with the outside world - for example, when publicizing your application. To ensure reliability of your database, add at least one replication slave dedicated to providing an active backup and storage to the Amazon S3 facility. You can see an example of this in the following topology. Typical standard scale-out structure with backup using EC2 *Using `memcached'* within your EC2 instances should provide better performance. The large and extra large instances have a significant amount of RAM. To use `memcached' in your application, when loading information from the database, first check whether the item exists in the cache. If the data you are looking for exists in the cache, use it. If not, reload the data from the database and populate the cache. *Sharding* divides up data in your entire database by allocating individual machines or machine groups to provide a unique set of data according to an appropriate group. For example, you might put all users with a surname ending in the letters A-D onto a single server. When a user connects to the application and their surname is known, queries can be redirected to the appropriate MySQL server. When using sharding with EC2, separate the web server and MySQL server into separate EC2 instances, and then apply the sharding decision logic into your application. Once you know which MySQL server you should be using for accessing the data you then distribute queries to the appropriate server. You can see a sample of this in the following illustration. Using sharding in EC2 to spread the load *Warning*: With sharding and EC2, be careful that the potential for failure of an instance does not affect your application. If the EC2 instance that provides the MySQL server for a particular shard fails, then all of the data on that shard becomes unavailable.  File: manual.info, Node: ha-zfs-replication, Next: ha-memcached, Prev: ha-vm, Up: ha-overview 15.5 Using ZFS Replication ========================== * Menu: * ha-zfs-config:: Using ZFS for File System Replication * ha-zfs-mysql:: Configuring MySQL for ZFS Replication * ha-zfs-mysql-recovery:: Handling MySQL Recovery with ZFS To support high availability environments, providing an instant copy of the information on both the currently active machine and the hot backup is a critical part of the HA solution. There are many solutions to this problem, including *Note replication:: and *Note ha-drbd::. The ZFS file system provides functionality to create a snapshot of the file system contents, transfer the snapshot to another machine, and extract the snapshot to recreate the file system. You can create a snapshot at any time, and you can create as many snapshots as you like. By continually creating, transferring, and restoring snapshots, you can provide synchronization between one or more machines in a fashion similar to DRBD. The following example shows a simple Solaris system running with a single ZFS pool, mounted at `/scratchpool': Filesystem size used avail capacity Mounted on /dev/dsk/c0d0s0 4.6G 3.7G 886M 82% / /devices 0K 0K 0K 0% /devices ctfs 0K 0K 0K 0% /system/contract proc 0K 0K 0K 0% /proc mnttab 0K 0K 0K 0% /etc/mnttab swap 1.4G 892K 1.4G 1% /etc/svc/volatile objfs 0K 0K 0K 0% /system/object /usr/lib/libc/libc_hwcap1.so.1 4.6G 3.7G 886M 82% /lib/libc.so.1 fd 0K 0K 0K 0% /dev/fd swap 1.4G 40K 1.4G 1% /tmp swap 1.4G 28K 1.4G 1% /var/run /dev/dsk/c0d0s7 26G 913M 25G 4% /export/home scratchpool 16G 24K 16G 1% /scratchpool The MySQL data is stored in a directory on `/scratchpool'. To help demonstrate some of the basic replication functionality, there are also other items stored in `/scratchpool' as well: total 17 drwxr-xr-x 31 root bin 50 Jul 21 07:32 DTT/ drwxr-xr-x 4 root bin 5 Jul 21 07:32 SUNWmlib/ drwxr-xr-x 14 root sys 16 Nov 5 09:56 SUNWspro/ drwxrwxrwx 19 1000 1000 40 Nov 6 19:16 emacs-22.1/ To create a snapshot of the file system, you use `zfs snapshot', specifying the pool and the snapshot name: root-shell> zfs snapshot scratchpool@snap1 To list the snapshots already taken: root-shell> zfs list -t snapshot NAME USED AVAIL REFER MOUNTPOINT scratchpool@snap1 0 - 24.5K - scratchpool@snap2 0 - 24.5K - The snapshots themselves are stored within the file system metadata, and the space required to keep them varies as time goes on because of the way the snapshots are created. The initial creation of a snapshot is very quick, because instead of taking an entire copy of the data and metadata required to hold the entire snapshot, ZFS records only the point in time and metadata of when the snapshot was created. As more changes to the original file system are made, the size of the snapshot increases because more space is required to keep the record of the old blocks. If you create lots of snapshots, say one per day, and then delete the snapshots from earlier in the week, the size of the newer snapshots might also increase, as the changes that make up the newer state have to be included in the more recent snapshots, rather than being spread over the seven snapshots that make up the week. You cannot directly back up the snapshots because they exist within the file system metadata rather than as regular files. To get the snapshot into a format that you can copy to another file system, tape, and so on, you use the `zfs send' command to create a stream version of the snapshot. For example, to write the snapshot out to a file: root-shell> zfs send scratchpool@snap1 >/backup/scratchpool-snap1 Or tape: root-shell> zfs send scratchpool@snap1 >/dev/rmt/0 You can also write out the incremental changes between two snapshots using `zfs send': root-shell> zfs send scratchpool@snap1 scratchpool@snap2 >/backup/scratchpool-changes To recover a snapshot, you use `zfs recv', which applies the snapshot information either to a new file system, or to an existing one.  File: manual.info, Node: ha-zfs-config, Next: ha-zfs-mysql, Prev: ha-zfs-replication, Up: ha-zfs-replication 15.5.1 Using ZFS for File System Replication -------------------------------------------- Because `zfs send' and `zfs recv' use streams to exchange data, you can use them to replicate information from one system to another by combining `zfs send', `ssh', and `zfs recv'. For example, to copy a snapshot of the `scratchpool' file system to a new file system called `slavepool' on a new server, you would use the following command. This sequence combines the snapshot of `scratchpool', the transmission to the slave machine (using `ssh' with login credentials), and the recovery of the snapshot on the slave using `zfs recv': root-shell> zfs send scratchpool@snap1 |ssh ID@HOST pfexec zfs recv -F slavepool The first part of the pipeline, `zfs send scratchpool@snap1', streams the snapshot. The `ssh' command, and the command that it executes on the other server, `pfexec zfs recv -F slavepool', receives the streamed snapshot data and writes it to slavepool. In this instance, I've specified the `-F' option which forces the snapshot data to be applied, and is therefore destructive. This is fine, as I'm creating the first version of my replicated file system. On the slave machine, the replicated file system contains the exact same content: root-shell> ls -al /slavepool/ total 23 drwxr-xr-x 6 root root 7 Nov 8 09:13 ./ drwxr-xr-x 29 root root 34 Nov 9 07:06 ../ drwxr-xr-x 31 root bin 50 Jul 21 07:32 DTT/ drwxr-xr-x 4 root bin 5 Jul 21 07:32 SUNWmlib/ drwxr-xr-x 14 root sys 16 Nov 5 09:56 SUNWspro/ drwxrwxrwx 19 1000 1000 40 Nov 6 19:16 emacs-22.1/ Once a snapshot has been created, to synchronize the file system again, you create a new snapshot and then use the incremental snapshot feature of `zfs send' to send the changes between the two snapshots to the slave machine again: root-shell> zfs send -i scratchpool@snapshot1 scratchpool@snapshot2 |ssh ID@HOST pfexec zfs recv slavepool This operation only succeeds if the file system on the slave machine has not been modified at all. You cannot apply the incremental changes to a destination file system that has changed. In the example above, the `ls' command would cause problems by changing the metadata, such as the last access time for files or directories. To prevent changes on the slave file system, set the file system on the slave to be read-only: root-shell> zfs set readonly=on slavepool Setting `readonly' means that you cannot change the file system on the slave by normal means, including the file system metadata. Operations that would normally update metadata (like our `ls') silently perform their function without attempting to update the file system state. In essence, the slave file system is nothing but a static copy of the original file system. However, even when configured to to be read-only, a file system can have snapshots applied to it. With the file system set to read only, re-run the initial copy: root-shell> zfs send scratchpool@snap1 |ssh ID@HOST pfexec zfs recv -F slavepool Now you can make changes to the original file system and replicate them to the slave.  File: manual.info, Node: ha-zfs-mysql, Next: ha-zfs-mysql-recovery, Prev: ha-zfs-config, Up: ha-zfs-replication 15.5.2 Configuring MySQL for ZFS Replication -------------------------------------------- Configuring MySQL on the source file system is a case of creating the data on the file system that you intend to replicate. The configuration file in the example below has been updated to use `/scratchpool/mysql-data' as the data directory, and now you can initialize the tables: root-shell> mysql_install_db --defaults-file=/etc/mysql/5.5/my.cnf --user=mysql To synchronize the initial information, perform a new snapshot and then send an incremental snapshot to the slave using `zfs send': root-shell> zfs snapshot scratchpool@snap2 root-shell> zfs send -i scratchpool@snap1 scratchpool@snap2|ssh ID@HOST pfexec zfs recv slavepool Doublecheck that the slave has the data by looking at the MySQL data directory on the `slavepool': root-shell> ls -al /slavepool/mysql-data/ Now you can start up MySQL, create some data, and then replicate the changes using `zfs send'/` zfs recv' to the slave to synchronize the changes. The rate at which you perform the synchronization depends on your application and environment. The limitation is the speed required to perform the snapshot and then to send the changes over the network. To automate the process, create a script that performs the snapshot, send, and receive operation, and use `cron' to synchronize the changes at set times or intervals.  File: manual.info, Node: ha-zfs-mysql-recovery, Prev: ha-zfs-mysql, Up: ha-zfs-replication 15.5.3 Handling MySQL Recovery with ZFS --------------------------------------- When using ZFS replication to provide a constant copy of your data, ensure that you can recover your tables, either manually or automatically, in the event of a failure of the original system. In the event of a failure, follow this sequence: 1. Stop the script on the master, if it is still up and running. 2. Set the slave file system to be read/write: root-shell> zfs set readonly=off slavepool 3. Start up *Note `mysqld': mysqld. on the slave. If you are using `InnoDB', you get auto-recovery, if it is needed, to make sure the table data is correct, as shown here when I started up from our mid-INSERT snapshot: InnoDB: The log sequence number in ibdata files does not match InnoDB: the log sequence number in the ib_logfiles! 081109 15:59:59 InnoDB: Database was not shut down normally! InnoDB: Starting crash recovery. InnoDB: Reading tablespace information from the .ibd files... InnoDB: Restoring possible half-written data pages from the doublewrite InnoDB: buffer... 081109 16:00:03 InnoDB: Started; log sequence number 0 1142807951 081109 16:00:03 [Note] /slavepool/mysql-5.0.67-solaris10-i386/bin/mysqld: ready for connections. Version: '5.0.67' socket: '/tmp/mysql.sock' port: 3306 MySQL Community Server (GPL) Use *Note `InnoDB': innodb-storage-engine. tables and a regular synchronization schedule to reduce the risk for significant data loss. On MyISAM tables, you might need to run *Note `REPAIR TABLE': repair-table, and you might even have lost some information.  File: manual.info, Node: ha-memcached, Next: mysql-proxy, Prev: ha-zfs-replication, Up: ha-overview 15.6 Using MySQL with `memcached' ================================= * Menu: * ha-memcached-install:: Installing `memcached' * ha-memcached-using:: Using `memcached' * ha-memcached-interfaces:: Developing a `memcached' Application * ha-memcached-stats:: Getting `memcached' Statistics * ha-memcached-faq:: `memcached' FAQ `memcached' is a simple, highly scalable key-based cache that stores data and objects wherever dedicated or spare RAM is available for quick access by applications, without going through layers of parsing or disk I/O. To use, you run the `memcached' command on one or more hosts and then use the shared cache to store objects. For more usage instructions, see *Note ha-memcached-using:: Benefits of using `memcached' include: * Because all information is stored in RAM, the access speed is faster than loading the information each time from disk. * Because the `value' portion of the key-value pair does not have any data type restrictions, you can cache data such as complex structures, documents, images, or a mixture of such things. * If you use the in-memory cache to hold transient information, or as a read-only cache for information also stored in a database, the failure of any `memcached' server is not critical. For persistent data, you can fall back to an alternative lookup method using database queries, and reload the data into RAM on a different server. The typical usage environment is to modify your application so that information is read from the cache provided by `memcached'. If the information is not in `memcached', then the data is loaded from the MySQL database and written into the cache so that future requests for the same object benefit from the cached data. For a typical deployment layout, see *Note ha-memcached-fig-overview::. FIGURE GOES HERE: `memcached' Architecture Overview In the example structure, any of the clients can contact one of the `memcached' servers to request a given key. Each client is configured to talk to all of the servers shown in the illustration. Within the client, when the request is made to store the information, the key used to reference the data is hashed and this hash is then used to select one of the `memcached' servers. The selection of the `memcached' server takes place on the client before the server is contacted, keeping the process lightweight. The same algorithm is used again when a client requests the same key. The same key generates the same hash, and the same `memcached' server is selected as the source for the data. Using this method, the cached data is spread among all of the `memcached' servers, and the cached information is accessible from any client. The result is a distributed, memory-based, cache that can return information, particularly complex data and structures, much faster than natively reading the information from the database. The data held within a traditional `memcached' server is never stored on disk (only in RAM, which means there is no persistence of data), and the RAM cache is always populated from the backing store (a MySQL database). If a `memcached' server fails, the data can always be recovered from the MySQL database.  File: manual.info, Node: ha-memcached-install, Next: ha-memcached-using, Prev: ha-memcached, Up: ha-memcached 15.6.1 Installing `memcached' ----------------------------- You can build and install `memcached' from the source code directly, or you can use an existing operating system package or installation. *Installing `memcached' from a Binary Distribution* To install `memcached' on a Red Hat, or Fedora host, use `yum': root-shell> yum install memcached *Note*: On CentOS, you may be able to obtain a suitable RPM from another source, or use the source tarball. To install `memcached' on a Debian or Ubuntu host, use `apt-get': root-shell> apt-get install memcached To install `memcached' on a Gentoo host, use `emerge': root-shell> emerge install memcached *Building `memcached' from Source* On other Unix-based platforms, including Solaris, AIX, HP-UX and Mac OS X, and Linux distributions not mentioned already, you must install from source. For Linux, make sure you have a 2.6-based kernel, which includes the improved `epoll' interface. For all platforms, ensure that you have `libevent' 1.1 or higher installed. You can obtain `libevent' from `libevent' web page (http://www.monkey.org/~provos/libevent/). You can obtain the source for `memcached' from `memcached' Web site (http://www.danga.com/memcached). To build `memcached', follow these steps: 1. Extract the `memcached' source package: shell> gunzip -c memcached-1.2.5.tar.gz | tar xf - 2. Change to the `memcached-1.2.5 directory:' shell> cd memcached-1.2.5 3. Run `configure' shell> ./configure Some additional options you might specify to the `configure': * `--prefix' To specify a different installation directory, use the `--prefix' option: shell> ./configure --prefix=/opt The default is to use the `/usr/local' directory. * `--with-libevent' If you have installed `libevent' and `configure' cannot find the library, use the `--with-libevent' option to specify the location of the installed library. * `--enable-64bit' To build a 64-bit version of `memcached' (which enables you to use a single instance with a large RAM allocation), use `--enable-64bit'. * `--enable-threads' To enable multi-threading support in `memcached', which improves the response times on servers with a heavy load, use `--enable-threads'. You must have support for the POSIX threads within your operating system to enable thread support. For more information on the threading support, see *Note ha-memcached-using-threads::. * `--enable-dtrace' `memcached' includes a range of DTrace threads that can be used to monitor and benchmark a `memcached' instance. For more information, see *Note ha-memcached-using-dtrace::. 4. Run `make' to build `memcached': shell> make 5. Run `make install' to install `memcached': shell> make install  File: manual.info, Node: ha-memcached-using, Next: ha-memcached-interfaces, Prev: ha-memcached-install, Up: ha-memcached 15.6.2 Using `memcached' ------------------------ * Menu: * ha-memcached-using-deployment:: `memcached' Deployment * ha-memcached-using-namespaces:: Using Namespaces * ha-memcached-using-expiry:: Data Expiry * ha-memcached-using-hashtypes:: `memcached' Hashing/Distribution Types * ha-memcached-using-dtrace:: Using `memcached' and DTrace * ha-memcached-using-memory:: Memory Allocation within `memcached' * ha-memcached-using-threads:: `memcached' Thread Support * ha-memcached-using-logs:: `memcached' Logs To start using `memcached', start the `memcached' service on one or more servers. Running `memcached' sets up the server, allocates the memory and starts listening for connections from clients. *Note*: You do not need to be a privileged user (`root') to run `memcached' except to listen on one of the privileged TCP/IP ports (below 1024). You must, however, use a user that has not had their memory limits restricted using `setrlimit' or similar. To start the server, run `memcached' as a nonprivileged (that is, non-`root') user: shell> memcached By default, `memcached' uses the following settings: * Memory allocation of 64MB * Listens for connections on all network interfaces, using port 11211 * Supports a maximum of 1024 simultaneous connections Typically, you would specify the full combination of options that you want when starting `memcached', and normally provide a startup script to handle the initialization of `memcached'. For example, the following line starts `memcached' with a maximum of 1024MB RAM for the cache, listening on port 11211 on the IP address 192.168.0.110, running as a background daemon: shell> memcached -d -m 1024 -p 11211 -l 192.168.0.110 To ensure that `memcached' is started up on boot, check the init script and configuration parameters. `memcached' supports the following options: * `-u user' If you start `memcached' as `root', use the `-u' option to specify the user for executing `memcached': shell> memcached -u memcache * `-m memory' Set the amount of memory allocated to `memcached' for object storage. Default is 64MB. To increase the amount of memory allocated for the cache, use the `-m' option to specify the amount of RAM to be allocated (in megabytes). The more RAM you allocate, the more data you can store and therefore the more effective your cache is. *Warning*: Do not specify a memory allocation larger than your available RAM. If you specify too large a value, then some RAM allocated for `memcached' uses swap space, and not physical RAM. This may lead to delays when storing and retrieving values, because data is swapped to disk, instead of storing the data directly in RAM. You can use the output of the `vmstat' command to get the free memory, as shown in `free' column: shell> vmstat kthr memory page disk faults cpu r b w swap free re mf pi po fr de sr s1 s2 -- -- in sy cs us sy id 0 0 0 5170504 3450392 2 7 2 0 0 0 4 0 0 0 0 296 54 199 0 0 100 For example, to allocate 3GB of RAM: shell> memcached -m 3072 On 32-bit x86 systems where you are using PAE to access memory above the 4GB limit, you cannot allocate RAM beyond the maximum process size. You can get around this by running multiple instances of `memcached', each listening on a different port: shell> memcached -m 1024 -p11211 shell> memcached -m 1024 -p11212 shell> memcached -m 1024 -p11213 *Note*: On all systems, particularly 32-bit, ensure that you leave enough room for both `memcached' application in addition to the memory setting. For example, if you have a dedicated `memcached' host with 4GB of RAM, do not set the memory size above 3500MB. Failure to do this may cause either a crash or severe performance issues. * `-l interface' Specify a network interface/address to listen for connections. The default is to listen on all available address (`INADDR_ANY'). shell> memcached -l 192.168.0.110 Support for IPv6 address support was added in `memcached' 1.2.5. * `-p port' Specify the TCP port to use for connections. Default is 18080. shell> memcached -p 18080 * `-U port' Specify the UDP port to use for connections. Default is 11211, 0 switches UDP off. shell> memcached -U 18080 * `-s socket' Specify a Unix socket to listen on. If you are running `memcached' on the same server as the clients, you can disable the network interface and use a local Unix socket using the `-s' option: shell> memcached -s /tmp/memcached Using a Unix socket automatically disables network support, and saves network ports (allowing more ports to be used by your web server or other process). * `-a mask' Specify the access mask to be used for the Unix socket, in octal. Default is 0700. * `-c connections' Specify the maximum number of simultaneous connections to the `memcached' service. The default is 1024. shell> memcached -c 2048 Use this option, either to reduce the number of connections (to prevent overloading `memcached' service) or to increase the number to make more effective use of the server running `memcached' server. * `-t threads' Specify the number of threads to use when processing incoming requests. By default, `memcached' is configured to use 4 concurrent threads. The threading improves the performance of storing and retrieving data in the cache, using a locking system to prevent different threads overwriting or updating the same values. To increase or decrease the number of threads, use the `-t' option: shell> memcached -t 8 * `-d' Run `memcached' as a daemon (background) process: shell> memcached -d * `-r' Maximize the size of the core file limit. In the event of a failure, this attempts to dump the entire memory space to disk as a core file, up to any limits imposed by `setrlimit'. * `-M' Return an error to the client when the memory has been exhausted. This replaces the normal behavior of removing older items from the cache to make way for new items. * `-k' Lock down all paged memory. This reserves the memory before use, instead of allocating new slabs of memory as new items are stored in the cache. *Note*: There is a user-level limit on how much memory you can lock. Trying to allocate more than the available memory fails. You can set the limit for the user you started the daemon with (not for the `-u user' user) within the shell by using `ulimit -S -l NUM_KB' * `-v' Verbose mode. Prints errors and warnings while executing the main event loop. * `-vv' Very verbose mode. In addition to information printed by `-v', also prints each client command and the response. * `-vvv' Extremely verbose mode. In addition to information printed by `-vv', also show the internal state transitions. * `-h' Print the help message and exit. * `-i' Print the `memcached' and `libevent' license. * `-I mem' Specify the maximum size permitted for storing an object within the `memcached' instance. The size supports a unit postfix (`k' for kilobytes, `m' for megabytes). For example, to increase the maximum supported object size to 32MB: shell> memcached -I 32m The maximum object size you can specify is 128MB, the default remains at 1MB. This option was added in 1.4.2. * `-b' Set the backlog queue limit. The backlog queue configures how many network connections can be waiting to be processed by `memcached'. Increasing this limit may reduce errors received by the client that it is not able to connect to the `memcached' instance, but does not improve the performance of the server. The default is 1024. * `-P pidfile' Save the process ID of the `memcached' instance into `file'. * `-f' Set the chunk size growth factor. When allocating new memory chunks, the allocated size of new chunks is determined by multiplying the default slab size by this factor. To see the effects of this option without extensive testing, use the `-vv' command-line option to show the calculated slab sizes. For more information, see *Note ha-memcached-using-logs::. * `-n bytes' The minimum space allocated for the key+value+flags information. The default is 48 bytes. * `-L' On systems that support large memory pages, enables large memory page use. Using large memory pages enables `memcached' to allocate the item cache in one large chunk, which can improve the performance by reducing the number misses when accessing memory. * `-C' Disable the use of compare and swap (CAS) operations. This option was added in `memcached' 1.3.x. * `-D char' Set the default character to be used as a delimiter between the key prefixes and IDs. This is used for the per-prefix statistics reporting (see *Note ha-memcached-stats::). The default is the colon (`:'). If this option is used, statistics collection is turned on automatically. If not used, you can enable stats collection by sending the `stats detail on' command to the server. This option was added in `memcached' 1.3.x. * `-R num' Sets the maximum number of requests per event process. The default is 20. * `-B protocol' Set the binding protocol, that is, the default `memcached' protocol support for client connections. Options are `ascii', `binary' or `auto'. Automatic (`auto') is the default. This option was added in `memcached' 1.4.0.  File: manual.info, Node: ha-memcached-using-deployment, Next: ha-memcached-using-namespaces, Prev: ha-memcached-using, Up: ha-memcached-using 15.6.2.1 `memcached' Deployment ............................... When using `memcached' you can use a number of different potential deployment strategies and topologies. The exact strategy to use depends on your application and environment. When developing a system for deploying `memcached' within your system, keep in mind the following points: * `memcached' is only a caching mechanism. It shouldn't be used to store information that you cannot otherwise afford to lose and then load from a different location. * There is no security built into the `memcached' protocol. At a minimum, make sure that the servers running `memcached' are only accessible from inside your network, and that the network ports being used are blocked (using a firewall or similar). If the information on the `memcached' servers that is being stored is any sensitive, then encrypt the information before storing it in `memcached'. * `memcached' does not provide any sort of failover. Because there is no communication between different `memcached' instances. If an instance fails, your application must capable of removing it from the list, reloading the data and then writing data to another `memcached' instance. * Latency between the clients and the `memcached' can be a problem if you are using different physical machines for these tasks. If you find that the latency is a problem, move the `memcached' instances to be on the clients. * Key length is determined by the `memcached' server. The default maximum key size is 250 bytes. * Try to use at least two `memcached' instances, especially for multiple clients, to avoid having a single point of failure. Ideally, create as many `memcached' nodes as possible. When adding and removing `memcached' instances from a pool, the hashing and distribution of key/value pairs may be affected. For information on how to avoid problems, see *Note ha-memcached-using-hashtypes::.  File: manual.info, Node: ha-memcached-using-namespaces, Next: ha-memcached-using-expiry, Prev: ha-memcached-using-deployment, Up: ha-memcached-using 15.6.2.2 Using Namespaces ......................... The `memcached' cache is a very simple massive key/value storage system, and as such there is no way of compartmentalizing data automatically into different sections. For example, if you are storing information by the unique ID returned from a MySQL database, then storing the data from two different tables could run into issues because the same ID might be valid in both tables. Some interfaces provide an automated mechanism for creating _namespaces_ when storing information into the cache. In practice, these namespaces are merely a prefix before a given ID that is applied every time a value is stored or retrieve from the cache. You can implement the same basic principle by using keys that describe the object and the unique identifier within the key that you supply when the object is stored. For example, when storing user data, prefix the ID of the user with `user:' or `user-'. *Note*: Using namespaces or prefixes only controls the keys stored/retrieved. There is no security within `memcached', and therefore no way to enforce that a particular client only accesses keys with a particular namespace. Namespaces are only useful as a method of identifying data and preventing corruption of key/value pairs.  File: manual.info, Node: ha-memcached-using-expiry, Next: ha-memcached-using-hashtypes, Prev: ha-memcached-using-namespaces, Up: ha-memcached-using 15.6.2.3 Data Expiry .................... There are two types of data expiry within a `memcached' instance. The first type is applied at the point when you store a new key/value pair into the `memcached' instance. If there is not enough space within a suitable slab to store the value, then an existing least recently used (LRU) object is removed (evicted) from the cache to make room for the new item. The LRU algorithm ensures that the object that is removed is one that is either no longer in active use or that was used so long ago that its data is potentially out of date or of little value. However, in a system where the memory allocated to `memcached' is smaller than the number of regularly used objects required in the cache, a lot of expired items could be removed from the cache even though they are in active use. You use the statistics mechanism to get a better idea of the level of evictions (expired objects). For more information, see *Note ha-memcached-stats::. You can change this eviction behavior by setting the `-M' command-line option when starting `memcached'. This option forces an error to be returned when the memory has been exhausted, instead of automatically evicting older data. The second type of expiry system is an explicit mechanism that you can set when a key/value pair is inserted into the cache, or when deleting an item from the cache. Using an expiration time can be a useful way of ensuring that the data in the cache is up to date and in line with your application needs and requirements. A typical scenario for explicitly setting the expiry time might include caching session data for a user when accessing a Web site. `memcached' uses a lazy expiry mechanism where the explicit expiry time that has been set is compared with the current time when the object is requested. Only objects that have not expired are returned. You can also set the expiry time when explicitly deleting an object from the cache. In this case, the expiry time is really a timeout and indicates the period when any attempts to set the value for a given key are rejected.  File: manual.info, Node: ha-memcached-using-hashtypes, Next: ha-memcached-using-dtrace, Prev: ha-memcached-using-expiry, Up: ha-memcached-using 15.6.2.4 `memcached' Hashing/Distribution Types ............................................... The `memcached' client interface supports a number of different distribution algorithms that are used in multi-server configurations to determine which host should be used when setting or getting data from a given `memcached' instance. When you get or set a value, a hash is constructed from the supplied key and then used to select a host from the list of configured servers. Because the hashing mechanism uses the supplied key as the basis for the hash, the same server is selected during both set and get operations. You can think of this process as follows. Given an array of servers (a, b, and c), the client uses a hashing algorithm that returns an integer based on the key being stored or retrieved. The resulting value is then used to select a server from the list of servers configured in the client. Most standard client hashing within `memcache' clients uses a simple modulus calculation on the value against the number of configured `memcached' servers. You can summarize the process in pseudocode as: @memcservers = ['a.memc','b.memc','c.memc']; $value = hash($key); $chosen = $value % length(@memcservers); Replacing the above with values: @memcservers = ['a.memc','b.memc','c.memc']; $value = hash('myid'); $chosen = 7009 % 3; In the above example, the client hashing algorithm chooses the server at index 1 (`7009 % 3 = 1'), and store or retrieve the key and value with that server. *Note*: This selection and hashing process is handled automatically by the `memcached' client you are using; you need only provide the list of `memcached' servers to use. You can see a graphical representation of this below in *Note ha-memcached-using-hashtypes-fig-selection::. FIGURE GOES HERE: `memcached' Hash Selection The same hashing and selection process takes place during any operation on the specified key within the `memcached' client. Using this method provides a number of advantages: * The hashing and selection of the server to contact is handled entirely within the client. This eliminates the need to perform network communication to determine the right machine to contact. * Because the determination of the `memcached' server occurs entirely within the client, the server can be selected automatically regardless of the operation being executed (set, get, increment, etc.). * Because the determination is handled within the client, the hashing algorithm returns the same value for a given key; values are not affected or reset by differences in the server environment. * Selection is very fast. The hashing algorithm on the key value is quick and the resulting selection of the server is from a simple array of available machines. * Using client-side hashing simplifies the distribution of data over each `memcached' server. Natural distribution of the values returned by the hashing algorithm means that keys are automatically spread over the available servers. Providing that the list of servers configured within the client remains the same, the same stored key returns the same value, and therefore selects the same server. However, if you do not use the same hashing mechanism then the same data may be recorded on different servers by different interfaces, both wasting space on your `memcached' and leading to potential differences in the information. *Note*: One way to use a multi-interface compatible hashing mechanism is to use the `libmemcached' library and the associated interfaces. Because the interfaces for the different languages (including C, Ruby, Perl and Python) use the same client library interface, they always generate the same hash code from the ID. The problem with client-side selection of the server is that the list of the servers (including their sequential order) _must_ remain consistent on each client using the `memcached' servers, and the servers must be available. If you try to perform an operation on a key when: * A new `memcached' instance has been added to the list of available instances * A `memcached' instance has been removed from the list of available instances * The order of the `memcached' instances has changed When the hashing algorithm is used on the given key, but with a different list of servers, the hash calculation may choose a different server from the list. If a new `memcached' instance is added into the list of servers, as `new.memc' is in the example below, then a GET operation using the same key, `myid', can result in a cache-miss. This is because the same value is computed from the key, which selects the same index from the array of servers, but index 2 now points to the new server, not the server `c.memc' where the data was originally stored. This would result in a cache miss, even though the key exists within the cache on another `memcached' instance. FIGURE GOES HERE: `memcached' Hash Selection with New `memcached' instance This means that servers `c.memc' and `new.memc ' both contain the information for key `myid', but the information stored against the key in eachs server may be different in each instance. A more significant problem is a much higher number of cache-misses when retrieving data, as the addition of a new server changes the distribution of keys, and this in turn requires rebuilding the cached data on the `memcached' instances, causing an increase in database reads. The same effect can occur if you actively manage the list of servers configured in your clients, adding and removing the configured `memcached' instances as each instance is identified as being available. For example, removing a `memcached' instance when the client notices that the instance can no longer be contacted can cause the server selection to fail as described here. To prevent this causing significant problems and invalidating your cache, you can select the hashing algorithm used to select the server. There are two common types of hashing algorithm, _consistent_ and _modula_. With _consistent_ hashing algorithms, the same key when applied to a list of servers always uses the same server to store or retrieve the keys, even if the list of configured servers changes. This means that you can add and remove servers from the configure list and always use the same server for a given key. There are two types of consistent hashing algorithms available, Ketama and Wheel. Both types are supported by `libmemcached', and implementations are available for PHP and Java. Any consistent hashing algorithm has some limitations. When you add servers to an existing list of configured servers, keys are distributed to the new servers as part of the normal distribution. When you remove servers from the list, the keys are re-allocated to another server within the list, meaning that the cache needs to be re-populated with the information. Also, a consistent hashing algorithm does not resolve the issue where you want consistent selection of a server across multiple clients, but where each client contains a different list of servers. The consistency is enforced only within a single client. With a _modula_ hashing algorithm, the client selects a server by first computing the hash and then choosing a server from the list of configured servers. As the list of servers changes, so the server selected when using a modula hashing algorithm also changes. The result is the behavior described above; changes to the list of servers mean that different servers are selected when retrieving data, leading to cache misses and increase in database load as the cache is re-seeded with information. If you use only a single `memcached' instance for each client, or your list of `memcached' servers configured for a client never changes, then the selection of a hashing algorithm is irrelevant, as it has no noticeable effect. If you change your servers regularly, or you use a common set of servers that are shared among a large number of clients, then using a consistent hashing algorithm should help to ensure that your cache data is not duplicated and the data is evenly distributed.  File: manual.info, Node: ha-memcached-using-dtrace, Next: ha-memcached-using-memory, Prev: ha-memcached-using-hashtypes, Up: ha-memcached-using 15.6.2.5 Using `memcached' and DTrace ..................................... `memcached' includes a number of different DTrace probes that can be used to monitor the operation of the server. The probes included can monitor individual connections, slab allocations, and modifications to the hash table when a key/value pair is added, updated, or removed. For more information on DTrace and writing DTrace scripts, read the DTrace User Guide (http://docs.oracle.com/cd/E19253-01/819-5488/). Support for DTrace probes was added to `memcached' 1.2.6 includes a number of DTrace probes that can be used to help monitor your application. DTrace is supported on Solaris 10, OpenSolaris, Mac OS X 10.5 and FreeBSD. To enable the DTrace probes in `memcached', build from source and use the `--enable-dtrace' option. For more information, see *Note ha-memcached-install::. The probes supported by `memcached' are: * `conn-allocate(connid)' Fired when a connection object is allocated from the connection pool. * `connid': The connection ID. * `conn-release(connid)' Fired when a connection object is released back to the connection pool. Arguments: * `connid': The connection ID. * `conn-create(ptr)' Fired when a new connection object is being created (that is, there are no free connection objects in the connection pool). Arguments: * `ptr': A pointer to the connection. object * `conn-destroy(ptr)' Fired when a connection object is being destroyed. Arguments: * `ptr': A pointer to the connection object. * `conn-dispatch(connid, threadid)' Fired when a connection is dispatched from the main or connection-management thread to a worker thread. Arguments: * `connid': The connection ID. * `threadid': The thread ID. * `slabs-allocate(size, slabclass, slabsize, ptr)' Allocate memory from the slab allocator. Arguments: * `size': The requested size. * `slabclass': The allocation is fulfilled in this class. * `slabsize': The size of each item in this class. * `ptr': A pointer to allocated memory. * `slabs-allocate-failed(size, slabclass)' Failed to allocate memory (out of memory). Arguments: * `size': The requested size. * `slabclass': The class that failed to fulfill the request. * `slabs-slabclass-allocate(slabclass)' Fired when a slab class needs more space. Arguments: * `slabclass': The class that needs more memory. * `slabs-slabclass-allocate-failed(slabclass)' Failed to allocate memory (out of memory). Arguments: * `slabclass': The class that failed to grab more memory. * `slabs-free(size, slabclass, ptr)' Release memory. Arguments: * `size': The amount of memory to release, in bytes. * `slabclass': The class the memory belongs to. * `ptr': A pointer to the memory to release. * `assoc-find(key, depth)' Fired when we have searched the hash table for a named key. These two elements provide an insight into how well the hash function operates. Traversals are a sign of a less optimal function, wasting CPU capacity. Arguments: * `key': The key searched for. * `depth': The depth in the list of hash table. * `assoc-insert(key, nokeys)' Fired when a new item has been inserted. Arguments: * `key': The key just inserted. * `nokeys': The total number of keys currently being stored, including the key for which insert was called. * `assoc-delete(key, nokeys)' Fired when a new item has been removed. Arguments: * `key': The key just deleted. * `nokeys': The total number of keys currently being stored, excluding the key for which delete was called. * `item-link(key, size)' Fired when an item is being linked in the cache. Arguments: * `key': The items key. * `size': The size of the data. * `item-unlink(key, size)' Fired when an item is being deleted. Arguments: * `key': The items key. * `size': The size of the data. * `item-remove(key, size)' Fired when the refcount for an item is reduced. Arguments: * `key': The item's key. * `size': The size of the data. * `item-update(key, size)' Fired when the "last referenced" time is updated. Arguments: * `key': The item's key. * `size': The size of the data. * `item-replace(oldkey, oldsize, newkey, newsize)' Fired when an item is being replaced with another item. Arguments: * `oldkey': The key of the item to replace. * `oldsize': The size of the old item. * `newkey': The key of the new item. * `newsize': The size of the new item. * `process-command-start(connid, request, size)' Fired when the processing of a command starts. Arguments: * `connid': The connection ID. * `request': The incoming request. * `size': The size of the request. * `process-command-end(connid, response, size)' Fired when the processing of a command is done. Arguments: * `connid': The connection ID. * `response': The response to send back to the client. * `size': The size of the response. * `command-get(connid, key, size)' Fired for a `get' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `size': The size of the key's data (or -1 if not found). * `command-gets(connid, key, size, casid)' Fired for a `gets' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `size': The size of the key's data (or -1 if not found). * `casid': The casid for the item. * `command-add(connid, key, size)' Fired for a `add' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `size': The new size of the key's data (or -1 if not found). * `command-set(connid, key, size)' Fired for a `set' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `size': The new size of the key's data (or -1 if not found). * `command-replace(connid, key, size)' Fired for a `replace' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `size': The new size of the key's data (or -1 if not found). * `command-prepend(connid, key, size)' Fired for a `prepend' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `size': The new size of the key's data (or -1 if not found). * `command-append(connid, key, size)' Fired for a `append' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `size': The new size of the key's data (or -1 if not found). * `command-cas(connid, key, size, casid)' Fired for a `cas' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `size': The size of the key's data (or -1 if not found). * `casid': The cas ID requested. * `command-incr(connid, key, val)' Fired for `incr' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `val': The new value. * `command-decr(connid, key, val)' Fired for `decr' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `val': The new value. * `command-delete(connid, key, exptime)' Fired for a `delete' command. Arguments: * `connid': The connection ID. * `key': The requested key. * `exptime': The expiry time.  File: manual.info, Node: ha-memcached-using-memory, Next: ha-memcached-using-threads, Prev: ha-memcached-using-dtrace, Up: ha-memcached-using 15.6.2.6 Memory Allocation within `memcached' ............................................. When you first start `memcached', the memory that you have configured is not automatically allocated. Instead, `memcached' only starts allocating and reserving physical memory once you start saving information into the cache. When you start to store data into the cache, `memcached' does not allocate the memory for the data on an item by item basis. Instead, a slab allocation is used to optimize memory usage and prevent memory fragmentation when information expires from the cache. With slab allocation, memory is reserved in blocks of 1MB. The slab is divided up into a number of blocks of equal size. When you try to store a value into the cache, `memcached' checks the size of the value that you are adding to the cache and determines which slab contains the right size allocation for the item. If a slab with the item size already exists, the item is written to the block within the slab. If the new item is bigger than the size of any existing blocks, then a new slab is created, divided up into blocks of a suitable size. If an existing slab with the right block size already exists, but there are no free blocks, a new slab is created. If you update an existing item with data that is larger than the existing block allocation for that key, then the key is re-allocated into a suitable slab. For example, the default size for the smallest block is 88 bytes (40 bytes of value, and the default 48 bytes for the key and flag data). If the size of the first item you store into the cache is less than 40 bytes, then a slab with a block size of 88 bytes is created and the value stored. If the size of the data that you intend to store is larger than this value, then the block size is increased by the chunk size factor until a block size large enough to hold the value is determined. The block size is always a function of the scale factor, rounded up to a block size which is exactly divisible into the chunk size. For a sample of the structure, see *Note ha-memcached-fig-slabs::. FIGURE GOES HERE: Memory Allocation in `memcached' The result is that you have multiple pages allocated within the range of memory allocated to `memcached'. Each page is 1MB in size (by default), and is split into a different number of chunks, according to the chunk size required to store the key/value pairs. Each instance has multiple pages allocated, and a page is always created when a new item needs to be created requiring a chunk of a particular size. A slab may consist of multiple pages, and each page within a slab contains an equal number of chunks. The chunk size of a new slab is determined by the base chunk size combined with the chunk size growth factor. For example, if the initial chunks are 104 bytes in size, and the default chunk size growth factor is used (1.25), then the next chunk size allocated would be the best power of 2 fit for 104*1.25, or 136 bytes. Allocating the pages in this way ensures that memory does not get fragmented. However, depending on the distribution of the objects that you store, it may lead to an inefficient distribution of the slabs and chunks if you have significantly different sized items. For example, having a relatively small number of items within each chunk size may waste a lot of memory with just few chunks in each allocated page. You can tune the growth factor to reduce this effect by using the `-f' command line option, which adapts the growth factor applied to make more effective use of the chunks and slabs allocated. For information on how to determine the current slab allocation statistics, see *Note ha-memcached-stats-slabs::. If your operating system supports it, you can also start `memcached' with the `-L' command line option. This option preallocates all the memory during startup using large memory pages. This can improve performance by reducing the number of misses in the CPU memory cache.  File: manual.info, Node: ha-memcached-using-threads, Next: ha-memcached-using-logs, Prev: ha-memcached-using-memory, Up: ha-memcached-using 15.6.2.7 `memcached' Thread Support ................................... If you enable the thread implementation within when building `memcached' from source, then `memcached' uses multiple threads in addition to the `libevent' system to handle requests. When enabled, the threading implementation operates as follows: * Threading is handled by wrapping functions within the code to provide basic protection from updating the same global structures at the same time. * Each thread uses its own instance of the `libevent' to help improve performance. * TCP/IP connections are handled with a single thread listening on the TCP/IP socket. Each connection is then distributed to one of the active threads on a simple round-robin basis. Each connection then operates solely within this thread while the connection remains open. * For UDP connections, all the threads listen to a single UDP socket for incoming requests. Threads that are not currently dealing with another request ignore the incoming packet. One of the remaining, nonbusy, threads reads the request and sends the response. This implementation can lead to increased CPU load as threads wake from sleep to potentially process the request. Using threads can increase the performance on servers that have multiple CPU cores available, as the requests to update the hash table can be spread between the individual threads. To minimize overhead from the locking mechanism employed, experiment with different thread values to achieve the best performance based on the number and type of requests within your given workload.  File: manual.info, Node: ha-memcached-using-logs, Prev: ha-memcached-using-threads, Up: ha-memcached-using 15.6.2.8 `memcached' Logs ......................... If you enable verbose mode, using the `-v', `-vv', or `-vvv' options, then the information output by `memcached' includes details of the operations being performed. Without the verbose options, `memcached' normally produces no output during normal operating. * *Output when using `-v'* The lowest verbosity level shows you: * Errors and warnings * Transient errors * Protocol and socket errors, including exhausting available connections * Each registered client connection, including the socket descriptor number and the protocol used. For example: 32: Client using the ascii protocol 33: Client using the ascii protocol Note that the socket descriptor is only valid while the client remains connected. Non-persistent connections may not be effectively represented. Examples of the error messages output at this level include: <%d send buffer was %d, now %d Can't listen for events on fd %d Can't read from libevent pipe Catastrophic: event fd doesn't match conn fd! Couldn't build response Couldn't realloc input buffer Couldn't update event Failed to build UDP headers Failed to read, and not due to blocking Too many open connections Unexpected state %d * *Output when using `-vv'* When using the second level of verbosity, you get more detailed information about protocol operations, keys updated, chunk and network operatings and details. During the initial start-up of `memcached' with this level of verbosity, you are shown the sizes of the individual slab classes, the chunk sizes, and the number of entries per slab. These do not show the allocation of the slabs, just the slabs that would be created when data is added. You are also given information about the listen queues and buffers used to send information. A sample of the output generated for a TCP/IP based system with the default memory and growth factors is given below: shell> memcached -vv slab class 1: chunk size 80 perslab 13107 slab class 2: chunk size 104 perslab 10082 slab class 3: chunk size 136 perslab 7710 slab class 4: chunk size 176 perslab 5957 slab class 5: chunk size 224 perslab 4681 slab class 6: chunk size 280 perslab 3744 slab class 7: chunk size 352 perslab 2978 slab class 8: chunk size 440 perslab 2383 slab class 9: chunk size 552 perslab 1899 slab class 10: chunk size 696 perslab 1506 slab class 11: chunk size 872 perslab 1202 slab class 12: chunk size 1096 perslab 956 slab class 13: chunk size 1376 perslab 762 slab class 14: chunk size 1720 perslab 609 slab class 15: chunk size 2152 perslab 487 slab class 16: chunk size 2696 perslab 388 slab class 17: chunk size 3376 perslab 310 slab class 18: chunk size 4224 perslab 248 slab class 19: chunk size 5280 perslab 198 slab class 20: chunk size 6600 perslab 158 slab class 21: chunk size 8256 perslab 127 slab class 22: chunk size 10320 perslab 101 slab class 23: chunk size 12904 perslab 81 slab class 24: chunk size 16136 perslab 64 slab class 25: chunk size 20176 perslab 51 slab class 26: chunk size 25224 perslab 41 slab class 27: chunk size 31536 perslab 33 slab class 28: chunk size 39424 perslab 26 slab class 29: chunk size 49280 perslab 21 slab class 30: chunk size 61600 perslab 17 slab class 31: chunk size 77000 perslab 13 slab class 32: chunk size 96256 perslab 10 slab class 33: chunk size 120320 perslab 8 slab class 34: chunk size 150400 perslab 6 slab class 35: chunk size 188000 perslab 5 slab class 36: chunk size 235000 perslab 4 slab class 37: chunk size 293752 perslab 3 slab class 38: chunk size 367192 perslab 2 slab class 39: chunk size 458992 perslab 2 <26 server listening (auto-negotiate) <29 server listening (auto-negotiate) <30 send buffer was 57344, now 2097152 <31 send buffer was 57344, now 2097152 <30 server listening (udp) <30 server listening (udp) <31 server listening (udp) <30 server listening (udp) <30 server listening (udp) <31 server listening (udp) <31 server listening (udp) <31 server listening (udp) Using this verbosity level can be a useful way to check the effects of the growth factor used on slabs with different memory allocations, which in turn can be used to better tune the growth factor to suit the data you are storing in the cache. For example, if you set the growth factor to 4 (quadrupling the size of each slab): shell> memcached -f 4 -m 1g -vv slab class 1: chunk size 80 perslab 13107 slab class 2: chunk size 320 perslab 3276 slab class 3: chunk size 1280 perslab 819 slab class 4: chunk size 5120 perslab 204 slab class 5: chunk size 20480 perslab 51 slab class 6: chunk size 81920 perslab 12 slab class 7: chunk size 327680 perslab 3 ... During use of the cache, this verbosity level also prints out detailed information on the storage and recovery of keys and other information. An example of the output during a typical set/get and increment/decrement operation is shown below. 32: Client using the ascii protocol <32 set my_key 0 0 10 >32 STORED <32 set object_key 1 0 36 >32 STORED <32 get my_key >32 sending key my_key >32 END <32 get object_key >32 sending key object_key >32 END <32 set key 0 0 6 >32 STORED <32 incr key 1 >32 789544 <32 decr key 1 >32 789543 <32 incr key 2 >32 789545 <32 set my_key 0 0 10 >32 STORED <32 set object_key 1 0 36 >32 STORED <32 get my_key >32 sending key my_key >32 END <32 get object_key >32 sending key object_key1 1 36 >32 END <32 set key 0 0 6 >32 STORED <32 incr key 1 >32 789544 <32 decr key 1 >32 789543 <32 incr key 2 >32 789545 During client communication, for each line, the initial character shows the direction of flow of the information. The < for communication from the client to the `memcached' server and > for communication back to the client. The number is the numeric socket descriptor for the connection. * *Output when using `-vvv'* This level of verbosity includes the transitions of connections between different states in the event library while reading and writing content to/from the clients. It should be used to diagnose and identify issues in client communication. For example, you can use this information to determine if `memcached' is taking a long time to return information to the client, during the read of the client operation or before returning and completing the operation. An example of the typical sequence for a set operation is provided below: <32 new auto-negotiating client connection 32: going from conn_new_cmd to conn_waiting 32: going from conn_waiting to conn_read 32: going from conn_read to conn_parse_cmd 32: Client using the ascii protocol <32 set my_key 0 0 10 32: going from conn_parse_cmd to conn_nread > NOT FOUND my_key >32 STORED 32: going from conn_nread to conn_write 32: going from conn_write to conn_new_cmd 32: going from conn_new_cmd to conn_waiting 32: going from conn_waiting to conn_read 32: going from conn_read to conn_closing <32 connection closed. All of the verbosity levels in `memcached' are designed to be used during debugging or examination of issues. The quantity of information generated, particularly when using `-vvv', is significant, particularly on a busy server. Also be aware that writing the error information out, especially to disk, may negate some of the performance gains you achieve by using `memcached'. Therefore, use in production or deployment environments is not recommended.  File: manual.info, Node: ha-memcached-interfaces, Next: ha-memcached-stats, Prev: ha-memcached-using, Up: ha-memcached 15.6.3 Developing a `memcached' Application ------------------------------------------- * Menu: * ha-memcached-operations:: Basic `memcached' Operations * ha-memcached-mysql-frontend:: Using `memcached' as a MySQL Caching Layer * ha-memcached-interfaces-libmemcached:: Using `libmemcached' with C and C++ * ha-memcached-interfaces-perl:: Using MySQL and `memcached' with Perl * ha-memcached-interfaces-python:: Using MySQL and `memcached' with Python * ha-memcached-interfaces-php:: Using MySQL and `memcached' with PHP * ha-memcached-interfaces-ruby:: Using MySQL and `memcached' with Ruby * ha-memcached-interfaces-java:: Using MySQL and `memcached' with Java * ha-memcached-interfaces-protocol:: Using the `memcached' TCP Text Protocol A number of language interfaces let applications store and retrieve information with `memcached' servers. You can write `memcached' applications in popular languages such as Perl, PHP, Python, Ruby, C, and Java. Data stored into a `memcached' server is referred to by a single string (the key), with storage into the cache and retrieval from the cache using the key as the reference. The cache therefore operates like a large associative array or hash table. It is not possible to structure or otherwise organize the information stored in the cache. To emulate database notions such as multiple tables or composite key values, you must use encode the extra information into the strings used as keys. For example, to store or look up the address corresponding to a specific latitude and longitude, you might turn those two numeric values into a single comma-separated string to use as a key.  File: manual.info, Node: ha-memcached-operations, Next: ha-memcached-mysql-frontend, Prev: ha-memcached-interfaces, Up: ha-memcached-interfaces 15.6.3.1 Basic `memcached' Operations ..................................... The interface to `memcached' supports the following methods for storing and retrieving information in the cache, and these are consistent across all the different APIs, although the language specific mechanics might be different: * `get(KEY)': Retrieves information from the cache. Returns the value associated with the key if the specified key exists. Returns `NULL', `nil', `undefined', or the closest equivalent in the corresponding language, if the specified key does not exist. * `set(KEY, VALUE [, EXPIRY])': Sets the item associated with a key in the cache to the specified value. Note that this either updates an existing item if the key already exists, or adds a new key/value pair if the key doesn't exist. If the expiry time is specified, then the item expires (and is deleted) when the expiry time is reached. The time is specified in seconds, and is taken as a relative time if the value is less than 30 days (30*24*60*60), or an absolute time (epoch) if larger than this value. * `add(KEY, VALUE [, EXPIRY])': Adds the key and associated value to the cache, if the specified key does not already exist. * `replace(KEY, VALUE [, EXPIRY])': Replaces the item associated with the specified `key', only if the key already exists. The new value is given by the `value' parameter. * `delete(KEY [, TIME])': Deletes the `key' and its associated item from the cache. If you supply a `time', then adding another item with the specified `key' is blocked for the specified period. * `incr(KEY [, VALUE])': Increments the item associated with the `key' by one or the optional `value'. * `decr(KEY [, VALUE])': Decrements the item associated with the `key' by one or the optional `value'. * `flush_all': Invalidates (or expires) all the current items in the cache. Technically they still exist (they are not deleted), but they are silently destroyed the next time you try to access them. In all implementations, most or all of these functions are duplicated through the corresponding native language interface. When practical, use `memcached' to store full items, rather than caching a single column value from the database. For example, when displaying a record about an object (invoice, user history, or blog post), load all the data for the associated entry from the database, and compile it into the internal structure that would normally be required by the application. Save the complete object in the cache. Complex data structures cannot be stored directly. Most interfaces serialize the data for you, that is, put it in a textual form that can reconstruct the original pointers and nesting. Perl uses `Storable', PHP uses `serialize', Python uses `cPickle' (or `Pickle') and Java uses the `Serializable' interface. In most cases, the serialization interface used is customizable. To share data stored in `memcached' instances between different language interfaces, consider using a common serialization solution such as JSON (Javascript Object Notation).  File: manual.info, Node: ha-memcached-mysql-frontend, Next: ha-memcached-interfaces-libmemcached, Prev: ha-memcached-operations, Up: ha-memcached-interfaces 15.6.3.2 Using `memcached' as a MySQL Caching Layer ................................................... When using `memcached' to cache MySQL data, your application must retrieve data from the database and load the appropriate key-value pairs into the cache. Then, subsequent lookups can be done directly from the cache. Because MySQL has its own in-memory caching mechanisms for queried data, such as the `InnoDB' buffer pool (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_buffer_pool) and the MySQL query cache, look for opportunities beyond loading individual column values or rows into the cache. Prefer to cache composite values, such as those retrieved from multiple tables through a join query, or result sets assembled from multiple rows. *Caution*: Limit the information in the cache to non-sensitive data, because there is no security required to access or update the information within a `memcached' instance. Anybody with access to the machine has the ability to read, view and potentially update the information. To keep the data secure, encrypt the information before caching it. To restrict the users capable of connecting to the server, either disable network access, or use IPTables or similar techniques to restrict access to the `memcached' ports to a select set of hosts. You can introduce `memcached' to an existing application, even if caching was not part of the original design. In many languages and environments the changes to the application will be just a few lines, first to attempt to read from the cache when loading data, fall back to the old method if the information is not cached, and to update the cache with information once the data has been read. The general sequence for using `memcached' in any language as a caching solution for MySQL is as follows: 1. Request the item from the cache. 2. If the item exists, use the item data. 3. If the item does not exist, load the data from MySQL, and store the value into the cache. This means the value is available to the next client that requests it from the cache. For a flow diagram of this sequence, see *Note ha-memcached-fig-basicflow::. FIGURE GOES HERE: Typical `memcached' Application Flowchart * Adapting Database Best Practices to `memcached' Applications * The most direct way to cache MySQL data is to use a 2-column table, where the first column is a primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key). Because of the uniqueness requirements for `memcached' keys, make sure your database schema makes appropriate use of primary keys and unique constraints (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_unique_constraint). If you combine multiple column values into a single `memcached' item value, choose data types to make it easy to parse the value back into its components, for example by using a separator character between numeric values. The queries that map most easily to `memcached' lookups are those with a single `WHERE' clause, using an `=' or `IN' operator. For complicated `WHERE' clauses, or those using operators such as `<', `>', `BETWEEN', or `LIKE', `memcached' does not provide a simple or efficient way to scan through or filter the keys or associated values, so typically you perform those operations as SQL queries on the underlying database.  File: manual.info, Node: ha-memcached-interfaces-libmemcached, Next: ha-memcached-interfaces-perl, Prev: ha-memcached-mysql-frontend, Up: ha-memcached-interfaces 15.6.3.3 Using `libmemcached' with C and C++ ............................................ * Menu: * ha-memcached-interfaces-libmemcached-base:: `libmemcached' Base Functions * ha-memcached-interfaces-libmemcached-servers:: `libmemcached' Server Functions * ha-memcached-interfaces-libmemcached-set:: `libmemcached' Set Functions * ha-memcached-interfaces-libmemcached-get:: `libmemcached' Get Functions * ha-memcached-interfaces-libmemcached-behaviors:: Controlling `libmemcached' Behaviors * ha-memcached-interfaces-libmemcached-utilities:: `libmemcached' Command-Line Utilities The `libmemcached' library provides both C and C++ interfaces to `memcached' and is also the basis for a number of different additional API implementations, including Perl, Python and Ruby. Understanding the core `libmemcached' functions can help when using these other interfaces. The C library is the most comprehensive interface library for `memcached' and provides functions and operational systems not always exposed in interfaces not based on the `libmemcached' library. The different functions can be divided up according to their basic operation. In addition to functions that interface to the core API, a number of utility functions provide extended functionality, such as appending and prepending data. To build and install `libmemcached', download the `libmemcached' package, run `configure', and then build and install: shell> tar xjf libmemcached-0.21.tar.gz shell> cd libmemcached-0.21 shell> ./configure shell> make shell> make install On many Linux operating systems, you can install the corresponding `libmemcached' package through the usual `yum', `apt-get', or similar commands. To build an application that uses the library, first set the list of servers. Either directly manipulate the servers configured within the main `memcached_st' structure, or separately populate a list of servers, and then add this list to the `memcached_st' structure. The latter method is used in the following example. Once the server list has been set, you can call the functions to store or retrieve data. A simple application for setting a preset value to `localhost' is provided here: #include #include #include #include int main(int argc, char *argv[]) { memcached_server_st *servers = NULL; memcached_st *memc; memcached_return rc; char *key= "keystring"; char *value= "keyvalue"; memcached_server_st *memcached_servers_parse (char *server_strings); memc= memcached_create(NULL); servers= memcached_server_list_append(servers, "localhost", 11211, &rc); rc= memcached_server_push(memc, servers); if (rc == MEMCACHED_SUCCESS) fprintf(stderr,"Added server successfully\n"); else fprintf(stderr,"Couldn't add server: %s\n",memcached_strerror(memc, rc)); rc= memcached_set(memc, key, strlen(key), value, strlen(value), (time_t)0, (uint32_t)0); if (rc == MEMCACHED_SUCCESS) fprintf(stderr,"Key stored successfully\n"); else fprintf(stderr,"Couldn't store key: %s\n",memcached_strerror(memc, rc)); return 0; } To test the success of an operation, use the return value, or populated result code, for a given function. The value is always set to `MEMCACHED_SUCCESS' if the operation succeeded. In the event of a failure, use the `memcached_strerror()' function to translate the result code into a printable string. To build the application, specify the `memcached' library: shell> gcc -o memc_basic memc_basic.c -lmemcached Running the above sample application, after starting a `memcached' server, should return a success message: shell> memc_basic Added server successfully Key stored successfully  File: manual.info, Node: ha-memcached-interfaces-libmemcached-base, Next: ha-memcached-interfaces-libmemcached-servers, Prev: ha-memcached-interfaces-libmemcached, Up: ha-memcached-interfaces-libmemcached 15.6.3.4 `libmemcached' Base Functions ...................................... The base `libmemcached' functions let you create, destroy and clone the main `memcached_st' structure that is used to interface with the `memcached' servers. The main functions are defined below: memcached_st *memcached_create (memcached_st *ptr); Creates a new `memcached_st' structure for use with the other `libmemcached' API functions. You can supply an existing, static, `memcached_st' structure, or `NULL' to have a new structured allocated. Returns a pointer to the created structure, or `NULL' on failure. void memcached_free (memcached_st *ptr); Frees the structure and memory allocated to a previously created `memcached_st' structure. memcached_st *memcached_clone(memcached_st *clone, memcached_st *source); Clones an existing `memcached' structure from the specified `source', copying the defaults and list of servers defined in the structure.  File: manual.info, Node: ha-memcached-interfaces-libmemcached-servers, Next: ha-memcached-interfaces-libmemcached-set, Prev: ha-memcached-interfaces-libmemcached-base, Up: ha-memcached-interfaces-libmemcached 15.6.3.5 `libmemcached' Server Functions ........................................ The `libmemcached' API uses a list of servers, stored within the `memcached_server_st' structure, to act as the list of servers used by the rest of the functions. To use `memcached', you first create the server list, and then apply the list of servers to a valid `libmemcached' object. Because the list of servers, and the list of servers within an active `libmemcached' object can be manipulated separately, you can update and manage server lists while an active `libmemcached' interface is running. The functions for manipulating the list of servers within a `memcached_st' structure are: memcached_return memcached_server_add (memcached_st *ptr, char *hostname, unsigned int port); Adds a server, using the given `hostname' and `port' into the `memcached_st' structure given in `ptr'. memcached_return memcached_server_add_unix_socket (memcached_st *ptr, char *socket); Adds a Unix socket to the list of servers configured in the `memcached_st' structure. unsigned int memcached_server_count (memcached_st *ptr); Returns a count of the number of configured servers within the `memcached_st' structure. memcached_server_st * memcached_server_list (memcached_st *ptr); Returns an array of all the defined hosts within a `memcached_st' structure. memcached_return memcached_server_push (memcached_st *ptr, memcached_server_st *list); Pushes an existing list of servers onto list of servers configured for a current `memcached_st' structure. This adds servers to the end of the existing list, and duplicates are not checked. The `memcached_server_st' structure can be used to create a list of `memcached' servers which can then be applied individually to `memcached_st' structures. memcached_server_st * memcached_server_list_append (memcached_server_st *ptr, char *hostname, unsigned int port, memcached_return *error); Adds a server, with `hostname' and `port', to the server list in `ptr'. The result code is handled by the `error' argument, which should point to an existing `memcached_return' variable. The function returns a pointer to the returned list. unsigned int memcached_server_list_count (memcached_server_st *ptr); Returns the number of the servers in the server list. void memcached_server_list_free (memcached_server_st *ptr); Frees the memory associated with a server list. memcached_server_st *memcached_servers_parse (char *server_strings); Parses a string containing a list of servers, where individual servers are separated by a comma, space, or both, and where individual servers are of the form `SERVER[:PORT]'. The return value is a server list structure.  File: manual.info, Node: ha-memcached-interfaces-libmemcached-set, Next: ha-memcached-interfaces-libmemcached-get, Prev: ha-memcached-interfaces-libmemcached-servers, Up: ha-memcached-interfaces-libmemcached 15.6.3.6 `libmemcached' Set Functions ..................................... The set-related functions within `libmemcached' provide the same functionality as the core functions supported by the `memcached' protocol. The full definition for the different functions is the same for all the base functions (`add', `replace', `prepend', `append'). For example, the function definition for `memcached_set()' is: memcached_return memcached_set (memcached_st *ptr, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags); The `ptr' is the `memcached_st' structure. The `key' and `key_length' define the key name and length, and `value' and `value_length' the corresponding value and length. You can also set the expiration and optional flags. For more information, see *Note ha-memcached-interfaces-libmemcached-behaviors::. This table outlines the remainder of the set-related `libmemcached' functions and the equivalent core functions supported by the `memcached' protocol. This table outlines the remainder of the set-related `libmemcached' functions and the equivalent core functions supported by the `memcached' protocol. `libmemcached' Function Equivalent Core Function `memcached_set(memc, key, Generic `set()' operation. key_length, value, value_length, expiration, flags)' `memcached_add(memc, key, Generic `add()' function. key_length, value, value_length, expiration, flags)' `memcached_replace(memc, key, Generic `replace()'. key_length, value, value_length, expiration, flags)' `memcached_prepend(memc, key, Prepends the specified `value' key_length, value, value_length, before the current value of the expiration, flags)' specified `key'. `memcached_append(memc, key, Appends the specified `value' after key_length, value, value_length, the current value of the specified expiration, flags)' `key'. `memcached_cas(memc, key, Overwrites the data for a given key key_length, value, value_length, as long as the corresponding `cas' expiration, flags, cas)' value is still the same within the server. `memcached_set_by_key(memc, Similar to the generic `set()', but master_key, master_key_length, key, has the option of an additional key_length, value, value_length, master key that can be used to expiration, flags)' identify an individual server. `memcached_add_by_key(memc, Similar to the generic `add()', but master_key, master_key_length, key, has the option of an additional key_length, value, value_length, master key that can be used to expiration, flags)' identify an individual server. `memcached_replace_by_key(memc, Similar to the generic `replace()', master_key, master_key_length, key, but has the option of an additional key_length, value, value_length, master key that can be used to expiration, flags)' identify an individual server. `memcached_prepend_by_key(memc, Similar to the master_key, master_key_length, key, `memcached_prepend()', but has the key_length, value, value_length, option of an additional master key expiration, flags)' that can be used to identify an individual server. `memcached_append_by_key(memc, Similar to the master_key, master_key_length, key, `memcached_append()', but has the key_length, value, value_length, option of an additional master key expiration, flags)' that can be used to identify an individual server. `memcached_cas_by_key(memc, Similar to the `memcached_cas()', master_key, master_key_length, key, but has the option of an additional key_length, value, value_length, master key that can be used to expiration, flags)' identify an individual server. The `by_key' methods add two further arguments that define the master key, to be used and applied during the hashing stage for selecting the servers. You can see this in the following definition: memcached_return memcached_set_by_key(memcached_st *ptr, const char *master_key, size_t master_key_length, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags); All the functions return a value of type `memcached_return', which you can compare against the `MEMCACHED_SUCCESS' constant.  File: manual.info, Node: ha-memcached-interfaces-libmemcached-get, Next: ha-memcached-interfaces-libmemcached-behaviors, Prev: ha-memcached-interfaces-libmemcached-set, Up: ha-memcached-interfaces-libmemcached 15.6.3.7 `libmemcached' Get Functions ..................................... The `libmemcached' functions provide both direct access to a single item, and a multiple-key request mechanism that provides much faster responses when fetching a large number of keys simultaneously. The main get-style function, which is equivalent to the generic `get()' is `memcached_get()'. This function returns a string pointer, pointing to the value associated with the specified key. char *memcached_get (memcached_st *ptr, const char *key, size_t key_length, size_t *value_length, uint32_t *flags, memcached_return *error); A multi-key get, `memcached_mget()', is also available. Using a multiple key get operation is much quicker to do in one block than retrieving the key values with individual calls to `memcached_get()'. To start the multi-key get, call `memcached_mget()': memcached_return memcached_mget (memcached_st *ptr, char **keys, size_t *key_length, unsigned int number_of_keys); The return value is the success of the operation. The `keys' parameter should be an array of strings containing the keys, and `key_length' an array containing the length of each corresponding key. `number_of_keys' is the number of keys supplied in the array. To fetch the individual values, use `memcached_fetch()' to get each corresponding value. char *memcached_fetch (memcached_st *ptr, const char *key, size_t *key_length, size_t *value_length, uint32_t *flags, memcached_return *error); The function returns the key value, with the `key', `key_length' and `value_length' parameters being populated with the corresponding key and length information. The function returns `NULL' when there are no more values to be returned. A full example, including the populating of the key data and the return of the information is provided here. #include #include #include #include int main(int argc, char *argv[]) { memcached_server_st *servers = NULL; memcached_st *memc; memcached_return rc; char *keys[]= {"huey", "dewey", "louie"}; size_t key_length[3]; char *values[]= {"red", "blue", "green"}; size_t value_length[3]; unsigned int x; uint32_t flags; char return_key[MEMCACHED_MAX_KEY]; size_t return_key_length; char *return_value; size_t return_value_length; memc= memcached_create(NULL); servers= memcached_server_list_append(servers, "localhost", 11211, &rc); rc= memcached_server_push(memc, servers); if (rc == MEMCACHED_SUCCESS) fprintf(stderr,"Added server successfully\n"); else fprintf(stderr,"Couldn't add server: %s\n",memcached_strerror(memc, rc)); for(x= 0; x < 3; x++) { key_length[x] = strlen(keys[x]); value_length[x] = strlen(values[x]); rc= memcached_set(memc, keys[x], key_length[x], values[x], value_length[x], (time_t)0, (uint32_t)0); if (rc == MEMCACHED_SUCCESS) fprintf(stderr,"Key %s stored successfully\n",keys[x]); else fprintf(stderr,"Couldn't store key: %s\n",memcached_strerror(memc, rc)); } rc= memcached_mget(memc, keys, key_length, 3); if (rc == MEMCACHED_SUCCESS) { while ((return_value= memcached_fetch(memc, return_key, &return_key_length, &return_value_length, &flags, &rc)) != NULL) { if (rc == MEMCACHED_SUCCESS) { fprintf(stderr,"Key %s returned %s\n",return_key, return_value); } } } return 0; } Running the above application produces the following output: shell> memc_multi_fetch Added server successfully Key huey stored successfully Key dewey stored successfully Key louie stored successfully Key huey returned red Key dewey returned blue Key louie returned green  File: manual.info, Node: ha-memcached-interfaces-libmemcached-behaviors, Next: ha-memcached-interfaces-libmemcached-utilities, Prev: ha-memcached-interfaces-libmemcached-get, Up: ha-memcached-interfaces-libmemcached 15.6.3.8 Controlling `libmemcached' Behaviors ............................................. The behavior of `libmemcached' can be modified by setting one or more behavior flags. These can either be set globally, or they can be applied during the call to individual functions. Some behaviors also accept an additional setting, such as the hashing mechanism used when selecting servers. To set global behaviors: memcached_return memcached_behavior_set (memcached_st *ptr, memcached_behavior flag, uint64_t data); To get the current behavior setting: uint64_t memcached_behavior_get (memcached_st *ptr, memcached_behavior flag); The following table describes `libmemcached' behavior flags. This table lists `libmemcached' behavior flags and provides a description of each. Behavior Description `MEMCACHED_BEHAVIOR_NO_BLOCK' Caused `libmemcached' to use asynchronous I/O. `MEMCACHED_BEHAVIOR_TCP_NODELAY'Turns on no-delay for network sockets. `MEMCACHED_BEHAVIOR_HASH' Without a value, sets the default hashing algorithm for keys to use MD5. Other valid values include `MEMCACHED_HASH_DEFAULT', `MEMCACHED_HASH_MD5', `MEMCACHED_HASH_CRC', `MEMCACHED_HASH_FNV1_64', `MEMCACHED_HASH_FNV1A_64', `MEMCACHED_HASH_FNV1_32', and `MEMCACHED_HASH_FNV1A_32'. `MEMCACHED_BEHAVIOR_DISTRIBUTION'Changes the method of selecting the server used to store a given value. The default method is `MEMCACHED_DISTRIBUTION_MODULA'. You can enable consistent hashing by setting `MEMCACHED_DISTRIBUTION_CONSISTENT'. `MEMCACHED_DISTRIBUTION_CONSISTENT' is an alias for the value `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA'. `MEMCACHED_BEHAVIOR_CACHE_LOOKUPS'Cache the lookups made to the DNS service. This can improve the performance if you are using names instead of IP addresses for individual hosts. `MEMCACHED_BEHAVIOR_SUPPORT_CAS'Support CAS operations. By default, this is disabled because it imposes a performance penalty. `MEMCACHED_BEHAVIOR_KETAMA' Sets the default distribution to `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA' and the hash to `MEMCACHED_HASH_MD5'. `MEMCACHED_BEHAVIOR_POLL_TIMEOUT'Modify the timeout value used by `poll()'. Supply a `signed int' pointer for the timeout value. `MEMCACHED_BEHAVIOR_BUFFER_REQUESTS'Buffers IO requests instead of them being sent. A get operation, or closing the connection causes the data to be flushed. `MEMCACHED_BEHAVIOR_VERIFY_KEY'Forces `libmemcached' to verify that a specified key is valid. `MEMCACHED_BEHAVIOR_SORT_HOSTS'If set, hosts added to the list of configured hosts for a `memcached_st' structure are placed into the host list in sorted order. This breaks consistent hashing if that behavior has been enabled. `MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT'In nonblocking mode this changes the value of the timeout during socket connection.  File: manual.info, Node: ha-memcached-interfaces-libmemcached-utilities, Prev: ha-memcached-interfaces-libmemcached-behaviors, Up: ha-memcached-interfaces-libmemcached 15.6.3.9 `libmemcached' Command-Line Utilities .............................................. In addition to the main C library interface, `libmemcached' also includes a number of command-line utilities that can be useful when working with and debugging `memcached' applications. All of the command-line tools accept a number of arguments, the most critical of which is `servers', which specifies the list of servers to connect to when returning information. The main tools are: * `memcat': Display the value for each ID given on the command line: shell> memcat --servers=localhost hwkey Hello world * `memcp': Copy the contents of a file into the cache, using the file name as the key: shell> echo "Hello World" > hwkey shell> memcp --servers=localhost hwkey shell> memcat --servers=localhost hwkey Hello world * `memrm': Remove an item from the cache: shell> memcat --servers=localhost hwkey Hello world shell> memrm --servers=localhost hwkey shell> memcat --servers=localhost hwkey * `memslap': Test the load on one or more `memcached' servers, simulating get/set and multiple client operations. For example, you can simulate the load of 100 clients performing get operations: shell> memslap --servers=localhost --concurrency=100 --flush --test=get memslap --servers=localhost --concurrency=100 --flush --test=get Threads connecting to servers 100 Took 13.571 seconds to read data * `memflush': Flush (empty) the contents of the `memcached' cache. shell> memflush --servers=localhost  File: manual.info, Node: ha-memcached-interfaces-perl, Next: ha-memcached-interfaces-python, Prev: ha-memcached-interfaces-libmemcached, Up: ha-memcached-interfaces 15.6.3.10 Using MySQL and `memcached' with Perl ............................................... The `Cache::Memcached' module provides a native interface to the Memcache protocol, and provides support for the core functions offered by `memcached'. Install the module using your operating system's package management system, or using `CPAN': root-shell> perl -MCPAN -e 'install Cache::Memcached' To use `memcached' from Perl through the `Cache::Memcached' module, first create a new `Cache::Memcached' object that defines the list of servers and other parameters for the connection. The only argument is a hash containing the options for the cache interface. For example, to create a new instance that uses three `memcached' servers: use Cache::Memcached; my $cache = new Cache::Memcached { 'servers' => [ '192.168.0.100:11211', '192.168.0.101:11211', '192.168.0.102:11211', ], }; *Note*: When using the `Cache::Memcached' interface with multiple servers, the API automatically performs certain operations across all the servers in the group. For example, getting statistical information through `Cache::Memcached' returns a hash that contains data on a host-by-host basis, as well as generalized statistics for all the servers in the group. You can set additional properties on the cache object instance when it is created by specifying the option as part of the option hash. Alternatively, you can use a corresponding method on the instance: * `servers' or method `set_servers()': Specifies the list of the servers to be used. The servers list should be a reference to an array of servers, with each element as the address and port number combination (separated by a colon). You can also specify a local connection through a Unix socket (for example `/tmp/sock/memcached'). To specify the server with a weight (indicating how much more frequently the server should be used during hashing), specify an array reference with the `memcached' server instance and a weight number. Higher numbers give higher priority. * `compress_threshold' or method `set_compress_threshold()': Specifies the threshold when values are compressed. Values larger than the specified number are automatically compressed (using `zlib') during storage and retrieval. * `no_rehash' or method `set_norehash()': Disables finding a new server if the original choice is unavailable. * `readonly' or method `set_readonly()': Disables writes to the `memcached' servers. Once the `Cache::Memcached' object instance has been configured, you can use the `set()' and `get()' methods to store and retrieve information from the `memcached' servers. Objects stored in the cache are automatically serialized and deserialized using the `Storable' module. The `Cache::Memcached' interface supports the following methods for storing/retrieving data, and relate to the generic methods as shown in the table. This table lists `memcached' functions used with Perl and the equivalent generic methods in the `memcached' interface specification. `Cache::Memcached' Function Equivalent Generic Method `get()' Generic `get()'. `get_multi(keys)' Gets multiple `keys' from memcache using just one query. Returns a hash reference of key/value pairs. `set()' Generic `set()'. `add()' Generic `add()'. `replace()' Generic `replace()'. `delete()' Generic `delete()'. `incr()' Generic `incr()'. `decr()' Generic `decr()'. Below is a complete example for using `memcached' with Perl and the `Cache::Memcached' module: #!/usr/bin/perl use Cache::Memcached; use DBI; use Data::Dumper; # Configure the memcached server my $cache = new Cache::Memcached { 'servers' => [ 'localhost:11211', ], }; # Get the film name from the command line # memcached keys must not contain spaces, so create # a key name by replacing spaces with underscores my $filmname = shift or die "Must specify the film name\n"; my $filmkey = $filmname; $filmkey =~ s/ /_/; # Load the data from the cache my $filmdata = $cache->get($filmkey); # If the data wasn't in the cache, then we load it from the database if (!defined($filmdata)) { $filmdata = load_filmdata($filmname); if (defined($filmdata)) { # Set the data into the cache, using the key if ($cache->set($filmkey,$filmdata)) { print STDERR "Film data loaded from database and cached\n"; } else { print STDERR "Couldn't store to cache\n"; } } else { die "Couldn't find $filmname\n"; } } else { print STDERR "Film data loaded from Memcached\n"; } sub load_filmdata { my ($filmname) = @_; my $dsn = "DBI:mysql:database=sakila;host=localhost;port=3306"; $dbh = DBI->connect($dsn, 'sakila','password'); my ($filmbase) = $dbh->selectrow_hashref(sprintf('select * from film where title = %s', $dbh->quote($filmname))); if (!defined($filmname)) { return (undef); } $filmbase->{stars} = $dbh->selectall_arrayref(sprintf('select concat(first_name," ",last_name) ' . 'from film_actor left join (actor) ' . 'on (film_actor.actor_id = actor.actor_id) ' . ' where film_id=%s', $dbh->quote($filmbase->{film_id}))); return($filmbase); } The example uses the Sakila database, obtaining film data from the database and writing a composite record of the film and actors to `memcached'. When calling it for a film does not exist, you get this result: shell> memcached-sakila.pl "ROCK INSTINCT" Film data loaded from database and cached When accessing a film that has already been added to the cache: shell> memcached-sakila.pl "ROCK INSTINCT" Film data loaded from Memcached  File: manual.info, Node: ha-memcached-interfaces-python, Next: ha-memcached-interfaces-php, Prev: ha-memcached-interfaces-perl, Up: ha-memcached-interfaces 15.6.3.11 Using MySQL and `memcached' with Python ................................................. The Python `memcache' module interfaces to `memcached' servers, and is written in pure Python (that is, without using one of the C APIs). You can download and install a copy from Python Memcached (http://www.tummy.com/Community/software/python-memcached/). To install, download the package and then run the Python installer: python setup.py install running install running bdist_egg running egg_info creating python_memcached.egg-info ... removing 'build/bdist.linux-x86_64/egg' (and everything under it) Processing python_memcached-1.43-py2.4.egg creating /usr/lib64/python2.4/site-packages/python_memcached-1.43-py2.4.egg Extracting python_memcached-1.43-py2.4.egg to /usr/lib64/python2.4/site-packages Adding python-memcached 1.43 to easy-install.pth file Installed /usr/lib64/python2.4/site-packages/python_memcached-1.43-py2.4.egg Processing dependencies for python-memcached==1.43 Finished processing dependencies for python-memcached==1.43 Once installed, the `memcache' module provides a class-based interface to your `memcached' servers. When you store Python data structures as `memcached' items, they are automatically serialized (turned into string values) using the Python `cPickle' or `pickle' modules. To create a new `memcache' interface, import the `memcache' module and create a new instance of the `memcache.Client' class. For example, if the `memcached' daemon is running on localhost using the default port: import memcache memc = memcache.Client(['127.0.0.1:11211']) The first argument is an array of strings containing the server and port number for each `memcached' instance to use. To enable debugging, set the optional `debug' parameter to 1. By default, the hashing mechanism used to divide the items among multiple servers is `crc32'. To change the function used, set the value of `memcache.serverHashFunction' to the alternate function to use. For example: from zlib import adler32 memcache.serverHashFunction = adler32 Once you have defined the servers to use within the `memcache' instance, the core functions provide the same functionality as in the generic interface specification. The following table provides a summary of the supported functions: This table lists Python `memcached' functions and the equivalent generic functions in the `memcached' interface specification. Python `memcache' Function Equivalent Generic Function `get()' Generic `get()'. `get_multi(keys)' Gets multiple values from the supplied array of `keys'. Returns a hash reference of key/value pairs. `set()' Generic `set()'. `set_multi(dict [, expiry [, Sets multiple key/value pairs from key_prefix]])' the supplied `dict'. `add()' Generic `add()'. `replace()' Generic `replace()'. `prepend(key, value [, expiry])' Prepends the supplied `value' to the value of the existing `key'. `append(key, value [, expiry[)' Appends the supplied `value' to the value of the existing `key'. `delete()' Generic `delete()'. `delete_multi(keys [, expiry [, Deletes all the keys from the hash key_prefix]] )' matching each string in the array `keys'. `incr()' Generic `incr()'. `decr()' Generic `decr()'. *Note*: Within the Python `memcache' module, all the `*_multi()'functions support an optional `key_prefix' parameter. If supplied, then the string is used as a prefix to all key lookups. For example, if you call: memc.get_multi(['a','b'], key_prefix='users:') The function retrieves the keys `users:a' and `users:b' from the servers. Here is an example showing the storage and retrieval of information to a `memcache' instance, loading the raw data from MySQL: import sys import MySQLdb import memcache memc = memcache.Client(['127.0.0.1:11211'], debug=1); try: conn = MySQLdb.connect (host = "localhost", user = "sakila", passwd = "password", db = "sakila") except MySQLdb.Error, e: print "Error %d: %s" % (e.args[0], e.args[1]) sys.exit (1) popularfilms = memc.get('top5films') if not popularfilms: cursor = conn.cursor() cursor.execute('select film_id,title from film order by rental_rate desc limit 5') rows = cursor.fetchall() memc.set('top5films',rows,60) print "Updated memcached with MySQL data" else: print "Loaded data from memcached" for row in popularfilms: print "%s, %s" % (row[0], row[1]) When executed for the first time, the data is loaded from the MySQL database and stored to the `memcached' server. shell> python memc_python.py Updated memcached with MySQL data Because the data is automatically serialized using `cPickle'/`pickle', when you load the data back from `memcached', you can use the object directly. In the example above, the information stored to `memcached' is in the form of rows from a Python DB cursor. When accessing the information (within the 60 second expiry time), the data is loaded from `memcached' and dumped: shell> python memc_python.py Loaded data from memcached 2, ACE GOLDFINGER 7, AIRPLANE SIERRA 8, AIRPORT POLLOCK 10, ALADDIN CALENDAR 13, ALI FOREVER The serialization and deserialization happens automatically. Because serialization of Python data may be incompatible with other interfaces and languages, you can change the serialization module used during initialization. For example, you might use JSON format when you store complex data structures using a script written in one language, and access them in a script written in a different language.  File: manual.info, Node: ha-memcached-interfaces-php, Next: ha-memcached-interfaces-ruby, Prev: ha-memcached-interfaces-python, Up: ha-memcached-interfaces 15.6.3.12 Using MySQL and `memcached' with PHP .............................................. PHP provides support for the Memcache functions through a PECL extension. To enable the PHP `memcache' extensions, build PHP using the `--enable-memcache' option to `configure' when building from source. If you are installing on a Red Hat-based server, you can install the `php-pecl-memcache' RPM: root-shell> yum --install php-pecl-memcache On Debian-based distributions, use the `php-memcache' package. To set global runtime configuration options, specify the configuration option values within your `php.ini' file. The following table provides the name, default value, and a description for each global runtime configuration option. This table lists global runtime configuration options for the PECL `Memcache' extension. The table provides configuration option names, default values, and descriptions. Configuration option Default Description `memcache.allow_failover' 1 Specifies whether another server in the list should be queried if the first server selected fails. `memcache.max_failover_attempts'20 Specifies the number of servers to try before returning a failure. `memcache.chunk_size' 8192 Defines the size of network chunks used to exchange data with the `memcached' server. `memcache.default_port' 11211 Defines the default port to use when communicating with the `memcached' servers. `memcache.hash_strategy' standard Specifies which hash strategy to use. Set to `consistent' to enable servers to be added or removed from the pool without causing the keys to be remapped to other servers. When set to `standard', an older (modula) strategy is used that potentially uses different servers for storage. `memcache.hash_function' crc32 Specifies which function to use when mapping keys to servers. `crc32' uses the standard CRC32 hash. `fnv' uses the FNV-1a hashing algorithm. To create a connection to a `memcached' server, create a new `Memcache' object and then specify the connection options. For example: connect('localhost',11211); ?> This opens an immediate connection to the specified server. To use multiple `memcached' servers, you need to add servers to the memcache object using `addServer()': bool Memcache::addServer ( string $host [, int $port [, bool $persistent [, int $weight [, int $timeout [, int $retry_interval [, bool $status [, callback $failure_callback ]]]]]]] ) The server management mechanism within the `php-memcache' module is a critical part of the interface as it controls the main interface to the `memcached' instances and how the different instances are selected through the hashing mechanism. To create a simple connection to two `memcached' instances: addServer('192.168.0.100',11211); $cache->addServer('192.168.0.101',11211); ?> In this scenario, the instance connection is not explicitly opened, but only opened when you try to store or retrieve a value. To enable persistent connections to `memcached' instances, set the `$persistent' argument to true. This is the default setting, and causes the connections to remain open. To help control the distribution of keys to different instances, use the global `memcache.hash_strategy' setting. This sets the hashing mechanism used to select. You can also add another weight to each server, which effectively increases the number of times the instance entry appears in the instance list, therefore increasing the likelihood of the instance being chosen over other instances. To set the weight, set the value of the `$weight' argument to more than one. The functions for setting and retrieving information are identical to the generic functional interface offered by `memcached', as shown in this table: This table lists PECL `memcached' functions and the equivalent generic functions in the `memcached' interface specification. PECL `memcache' Function Generic Function `get()' Generic `get()'. `set()' Generic `set()'. `add()' Generic `add()'. `replace()' Generic `replace()'. `delete()' Generic `delete()'. `increment()' Generic `incr()'. `decrement()' Generic `decr()'. A full example of the PECL `memcache' interface is provided below. The code loads film data from the Sakila database when the user provides a film name. The data stored into the `memcached' instance is recorded as a `mysqli' result row, and the API automatically serializes the information for you. addServer('localhost','11211'); if(empty($_POST['film'])) { ?> Simple Memcache Lookup

Film:

get($film); if ($mfilms) { printf("

Film data for %s loaded from memcache

", $mfilms['title']); foreach (array_keys($mfilms) as $key) { printf("

%s: %s

", $key, $mfilms[$key]); } } else { $mysqli = mysqli('localhost','sakila','password','sakila'); if (mysqli_connect_error()) { sprintf("Database error: (%d) %s", mysqli_connect_errno(), mysqli_connect_error()); exit; } $sql = sprintf('SELECT * FROM film WHERE title="%s"', $mysqli->real_escape_string($film)); $result = $mysqli->query($sql); if (!$result) { sprintf("Database error: (%d) %s", $mysqli->errno, $mysqli->error); exit; } $row = $result->fetch_assoc(); $memc->set($row['title'], $row); printf("

Loaded (%s) from MySQL

", htmlspecialchars($row['title'], ENT_QUOTES, 'UTF-8'); } } ?> With PHP, the connections to the `memcached' instances are kept open as long as the PHP and associated Apache instance remain running. When adding or removing servers from the list in a running instance (for example, when starting another script that mentions additional servers), the connections are shared, but the script only selects among the instances explicitly configured within the script. To ensure that changes to the server list within a script do not cause problems, make sure to use the consistent hashing mechanism.  File: manual.info, Node: ha-memcached-interfaces-ruby, Next: ha-memcached-interfaces-java, Prev: ha-memcached-interfaces-php, Up: ha-memcached-interfaces 15.6.3.13 Using MySQL and `memcached' with Ruby ............................................... There are a number of different modules for interfacing to `memcached' within Ruby. The `Ruby-MemCache' client library provides a native interface to `memcached' that does not require any external libraries, such as `libmemcached'. You can obtain the installer package from `http://www.deveiate.org/projects/RMemCache'. To install, extract the package and then run `install.rb': shell> install.rb If you have RubyGems, you can install the `Ruby-MemCache' gem: shell> gem install Ruby-MemCache Bulk updating Gem source index for: http://gems.rubyforge.org Install required dependency io-reactor? [Yn] y Successfully installed Ruby-MemCache-0.0.1 Successfully installed io-reactor-0.05 Installing ri documentation for io-reactor-0.05... Installing RDoc documentation for io-reactor-0.05... To use a `memcached' instance from within Ruby, create a new instance of the `MemCache' object. require 'memcache' memc = MemCache::new '192.168.0.100:11211' You can add a weight to each server to increase the likelihood of the server being selected during hashing by appending the weight count to the server host name/port string: require 'memcache' memc = MemCache::new '192.168.0.100:11211:3' To add servers to an existing list, you can append them directly to the `MemCache' object: memc += ["192.168.0.101:11211"] To set data into the cache, you can just assign a value to a key within the new cache object, which works just like a standard Ruby hash object: memc["key"] = "value" Or to retrieve the value: print memc["key"] For more explicit actions, you can use the method interface, which mimics the main `memcached' API functions, as summarized in the following table: This table lists `memcached' methods for Ruby and the equivalent `memcached' API functions. Ruby `MemCache' Method Equivalent `memcached' API Functions `get()' Generic `get()'. `get_hash(keys)' Get the values of multiple `keys', returning the information as a hash of the keys and their values. `set()' Generic `set()'. `set_many(pairs)' Set the values of the keys and values in the hash `pairs'. `add()' Generic `add()'. `replace()' Generic `replace()'. `delete()' Generic `delete()'. `incr()' Generic `incr()'. `decr()' Generic `decr()'.  File: manual.info, Node: ha-memcached-interfaces-java, Next: ha-memcached-interfaces-protocol, Prev: ha-memcached-interfaces-ruby, Up: ha-memcached-interfaces 15.6.3.14 Using MySQL and `memcached' with Java ............................................... The `com.danga.MemCached' class within Java provides a native interface to `memcached' instances. You can obtain the client from `https://github.com/gwhalin/Memcached-Java-Client/downloads'. The Java class uses hashes that are compatible with `libmemcached', so you can mix and match Java and `libmemcached' applications accessing the same `memcached' instances. The serialization between Java and other interfaces are not compatible. If this is a problem, use JSON or a similar nonbinary serialization format. On most systems, you can download the package and use the `jar' directly. To use the `com.danga.MemCached' interface, you create a `MemCachedClient' instance and then configure the list of servers by configuring the `SockIOPool'. Through the pool specification you set up the server list, weighting, and the connection parameters to optimized the connections between your client and the `memcached' instances that you configure. Generally, you can configure the `memcached' interface once within a single class, then use this interface throughout the rest of your application. For example, to create a basic interface, first configure the `MemCachedClient' and base `SockIOPool' settings: public class MyClass { protected static MemCachedClient mcc = new MemCachedClient(); static { String[] servers = { "localhost:11211", }; Integer[] weights = { 1 }; SockIOPool pool = SockIOPool.getInstance(); pool.setServers( servers ); pool.setWeights( weights ); In the above sample, the list of servers is configured by creating an array of the `memcached' instances to use. You can then configure individual weights for each server. The remainder of the properties for the connection are optional, but you can set the connection numbers (initial connections, minimum connections, maximum connections, and the idle timeout) by setting the pool parameters: pool.setInitConn( 5 ); pool.setMinConn( 5 ); pool.setMaxConn( 250 ); pool.setMaxIdle( 1000 * 60 * 60 * 6 Once the parameters have been configured, initialize the connection pool: pool.initialize(); The pool, and the connection to your `memcached' instances should now be ready to use. To set the hashing algorithm used to select the server used when storing a given key, use `pool.setHashingAlg()': pool.setHashingAlg( SockIOPool.NEW_COMPAT_HASH ); Valid values are `NEW_COMPAT_HASH', `OLD_COMPAT_HASH' and `NATIVE_HASH' are also basic modula hashing algorithms. For a consistent hashing algorithm, use `CONSISTENT_HASH'. These constants are equivalent to the corresponding hash settings within `libmemcached'. The following table outlines the Java `com.danga.MemCached' methods and the equivalent generic methods in the `memcached' interface specification. This table lists Java `com.danga.MemCached' methods and the equivalent generic methods in the `memcached' interface specification. Java `com.danga.MemCached' Method Equivalent Generic Method `get()' Generic `get()'. `getMulti(keys)' Get the values of multiple `keys', returning the information as Hash map using `java.lang.String' for the keys and `java.lang.Object' for the corresponding values. `set()' Generic `set()'. `add()' Generic `add()'. `replace()' Generic `replace()'. `delete()' Generic `delete()'. `incr()' Generic `incr()'. `decr()' Generic `decr()'.  File: manual.info, Node: ha-memcached-interfaces-protocol, Prev: ha-memcached-interfaces-java, Up: ha-memcached-interfaces 15.6.3.15 Using the `memcached' TCP Text Protocol ................................................. Communicating with a `memcached' server can be achieved through either the TCP or UDP protocols. When using the TCP protocol, you can use a simple text based interface for the exchange of information. When communicating with `memcached', you can connect to the server using the port configured for the server. You can open a connection with the server without requiring authorization or login. As soon as you have connected, you can start to send commands to the server. When you have finished, you can terminate the connection without sending any specific disconnection command. Clients are encouraged to keep their connections open to decrease latency and improve performance. Data is sent to the `memcached' server in two forms: * Text lines, which are used to send commands to the server, and receive responses from the server. * Unstructured data, which is used to receive or send the value information for a given key. Data is returned to the client in exactly the format it was provided. Both text lines (commands and responses) and unstructured data are always terminated with the string `\r\n'. Because the data being stored may contain this sequence, the length of the data (returned by the client before the unstructured data is transmitted should be used to determine the end of the data. Commands to the server are structured according to their operation: * *Storage commands*: `set', `add', `replace', `append', `prepend', `cas' Storage commands to the server take the form: command key [flags] [exptime] length [noreply] Or when using compare and swap (cas): cas key [flags] [exptime] length [casunique] [noreply] Where: * `command': The command name. * `set': Store value against key * `add': Store this value against key if the key does not already exist * `replace': Store this value against key if the key already exists * `append': Append the supplied value to the end of the value for the specified key. The `flags' and `exptime' arguments should not be used. * `prepend': Append value currently in the cache to the end of the supplied value for the specified key. The `flags' and `exptime' arguments should not be used. * `cas': Set the specified key to the supplied value, only if the supplied `casunique' matches. This is effectively the equivalent of change the information if nobody has updated it since I last fetched it. * `key': The key. All data is stored using a the specific key. The key cannot contain control characters or whitespace, and can be up to 250 characters in size. * `flags': The flags for the operation (as an integer). Flags in `memcached' are transparent. The `memcached' server ignores the contents of the flags. They can be used by the client to indicate any type of information. In `memcached' 1.2.0 and lower the value is a 16-bit integer value. In `memcached' 1.2.1 and higher the value is a 32-bit integer. * `exptime': The expiry time, or zero for no expiry. * `length': The length of the supplied value block in bytes, excluding the terminating `\r\n' characters. * `casunique': A unique 64-bit value of an existing entry. This is used to compare against the existing value. Use the value returned by the `gets' command when issuing `cas' updates. * `noreply': Tells the server not to reply to the command. For example, to store the value `abcdef' into the key `xyzkey', you would use: set xyzkey 0 0 6\r\nabcdef\r\n The return value from the server is one line, specifying the status or error information. For more information, see *Note ha-memcached-interfaces-protocol-responses::. * *Retrieval commands*: `get', `gets' Retrieval commands take the form: get key1 [key2 .... keyn] gets key1 [key2 ... keyn] You can supply multiple keys to the commands, with each requested key separated by whitespace. The server responds with an information line of the form: VALUE key flags bytes [casunique] Where: * `key': The key name. * `flags': The value of the flag integer supplied to the `memcached' server when the value was stored. * `bytes': The size (excluding the terminating `\r\n' character sequence) of the stored value. * `casunique': The unique 64-bit integer that identifies the item. The information line is immediately followed by the value data block. For example: get xyzkey\r\n VALUE xyzkey 0 6\r\n abcdef\r\n If you have requested multiple keys, an information line and data block is returned for each key found. If a requested key does not exist in the cache, no information is returned. * *Delete commands*: `delete' Deletion commands take the form: delete key [time] [noreply] Where: * `key': The key name. * `time': The time in seconds (or a specific Unix time) for which the client wishes the server to refuse `add' or `replace' commands on this key. All `add', `replace', `get', and `gets' commands fail during this period. `set' operations succeed. After this period, the key is deleted permanently and all commands are accepted. If not supplied, the value is assumed to be zero (delete immediately). * `noreply': Tells the server not to reply to the command. Responses to the command are either `DELETED' to indicate that the key was successfully removed, or `NOT_FOUND' to indicate that the specified key could not be found. * *Increment/Decrement*: `incr', `decr' The increment and decrement commands change the value of a key within the server without performing a separate get/set sequence. The operations assume that the currently stored value is a 64-bit integer. If the stored value is not a 64-bit integer, then the value is assumed to be zero before the increment or decrement operation is applied. Increment and decrement commands take the form: incr key value [noreply] decr key value [noreply] Where: * `key': The key name. * `value': An integer to be used as the increment or decrement value. * `noreply': Tells the server not to reply to the command. The response is: * `NOT_FOUND': The specified key could not be located. * `value': The new value associated with the specified key. Values are assumed to be unsigned. For `decr' operations, the value is never decremented below 0. For `incr' operations, the value wraps around the 64-bit maximum. * *Statistics commands*: `stats' The `stats' command provides detailed statistical information about the current status of the `memcached' instance and the data it is storing. Statistics commands take the form: STAT [name] [value] Where: * `name': The optional name of the statistics to return. If not specified, the general statistics are returned. * `value': A specific value to be used when performing certain statistics operations. The return value is a list of statistics data, formatted as follows: STAT name value The statistics are terminated with a single line, `END'. For more information, see *Note ha-memcached-stats::. For reference, a list of the different commands supported and their formats is provided below. *`memcached' Command Reference* Command Command Formats `set' `set key flags exptime length', `set key flags exptime length noreply' `add' `add key flags exptime length', `add key flags exptime length noreply' `replace' `replace key flags exptime length', `replace key flags exptime length noreply' `append' `append key length', `append key length noreply' `prepend' `prepend key length', `prepend key length noreply' `cas' `cas key flags exptime length casunique', `cas key flags exptime length casunique noreply' `get' `get key1 [key2 ... keyn]' `gets' `' `delete' `delete key', `delete key noreply', `delete key expiry', `delete key expiry noreply' `incr' `incr key', `incr key noreply', `incr key value', `incr key value noreply' `decr' `decr key', `decr key noreply', `decr key value', `decr key value noreply' `stat' `stat', `stat name', `stat name value' When sending a command to the server, the response from the server is one of the settings in the following table. All response values from the server are terminated by `\r\n': *`memcached' Protocol Responses* String Description `STORED' Value has successfully been stored. `NOT_STORED' The value was not stored, but not because of an error. For commands where you are adding a or updating a value if it exists (such as `add' and `replace'), or where the item has already been set to be deleted. `EXISTS' When using a `cas' command, the item you are trying to store already exists and has been modified since you last checked it. `NOT_FOUND' The item you are trying to store, update or delete does not exist or has already been deleted. `ERROR' You submitted a nonexistent command name. `CLIENT_ERROR There was an error in the input line, the detail is errorstring' contained in `errorstring'. `SERVER_ERROR There was an error in the server that prevents it errorstring' from returning the information. In extreme conditions, the server may disconnect the client after this error occurs. `VALUE keys flags The requested key has been found, and the stored length' `key', `flags' and data block are returned, of the specified `length'. `DELETED' The requested key was deleted from the server. `STAT name value' A line of statistics data. `END' The end of the statistics data.  File: manual.info, Node: ha-memcached-stats, Next: ha-memcached-faq, Prev: ha-memcached-interfaces, Up: ha-memcached 15.6.4 Getting `memcached' Statistics ------------------------------------- * Menu: * ha-memcached-stats-general:: `memcached' General Statistics * ha-memcached-stats-slabs:: `memcached' Slabs Statistics * ha-memcached-stats-items:: `memcached' Item Statistics * ha-memcached-stats-sizes:: `memcached' Size Statistics * ha-memcached-stats-detail:: `memcached' Detail Statistics * ha-memcached-stats-memcached-tool:: Using `memcached-tool' The `memcached' system has a built-in statistics system that collects information about the data being stored into the cache, cache hit ratios, and detailed information on the memory usage and distribution of information through the slab allocation used to store individual items. Statistics are provided at both a basic level that provide the core statistics, and more specific statistics for specific areas of the `memcached' server. This information can be useful to ensure that you are getting the correct level of cache and memory usage, and that your slab allocation and configuration properties are set at an optimal level. The stats interface is available through the standard `memcached' protocol, so the reports can be accessed by using `telnet' to connect to the `memcached'. The supplied `memcached-tool' includes support for obtaining the *Note ha-memcached-stats-slabs:: and *Note ha-memcached-stats-general:: information. For more information, see *Note ha-memcached-stats-memcached-tool::. Alternatively, most of the language API interfaces provide a function for obtaining the statistics from the server. For example, to get the basic stats using `telnet': shell> telnet localhost 11211 Trying ::1... Connected to localhost. Escape character is '^]'. stats STAT pid 23599 STAT uptime 675 STAT time 1211439587 STAT version 1.2.5 STAT pointer_size 32 STAT rusage_user 1.404992 STAT rusage_system 4.694685 STAT curr_items 32 STAT total_items 56361 STAT bytes 2642 STAT curr_connections 53 STAT total_connections 438 STAT connection_structures 55 STAT cmd_get 113482 STAT cmd_set 80519 STAT get_hits 78926 STAT get_misses 34556 STAT evictions 0 STAT bytes_read 6379783 STAT bytes_written 4860179 STAT limit_maxbytes 67108864 STAT threads 1 END When using Perl and the `Cache::Memcached' module, the `stats()' function returns information about all the servers currently configured in the connection object, and total statistics for all the `memcached' servers as a whole. For example, the following Perl script obtains the stats and dumps the hash reference that is returned: use Cache::Memcached; use Data::Dumper; my $memc = new Cache::Memcached; $memc->set_servers(\@ARGV); print Dumper($memc->stats()); When executed on the same `memcached' as used in the `Telnet' example above we get a hash reference with the host by host and total statistics: $VAR1 = { 'hosts' => { 'localhost:11211' => { 'misc' => { 'bytes' => '2421', 'curr_connections' => '3', 'connection_structures' => '56', 'pointer_size' => '32', 'time' => '1211440166', 'total_items' => '410956', 'cmd_set' => '588167', 'bytes_written' => '35715151', 'evictions' => '0', 'curr_items' => '31', 'pid' => '23599', 'limit_maxbytes' => '67108864', 'uptime' => '1254', 'rusage_user' => '9.857805', 'cmd_get' => '838451', 'rusage_system' => '34.096988', 'version' => '1.2.5', 'get_hits' => '581511', 'bytes_read' => '46665716', 'threads' => '1', 'total_connections' => '3104', 'get_misses' => '256940' }, 'sizes' => { '128' => '16', '64' => '15' } } }, 'self' => {}, 'total' => { 'cmd_get' => 838451, 'bytes' => 2421, 'get_hits' => 581511, 'connection_structures' => 56, 'bytes_read' => 46665716, 'total_items' => 410956, 'total_connections' => 3104, 'cmd_set' => 588167, 'bytes_written' => 35715151, 'curr_items' => 31, 'get_misses' => 256940 } }; The statistics are divided up into a number of distinct sections, and then can be requested by adding the type to the `stats' command. Each statistics output is covered in more detail in the following sections. * General statistics, see *Note ha-memcached-stats-general::. * Slab statistics (`slabs'), see *Note ha-memcached-stats-slabs::. * Item statistics (`items'), see *Note ha-memcached-stats-items::. * Size statistics (`sizes'), see *Note ha-memcached-stats-sizes::. * Detailed status (`detail'), see *Note ha-memcached-stats-detail::.  File: manual.info, Node: ha-memcached-stats-general, Next: ha-memcached-stats-slabs, Prev: ha-memcached-stats, Up: ha-memcached-stats 15.6.4.1 `memcached' General Statistics ....................................... The output of the general statistics provides an overview of the performance and use of the `memcached' instance. The statistics returned by the command and their meaning is shown in the following table. The following terms are used to define the value type for each statistics value: * `32u': 32-bit unsigned integer * `64u': 64-bit unsigned integer * `32u:32u': Two 32-bit unsigned integers separated by a colon * `String': Character string This table lists `memcached' general statistics and provides the data type and a description for each statistic. Statistic Data type Description Version `pid' 32u Process ID of the `memcached' instance. `uptime' 32u Uptime (in seconds) for this `memcached' instance. `time' 32u Current time (as epoch). `version' string Version string of this instance. `pointer_size' string Size of pointers for this host specified in bits (32 or 64). `rusage_user' 32u:32u Total user time for this instance (seconds:microseconds). `rusage_system'32u:32u Total system time for this instance (seconds:microseconds). `curr_items' 32u Current number of items stored by this instance. `total_items' 32u Total number of items stored during the life of this instance. `bytes' 64u Current number of bytes used by this server to store items. `curr_connections'32u Current number of open connections. `total_connections'32u Total number of connections opened since the server started running. `connection_structures'32u Number of connection structures allocated by the server. `cmd_get' 64u Total number of retrieval requests (`get' operations). `cmd_set' 64u Total number of storage requests (`set' operations). `get_hits' 64u Number of keys that have been requested and found present. `get_misses' 64u Number of items that have been requested and not found. `delete_hits' 64u Number of keys that have been deleted 1.3.x and found present. `delete_misses'64u Number of items that have been delete 1.3.x and not found. `incr_hits' 64u Number of keys that have been 1.3.x incremented and found present. `incr_misses' 64u Number of items that have been 1.3.x incremented and not found. `decr_hits' 64u Number of keys that have been 1.3.x decremented and found present. `decr_misses' 64u Number of items that have been 1.3.x decremented and not found. `cas_hits' 64u Number of keys that have been compared 1.3.x and swapped and found present. `cas_misses' 64u Number of items that have been compared 1.3.x and swapped and not found. `cas_badvalue' 64u Number of keys that have been compared 1.3.x and swapped, but the comparison (original) value did not match the supplied value. `evictions' 64u Number of valid items removed from cache to free memory for new items. `bytes_read' 64u Total number of bytes read by this server from network. `bytes_written'64u Total number of bytes sent by this server to network. `limit_maxbytes'32u Number of bytes this server is permitted to use for storage. `threads' 32u Number of worker threads requested. `conn_yields' 64u Number of yields for connections 1.4.0 (related to the `-R' option). The most useful statistics from those given here are the number of cache hits, misses, and evictions. A large number of `get_misses' may just be an indication that the cache is still being populated with information. The number should, over time, decrease in comparison to the number of cache `get_hits'. If, however, you have a large number of cache misses compared to cache hits after an extended period of execution, it may be an indication that the size of the cache is too small and you either need to increase the total memory size, or increase the number of the `memcached' instances to improve the hit ratio. A large number of `evictions' from the cache, particularly in comparison to the number of items stored is a sign that your cache is too small to hold the amount of information that you regularly want to keep cached. Instead of items being retained in the cache, items are being evicted to make way for new items keeping the turnover of items in the cache high, reducing the efficiency of the cache.  File: manual.info, Node: ha-memcached-stats-slabs, Next: ha-memcached-stats-items, Prev: ha-memcached-stats-general, Up: ha-memcached-stats 15.6.4.2 `memcached' Slabs Statistics ..................................... To get the `slabs' statistics, use the `stats slabs' command, or the API equivalent. The slab statistics provide you with information about the slabs that have created and allocated for storing information within the cache. You get information both on each individual slab-class and total statistics for the whole slab. STAT 1:chunk_size 104 STAT 1:chunks_per_page 10082 STAT 1:total_pages 1 STAT 1:total_chunks 10082 STAT 1:used_chunks 10081 STAT 1:free_chunks 1 STAT 1:free_chunks_end 10079 STAT 9:chunk_size 696 STAT 9:chunks_per_page 1506 STAT 9:total_pages 63 STAT 9:total_chunks 94878 STAT 9:used_chunks 94878 STAT 9:free_chunks 0 STAT 9:free_chunks_end 0 STAT active_slabs 2 STAT total_malloced 67083616 END Individual stats for each slab class are prefixed with the slab ID. A unique ID is given to each allocated slab from the smallest size up to the largest. The prefix number indicates the slab class number in relation to the calculated chunk from the specified growth factor. Hence in the example, 1 is the first chunk size and 9 is the 9th chunk allocated size. The parameters returned for each chunk size and a description of each parameter are provided in the following table. This table lists `memcached' slabs statistics parameters that are returned for each chunk size. The table provides the statistic name, description, and version (if applicable). Statistic Description Version `chunk_size' Space allocated to each chunk within this slab class. `chunks_per_page' Number of chunks within a single page for this slab class. `total_pages' Number of pages allocated to this slab class. `total_chunks' Number of chunks allocated to the slab class. `used_chunks' Number of chunks allocated to an item.. `free_chunks' Number of chunks not yet allocated to items. `free_chunks_end' Number of free chunks at the end of the last allocated page. `get_hits' Number of get hits to this chunk 1.3.x `cmd_set' Number of set commands on this chunk 1.3.x `delete_hits' Number of delete hits to this chunk 1.3.x `incr_hits' Number of increment hits to this chunk 1.3.x `decr_hits' Number of decrement hits to this chunk 1.3.x `cas_hits' Number of CAS hits to this chunk 1.3.x `cas_badval' Number of CAS hits on this chunk where 1.3.x the existing value did not match `mem_requested' The true amount of memory of memory 1.4.1 requested within this chunk The following additional statistics cover the information for the entire server, rather than on a chunk by chunk basis: This table lists `memcached' slab statistics that provide information for the the entire server rather than for a single chunk. The table provides the statistic name, description, and version (if applicable). Statistic Description Version `active_slabs' Total number of slab classes allocated. `total_malloced' Total amount of memory allocated to slab pages. The key values in the slab statistics are the `chunk_size', and the corresponding `total_chunks' and `used_chunks' parameters. These given an indication of the size usage of the chunks within the system. Remember that one key/value pair is placed into a chunk of a suitable size. From these stats, you can get an idea of your size and chunk allocation and distribution. If you store many items with a number of largely different sizes, consider adjusting the chunk size growth factor to increase in larger steps to prevent chunk and memory wastage. A good indication of a bad growth factor is a high number of different slab classes, but with relatively few chunks actually in use within each slab. Increasing the growth factor creates fewer slab classes and therefore makes better use of the allocated pages.  File: manual.info, Node: ha-memcached-stats-items, Next: ha-memcached-stats-sizes, Prev: ha-memcached-stats-slabs, Up: ha-memcached-stats 15.6.4.3 `memcached' Item Statistics .................................... To get the `items' statistics, use the `stats items' command, or the API equivalent. The `items' statistics give information about the individual items allocated within a given slab class. STAT items:2:number 1 STAT items:2:age 452 STAT items:2:evicted 0 STAT items:2:evicted_nonzero 0 STAT items:2:evicted_time 2 STAT items:2:outofmemory 0 STAT items:2:tailrepairs 0 ... STAT items:27:number 1 STAT items:27:age 452 STAT items:27:evicted 0 STAT items:27:evicted_nonzero 0 STAT items:27:evicted_time 2 STAT items:27:outofmemory 0 STAT items:27:tailrepairs 0 The prefix number against each statistics relates to the corresponding chunk size, as returned by the `stats slabs' statistics. The result is a display of the number of items stored within each chunk within each slab size, and specific statistics about their age, eviction counts, and out of memory counts. A summary of the statistics is given in the following table. This table lists `memcached' item statistics and provides a description of each. Statistic Description `number' The number of items currently stored in this slab class. `age' The age of the oldest item within the slab class, in seconds. `evicted' The number of items evicted to make way for new entries. `evicted_time' The time of the last evicted entry `evicted_nonzero' The time of the last evicted non-zero entry 1.4.0 `outofmemory' The number of items for this slab class that have triggered an out of memory error (only value when the `-M' command line option is in effect). `tailrepairs' Number of times the entries for a particular ID need repairing Item level statistics can be used to determine how many items are stored within a given slab and their freshness and recycle rate. You can use this to help identify whether there are certain slab classes that are triggering a much larger number of evictions that others.  File: manual.info, Node: ha-memcached-stats-sizes, Next: ha-memcached-stats-detail, Prev: ha-memcached-stats-items, Up: ha-memcached-stats 15.6.4.4 `memcached' Size Statistics .................................... To get size statistics, use the `stats sizes' command, or the API equivalent. The size statistics provide information about the sizes and number of items of each size within the cache. The information is returned as two columns, the first column is the size of the item (rounded up to the nearest 32 byte boundary), and the second column is the count of the number of items of that size within the cache: 96 35 128 38 160 807 192 804 224 410 256 222 288 83 320 39 352 53 384 33 416 64 448 51 480 30 512 54 544 39 576 10065 *Caution*: Running this statistic locks up your cache as each item is read from the cache and its size calculated. On a large cache, this may take some time and prevent any set or get operations until the process completes. The item size statistics are useful only to determine the sizes of the objects you are storing. Since the actual memory allocation is relevant only in terms of the chunk size and page size, the information is only useful during a careful debugging or diagnostic session.  File: manual.info, Node: ha-memcached-stats-detail, Next: ha-memcached-stats-memcached-tool, Prev: ha-memcached-stats-sizes, Up: ha-memcached-stats 15.6.4.5 `memcached' Detail Statistics ...................................... For `memcached' 1.3.x and higher, you can enable and obtain detailed statistics about the get, set, and del operations on theindividual keys stored in the cache, and determine whether the attempts hit (found) a particular key. These operations are only recorded while the detailed stats analysis is turned on. To enable detailed statistics, you must send the `stats detail on' command to the `memcached' server: $ telnet localhost 11211 Trying 127.0.0.1... Connected to tiger. Escape character is '^]'.stats detail on OK Individual statistics are recorded for every `get', `set' and `del' operation on a key, including keys that are not currently stored in the server. For example, if an attempt is made to obtain the value of key `abckey' and it does not exist, the `get' operating on the specified key are recorded while detailed statistics are in effect, even if the key is not currently stored. The `hits', that is, the number of `get' or `del' operations for a key that exists in the server are also counted. To turn detailed statistics off, send the `stats detail off' command to the `memcached' server: $ telnet localhost 11211 Trying 127.0.0.1... Connected to tiger. Escape character is '^]'.stats detail on OK To obtain the detailed statistics recorded during the process, send the `stats detail dump' command to the `memcached' server: stats detail dump PREFIX hykkey get 0 hit 0 set 1 del 0 PREFIX xyzkey get 0 hit 0 set 1 del 0 PREFIX yukkey get 1 hit 0 set 0 del 0 PREFIX abckey get 3 hit 3 set 1 del 0 END You can use the detailed statistics information to determine whether your `memcached' clients are using a large number of keys that do not exist in the server by comparing the `hit' and `get' or `del' counts. Because the information is recorded by key, you can also determine whether the failures or operations are clustered around specific keys.  File: manual.info, Node: ha-memcached-stats-memcached-tool, Prev: ha-memcached-stats-detail, Up: ha-memcached-stats 15.6.4.6 Using `memcached-tool' ............................... The `memcached-tool', located within the `scripts' directory within the `memcached' source directory. The tool provides convenient access to some reports and statistics from any `memcached' instance. The basic format of the command is: shell> ./memcached-tool hostname:port [command] The default output produces a list of the slab allocations and usage. For example: shell> memcached-tool localhost:11211 display # Item_Size Max_age Pages Count Full? Evicted Evict_Time OOM 1 80B 93s 1 20 no 0 0 0 2 104B 93s 1 16 no 0 0 0 3 136B 1335s 1 28 no 0 0 0 4 176B 1335s 1 24 no 0 0 0 5 224B 1335s 1 32 no 0 0 0 6 280B 1335s 1 34 no 0 0 0 7 352B 1335s 1 36 no 0 0 0 8 440B 1335s 1 46 no 0 0 0 9 552B 1335s 1 58 no 0 0 0 10 696B 1335s 1 66 no 0 0 0 11 872B 1335s 1 89 no 0 0 0 12 1.1K 1335s 1 112 no 0 0 0 13 1.3K 1335s 1 145 no 0 0 0 14 1.7K 1335s 1 123 no 0 0 0 15 2.1K 1335s 1 198 no 0 0 0 16 2.6K 1335s 1 199 no 0 0 0 17 3.3K 1335s 1 229 no 0 0 0 18 4.1K 1335s 1 248 yes 36 2 0 19 5.2K 1335s 2 328 no 0 0 0 20 6.4K 1335s 2 316 yes 387 1 0 21 8.1K 1335s 3 381 yes 492 1 0 22 10.1K 1335s 3 303 yes 598 2 0 23 12.6K 1335s 5 405 yes 605 1 0 24 15.8K 1335s 6 384 yes 766 2 0 25 19.7K 1335s 7 357 yes 908 170 0 26 24.6K 1336s 7 287 yes 1012 1 0 27 30.8K 1336s 7 231 yes 1193 169 0 28 38.5K 1336s 4 104 yes 1323 169 0 29 48.1K 1336s 1 21 yes 1287 1 0 30 60.2K 1336s 1 17 yes 1093 169 0 31 75.2K 1337s 1 13 yes 713 168 0 32 94.0K 1337s 1 10 yes 278 168 0 33 117.5K 1336s 1 3 no 0 0 0 This output is the same if you specify the `command' as `display': shell> memcached-tool localhost:11211 display # Item_Size Max_age Pages Count Full? Evicted Evict_Time OOM 1 80B 93s 1 20 no 0 0 0 2 104B 93s 1 16 no 0 0 0 ... The output shows a summarized version of the output from the `slabs' statistics. The columns provided in the output are shown below: * `#': The slab number * `Item_Size': The size of the slab * `Max_age': The age of the oldest item in the slab * `Pages': The number of pages allocated to the slab * `Count': The number of items in this slab * `Full?': Whether the slab is fully populated * `Evicted': The number of objects evicted from this slab * `Evict_Time': The time (in seconds) since the last eviction * `OOM': The number of items that have triggered an out of memory error You can also obtain a dump of the general statistics for the server using the `stats' command: shell> memcached-tool localhost:11211 stats #localhost:11211 Field Value accepting_conns 1 bytes 162 bytes_read 485 bytes_written 6820 cas_badval 0 cas_hits 0 cas_misses 0 cmd_flush 0 cmd_get 4 cmd_set 2 conn_yields 0 connection_structures 11 curr_connections 10 curr_items 2 decr_hits 0 decr_misses 1 delete_hits 0 delete_misses 0 evictions 0 get_hits 4 get_misses 0 incr_hits 0 incr_misses 2 limit_maxbytes 67108864 listen_disabled_num 0 pid 12981 pointer_size 32 rusage_system 0.013911 rusage_user 0.011876 threads 4 time 1255518565 total_connections 20 total_items 2 uptime 880 version 1.4.2  File: manual.info, Node: ha-memcached-faq, Prev: ha-memcached-stats, Up: ha-memcached 15.6.5 `memcached' FAQ ---------------------- *Questions* * 16.6.5.1: Can memcached be run on a Windows environment? * 16.6.5.2: What is the maximum size of an object you can store in memcached? Is that configurable? * 16.6.5.3: Is it true `memcached' will be much more effective with db-read-intensive applications than with db-write-intensive applications? * 16.6.5.4: Is there any overhead in not using persistent connections? If persistent is always recommended, what are the downsides (for example, locking up)? * 16.6.5.5: How is an event such as a crash of one of the `memcached' servers handled by the `memcached' client? * 16.6.5.6: What is a recommended hardware configuration for a memcached server? * 16.6.5.7: Is memcached more effective for video and audio as opposed to textual read/writes? * 16.6.5.8: Can `memcached' work with ASPX? * 16.6.5.9: How expensive is it to establish a memcache connection? Should those connections be pooled? * 16.6.5.10: How is the data handled when the `memcached' server is down? * 16.6.5.11: How are auto-increment columns in the MySQL database coordinated across multiple instances of memcached? * 16.6.5.12: Is compression available? * 16.6.5.13: Can we implement different types of `memcached' as different nodes in the same server, so can there be deterministic and non-deterministic in the same server? * 16.6.5.14: What are best practices for testing an implementation, to ensure that it improves performance, and to measure the impact of `memcached' configuration changes? And would you recommend keeping the configuration very simple to start? *Questions and Answers* *16.6.5.1: ** Can memcached be run on a Windows environment? * No. Currently `memcached' is available only on the Unix/Linux platform. There is an unofficial port available, see `http://www.codeplex.com/memcachedproviders'. *16.6.5.2: ** What is the maximum size of an object you can store in memcached? Is that configurable? * The default maximum object size is 1MB. In `memcached' 1.4.2 and later, you can change the maximum size of an object using the `-I' command line option. For versions before this, to increase this size, you have to re-compile `memcached'. You can modify the value of the `POWER_BLOCK' within the `slabs.c' file within the source. In `memcached' 1.4.2 and higher, you can configure the maximum supported object size by using the `-I' command-line option. For example, to increase the maximum object size to 5MB: $ memcached -I 5m If an object is larger than the maximum object size, you must manually split it. `memcached' is very simple: you give it a key and some data, it tries to cache it in RAM. If you try to store more than the default maximum size, the value is just truncated for speed reasons. *16.6.5.3: ** Is it true `memcached' will be much more effective with db-read-intensive applications than with db-write-intensive applications? * Yes. `memcached' plays no role in database writes, it is a method of caching data already read from the database in RAM. *16.6.5.4: ** Is there any overhead in not using persistent connections? If persistent is always recommended, what are the downsides (for example, locking up)? * If you don't use persistent connections when communicating with `memcached', there will be a small increase in the latency of opening the connection each time. The effect is comparable to use nonpersistent connections with MySQL. In general, the chance of locking or other issues with persistent connections is minimal, because there is very little locking within `memcached'. If there is a problem, eventually your request will time out and return no result, so your application will need to load from MySQL again. *16.6.5.5: ** How is an event such as a crash of one of the `memcached' servers handled by the `memcached' client? * There is no automatic handling of this. If your client fails to get a response from a server, code a fallback mechanism to load the data from the MySQL database. The client APIs all provide the ability to add and remove `memcached' instances on the fly. If within your application you notice that `memcached' server is no longer responding, you can remove the server from the list of servers, and keys will automatically be redistributed to another `memcached' server in the list. If retaining the cache content on all your servers is important, make sure you use an API that supports a consistent hashing algorithm. For more information, see *Note ha-memcached-using-hashtypes::. *16.6.5.6: ** What is a recommended hardware configuration for a memcached server? * `memcached' has a very low processing overhead. All that is required is spare physical RAM capacity. A `memcached' server does not require a dedicated machine. If you have web, application, or database servers that have spare RAM capacity, then use them with `memcached'. To build and deploy a dedicated `memcached' server, use a relatively low-power CPU, lots of RAM, and one or more Gigabit Ethernet interfaces. *16.6.5.7: ** Is memcached more effective for video and audio as opposed to textual read/writes? * `memcached' works equally well for all kinds of data. To `memcached', any value you store is just a stream of data. Remember, though, that the maximum size of an object you can store in `memcached' is 1MB, but can be configured to be larger by using the `-I' option in `memcached' 1.4.2 and later, or by modifying the source in versions before 1.4.2. If you plan on using `memcached' with audio and video content, you will probably want to increase the maximum object size. Also remember that `memcached' is a solution for caching information for reading. It shouldn't be used for writes, except when updating the information in the cache. *16.6.5.8: ** Can `memcached' work with ASPX? * There are ports and interfaces for many languages and environments. ASPX relies on an underlying language such as C# or VisualBasic, and if you are using ASP.NET then there is a C# `memcached' library. For more information, see `https://sourceforge.net/projects/memcacheddotnet/'. *16.6.5.9: ** How expensive is it to establish a memcache connection? Should those connections be pooled? * Opening the connection is relatively inexpensive, because there is no security, authentication or other handshake taking place before you can start sending requests and getting results. Most APIs support a persistent connection to a `memcached' instance to reduce the latency. Connection pooling would depend on the API you are using, but if you are communicating directly over TCP/IP, then connection pooling would provide some small performance benefit. *16.6.5.10: ** How is the data handled when the `memcached' server is down? * The behavior is entirely application dependent. Most applications fall back to loading the data from the database (just as if they were updating the `memcached' information). If you are using multiple `memcached' servers, you might also remove a downed server from the list to prevent it from affecting performance. Otherwise, the client will still attempt to communicate with the `memcached' server that corresponds to the key you are trying to load. *16.6.5.11: ** How are auto-increment columns in the MySQL database coordinated across multiple instances of memcached? * They aren't. There is no relationship between MySQL and `memcached' unless your application (or, if you are using the MySQL UDFs for `memcached', your database definition) creates one. If you are storing information based on an auto-increment key into multiple instances of `memcached', the information is only stored on one of the `memcached' instances anyway. The client uses the key value to determine which `memcached' instance to store the information. It doesn't store the same information across all the instances, as that would be a waste of cache memory. *16.6.5.12: ** Is compression available? * Yes. Most of the client APIs support some sort of compression, and some even allow you to specify the threshold at which a value is deemed appropriate for compression during storage. *16.6.5.13: ** Can we implement different types of `memcached' as different nodes in the same server, so can there be deterministic and non-deterministic in the same server? * Yes. You can run multiple instances of `memcached' on a single server, and in your client configuration you choose the list of servers you want to use. *16.6.5.14: ** What are best practices for testing an implementation, to ensure that it improves performance, and to measure the impact of `memcached' configuration changes? And would you recommend keeping the configuration very simple to start? * The best way to test the performance is to start up a `memcached' instance. First, modify your application so that it stores the data just before the data is about to be used or displayed into `memcached'. Since the APIs handle the serialization of the data, it should just be a one-line modification to your code. Then, modify the start of the process that would normally load that information from MySQL with the code that requests the data from `memcached'. If the data cannot be loaded from `memcached', default to the MySQL process. All of the changes required will probably amount to just a few lines of code. To get the best benefit, make sure you cache entire objects (for example, all the components of a web page, blog post, discussion thread, and so on), rather than using `memcached' as a simple cache of individual rows of MySQL tables. Keeping the configuration simple at the start, or even over the long term, is easy with `memcached'. Once you have the basic structure up and running, often the only ongoing change is to add more servers into the list of servers used by your applications. You don't need to manage the `memcached' servers, and there is no complex configuration; just add more servers to the list and let the client API and the `memcached' servers make the decisions.  File: manual.info, Node: mysql-proxy, Prev: ha-memcached, Up: ha-overview 15.7 MySQL Proxy ================ * Menu: * mysql-proxy-platforms:: MySQL Proxy Supported Platforms * mysql-proxy-install:: Installing MySQL Proxy * mysql-proxy-configuration:: MySQL Proxy Command Options * mysql-proxy-scripting:: MySQL Proxy Scripting * mysql-proxy-using:: Using MySQL Proxy * mysql-proxy-faq:: MySQL Proxy FAQ The MySQL Proxy is an application that communicates over the network using the MySQL network protocol and provides communication between one or more MySQL servers and one or more MySQL clients. Because MySQL Proxy uses the MySQL network protocol, it can be used without modification with any MySQL-compatible client that uses the protocol. This includes the *Note `mysql': mysql. command-line client, any clients that uses the MySQL client libraries, and any connector that supports the MySQL network protocol. In the most basic configuration, MySQL Proxy simply interposes itself between the server and clients, passing queries from the clients to the MySQL Server and returning the responses from the MySQL Server to the appropriate client. In more advanced configurations, the MySQL Proxy can also monitor and alter the communication between the client and the server. Query interception enables you to add profiling, and interception of the exchanges is scriptable using the Lua scripting language. By intercepting the queries from the client, the proxy can insert additional queries into the list of queries sent to the server, and remove the additional results when they are returned by the server. Using this functionality you can return the results from the original query to the client while adding informational statements to each query, for example, to monitor their execution time or progress, and separately log the results. The proxy enables you to perform additional monitoring, filtering, or manipulation of queries without requiring you to make any modifications to the client and without the client even being aware that it is communicating with anything but a genuine MySQL server. This documentation covers MySQL Proxy 0.8.2. And MySQL Proxy contains third-party code. For license information on third-party code, see *Note licenses-third-party::. *Warning*: MySQL Proxy is currently an Alpha release and should not be used within production environments. *Important*: MySQL Proxy is compatible with MySQL 5.0 or later. Testing has not been performed with Version 4.1. Please provide feedback on your experiences using the MySQL Proxy Forum (http://forums.mysql.com/list.php?146). For release notes detailing the changes in each release of MySQL Proxy, see MySQL Proxy Release Notes (http://dev.mysql.com/doc/relnotes/mysql-proxy/en/).  File: manual.info, Node: mysql-proxy-platforms, Next: mysql-proxy-install, Prev: mysql-proxy, Up: mysql-proxy 15.7.1 MySQL Proxy Supported Platforms -------------------------------------- MySQL Proxy is currently available as a precompiled binary for the following platforms: * Linux (including Red Hat, Fedora, Debian, SuSE) and derivatives * Mac OS X * FreeBSD * IBM AIX * Sun Solaris * Microsoft Windows (including Microsoft Windows XP, Microsoft Windows Vista, Microsoft Windows Server 2003, Microsoft Windows Server 2008) *Note*: You must have the .NET Framework 1.1 or higher installed. Other Unix/Linux platforms not listed should be compatible by using the source package and building MySQL Proxy locally. System requirements for the MySQL Proxy application are the same as the main MySQL server. Currently MySQL Proxy is compatible only with MySQL 5.0.1 and later. MySQL Proxy is provided as a standalone, statically linked binary. You need not have MySQL or Lua installed.  File: manual.info, Node: mysql-proxy-install, Next: mysql-proxy-configuration, Prev: mysql-proxy-platforms, Up: mysql-proxy 15.7.2 Installing MySQL Proxy ----------------------------- * Menu: * mysql-proxy-install-binary:: Installing MySQL Proxy from a Binary Distribution * mysql-proxy-install-source:: Installing MySQL Proxy from a Source Distribution * mysql-proxy-install-cvs:: Installing MySQL Proxy from the Bazaar Repository * mysql-proxy-configuration-windows:: Setting Up MySQL Proxy as a Windows Service You have three choices for installing MySQL Proxy: * Precompiled binaries are available for a number of different platforms. See *Note mysql-proxy-install-binary::. * You can install from the source code to build on an environment not supported by the binary distributions. See *Note mysql-proxy-install-source::. * The latest version of the MySQL Proxy source code is available through a development repository is the best way to stay up to date with the latest fixes and revisions. See *Note mysql-proxy-install-cvs::.  File: manual.info, Node: mysql-proxy-install-binary, Next: mysql-proxy-install-source, Prev: mysql-proxy-install, Up: mysql-proxy-install 15.7.2.1 Installing MySQL Proxy from a Binary Distribution .......................................................... If you download a binary package, you must extract and copy the package contents to your desired installation directory. The package contains files required by MySQL Proxy, including additional Lua scripts and other components required for execution. To install, unpack the archive into the desired directory, then modify your `PATH' environment variable so that you can use the *Note `mysql-proxy': mysql-proxy. command directly: shell> cd /usr/local shell> tar zxf mysql-proxy-0.8.2-PLATFORM.tar.gz shell> PATH=$PATH:/usr/local/mysql-proxy-0.8.2-PLATFORM/sbin To update the path globally on a system, you might need administrator privileges to modify the appropriate `/etc/profile', `/etc/bashrc', or other system configuration file. On Windows, you can update the `PATH' environment variable using this procedure: 1. On the Windows desktop, right-click the `My Computer' icon, and select `Properties'. 2. Next 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. The Microsoft Visual C++ runtime libraries are a requirement for running MySQL Proxy as of version 0.8.2. Users that do not have these libraries must download and install the Microsoft Visual C++ 2008 Service Pack 1 Redistributable Package MFC Security Update. Use the following link to obtain the package: `http://www.microsoft.com/download/en/details.aspx?id=26368'  File: manual.info, Node: mysql-proxy-install-source, Next: mysql-proxy-install-cvs, Prev: mysql-proxy-install-binary, Up: mysql-proxy-install 15.7.2.2 Installing MySQL Proxy from a Source Distribution .......................................................... You can download a source package and compile the MySQL Proxy yourself. To build from source, you must have the following prerequisite components installed: * `libevent' 1.x or higher (1.3b or later is preferred). * `lua' 5.1.x or higher. * `glib2' 2.6.0 or higher. * `pkg-config'. * `libtool' 1.5 or higher. * MySQL 5.0.x or higher developer files. *Note*: On some operating systems, you might need to manually build the required components to get the latest version. If you have trouble compiling MySQL Proxy, consider using a binary distributions instead. After verifying that the prerequisite components are installed, configure and build MySQL Proxy: shell> tar zxf mysql-proxy-0.8.2.tar.gz shell> cd mysql-proxy-0.8.2 shell> ./configure shell> make To test the build, use the `check' target to `make': shell> make check The tests try to connect to `localhost' using the `root' user. To provide a password, set the `MYSQL_PASSWORD' environment variable: shell> MYSQL_PASSWORD=root_pwd make check You can install using the `install' target: shell> make install By default, *Note `mysql-proxy': mysql-proxy. is installed into `/usr/local/sbin/mysql-proxy'. The Lua example scripts are installed into `/usr/local/share'.  File: manual.info, Node: mysql-proxy-install-cvs, Next: mysql-proxy-configuration-windows, Prev: mysql-proxy-install-source, Up: mysql-proxy-install 15.7.2.3 Installing MySQL Proxy from the Bazaar Repository .......................................................... The MySQL Proxy source is available through a public Bazaar repository and is the quickest way to get the latest releases and fixes. A build from the Bazaar repository requires that the following prerequisite components be installed: * Bazaar 1.10.0 or later. * `libtool' 1.5 or higher. * `autoconf' 2.56 or higher. * `automake' 1.10 or higher. * `libevent' 1.x or higher (1.3b or later is preferred). * `lua' 5.1.x or higher. * `glib2' 2.4.0 or higher. * `pkg-config'. * MySQL 5.0.x or higher developer files. The *Note `mysql-proxy': mysql-proxy. source is hosted on Launchpad. To check out a local copy of the Bazaar repository, use `bzr': shell> bzr branch lp:mysql-proxy The preceding command downloads a complete version of the Bazaar repository for *Note `mysql-proxy': mysql-proxy. The main source files are located within the `trunk' subdirectory. The configuration scripts must be generated before you can configure and build *Note `mysql-proxy': mysql-proxy. The `autogen.sh' script generates the required configuration scripts for you: shell> sh ./autogen.sh The `autogen.sh' script creates the standard `configure' script, which you then use to configure and build with `make': shell> ./configure shell> make shell> make install To create a standalone source distribution, identical to the source distribution available for download, use this command: shell> make distcheck The preceding command creates the file `mysql-proxy-0.8.2.tar.gz' (with the corresponding current version) within the current directory.  File: manual.info, Node: mysql-proxy-configuration-windows, Prev: mysql-proxy-install-cvs, Up: mysql-proxy-install 15.7.2.4 Setting Up MySQL Proxy as a Windows Service .................................................... The MySQL distribution on Windows includes the `mysql-proxy-svc.exe' command that enables a MySQL Proxy instance to be managed by the Windows service control manager. You can control the service, including automatically starting and stopping it during boot, reboot and shutdown, without separately running the MySQL Proxy application. To set up a MySQL Proxy service, use the `sc' command to create a new service using the MySQL Proxy service command. Specify the MySQL Proxy options on the `sc' command line, and identify the service with a unique name. For example, to configure a new MySQL Proxy instance that will automatically start when your system boots, redirecting queries to the local MySQL server: C:\> sc create "Proxy" DisplayName= "MySQL Proxy" start= "auto" » binPath= "C:\Program Files\MySQL\mysql-proxy-0.8.2\bin\mysql-proxy-svc.exe » --proxy-backend-addresses=127.0.0.1:3306" *Note*: The space following the equal sign after each property is required; failure to include it results in an error. The preceding command creates a new service called `Proxy'. You can start and stop the service using the `net start|stop' command with the service name. The service is not automatically started after it is created. To start the service: C:\> net start proxy The MySQL Proxy service is starting. The MySQL Proxy service was started successfully. You can specify additional command-line options to the `sc' command. You can also set up multiple MySQL Proxy services on the same machine (providing they are configured to listen on different ports and/or IP addresses. You can delete a service that you have created: C:\> sc delete proxy For more information on creating services using `sc', see How to create a Windows service by using Sc.exe (http://support.microsoft.com/kb/251192).  File: manual.info, Node: mysql-proxy-configuration, Next: mysql-proxy-scripting, Prev: mysql-proxy-install, Up: mysql-proxy 15.7.3 MySQL Proxy Command Options ---------------------------------- To start MySQL Proxy, you can run it directly from the command line: shell> mysql-proxy For most situations, you specify at least the host name or address and the port number of the backend MySQL server to which the MySQL Proxy should pass queries. You can specify options to *Note `mysql-proxy': mysql-proxy. either on the command line, or by using a configuration file and the `--defaults-file' command-line option to specify the file location. If you use a configuration file, format it as follows: * Specify the options within a `[mysql-proxy]' configuration group. For example: [mysql-proxy] admin-address = HOST:PORT * Specify all configuration options in the form of a configuration name and the value to set. * For options that are a simple toggle on the command line (for example, `--proxy-skip-profiling'), use `true' or `false'. For example, the following is invalid: [mysql-proxy] proxy-skip-profiling But this is valid: [mysql-proxy] proxy-skip-profiling = true * Give the configuration file Unix permissions of `0660' (readable and writable by user and group, no access for others). Failure to adhere to any of these requirements causes *Note `mysql-proxy': mysql-proxy. to generate an error during startup. The following tables list the supported configuration file and command-line options. *`mysql-proxy' Help Options* Format Option File Description -help Show help options -help-admin Show admin module options -help-all Show all help options -help-proxy Show proxy module options *`mysql-proxy' Admin Options* Format Option File Description -admin-address=host:portadmin-address=host:portThe admin module listening host and port -admin-lua-script=file_nameadmin-lua-script=file_nameScript to execute by the admin module -admin-password=passwordadmin-password=passwordAuthentication password for admin module -admin-username=user_nameadmin-username=user_nameAuthentication user name for admin module -proxy-address=host:portproxy-address=host:portThe listening proxy server host and port *`mysql-proxy' Proxy Options* Format Option File Description Removed -no-proxy no-proxy Do not start the proxy module -proxy-backend-addresses=host:portproxy-backend-addresses=host:portThe MySQL server host and port -proxy-fix-bug-25371proxy-fix-bug-25371Enable the fix for Bug 0.8.1 #25371 for older libmysql versions -proxy-lua-script=file_nameproxy-lua-script=file_nameFilename for Lua script for proxy operations -proxy-pool-no-change-userproxy-pool-no-change-userDo not use the protocol CHANGE_USER command to reset the connection when coming from the connection pool -proxy-read-only-backend-addresses=host:portproxy-read-only-backend-addresses=host:portThe MySQL server host and port (read only) -proxy-skip-profilingproxy-skip-profilingDisable query profiling *`mysql-proxy' Applications Options* Format Option File Description -basedir=dir_namebasedir=dir_nameThe base directory prefix for paths in the configuration -daemon daemon Start in daemon mode -defaults-file=file_name The configuration file to use -event-threads=countevent-threads=countThe number of event-handling threads -keepalive keepalive Try to restart the proxy if a crash occurs -log-backtrace-on-crashlog-backtrace-on-crashTry to invoke the debugger and generate a backtrace on crash -log-file=file_namelog-file=file_nameThe file where error messages are logged -log-level=levellog-level=levelThe logging level -log-use-sysloglog-use-syslogLog errors to syslog -lua-cpath=dir_namelua-cpath=dir_nameSet the LUA_CPATH -lua-path=dir_namelua-path=dir_nameSet the LUA_PATH -max-open-files=countmax-open-files=countThe maximum number of open files to support -pid-file=file_namepid-file=file_nameFile in which to store the process ID -plugin-dir=dir_nameplugin-dir=dir_nameDirectory containing plugin files -plugins=plugin,...plugins=plugin,...List of plugins to load -user=user_nameuser=user_nameThe user to use when running mysql-proxy -version Show version information Except as noted in the following details, all of the options can be used within the configuration file by supplying the option and the corresponding value. For example: [mysql-proxy] log-file = /var/log/mysql-proxy.log log-level = message * `--help', `-h' Options for help *Command-Line `--help' Format* `-h' Show available help options. * `--help-admin' Options for help-admin *Command-Line `--help-admin' Format* Show options for the admin module. * `--help-all' Options for help-all *Command-Line `--help-all' Format* Show all help options. * `--help-proxy' Options for help-proxy *Command-Line `--help-proxy' Format* Show options for the proxy module. * `--admin-address=HOST:PORT' Options for admin-address *Command-Line `--admin-address=host:port' Format* *Option-File Format* `admin-address=host:port' *Permitted Values* *Type* `string' *Default* `:4041' The host name (or IP address) and port for the administration port. The default is `localhost:4041'. * `--admin-lua-script=FILE_NAME' Options for admin-lua-script *Command-Line `--admin-lua-script=file_name' Format* *Option-File Format* `admin-lua-script=file_name' *Permitted Values* *Type* `file name' *Default* `' The script to use for the proxy administration module. * `--admin-password=PASSWORD' Options for admin-password *Command-Line `--admin-password=password' Format* *Option-File Format* `admin-password=password' *Permitted Values* *Type* `string' *Default* `' The password to use to authenticate users wanting to connect to the MySQL Proxy administration module. This module uses the MySQL protocol to request a user name and password for connections. * `--admin-username=USER_NAME' Options for admin-username *Command-Line `--admin-username=user_name' Format* *Option-File Format* `admin-username=user_name' *Permitted Values* *Type* `string' *Default* `root' The user name to use to authenticate users wanting to connect to the MySQL Proxy administration module. This module uses the MySQL protocol to request a user name and password for connections. The default user name is `root'. * `--basedir=DIR_NAME' Options for basedir *Command-Line `--basedir=dir_name' Format* *Option-File Format* `basedir=dir_name' *Permitted Values* *Type* `directory name' The base directory to use as a prefix for all other file name configuration options. The base name should be an absolute (not relative) directory. If you specify a relative directory, *Note `mysql-proxy': mysql-proxy. generates an error during startup. * `--daemon' Options for daemon *Command-Line `--daemon' Format* *Option-File Format* `daemon' Starts the proxy in daemon mode. * `--defaults-file=FILE_NAME' Options for defaults-file *Command-Line `--defaults-file=file_name' Format* The file to read for configuration options. If not specified, MySQL Proxy takes options only from the command line. * `--event-threads=COUNT' Options for event-threads *Command-Line `--event-threads=count' Format* *Option-File Format* `event-threads=count' *Permitted Values* *Type* `numeric' *Default* `1' The number of event threads to reserve to handle incoming requests. * `--keepalive' Options for keepalive *Command-Line `--keepalive' Format* *Option-File Format* `keepalive' Create a process surrounding the main *Note `mysql-proxy': mysql-proxy. process that attempts to restart the main *Note `mysql-proxy': mysql-proxy. process in the event of a crash or other failure. *Note*: The `--keepalive' option is not available on Microsoft Windows. When running as a service, *Note `mysql-proxy': mysql-proxy. automatically restarts. * `--log-backtrace-on-crash' Options for log-backtrace-on-crash *Command-Line `--log-backtrace-on-crash' Format* *Option-File Format* `log-backtrace-on-crash' Log a backtrace to the error log and try to initialize the debugger in the event of a failure. * `--log-file=FILE_NAME' Options for log-file *Command-Line `--log-file=file_name' Format* *Option-File Format* `log-file=file_name' *Permitted Values* *Type* `file name' The file to use to record log information. If this option is not given, *Note `mysql-proxy': mysql-proxy. logs to the standard error output. * `--log-level=LEVEL' Options for log-level *Command-Line `--log-level=level' Format* *Option-File Format* `log-level=level' *Permitted Values* *Type* `enumeration' *Valid Values* `error' `warning' `info' `message' `debug' The log level to use when outputting error messages. Messages with that level (or lower) are output. For example, `message' level also outputs message with `info', `warning', and `error' levels. * `--log-use-syslog' Options for log-use-syslog *Command-Line `--log-use-syslog' Format* *Option-File Format* `log-use-syslog' Log errors to the syslog (Unix/Linux only). * `--lua-cpath=DIR_NAME' Options for lua-cpath *Command-Line `--lua-cpath=dir_name' Format* *Option-File Format* `lua-cpath=dir_name' *Permitted Values* *Type* `directory name' The `LUA_CPATH' to use when loading compiled modules or libraries for Lua scripts. * `--lua-path=DIR_NAME' Options for lua-path *Command-Line `--lua-path=dir_name' Format* *Option-File Format* `lua-path=dir_name' *Permitted Values* *Type* `directory name' The `LUA_CPATH' to use when loading modules for Lua. * `--max-open-files=COUNT' Options for max-open-files *Command-Line `--max-open-files=count' Format* *Option-File Format* `max-open-files=count' *Permitted Values* *Type* `numeric' The maximum number of open files and sockets supported by the *Note `mysql-proxy': mysql-proxy. process. Certain scripts might require a higher value. * `--no-proxy' Options for no-proxy *Command-Line `--no-proxy' Format* *Option-File Format* `no-proxy' Disable the proxy module. * `--plugin-dir=DIR_NAME' Options for plugin-dir *Command-Line `--plugin-dir=dir_name' Format* *Option-File Format* `plugin-dir=dir_name' *Permitted Values* *Type* `directory name' The directory to use when loading plugins for *Note `mysql-proxy': mysql-proxy. * `--plugins=PLUGIN' Options for plugins *Command-Line `--plugins=plugin,...' Format* *Option-File Format* `plugins=plugin,...' *Permitted Values* *Type* `string' Loads a plugin. When using this option on the command line, you can specify the option multiple times to specify multiple plugins. For example: shell> mysql-proxy --plugins=proxy --plugins=admin When using the option within the configuration file, you should separate multiple plugins by commas. The equivalent of the preceding example would be: ... plugins=proxy,admin * `--proxy-address=HOST:PORT', `-P HOST:PORT' Options for proxy-address *Command-Line `--proxy-address=host:port' Format* `-P host:port' *Option-File Format* `proxy-address=host:port' *Permitted Values* *Type* `string' *Default* `:4040' The listening host name (or IP address) and port of the proxy server. The default is `:4040' (all IPs on port 4040). * `--proxy-read-only-backend-addresses=HOST:PORT', `-r HOST:PORT' Options for proxy-read-only-backend-addresses *Command-Line `--proxy-read-only-backend-addresses=host:port' Format* `-r host:port' *Option-File Format* `proxy-read-only-backend-addresses=host:port' *Permitted Values* *Type* `string' The listening host name (or IP address) and port of the proxy server for read-only connections. The default is for this information not to be set. *Note*: Setting this value only configures the servers within the corresponding internal structure (see `proxy.global.backends'). You can determine the backend type by checking the `type' field for each connection. You should therefore only use this option in combination with a script designed to make use of the different backend types. When using this option on the command line, you can specify the option and the server multiple times to specify multiple backends. For example: shell> mysql-proxy --proxy-read-only-backend-addresses=192.168.0.1:3306 --proxy-read-only-backend-addresses=192.168.0.2:3306 When using the option within the configuration file, you should separate multiple servers by commas. The equivalent of the preceding example would be: ... proxy-read-only-backend-addresses = 192.168.0.1:3306,192.168.0.2:3306 * `--proxy-backend-addresses=HOST:PORT', `-b HOST:PORT' Options for proxy-backend-addresses *Command-Line `--proxy-backend-addresses=host:port' Format* `-b host:port' *Option-File Format* `proxy-backend-addresses=host:port' *Permitted Values* *Type* `string' *Default* `127.0.0.1:3306' The host name (or IP address) and port of the MySQL server to connect to. You can specify multiple backend servers by supplying multiple options. Clients are connected to each backend server in round-robin fashion. For example, if you specify two servers A and B, the first client connection will go to server A; the second client connection to server B and the third client connection to server A. When using this option on the command line, you can specify the option and the server multiple times to specify multiple backends. For example: shell> mysql-proxy --proxy-backend-addresses 192.168.0.1:3306 --proxy-backend-addresses 192.168.0.2:3306 When using the option within the configuration file, you should separate multiple servers by commas. The equivalent of the preceding example would be: ... proxy-backend-addresses = 192.168.0.1:3306,192.168.0.2:3306 * `--proxy-pool-no-change-user' Options for proxy-pool-no-change-user *Command-Line `--proxy-pool-no-change-user' Format* *Option-File Format* `proxy-pool-no-change-user' Disable use of the MySQL protocol `CHANGE_USER' command when reusing a connection from the pool of connections specified by the `proxy-backend-addresses' list. * `--proxy-skip-profiling' Options for proxy-skip-profiling *Command-Line `--proxy-skip-profiling' Format* *Option-File Format* `proxy-skip-profiling' Disable query profiling (statistics time tracking). The default is for tracking to be enabled. * `--proxy-fix-bug-25371' Options for proxy-fix-bug-25371 *Removed* 0.8.1 *Command-Line `--proxy-fix-bug-25371' Format* *Option-File Format* `proxy-fix-bug-25371' Enable a workaround for an issue when connecting to a MySQL server later than 5.1.12 when using a MySQL client library of any earlier version. This option was removed in *Note `mysql-proxy': mysql-proxy. 0.8.1. Now, *Note `mysql-proxy': mysql-proxy. returns an error message at the protocol level if it sees a `COM_CHANGE_USER' being sent to a server that has a version from 5.1.14 to 5.1.17. * `--proxy-lua-script=FILE_NAME', `-s FILE_NAME' Options for proxy-lua-script *Command-Line `--proxy-lua-script=file_name' Format* `-s file_name' *Option-File Format* `proxy-lua-script=file_name' *Permitted Values* *Type* `file name' The Lua script file to be loaded. Note that the script file is not physically loaded and parsed until a connection is made. Also note that the specified Lua script is reloaded for each connection; if the content of the Lua script changes while *Note `mysql-proxy': mysql-proxy. is running, the updated content is automatically used when a new connection is made. * `--pid-file=FILE_NAME' Options for pid-file *Command-Line `--pid-file=file_name' Format* *Option-File Format* `pid-file=file_name' *Permitted Values* *Type* `file name' The name of the file in which to store the process ID. * `--user=USER_NAME' Options for user *Command-Line `--user=user_name' Format* *Option-File Format* `user=user_name' *Permitted Values* *Type* `string' Run *Note `mysql-proxy': mysql-proxy. as the specified `user'. * `--version', `-V' Options for version *Command-Line `--version' Format* `-V' Show the version number. The most common usage is as a simple proxy service (that is, without additional scripting). For basic proxy operation, you must specify at least one `proxy-backend-addresses' option to specify the MySQL server to connect to by default: shell> mysql-proxy --proxy-backend-addresses=MySQL.example.com:3306 The default proxy port is `4040', so you can connect to your MySQL server through the proxy by specifying the host name and port details: shell> mysql --host=localhost --port=4040 If your server requires authentication information, this will be passed through natively without alteration by *Note `mysql-proxy': mysql-proxy, so you must also specify the required authentication information: shell> mysql --host=localhost --port=4040 \ --user=user_name --password=password You can also connect to a read-only port (which filters out *Note `UPDATE': update. and *Note `INSERT': insert. queries) by connecting to the read-only port. By default the host name is the default, and the port is `4042', but you can alter the host/port information by using the `--proxy-read-only-backend-addresses' command-line option. For more detailed information on how to use these command-line options, and *Note `mysql-proxy': mysql-proxy. in general in combination with Lua scripts, see *Note mysql-proxy-using::.  File: manual.info, Node: mysql-proxy-scripting, Next: mysql-proxy-using, Prev: mysql-proxy-configuration, Up: mysql-proxy 15.7.4 MySQL Proxy Scripting ---------------------------- * Menu: * mysql-proxy-scripting-injection:: Proxy Scripting Sequence During Query Injection * mysql-proxy-scripting-structures:: Internal Structures * mysql-proxy-scripting-connect-server:: Capturing a Connection with `connect_server()' * mysql-proxy-scripting-read-handshake:: Examining the Handshake with `read_handshake()' * mysql-proxy-scripting-read-auth:: Examining the Authentication Credentials with `read_auth()' * mysql-proxy-scripting-read-auth-result:: Accessing Authentication Information with `read_auth_result()' * mysql-proxy-scripting-read-query:: Manipulating Queries with `read_query()' * mysql-proxy-scripting-read-query-result:: Manipulating Results with `read_query_result()' You can control how MySQL Proxy manipulates and works with the queries and results that are passed on to the MySQL server through the use of the embedded Lua scripting language. You can find out more about the Lua programming language from the Lua Web site (http://www.lua.org). The following diagram shows an overview of the classes exposed by MySQL Proxy. MySQL Proxy architecture The primary interaction between MySQL Proxy and the server is provided by defining one or more functions through an Lua script. A number of functions are supported, according to different events and operations in the communication sequence between a client and one or more backend MySQL servers: * `connect_server()': This function is called each time a connection is made to MySQL Proxy from a client. You can use this function during load-balancing to intercept the original connection and decide which server the client should ultimately be attached to. If you do not define a special solution, a simple round-robin style distribution is used by default. * `read_handshake()': This function is called when the initial handshake information is returned by the server. You can capture the handshake information returned and provide additional checks before the authorization exchange takes place. * `read_auth()': This function is called when the authorization packet (user name, password, default database) are submitted by the client to the server for authentication. * `read_auth_result()': This function is called when the server returns an authorization packet to the client indicating whether the authorization succeeded. * `read_query()': This function is called each time a query is sent by the client to the server. You can use this to edit and manipulate the original query, including adding new queries before and after the original statement. You can also use this function to return information directly to the client, bypassing the server, which can be useful to filter unwanted queries or queries that exceed known limits. * `read_query_result()': This function is called each time a result is returned from the server, providing you have manually injected queries into the query queue. If you have not explicitly injected queries within the `read_query()' function, this function is not triggered. You can use this to edit the result set, or to remove or filter the result sets generated from additional queries you injected into the queue when using `read_query()'. The following table lists MySQL proxy and server communication functions, the supplied information, and the direction of information flow when the function is triggered. This table lists MySQL proxy and server communication functions, the supplied information, and the direction of information flow when the function is triggered. Function Supplied Information Direction `connect_server()' None Client to Server `read_handshake()' None Server to Client `read_auth()' None Client to Server `read_auth_result()' None Server to Client `read_query()' Query Client to Server `read_query_result()' Query result Server to Client By default, all functions return a result that indicates whether the data should be passed on to the client or server (depending on the direction of the information being transferred). This return value can be overridden by explicitly returning a constant indicating that a particular response should be sent. For example, it is possible to construct result set information by hand within `read_query()' and to return the result set directly to the client without ever sending the original query to the server. In addition to these functions, a number of built-in structures provide control over how MySQL Proxy forwards queries and returns the results by providing a simplified interface to elements such as the list of queries and the groups of result sets that are returned.  File: manual.info, Node: mysql-proxy-scripting-injection, Next: mysql-proxy-scripting-structures, Prev: mysql-proxy-scripting, Up: mysql-proxy-scripting 15.7.4.1 Proxy Scripting Sequence During Query Injection ........................................................ The following figure gives an example of how the proxy might be used when injecting queries into the query queue. Because the proxy sits between the client and MySQL server, what the proxy sends to the server, and the information that the proxy ultimately returns to the client, need not match or correlate. Once the client has connected to the proxy, the sequence shown in the following diagram occurs for each individual query sent by the client. MySQL Proxy architecture 1. When the client submits one query to the proxy, the `read_query()' function within the proxy is triggered. The function adds the query to the query queue. 2. Once manipulation by `read_query()' has completed, the queries are submitted, sequentially, to the MySQL server. 3. The MySQL server returns the results from each query, one result set for each query submitted. The `read_query_result()' function is triggered for each result set, and each invocation can decide which result set to return to the client For example, you can queue additional queries into the global query queue to be processed by the server. This can be used to add statistical information by adding queries before and after the original query, changing the original query: SELECT * FROM City; Into a sequence of queries: SELECT NOW(); SELECT * FROM City; SELECT NOW(); You can also modify the original statement; for example, to add *Note `EXPLAIN': explain. to each statement executed to get information on how the statement was processed, again altering our original SQL statement into a number of statements: SELECT * FROM City; EXPLAIN SELECT * FROM City; In both of these examples, the client would have received more result sets than expected. Regardless of how you manipulate the incoming query and the returned result, the number of queries returned by the proxy must match the number of original queries sent by the client. You could adjust the client to handle the multiple result sets sent by the proxy, but in most cases you will want the existence of the proxy to remain transparent. To ensure that the number of queries and result sets match, you can use the MySQL Proxy `read_query_result()' to extract the additional result set information and return only the result set the client originally requested back to the client. You can achieve this by giving each query that you add to the query queue a unique ID, then filter out queries that do not match the original query ID when processing them with `read_query_result()'.  File: manual.info, Node: mysql-proxy-scripting-structures, Next: mysql-proxy-scripting-connect-server, Prev: mysql-proxy-scripting-injection, Up: mysql-proxy-scripting 15.7.4.2 Internal Structures ............................ There are a number of internal structures within the scripting element of MySQL Proxy. The primary structure is `proxy' and this provides an interface to the many common structures used throughout the script, such as connection lists and configured backend servers. Other structures, such as the incoming packet from the client and result sets are only available within the context of one of the scriptable functions. The following table describes common attributes of the MySQL `proxy' scripting element. This table describes common attributes of the MySQL `proxy' scripting element. Attribute Description `connection' A structure containing the active client connections. For a list of attributes, see `proxy.connection'. `servers' A structure containing the list of configured backend servers. For a list of attributes, see `proxy.global.backends'. `queries' A structure containing the queue of queries that will be sent to the server during a single client query. For a list of attributes, see `proxy.queries'. `PROXY_VERSION' The version number of MySQL Proxy, encoded in hex. You can use this to check that the version number supports a particular option from within the Lua script. Note that the value is encoded as a hex value, so to check the version is at least 0.5.1 you compare against `0x00501'. *`proxy.connection'* The `proxy.connection' object is read only, and provides information about the current connection, and is split into a `client' and `server' tables. This enables you to examine information about both the incoming client connections to the proxy (`client'), and to the backend servers (`server'). The following table describes the client and server attributes of the `proxy.connection' object. This table describes the client and server attributes of the `proxy.connection' object. Attribute Description `client.default_db' Default database requested by the client `client.username' User name used to authenticate `client.scrambled_password'The scrambled version of the password used to authenticate `client.dst.name' The combined `address:port' of the Proxy port used by this client (should match the `--proxy-address' configuration parameter) `client.dst.address' The IP address of the of the Proxy port used by this client `client.dst.port' The port number of the of the Proxy port used by this client `client.src.name' The combined `address:port' of the client (originating) TCP/IP endpoint `client.src.address' The IP address of the client (originating) TCP/IP port `client.src.port' The port of the client (originating) TCP/IP endpoint `server.scramble_buffer'The scramble buffer used to scramble the password `server.mysqld_version'The MySQL version number of the server `server.thread_id' The ID of the thread handling the connection to the current server `server.dst.name' The combined `address:port' for the backend server for the current connection (i.e. the connection to the MySQL server) `server.dst.address' The address for the backend server `server.dst.port' The port for the backend server `server.src.name' The combined `address:port' for the TCP/IP endpoint used by the Proxy to connect to the backend server `server.src.address' The address of the endpoint for the proxy-side connection to the MySQL server `server.src.port' The port of the endpoint for the proxy-side connection to the MySQL server *`proxy.global.backends'* The `proxy.global.backends' table is partially writable and contains an array of all the configured backend servers and the server metadata (IP address, status, etc.). You can determine the array index of the current connection using `proxy.connection["backend_ndx"]' which is the index into this table of the backend server being used by the active connection. The attributes for each entry within the `proxy.global.backends' table are shown in the following table. This table describes the attributes for each entry within the `proxy.global.backends' table. Attribute Description `dst.name' The combined `address:port' of the backend server. `dst.address' The IP address of the backend server. `dst.port' The port of the backend server. `connected_clients' The number of clients currently connected. `state' The status of the backend server. See *Note mysql-proxy-scripting-structures-backend-states::. `type' The type of the backend server. You can use this to identify whether the backed was configured as a standard read/write backend, or a read-only backend. You can compare this value to the `proxy.BACKEND_TYPE_RW' and `proxy.BACKEND_TYPE_RO'. *`proxy.queries'* The `proxy.queries' object is a queue representing the list of queries to be sent to the server. The queue is not populated automatically, but if you do not explicitly populate the queue, queries are passed on to the backend server verbatim. Also, if you do not populate the query queue by hand, the `read_query_result()' function is not triggered. The following functions are supported for populating the `proxy.queries' object. This table describes the functions that are supported for populating the `proxy.queries' object. Function Description `append(id,packet,[options])'Appends a query to the end of the query queue. The `id' is an integer identifier that you can use to recognize the query results when they are returned by the server. The packet should be a properly formatted query packet. The optional `options' should be a table containing the options specific to this packet. `prepend(id,packet)' Prepends a query to the query queue. The `id' is an identifier that you can use to recognize the query results when they are returned by the server. The packet should be a properly formatted query packet. `reset()' Empties the query queue. `len()' Returns the number of query packets in the queue. For example, you could append a query packet to the `proxy.queries' queue by using the `append()': proxy.queries:append(1,packet) The optional third argument to `append()' should contain the options for the packet. To have access to the result set through the `read_query_result()' function, set the `resultset_is_needed' flag to `true': proxy.queries:append( 1, packet, { resultset_is_needed = true } ) If that flag is `false' (the default), proxy will: * Send the result set to the client as soon as it is received * Reduce memory usage (because the result set is not stored internally for processing) * Reduce latency of returning results to the client * Pass data from server to client unaltered The default mode is therefore quicker and useful if you only want to monitor the queries sent, and the basic statistics. To perform any kind of manipulation on the returned data, you must set the flag to `true', which will: * Store the result set so that it can be processed. * Enable modification of the result set before it is returned to the client. * Enable you to discard the result set instead of returning it to the client. *`proxy.response'* The `proxy.response' structure is used when you want to return your own MySQL response, instead of forwarding a packet that you have received a backend server. The structure holds the response type information, an optional error message, and the result set (rows/columns) to return. The following table describes the attributes of the `proxy.response' structure. This table describes the attributes of the `proxy.response' structure. Attribute Description `type' The type of the response. The type must be either `MYSQLD_PACKET_OK' or `MYSQLD_PACKET_ERR'. If the `MYSQLD_PACKET_ERR', you should set the value of the `mysql.response.errmsg' with a suitable error message. `errmsg' A string containing the error message that will be returned to the client. `resultset' A structure containing the result set information (columns and rows), identical to what would be returned when returning a results from a *Note `SELECT': select. query. When using `proxy.response' you either set `proxy.response.type' to `proxy.MYSQLD_PACKET_OK' and then build `resultset' to contain the results to return, or set `proxy.response.type' to `proxy.MYSQLD_PACKET_ERR' and set the `proxy.response.errmsg' to a string with the error message. To send the completed result set or error message, you should return the `proxy.PROXY_SEND_RESULT' to trigger the return of the packet information. An example of this can be seen in the `tutorial-resultset.lua' script within the MySQL Proxy package: if string.lower(command) == "show" and string.lower(option) == "querycounter" then --- -- proxy.PROXY_SEND_RESULT requires -- -- proxy.response.type to be either -- * proxy.MYSQLD_PACKET_OK or -- * proxy.MYSQLD_PACKET_ERR -- -- for proxy.MYSQLD_PACKET_OK you need a resultset -- * fields -- * rows -- -- for proxy.MYSQLD_PACKET_ERR -- * errmsg proxy.response.type = proxy.MYSQLD_PACKET_OK proxy.response.resultset = { fields = { { type = proxy.MYSQL_TYPE_LONG, name = "global_query_counter", }, { type = proxy.MYSQL_TYPE_LONG, name = "query_counter", }, }, rows = { { proxy.global.query_counter, query_counter } } } -- we have our result, send it back return proxy.PROXY_SEND_RESULT elseif string.lower(command) == "show" and string.lower(option) == "myerror" then proxy.response.type = proxy.MYSQLD_PACKET_ERR proxy.response.errmsg = "my first error" return proxy.PROXY_SEND_RESULT *`proxy.response.resultset'* The `proxy.response.resultset' structure should be populated with the rows and columns of data to return. The structure contains the information about the entire result set, with the individual elements of the data shown in the following table. The following table describes the attributes of the `proxy.response.resultset' structure. This table describes the attributes of the `proxy.response.resultset' structure. Attribute Description `fields' The definition of the columns being returned. This should be a dictionary structure with the `type' specifying the MySQL data type, and the `name' specifying the column name. Columns should be listed in the order of the column data that will be returned. `flags' A number of flags related to the result set. Valid flags include `auto_commit' (whether an automatic commit was triggered), `no_good_index_used' (the query executed without using an appropriate index), and `no_index_used' (the query executed without using any index). `rows' The actual row data. The information should be returned as an array of arrays. Each inner array should contain the column data, with the outer array making up the entire result set. `warning_count' The number of warnings for this result set. `affected_rows' The number of rows affected by the original statement. `insert_id' The last insert ID for an auto-incremented column in a table. `query_status' The status of the query operation. You can use the `MYSQLD_PACKET_OK' or `MYSQLD_PACKET_ERR' constants to populate this parameter. For an example showing how to use this structure, see `proxy.response'. *Proxy Return State Constants* The following constants are used internally by the proxy to specify the response to send to the client or server. All constants are exposed as values within the main `proxy' table. This table describes proxy return state constants, which are used internally by the proxy to specify the response to send to the client or server. Constant Description `PROXY_SEND_QUERY' Causes the proxy to send the current contents of the queries queue to the server. `PROXY_SEND_RESULT' Causes the proxy to send a result set back to the client. `PROXY_IGNORE_RESULT' Causes the proxy to drop the result set (nothing is returned to the client). As constants, these entities are available without qualification in the Lua scripts. For example, at the end of the `read_query_result()' you might return `PROXY_IGNORE_RESULT:' return proxy.PROXY_IGNORE_RESULT *Packet State Constants* The following states describe the status of a network packet. These items are entries within the main `proxy' table. This table describes packet state constants, which define the status of a network packet. Constant Description `MYSQLD_PACKET_OK' The packet is OK `MYSQLD_PACKET_ERR' The packet contains error information `MYSQLD_PACKET_RAW' The packet contains raw data *Backend State/Type Constants* The following constants are used either to define the status or type of the backend MySQL server to which the proxy is connected. These items are entries within the main `proxy' table. This table describes backend state/type constants, which are used to define the status or type of the backend MySQL server to which the proxy is connected. Constant Description `BACKEND_STATE_UNKNOWN'The current status is unknown `BACKEND_STATE_UP' The backend is known to be up (available) `BACKEND_STATE_DOWN' The backend is known to be down (unavailable) `BACKEND_TYPE_UNKNOWN' Backend type is unknown `BACKEND_TYPE_RW' Backend is available for read/write `BACKEND_TYPE_RO' Backend is available only for read-only use *Server Command Constants* The values described in the table below are used in the packets exchanged between the client and server to identify the information in the rest of the packet. These items are entries within the main `proxy' table. The packet type is defined as the first character in the sent packet. For example, when intercepting packets from the client to edit or monitor a query, you would check that the first byte of the packet was of type `proxy.COM_QUERY'. This table describes server command constants, which are used in the packets exchanged between the client and server to identify the information in the rest of the packet. Constant Description `COM_SLEEP' Sleep `COM_QUIT' Quit `COM_INIT_DB' Initialize database `COM_QUERY' Query `COM_FIELD_LIST' Field List `COM_CREATE_DB' Create database `COM_DROP_DB' Drop database `COM_REFRESH' Refresh `COM_SHUTDOWN' Shutdown `COM_STATISTICS' Statistics `COM_PROCESS_INFO' Process List `COM_CONNECT' Connect `COM_PROCESS_KILL' Kill `COM_DEBUG' Debug `COM_PING' Ping `COM_TIME' Time `COM_DELAYED_INSERT' Delayed insert `COM_CHANGE_USER' Change user `COM_BINLOG_DUMP' Binlog dump `COM_TABLE_DUMP' Table dump `COM_CONNECT_OUT' Connect out `COM_REGISTER_SLAVE' Register slave `COM_STMT_PREPARE' Prepare server-side statement `COM_STMT_EXECUTE' Execute server-side statement `COM_STMT_SEND_LONG_DATA'Long data `COM_STMT_CLOSE' Close server-side statement `COM_STMT_RESET' Reset statement `COM_SET_OPTION' Set option `COM_STMT_FETCH' Fetch statement `COM_DAEMON' Daemon (MySQL 5.1 only) `COM_ERROR' Error *MySQL Type Constants* These constants are used to identify the field types in the query result data returned to clients from the result of a query. These items are entries within the main `proxy' table. This table describes MySQL type constants and associated field types. The constants are used to identify the field types in the query result data returned to clients from the result of a query. Constant Field Type `MYSQL_TYPE_DECIMAL' Decimal `MYSQL_TYPE_NEWDECIMAL'Decimal (MySQL 5.0 or later) `MYSQL_TYPE_TINY' Tiny `MYSQL_TYPE_SHORT' Short `MYSQL_TYPE_LONG' Long `MYSQL_TYPE_FLOAT' Float `MYSQL_TYPE_DOUBLE' Double `MYSQL_TYPE_NULL' Null `MYSQL_TYPE_TIMESTAMP' Timestamp `MYSQL_TYPE_LONGLONG' Long long `MYSQL_TYPE_INT24' Integer `MYSQL_TYPE_DATE' Date `MYSQL_TYPE_TIME' Time `MYSQL_TYPE_DATETIME' Datetime `MYSQL_TYPE_YEAR' Year `MYSQL_TYPE_NEWDATE' Date (MySQL 5.0 or later) `MYSQL_TYPE_ENUM' Enumeration `MYSQL_TYPE_SET' Set `MYSQL_TYPE_TINY_BLOB' Tiny Blob `MYSQL_TYPE_MEDIUM_BLOB'Medium Blob `MYSQL_TYPE_LONG_BLOB' Long Blob `MYSQL_TYPE_BLOB' Blob `MYSQL_TYPE_VAR_STRING'Varstring `MYSQL_TYPE_STRING' String `MYSQL_TYPE_TINY' Tiny (compatible with `MYSQL_TYPE_CHAR)' `MYSQL_TYPE_ENUM' Enumeration (compatible with `MYSQL_TYPE_INTERVAL') `MYSQL_TYPE_GEOMETRY' Geometry `MYSQL_TYPE_BIT' Bit  File: manual.info, Node: mysql-proxy-scripting-connect-server, Next: mysql-proxy-scripting-read-handshake, Prev: mysql-proxy-scripting-structures, Up: mysql-proxy-scripting 15.7.4.3 Capturing a Connection with `connect_server()' ....................................................... When the proxy accepts a connection from a MySQL client, the `connect_server()' function is called. There are no arguments to the function, but you can use and if necessary manipulate the information in the `proxy.connection' table, which is unique to each client session. For example, if you have multiple backend servers, you can specify which server that connection should use by setting the value of `proxy.connection.backend_ndx' to a valid server number. The following code chooses between two servers based on whether the current time in minutes is odd or even: function connect_server() print("--> a client really wants to talk to a server") if (tonumber(os.date("%M")) % 2 == 0) then proxy.connection.backend_ndx = 2 print("Choosing backend 2") else proxy.connection.backend_ndx = 1 print("Choosing backend 1") end print("Using " .. proxy.global.backends[proxy.connection.backend_ndx].dst.name) end This example also displays the IP address/port combination by accessing the information from the internal `proxy.global.backends' table.  File: manual.info, Node: mysql-proxy-scripting-read-handshake, Next: mysql-proxy-scripting-read-auth, Prev: mysql-proxy-scripting-connect-server, Up: mysql-proxy-scripting 15.7.4.4 Examining the Handshake with `read_handshake()' ........................................................ Handshake information is sent by the server to the client after the initial connection (through `connect_server()') has been made. The handshake information contains details about the MySQL version, the ID of the thread that will handle the connection information, and the IP address of the client and server. This information is exposed through the `proxy.connection' structure. * `proxy.connection.server.mysqld_version': The version of the MySQL server. * `proxy.connection.server.thread_id': The thread ID. * `proxy.connection.server.scramble_buffer': The password scramble buffer. * `proxy.connection.server.dst.name': The IP address of the server. * `proxy.connection.client.src.name': The IP address of the client. For example, you can print out the handshake data and refuse clients by IP address with the following function: function read_handshake() print("<-- let's send him some information about us") print(" mysqld-version: " .. proxy.connection.server.mysqld_version) print(" thread-id : " .. proxy.connection.server.thread_id) print(" scramble-buf : " .. string.format("%q",proxy.connection.server.scramble_buffer)) print(" server-addr : " .. proxy.connection.server.dst.name) print(" client-addr : " .. proxy.connection.client.dst.name) if not proxy.connection.client.src.name:match("^127.0.0.1:") then proxy.response.type = proxy.MYSQLD_PACKET_ERR proxy.response.errmsg = "only local connects are allowed" print("we don't like this client"); return proxy.PROXY_SEND_RESULT end end Note that you must return an error packet to the client by using `proxy.PROXY_SEND_RESULT'.  File: manual.info, Node: mysql-proxy-scripting-read-auth, Next: mysql-proxy-scripting-read-auth-result, Prev: mysql-proxy-scripting-read-handshake, Up: mysql-proxy-scripting 15.7.4.5 Examining the Authentication Credentials with `read_auth()' .................................................................... The `read_auth()' function is triggered when an authentication handshake is initiated by the client. In the execution sequence, `read_auth()' occurs immediately after `read_handshake()', so the server selection has already been made, but the connection and authorization information has not yet been provided to the backend server. You can obtain the authentication information by examining the `proxy.connection.client' structure. For more information, see `proxy.connection'. For example, you can print the user name and password supplied during authorization using: function read_auth() print(" username : " .. proxy.connection.client.username) print(" password : " .. string.format("%q", proxy.connection.client.scrambled_password)) end You can interrupt the authentication process within this function and return an error packet back to the client by constructing a new packet and returning `proxy.PROXY_SEND_RESULT': proxy.response.type = proxy.MYSQLD_PACKET_ERR proxy.response.errmsg = "Logins are not allowed" return proxy.PROXY_SEND_RESULT  File: manual.info, Node: mysql-proxy-scripting-read-auth-result, Next: mysql-proxy-scripting-read-query, Prev: mysql-proxy-scripting-read-auth, Up: mysql-proxy-scripting 15.7.4.6 Accessing Authentication Information with `read_auth_result()' ....................................................................... The return packet from the server during authentication is captured by `read_auth_result()'. The only argument to this function is the authentication packet returned by the server. As the packet is a raw MySQL network protocol packet, you must access the first byte to identify the packet type and contents. The `MYSQLD_PACKET_ERR' and `MYSQLD_PACKET_OK' constants can be used to identify whether the authentication was successful: function read_auth_result(auth) local state = auth.packet:byte() if state == proxy.MYSQLD_PACKET_OK then print("<-- auth ok"); elseif state == proxy.MYSQLD_PACKET_ERR then print("<-- auth failed"); else print("<-- auth ... don't know: " .. string.format("%q", auth.packet)); end end If a long-password capable client tries to authenticate to a server that supports long passwords, but the user password provided is actually short, `read_auth_result()' will be called twice. The first time, `auth.packet:byte()' will equal 254, indicating that the client should try again using the old password protocol. The second time time `read_auth_result()/' is called, `auth.packet:byte()' will indicate whether the authentication actually succeeded.  File: manual.info, Node: mysql-proxy-scripting-read-query, Next: mysql-proxy-scripting-read-query-result, Prev: mysql-proxy-scripting-read-auth-result, Up: mysql-proxy-scripting 15.7.4.7 Manipulating Queries with `read_query()' ................................................. The `read_query()' function is called once for each query submitted by the client and accepts a single argument, the query packet that was provided. To access the content of the packet, you must parse the packet contents manually. For example, you can intercept a query packet and print out the contents using the following function definition: function read_query( packet ) if packet:byte() == proxy.COM_QUERY then print("we got a normal query: " .. packet:sub(2)) end end This example checks the first byte of the packet to determine the type. If the type is `COM_QUERY' (see *Note mysql-proxy-scripting-structures-command-constants::), we extract the query from the packet and print it. The structure of the packet type supplied is important. In the case of a `COM_QUERY' packet, the remaining contents of the packet are the text of the query string. In this example, no changes have been made to the query or the list of queries that will ultimately be sent to the MySQL server. To modify a query, or add new queries, you must populate the query queue (`proxy.queries'), then execute the queries that you have placed into the queue. If you do not modify the original query or the queue, the query received from the client is sent to the MySQL server verbatim. When adding queries to the queue, you should follow these guidelines: * The packets inserted into the queue must be valid query packets. For each packet, you must set the initial byte to the packet type. If you are appending a query, you can append the query statement to the rest of the packet. * Once you add a query to the queue, the queue is used as the source for queries sent to the server. If you add a query to the queue to add more information, you must also add the original query to the queue or it will not be executed. * Once the queue has been populated, you must set the return value from `read_query()' to indicate whether the query queue should be sent to the server. * When you add queries to the queue, you should add an ID. The ID you specify is returned with the result set so that you identify each query and corresponding result set. The ID has no other purpose than as an identifier for correlating the query and result set. When operating in a passive mode, during profiling for example, you identify the original query and the corresponding result set so that the results expected by the client can be returned correctly. * Unless your client is designed to cope with more result sets than queries, you should ensure that the number of queries from the client match the number of results sets returned to the client. Using the unique ID and removing result sets you inserted will help. Normally, the `read_query()' and `read_query_result()' function are used in conjunction with each other to inject additional queries and remove the additional result sets. However, `read_query_result()' is only called if you populate the query queue within `read_query()'.  File: manual.info, Node: mysql-proxy-scripting-read-query-result, Prev: mysql-proxy-scripting-read-query, Up: mysql-proxy-scripting 15.7.4.8 Manipulating Results with `read_query_result()' ........................................................ The `read_query_result()' is called for each result set returned by the server only if you have manually injected queries into the query queue. If you have not manipulated the query queue, this function is not called. The function supports a single argument, the result packet, which provides a number of properties: * `id': The ID of the result set, which corresponds to the ID that was set when the query packet was submitted to the server when using `append(id)' on the query queue. You must have set the `resultset_is_needed' flag to `append' to intercept the result set before it is returned to the client. See *Note mysql-proxy-scripting-structures-queries::. * `query': The text of the original query. * `query_time': The number of microseconds required to receive the first row of a result set since the query was sent to the server. * `response_time': The number of microseconds required to receive the last row of the result set since the query was sent to the server. * `resultset': The content of the result set data. By accessing the result information from the MySQL server, you can extract the results that match the queries that you injected, return different result sets (for example, from a modified query), and even create your own result sets. The following Lua script, for example, will output the query, followed by the query time and response time (that is, the time to execute the query and the time to return the data for the query) for each query sent to the server: function read_query( packet ) if packet:byte() == proxy.COM_QUERY then print("we got a normal query: " .. packet:sub(2)) proxy.queries:append(1, packet ) return proxy.PROXY_SEND_QUERY end end function read_query_result(inj) print("query-time: " .. (inj.query_time / 1000) .. "ms") print("response-time: " .. (inj.response_time / 1000) .. "ms") end You can access the rows of returned results from the result set by accessing the `rows' property of the `resultset' property of the result that is exposed through `read_query_result()'. For example, you can iterate over the results showing the first column from each row using this Lua fragment: for row in inj.resultset.rows do print("injected query returned: " .. row[1]) end Just like `read_query()', `read_query_result()' can return different values for each result according to the result returned. If you have injected additional queries into the query queue, for example, remove the results returned from those additional queries and return only the results from the query originally submitted by the client. The following example injects additional `SELECT NOW()' statements into the query queue, giving them a different ID to the ID of the original query. Within `read_query_result()', if the ID for the injected queries is identified, we display the result row, and return the `proxy.PROXY_IGNORE_RESULT' from the function so that the result is not returned to the client. If the result is from any other query, we print out the query time information for the query and return the default, which passes on the result set unchanged. We could also have explicitly returned `proxy.PROXY_IGNORE_RESULT' to the MySQL client. function read_query( packet ) if packet:byte() == proxy.COM_QUERY then proxy.queries:append(2, string.char(proxy.COM_QUERY) .. "SELECT NOW()", {resultset_is_needed = true} ) proxy.queries:append(1, packet, {resultset_is_needed = true}) proxy.queries:append(2, string.char(proxy.COM_QUERY) .. "SELECT NOW()", {resultset_is_needed = true} ) return proxy.PROXY_SEND_QUERY end end function read_query_result(inj) if inj.id == 2 then for row in inj.resultset.rows do print("injected query returned: " .. row[1]) end return proxy.PROXY_IGNORE_RESULT else print("query-time: " .. (inj.query_time / 1000) .. "ms") print("response-time: " .. (inj.response_time / 1000) .. "ms") end end For further examples, see *Note mysql-proxy-using::.  File: manual.info, Node: mysql-proxy-using, Next: mysql-proxy-faq, Prev: mysql-proxy-scripting, Up: mysql-proxy 15.7.5 Using MySQL Proxy ------------------------ * Menu: * mysql-proxy-using-admin:: Using the Administration Interface There are a number of different ways to use MySQL Proxy. At the most basic level, you can allow MySQL Proxy to pass queries from clients to a single server. To use MySQL Proxy in this mode, you just have to specify on the command line the backend server to which the proxy should connect: shell> mysql-proxy --proxy-backend-addresses=sakila:3306 If you specify multiple backend MySQL servers, the proxy connects each client to each server in a round-robin fashion. Suppose that you have two MySQL servers, A and B. The first client to connect is connected to server A, the second to server B, the third to server A. For example: shell> mysql-proxy \ --proxy-backend-addresses=narcissus:3306 \ --proxy-backend-addresses=nostromo:3306 When you specify multiple servers in this way, the proxy automatically identifies when a MySQL server has become unavailable and marks it accordingly. New connections are automatically attached to a server that is available, and a warning is reported to the standard output from *Note `mysql-proxy': mysql-proxy.: network-mysqld.c.367: connect(nostromo:3306) failed: Connection refused network-mysqld-proxy.c.2405: connecting to backend (nostromo:3306) failed, marking it as down for ... Lua scripts enable a finer level of control, both over the connections and their distribution and how queries and result sets are processed. When using an Lua script, you must specify the name of the script on the command line using the `--proxy-lua-script' option: shell> mysql-proxy --proxy-lua-script=mc.lua --proxy-backend-addresses=sakila:3306 When you specify a script, the script is not executed until a connection is made. This means that faults with the script are not raised until the script is executed. Script faults will not affect the distribution of queries to backend MySQL servers. *Note*: Because a script is not read until the connection is made, you can modify the contents of the Lua script file while the proxy is still running and the modified script is automatically used for the next connection. This ensures that MySQL Proxy remains available because it need not be restarted for the changes to take effect.  File: manual.info, Node: mysql-proxy-using-admin, Prev: mysql-proxy-using, Up: mysql-proxy-using 15.7.5.1 Using the Administration Interface ........................................... The *Note `mysql-proxy': mysql-proxy. administration interface can be accessed using any MySQL client using the standard protocols. You can use the administration interface to gain information about the proxy server as a whole - standard connections to the proxy are isolated to operate as if you were connected directly to the backend MySQL server. In *Note `mysql-proxy': mysql-proxy. 0.8.0 and earlier, a rudimentary interface was built into the proxy. In later versions this was replaced so that you must specify an administration script to be used when users connect to the administration interface. To use the administration interface, specify the user name and password required to connect to the admin service, using the `--admin-username' and `--admin-password' options. You must also specify the Lua script to be used as the interface to the administration service by using the `admin-lua-script' script option to point to a Lua script. For example, you can create a basic interface to the internal components of the *Note `mysql-proxy': mysql-proxy. system using the following script, written by Diego Medina: --[[ Copyright 2008, 2010, Oracle and/or its affiliates. All rights reserved. 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; version 2 of the License. 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 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA --]] -- admin.lua --[[ See http://www.chriscalender.com/?p=41 (Thanks to Chris Calender) See http://datacharmer.blogspot.com/2009/01/mysql-proxy-is-back.html (Thanks Giuseppe Maxia) --]] function set_error(errmsg) proxy.response = { type = proxy.MYSQLD_PACKET_ERR, errmsg = errmsg or "error" } end function read_query(packet) if packet:byte() ~= proxy.COM_QUERY then set_error("[admin] we only handle text-based queries (COM_QUERY)") return proxy.PROXY_SEND_RESULT end local query = packet:sub(2) local rows = { } local fields = { } -- try to match the string up to the first non-alphanum local f_s, f_e, command = string.find(packet, "^%s*(%w+)", 2) local option if f_e then -- if that match, take the next sub-string as option f_s, f_e, option = string.find(packet, "^%s+(%w+)", f_e + 1) end -- we got our commands, execute it if command == "show" and option == "querycounter" then --- -- proxy.PROXY_SEND_RESULT requires -- -- proxy.response.type to be either -- * proxy.MYSQLD_PACKET_OK or -- * proxy.MYSQLD_PACKET_ERR -- -- for proxy.MYSQLD_PACKET_OK you need a resultset -- * fields -- * rows -- -- for proxy.MYSQLD_PACKET_ERR -- * errmsg proxy.response.type = proxy.MYSQLD_PACKET_OK proxy.response.resultset = { fields = { { type = proxy.MYSQL_TYPE_LONG, name = "query_counter", }, }, rows = { { proxy.global.query_counter } } } -- we have our result, send it back return proxy.PROXY_SEND_RESULT elseif command == "show" and option == "myerror" then proxy.response.type = proxy.MYSQLD_PACKET_ERR proxy.response.errmsg = "my first error" return proxy.PROXY_SEND_RESULT elseif string.sub(packet, 2):lower() == 'select help' then return show_process_help() elseif string.sub(packet, 2):lower() == 'show proxy processlist' then return show_process_table() elseif query == "SELECT * FROM backends" then fields = { { name = "backend_ndx", type = proxy.MYSQL_TYPE_LONG }, { name = "address", type = proxy.MYSQL_TYPE_STRING }, { name = "state", type = proxy.MYSQL_TYPE_STRING }, { name = "type", type = proxy.MYSQL_TYPE_STRING }, } for i = 1, #proxy.global.backends do local b = proxy.global.backends[i] rows[#rows + 1] = { i, b.dst.name, b.state, b.type } end else set_error() return proxy.PROXY_SEND_RESULT end proxy.response = { type = proxy.MYSQLD_PACKET_OK, resultset = { fields = fields, rows = rows } } return proxy.PROXY_SEND_RESULT end function make_dataset (header, dataset) proxy.response.type = proxy.MYSQLD_PACKET_OK proxy.response.resultset = { fields = {}, rows = {} } for i,v in pairs (header) do table.insert(proxy.response.resultset.fields, {type = proxy.MYSQL_TYPE_STRING, name = v}) end for i,v in pairs (dataset) do table.insert(proxy.response.resultset.rows, v ) end return proxy.PROXY_SEND_RESULT end function show_process_table() local dataset = {} local header = { 'Id', 'IP Address', 'Time' } local rows = {} for t_i, t_v in pairs (proxy.global.process) do for s_i, s_v in pairs ( t_v ) do table.insert(rows, { t_i, s_v.ip, os.date('%c',s_v.ts) }) end end return make_dataset(header,rows) end function show_process_help() local dataset = {} local header = { 'command', 'description' } local rows = { {'SELECT HELP', 'This command.'}, {'SHOW PROXY PROCESSLIST', 'Show all connections and their true IP Address.'}, } return make_dataset(header,rows) end function dump_process_table() proxy.global.initialize_process_table() print('current contents of process table') for t_i, t_v in pairs (proxy.global.process) do print ('session id: ', t_i) for s_i, s_v in pairs ( t_v ) do print ( '\t', s_i, s_v.ip, s_v.ts ) end end print ('---END PROCESS TABLE---') end --[[ Help we use a simple string-match to split commands are word-boundaries mysql> show querycounter is split into command = "show" option = "querycounter" spaces are ignored, the case has to be as is. mysql> show myerror returns a error-packet --]] The script works in combination with a main proxy script, `reporter.lua': --[[ Copyright 2008, 2010, Oracle and/or its affiliates. All rights reserved. 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; version 2 of the License. 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 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA --]] -- reporter.lua --[[ See http://www.chriscalender.com/?p=41 (Thanks to Chris Calender) See http://datacharmer.blogspot.com/2009/01/mysql-proxy-is-back.html (Thanks Giuseppe Maxia) --]] proxy.global.query_counter = proxy.global.query_counter or 0 function proxy.global.initialize_process_table() if proxy.global.process == nil then proxy.global.process = {} end if proxy.global.process[proxy.connection.server.thread_id] == nil then proxy.global.process[proxy.connection.server.thread_id] = {} end end function read_auth_result( auth ) local state = auth.packet:byte() if state == proxy.MYSQLD_PACKET_OK then proxy.global.initialize_process_table() table.insert( proxy.global.process[proxy.connection.server.thread_id], { ip = proxy.connection.client.src.name, ts = os.time() } ) end end function disconnect_client() local connection_id = proxy.connection.server.thread_id if connection_id then -- client has disconnected, set this to nil proxy.global.process[connection_id] = nil end end --- -- read_query() can return a resultset -- -- You can use read_query() to return a result-set. -- -- @param packet the mysql-packet sent by the client -- -- @return -- * nothing to pass on the packet as is, -- * proxy.PROXY_SEND_QUERY to send the queries from the proxy.queries queue -- * proxy.PROXY_SEND_RESULT to send your own result-set -- function read_query( packet ) -- a new query came in in this connection -- using proxy.global.* to make it available to the admin plugin proxy.global.query_counter = proxy.global.query_counter + 1 end To use the script, save the first script to a file (`admin.lua' in the following example) and the other to `reporter.lua', then run *Note `mysql-proxy': mysql-proxy. specifying the admin script and a backend MySQL server: shell> mysql-proxy --admin-lua-script=admin.lua --admin-password=password \ » --admin-username=root --proxy-backend-addresses=127.0.0.1:3306 -proxy-lua-script=reporter.lua In a different window, connect to the MySQL server through the proxy: shell> mysql --user=root --password=password --port=4040 Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 1798669 Server version: 5.0.70-log Gentoo Linux mysql-5.0.70-r1 Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> In another different window, connect to the *Note `mysql-proxy': mysql-proxy. admin service using the specified user name and password: shell> mysql --user=root --password=password --port=4041 --host=localhost Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 1 Server version: 5.0.99-agent-admin Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> To monitor the status of the proxy, ask for a list of the current active processes: mysql> show proxy processlist; +---------+---------------------+--------------------------+ | Id | IP Address | Time | +---------+---------------------+--------------------------+ | 1798669 | 192.168.0.112:52592 | Wed Jan 20 16:58:00 2010 | +---------+---------------------+--------------------------+ 1 row in set (0.00 sec) mysql> For more information on the example, see MySQL Proxy Admin Example (http://fmpwizard.blogspot.com/2009/04/how-do-i-use-mysql-proxy-admin-plugin.html).  File: manual.info, Node: mysql-proxy-faq, Prev: mysql-proxy-using, Up: mysql-proxy 15.7.6 MySQL Proxy FAQ ---------------------- *Questions* * 16.7.6.1: In load balancing, how can I separate reads from writes? * 16.7.6.2: How do I use a socket with MySQL Proxy? Proxy change logs mention that support for UNIX sockets has been added. * 16.7.6.3: Can I use MySQL Proxy with all versions of MySQL? * 16.7.6.4: Can I run MySQL Proxy as a daemon? * 16.7.6.5: Do proxy applications run on a separate server? If not, what is the overhead incurred by Proxy on the DB server side? * 16.7.6.6: With load balancing, what happens to transactions? Are all queries sent to the same server? * 16.7.6.7: Is it possible to use MySQL Proxy with updating a Lucene index (or Solr) by making TCP calls to that server to update? * 16.7.6.8: Is the system context switch expensive, how much overhead does the Lua script add? * 16.7.6.9: How much latency does a proxy add to a connection? * 16.7.6.10: Do you have to make one large script and call it at proxy startup, can I change scripts without stopping and restarting (interrupting) the proxy? * 16.7.6.11: If MySQL Proxy has to live on same machine as MySQL, are there any tuning considerations to ensure both perform optimally? * 16.7.6.12: I currently use SQL Relay for efficient connection pooling with a number of Apache processes connecting to a MySQL server. Can MySQL Proxy currently accomplish this? My goal is to minimize connection latency while keeping temporary tables available. * 16.7.6.13: Are these reserved function names (for example, `error_result()') that get automatically called? * 16.7.6.14: As the script is re-read by MySQL Proxy, does it cache this or is it looking at the file system with each request? * 16.7.6.15: Given that there is a `connect_server()' function, can a Lua script link up with multiple servers? * 16.7.6.16: Is the MySQL Proxy an API? * 16.7.6.17: The global namespace variable example with quotas does not persist after a reboot, is that correct? * 16.7.6.18: Can MySQL Proxy handle SSL connections? * 16.7.6.19: Could MySQL Proxy be used to capture passwords? * 16.7.6.20: Are there tools for isolating problems? How can someone figure out whether a problem is in the client, the database, or the proxy? * 16.7.6.21: Is MySQL Proxy similar to what is provided by Java connection pools? * 16.7.6.22: So authentication with connection pooling has to be done at every connection? What is the authentication latency? * 16.7.6.23: If you have multiple databases on the same box, can you use proxy to connect to databases on default port 3306? * 16.7.6.24: What about caching the authorization information so clients connecting are given back-end connections that were established with identical authorization information, thus saving a few more round trips? * 16.7.6.25: Is there any big web site using MySQL Proxy? For what purpose and what transaction rate have they achieved? * 16.7.6.26: How does MySQL Proxy compare to DBSlayer? * 16.7.6.27: I tried using MySQL Proxy without any Lua script to try a round-robin type load balancing. In this case, if the first database in the list is down, MySQL Proxy would not connect the client to the second database in the list. * 16.7.6.28: Is it `safe' to use `LuaSocket' with proxy scripts? * 16.7.6.29: How different is MySQL Proxy from DBCP (Database connection pooling) for Apache in terms of connection pooling? * 16.7.6.30: MySQL Proxy can handle about 5000 connections, what is the limit on a MySQL server? * 16.7.6.31: Would the Java-only connection pooling solution work for multiple web servers? With this, I would assume that you can pool across many web servers at once? *Questions and Answers* *16.7.6.1: ** In load balancing, how can I separate reads from writes? * There is no automatic separation of queries that perform reads or writes to the different backend servers. However, you can specify to *Note `mysql-proxy': mysql-proxy. that one or more of the `backend' MySQL servers are read only. shell> mysql-proxy \ --proxy-backend-addresses=10.0.1.2:3306 \ --proxy-read-only-backend-addresses=10.0.1.3:3306 & *16.7.6.2: ** How do I use a socket with MySQL Proxy? Proxy change logs mention that support for UNIX sockets has been added. * Specify the path to the socket: --proxy-backend-addresses=/PATH/TO/SOCKET *16.7.6.3: ** Can I use MySQL Proxy with all versions of MySQL? * MySQL Proxy is designed to work with MySQL 5.0 or higher, and supports the MySQL network protocol for 5.0 and higher. *16.7.6.4: ** Can I run MySQL Proxy as a daemon? * Use the `--daemon' option. To keep track of the process ID, the daemon can be started with the `--pid-file=file' option to save the PID to a known file name. On version 0.5.x, the Proxy cannot be started natively as a daemon. *16.7.6.5: ** Do proxy applications run on a separate server? If not, what is the overhead incurred by Proxy on the DB server side? * You can run the proxy on the application server, on its own box, or on the DB-server depending on the use case. *16.7.6.6: ** With load balancing, what happens to transactions? Are all queries sent to the same server? * Without any special customization the whole connection is sent to the same server. That keeps the whole connection state intact. *16.7.6.7: ** Is it possible to use MySQL Proxy with updating a Lucene index (or Solr) by making TCP calls to that server to update? * Yes, but it is not advised for now. *16.7.6.8: ** Is the system context switch expensive, how much overhead does the Lua script add? * Lua is fast and the overhead should be small enough for most applications. The raw packet overhead is around 400 microseconds. *16.7.6.9: ** How much latency does a proxy add to a connection? * In the range of 400 microseconds per request. *16.7.6.10: ** Do you have to make one large script and call it at proxy startup, can I change scripts without stopping and restarting (interrupting) the proxy? * You can just change the script and the proxy will reload it when a client connects. *16.7.6.11: ** If MySQL Proxy has to live on same machine as MySQL, are there any tuning considerations to ensure both perform optimally? * MySQL Proxy can live on any box: application, database, or its own box. MySQL Proxy uses comparatively little CPU or RAM, with negligible additional requirements or overhead. *16.7.6.12: ** I currently use SQL Relay for efficient connection pooling with a number of Apache processes connecting to a MySQL server. Can MySQL Proxy currently accomplish this? My goal is to minimize connection latency while keeping temporary tables available. * Yes. *16.7.6.13: ** Are these reserved function names (for example, `error_result()') that get automatically called? * Only functions and values starting with `proxy.*' are provided by the proxy. All others are user provided. *16.7.6.14: ** As the script is re-read by MySQL Proxy, does it cache this or is it looking at the file system with each request? * It looks for the script at client-connect and reads it if it has changed, otherwise it uses the cached version. *16.7.6.15: ** Given that there is a `connect_server()' function, can a Lua script link up with multiple servers? * MySQL Proxy provides some tutorials in the source package; one is `examples/tutorial-keepalive.lua'. *16.7.6.16: ** Is the MySQL Proxy an API? * No, MySQL Proxy is an application that forwards packets from a client to a server using the MySQL network protocol. The MySQL Proxy provides a API allowing you to change its behavior. *16.7.6.17: ** The global namespace variable example with quotas does not persist after a reboot, is that correct? * Yes. If you restart the proxy, you lose the results, unless you save them in a file. *16.7.6.18: ** Can MySQL Proxy handle SSL connections? * No, being the man-in-the-middle, Proxy cannot handle encrypted sessions because it cannot share the SSL information. *16.7.6.19: ** Could MySQL Proxy be used to capture passwords? * The MySQL network protocol does not allow passwords to be sent in cleartext, all you could capture is the encrypted version. *16.7.6.20: ** Are there tools for isolating problems? How can someone figure out whether a problem is in the client, the database, or the proxy? * You can set a debug script in the proxy, which is an exceptionally good tool for this purpose. You can see very clearly which component is causing the problem, if you set the right breakpoints. *16.7.6.21: ** Is MySQL Proxy similar to what is provided by Java connection pools? * Yes and no. Java connection pools are specific to Java applications, MySQL Proxy works with any client API that talks the MySQL network protocol. Also, connection pools do not provide any functionality for intelligently examining the network packets and modifying the contents. *16.7.6.22: ** So authentication with connection pooling has to be done at every connection? What is the authentication latency? * You can skip the round-trip and use the connection as it was added to the pool. As long as the application cleans up the temporary tables it used. The overhead is (as always) around 400 microseconds. *16.7.6.23: ** If you have multiple databases on the same box, can you use proxy to connect to databases on default port 3306? * Yes, MySQL Proxy can listen on any port, provided that none of the MySQL servers are listening on the same port. *16.7.6.24: ** What about caching the authorization information so clients connecting are given back-end connections that were established with identical authorization information, thus saving a few more round trips? * There is an `--proxy-pool-no-change-user' option that provides this functionality. *16.7.6.25: ** Is there any big web site using MySQL Proxy? For what purpose and what transaction rate have they achieved? * Yes, gaiaonline (http://gaiaonline.com/). They have tested MySQL Proxy and seen it handle 2400 queries per second through the proxy. *16.7.6.26: ** How does MySQL Proxy compare to DBSlayer? * DBSlayer is a REST->MySQL tool, MySQL Proxy is transparent to your application. No change to the application is needed. *16.7.6.27: ** I tried using MySQL Proxy without any Lua script to try a round-robin type load balancing. In this case, if the first database in the list is down, MySQL Proxy would not connect the client to the second database in the list. * This issue is fixed in version 0.7.0. *16.7.6.28: ** Is it `safe' to use `LuaSocket' with proxy scripts? * You can, but it is not advised because it may block. *16.7.6.29: ** How different is MySQL Proxy from DBCP (Database connection pooling) for Apache in terms of connection pooling? * Connection Pooling is just one use case of the MySQL Proxy. You can use it for a lot more and it works in cases where you cannot use DBCP (for example, if you do not have Java). *16.7.6.30: ** MySQL Proxy can handle about 5000 connections, what is the limit on a MySQL server? * The server limit is given by the value of the `max_connections' system variable. The default value is version dependent. *16.7.6.31: ** Would the Java-only connection pooling solution work for multiple web servers? With this, I would assume that you can pool across many web servers at once? * Yes. But you can also start one proxy on each application server to get a similar behavior as you have it already.  File: manual.info, Node: replication, Next: mysql-cluster, Prev: ha-overview, Up: Top 16 Replication ************** * Menu: * replication-configuration:: Replication Configuration * replication-implementation:: Replication Implementation * replication-solutions:: Replication Solutions * replication-notes:: Replication Notes and Tips Replication enables data from one MySQL database server (the master) to be replicated to one or more MySQL database servers (the slaves). Replication is asynchronous - slaves need not be connected permanently to receive updates from the master. This means that updates can occur over long-distance connections and even over temporary or intermittent connections such as a dial-up service. Depending on the configuration, you can replicate all databases, selected databases, or even selected tables within a database. For answers to some questions often asked by those who are new to MySQL Replication, see *Note faqs-replication::. The target uses for 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 - if a branch office would like to work with a copy of your main data, you can use replication to create a local copy of the data for their use without requiring permanent access to the master. Replication in MySQL features support for 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 MySQL Cluster (see *Note mysql-cluster::). There are a number of solutions available for setting up replication between two servers, but 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 *Note 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 may also use a third variety, Mixed Based Replication (MBR). For more information on the different replication formats, see *Note replication-formats::. From MySQL 5.1.12 to MySQL 5.1.28, mixed format is the default. Beginning with MySQL 5.1.29, statement-based format is the default. Replication is controlled through a number of different options and variables. These control the core operation of the replication, timeouts, and the databases and filters that can be applied on databases and tables. For more information on the available options, see *Note replication-options::. You can use replication to solve a number of different problems, including problems with 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 *Note 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 problems and their resolution, including an FAQ, see *Note replication-notes::. 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 replication, see *Note replication-implementation::.  File: manual.info, Node: replication-configuration, Next: replication-implementation, Prev: replication, Up: replication 16.1 Replication Configuration ============================== * Menu: * replication-howto:: How to Set Up Replication * replication-formats:: Replication Formats * replication-options:: Replication and Binary Logging Options and Variables * replication-administration:: Common Replication Administration Tasks Replication between servers in MySQL is based on the binary logging mechanism. 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. The master is `dumb' in this scenario. Once binary logging has been enabled, all statements are recorded in the binary log. 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; you cannot configure the master to log only certain events. If you do not 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. 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 remembers the position within the binary log, it is possible for slaves to be disconnected, reconnect and then `catch up' by continuing from the recorded position. Both 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 *Note `CHANGE MASTER TO': change-master-to. statement on the slave. The details are stored within the slave's `master.info' file. This section describes 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, *Note replication-howto::, deals with the configuration of the systems and provides methods for copying data between the master and slaves. * 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 *Note replication-formats::. * Detailed information on the different configuration options and variables that apply to replication is provided in *Note 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 *Note replication-administration::.  File: manual.info, Node: replication-howto, Next: replication-formats, Prev: replication-configuration, Up: replication-configuration 16.1.1 How to Set Up Replication -------------------------------- * Menu: * replication-howto-masterbaseconfig:: Setting the Replication Master Configuration * replication-howto-slavebaseconfig:: Setting the Replication Slave Configuration * replication-howto-repuser:: Creating a User for Replication * replication-howto-masterstatus:: Obtaining the Replication Master Binary Log Coordinates * replication-howto-mysqldump:: Creating a Data Snapshot Using `mysqldump' * replication-howto-rawdata:: Creating a Data Snapshot Using Raw Data Files * replication-howto-newservers:: Setting Up Replication with New Master and Slaves * replication-howto-existingdata:: Setting Up Replication with Existing Data * replication-howto-additionalslaves:: Introducing Additional Slaves to an Existing Replication Environment * replication-howto-slaveinit:: Setting the Master Configuration on the Slave This section describes how to set up complete replication of a MySQL server. 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 replication setups: * On the master, you must enable binary logging and configure a unique server ID. This might require a server restart. See *Note 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 *Note replication-howto-slavebaseconfig::. * You may want to create a separate user that will be used by your slaves to authenticate with the master to read the binary log for replication. The step is optional. See *Note replication-howto-repuser::. * Before creating a data snapshot or starting the replication process, you should record the position of the binary log on the master. You will need this information when configuring the slave so that the slave knows where within the binary log to start executing events. See *Note replication-howto-masterstatus::. * If you already have data on your master and you want to use it to synchronize your slave, you will need to create a data snapshot. You can create a snapshot using *Note `mysqldump': mysqldump. (see *Note replication-howto-mysqldump::) or by copying the data files directly (see *Note replication-howto-rawdata::). * You will need to 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 *Note replication-howto-slaveinit::. Once you have configured the basic options, you will need to follow the instructions for your replication setup. A number of alternatives are provided: * If you are establishing a new MySQL master and one or more slaves, you need only set up the configuration, as you have no data to exchange. For guidance on setting up replication in this situation, see *Note replication-howto-newservers::. * If you are already running a MySQL server, and therefore already have data that must be transferred to your slaves before replication starts, have not previously configured the binary log and are able to shut down your MySQL server for a short period during the process, see *Note replication-howto-existingdata::. * If you are adding slaves to an existing replication environment, you can set up the slaves without affecting the master. See *Note replication-howto-additionalslaves::. If you will be administering MySQL replication servers, we suggest that you read this entire chapter through and try all statements mentioned in *Note replication-master-sql::, and *Note replication-slave-sql::. You should also familiarize yourself with the replication startup options described in *Note replication-options::. *Note*: Note that 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.  File: manual.info, Node: replication-howto-masterbaseconfig, Next: replication-howto-slavebaseconfig, Prev: replication-howto, Up: replication-howto 16.1.1.1 Setting the Replication Master Configuration ..................................................... On a replication master, you must enable binary logging and establish a unique server ID. If this has not already been done, this part of master setup requires a server restart. Binary logging _must_ be enabled on the master because the binary log is the basis for sending data changes from the master to its slaves. If binary logging is not enabled, replication will not be 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 entirely up to you. To configure the binary log and server ID options, you will need to shut down your MySQL server and edit the `my.cnf' or `my.ini' file. Add the following options to the configuration file within the `[mysqld]' section. 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*: If you omit `server-id' (or set it explicitly to its default value of 0), a master refuses connections from all slaves. *Note*: 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. *Note*: Ensure that the `skip-networking' option is not enabled on your replication master. If networking has been disabled, your slave will not able to communicate with the master and replication will fail.  File: manual.info, Node: replication-howto-slavebaseconfig, Next: replication-howto-repuser, Prev: replication-howto-masterbaseconfig, Up: replication-howto 16.1.1.2 Setting the Replication Slave Configuration .................................................... On a replication slave, you must establish 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, you should shut down your slave server and edit the configuration 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 each of the other slaves. Think of `server-id' values as something similar to IP addresses: These IDs uniquely identify each server instance in the community of replication partners. *Note*: If you omit `server-id' (or set it explicitly to its default value of 0), a slave refuses to connect to a master. You do not have to enable binary logging on the slave for replication to be enabled. However, if you enable binary logging on the slave, you can use the binary log for data backups and crash recovery on the slave, and also use the slave as part of a more complex replication topology (for example, where the slave acts as a master to other slaves).  File: manual.info, Node: replication-howto-repuser, Next: replication-howto-masterstatus, Prev: replication-howto-slavebaseconfig, Up: replication-howto 16.1.1.3 Creating a User for Replication ........................................ Each slave must connect 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. Any account can be used for this operation, providing it has been granted the `REPLICATION SLAVE' privilege. You may wish to create a different account for each slave, or connect to the master using the same account for each slave. You need not create an account specifically for replication. However, you should be aware that the user name and password will be stored in plain text within the `master.info' file (see *Note 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 *Note `CREATE USER': create-user. To grant this account the privileges required for replication, use the *Note `GRANT': 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 `mydomain.com' domain, issue these statements on the master: mysql> CREATE USER 'repl'@'%.mydomain.com' IDENTIFIED BY 'slavepass'; mysql> GRANT REPLICATION SLAVE ON *.* TO 'repl'@'%.mydomain.com'; See *Note account-management-sql::, for more information on statements for manipulation of user accounts.  File: manual.info, Node: replication-howto-masterstatus, Next: replication-howto-mysqldump, Prev: replication-howto-repuser, Up: replication-howto 16.1.1.4 Obtaining the Replication Master Binary Log Coordinates ................................................................ To configure replication on the slave you must determine the master's current coordinates within its binary log. You will need this information so that when the slave starts the replication process, it is able to start processing events from the binary log at the correct point. If you have existing data on your master that you want to synchronize on your slaves before starting the replication process, you must stop processing statements on the master, and 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 that you use will not match and you will end up with inconsistent or corrupted databases on the slaves. To obtain the master binary log coordinates, follow these steps: 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 *Note `FLUSH TABLES WITH READ LOCK': flush. statement: mysql> FLUSH TABLES WITH READ LOCK; For `InnoDB' tables, note that *Note `FLUSH TABLES WITH READ LOCK': flush. also blocks *Note `COMMIT': commit. operations. *Warning*: Leave the client from which you issued the *Note `FLUSH TABLES': flush. 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 *Note `SHOW MASTER STATUS': 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 `Position' 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. If the master has been running previously without binary logging enabled, the log file name and position values displayed by *Note `SHOW MASTER STATUS': show-master-status. or *Note `mysqldump --master-data': mysqldump. will be 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'. 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. 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 and then proceed to *Note replication-howto-mysqldump::, or *Note replication-howto-rawdata::. The idea here is to prevent any further changes so that the data copied to the slaves is in synchrony with the master. If you are setting up a brand new master and slave replication group, you can exit the first session to release the read lock.  File: manual.info, Node: replication-howto-mysqldump, Next: replication-howto-rawdata, Prev: replication-howto-masterstatus, Up: replication-howto 16.1.1.5 Creating a Data Snapshot Using `mysqldump' ................................................... One way to create a snapshot of the data in an existing master database is to use the *Note `mysqldump': mysqldump. tool. Once the data dump has been completed, you then import this data into the slave before starting the replication process. To obtain a snapshot of the data using *Note `mysqldump': mysqldump.: 1. If you have not already locked the tables on the server to prevent statements that update data from executing: Start a session on the server by connecting to it with the command-line client, and flush all tables and block write statements by executing the *Note `FLUSH TABLES WITH READ LOCK': flush. statement: mysql> FLUSH TABLES WITH READ LOCK; Remember to use *Note `SHOW MASTER STATUS': show-master-status. and record the binary log details for use when starting up the slave. The point in time of your snapshot and the binary log position must match. See *Note replication-howto-masterstatus::. 2. In another session, use *Note `mysqldump': mysqldump. to create a dump either of all the databases you want to replicate, or of selected individual databases. For example: shell> mysqldump --all-databases --lock-all-tables >dbdump.db An alternative to using a bare dump, is to use the `--master-data' option, which automatically appends the *Note `CHANGE MASTER TO': change-master-to. statement required on the slave to start the replication process. shell> mysqldump --all-databases --master-data >dbdump.db 3. In the client where you acquired the read lock, release the lock: mysql> UNLOCK TABLES; Alternatively, exit the first session to release the read lock. When choosing databases to include in the dump, remember to filter out databases on each slave that you do not want to include in the replication process. Either to copy the dump file to the slave, or use the file from the master when connecting remotely to the slave to import the data.  File: manual.info, Node: replication-howto-rawdata, Next: replication-howto-newservers, Prev: replication-howto-mysqldump, Up: replication-howto 16.1.1.6 Creating a Data Snapshot Using Raw Data Files ...................................................... If your database is large, copying the raw data files can be more efficient than using *Note `mysqldump': mysqldump. and importing the file on each slave. This technique skips the overhead of updating indexes as the `INSERT' statements are replayed. Using this method with tables in storage engines with complex caching or logging algorithms requires extra steps to produce a perfect `point in time' snapshot: the initial copy command might 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. 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. If you use *Note `InnoDB': innodb-storage-engine. 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 later used on the slave. MySQL Enterprise Backup is a commercial product that is included as part of a MySQL Enterprise subscription. See *Note mysql-enterprise-backup:: for detailed information. Otherwise, use the cold backup (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_cold_backup) technique to obtain a reliable binary snapshot of `InnoDB' tables: copy all data files after doing a slow shutdown (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_slow_shutdown) of the MySQL Server. To create a raw data snapshot of `MyISAM' tables, you can use standard 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', providing that your MySQL data files exist on a single file system. 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 (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_system_tablespace) files, unless you have the `innodb_file_per_table' option enabled.) You might want to specifically exclude the following files from your archive: * Files relating to the `mysql' database. * The `master.info' file. * The master's binary log files. * Any relay log files. 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 *Note 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 *Note 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.  File: manual.info, Node: replication-howto-newservers, Next: replication-howto-existingdata, Prev: replication-howto-rawdata, Up: replication-howto 16.1.1.7 Setting Up Replication with New Master and Slaves .......................................................... The easiest and most straightforward method for setting up replication is to use new master and slave servers. You can also use this method 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 will be automatically replicated to the slaves. To set up replication between a new master and slave: 1. Configure the MySQL master with the necessary configuration properties. See *Note replication-howto-masterbaseconfig::. 2. Start up the MySQL master. 3. Set up a user. See *Note replication-howto-repuser::. 4. Obtain the master status information. See *Note replication-howto-masterstatus::. 5. On the master, release the read lock: mysql> UNLOCK TABLES; 6. On the slave, edit the MySQL configuration. See *Note replication-howto-slavebaseconfig::. 7. Start up the MySQL slave. 8. Execute a *Note `CHANGE MASTER TO': change-master-to. statement to set the master replication server configuration. See *Note replication-howto-slaveinit::. Perform the slave setup steps on each slave. Because there is no data to load or exchange on a new server configuration you do not need to copy or import any information. If you are setting up a new replication environment using the data from a different existing database server, you will now need to run the dump file generated from that server on the new master. The database updates will automatically be propagated to the slaves: shell> mysql -h master < fulldb.dump  File: manual.info, Node: replication-howto-existingdata, Next: replication-howto-additionalslaves, Prev: replication-howto-newservers, Up: replication-howto 16.1.1.8 Setting Up Replication with Existing Data .................................................. When setting up replication with existing data, you will need to decide how best to get the data from the master to the slave before starting the replication service. The basic process for setting up replication with existing data is as follows: 1. With the MySQL master running, create a user to be used by the slave when connecting to the master during replication. See *Note replication-howto-repuser::. 2. If you have not already configured the `server-id' and enabled binary logging on the master server, you will need to shut it down to configure these options. See *Note replication-howto-masterbaseconfig::. If you have to shut down your master server, this is a good opportunity to take a snapshot of its databases. You should obtain the master status (see *Note replication-howto-masterstatus::) before taking down the master, updating the configuration and taking a snapshot. For information on how to create a snapshot using raw data files, see *Note replication-howto-rawdata::. 3. If your master server is already correctly configured, obtain its status (see *Note replication-howto-masterstatus::) and then use *Note `mysqldump': mysqldump. to take a snapshot (see *Note replication-howto-mysqldump::) or take a raw snapshot of the live server using the guide in *Note replication-howto-rawdata::. 4. Update the configuration of the slave. See *Note replication-howto-slavebaseconfig::. 5. The next step depends on how you created the snapshot of data on the master. If you used *Note `mysqldump': 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. 6. 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 *Note `CHANGE MASTER TO': change-master-to. statement required, see *Note replication-howto-slaveinit::. 7. Start the slave threads: mysql> START SLAVE; After you have performed this procedure, the slave should connect to the master and catch up on any updates that have occurred since the snapshot was taken. If you have forgotten to set the `server-id' option for the master, slaves cannot connect to it. If you have forgotten to set the `server-id' option 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. Once a slave is replicating, you can find in its data directory one file named `master.info' and another named `relay-log.info'. The slave uses these two files to keep track of how much of the master's binary log it has processed. Do _not_ remove or edit these files unless you know exactly what you are doing and fully understand the implications. Even in that case, it is preferred that you use the *Note `CHANGE MASTER TO': change-master-to. statement to change replication parameters. The slave will use the values specified in the statement to update the status files automatically. *Note*: The content of `master.info' overrides some of the server options specified on the command line or in `my.cnf'. See *Note 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.  File: manual.info, Node: replication-howto-additionalslaves, Next: replication-howto-slaveinit, Prev: replication-howto-existingdata, Up: replication-howto 16.1.1.9 Introducing Additional Slaves to an Existing Replication Environment ............................................................................. To add another slave to an existing replication configuration, you can do so 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 is due to the fact that, if the `--relay-log' option is not specified, 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 *Note 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 feasible, 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 *Note `STOP SLAVE': stop-slave. on the new slave. If you have already started the existing slave again, issue a *Note `STOP SLAVE': 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' files from the existing slave to the new slave if they were not located in the data directory. These files 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 will use the information in its `master.info' file to start the replication process.  File: manual.info, Node: replication-howto-slaveinit, Prev: replication-howto-additionalslaves, Up: replication-howto 16.1.1.10 Setting the Master Configuration on the Slave ....................................................... To set up the slave to communicate with the master for replication, you must tell the slave 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 *Note `CHANGE MASTER TO': 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 *Note change-master-to::.  File: manual.info, Node: replication-formats, Next: replication-options, Prev: replication-howto, Up: replication-configuration 16.1.2 Replication Formats -------------------------- * Menu: * replication-sbr-rbr:: Advantages and Disadvantages of Statement-Based and Row-Based Replication * replication-rbr-usage:: Usage of Row-Based Logging and Replication * replication-rbr-safe-unsafe:: Determination of Safe and Unsafe Statements in Binary Logging 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: * Replication capabilities in MySQL originally were based on propagation of SQL statements from master to slave. This is called _statement-based replication_ (often abbreviated as _SBR_), which corresponds to the standard statement-based binary logging format. In MySQL 5.1.4 and earlier, binary logging and replication used this format exclusively. * Row-based binary logging logs changes in individual table rows. When used with MySQL replication, this is known as _row-based replication_ (often abbreviated as _RBR_). In row-based replication, the master writes _events_ to the binary log that indicate how individual table rows are changed. * As of MySQL 5.1.8, the server can change the binary logging format in real time according to the type of event using _mixed-format logging_. When the mixed format is in effect, statement-based logging is used by default, but automatically switches to row-based logging in particular cases as described later. Replication using the mixed format is often referred to as _mixed-based replication_ or _mixed-format replication_. For more information, see *Note binary-log-mixed::. From MySQL 5.1.12 to MySQL 5.1.28, mixed format is the default. Beginning with MySQL 5.1.29, statement-based format is the default. MySQL Cluster The default binary logging format in all MySQL Cluster NDB 6.x and 7.x releases is `ROW'. MySQL Cluster Replication always uses row-based replication, and the *Note `NDBCLUSTER': mysql-cluster. storage engine is incompatible with statement-based replication. Using *Note `NDBCLUSTER': mysql-cluster. sets row-based logging format automatically. See *Note mysql-cluster-replication-general::, for more information. Starting with MySQL 5.1.20, 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 *Note 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 requires a restart of the server to take effect. For more information, see *Note set-statement::. There are conditions under which you cannot change the binary logging format at runtime or doing so causes replication to fail. See *Note binary-log-setting::. You must have the `SUPER' privilege to set the global `binlog_format' value. Starting with MySQL 5.1.29, you must have the `SUPER' privilege to set either the global or session `binlog_format' value. (Bug #39106) The statement-based and row-based replication formats have different issues and limitations. For a comparison of their relative advantages and disadvantages, see *Note 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 *Note stored-programs-logging::.  File: manual.info, Node: replication-sbr-rbr, Next: replication-rbr-usage, Prev: replication-formats, Up: replication-formats 16.1.2.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 that has existed in MySQL since 3.23. * 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 *Note `INSERT': insert. *Note `DELETE': delete, *Note `UPDATE': 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 DML (Data Modification Language) 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 *Note replication-features-invoked::, for more information. * *Note `DELETE': delete. and *Note `UPDATE': update. statements that use a `LIMIT' clause without an `ORDER BY' are nondeterministic. See *Note replication-features-limit::. * 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 *Note replication-features-functions::. Statements that cannot be replicated correctly using statement-based replication are logged with a warning like the one shown here: 090213 16:58:54 [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 *Note `SHOW WARNINGS': show-warnings. * *Note `INSERT ... SELECT': insert. requires a greater number of row-level locks than with row-based replication. * *Note `UPDATE': 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 *Note `InnoDB': innodb-storage-engine.: An *Note `INSERT': insert. statement that uses `AUTO_INCREMENT' blocks other nonconflicting *Note `INSERT': 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 *Note 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 *Note replication-features-differing-tables::, for more information. * Advantages of row-based replication: * * All changes can be replicated. This is the safest form of replication. For MySQL versions earlier than 5.1.14, DDL (Data Definition Language) statements such as *Note `CREATE TABLE': create-table. are replicated using statement-based replication, while DML statements, as well as *Note `GRANT': grant. and *Note `REVOKE': revoke. statements, are replicated using row-based replication. In MySQL 5.1.14 and later, the `mysql' database is not replicated. The `mysql' database is instead seen as a node-specific database. Row-based replication is not supported on tables in this database. Instead, statements that would normally update this information--such as *Note `GRANT': grant, *Note `REVOKE': 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 *Note `CREATE TABLE ... SELECT': create-table, 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. * The technology is the same as in most other database management systems; knowledge about other systems transfers to MySQL. * Fewer row locks are required on the master, which thus achieves higher concurrency, for the following types of statements: * *Note `INSERT ... SELECT': insert-select. * *Note `INSERT': insert. statements with `AUTO_INCREMENT' * *Note `UPDATE': update. or *Note `DELETE': 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 *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': delete. statement. * Disadvantages of row-based replication: * * RBR tends to generate more data that must be logged. To replicate a DML statement (such as an *Note `UPDATE': update. or *Note `DELETE': 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 taking and restoring from 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. * Deterministic UDFs that generate large *Note `BLOB': blob. values take longer to replicate with row-based replication than with statement-based replication. This is because the *Note `BLOB': blob. column value is logged, rather than the statement generating the data. * You cannot examine the logs to see what statements were executed, nor can you see on the slave what statements were received from the master and executed. However, beginning with MySQL 5.1.29, you can see what data was changed using *Note `mysqlbinlog': mysqlbinlog. with the options `--base64-output=DECODE-ROWS' and `--verbose'. * For tables using the *Note `MyISAM': myisam-storage-engine. storage engine, a stronger lock is required on the slave for *Note `INSERT': 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 *Note `MyISAM': myisam-storage-engine. tables are not supported when using row-based replication. * Formerly, when performing a bulk operation that includes nontransactional storage engines, changes were applied as the statement executed. With row-based logging, this meant that the binary log was written while the statement was running. On the master, this does not cause problems with concurrency, because tables are locked until the bulk operation terminates. On the slave server, tables were not locked while the slave applied changes, because the slave did not know that those changes were part of a bulk operation. In such cases, if you retrieved data from a table on the master (for example, using `SELECT * FROM table_name'), the server waited for the bulk operation to complete before executing the *Note `SELECT': select. statement, because the table was read-locked. On the slave, the server did not wait (because there was no lock). This meant that, until the bulk operation on the slave completed, different results were obtained for the same *Note `SELECT': select. query on the master and on the slave. This issue was resolved in MySQL 5.1.24. (Bug #29020)  File: manual.info, Node: replication-rbr-usage, Next: replication-rbr-safe-unsafe, Prev: replication-sbr-rbr, Up: replication-formats 16.1.2.2 Usage of Row-Based Logging and Replication ................................................... Major changes in the replication environment and in the behavior of applications can result from using row-based logging (RBL) or row-based replication (RBR) rather than statement-based logging or replication. This section describes a number of issues known to exist when using row-based logging or replication, and discusses some best practices for taking advantage of row-based logging and replication. For additional information, see *Note replication-formats::, and *Note replication-sbr-rbr::. For information about issues specific to MySQL Cluster Replication (which depends on row-based replication), see *Note mysql-cluster-replication-issues::. * RBL, RBR, and temporary tables As noted in *Note replication-features-temptables::, temporary tables are not replicated when using row-based format. When mixed format is in effect, `safe' statements involving temporary tables are logged using statement-based format. For more information, see *Note 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. * RBL and the `BLACKHOLE' storage engine Prior to MySQL 5.1.29, *Note `DELETE': delete. and *Note `UPDATE': update. statements for `BLACKHOLE' tables did not work with RBL. (Bug #38360) * 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 if the statement is an initial nontransactional statement (occurring in the transaction before any transactional statements). When executing on the slave, a table lock is taken on all tables involved, and then the rows are applied in batch mode. (This may or may not be effective, depending on the engine used for the slave's copy of the table.) * Latency and binary log size Because RBL writes changes for each row to the binary log, its size can increase quite rapidly. In a replication environment, 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 *Note `mysqlbinlog': mysqlbinlog. displays row-based events in the binary log using the `BINLOG' statement (see *Note binlog::). This statement displays an event in printable form, but as a base 64-encoded string the meaning of which is not evident. As of MySQL 5.1.28, when invoked with the `--base64-output=DECODE-ROWS' and `--verbose' options, *Note `mysqlbinlog': mysqlbinlog. formats the contents of the binary log in a manner that is easily human readable. This is helpful when binary log events were written in row-based format if you want to read or recover from a replication or database failure using the contents of the binary log. For more information, see *Note mysqlbinlog-row-events::. * Binary log execution errors and `slave_exec_mode' If `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 *Note server-system-variables::. *Note*: `slave_exec_mode=IDEMPOTENT' is generally useful only for circular replication or multi-master replication with MySQL Cluster, for which `IDEMPOTENT' is the default value (see *Note mysql-cluster-replication::). For other scenarios, setting `slave_exec_mode' to `STRICT' is normally sufficient; this is the default value for storage engines other than *Note `NDB': mysql-cluster. * Lack of binary log checksums RBL uses no checksums. This means that network, disk, and other errors may not be identified when processing the binary log. To ensure that data is transmitted without network corruption, you may want to consider using SSL, which adds another layer of checksumming, for replication connections. The *Note `CHANGE MASTER TO': change-master-to. statement has options to enable replication over SSL. See also *Note change-master-to::, for general information about setting up MySQL with SSL. * Filtering based on server ID not supported A common practice is to filter out changes on some slaves by using a `WHERE' clause that includes the relation `@@server_id <> ID_VALUE' clause with *Note `UPDATE': update. and *Note `DELETE': delete. statements, a simple example of such a clause being `WHERE @@server_id <> 1'. However, this does not work correctly with row-based logging. If you must use the `server_id' system variable for statement filtering, you must also use `--binlog_format=STATEMENT'. * 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. Because of this, 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 that your choice of replication format has on how they operate, see *Note 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 may reaches an inconsistent state. For this reason, it is recommended that you use a transactional storage engine such as *Note `InnoDB': innodb-storage-engine. for all tables replicated using the row-based format. Use of *Note `STOP SLAVE': stop-slave. (or *Note `STOP SLAVE SQL_THREAD': stop-slave. in MySQL 5.1.55 and later) prior to shutting down the slave MySQL server helps prevent such issues from occurring, and is always recommended regardless of the logging format or storage engines employed.  File: manual.info, Node: replication-rbr-safe-unsafe, Prev: replication-rbr-usage, Up: replication-formats 16.1.2.3 Determination of Safe and Unsafe Statements in Binary Logging ...................................................................... When speaking of the `safeness' of a statement in MySQL Replication, we are referring to whether a 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 *Note 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 safe (see *Note 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'). * No distinction is made in the treatment of safe and unsafe statements when the binary logging mode is `ROW'. * If the binary logging format is `MIXED', statements flagged as unsafe are logged using the row-based format; statements regarded as safe are logged using the statement-based format. * If the binary logging format is `STATEMENT', statements flagged as being unsafe generate a warning to this effect. (Safe statements are logged normally.) For more information, see *Note replication-formats::. Statements considered unsafe Statements having 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()', `RELEASE_LOCK()', `ROW_COUNT()', `SESSION_USER()', `SLEEP()', `SYSDATE()', `SYSTEM_USER()', `USER()', `UUID()', and `UUID_SHORT()'. In MySQL 5.1.43 and later, `RAND()' is also treated as unsafe. (Bug #11757207, Bug #49222) 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()', `LOCALTIME()', `LOCALTIMESTAMP()', `NOW()', `UNIX_TIMESTAMP()', `UTC_DATE()', `UTC_TIME()', `UTC_TIMESTAMP()', and `LAST_INSERT_ID()' For more information, see *Note replication-features-functions::. * References to system variables Most system variables are not replicated correctly using the statement-based format. For exceptions, see *Note binary-log-mixed::. See *Note replication-features-variables::. * UDFs Since we have no control over what a UDF does, we must assume that it is executing unsafe statements. * 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 *Note `INSERT': 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 *Note replication-features-auto-increment::. * `INSERT DELAYED' statement This statement is considered unsafe because the insertion of the rows may interleave with concurrently executing statements. * `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. Thus, such statements are considered unsafe. * Updates using `LIMIT' The order in which rows are retrieved is not specified. See *Note 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 *Note 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 Beginning with MySQL 5.1.50, *Note `LOAD DATA INFILE': load-data. is considered unsafe, it causes a warning in statement-based mode, and a switch to row-based format when using mixed-format logging. See *Note replication-features-load-data::. For additional information, see *Note replication-features::.  File: manual.info, Node: replication-options, Next: replication-administration, Prev: replication-formats, Up: replication-configuration 16.1.3 Replication and Binary Logging Options and Variables ----------------------------------------------------------- * Menu: * replication-options-table:: Replication and Binary Logging Option and Variable Reference * replication-options-master:: Replication Master Options and Variables * replication-options-slave:: Replication Slave Options and Variables * replication-options-binary-log:: Binary Log Options and Variables The next few sections contain information about *Note `mysqld': 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. A set of quick-reference tables providing basic information about these options and variables is also included (in the next section following this one). Of particular importance is the `--server-id' option. Options for server-id *Command-Line Format* `--server-id=#' *Option-File Format* `server-id' *System Variable Name* `server_id' *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 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 *Note replication-options-master::, and *Note 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. Example: `server-id=3'. If you omit `--server-id', the default ID is 0, in which case a master refuses connections from all slaves, and a slave refuses to connect to a master. For more information, see *Note replication-howto-slavebaseconfig::.  File: manual.info, Node: replication-options-table, Next: replication-options-master, Prev: replication-options, Up: replication-options 16.1.3.1 Replication and Binary Logging Option and Variable Reference ..................................................................... The following tables list basic information about the MySQL command-line options and system variables applicable to replication and the binary log. *Replication Options and Variables: MySQL 5.1* This table provides a summary of Replication options and variables in MySQL 5.1 Option or Variable Name Command System Scope Line Variable Option File Status Dynamic Variable `Com_change_master' N N Both N Y N `Com_show_master_status' N N Both N Y N `Com_show_new_master' N N Both N Y N `Com_show_slave_hosts' N N Both N Y N `Com_show_slave_status' N N Both N Y N `Com_slave_start' N N Both N Y N `Com_slave_stop' N N Both N Y N `Rpl_status' N N Global N Y N `slave_exec_mode' Y Y Global Y N Y `Slave_open_temp_tables' N N Global N Y N `Slave_retried_transactions' N N Global N Y N `Slave_running' N N Global N Y N `abort-slave-event-count' Y N Global Y N N `disconnect-slave-event-count' Y N Global Y N N `init_slave' Y Y Global Y N Y `log-slave-updates' Y Y Global Y N N `log_slave_updates' Y Y Global Y N N `master-connect-retry' Y N Global Y N N `master-host' Y N Global Y N N `master-info-file' Y N Global Y N N `master-password' Y N Global Y N N `master-port' Y N Global Y N N `master-retry-count' Y N Global Y N N `master-ssl' Y N Global Y N N `master-ssl-ca' Y N Global Y N N `master-ssl-capath' Y N Global Y N N `master-ssl-cert' Y N Global Y N N `master-ssl-cipher' Y N Global Y N N `master-ssl-key' Y N Global Y N N `master-user' Y N Global Y N N `relay-log' Y Y Global Y N N `relay-log-index' Y Y Global Y N N `relay-log-info-file' Y N Global Y N N `relay_log_info_file' Y Y Global Y N N `relay_log_index' Y Y Global Y N N `relay_log_purge' Y Y Global Y N Y `relay_log_space_limit' Y Y Global Y N N `replicate-do-db' Y N Global Y N N `replicate-do-table' Y N Global Y N N `replicate-ignore-db' Y N Global Y N N `replicate-ignore-table' Y N Global Y N N `replicate-rewrite-db' Y N Global Y N N `replicate-same-server-id' Y N Global Y N N `replicate-wild-do-table' Y N Global Y N N `replicate-wild-ignore-table' Y N Global Y N N `report-host' Y Y Global Y N N `report-password' Y Y Global Y N N `report-port' Y Y Global Y N N `report-user' Y Y Global Y N N `rpl_recovery_rank' N Y Global N N Y `show-slave-auth-info' Y N Global Y N N `skip-slave-start' Y N Global Y N N `slave_allow_batching' Y Y Global Y N Y `slave-load-tmpdir' Y Y Global Y N N `slave-skip-errors' Y Y Global Y N N `slave_compressed_protocol' Y Y Global Y N Y `slave-max-allowed-packet' Y N Global Y N N `slave_max_allowed_packet' N Y Global N N Y `slave_net_timeout' Y Y Global Y N Y `slave_transaction_retries' Y Y Global Y N Y `slave_type_conversions' Y Y Global Y N N `sql_slave_skip_counter' N Y Global N N Y `have_row_based_replication' N Y Global N N N *Note 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 *Note replication-options-slave::. *Binary Logging Options and Variables: MySQL 5.1* This table provides a summary of Binary Logging options and variables in MySQL 5.1 Option or Variable Name Command System Scope Line Variable Option File Status Dynamic Variable `Binlog_cache_disk_use' N N Global N Y N `Binlog_cache_use' N N Global N Y N `Com_show_binlog_events' N N Both N Y N `Com_show_binlogs' N N Both N Y N `binlog-do-db' Y N Global Y N N `binlog-ignore-db' Y N Global Y N N `binlog-row-event-max-size' Y N Global Y N N `binlog_cache_size' Y Y Global Y N Y `binlog_format' Y Y Both Y N Y `binlog_direct_non_transactional_updates' Y Y Both Y N Y `log-bin-use-v1-row-events' Y Y Global Y N N `log_bin_use_v1_row_events' Y Y Global Y N N `max-binlog-dump-events' Y N Global Y N N `max_binlog_cache_size' Y Y Global Y N Y `max_binlog_size' Y Y Global Y N Y `sporadic-binlog-dump-fail' Y N Global Y N N *Note 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 *Note binary-log::. For a table showing _all_ command-line options, system and status variables used with *Note `mysqld': mysqld, see *Note mysqld-option-tables::.  File: manual.info, Node: replication-options-master, Next: replication-options-slave, Prev: replication-options-table, Up: replication-options 16.1.3.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 *Note command line: command-line-options. or in an *Note option file: option-files. You can specify system variable values using *Note `SET': set-statement. 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 *Note replication-options-binary-log::. System variables used on replication masters The following system variables are used in controlling replication masters: * `auto_increment_increment' Options for auto_increment_increment *System Variable `auto_increment_increment' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `1' *Range* `1 .. 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 gives rise to an error, and the actual value of the variable remains unchanged. *Note*: `auto_increment_increment' is supported for use with *Note `NDB': mysql-cluster. tables beginning with MySQL 5.1.20, MySQL Cluster NDB 6.2.5, and MySQL Cluster NDB 6.3.2. Previously, setting it when using MySQL Cluster tables or MySQL Cluster Replication produced unpredictable results. 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) If the value of `auto_increment_offset' is greater than that of `auto_increment_increment', the value of `auto_increment_offset' is ignored. Should one or both of these variables be 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. In other words, the series is calculated like so: `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 greatest value present in the `col' column prior to the *Note `INSERT': 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 *Note `SELECT': select. query. It is not possible to confine the effects of these two variables to a single table, and thus they do not take the place of the sequences offered by some other database management systems; 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 *Note `mysqld': 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 *Note replication-features-auto-increment::. * `auto_increment_offset' Options for auto_increment_offset *System Variable `auto_increment_offset' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `1' *Range* `1 .. 65535' This variable has a default value of 1. For particulars, see the description for `auto_increment_increment'. *Note*: `auto_increment_offset' is supported for use with *Note `NDB': mysql-cluster. tables beginning with MySQL 5.1.20, MySQL Cluster NDB 6.2.5, and MySQL Cluster NDB 6.3.2. Previously, setting it when using MySQL Cluster tables or MySQL Cluster Replication produced unpredictable results.  File: manual.info, Node: replication-options-slave, Next: replication-options-binary-log, Prev: replication-options-master, Up: replication-options 16.1.3.3 Replication Slave Options and Variables ................................................ This section describes the server options and system variables that apply to slave replication servers. You can specify the options either on the *Note command line: command-line-options. or in an *Note option file: option-files. Many of the options can be set while the server is running by using the *Note `CHANGE MASTER TO': change-master-to. statement. You can specify system variable values using *Note `SET': set-statement. 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 *Important*: Certain `--master-XXX' options are handled in a special way to ensure that the active replication configuration is not inadvertently altered or affected: * `--master-host' * `--master-user' * `--master-password' * `--master-port' * `--master-connect-retry' * `--master-ssl' * `--master-ssl-ca' * `--master-ssl-capath' * `--master-ssl-cert' * `--master-ssl-cipher' * `--master-ssl-key' Before MySQL 5.1.17, these options are silently ignored if given unless there is no `master.info' file. If that file exists, the MySQL server has already previously been configured for replication, so the information in the file is used instead. Because the server gives an existing `master.info' file precedence over the startup options just described, you might elect not to use startup options for these values at all, and instead to specify the replication parameters associated with them by using the *Note `CHANGE MASTER TO': change-master-to. statement. See *Note change-master-to::. Beginning with MySQL 5.1.17, these options are deprecated and have no effect when *Note `mysqld': mysqld. is started. If they are used, an appropriate warning is written to the error log. Instead, you _must_ use *Note `CHANGE MASTER TO': change-master-to. to set the values corresponding to the deprecated options. These options are removed in MySQL 5.5. The `master.info' file format in MySQL 5.1 includes as its first line the number of lines in the file. (See *Note slave-logs::.) If you upgrade an older server (before MySQL 4.1.1) to a newer version, the new server upgrades the `master.info' file to the new format automatically when it starts. However, if you downgrade a newer server to an older version, you should remove the first line manually before starting the older server for the first time. If no `master.info' file exists when the slave server starts, it uses the values for those options that are specified in option files or on the command line. This occurs when you start the server as a replication slave for the very first time, when you use *Note `CHANGE MASTER TO': change-master-to, or when you have run *Note `RESET SLAVE': reset-slave. and then have shut down and restarted the slave. Because the server uses `master.info' file contents and ignores any startup options that correspond to the values listed in the file, if you start the slave server with different values of the startup options that correspond to values in the file, the different values have no effect. To use different values, the preferred method is to use the *Note `CHANGE MASTER TO': change-master-to. statement to reset the values while the slave is running. Alternatively, you can stop the server, remove the `master.info' file, and restart the server with different option values. Suppose that you specify this option in your `my.cnf' file to configure a pre-5.1.17 slave server: [mysqld] master-host=SOME_HOST The first time you start the server as a replication slave, it reads and uses that option from the `my.cnf' file. The server then records the value in the `master.info' file. The next time you start the server, it reads the master host value from the `master.info' file only and ignores the value in the option file. If you modify the `my.cnf' file to specify a different master host value of SOME_OTHER_HOST, the change has no effect. Instead, use *Note `CHANGE MASTER TO': change-master-to. to change the value. This example shows a more extensive use of startup options to configure a pre-5.1.17 slave server: [mysqld] server-id=2 master-host=db-master.mycompany.com master-port=3306 master-user=pertinax master-password=freitag master-connect-retry=60 report-host=db-slave.mycompany.com As of 5.1.17, the `master-XXX' options are ignored and result in warnings in the error log. Startup options for replication slaves The following list describes startup options for controlling replication slave servers. Many of these options can be set while the server is running by using the *Note `CHANGE MASTER TO': 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. * `--abort-slave-event-count' Options for abort-slave-event-count *Command-Line `--abort-slave-event-count=#' Format* *Option-File Format* `abort-slave-event-count' *Permitted Values* *Type* `numeric' *Default* `0' *Min 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 *Note `SHOW SLAVE STATUS': 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. This option is used internally by the MySQL test suite for replication testing and debugging. It is not intended for use in a production setting. * `--disconnect-slave-event-count' Options for disconnect-slave-event-count *Command-Line `--disconnect-slave-event-count=#' Format* *Option-File Format* `disconnect-slave-event-count' *Permitted Values* *Type* `numeric' *Default* `0' This option is used internally by the MySQL test suite for replication testing and debugging. * `--log-slave-updates' Options for log-slave-updates *Command-Line `--log-slave-updates' Format* *Option-File Format* `log-slave-updates' *System Variable `log_slave_updates' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `FALSE' Normally, a slave does not log to its own binary log any updates that are received from a master server. This option tells the slave to log 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. When using MySQL Cluster Replication prior to MySQL Cluster NDB 6.2.16 and MySQL Cluster NDB 6.3.13, records for `empty' epochs--that is, epochs in which no changes to *Note `NDBCLUSTER': mysql-cluster. data or tables took place--were inserted into the `ndb_apply_status' and `ndb_binlog_index' tables on the slave even when `--log-slave-updates' was disabled (Bug #37472). Beginning with MySQL Cluster NDB 6.3.33, MySQL Cluster NDB 7.0.14, and MySQL Cluster NDB 7.1.3, it is possible to re-enable the older behavior by using the `--ndb-log-empty-epochs' option. *Note*: The `--ndb-log-empty-epochs' option was first implemented in MySQL Cluster NDB 6.3.21 and MySQL Cluster NDB 6.4.1, but did not work correctly before the versions cited previously. * `--log-slow-slave-statements' Options for log-slow-slave-statements *Introduced* 5.1.21 *Command-Line `--log-slow-slave-statements' Format* *Option-File Format* `log-slow-slave-statements' *Permitted Values* *Type* `boolean' *Default* `OFF' When the slow query log is enabled, this option enables logging for queries that have taken more than `long_query_time' seconds to execute on the slave. This option was added in MySQL 5.1.21. * `--log-warnings[=LEVEL]' Options for log-warnings *Command-Line `--log-warnings[=#]' Format* `-W [#]' *Option-File Format* `log-warnings[=#]' *System Variable `log_warnings' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `1' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `1' *Range* `0 .. 18446744073709547520' This option causes a server to print 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/connection failure, and informs you as to how each slave thread started. This option is enabled (1) by default; to disable it, use `--log-warnings=0'. Aborted connections are not logged to the error log unless the value is greater than 1. Note that the effects of this option are not limited to replication. It produces warnings across a spectrum of server activities. * `--master-connect-retry=SECONDS' Options for master-connect-retry *Deprecated* 5.1.17 *Command-Line `--master-connect-retry=#' Format* *Option-File Format* `master-connect-retry' *Permitted Values* *Type* `numeric' *Default* `60' The number of seconds that the slave thread sleeps before trying to reconnect to the master in case the master goes down or the connection is lost. The value in the `master.info' file takes precedence if it can be read. If not set, the default is 60. Connection retries are not invoked until the slave times out reading data from the master according to the value of `--slave-net-timeout'. The number of reconnection attempts is limited by the `--master-retry-count' option. This option is deprecated as of MySQL 5.1.17 and is removed in MySQL 5.5. * `slave-max-allowed-packet=BYTES' Options for slave-max-allowed-packet *Introduced* 5.1.64 *Command-Line `--slave-max-allowed-packet=#' Format* *Option-File Format* `slave-max-allowed-packet' *Permitted Values* *Type* `numeric' *Default* `1073741824' *Range* `1024 .. 1073741824' In MySQL 5.1.64 and later, 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. * `--master-host=HOST_NAME' Options for master-host *Deprecated* 5.1.17 *Command-Line `--master-host=name' Format* *Option-File Format* `master-host' *Permitted Values* *Type* `string' The host name or IP address of the master replication server. The value in `master.info' takes precedence if it can be read. If no master host is specified, the slave thread does not start. This option is deprecated as of MySQL 5.1.17 and is removed in MySQL 5.5. * `--master-info-file=FILE_NAME' Options for master-info-file *Command-Line `--master-info-file=file_name' Format* *Option-File Format* `master-info-file' *Permitted Values* *Type* `file name' *Default* `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 *Note slave-logs-status::. * `--master-password=PASSWORD' Options for master-password *Deprecated* 5.1.17 *Command-Line `--master-password=name' Format* *Option-File Format* `master-password' *Permitted Values* *Type* `string' The password of the account that the slave thread uses for authentication when it connects to the master. The value in the `master.info' file takes precedence if it can be read. If not set, an empty password is assumed. This option is deprecated as of MySQL 5.1.17 and is removed in MySQL 5.5. * `--master-port=PORT_NUMBER' Options for master-port *Deprecated* 5.1.17 *Command-Line `--master-port=#' Format* *Option-File Format* `master-port' *Permitted Values* *Type* `numeric' *Default* `3306' The TCP/IP port number that the master is listening on. The value in the `master.info' file takes precedence if it can be read. If not set, the compiled-in setting is assumed (normally 3306). This option is deprecated as of MySQL 5.1.17 and is removed in MySQL 5.5. * `--master-retry-count=COUNT' Options for master-retry-count *Command-Line `--master-retry-count=#' Format* *Option-File Format* `master-retry-count' *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `86400' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `86400' *Range* `0 .. 18446744073709551615' 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 (or the `MASTER_CONNECT_RETRY' option of the *Note `CHANGE MASTER TO': change-master-to. statement) and 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. * `--master-ssl', `--master-ssl-ca=FILE_NAME', `--master-ssl-capath=DIRECTORY_NAME', `--master-ssl-cert=FILE_NAME', `--master-ssl-cipher=CIPHER_LIST', `--master-ssl-key=FILE_NAME' These options are used for setting up a secure replication connection to the master server using SSL. Their meanings are the same as the corresponding `--ssl', `--ssl-ca', `--ssl-capath', `--ssl-cert', `--ssl-cipher', `--ssl-key' options that are described in *Note ssl-options::. The values in the `master.info' file take precedence if they can be read. These options are deprecated as of MySQL 5.1.17 and are removed in MySQL 5.5. * `--master-user=USER_NAME' Options for master-user *Deprecated* 5.1.17 *Command-Line `--master-user=name' Format* *Option-File Format* `master-user' *Permitted Values* *Type* `string' *Default* `test' The user name of the account that the slave thread uses for authentication when it connects to the master. This account must have the `REPLICATION SLAVE' privilege. The value in the `master.info' file takes precedence if it can be read. If the master user name is not set, the name `test' is assumed. This option is deprecated as of MySQL 5.1.17 and is removed in MySQL 5.5. * `--max-relay-log-size=SIZE' Options for max_relay_log_size *Command-Line `--max_relay_log_size=#' Format* *Option-File Format* `max_relay_log_size' *System Variable `max_relay_log_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 1073741824' The size at which the server rotates relay log files automatically. For more information, see *Note slave-logs::. The default size is 1GB. * `--read-only' Options for read_only *Command-Line `--read-only' Format* *Option-File Format* `read_only' *System Variable `read_only' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `false' Cause the slave to permit no updates except from slave threads or from users having the `SUPER' privilege. On a slave server, this can be useful to ensure that the slave accepts updates only from its master server and not from clients. This variable does not apply to `TEMPORARY' tables. * `--relay-log=FILE_NAME' Options for relay-log *Command-Line `--relay-log=name' Format* *Option-File Format* `relay-log' *System Variable `relay_log' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The basename for the relay log. The default basename is `HOST_NAME-relay-bin'. The server writes the file in the data directory unless the basename 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 basename. Due to the manner in which MySQL parses server options, if you specify this option, you must supply a value; _the default basename 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 *Note program-options::. If you specify this option, the value specified is also used as the basename for the relay log index file. You can override this behavior by specifying a different relay log index file basename using the `--relay-log-index' option. 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. * `--relay-log-index=FILE_NAME' Options for relay-log-index *Command-Line `--relay-log-index=name' Format* *Option-File Format* `relay-log-index' *System Variable `relay_log_index' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *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 slave server. Due to the manner in which MySQL parses server options, if you specify this option, you must supply a value; _the default basename 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 *Note program-options::. If you specify this option, the value specified is also used as the basename for the relay logs. You can override this behavior by specifying a different relay log file basename using the `--relay-log' option. * `--relay-log-info-file=FILE_NAME' Options for relay-log-info-file *Command-Line `--relay-log-info-file=file_name' Format* *Option-File Format* `relay-log-info-file' *Permitted Values* *Type* `file name' *Default* `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 *Note slave-logs-status::. * `--relay-log-purge={0|1}' Options for relay_log_purge *Command-Line `--relay_log_purge' Format* *Option-File Format* `relay_log_purge' *System Variable `relay_log_purge' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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'. * `--relay-log-space-limit=SIZE' Options for relay_log_space_limit *Command-Line `--relay_log_space_limit=#' Format* *Option-File Format* `relay_log_space_limit' *System Variable `relay_log_space_limit' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `0' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `0' *Range* `0 .. 18446744073709547520' 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' Options for replicate-do-db *Command-Line `--replicate-do-db=name' Format* *Option-File Format* `replicate-do-db' *Permitted Values* *Type* `string' The effects of this option depend on whether statement-based or row-based replication is in use. Statement-based replication Tell the slave SQL thread to restrict replication to statements where the default database (that is, the one selected by *Note `USE': 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 *Note `UPDATE': 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 *Note `DELETE': delete. statements or multiple-table *Note `UPDATE': 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 *Note `UPDATE': update. statement; this occurs whether or not the *Note `USE': 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 *Note `UPDATE': 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 *Note `UPDATE': 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 *Note `UPDATE': update. statement would have no effect on the slave when using statement-based replication. However, if you are using row-based replication, the *Note `UPDATE': 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 *Note 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'. Beginning with MySQL 5.1.35, this option has no effect on *Note `BEGIN': commit, *Note `COMMIT': commit, or *Note `ROLLBACK': commit. statements. (Bug #43263) * `--replicate-ignore-db=DB_NAME' Options for replicate-ignore-db *Command-Line `--replicate-ignore-db=name' Format* *Option-File Format* `replicate-ignore-db' *Permitted Values* *Type* `string' As with `--replicate-do-db', the effects of this option depend on whether statement-based or row-based replication is in use. Statement-based replication Tells the slave SQL thread not to replicate any statement where the default database (that is, the one selected by *Note `USE': 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 *Note `UPDATE': update. statement _is_ replicated in such a case because `--replicate-ignore-db' applies only to the default database (determined by the *Note `USE': 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 *Note `UPDATE': 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 *Note replication-rules::. If you need cross-database updates to work, use `--replicate-wild-ignore-table=DB_NAME.%' instead. See *Note 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'. Beginning with MySQL 5.1.35, this option has no effect on *Note `BEGIN': commit, *Note `COMMIT': commit, or *Note `ROLLBACK': commit. statements. (Bug #43263) * `--replicate-do-table=DB_NAME.TBL_NAME' Options for replicate-do-table *Command-Line `--replicate-do-table=name' Format* *Option-File Format* `replicate-do-table' *Permitted Values* *Type* `string' Tells the slave SQL thread to restrict replication to the specified 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 *Note replication-rules::. 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' Options for replicate-ignore-table *Command-Line `--replicate-ignore-table=name' Format* *Option-File Format* `replicate-ignore-table' *Permitted Values* *Type* `string' Tells 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 *Note replication-rules::. 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' Options for replicate-rewrite-db *Command-Line `--replicate-rewrite-db=old_name->new_name' Format* *Option-File Format* `replicate-rewrite-db' *Permitted Values* *Type* `string' Tells the slave to translate the default database (that is, the one selected by *Note `USE': use.) to TO_NAME if it was FROM_NAME on the master. Only statements involving tables are affected (not statements such as *Note `CREATE DATABASE': create-database, *Note `DROP DATABASE': drop-database, and *Note `ALTER DATABASE': 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. 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 *Note `DELETE FROM a.t': delete. 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' Options for replicate-same-server-id *Command-Line `--replicate-same-server-id' Format* *Option-File Format* `replicate-same-server-id' *Permitted Values* *Type* `boolean' *Default* `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' Options for replicate-wild-do-table *Command-Line `--replicate-wild-do-table=name' Format* *Option-File Format* `replicate-wild-do-table' *Permitted Values* *Type* `string' Tells 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 *Note replication-rules::. 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 (*Note `CREATE DATABASE': create-database, *Note `DROP DATABASE': drop-database, and *Note `ALTER DATABASE': 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' Options for replicate-wild-ignore-table *Command-Line `--replicate-wild-ignore-table=name' Format* *Option-File Format* `replicate-wild-ignore-table' *Permitted Values* *Type* `string' Tells the slave thread not to replicate a statement where 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 *Note replication-rules::. 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' Options for report-host *Command-Line `--report-host=host_name' Format* *Option-File Format* `report-host' *System Variable `report_host' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *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 *Note `SHOW SLAVE HOSTS': 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 that 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' Options for report-password *Command-Line `--report-password=name' Format* *Option-File Format* `report-password' *System Variable `report_password' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' An arbitrary account password to be reported by the slave to the master during slave registration. This value appears in the output of *Note `SHOW SLAVE HOSTS': show-slave-hosts. on the master server if the `--show-slave-auth-info' option is given. 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' Options for report-port *Command-Line `--report-port=#' Format* *Option-File Format* `report-port' *System Variable `report_port' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `3306' *Range* `0 .. 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. * `--report-user=USER_NAME' Options for report-user *Command-Line `--report-user=name' Format* *Option-File Format* `report-user' *System Variable `report_user' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *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 *Note `SHOW SLAVE HOSTS': show-slave-hosts. on the master server if the `--show-slave-auth-info' option is given. 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. * `--show-slave-auth-info' Options for show-slave-auth-info *Command-Line `--show-slave-auth-info' Format* *Option-File Format* `show-slave-auth-info' *Permitted Values* *Type* `boolean' *Default* `FALSE' Display slave user names and passwords in the output of *Note `SHOW SLAVE HOSTS': show-slave-hosts. on the master server for slaves started with the `--report-user' and `--report-password' options. * `--skip-slave-start' Options for skip-slave-start *Command-Line `--skip-slave-start' Format* *Option-File Format* `skip-slave-start' *Permitted Values* *Type* `boolean' *Default* `FALSE' Tells the slave server not to start the slave threads when the server starts. To start the threads later, use a *Note `START SLAVE': start-slave. statement. * `--slave_compressed_protocol={0|1}' Options for slave_compressed_protocol *Command-Line `--slave_compressed_protocol' Format* *Option-File Format* `slave_compressed_protocol' *System Variable `slave_compressed_protocol' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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=FILE_NAME' Options for slave-load-tmpdir *Command-Line `--slave-load-tmpdir=path' Format* *Option-File Format* `slave-load-tmpdir' *System Variable `slave_load_tmpdir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' *Default* `/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 *Note `LOAD DATA INFILE': load-data. 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 *Note `LOAD DATA INFILE': load-data. must survive machine restarts. The directory also should not be one that is cleared by the operating system during the system startup process. * `--slave-net-timeout=SECONDS' Options for slave-net-timeout *Command-Line `--slave-net-timeout=#' Format* *Option-File Format* `slave-net-timeout' *System Variable `slave_net_timeout' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `3600' *Min 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 *Note `CHANGE MASTER TO': change-master-to. statement or `--master-connect-retry' option, and the number of reconnection attempts is limited by the `--master-retry-count' option. The default is 3600 seconds (one hour). * `--slave-skip-errors=[ERR_CODE1,ERR_CODE2,...|all]' _(MySQL Cluster NDB 7.0.33 and later; MySQL Cluster NDB 7.1.22 and later:)_ `--slave-skip-errors=[ERR_CODE1,ERR_CODE2,...|all|ddl_exist_errors]' Options for slave-skip-errors *Command-Line `--slave-skip-errors=name' Format* *Option-File Format* `slave-skip-errors' *System Variable `slave_skip_errors' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values (>= 5.1.61-ndb-7.0.33,5.1.61-ndb-7.1.22)* *Type* `string' *Default* `OFF' *Valid Values* `[list of error codes]' `all' `ddl_exist_errors' Normally, replication stops when an error occurs on the slave. This gives you the opportunity to resolve the inconsistency in the data manually. This option tells 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. *Note*: Prior to MySQL 5.1.35, this option had no effect with row-based logging. (Bug #39393) For error codes, you should use the numbers provided by the error message in your slave error log and in the output of *Note `SHOW SLAVE STATUS': show-slave-status. *Note error-handling::, lists server error codes. 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_. For MySQL Cluster Replication in MySQL Cluster NDB 7.0 beginning with version 7.0.33 and MySQL Cluster NDB 7.1 beginning with version 7.1.22, an additional shorthand value `ddl_exist_errors' is supported for use with the enhanced failover mechanism which is implemented in that and later version of MySQL Cluster NDB 7.2. This value is equivalent to the error code list `1007,1008,1050,1051,1054,1060,1061,1068,1094,1146'. _This value is not supported by the *Note `mysqld': mysqld. binary included with the MySQL Server 5.1 distribution_. (Bug #11762277, Bug #54854) For more information, see *Note mysql-cluster-replication-failover::. Examples: --slave-skip-errors=1062,1053 --slave-skip-errors=all --slave-skip-errors=ddl_exist_errors 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 *Note `SET': set-statement. Server options used with replication slaves are listed earlier in this section. * `init_slave' Options for init_slave *Command-Line `--init-slave=name' Format* *Option-File Format* `init_slave' *System Variable `init_slave' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *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. *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 *Note `START SLAVE': start-slave. returns. See *Note start-slave::, for more information. * `relay_log' Options for relay-log *Command-Line `--relay-log=name' Format* *Option-File Format* `relay-log' *System Variable `relay_log' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' The name of the relay log file. * `relay_log_index' Options for relay_log_index *Command-Line `--relay-log-index' Format* *Option-File Format* `relay_log_index' *System Variable `relay_log_index' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' *Default* `*host_name*-relay-bin.index' The name of 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 slave server. * `relay_log_info_file' Options for relay_log_info_file *Command-Line `--relay-log-info-file=file_name' Format* *Option-File Format* `relay_log_info_file' *System Variable `relay_log_info_file' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' *Default* `relay-log.info' The name of the file in which the slave records information about the relay logs. The default name is `relay-log.info' in the data directory. * `rpl_recovery_rank' This variable is unused, and is removed in MySQL 5.6. * `slave_compressed_protocol' Options for slave_compressed_protocol *Command-Line `--slave_compressed_protocol' Format* *Option-File Format* `slave_compressed_protocol' *System Variable `slave_compressed_protocol' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' Whether to use compression of the slave/master protocol if both the slave and the master support it. * `slave_exec_mode' Options for slave_exec_mode *Introduced* 5.1.23-ndb-6.2.14, 5.1.23-ndb-6.3.11, 5.1.24 *Command-Line `--slave-exec-mode=mode' Format* *Option-File Format* `slave_exec_mode' *System Variable `slave_exec_mode' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `STRICT' (ALL) *Default* `IDEMPOTENT' (NDB) *Valid Values* `IDEMPOTENT' `STRICT' Controls whether `IDEMPOTENT' or `STRICT' mode is used in replication conflict resolution and error checking. `IDEMPOTENT' mode causes suppression of duplicate-key and no-key-found errors. Beginning with MySQL 5.1.23-ndb-6.2.14 and MySQL 5.1.24, this mode should be employed in multi-master replication, circular replication, and some other special replication scenarios. `STRICT' mode is the default, and is suitable for most other cases. *Note*: MySQL Cluster ignores any value explicitly set for `slave_exec_mode', and always treats it as `IDEMPOTENT'. * `slave_max_allowed_packet' Options for slave_max_allowed_packet *Introduced* 5.1.64 *System Variable `slave_max_allowed_packet' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `1073741824' *Range* `1024 .. 1073741824' In MySQL 5.1.64 and later, 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'. 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_load_tmpdir' Options for slave-load-tmpdir *Command-Line `--slave-load-tmpdir=path' Format* *Option-File Format* `slave-load-tmpdir' *System Variable `slave_load_tmpdir' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' *Default* `/tmp' The name of the directory where the slave creates temporary files for replicating *Note `LOAD DATA INFILE': load-data. statements. * `slave_net_timeout' Options for slave-net-timeout *Command-Line `--slave-net-timeout=#' Format* *Option-File Format* `slave-net-timeout' *System Variable `slave_net_timeout' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `3600' *Min Value* `1' The number of seconds to wait for more data from a master/slave connection before aborting the read. Before MySQL 5.1.41, this timeout applies only to TCP/IP connections, not to connections made through Unix socket files, named pipes, or shared memory. * `slave_skip_errors' Options for slave-skip-errors *Command-Line `--slave-skip-errors=name' Format* *Option-File Format* `slave-skip-errors' *System Variable `slave_skip_errors' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values (>= 5.1.61-ndb-7.0.33,5.1.61-ndb-7.1.22)* *Type* `string' *Default* `OFF' *Valid Values* `[list of error codes]' `all' `ddl_exist_errors' Normally, replication stops when an error occurs on the slave. This gives you the opportunity to resolve the inconsistency in the data manually. This variable tells the slave SQL thread to continue replication when a statement returns any of the errors listed in the variable value. * `slave_transaction_retries' Options for slave_transaction_retries *Command-Line `--slave_transaction_retries=#' Format* *Option-File Format* `slave_transaction_retries' *System Variable `slave_transaction_retries' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `10' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `10' *Range* `0 .. 18446744073709547520' If a replication slave SQL thread fails to execute a transaction because of an *Note `InnoDB': innodb-storage-engine. deadlock or because the transaction's execution time exceeded *Note `InnoDB': innodb-storage-engine.'s `innodb_lock_wait_timeout' or *Note `NDBCLUSTER': mysql-cluster.'s `TransactionDeadlockDetectionTimeout' or `TransactionInactiveTimeout', it automatically retries `slave_transaction_retries' times before stopping with an error. The default value is 10. * `slave_type_conversions' Options for slave_type_conversions *Introduced* 5.1.44-ndb-6.3.33, 5.1.44-ndb-7.0.14, 5.1.44-ndb-7.1.3 *Command-Line `--slave_type_conversions=set' Format* *Option-File Format* `slave_type_conversions' *System Variable `slave_type_conversions' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `set' *Default* `' *Valid Values* `ALL_LOSSY' `ALL_NON_LOSSY' Controls the type conversion mode in effect on the slave when using MySQL Cluster Replication. Its value is a comma-delimited set of zero or more elements from the list: `ALL_LOSSY', `ALL_NON_LOSSY'. Set this variable to an empty string to disallow type conversions between the master and the slave. Changes require a restart of the slave to take effect. For additional information on type conversion modes applicable to MySQL Cluster replication attribute promotion and demotion, see *Note replication-features-attribute-promotion::. This variable was added in MySQL Cluster NDB 6.3.33, 7.0.14, and 7.1.3. * `sql_slave_skip_counter' Options for sql_slave_skip_counter *System Variable `sql_slave_skip_counter' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' The number of events from the master that a slave server should skip. *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 *Note set-global-sql-slave-skip-counter::.  File: manual.info, Node: replication-options-binary-log, Prev: replication-options-slave, Up: replication-options 16.1.3.4 Binary Log Options and Variables ......................................... You can use the *Note `mysqld': 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 *Note binary-log::. For additional information about using MySQL server options and system variables, see *Note server-options::, and *Note 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' Options for binlog-row-event-max-size *Introduced* 5.1.5 *Command-Line `--binlog-row-event-max-size=#' Format* *Option-File Format* `binlog-row-event-max-size' *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `1024' *Range* `256 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `1024' *Range* `256 .. 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 1024. See *Note replication-formats::. This option was added in MySQL 5.1.5. * `--log-bin[=BASE_NAME]' Options for log-bin *Command-Line `--log-bin' Format* *Option-File Format* `log-bin' *System Variable `log_bin' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `file name' Enable binary logging. The server logs all statements that change data to the binary log, which is used for backup and replication. See *Note binary-log::. The option value, if given, is the basename for the log sequence. The server creates binary log files in sequence by adding a numeric suffix to the basename. It is recommended that you specify a basename (see *Note bugs::, for the reason). Otherwise, MySQL uses `HOST_NAME-bin' as the basename. Setting this option causes the `log_bin' system variable to be set to `ON' (or `1'), and not to the basename. This is a known issue; see Bug #19614 for more information. * `--log-bin-index[=FILE_NAME]' Options for log-bin-index *Command-Line `--log-bin-index=name' Format* *Option-File Format* `log-bin-index' *Permitted Values* *Type* `file name' The index file for binary log file names. See *Note 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}]' Options for log-bin-trust-function-creators *Command-Line `--log-bin-trust-function-creators' Format* *Option-File Format* `log-bin-trust-function-creators' *System Variable `log_bin_trust_function_creators' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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 *Note stored-programs-logging::. *Note*: Previously, this option was known as `--log-bin-trust-routine-creators', which is now deprecated. * `--log-bin-use-v1-row-events[={0|1}]' Options for log-bin-use-v1-row-events *Introduced* 5.1.56-ndb-7-0-27, 5.1.56-ndb-7.1.16 *Command-Line `--log-bin-use-v1-row-events[={0|1}]' Format* *Option-File Format* `log-bin-use-v1-row-events' *System Variable `log_bin_use_v1_row_events' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `0' Version 2 binary log row events are available beginning with MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.16; however, Version 2 events cannot be read by previous MySQL Cluster releases. Setting `--log-bin-use-v1-row-events' to 0 causes *Note `mysqld': mysqld. to use Version 2 binary log events. Setting this option to 1 (the default) causes *Note `mysqld': 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. 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. *Note*: MySQL Cluster NDB 7.2.1 and later use Version 2 binary log events by default (and so the default value for this option changes to 0 in those versions). You should keep this mind when planning upgrades for setups using MySQL Cluster Replication. `--log-bin-use-v1-row-events' is not supported in mainline MySQL Server 5.1 releases. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `--log-short-format' Options for log-short-format *Command-Line `--log-short-format' Format* *Option-File Format* `log-short-format' *Permitted Values* *Type* `boolean' *Default* `FALSE' Log less information to the binary log and slow query log, if they have been activated. 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 *Note replication-options-slave::. * `--binlog-do-db=DB_NAME' Options for binlog-do-db *Command-Line `--binlog-do-db=name' Format* *Option-File Format* `binlog-do-db' *Permitted Values* *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 *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': 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 *Note `USE': 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 *Note `UPDATE': 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 *Note `DELETE': delete. statements or multiple-table *Note `UPDATE': 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 *Note `UPDATE': 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 *Note `UPDATE': update. statement is issued, the *Note `UPDATE': 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 *Note `UPDATE': update. statement; this occurs whether or not the *Note `USE': use. statement was issued. However, when using the row-based logging format and `--binlog-do-db=sales', changes made by the following *Note `UPDATE': 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 *Note `UPDATE': 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 *Note `UPDATE': 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 *Note `UPDATE': 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' Options for binlog-ignore-db *Command-Line `--binlog-ignore-db=name' Format* *Option-File Format* `binlog-ignore-db' *Permitted Values* *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 *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': 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 *Note `USE': use.) is DB_NAME. Prior to MySQL 5.1.70, this option caused any statements containing fully qualified table names not to be logged if there was no default database specified (that is, when *Note `SELECT': select. `DATABASE()' returned `NULL'). In MySQL 5.1.70 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 *Note `UPDATE': update. statement _is_ logged in such a case because `--binlog-ignore-db' applies only to the default database (determined by the *Note `USE': 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 *Note `UPDATE': 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. 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' Options for max-binlog-dump-events *Command-Line `--max-binlog-dump-events=#' Format* *Option-File Format* `max-binlog-dump-events' *Permitted Values* *Type* `numeric' *Default* `0' This option is used internally by the MySQL test suite for replication testing and debugging. * `--sporadic-binlog-dump-fail' Options for sporadic-binlog-dump-fail *Command-Line `--sporadic-binlog-dump-fail' Format* *Option-File Format* `sporadic-binlog-dump-fail' *Permitted Values* *Type* `boolean' *Default* `FALSE' This option is used internally by the MySQL test suite for replication testing and debugging. System variables used with the binary log 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 *Note `SET': set-statement. Server options used to control binary logging are listed earlier in this section. * `binlog_cache_size' Options for binlog_cache_size *Command-Line `--binlog_cache_size=#' Format* *Option-File Format* `binlog_cache_size' *System Variable `binlog_cache_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `32768' *Range* `4096 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `32768' *Range* `4096 .. 18446744073709547520' The size of the cache to hold the SQL statements for 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, multiple-statement 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 *Note binary-log::. * `binlog_direct_non_transactional_updates' Options for binlog_direct_non_transactional_updates *Introduced* 5.1.44 *Command-Line `--binlog_direct_non_transactional_updates[=value]' Format* *Option-File Format* `binlog_direct_non_transactional_updates' *System Variable `binlog_direct_non_transactional_updates' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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. Beginning with MySQL 5.1.44, 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. * `binlog_format' Options for binlog-format *Introduced* 5.1.5 *Command-Line `--binlog-format=format' Format* *Option-File Format* `binlog-format' *System Variable `binlog_format' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values (>= 5.1.5, <= 5.1.7)* *Type* `enumeration' *Default* `STATEMENT' *Valid Values* `ROW' `STATEMENT' *Permitted Values (>= 5.1.8, <= 5.1.11)* *Type* `enumeration' *Default* `STATEMENT' *Valid Values* `ROW' `STATEMENT' `MIXED' *Permitted Values (>= 5.1.12, <= 5.1.28)* *Type* `enumeration' *Default* `MIXED' *Valid Values* `ROW' `STATEMENT' `MIXED' *Permitted Values (>= 5.1.29)* *Type* `enumeration' *Default* `STATEMENT' *Valid Values* `ROW' `STATEMENT' `MIXED' This variable sets the binary logging format, and can be any one of `STATEMENT', `ROW', or `MIXED'. See *Note 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. The startup variable was added in MySQL 5.1.5, and the runtime variable in MySQL 5.1.8. `MIXED' was added in MySQL 5.1.8. `STATEMENT' was used by default prior to MySQL 5.1.12; in MySQL 5.1.12, the default was changed to `MIXED'. In MySQL 5.1.29, the default was changed back to `STATEMENT'. You must have the `SUPER' privilege to set the global `binlog_format' value. Starting with MySQL 5.1.29, you must have the `SUPER' privilege to set either the global or session `binlog_format' value. (Bug #39106) 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. See *Note set-statement::, for more information. 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. An exception to this rule is that `MIXED' always uses statement-based replication for stored functions and triggers. There are exceptions when you cannot switch the replication format at runtime: * From within a stored function or a trigger. * If the *Note `NDBCLUSTER': mysql-cluster. 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 those cases results in an error. Before MySQL 5.1.8, switching to row-based replication format would implicitly set `--log-bin-trust-function-creators=1' and `--innodb_locks_unsafe_for_binlog'. This does not occur for MySQL 5.1.8 and later. 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. * `log_bin' Options for log_bin *System Variable `log_bin' Name* *Variable Scope* Global *Dynamic Variable* 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 *Note binary-log::. * `log_bin_use_v1_row_events' Options for log_bin_use_v1_row_events *Introduced* 5.1.56-ndb-7-0-27, 5.1.56-ndb-7.1.16 *Command-Line `--log-bin-use-v1-row-events[={0|1}]' Format* *Option-File Format* `log_bin_use_v1_row_events' *System Variable `log_bin_use_v1_row_events' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `0' Shows whether Version 2 binary logging, available beginning with MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.16, 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 *Note `mysqld': mysqld. with the `--log-bin-use-v1-row-events' option. Other than when performing upgrades of MySQL 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 Cluster NDB 7.2.1 and later use Version 2 binary log row events by default (and so the default value for this variable changes to 0 in those versions). You should keep this mind when planning upgrades for setups using MySQL Cluster Replication. This variable is not supported in mainline MySQL Server 5.1. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `log_slave_updates' Options for log_slave_updates *Command-Line `--log-slave-updates' Format* *Option-File Format* `log_slave_updates' *System Variable `log_slave_updates' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `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 *Note replication-options::. * `max_binlog_cache_size' Options for max_binlog_cache_size *Command-Line `--max_binlog_cache_size=#' Format* *Option-File Format* `max_binlog_cache_size' *System Variable `max_binlog_cache_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values (<= 5.1.35)* *Platform Bit Size* `32' *Type* `numeric' *Default* `4294967295' *Range* `4096 .. 4294967295' *Permitted Values (<= 5.1.35)* *Platform Bit Size* `64' *Type* `numeric' *Default* `18446744073709547520' *Range* `4096 .. 18446744073709547520' *Permitted Values (>= 5.1.36)* *Type* `numeric' *Default* `18446744073709547520' *Range* `4096 .. 18446744073709547520' If a multiple-statement 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 and default values are 4GB on 32-bit platforms and 16EB (exabytes) on 64-bit platforms. As of MySQL 5.1.36, the maximum value is 16EB (exabytes) on all platforms. The maximum recommended value is 4GB; this is due to the fact that MySQL currently cannot work with binary log positions greater than 4GB. In MySQL 5.1, a change in `max_binlog_cache_size' takes immediate effect for all active sessions. * `max_binlog_size' Options for max_binlog_size *Command-Line `--max_binlog_size=#' Format* *Option-File Format* `max_binlog_size' *System Variable `max_binlog_size' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `1073741824' *Range* `4096 .. 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. * `sync_binlog' Options for sync_binlog *Command-Line `--sync-binlog=#' Format* *Option-File Format* `sync_binlog' *System Variable `sync_binlog' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Platform Bit Size* `32' *Type* `numeric' *Default* `0' *Range* `0 .. 4294967295' *Permitted Values* *Platform Bit Size* `64' *Type* `numeric' *Default* `0' *Range* `0 .. 18446744073709547520' If the value of this variable is greater than 0, the MySQL server synchronizes its binary log to disk (using `fdatasync()') after every `sync_binlog' writes to the binary log. There is one write to the binary log per statement if autocommit is enabled, and one write per transaction otherwise. The default value of `sync_binlog' is 0, which does 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. A value of 1 is the safest choice because in the event of a crash you lose at most one statement or transaction from the binary log. However, it is also the slowest choice (unless the disk has a battery-backed cache, which makes synchronization very fast).  File: manual.info, Node: replication-administration, Prev: replication-options, Up: replication-configuration 16.1.4 Common Replication Administration Tasks ---------------------------------------------- * Menu: * replication-administration-status:: Checking Replication Status * replication-administration-pausing:: Pausing Replication on the Slave Once replication has been started it should execute without requiring much regular administration. Depending on your replication environment, you will want to check the replication status of each slave periodically, daily, or even more frequently.  File: manual.info, Node: replication-administration-status, Next: replication-administration-pausing, Prev: replication-administration, Up: replication-administration 16.1.4.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 primary statement for this is *Note `SHOW SLAVE STATUS': show-slave-status, which you must execute on each slave: 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: The key fields from the status report to examine are: * `Slave_IO_State': The current status of the slave. See *Note slave-io-thread-states::, and *Note 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 *Note `STOP SLAVE': 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 *Note `SHOW SLAVE STATUS': 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 *Note `SHOW PROCESSLIST': 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 *Note `SHOW SLAVE HOSTS': 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)  File: manual.info, Node: replication-administration-pausing, Prev: replication-administration-status, Up: replication-administration 16.1.4.2 Pausing Replication on the Slave ......................................... You can stop and start the replication of statements on the slave using the *Note `STOP SLAVE': stop-slave. and *Note `START SLAVE': start-slave. statements. To stop processing of the binary log from the master, use *Note `STOP SLAVE': 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 *Note `START SLAVE': 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.  File: manual.info, Node: replication-implementation, Next: replication-solutions, Prev: replication-configuration, Up: replication 16.2 Replication Implementation =============================== * Menu: * replication-implementation-details:: Replication Implementation Details * slave-logs:: Replication Relay and Status Logs * replication-rules:: How Servers Evaluate Replication Filtering Rules 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, *Note `SELECT': 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 *Note replication-implementation-details::. Masters and slaves report their status in respect of the replication process regularly so that you can monitor them. See *Note 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 *Note 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 *Note replication-rules::.  File: manual.info, Node: replication-implementation-details, Next: slave-logs, Prev: replication-implementation, Up: replication-implementation 16.2.1 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 *Note `SHOW PROCESSLIST': show-processlist. on the master as the `Binlog Dump' thread. The binlog 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 *Note `START SLAVE': 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 *Note `SHOW SLAVE STATUS': show-slave-status. or as `Slave_running' in the output of *Note `SHOW STATUS': 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 binlog 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. This enables the master server to purge its binary logs sooner because it no longer needs to wait for the slave to fetch their contents. The *Note `SHOW PROCESSLIST': 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 *Note master-thread-states::. For slave states, see *Note slave-io-thread-states::, and *Note slave-sql-thread-states::. The following example illustrates how the three threads show up in the output from *Note `SHOW PROCESSLIST': show-processlist. On the master server, the output from *Note `SHOW PROCESSLIST': 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 *Note `SHOW PROCESSLIST': 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 *Note `SHOW PROCESSLIST': 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 *Note 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 *Note server-system-variables::. The *Note `SHOW SLAVE STATUS': show-slave-status. statement provides additional information about replication processing on a slave server. See *Note replication-administration-status::.  File: manual.info, Node: slave-logs, Next: replication-rules, Prev: replication-implementation-details, Up: replication-implementation 16.2.2 Replication Relay and Status Logs ---------------------------------------- * Menu: * slave-logs-relaylog:: The Slave Relay Log * slave-logs-status:: Slave 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 _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 _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. * The _relay log info log_ holds status information about the execution point within the slave's relay log.  File: manual.info, Node: slave-logs-relaylog, Next: slave-logs-status, Prev: slave-logs, Up: slave-logs 16.2.2.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 *Note `mysqlbinlog': mysqlbinlog. (see *Note 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 *Note 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 *Note `FLUSH LOGS': flush. or *Note `mysqladmin flush-logs': mysqladmin. * 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 as soon as 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, *Note `FLUSH LOGS': flush. rotates relay logs, which influences when the SQL thread deletes them.  File: manual.info, Node: slave-logs-status, Prev: slave-logs-relaylog, Up: slave-logs 16.2.2.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. See *Note replication-options::. The two status logs contain information like that shown in the output of the *Note `SHOW SLAVE STATUS': show-slave-status. statement, which is discussed in *Note 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 should be protected because it contains the password for connecting to the master. See *Note password-logging::. The slave I/O thread updates the master info log. The following table shows the correspondence between the lines in the `master.info' file and the columns displayed by *Note `SHOW SLAVE STATUS': show-slave-status. This table shows the correspondence between the lines in the `master.info' file and the columns displayed by *Note `SHOW SLAVE STATUS': show-slave-status. Line in `SHOW SLAVE STATUS' Column Description `master.info' 1 Number of lines in the file 2 `Master_Log_File' The name of the master binary log currently being read from the master 3 `Read_Master_Log_Pos' The current position within the master binary log that have been read from the master 4 `Master_Host' The host name of the master 5 `Master_User' The user name used to connect to the master 6 Password (not shown by *Note The password used to connect to `SHOW SLAVE STATUS': the master show-slave-status.) 7 `Master_Port' The network port used to connect to the master 8 `Connect_Retry' The period (in seconds) that the slave will wait before trying to reconnect to the master 9 `Master_SSL_Allowed' Indicates whether the server supports SSL connections 10 `Master_SSL_CA_File' The file used for the Certificate Authority (CA) certificate 11 `Master_SSL_CA_Path' The path to the Certificate Authority (CA) certificates 12 `Master_SSL_Cert' The name of the SSL certificate file 13 `Master_SSL_Cipher' The list of possible ciphers used in the handshake for the SSL connection 14 `Master_SSL_Key' The name of the SSL key file 15 `Master_SSL_Verify_Server_Cert'Whether to verify the server certificate (added in MySQL 5.1.18) The slave SQL thread updates the relay log info log. The following table shows the correspondence between the lines in the `relay-log.info' file and the columns displayed by *Note `SHOW SLAVE STATUS': show-slave-status. This table shows the correspondence between the lines in the `relay-log.info' file and the columns displayed by *Note `SHOW SLAVE STATUS': show-slave-status. Line in `SHOW SLAVE STATUS' Description `relay-log.info'Column 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 The contents of the `relay-log.info' file and the states shown by the *Note `SHOW SLAVE STATUS': 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, *Note `SHOW SLAVE STATUS': show-slave-status. should be used. 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 *Note `CHANGE MASTER TO': 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.  File: manual.info, Node: replication-rules, Prev: slave-logs, Up: replication-implementation 16.2.3 How Servers Evaluate Replication Filtering Rules ------------------------------------------------------- * Menu: * replication-rules-db-options:: Evaluation of Database-Level Replication and Binary Logging Options * replication-rules-table-options:: Evaluation of Table-Level Replication Options * replication-rules-examples:: Replication Rule Application 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 *Note 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 *Note replication-options::.) 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 *Note replication-rules-db-options::, for a description of this process. If no matching database-level options are found, option checking proceeds to any table-level options that may be in use, as discussed in *Note replication-rules-table-options::. 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. An example of the latter that may have unintended effects is the use of `--replicate-do-db' and `--replicate-wild-do-table' together, where `--replicate-wild-do-table' uses a pattern for the database name that matches the name given for `--replicate-do-db'. Suppose a replication slave is started with `--replicate-do-db=dbx' `--replicate-wild-do-table=db%.t1'. Then, suppose that on the master, you issue the statement *Note `CREATE DATABASE dbx': create-database. Although you might expect it, this statement is not replicated because it does not reference a table named `t1'. If any `--replicate-rewrite-db' options were specified, they are applied before the `--replicate-*' filtering rules are tested. *Note*: In MySQL 5.1, database-level filtering options are case-sensitive on platforms supporting case sensitivity in filenames, whereas table-level filtering options are not (regardless of platform). This is true regardless of the value of the `lower_case_table_names' system variable. These are known issues which are fixed in MySQL 5.5.  File: manual.info, Node: replication-rules-db-options, Next: replication-rules-table-options, Prev: replication-rules, Up: replication-rules 16.2.3.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. With statement-based replication, the default database is checked for a match. With row-based replication, the database where data is to be changed is the database that is checked. Regardless of the binary logging format, checking of database-level options proceeds as shown in the following diagram. Evaluation of Database-Level Filtering Rules in Replication The steps involved are listed here: 1. Are there any `--replicate-do-db' options? * Yes Do any of them match the database? * Yes Execute the statement and exit. * No Continue to step 2. * No Continue to step 2. 2. Are there any `--replicate-ignore-db' options? * Yes Do any of them match the database? * Yes Ignore the statement and exit. * No Continue to step 3. * No Continue to step 3. 3. Proceed to checking the table-level replication options, if there are any. For a description of how these options are checked, see *Note 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 *Note `USE': 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 *Note `CREATE DATABASE': create-database, *Note `ALTER DATABASE': alter-database, and *Note `DROP DATABASE': 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'.  File: manual.info, Node: replication-rules-table-options, Next: replication-rules-examples, Prev: replication-rules-db-options, Up: replication-rules 16.2.3.2 Evaluation of Table-Level Replication Options ...................................................... The slave checks for and evaluates table options only if no matching database options were found (see *Note 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. This process is illustrated in the following diagram. Evaluation of Table-Level Filtering Rules in Replication The following steps describe this evaluation in more detail: 1. Are there any table options? * Yes Continue to step 2. * No Execute the event and exit. 2. Are there any `--replicate-do-table' options? * Yes Does the table match any of them? * Yes Execute the event and exit. * No Continue to step 3. * No Continue to step 3. 3. Are there any `--replicate-ignore-table' options? * Yes Does the table match any of them? * Yes Ignore the event and exit. * No Continue to step 4. * No Continue to step 4. 4. Are there any `--replicate-wild-do-table' options? * Yes Does the table match any of them? * Yes Execute the event and exit. * No Continue to step 5. * No Continue to step 5. 5. Are there any `--replicate-wild-ignore-table' options? * Yes Does the table match any of them? * Yes Ignore the event and exit. * No Continue to step 6. * No Continue to step 6. 6. Are there any `--replicate-do-table' or `--replicate-wild-do-table' options? * Yes Ignore the event and exit. * No Execute the event and exit.  File: manual.info, Node: replication-rules-examples, Prev: replication-rules-table-options, Up: replication-rules 16.2.3.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: This table shows typical combinations of replication filter rule types and describes the outcome of each. Condition (Types of Options) Outcome 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 *Note `INSERT': 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 *Note `USE': 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 *Note `INSERT': 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_.  File: manual.info, Node: replication-solutions, Next: replication-notes, Prev: replication-implementation, Up: replication 16.3 Replication Solutions ========================== * Menu: * replication-solutions-backups:: Using Replication for Backups * replication-solutions-diffengines:: Using Replication with Different Master and Slave Storage Engines * replication-solutions-scaleout:: Using Replication for Scale-Out * replication-solutions-partitioning:: Replicating Different Databases to Different Slaves * replication-solutions-performance:: Improving Replication Performance * replication-solutions-switch:: Switching Masters During Failover * replication-solutions-ssl:: Setting Up Replication Using SSL 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 *Note replication-solutions-backups::. For advice and tips on using different storage engines on the master and slaves, see *Note 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 *Note replication-solutions-scaleout::. For performance or data distribution reasons, you may want to replicate different databases to different replication slaves. See *Note 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 an replication master, see *Note replication-solutions-performance::. For guidance on switching masters, or converting slaves into masters as part of an emergency failover solution, see *Note replication-solutions-switch::. To secure your replication communication, you can use SSL to encrypt the communication channel. For step-by-step instructions, see *Note replication-solutions-ssl::.  File: manual.info, Node: replication-solutions-backups, Next: replication-solutions-diffengines, Prev: replication-solutions, Up: replication-solutions 16.3.1 Using Replication for Backups ------------------------------------ * Menu: * replication-solutions-backups-mysqldump:: Backing Up a Slave Using `mysqldump' * replication-solutions-backups-rawdata:: Backing Up Raw Data from a Slave * replication-solutions-backups-read-only:: Backing Up a Master or Slave by Making It Read Only 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 *Note `mysqldump': mysqldump. tool may be suitable. See *Note replication-solutions-backups-mysqldump::. * For larger databases, where *Note `mysqldump': 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 *Note 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 *Note replication-solutions-backups-read-only::.  File: manual.info, Node: replication-solutions-backups-mysqldump, Next: replication-solutions-backups-rawdata, Prev: replication-solutions-backups, Up: replication-solutions-backups 16.3.1.1 Backing Up a Slave Using `mysqldump' ............................................. Using *Note `mysqldump': 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 *Note 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, *Note `mysqldump': mysqldump. may be impractical. When using *Note `mysqldump': 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 *Note `mysqladmin': 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 *Note `mysqldump': 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 *Note 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 *Note replication-solutions-partitioning::.  File: manual.info, Node: replication-solutions-backups-rawdata, Next: replication-solutions-backups-read-only, Prev: replication-solutions-backups-mysqldump, Up: replication-solutions-backups 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.1\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, `master.info' and `relay-log.info', along with 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 *Note `CHANGE MASTER TO': 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 *Note `LOAD DATA INFILE': load-data. 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 *Note `LOAD DATA INFILE': load-data. 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.  File: manual.info, Node: replication-solutions-backups-read-only, Prev: replication-solutions-backups-rawdata, Up: replication-solutions-backups 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 *Note `mysqldump': mysqldump. (see *Note 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. These instructions also require MySQL 5.1.15 or higher. For earlier versions, setting `read_only' does not block while table locks or outstanding transactions are pending, so data changes can still occur during the backup operation and produce inconsistent backup results. 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 *Note `mysqldump': 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 *Note `mysqldump': 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.  File: manual.info, Node: replication-solutions-diffengines, Next: replication-solutions-scaleout, Prev: replication-solutions-backups, Up: replication-solutions 16.3.2 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 system variables `storage_engine' and `table_type' 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 *Note 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 *Note `mysqldump': 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 *Note `mysqldump': 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-innodb' option on your slave to disable the `InnoDB' 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 *Note `ALTER TABLE': 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 `storage_engine' and `table_type' variables are not replicated, be aware that *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': 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 `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 storage_engine=MyISAM; mysql> CREATE TABLE tablea (columna int); When replicated, the `storage_engine' variable will be ignored, and the *Note `CREATE TABLE': create-table. statement will execute on the slave using the slave's default engine.  File: manual.info, Node: replication-solutions-scaleout, Next: replication-solutions-partitioning, Prev: replication-solutions-diffengines, Up: replication-solutions 16.3.3 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 Web sites fit into this category, where users are browsing the Web site, 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 *Note 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 *Note `replace': replace-utility. 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.  File: manual.info, Node: replication-solutions-partitioning, Next: replication-solutions-performance, Prev: replication-solutions-scaleout, Up: replication-solutions 16.3.4 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 *Note 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 *Note figure_replication-multi-db::, you should configure each replication slave as follows, before executing *Note `START SLAVE': 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 *Note `mysqldump': 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 *Note `InnoDB': innodb-storage-engine. databases unless you use `innodb_file_per_table'.  File: manual.info, Node: replication-solutions-performance, Next: replication-solutions-switch, Prev: replication-solutions-partitioning, Up: replication-solutions 16.3.5 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 *Note 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 *Note 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 *Note 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.  File: manual.info, Node: replication-solutions-switch, Next: replication-solutions-ssl, Prev: replication-solutions-performance, Up: replication-solutions 16.3.6 Switching Masters During Failover ---------------------------------------- There is currently no official solution for providing failover between master and slaves in the event of a failure. With the currently available features, you would have to set up a master and a slave (or several slaves), and to write a script that monitors the master to check whether it is up. Then instruct your applications and the slaves to change master in case of failure. Remember that you can tell a slave to change its master at any time, using the *Note `CHANGE MASTER TO': change-master-to. statement. The slave will not check whether the databases on the master are compatible with the slave, it will just start reading and executing events from the specified binary log coordinates on the new master. 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 database structure or integrity providing you are careful. Run your slaves with the `--log-bin' option and without `--log-slave-updates'. In this way, the slave is ready to become a master as soon as you issue *Note `STOP SLAVE': stop-slave.; *Note `RESET MASTER': reset-master, and *Note `CHANGE MASTER TO': change-master-to. statement on the other slaves. For example, assume that you have the structure shown in *Note 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 *Note 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 will log 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. Suppose that `Slave 1' has `--log-slave-updates' enabled. Then it will write updates that it receives from `Master' to its own binary log. 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 *Note `SHOW PROCESSLIST': 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 *Note `STOP SLAVE': stop-slave. and *Note `RESET MASTER': reset-master. On the other slaves `Slave 2' and `Slave 3', use *Note `STOP SLAVE': stop-slave. and `CHANGE MASTER TO MASTER_HOST='Slave1'' (where `'Slave1'' represents the real host name of `Slave 1'). To use *Note `CHANGE MASTER TO': change-master-to, add all information about how to connect to `Slave 1' from `Slave 2' or `Slave 3' (USER, PASSWORD, PORT). In *Note `CHANGE MASTER TO': change-master-to, there is no need to specify the name of the `Slave 1' binary log file or log position to read from: We know it is the first binary log file and position 4, which are the defaults for *Note `CHANGE MASTER TO': change-master-to. Finally, use *Note `START SLAVE': start-slave. on `Slave 2' and `Slave 3'. Once the new replication is in place, you will then need to instruct 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 *Note figure_replication-redundancy-after::. FIGURE GOES HERE: Redundancy Using Replication, After Master Failure When `Master' is up again, you must issue on it the same *Note `CHANGE MASTER TO': change-master-to. as that issued on `Slave 2' and `Slave 3', so that `Master' becomes a slave of `S1' and picks up each `Web Client' writes that it missed while it was down. To make `Master' a master again (for example, because it is the most powerful machine), 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 *Note `RESET MASTER': reset-master. on `Master' before making `Slave 1', `Slave 2', and `Slave 3' slaves of `Master'. Otherwise, they may pick up old `Web Client' writes from before the point at which `Master' became unavailable. Note that there is no synchronization between the different slaves to a master. Some slaves might be ahead of others. This means that the concept outlined in the previous example might not work. In practice, however, the relay logs of different slaves will most likely not be far behind the master, so it would work, anyway (but there is no guarantee). A good way to keep your applications informed as to the location of the master is by having a dynamic DNS entry for the master. With `bind' you can use `nsupdate' to dynamically update your DNS.  File: manual.info, Node: replication-solutions-ssl, Prev: replication-solutions-switch, Up: replication-solutions 16.3.7 Setting Up Replication Using SSL --------------------------------------- To use SSL for encrypting the transfer of the binary log required during replication, both the master and the slave must support SSL network connections. If either host does not support SSL connections (because it has not been compiled or configured for SSL), replication through an SSL connection is not possible. Setting up replication using an SSL connection is similar to setting up a server and client using SSL. 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. For more information on setting up a server and client for SSL connectivity, see *Note configuring-for-ssl::. To enable SSL on the master you must create or obtain suitable certificates, and then add the following configuration options to the master's configuration within the `[mysqld]' section of the master's `my.cnf' file: [mysqld] ssl-ca=CACERT.PEM ssl-cert=SERVER-CERT.PEM ssl-key=SERVER-KEY.PEM The paths to the certificates may be relative or absolute; we recommend that you always use complete paths for this purpose. The options are as follows: * `ssl-ca' identifies the Certificate Authority (CA) certificate. * `ssl-cert' identifies the server public key. This can be sent to the client and authenticated against the CA certificate that it has. * `ssl-key' identifies the server private key. On the slave, you have two options available for setting the SSL information. You can either add the slave certificates to the `[client]' section of the slave's `my.cnf' file, or you can explicitly specify the SSL information using the *Note `CHANGE MASTER TO': change-master-to. statement: * To add the slave certificates using an option file, add the following lines to the `[client]' section of the slave's `my.cnf' file: [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 *Note `CHANGE MASTER TO': change-master-to. to specify the master configuration, using the `MASTER_SSL' option to enable SSL connectivity: mysql> CHANGE MASTER TO -> MASTER_HOST='master_hostname', -> MASTER_USER='replicate', -> MASTER_PASSWORD='password', -> MASTER_SSL=1; * To specify the SSL certificate options using the *Note `CHANGE MASTER TO': change-master-to. statement, append the SSL options: mysql> CHANGE MASTER TO -> MASTER_HOST='master_hostname', -> MASTER_USER='replicate', -> MASTER_PASSWORD='password', -> MASTER_SSL=1, -> MASTER_SSL_CA = 'ca_file_name', -> MASTER_SSL_CAPATH = 'ca_directory_name', -> MASTER_SSL_CERT = 'cert_file_name', -> MASTER_SSL_KEY = 'key_file_name'; After the master information has been updated, start the slave replication process: mysql> START SLAVE; You can use the *Note `SHOW SLAVE STATUS': show-slave-status. statement to confirm that the SSL connection was established successfully. For more information on the *Note `CHANGE MASTER TO': change-master-to. statement, see *Note change-master-to::. If you want to enforce the use of SSL connections during replication, then create a user with the `REPLICATION SLAVE' privilege and use the `REQUIRE SSL' option for that user. For example: mysql> CREATE USER 'repl'@'%.mydomain.com' IDENTIFIED BY 'slavepass'; mysql> GRANT REPLICATION SLAVE ON *.* -> TO 'repl'@'%.mydomain.com' REQUIRE SSL; If the account already exists, you can add `REQUIRE SSL' to it with this statement: mysql> GRANT USAGE ON *.* -> TO 'repl'@'%.mydomain.com' REQUIRE SSL;  File: manual.info, Node: replication-notes, Prev: replication-solutions, Up: replication 16.4 Replication Notes and Tips =============================== * Menu: * replication-features:: Replication Features and Issues * replication-compatibility:: Replication Compatibility Between MySQL Versions * replication-upgrade:: Upgrading a Replication Setup * replication-problems:: Troubleshooting Replication * replication-bugs:: How to Report Replication Bugs or Problems  File: manual.info, Node: replication-features, Next: replication-compatibility, Prev: replication-notes, Up: replication-notes 16.4.1 Replication Features and Issues -------------------------------------- * Menu: * replication-features-auto-increment:: Replication and `AUTO_INCREMENT' * replication-features-blackhole:: Replication and `BLACKHOLE' Tables * replication-features-charset:: Replication and Character Sets * replication-features-create-if-not-exists:: Replication of `CREATE ... IF NOT EXISTS' Statements * replication-features-create-select:: Replication of `CREATE TABLE ... SELECT' Statements * replication-features-current-user:: Replication of `CURRENT_USER()' * replication-features-create-alter-drop-server:: Replication of `CREATE SERVER', `ALTER SERVER', and `DROP SERVER' * replication-features-drop-if-exists:: Replication of `DROP ... IF EXISTS' Statements * replication-features-differing-tables:: Replication with Differing Table Definitions on Master and Slave * replication-features-directory:: Replication and `DIRECTORY' Table Options * replication-features-invoked:: Replication of Invoked Features * replication-features-floatvalues:: Replication and Floating-Point Values * replication-features-flush:: Replication and `FLUSH' * replication-features-functions:: Replication and System Functions * replication-features-limit:: Replication and `LIMIT' * replication-features-load-data:: Replication and `LOAD DATA INFILE' * replication-features-logging:: Replication and the Slow Query Log * replication-features-repair-table:: Replication and `REPAIR TABLE' * replication-features-shutdowns:: Replication and Master or Slave Shutdowns * replication-features-max-allowed-packet:: Replication and `max_allowed_packet' * replication-features-memory:: Replication and `MEMORY' Tables * replication-features-temptables:: Replication and Temporary Tables * replication-features-mysqldb:: Replication of the `mysql' System Database * replication-features-optimizer:: Replication and the Query Optimizer * replication-features-reserved-words:: Replication and Reserved Words * replication-features-set-password:: `SET PASSWORD' and Row-Based Replication * replication-features-slaveerrors:: Slave Errors During Replication * replication-features-sql-mode:: Replication and Server SQL Mode * replication-features-timeout:: Replication Retries and Timeouts * replication-features-timestamp:: Replication and `TIMESTAMP' * replication-features-timezone:: Replication and Time Zones * replication-features-transactions:: Replication and Transactions * replication-features-triggers:: Replication and Triggers * replication-features-truncate:: Replication and `TRUNCATE TABLE' * replication-features-variables:: Replication and Variables * replication-features-views:: Replication and Views 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 others, successful SBR requires that any SQL features used be supported by both the master and the slave servers. For example, if you use a feature on the master server that is available only in MySQL 5.1 (or later), you cannot replicate to a slave that uses MySQL 5.0 (or earlier). Such incompatibilities also can occur within a release series when using pre-production releases of MySQL. For example, the `SLEEP()' function is available beginning with MySQL 5.0.12. If you use this function on the master, you cannot replicate to a slave that uses MySQL 5.0.11 or earlier. For this reason, use Generally Available (GA) releases of MySQL for statement-based replication in a production setting, since we do not introduce new SQL statements or change their behavior within a given release series once that series reaches GA release status. If you are planning to use statement-based replication between MySQL 5.1 and a previous MySQL release series, it is also 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 *Note stored-programs-logging::. For more information about row-based logging and row-based replication, see *Note binary-log-formats::, and *Note replication-formats::. For additional information specific to replication and `InnoDB', see *Note innodb-and-mysql-replication::. For information relating to replication with MySQL Cluster, see *Note mysql-cluster-replication::.  File: manual.info, Node: replication-features-auto-increment, Next: replication-features-blackhole, Prev: replication-features, Up: replication-features 16.4.1.1 Replication and `AUTO_INCREMENT' ......................................... Statement-based replication of `AUTO_INCREMENT', `LAST_INSERT_ID()', and *Note `TIMESTAMP': datetime. values is done correctly, subject to the following exceptions: * When using statement-based replication, `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. This is a known issue which is fixed in MySQL 5.5. (Bug #12669186) * Prior to MySQL 5.1.12, a stored procedure that uses `LAST_INSERT_ID()' does not replicate properly using statement-based binary logging. * Prior to MySQL 5.1.12, when a stored routine or trigger caused an *Note `INSERT': insert. into an `AUTO_INCREMENT' column, the generated `AUTO_INCREMENT' value was not written into the binary log, so a different value could in some cases be inserted on the slave. * An insert into an `AUTO_INCREMENT' column caused by a stored routine or trigger running on a master that uses MySQL 5.0.60 or earlier does not replicate correctly to a slave running MySQL 5.1.12 through 5.1.23 (inclusive). (Bug #33029) A statement invoking a trigger or function that causes an update to an `AUTO_INCREMENT' column is not replicated correctly using statement-based replication. Beginning with MySQL 5.1.40, such statements are marked as unsafe. (Bug #45677) * The `AUTO_INCREMENT' table option was not replicated correctly prior to MySQL 5.1.31. (Bug #41986) * An *Note `INSERT': 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. Beginning with MySQL 5.1.64, such statements are marked as unsafe. (Bug #11754117, Bug #45670) This issue does not affect tables using the *Note `InnoDB': innodb-storage-engine. storage engine, since an `InnoDB' table with an AUTO_INCREMENT (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_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 *Note `ALTER TABLE': 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 *Note `CREATE TABLE': 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 *Note alter-table-problems::.  File: manual.info, Node: replication-features-blackhole, Next: replication-features-charset, Prev: replication-features-auto-increment, Up: replication-features 16.4.1.2 Replication and `BLACKHOLE' Tables ........................................... The *Note `BLACKHOLE': blackhole-storage-engine. 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. For this reason we recommend when you replicate to tables using the *Note `BLACKHOLE': blackhole-storage-engine. storage engine that you have the `binlog_format' server variable set to `STATEMENT', and not to either `ROW' or `MIXED'.  File: manual.info, Node: replication-features-charset, Next: replication-features-create-if-not-exists, Prev: replication-features-blackhole, Up: replication-features 16.4.1.3 Replication and Character Sets ....................................... The following applies to replication between MySQL servers that use different character sets: * If the master uses MySQL 4.1, you must _always_ use the same _global_ character set and collation on the master and the slave, regardless of the slave MySQL version. (These are controlled by the `--character-set-server' and `--collation-server' options.) Otherwise, you may get duplicate-key errors on the slave, because a key that is unique in the master character set might not be unique in the slave character set. Note that this is not a cause for concern when master and slave are both MySQL 5.0 or later. * If the master is older than MySQL 4.1.3, the character set of any client should never be made different from its global value because this character set change is not known to the slave. In other words, clients should not use `SET NAMES', `SET CHARACTER SET', and so forth. If both the master and the slave are 4.1.3 or newer, clients can freely set session values for character set variables because these settings are written to the binary log and so are known to the slave. That is, clients can use `SET NAMES' or `SET CHARACTER SET' or can set variables such as `collation_client' or `collation_server'. However, clients are prevented from changing the _global_ value of these variables; as stated previously, the master and slave must always have identical global character set values. This is true whether you are using statement-based or row-based replication. * If the master has databases with a character set different from the global `character_set_server' value, you should design your *Note `CREATE TABLE': 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 *Note `CREATE TABLE': create-table. statements.  File: manual.info, Node: replication-features-create-if-not-exists, Next: replication-features-create-select, Prev: replication-features-charset, Up: replication-features 16.4.1.4 Replication of `CREATE ... IF NOT EXISTS' Statements ............................................................. This section discusses the rules that are applied when various `CREATE ... IF NOT EXISTS' statements are replicated. Previous to MySQL 5.1.38 *Note `CREATE DATABASE IF NOT EXISTS': create-database. was replicated only if the database named in the statement did not exist on the master. *Note `CREATE TABLE IF NOT EXISTS': create-table. was replicated only if the table named in the statement did not exist on the master. MySQL 5.1.39 and later Every *Note `CREATE DATABASE IF NOT EXISTS': create-database. statement is replicated, whether or not the database already exists on the master. Similarly, every *Note `CREATE TABLE IF NOT EXISTS': create-table. statement is replicated, whether or not the table already exists on the master. This includes *Note `CREATE TABLE IF NOT EXISTS ... LIKE': create-table. However, replication of *Note `CREATE TABLE IF NOT EXISTS ... SELECT': create-table. follows somewhat different rules; see *Note replication-features-create-select::, for more information. Replication of `CREATE EVENT IF NOT EXISTS' *Note `CREATE EVENT IF NOT EXISTS': create-event. is always replicated, whether or not the event named in the statement already exists on the master. This is true for all MySQL 5.1 releases beginning with MySQL 5.1.6, when this statement was introduced. See also Bug #45574.  File: manual.info, Node: replication-features-create-select, Next: replication-features-current-user, Prev: replication-features-create-if-not-exists, Up: replication-features 16.4.1.5 Replication of `CREATE TABLE ... SELECT' Statements ............................................................ This section discusses how MySQL replicates *Note `CREATE TABLE ... SELECT': create-table-select. statements. These behaviors are not dependent on MySQL version: * *Note `CREATE TABLE ... SELECT': create-table-select. always performs an implicit commit (*Note 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 *Note `CREATE TABLE': 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 handles the statement in a version-dependent way. In MySQL 5.1 before 5.1.51 and in MySQL 5.5 before 5.5.6 (this is the original behavior): * `STATEMENT' or `MIXED' format: The statement is logged as written. * `ROW' format: The statement is logged as a *Note `CREATE TABLE': create-table. statement followed by a series of insert-row events. In MySQL 5.1 as of 5.1.51: * `STATEMENT' or `MIXED' format: The statement is logged as the equivalent pair of *Note `CREATE TABLE': create-table. and *Note `INSERT INTO ... SELECT': insert-select. statements. * `ROW' format: The statement is logged as a *Note `CREATE TABLE': create-table. statement followed by a series of insert-row events. In MySQL 5.5 as of 5.5.6: * Nothing is inserted or logged. These version dependencies arise due to a change in MySQL 5.5.6 in handling of *Note `CREATE TABLE ... SELECT': create-table-select. not to insert rows if the destination table already exists, and a change made in MySQL 5.1.51 to preserve forward compatibility in replication of such statements from a 5.1 master to a 5.5 slave. For details, see *Note create-table-select::.  File: manual.info, Node: replication-features-current-user, Next: replication-features-create-alter-drop-server, Prev: replication-features-create-select, Up: replication-features 16.4.1.6 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: * *Note `DROP USER': drop-user. * *Note `RENAME USER': rename-user. * *Note `GRANT': grant. * *Note `REVOKE': revoke. * *Note `CREATE FUNCTION': create-function. * *Note `CREATE PROCEDURE': create-procedure. * *Note `CREATE TRIGGER': create-trigger. * *Note `CREATE EVENT': create-event. * *Note `CREATE VIEW': create-view. * *Note `ALTER EVENT': alter-event. * *Note `ALTER VIEW': alter-view. * *Note `SET PASSWORD': set-password. In all MySQL 5.1 releases, when `CURRENT_USER()' or `CURRENT_USER' is used as the definer in any of the statements *Note `CREATE FUNCTION': create-function, *Note `CREATE PROCEDURE': create-procedure, *Note `CREATE TRIGGER': create-trigger, *Note `CREATE EVENT': create-event, *Note `CREATE VIEW': create-view, or *Note `ALTER VIEW': 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. Beginning with MySQL 5.1.49, `CURRENT_USER()' or `CURRENT_USER' is also expanded prior to being written to the binary log when used in *Note `DROP USER': drop-user, *Note `RENAME USER': rename-user, *Note `GRANT': grant, *Note `REVOKE': revoke, or *Note `ALTER EVENT': alter-event. (Bug #48321)  File: manual.info, Node: replication-features-create-alter-drop-server, Next: replication-features-drop-if-exists, Prev: replication-features-current-user, Up: replication-features 16.4.1.7 Replication of `CREATE SERVER', `ALTER SERVER', and `DROP SERVER' .......................................................................... In MySQL 5.1, the statements *Note `CREATE SERVER': create-server, *Note `ALTER SERVER': alter-server, and *Note `DROP SERVER': drop-server. are logged only when `binlog_format' is equal to `ROW'. These statements are not written to the binary log when using either the statement-based or mixed logging format.  File: manual.info, Node: replication-features-drop-if-exists, Next: replication-features-differing-tables, Prev: replication-features-create-alter-drop-server, Up: replication-features 16.4.1.8 Replication of `DROP ... IF EXISTS' Statements ....................................................... The *Note `DROP DATABASE IF EXISTS': drop-database, *Note `DROP TABLE IF EXISTS': drop-table, and *Note `DROP VIEW IF EXISTS': drop-view. 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. Beginning with MySQL 5.1.33, `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. (Bug #13684)  File: manual.info, Node: replication-features-differing-tables, Next: replication-features-directory, Prev: replication-features-drop-if-exists, Up: replication-features 16.4.1.9 Replication with Differing Table Definitions on Master and Slave ......................................................................... * Menu: * replication-features-more-columns:: Replication with More Columns on Master or Slave * replication-features-different-data-types:: Replication of Columns Having Different Data Types Starting with MySQL 5.1.21, 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. 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.  File: manual.info, Node: replication-features-more-columns, Next: replication-features-different-data-types, Prev: replication-features-differing-tables, Up: replication-features-differing-tables 16.4.1.10 Replication with More Columns on Master or Slave .......................................................... Starting with MySQL 5.1.21, 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 *Note `ALTER TABLE': 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 *Note `CREATE TABLE': create-table. statement: CREATE TABLE t ( c1 INT, c2 INT, c3 INT ); Suppose that the *Note `ALTER TABLE': alter-table. statement shown here is executed on the slave: ALTER TABLE t ADD COLUMN cnew1 INT AFTER c3; The previous *Note `ALTER TABLE': 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 *Note `ALTER TABLE': 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 *Note `ALTER TABLE': 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. *Note*: 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 *Note 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 Error 1532 (`ER_BINLOG_ROW_RBR_TO_SBR') 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 Error 1532 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 Error 1532 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 Error 1532 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);  File: manual.info, Node: replication-features-different-data-types, Prev: replication-features-more-columns, Up: replication-features-differing-tables 16.4.1.11 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, beginning with MySQL 5.1.21, this is not always strictly enforced, as long as certain conditions are met. All other things being equal, it is always 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. When using statement-based replication, `AUTO_INCREMENT' columns must be the same on both the master and the slave; otherwise, updates may be applied to the wrong table on the slave. This is a known issue which is fixed in MySQL 5.5. (Bug #12669186) *Note*: The restrictions described in the next few paragraphs do not apply to MySQL Cluster Replication, beginning with MySQL Cluster NDB 6.3.33, 7.0.14, and 7.1.3. These and later versions of MySQL Cluster support attribute promotion and demotion (such as *Note `TINYINT': integer-types. to *Note `BIGINT': integer-types, and *Note `VARCHAR(50)': char. to *Note `CHAR(25)': char, respectively) in replication; see *Note replication-features-attribute-promotion::, for more information. Row-based replication For row-based replication, the case is not so simple, due to the fact that changes rather than statements are replicated, and these changes are transmitted from master to slave using formats that do not always map directly to MySQL server column data types. For example, with row-based binary logging, you cannot replicate between different `INT' subtypes, such as from `TINYINT' to `BIGINT', because changes to columns of these types are represented differently from one another in the binary log when using row-based logging. However, you can replicate from `BLOB' to `TEXT' using row-based replication because changes to `BLOB' and `TEXT' columns are represented using the same format in the binary log. Supported conversions for attribute promotion when using row-based replication are shown in the following table: This table shows supported conversions for attribute promotion when using row-based replication. From (Master) To (Slave) *Note `BINARY': binary-varbinary. *Note `CHAR': char. *Note `BLOB': blob. *Note `TEXT': blob. *Note `CHAR': char. *Note `BINARY': binary-varbinary. *Note `DECIMAL': fixed-point-types. *Note `NUMERIC': fixed-point-types. *Note `NUMERIC': fixed-point-types. *Note `DECIMAL': fixed-point-types. *Note `TEXT': blob. *Note `BLOB': blob. *Note `VARBINARY': binary-varbinary. *Note `VARCHAR': char. *Note `VARCHAR': char. *Note `VARBINARY': binary-varbinary. *Note*: In all cases, the size or width of the column on the slave must be equal to or greater than that of the column on the master. For example, you can replicate from a `CHAR(10)' column on the master to a column that uses `BINARY(10)' or `BINARY(25)' on the slave, but you cannot replicate from a `CHAR(10)' column on the master to `BINARY(5)' column on the slave. Any unique index (including primary keys) having a prefix must use a prefix of the same length on both master and slave; in such cases, differing prefix lengths are disallowed. It is possible to use a nonunique index whose prefix length differs between master and slave, but this can cause serious performance issues, particularly when the prefix used on the master is longer. This is due to the fact that 2 unique prefixes of a given length may no longer be unique at a shorter length; for example, the words _catalogue_ and _catamount_ have the 5-character prefixes _catal_ and _catam_, respectively, but share the same 4-character prefix (_cata_). This can lead to queries that use such indexes executing less efficiently on the slave, when a shorter prefix is employed in the slave' definition of the same index than on the master. For *Note `DECIMAL': fixed-point-types. and *Note `NUMERIC': fixed-point-types. columns, both the mantissa (_M_) and the number of decimals (_D_) must be the same size or larger on the slave as compared with the master. For example, replication from a `NUMERIC(5,4)' to a `DECIMAL(6,4)' works, but not from a `NUMERIC(5,4)' to a `DECIMAL(5,3)'. MySQL (except for MySQL Cluster) does _not_ support attribute promotion of any of the following data types to or from any other data type when using row-based replication: * *Note `INT': integer-types. (including `TINYINT', `SMALLINT', `MEDIUMINT', `BIGINT'). Promotion between *Note `INT': integer-types. subtypes--for example, from `SMALLINT' to `BIGINT'--is also not supported. * *Note `SET': set. or *Note `ENUM': enum. * *Note `FLOAT': floating-point-types. or *Note `DOUBLE': floating-point-types. * All of the data types relating to dates, times, or both: *Note `DATE': datetime, *Note `TIME': time, *Note `DATETIME': datetime, *Note `TIMESTAMP': datetime, and *Note `YEAR': year. Attribute promotion and demotion (MySQL Cluster) Beginning with MySQL Cluster NDB 6.3.33, 7.0.14, and 7.1.3, MySQL Cluster 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: This table shows type conversion modes for the `slave_type_conversions' global server variable and describes 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. [_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. 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 *Note `TINYINT': integer-types, *Note `SMALLINT': integer-types, *Note `MEDIUMINT': integer-types, *Note `INT': integer-types, and *Note `BIGINT': integer-types. 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 insuring 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 *Note `DECIMAL': fixed-point-types, *Note `FLOAT': floating-point-types, *Note `DOUBLE': floating-point-types, and *Note `NUMERIC': fixed-point-types. `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 `M' => M' and `D' => 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 *Note precision-math-rounding::, for information about how this is done for decimal types. * Between any of the string types *Note `CHAR': char, *Note `VARCHAR': char, and *Note `TEXT': blob, 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 *Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, and *Note `BLOB': 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 *Note `BIT': bit-type. 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.  File: manual.info, Node: replication-features-directory, Next: replication-features-invoked, Prev: replication-features-differing-tables, Up: replication-features 16.4.1.12 Replication and `DIRECTORY' Table Options ................................................... If a `DATA DIRECTORY' or `INDEX DIRECTORY' table option is used in a *Note `CREATE TABLE': 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 *Note `CREATE TABLE': create-table. statements. The result is that `MyISAM' data and index files are created in the table's database directory. For more information, see *Note server-sql-mode::.  File: manual.info, Node: replication-features-invoked, Next: replication-features-floatvalues, Prev: replication-features-directory, Up: replication-features 16.4.1.13 Replication of Invoked Features ......................................... Replication of invoked features such as user-defined functions (UDFs) and stored programs (stored procedures and functions, triggers, and events) was re-implemented in MySQL 5.1.18 to provide the following characteristics: * The effects of the feature are always replicated. * The following statements are replicated using statement-based replication: * *Note `CREATE EVENT': create-event. * *Note `ALTER EVENT': alter-event. * *Note `DROP EVENT': drop-event. * *Note `CREATE PROCEDURE': create-procedure. * *Note `DROP PROCEDURE': drop-procedure. * *Note `CREATE FUNCTION': create-function. * *Note `DROP FUNCTION': drop-function. * *Note `CREATE TRIGGER': create-trigger. * *Note `DROP 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 may not be safe to log in statement format'. (Prior to MySQL 5.1.36, this was `Statement is not safe to log in statement format'; see Bug #42415.) 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 *Note `CREATE EVENT': create-event. and *Note `ALTER EVENT': 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 *Note `DROP EVENT': drop-event.). * The master on which the event was created is identified on the slave by its server ID. The `ORIGINATOR' column in *Note `INFORMATION_SCHEMA.EVENTS': events-table. and the `originator' column in `mysql.event' were added to these tables in MySQL 5.1.18 to store this information. See *Note events-table::, and *Note 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 *Note `INFORMATION_SCHEMA.EVENTS': events-table. 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 *Note `SHOW EVENTS': 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 *Note `ALTER EVENT EVENT_NAME ENABLED': alter-event, 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 *Note `EVENTS': events-table. 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 *Note `SHOW EVENTS': 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 *Note `ALTER EVENT': 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 *Note `ALTER EVENT': alter-event. statements. You can do this by storing in a separate table the event names from the *Note `SELECT': select. statement shown previously, or using *Note `ALTER EVENT': 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 *Note `EVENTS': events-table. table, as shown here: SELECT CONCAT(EVENT_SCHEMA, '.', EVENT_NAME) AS 'Db.Event' FROM INFORMATION_SCHEMA.EVENTS WHERE INSTR(EVENT_NAME, 'replicated_') = 1;  File: manual.info, Node: replication-features-floatvalues, Next: replication-features-flush, Prev: replication-features-invoked, Up: replication-features 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 *Note type-conversion::, and *Note problems-with-float::.  File: manual.info, Node: replication-features-flush, Next: replication-features-functions, Prev: replication-features-floatvalues, Up: replication-features 16.4.1.15 Replication and `FLUSH' ................................. Some forms of the *Note `FLUSH': flush. statement are not logged because they could cause problems if replicated to a slave: *Note `FLUSH LOGS': flush, *Note `FLUSH MASTER': flush, *Note `FLUSH SLAVE': flush, and *Note `FLUSH TABLES WITH READ LOCK': flush. For a syntax example, see *Note flush::. The *Note `FLUSH TABLES': flush, *Note `ANALYZE TABLE': analyze-table, *Note `OPTIMIZE TABLE': optimize-table, and *Note `REPAIR TABLE': 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 *Note `GRANT': grant, you must issue a *Note `FLUSH PRIVILEGES': flush. on the slaves to put the new privileges into effect. In addition, if you use *Note `FLUSH TABLES': flush. when renaming a `MyISAM' table that is part of a `MERGE' table, you must issue *Note `FLUSH TABLES': flush. manually on the slaves. These statements are written to the binary log unless you specify `NO_WRITE_TO_BINLOG' or its alias `LOCAL'.  File: manual.info, Node: replication-features-functions, Next: replication-features-limit, Prev: replication-features-flush, Up: replication-features 16.4.1.16 Replication and System Functions .......................................... Certain functions do not replicate well under some conditions: * The `USER()', `CURRENT_USER()' (or `CURRENT_USER'), `UUID()', `VERSION()', `LOAD_FILE()', and `RAND()' functions are replicated without change and thus do not work reliably on the slave unless row-based replication is enabled. (See *Note replication-formats::.) For early implementations of mixed-format logging, stored functions, triggers, and views that use these functions in their body do not replicate reliably in mixed-format logging mode because the logging did not switch from statement-based to row-based format. For example, `INSERT INTO t SELECT FROM v', where `v' is a view that selects `UUID()' could cause problems. This limitation is lifted in MySQL 5.1.12. Beginning with MySQL 5.1.23, `USER()' and `CURRENT_USER()' are automatically replicated using row-based replication when using `MIXED' mode, and generate a warning in `STATEMENT' mode. (Bug #28086) (See also *Note replication-features-current-user::.) Beginning with MySQL 5.1.42, `VERSION()' is also automatically replicated using row-based replication when using `MIXED' mode, and generates a warning in `STATEMENT' mode. (Bug #47995) Beginning with MySQL 5.1.43, this is also true with regard to the `RAND()' function. (Bug #49222) * 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. This can lead to a possibly unexpected result when replicating between MySQL servers 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 *Note `INSERT': 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 *Note `CREATE TABLE': create-table. and *Note `INSERT': 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. Beginning with MySQL 5.1.42, `SYSDATE()' is automatically replicated using row-based replication when using `MIXED' mode, and generates a warning in `STATEMENT' mode. (Bug #47995) See also *Note 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(...))'. Beginning with MySQL 5.1.42, these functions are automatically replicated using row-based replication when using `MIXED' mode, and generate a warning in `STATEMENT' mode. (Bug #47995) 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 *Note `INSERT': 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 *Note `INSERT': insert. statement and is available for use in the *Note `INSERT': 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 *Note `INSERT': 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 *Note `SELECT ... INTO': 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. Beginning with MySQL 5.1.23, these functions are automatically replicated using row-based replication when using `MIXED' mode, and generate a warning in `STATEMENT' mode. (Bug #12092, Bug #30244)  File: manual.info, Node: replication-features-limit, Next: replication-features-load-data, Prev: replication-features-functions, Up: replication-features 16.4.1.17 Replication and `LIMIT' ................................. Statement-based replication of `LIMIT' clauses in *Note `DELETE': delete, *Note `UPDATE': update, and *Note `INSERT ... SELECT': 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.) Beginning with MySQL 5.1.24, 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. Currently, 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.  File: manual.info, Node: replication-features-load-data, Next: replication-features-logging, Prev: replication-features-limit, Up: replication-features 16.4.1.18 Replication and `LOAD DATA INFILE' ............................................ The *Note `LOAD DATA INFILE': load-data. statement was not always replicated correctly to a slave running MySQL 5.1.42 or earlier from a master running MySQL 4.0 or earlier. When using statement-based replication, the *Note `LOAD DATA INFILE': load-data. statement `CONCURRENT' option was not replicated. This issue was fixed in MySQL 5.1.43. This issue does not have any impact on `CONCURRENT' option handling when using row-based replication in MySQL 5.1 or later. (Bug #34628) In MySQL 5.1.52 and later, *Note `LOAD DATA INFILE': load-data. is considered unsafe (see *Note replication-rbr-safe-unsafe::). It causes a warning when using statement-based logging format, and is logged using row-based format when using mixed-format logging.  File: manual.info, Node: replication-features-logging, Next: replication-features-repair-table, Prev: replication-features-load-data, Up: replication-features 16.4.1.19 Replication and the Slow Query Log ............................................ Prior to MySQL 5.1.45, replication slaves did not write replicated queries to the slow query log, even if the same queries were written to the slow query log on the master. (Bug #23300)  File: manual.info, Node: replication-features-repair-table, Next: replication-features-shutdowns, Prev: replication-features-logging, Up: replication-features 16.4.1.20 Replication and `REPAIR TABLE' ........................................ When used on a corrupted or otherwise damaged table, it is possible for the *Note `REPAIR TABLE': 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 *Note `REPAIR TABLE': repair-table. to repair it, you should first stop replication (if it is still running) before using *Note `REPAIR TABLE': 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.  File: manual.info, Node: replication-features-shutdowns, Next: replication-features-max-allowed-packet, Prev: replication-features-repair-table, Up: replication-features 16.4.1.21 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 *Note `CHANGE MASTER TO': change-master-to. statement or `--master-connect-retry' option. 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 *Note server-system-variables::. 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 *Note 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. Writes are not forced to disk because 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.  File: manual.info, Node: replication-features-max-allowed-packet, Next: replication-features-memory, Prev: replication-features-shutdowns, Up: replication-features 16.4.1.22 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 *Note `TEXT': blob. or *Note `BLOB': 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. Prior to MySQL 5.1.40, `Last_IO_Error' and `Last_IO_Errno' in the output of *Note `SHOW SLAVE STATUS': show-slave-status. were not set in the event that replication failed due to exceeding `max_allowed_packet' (Bug #42914). 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.  File: manual.info, Node: replication-features-memory, Next: replication-features-temptables, Prev: replication-features-max-allowed-packet, Up: replication-features 16.4.1.23 Replication and `MEMORY' Tables ......................................... When a master server shuts down and restarts, its *Note `MEMORY': memory-storage-engine. tables become empty. To replicate this effect to slaves, the first time that the master uses a given *Note `MEMORY': memory-storage-engine. table after startup, it logs an event that notifies slaves that the table must to be emptied by writing a *Note `DELETE': delete. statement for that table to the binary log. When a slave server shuts down and restarts, its *Note `MEMORY': memory-storage-engine. 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 *Note `INSERT INTO ... SELECT FROM MEMORY_TABLE': insert-select. may insert a different set of rows on the master and slave. The safe way to restart a slave that is replicating *Note `MEMORY': memory-storage-engine. tables is to first drop or delete all rows from the *Note `MEMORY': memory-storage-engine. 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 *Note `MEMORY': memory-storage-engine. tables will still be different from those on the master. This can be okay if the application logic is such that the contents of *Note `MEMORY': memory-storage-engine. tables can be safely lost (for example, if the *Note `MEMORY': memory-storage-engine. tables are used for caching). `slave_exec_mode=IDEMPOTENT' applies globally to all tables, so it may hide other replication errors in non-*Note `MEMORY': memory-storage-engine. tables. The size of *Note `MEMORY': memory-storage-engine. tables is limited by the value of the `max_heap_table_size' system variable, which is not replicated (see *Note replication-features-variables::). A change in `max_heap_table_size' takes effect for `MEMORY' tables that are created or updated using *Note `ALTER TABLE ... ENGINE = MEMORY': alter-table. or *Note `TRUNCATE TABLE': truncate-table. following the change, or for all *Note `MEMORY': memory-storage-engine. 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 *Note memory-storage-engine::, for more information about *Note `MEMORY': memory-storage-engine. tables.  File: manual.info, Node: replication-features-temptables, Next: replication-features-mysqldb, Prev: replication-features-memory, Up: replication-features 16.4.1.24 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 RBR and temporary tables. 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 *Note `SHOW STATUS': 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 *Note `mysqladmin shutdown': mysqladmin. 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. 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.  File: manual.info, Node: replication-features-mysqldb, Next: replication-features-optimizer, Prev: replication-features-temptables, Up: replication-features 16.4.1.25 Replication of the `mysql' System Database .................................................... MySQL 5.1.14 and later 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 statement are replicated using the row-based format. However, statements that would normally update this information indirectly--such *Note `GRANT': grant, *Note `REVOKE': revoke, and statements manipulating triggers, stored routines, and views--are replicated to slaves using statement-based replication. MySQL 5.1.13 and earlier User privileges are replicated only if the `mysql' database is replicated. That is, the *Note `GRANT': grant, *Note `REVOKE': revoke, *Note `SET PASSWORD': set-password, *Note `CREATE USER': create-user, and *Note `DROP USER': drop-user. statements take effect on the slave only if the replication setup includes the `mysql' database.  File: manual.info, Node: replication-features-optimizer, Next: replication-features-reserved-words, Prev: replication-features-mysqldb, Up: replication-features 16.4.1.26 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 *Note `DELETE': delete. or *Note `UPDATE': update. statements that use `LIMIT' with no `ORDER BY' clause; see *Note replication-features-limit::, for a detailed discussion of these.  File: manual.info, Node: replication-features-reserved-words, Next: replication-features-set-password, Prev: replication-features-optimizer, Up: replication-features 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 `current_user' on a 4.0 master that is replicating to a 4.1 or higher slave because `CURRENT_USER' is a reserved word beginning in MySQL 4.1. 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 *Note `ALTER TABLE': 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 *Note identifiers::.  File: manual.info, Node: replication-features-set-password, Next: replication-features-slaveerrors, Prev: replication-features-reserved-words, Up: replication-features 16.4.1.28 `SET PASSWORD' and Row-Based Replication .................................................. Row-based replication of *Note `SET PASSWORD': set-password. statements from a MySQL 5.1 master to a MySQL 5.5 slave did not work correctly prior to MySQL 5.1.53 on the master and MySQL 5.5.7 on the slave (see Bug #57098, Bug #57357).  File: manual.info, Node: replication-features-slaveerrors, Next: replication-features-sql-mode, Prev: replication-features-set-password, Up: replication-features 16.4.1.29 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. *Note `SHOW SLAVE STATUS': show-slave-status. is useful for this. Then fix the problem and run *Note `START SLAVE': start-slave. For example, you might need to create a nonexistent table before you can start the slave again. 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 *Note `INSERT': insert. or *Note `UPDATE': 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.  File: manual.info, Node: replication-features-sql-mode, Next: replication-features-timeout, Prev: replication-features-slaveerrors, Up: replication-features 16.4.1.30 Replication and Server SQL Mode ......................................... Using different server SQL mode settings on the master and the slave may cause the same *Note `INSERT': 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 *Note server-sql-mode::.  File: manual.info, Node: replication-features-timeout, Next: replication-features-timestamp, Prev: replication-features-sql-mode, Up: replication-features 16.4.1.31 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 *Note `NDBCLUSTER': mysql-cluster. `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 *Note `SHOW STATUS': show-status.; see *Note server-status-variables::.  File: manual.info, Node: replication-features-timestamp, Next: replication-features-timezone, Prev: replication-features-timeout, Up: replication-features 16.4.1.32 Replication and `TIMESTAMP' ..................................... Older versions of MySQL (prior to 4.1) differed significantly in several ways in their handling of the *Note `TIMESTAMP': datetime. data type from what is supported in MySQL versions 5.1 and newer; these include syntax extensions which are deprecated in MySQL 5.1, and that no longer supported in MySQL 5.5. This this can cause problems (including replication failures) when replicating between MySQL Server versions, if you are using columns that are defined using the old *Note `TIMESTAMP(N)': datetime. syntax. See *Note upgrading-from-previous-series::, for more information about the differences, how they can impact MySQL replication, and what you can do if you encounter such problems.  File: manual.info, Node: replication-features-timezone, Next: replication-features-transactions, Prev: replication-features-timestamp, Up: replication-features 16.4.1.33 Replication and Time Zones .................................... The same system time zone should be set for 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. You can 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 *Note replication-features-functions::. If the master is MySQL 4.1 or earlier, both master and slave should also use the same default connection time zone. That is, the `--default-time-zone' parameter should have the same value for both master and slave. `CONVERT_TZ(...,...,@@session.time_zone)' is properly replicated only if both master and slave are running MySQL 5.0.4 or newer.  File: manual.info, Node: replication-features-transactions, Next: replication-features-triggers, Prev: replication-features-timezone, Up: replication-features 16.4.1.34 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. As of MySQL 5.1.44, 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 changes both nontransactional and transactional tables is considered `mixed'. Mixed statements, like transactional statements, are cached and logged when the transaction commits. *Note*: A mixed statement is unrelated to mixed binary logging format. Before MySQL 5.1.44, the rules for binary logging are similar to those just described, except that there is no `binlog_direct_non_transactional_updates' system variable to affect logging of transactional statements. Thus, the server immediately logs only the initial nontransactional statements in a transaction and caches the rest until commit time. Before MySQL 5.1.31, the _effect_ of the rules differs because the definition of transactional statement is different: In these earlier versions, a statement is nontransactional if the first changes it makes change nontransactional tables, transactional if the first changes it makes change transactional tables. `First' applies in the sense that a statement may have several effects if it involves such things as triggers, stored functions, or multiple-table updates. A mixed statement that changes both nontransactional and transactional tables is handled as nontransactional or transactional depending on the type of changes it makes first. 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 *Note `ROLLBACK': commit. 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 *Note `BEGIN': commit ... *Note `COMMIT': commit. block because the slave restarts at the beginning of the *Note `BEGIN': commit. block. Beginning with MySQL 5.1.48, it is also safe to replicate transactions from *Note `MyISAM': myisam-storage-engine. tables on the master to transactional tables--such as tables that use the *Note `InnoDB': innodb-storage-engine. storage engine--on the slave. In such cases (beginning with MySQL 5.1.48), 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. Beginning with MySQL Cluster NDB 6.2.14 and MySQL 5.1.24, every transaction (including `autocommit' transactions) is recorded in the binary log as though it starts with a *Note `BEGIN': commit. statement, and ends with either a *Note `COMMIT': commit. or a *Note `ROLLBACK': commit. statement. However, this does _not_ apply to nontransactional changes; any statements affecting tables using a nontransactional storage engine such as *Note `MyISAM': myisam-storage-engine. are regarded for this purpose as nontransactional, even when `autocommit' is enabled. (Bug #26395)  File: manual.info, Node: replication-features-triggers, Next: replication-features-truncate, Prev: replication-features-transactions, Up: replication-features 16.4.1.35 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. Before MySQL 5.1.31, a trigger that was defined on a transactional table but that updated a nontransactional table could cause updates on the transactional table to be replicated before they were actually committed on the master, and not be rolled back correctly on the slave if they were rolled back on the master. (Bug #40116) See also *Note replication-features-transactions::. A statement invoking a trigger (or function) that causes an update to an `AUTO_INCREMENT' column is not replicated correctly using statement-based replication. Beginning with MySQL 5.1.40, such statements are marked as unsafe. (Bug #45677)  File: manual.info, Node: replication-features-truncate, Next: replication-features-variables, Prev: replication-features-triggers, Up: replication-features 16.4.1.36 Replication and `TRUNCATE TABLE' .......................................... *Note `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 *Note `InnoDB': innodb-storage-engine. when the transaction isolation level was `READ COMMITTED' or `READ UNCOMMITTED', which precludes statement-based logging. Beginning with MySQL 5.1.32, *Note `TRUNCATE TABLE': 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 *Note `InnoDB': innodb-storage-engine. and other transactional tables on replication slaves still follow the rules described in *Note truncate-table:: governing such tables. (Bug #36763)  File: manual.info, Node: replication-features-variables, Next: replication-features-views, Prev: replication-features-truncate, Up: replication-features 16.4.1.37 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 *Note 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 *Note `mysqlbinlog': 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 `storage_engine' system variable is 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 *Note `SET PASSWORD': 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 *Note `INSERT': insert. statements on a *Note `MEMORY': memory-storage-engine. table on the master that is thus permitted to grow larger than its counterpart on the slave. For more information, see *Note 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 *Note replication-formats::. In MySQL 5.1.20 and later (and in MySQL 5.0.46 and later in MySQL 5.0, for backward compatibility), 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. It is strongly recommended that you always use the same setting for the `lower_case_table_names' system variable on both master and slave. In particular, when a case-sensitive file system is used, setting this variable to 1 on the slave, but to a different value on the master, can cause two types of problems: Names of databases are not converted to lowercase; in addition, when using row-based replication names of tables are also not converted. Either of these problems can cause replication to fail. This is a known issue, which is fixed in MySQL 5.6.  File: manual.info, Node: replication-features-views, Prev: replication-features-variables, Up: replication-features 16.4.1.38 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 samed-named view is supported using statement-based logging, but not when using row-based logging. In MySQL 5.1.69 and later, trying to do so when row-based logging is in effect causes an error. (Bug #11752707, Bug #43975)  File: manual.info, Node: replication-compatibility, Next: replication-upgrade, Prev: replication-features, Up: replication-notes 16.4.2 Replication Compatibility Between MySQL Versions ------------------------------------------------------- MySQL supports replication from one major version to the next higher major version. For example, you can replicate from a master running MySQL 4.1 to a slave running MySQL 5.0, from a master running MySQL 5.0 to a slave running MySQL 5.1, and so on. However, one 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. The use of more than 2 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 major versions, but to minor versions within the same major version as well. For example, if you are using a chained or circular replication setup, you cannot use MySQL 5.1.31, MySQL 5.1.32, and MySQL 5.1.34 concurrently, although you could use any 2 of these releases together. In some cases, it is also possible to replicate between a master and a slave that is more than one major version newer than the master. However, there are known issues with trying to replicate from a master running MySQL 4.1 or earlier to a slave running MySQL 5.1 or later. To work around such problems, you can insert a MySQL server running an intermediate version between the two; for example, rather than replicating directly from a MySQL 4.1 master to a MySQL 5.1 slave, it is possible to replicate from a MySQL 4.1 server to a MySQL 5.0 server, and then from the MySQL 5.0 server to a MySQL 5.1 server. *Important*: It is strongly recommended to use the most recent release available within a given MySQL major version because replication (and other) capabilities are continually being improved. It is also recommended to upgrade masters and slaves that use early releases of a major version of MySQL to GA (production) releases when the latter become available for that major version. 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. For example, the binary log format implemented in MySQL 5.0 changed considerably from that used in previous versions, especially with regard to handling of character sets, *Note `LOAD DATA INFILE': load-data, and time zones. This means that replication from a MySQL 5.0 (or later) master to a MySQL 4.1 (or earlier) slave is generally not supported. This also has significant implications for upgrading replication servers; see *Note replication-upgrade::, for more information. * Use of row-based replication Row-based replication was implemented in MySQL 5.1.5, so you cannot replicate using row-based replication from any MySQL 5.1 or later master to a slave older than MySQL 5.1.5. For more information about row-based replication, see *Note 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 *Note replication-features::.  File: manual.info, Node: replication-upgrade, Next: replication-problems, Prev: replication-compatibility, Up: replication-notes 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 applies to upgrading replication from older versions of MySQL to MySQL 5.1. A 4.0 server should be 4.0.3 or newer. When you upgrade a master to 5.1 from an earlier MySQL release series, you should first ensure that all the slaves of this master are using the same 5.1.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.1.x version, restart it, and restart replication. The 5.1 slave is able to read the old relay logs written prior to the upgrade and to execute the statements they contain. Relay logs created by the slave after the upgrade are in 5.1 format. After the slaves have been upgraded, shut down the master, upgrade it to the same 5.1.x release as the slaves, and restart it. The 5.1 master is able to read the old binary logs written prior to the upgrade and to send them to the 5.1 slaves. The slaves recognize the old format and handle it properly. Binary logs created by the master subsequent to the upgrade are in 5.1 format. These too are recognized by the 5.1 slaves. In other words, when upgrading to MySQL 5.1, the slaves must be MySQL 5.1 before you can upgrade the master to 5.1. Note that downgrading from 5.1 to older versions does not work so simply: You must ensure that any 5.1 binary log or relay log has been fully processed, so that you can remove it before proceeding with the downgrade. Downgrading a replication setup to a previous version cannot be done once you have switched from statement-based to row-based replication, and after the first row-based statement has been written to the binlog. See *Note replication-formats::. 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, will be detailed at *Note 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.  File: manual.info, Node: replication-problems, Next: replication-bugs, Prev: replication-upgrade, Up: replication-notes 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 *Note `SHOW MASTER STATUS': 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 *Note `SHOW SLAVE STATUS': 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 *Note `START SLAVE': start-slave. statement. * If the slave is running, check whether it established a connection to the master. Use *Note `SHOW PROCESSLIST': show-processlist, find the I/O and SQL threads and check their `State' column to see what they display. See *Note 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 *Note replication-features::. If it is a bug, see *Note 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 *Note `START SLAVE': 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 *Note 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.  File: manual.info, Node: replication-bugs, Prev: replication-problems, Up: replication-notes 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 *Note 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 *Note `SHOW MASTER STATUS': show-master-status. from the master at the time you discovered the problem * The output of *Note `SHOW SLAVE STATUS': show-slave-status. from the slave at the time you discovered the problem * Error logs from the master and the slave 4. Use *Note `mysqlbinlog': 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 *Note `SHOW SLAVE STATUS': 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 *Note bug-reports::.  File: manual.info, Node: mysql-cluster, Next: partitioning, Prev: replication, Up: Top 17 MySQL Cluster NDB 6.1 - 7.1 ****************************** * Menu: * mysql-cluster-overview:: MySQL Cluster Overview * mysql-cluster-installation:: MySQL Cluster Installation and Upgrades * mysql-cluster-configuration:: Configuration of MySQL Cluster NDB 6.1-7.1 * mysql-cluster-programs:: MySQL Cluster Programs * mysql-cluster-management:: Management of MySQL Cluster * mysql-cluster-replication:: MySQL Cluster Replication * mysql-cluster-news:: MySQL Cluster NDB 6.1 - 7.1 Release Notes This chapter contains information about _MySQL Cluster_, which is a high-availability, high-redundancy version of MySQL adapted for the distributed computing environment. Current releases of MySQL Cluster use versions 6 and 7 of the *Note `NDB': mysql-cluster. storage engine (also known as *Note `NDBCLUSTER': mysql-cluster.) to enable running several computers with MySQL servers and other software in a cluster. Beginning with MySQL 5.1.24, support for the *Note `NDBCLUSTER': mysql-cluster. storage engine was removed from the standard MySQL server binaries built by MySQL. Instead, users of MySQL Cluster binaries built by MySQL should upgrade to the most recent binary release of MySQL Cluster NDB 7.0 or MySQL Cluster 7.1 for supported platforms--these include RPMs that should work with most Linux distributions. MySQL Cluster users who build from source should be aware that, also beginning with MySQL 5.1.24, *Note `NDBCLUSTER': mysql-cluster. sources in the standard MySQL 5.1 tree are no longer maintained; these users should use the sources provided for MySQL Cluster NDB 7.0 or later. (Locations where the sources can be obtained are listed later in this section.) *Note*: MySQL Cluster NDB 6.1, 6.2, and 6.3 were formerly known as `MySQL Cluster Carrier Grade Edition'. Beginning with MySQL Cluster NDB 6.2.15 and MySQL Cluster NDB 6.3.14, this term is no longer applied to the MySQL Cluster software--which is now known simply as `MySQL Cluster'--but rather to a commercial licensing and support package. You can learn more about available options for commercial licensing of MySQL Cluster from http://mysql.com/products/database/cluster/features.html, on the MySQL web site. This chapter contains information about MySQL Cluster in MySQL 5.1 mainline releases through MySQL 5.1.23, MySQL Cluster NDB 6.2 releases through 5.1.51-ndb-6.2.19, MySQL Cluster NDB 6.3 releases through 5.1.71-ndb-6.3.53, MySQL Cluster NDB 7.0 releases through 5.1.71-ndb-7.0.40 and MySQL Cluster NDB 7.1 releases through 5.1.71-ndb-7.1.29. Currently, the MySQL Cluster NDB 7.2 release series is Generally Available (GA), as is MySQL Cluster NDB 7.1. MySQL Cluster NDB 7.0 and MySQL Cluster NDB 6.3 are previous GA release series; although they are still supported, we recommend that new deployments use MySQL Cluster NDB 7.2. For information about MySQL Cluster NDB 7.2, see MySQL Cluster NDB 7.2 (http://dev.mysql.com/doc/refman/5.5/en/mysql-cluster.html), in the `MySQL 5.5 Manual'. This chapter also contains historical information about MySQL Cluster NDB 6.1 and MySQL Cluster NDB 6,2, although these release series are no longer in active development, and no longer supported for new deployments. You should upgrade to a MySQL Cluster NDB 7.1 or later release series as soon as possible. Release notes for the changes in each release of MySQL Cluster are located at MySQL Cluster 7.1 Release Notes (http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/). Supported Platforms MySQL 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 MySQL Cluster binary and source packages are available for supported platforms from `http://dev.mysql.com/downloads/cluster/'. *Note*: Binary releases and RPMs were not available for MySQL Cluster NDB 6.2 prior to MySQL Cluster NDB 6.2.15. MySQL Cluster release numbers Starting with MySQL Cluster NDB 6.1 and MySQL Cluster NDB 6.2, MySQL Cluster follows a somewhat different release pattern from the mainline MySQL 5.1 Cluster series of releases. In this `Manual' and other MySQL documentation, we identify these and later MySQL Cluster releases employing a version number that begins with `NDB'. This version number is that of the *Note `NDBCLUSTER': mysql-cluster. storage engine used in the release, and not of the MySQL server version on which the MySQL Cluster release is based. Version strings used in MySQL Cluster NDB 6.x and 7.x software The version string displayed by MySQL Cluster NDB 6.x and 7.x software uses this format: mysql-MYSQL_SERVER_VERSION-ndb-NDB_ENGINE_VERSION MYSQL_SERVER_VERSION represents the version of the MySQL Server on which the MySQL Cluster release is based. For all MySQL Cluster NDB 6.x and 7.x releases, this is `5.1'. NDB_ENGINE_VERSION is the version of the *Note `NDB': mysql-cluster. storage engine used by this release of the MySQL Cluster software. You can see this format used in the *Note `mysql': 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.1.71-ndb-7.1.29 Source distribution Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> SELECT VERSION()\G *************************** 1. row *************************** VERSION(): 5.1.71-ndb-7.1.29 1 row in set (0.00 sec) This version string is also displayed in the output of the `SHOW' command in the *Note `ndb_mgm': mysql-cluster-programs-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.1.71-ndb-7.1.29, Nodegroup: 0, Master) id=2 @10.0.10.8 (5.1.71-ndb-7.1.29, Nodegroup: 0) [ndb_mgmd(MGM)] 1 node(s) id=3 @10.0.10.2 (5.1.71-ndb-7.1.29) [mysqld(API)] 2 node(s) id=4 @10.0.10.10 (5.1.71-ndb-7.1.29) id=5 (not connected, accepting connect from any host) The version string identifies the mainline MySQL version from which the MySQL Cluster release was branched and the version of the *Note `NDBCLUSTER': mysql-cluster. storage engine used. For example, the full version string for MySQL Cluster NDB 7.0.5 (the first GA MySQL Cluster NDB 7.0 binary release) was `mysql-5.1.32-ndb-7.0.5'. 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 MySQL Cluster NDB 7.0.5 derives from the MySQL 5.1.32, and contains all feature enhancements and bugfixes from MySQL 5.1 up to and including MySQL 5.1.32. * Since the portion of the version string following ``-ndb-'' represents the version number of the *Note `NDB': mysql-cluster. (or *Note `NDBCLUSTER': mysql-cluster.) storage engine, MySQL Cluster NDB 7.0.5 uses version 7.0.5 of the *Note `NDBCLUSTER': mysql-cluster. storage engine. New MySQL Cluster releases are numbered according to updates in the `NDB' storage engine, and do not necessarily correspond in a linear fashion with mainline MySQL Server releases. For example, MySQL Cluster NDB 7.0.5 (as previously noted) is based on MySQL 5.1.32, and MySQL Cluster NDB 7.0.6 is based on MySQL 5.1.34 (version string: `mysql-5.1.34-ndb-7.0.6'). Compatibility with standard MySQL 5.1 releases While many standard MySQL schemas and applications can work using MySQL Cluster, it is also true that unmodified applications and database schemas may be slightly incompatible or have suboptimal performance when run using MySQL Cluster (see *Note 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, *Note `MyISAM': myisam-storage-engine. or *Note `InnoDB': innodb-storage-engine.--to use the *Note `NDB': mysql-cluster. storage engine without allowing for the possibility of changes in schemas, queries, and applications. Moreover, from MySQL 5.1.24 onwards, the MySQL Server and MySQL Cluster codebases diverge considerably (and *Note `NDB': mysql-cluster. storage engine support dropped from subsequent MySQL Server releases), so that the standard *Note `mysqld': mysqld. cannot function as a dropin replacement for the version of *Note `mysqld': mysqld. that is supplied with MySQL Cluster. MySQL Cluster development source trees MySQL Cluster development trees can also be accessed from `https://code.launchpad.net/~mysql/': The MySQL Cluster development sources maintained at `https://code.launchpad.net/~mysql/' are licensed under the GPL. For information about obtaining MySQL sources using Bazaar and building them yourself, see *Note installing-development-tree::. Currently, MySQL Cluster NDB 7.0, MySQL Cluster NDB 7.1, and MySQL Cluster NDB 7.2 releases are all Generally Available (GA), although we recommend that new deployments use MySQL Cluster NDB 7.2. MySQL Cluster NDB 6.1, MySQL Cluster NDB 6.2, and MySQL Cluster NDB 6.3, are no longer in active development. For an overview of major features added in MySQL Cluster NDB 6.x and 7.x releases, see *Note mysql-cluster-development::. For an overview of major features added in MySQL Cluster NDB 7.2, see MySQL Cluster Development History (http://dev.mysql.com/doc/refman/5.5/en/mysql-cluster-development.html). This chapter represents a work in progress, and its contents are subject to revision as MySQL Cluster continues to evolve. Additional information regarding MySQL Cluster can be found on the MySQL Web site at http://www.mysql.com/products/cluster/. Additional Resources More information about MySQL Cluster can be found in the following places: * For answers to some commonly asked questions about MySQL Cluster, see *Note faqs-mysql-cluster::. * The MySQL Cluster mailing list: `http://lists.mysql.com/cluster'. * The MySQL Cluster Forum: `http://forums.mysql.com/list.php?25'. * Many MySQL Cluster users and developers blog about their experiences with MySQL Cluster, and make feeds of these available through PlanetMySQL (http://www.planetmysql.org/).  File: manual.info, Node: mysql-cluster-overview, Next: mysql-cluster-installation, Prev: mysql-cluster, Up: mysql-cluster 17.1 MySQL Cluster Overview =========================== * Menu: * mysql-cluster-basics:: MySQL Cluster Core Concepts * mysql-cluster-nodes-groups:: MySQL Cluster Nodes, Node Groups, Replicas, and Partitions * mysql-cluster-overview-requirements:: MySQL Cluster Hardware, Software, and Networking Requirements * mysql-cluster-development:: MySQL Cluster Development History * mysql-cluster-compared:: MySQL Server Using `InnoDB' Compared with MySQL Cluster * mysql-cluster-limitations:: Known Limitations of MySQL Cluster _MySQL 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. MySQL 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. MySQL Cluster integrates the standard MySQL server with an in-memory clustered storage engine called *Note `NDB': mysql-cluster. (which stands for `_N_etwork _D_ata_B_ase'). In our documentation, the term *Note `NDB': mysql-cluster. refers to the part of the setup that is specific to the storage engine, whereas `MySQL Cluster' refers to the combination of one or more MySQL servers with the *Note `NDB': mysql-cluster. storage engine. A MySQL 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 a MySQL Cluster is shown here: MySQL Cluster Components All these programs work together to form a MySQL Cluster (see *Note mysql-cluster-programs::. When data is stored by the *Note `NDB': mysql-cluster. 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 a MySQL Cluster SQL node uses the *Note `mysqld': mysqld. server daemon, it differs in a number of critical respects from the *Note `mysqld': mysqld. binary supplied with the MySQL 5.1 distributions, and the two versions of *Note `mysqld': mysqld. are not interchangeable. In addition, a MySQL server that is not connected to a MySQL Cluster cannot use the *Note `NDB': mysql-cluster. storage engine and cannot access any MySQL Cluster data. The data stored in the data nodes for MySQL 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 *Note mysql-cluster-rolling-restart::). In MySQL Cluster NDB 7.0 and later, rolling restarts are also used as part of the process of adding new data nodes online (see *Note mysql-cluster-online-add-node::). For more information about data nodes, how they are organized in a MySQL Cluster, and how they handle and store MySQL Cluster data, see *Note mysql-cluster-nodes-groups::. Backing up and restoring MySQL Cluster databases can be done using the `NDB'-native functionality found in the MySQL Cluster management client and the *Note `ndb_restore': mysql-cluster-programs-ndb-restore. program included in the MySQL Cluster distribution. For more information, see *Note mysql-cluster-backup::, and *Note mysql-cluster-programs-ndb-restore::. You can also use the standard MySQL functionality provided for this purpose in *Note `mysqldump': mysqldump. and the MySQL server. See *Note mysqldump::, for more information. MySQL Cluster nodes can use a number of different transport mechanisms for inter-node communications, including TCP/IP using standard 100 Mbps or faster Ethernet hardware. It is also possible to use the high-speed _Scalable Coherent Interface_ (SCI) protocol with MySQL Cluster, although this is not required to use MySQL Cluster. SCI requires special hardware and software; see *Note mysql-cluster-interconnects::, for more about SCI and using it with MySQL Cluster.  File: manual.info, Node: mysql-cluster-basics, Next: mysql-cluster-nodes-groups, Prev: mysql-cluster-overview, Up: mysql-cluster-overview 17.1.1 MySQL Cluster Core Concepts ---------------------------------- _*Note `NDBCLUSTER': mysql-cluster._ (also known as *Note `NDB': mysql-cluster.) is an in-memory storage engine offering high-availability and data-persistence features. The *Note `NDBCLUSTER': mysql-cluster. 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. MySQL Cluster's *Note `NDB': mysql-cluster. storage engine contains a complete set of data, dependent only on other data within the cluster itself. The `Cluster' portion of MySQL Cluster is configured independently of the MySQL servers. In a MySQL 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 MySQL 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 MySQL 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 MySQL Cluster, performing such functions as providing configuration data, starting and stopping nodes, running backup, and so forth. 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 *Note `ndb_mgmd': mysql-cluster-programs-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 *Note 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 *Note `ndbd': mysql-cluster-programs-ndbd. (see *Note mysql-cluster-programs-ndbd::). In MySQL Cluster NDB 7.0 and later, *Note `ndbmtd': mysql-cluster-programs-ndbmtd. can also be used for the data node process; see *Note mysql-cluster-programs-ndbmtd::, for more information. MySQL Cluster tables are normally stored completely in memory rather than on disk (this is why we refer to MySQL Cluster as an _in-memory_ database). In MySQL 5.1, MySQL Cluster NDB 6.X, and later, some MySQL Cluster data can be stored on disk; see *Note mysql-cluster-disk-data::, for more information. * _SQL node_: This is a node that accesses the cluster data. In the case of MySQL Cluster, an SQL node is a traditional MySQL server that uses the *Note `NDBCLUSTER': mysql-cluster. storage engine. An SQL node is a *Note `mysqld': 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 MySQL Cluster data. Another example of an API node is the *Note `ndb_restore': mysql-cluster-programs-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 MySQL 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 MySQL Cluster, see *Note mysql-cluster-nodes-groups::. Configuration of a cluster involves configuring each individual node in the cluster and setting up individual communication links between nodes. MySQL 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 MySQL 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 MySQL Cluster SQL nodes in much the same way that they interact with standalone MySQL servers. MySQL clients using a MySQL 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 MySQL Cluster, see Using Connector/J with MySQL Cluster (http://dev.mysql.com/doc/ndbapi/en/mccj-using-connectorj.html). `NDB' client programs Client programs can be written that access MySQL Cluster data directly from the `NDBCLUSTER' storage engine, bypassing any MySQL Servers that may 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). Beginning with MySQL Cluster NDB 7.1, `NDB'-specific Java applications can also be written for MySQL Cluster, using the _MySQL Cluster Connector for Java_. This MySQL 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 MySQL Cluster NDB 7.1 and later for _ClusterJPA_, an OpenJPA implementation for MySQL 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 MySQL 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. 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. management client supplied with MySQL Cluster (see *Note 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 MySQL 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 MySQL Cluster management tasks, such restarting a MySQL 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 *Note `mysqld': mysqld. server options and variables relating to MySQL Cluster. MySQL Cluster Manager 1.1 provides support for adding data nodes online. See the MySQL Cluster Manager User Manual (http://dev.mysql.com/doc/mysql-cluster-manager/1.1/en/index.html), for more information. Event logs MySQL 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 *Note 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 MySQL Cluster, a checkpoint is a point in time where all committed transactions are stored on disk. With regard to the *Note `NDB': mysql-cluster. 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 involves saving all of a node's data to disk, and so 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. * _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 MySQL Cluster Data Node `FileSystemDir' Files (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-ndbd-filesystemdir-files.html).  File: manual.info, Node: mysql-cluster-nodes-groups, Next: mysql-cluster-overview-requirements, Prev: mysql-cluster-basics, Up: mysql-cluster-overview 17.1.2 MySQL Cluster Nodes, Node Groups, Replicas, and Partitions ----------------------------------------------------------------- This section discusses the manner in which MySQL 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 *Note `ndbd': mysql-cluster-programs-ndbd. process, which stores a _replica_ --that is, a copy of the _partition_ (see below) 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 *Note `ndbd': mysql-cluster-programs-ndbd. processes on a single computer, such a configuration is not supported. It is common for the terms `node' and `data node' to be used interchangeably when referring to an *Note `ndbd': mysql-cluster-programs-ndbd. process; where mentioned, management nodes (*Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. processes) and SQL nodes (*Note `mysqld': 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 a MySQL 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: [NUMBER_OF_NODE_GROUPS] = NUMBER_OF_DATA_NODES / `NoOfReplicas' Thus, a MySQL 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 *Note mysql-cluster-ndbd-definition::. *Note*: All node groups in a MySQL Cluster must have the same number of data nodes. Prior to MySQL Cluster NDB 7.0, it was not possible to add new data nodes to a MySQL Cluster without shutting down the cluster completely and reloading all of its data. In MySQL Cluster NDB 7.0 (beginning with MySQL Cluster version NDB 6.4.0), you can add new node groups (and thus new data nodes) to a running MySQL Cluster--see *Note mysql-cluster-online-add-node::, for information about how this can be done. Partition This is a portion of the data stored by the cluster. There are as many cluster partitions as nodes participating in 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. A replica belongs entirely to a single node; a node can (and usually does) store several replicas. `NDB' and user-defined partitioning MySQL Cluster normally partitions *Note `NDBCLUSTER': mysql-cluster. tables automatically. However, in MySQL 5.1 and later MySQL Cluster releases, it is possible to employ user-defined partitioning with *Note `NDBCLUSTER': mysql-cluster. tables. This is subject to the following limitations: 1. Only `KEY' and `LINEAR KEY' partitioning schemes can be used with *Note `NDBCLUSTER': mysql-cluster. tables. 2. When using *Note `ndbd': mysql-cluster-programs-ndbd, the maximum number of partitions that may be defined explicitly for any *Note `NDBCLUSTER': mysql-cluster. table is `8 * [NUMBER OF NODE GROUPS]'. (The number of node groups in a MySQL Cluster is determined as discussed previously in this section.) When using *Note `ndbmtd': mysql-cluster-programs-ndbmtd, this maximum is also affected by the number of local query handler threads, which is determined by the value of the `MaxNoOfExecutionThreads' configuration parameter. In such cases, the maxmimum number of partitions that may be defined explicitly for an *Note `NDB': mysql-cluster. table is equal to `4 * MaxNoOfExecutionThreads * [NUMBER OF NODE GROUPS]'. See *Note mysql-cluster-programs-ndbmtd::, for more information. For more information relating to MySQL Cluster and user-defined partitioning, see *Note mysql-cluster-limitations::, and *Note 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. The following diagram illustrates a MySQL Cluster with four data nodes, 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 that only data (*Note `ndbd': mysql-cluster-programs-ndbd.) nodes are shown here; although a working cluster requires an *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. process for cluster management and at least one SQL node to access the data stored by the cluster, these have been omitted in the figure for clarity. A MySQL Cluster, with 2 node groups having 2 nodes each 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 a MySQL 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. Nodes required to keep a 2x2 cluster viable In this example, where the cluster consists of two node groups of two nodes each, any combination of at least one node in node group 0 and at least one node in node group 1 is sufficient to keep the cluster `alive' (indicated by arrows in the diagram). However, if _both_ nodes from _either_ node group fail, the remaining two nodes are not sufficient (shown by the arrows marked out with an *X*); in either case, the cluster has lost an entire partition and so can no longer provide access to a complete set of all cluster data.  File: manual.info, Node: mysql-cluster-overview-requirements, Next: mysql-cluster-development, Prev: mysql-cluster-nodes-groups, Up: mysql-cluster-overview 17.1.3 MySQL Cluster Hardware, Software, and Networking Requirements -------------------------------------------------------------------- One of the strengths of MySQL 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 *Note mysql-cluster-disk-data::, for more information about these.) Naturally, multiple and faster CPUs can enhance performance. Memory requirements for other MySQL Cluster processes are relatively small. The software requirements for MySQL Cluster are also modest. Host operating systems do not require any unusual modules, services, applications, or configuration to support MySQL 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 MySQL Cluster. It is not strictly necessary to compile MySQL yourself merely to be able to use MySQL Cluster. We assume that you are using the binaries appropriate to your platform, available from the MySQL Cluster software downloads page at `http://dev.mysql.com/downloads/cluster/'. For communication between nodes, MySQL 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 a MySQL 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 MySQL Cluster nodes are not encrypted or shielded in any way. The only means of protecting transmissions within a MySQL Cluster is to run your MySQL Cluster on a protected network. If you intend to use MySQL 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 *Note mysql-cluster-security-networking-issues::, for more information. * Efficiency Setting up a MySQL 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 MySQL Cluster not only helps protect against unauthorized access to MySQL Cluster data, it also ensures that MySQL 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 MySQL 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, MySQL 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, a MySQL 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 MySQL 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 MySQL 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 MySQL Cluster, but this is not a requirement. See *Note mysql-cluster-interconnects::, for more about this protocol and its use with MySQL Cluster.  File: manual.info, Node: mysql-cluster-development, Next: mysql-cluster-compared, Prev: mysql-cluster-overview-requirements, Up: mysql-cluster-overview 17.1.4 MySQL Cluster Development History ---------------------------------------- * Menu: * mysql-cluster-development-5-1-ndb-7-2:: MySQL Cluster Development in MySQL Cluster NDB 7.2.0 * mysql-cluster-development-5-1-ndb-7-1:: MySQL Cluster Development in MySQL Cluster NDB 7.1 * mysql-cluster-development-5-1-ndb-7-0:: MySQL Cluster Development in MySQL Cluster NDB 7.0 * mysql-cluster-development-5-1-ndb-6-3:: MySQL Cluster Development in MySQL Cluster NDB 6.3 * mysql-cluster-development-5-1-ndb-6-2:: MySQL Cluster Development in MySQL Cluster NDB 6.2 * mysql-cluster-development-5-1-ndb-6-1:: MySQL Cluster Development in MySQL Cluster NDB 6.1 * mysql-cluster-development-5-1:: Development History of MySQL Cluster in MySQL 5.1 In this section, we discuss changes in the implementation of MySQL Cluster in MySQL 5.1, MySQL Cluster NDB 6.x, and MySQL Cluster NDB 7.x, as compared to earlier MySQL Cluster releases. There are a number of significant changes in the implementation of the *Note `NDBCLUSTER': mysql-cluster. storage engine in mainline MySQL 5.1 releases up to and including MySQL 5.1.23 as compared to that in MySQL 5.0; MySQL Cluster NDB 6.x and 7.x make further changes and improvements in MySQL Cluster in addition to these. The changes and features most likely to be of interest are shown in the following tables: This table lists changes and features in MySQL Cluster NDB 7.2 that are most likely to be of interest. *Note MySQL Cluster NDB 7.2: mysql-cluster-development-5-1-ndb-7-2. Distribution of MySQL users and privileges across MySQL Cluster SQL nodes Distributed pushed-down joins, with greatly improved performance for many joins that can thus be pushed down and executed in parallel on the data nodes. Improved default values for data node configuration parameters. This table lists changes and features in MySQL Cluster NDB 7.1 that are most likely to be of interest. *Note MySQL Cluster NDB 7.1: mysql-cluster-development-5-1-ndb-7-1. Production-level support for MySQL Cluster on Microsoft Windows platforms. *Note `ndbinfo': mysql-cluster-ndbinfo. meta-information database MySQL Cluster Connector for Java, including ClusterJ and OpenJPA (ClusterJPA) support Native support for default column values This table lists changes and features in MySQL Cluster NDB 7.0 that are most likely to be of interest. *Note MySQL Cluster NDB 7.0: mysql-cluster-development-5-1-ndb-7-0. Multi-threaded data nodes (*Note `ndbmtd': mysql-cluster-programs-ndbmtd. data node daemon) Online addition of data nodes; online data redistribution MySQL on Windows (alpha; source releases only) Configuration cache Backup snapshots (`START BACKUP ... SNAPSHOTSTART', `START BACKUP ... SNAPSHOTEND' commands) IPv6 support for geo-replication Protected DDL operations Dynamic buffering for NDB transporters Increased flexibility in determining arbitration handling, using a new `Arbitration' data node configuration parameter NDB API counters and associated status variables, which make it possible to observe the API-level effects of SQL statements on *Note `NDB': mysql-cluster. tables from the *Note `mysql': mysql. client. This table lists changes and features in MySQL Cluster NDB 6.3 that are most likely to be of interest. *Note MySQL Cluster NDB 6.3: mysql-cluster-development-5-1-ndb-6-3. Conflict detection and resolution for multi-master replication Compressed backups and local checkpoints Support for *Note `OPTIMIZE TABLE': optimize-table. Parallel data node recovery Enhanced transaction coordinator selection Improved SQL statement performance metrics Transaction batching *Note `ndb_restore': mysql-cluster-programs-ndb-restore. attribute promotion Support for `epoll' (Linux only) Distribution awareness *Note `NDB': mysql-cluster. thread locks; realtime extensions for multiple CPUs This table lists changes and features in MySQL Cluster NDB 6.2 that are most likely to be of interest. *Note MySQL Cluster NDB 6.2: mysql-cluster-development-5-1-ndb-6-2. Improved backup status reporting (`BackupReportFrequency', `REPORT BackupStatus') Multiple connections per SQL node Data access with `NdbRecord' (NDB API) `REPORT MemoryUsage' command Memory allocation improvements Management client connection control Micro-GCPs Online `ADD COLUMN'; improved online index creation This table lists changes and features in MySQL Cluster NDB 6.1 that are most likely to be of interest. *Note MySQL Cluster NDB 6.1: mysql-cluster-development-5-1-ndb-6-1. Greater number of cluster nodes Disabling of arbitration Additional `DUMP' commands Faster Disk Data backups Batched slave updates This table lists changes and features in MySQL Cluster NDB 5.1 through to 5.1.23 that are most likely to be of interest. *Note MySQL 5.1 (through 5.1.23): mysql-cluster-development-5-1. MySQL Cluster Replication Disk Data storage Variable-size columns User-defined partitioning Autodiscovery of table schema changes Online adding and dropping of indexes  File: manual.info, Node: mysql-cluster-development-5-1-ndb-7-2, Next: mysql-cluster-development-5-1-ndb-7-1, Prev: mysql-cluster-development, Up: mysql-cluster-development 17.1.4.1 MySQL Cluster Development in MySQL Cluster NDB 7.2.0 ............................................................. The following improvements to MySQL Cluster were made in MySQL Cluster NDB 7.2.0. * Distribution of MySQL users and privileges Automatic distribution of MySQL users and privileges across all SQL nodes in a given MySQL Cluster is now supported. To enable this support, you must first import an SQL script `share/mysql/ndb_dist_priv.sql' that is included with the MySQL Cluster NDB 7.2 distribution. This script creates several stored procedures which you can use to enable privilege distribution and perform related tasks. When a new MySQL Server joins a MySQL Cluster where privilege distribution is in effect, it also participates in the privilege distribution automatically. Once privilege distribution is enabled, all changes to the grant tables made on any *Note `mysqld': mysqld. attached to the cluster are immediately available on any other attached MySQL Servers. This is true whether the changes are made using *Note `CREATE USER': create-user, *Note `GRANT': grant, or any of the other statements described elsewhere in this Manual (see *Note account-management-sql::.) This includes privileges relating to stored routines and views; however, automatic distribution of the views or stored routines themselves is not currently supported. For more information, see *Note mysql-cluster-privilege-distribution::. * Distributed pushed-down joins Many joins can now be pushed down to the NDB kernel for processing on MySQL Cluster data nodes. Previously, a join was handled in MySQL Cluster by means of repeated accesses of *Note `NDB': mysql-cluster. by the SQL node; however, when pushed-down joins are 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 *Note `mysqld': mysqld. This can reduce greatly the number of round trips between an SQL node and the data nodes required to handle such a join, leading to greatly improved performance of join processing. It is possible to determine when joins can be pushed down to the data nodes by examining the join with *Note `EXPLAIN': explain. A number of new system status variables (`Ndb_pushed_queries_defined', `Ndb_pushed_queries_dropped', `Ndb_pushed_queries_executed', and `Ndb_pushed_reads') and additions to the *Note `counters': mysql-cluster-ndbinfo-counters. table (in the *Note `ndbinfo': mysql-cluster-ndbinfo. information database) can also be helpful in determining when and how well joins are being pushed down. More information and examples are available in the description of the `ndb_join_pushdown' server system variable. See also the description of the status variables referenced in the previous paragraph, as well as *Note mysql-cluster-ndbinfo-counters::. * Improved default values for data node configuration parameters In order to provide more resiliency to environmental issues and better handling of some potential failure scenarios, and to perform more reliably with increases in memory and other resource requirements brought about by recent improvements in join handling by *Note `NDB': mysql-cluster, the default values for a number of MySQL Cluster data node configuration parameters have been changed. The parameters and changes are described in the following list: * `HeartbeatIntervalDbDb': Default increased from 1500 ms to 5000 ms. * `ArbitrationTimeout': Default increased from 3000 ms to 7500 ms. * `TimeBetweenEpochsTimeout': Now effectively disabled by default (default changed from 4000 ms to 0). * `SharedGlobalMemory': Default increased from 20 MB to 128 MB. * `MaxParallelScansPerFragment': Default increased from 32 to 256. In addition, the value computed for `MaxNoOfLocalScans' when this parameter is not set in `config.ini' has been increased by a factor of 4. MySQL Cluster NDB 7.2.1 and later MySQL Cluster NDB 7.2 releases are based on MySQL Server 5.5 and are not covered here. See MySQL Cluster NDB 7.2 (http://dev.mysql.com/doc/refman/5.5/en/mysql-cluster.html).  File: manual.info, Node: mysql-cluster-development-5-1-ndb-7-1, Next: mysql-cluster-development-5-1-ndb-7-0, Prev: mysql-cluster-development-5-1-ndb-7-2, Up: mysql-cluster-development 17.1.4.2 MySQL Cluster Development in MySQL Cluster NDB 7.1 ........................................................... The following improvements to MySQL Cluster have been made in MySQL Cluster NDB 7.1. * MySQL Cluster information database (`ndbinfo') The *Note `ndbinfo': mysql-cluster-ndbinfo. information database makes it possible to obtain real-time characteristics of a MySQL Cluster by issuing queries from the *Note `mysql': mysql. client or other MySQL client applications. *Note `ndbinfo': mysql-cluster-ndbinfo. provides metadata specific to MySQL Cluster similarly to how the `INFORMATION_SCHEMA' database provides metadata for the standard MySQL Server. This eliminates much of the need to read log files, issue `REPORT' or `DUMP' commands in the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client, or parse the output of *Note `ndb_config': mysql-cluster-programs-ndb-config. in order to get configuration and status information from a running MySQL Cluster. For more information, see *Note mysql-cluster-ndbinfo::. * Java connectors for MySQL Cluster The MySQL Cluster distribution now includes 2 new Java user APIs, ClusterJ and ClusterJPA. ClusterJ is an object-relational interface in a manner similar to that of Java persistence frameworks such as Hibernate. Cluster JPA is a reimplementation of OpenJPA. ClusterJ uses a backend library (NdbJTie) that provides access to the *Note `NDB': mysql-cluster. storage engine without using a MySQL Server connection or JDBC. ClusterJPA also uses NdbJTie when it improves performance, but can also process complex queries using JDBC and a MySQL Server connection, where it can take advantage of the MySQL query optimizer. ClusterJ and Cluster JPA can also be made to work with recent MySQL Cluster NDB 7.0 releases although the necessary library and JAR files are included only in MySQL Cluster NDB 7.1.1 and later. For more information about using ClusterJ and ClusterJPA, see MySQL Cluster Connector for Java (http://dev.mysql.com/doc/ndbapi/en/mccj.html). * New `CHANGE MASTER TO' option for circular replication Beginning with MySQL Cluster NDB 7.1.0, the *Note `CHANGE MASTER TO': change-master-to. statement 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. (Log rotation and log deletion events are preserved.) See *Note change-master-to::, as well as *Note show-slave-status::, for more information. * Native support for default column values Starting with MySQL Cluster NDB 7.1.4, default values for table columns are stored in the NDB kernel rather than by the MySQL server as was done previously. This means that inserts on tables having column value defaults can be smaller and faster than before, because less data must be sent from SQL nodes to `NDBCLUSTER'. Tables created using previous MySQL Cluster releases can still be used in MySQL Cluster 7.1.4 and later; however, they do not support native default values until they are upgraded. You can upgrade a table with non-native default values to support native default values using an offline *Note `ALTER TABLE': alter-table. statement. * MySQL Cluster on Windows (_Production_) Beginning with MySQL Cluster NDB 7.1.3, MySQL Cluster is available for production use on Microsoft Windows operating systems; MySQL Cluster NDB 7.1 binaries for Windows can be obtained from http://dev.mysql.com/downloads/cluster/ (http://dev.mysql.com/downloads/cluster/). Features and behavior are generally comparable to those found on previously supported platforms such as Linux and Solaris. However, you must install the binaries manually. Beginning with MySQL Cluster NDB 7.1.5, MySQL Cluster processes can be run as Windows services. If you wish to build MySQL Cluster from source on Windows, you must configure the build using the `WITH_NDBCLUSTER_STORAGE_ENGINE' option. For more information, see *Note windows-source-build::. * `--nowait-nodes' option for management servers It is now possible to configure a cluster with two management servers, but to start the cluster using only one of them by starting the management node daemon with the `--nowait-nodes' option. The other management server can then be started at a later time to join the running MySQL Cluster. * Improved lock handling for primary key lookups on `BLOB' tables A MySQL Cluster table stores all but the first 256 bytes of any *Note `BLOB': blob. or *Note `TEXT': blob. column values in a separate *Note `BLOB': blob. table; when executing queries against such tables, a shared lock is obtained. Prior to MySQL Cluster NDB 7.1.1, when the query used a primary key lookup and took place within a transaction, the lock was held for the duration of the transaction, even after no more data was being read from the *Note `NDB': mysql-cluster. table. Now in such cases, the lock is released when all *Note `BLOB': blob. data associated with the table has been read. (Bug #49190) *Note*: A shared lock is also taken for unique key lookups; it is still the case that this lock is held for the duration of the transaction. * Heartbeat thread policy and priority Beginning with MySQL Cluster NDB 7.1.2, a new configuration parameter `HeartbeatThreadPriority' makes it possible to set the policy and the priority for the heartbeat thread on management and API nodes. * Improved access to partitioning information The *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility now provides additional information about the partitioning of data stored in MySQL Cluster. Beginning with MySQL Cluster NDB 7.1.2, the `--blob-info' option causes this program to include partition information for *Note `BLOB': blob. tables in its output. Also beginning with MySQL Cluster NDB 7.1.2, the `--extra-node-info' option causes *Note `ndb_desc': mysql-cluster-programs-ndb-desc. to include information about data distribution (that is, which table fragments are stored on which data nodes). Each of these options also requires the use of the `--extra-partition-info' option. Information about partition-to-node mappings can also be obtained using the `Table::getFragmentNodes()' method, also added in MySQL Cluster NDB 7.1.2. * Replication attribute promotion and demotion Beginning with MySQL Cluster NDB 7.1.3, MySQL Cluster Replication supports attribute promotion and demotion when replicating between columns of different but similar types on the master and the slave. For example, it is possible to promote an *Note `INT': integer-types. column on the master to a *Note `BIGINT': integer-types. column on the slave, and to demote a *Note `TEXT': blob. column to a *Note `VARCHAR': char. column. The implementation of type demotion 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, see *Note replication-features-attribute-promotion::. * Change in `ndbinfo' database The experimental *Note `pools': mysql-cluster-ndbinfo-pools. table was removed from *Note `ndbinfo': mysql-cluster-ndbinfo. in MySQL Cluster NDB 7.1.3. Applications which used this table can and should be rewritten to use other *Note `ndbinfo': mysql-cluster-ndbinfo. tables. * Configuration caching control Beginning with MySQL Cluster NDB 7.1.4, it is possible to disable the management server's configuration cache using the `--config-cache' option, which forces *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. to read its configuration data from the `config.ini' configuration file every time it starts. For more information about configuration caching and this option, see *Note mysql-cluster-config-file::. See also *Note mysql-cluster-programs-ndb-mgmd::. * Incompatible change in NDB API event reporting Beginning with MySQL Cluster NDB 7.1.4, DDL events are no longer reported on `Event' objects by default. Instead the desired level of event reporting (`EventReport' value) must be set explicitly using `Event::setReport()'. * Number of table attributes Beginning with MySQL Cluster NDB 7.1.4, the maximum number of attributes (columns plus indexes) per table has been increased from 128 to 512. * `InnoDB' support in commercial binaries Beginning with MySQL Cluster NDB 7.1.4b, all commercial binary releases of MySQL Cluster provide support for the *Note `InnoDB': innodb-storage-engine. storage engine. * Heartbeat ordering Beginning with MySQL Cluster NDB 7.1.5, it is possible to set a specific order for transmission of heartbeats between data nodes, using the `HeartbeatOrder' data node configuration parameter introduced in this version. This parameter can be useful in situations where multiple data nodes are running on the same host and a temporary disruption in connectivity between hosts would otherwise cause the loss of a node group (and thus failure of the cluster). * Relaxed `ndb_restore' column comparison rules When restoring data, ndb_restore compares the attributes of a column for equality with the definition of the column in the target table. However, not all of these attributes need to be the same for *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to be meaningful, safe and useful. Beginning with MySQL Cluster NDB 7.1.5, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. automatically ignores differences in certain column attributes which do not necessarily have to match between the version of the column in a backup and the version of that column in the MySQL Cluster to which the column data is being restored. These attributes include the following: * `COLUMN_FORMAT' setting (`FIXED', `DYNAMIC', or `DEFAULT') * `STORAGE' setting (`MEMORY' or `DISK') * The default value * The distribution key In such cases, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. reports any such differences to minimize any chance of user error. * Storage of user data in `anyValue' When writing NDB events to the binary log, MySQL Cluster uses `OperationOptions::anyValue' (http://dev.mysql.com/doc/ndbapi/en/ndb-operationoptions.html) to store the server ID. Beginning with MySQL Cluster NDB 7.1.6, it is possible to store user data from an NDB API application in part of the `anyValue' when *Note `mysqld': mysqld. has been started with the `--server-id-bits' option set to a nondefault value. Also beginning with MySQL Cluster NDB 7.1.6, it is possible to view this data in the output of mysqlbinlog, for which its own `--server-id-bits' option is added. * `--add-drop-trigger' option for `mysqldump' Beginning with MySQL Cluster NDB 7.1.8, this option can be used to force all *Note `CREATE TRIGGER': create-trigger. statements in *Note `mysqldump': mysqldump. output to be preceded by a *Note `DROP TRIGGER IF EXISTS': drop-trigger. statement. * Forcing node shutdown and restart In MySQL Cluster NDB 7.1.8 and later, it is possible using the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. management client or the MGM API to force a data node shutdown or restart even if this would force the shutdown or restart of the entire cluster. In the management client, this is implemented through the addition of the `-f' (force) option to the `STOP' and `RESTART' commands. For more information, see *Note mysql-cluster-mgm-client-commands::. The MGM API also adds two new methods for forcing such a node shutdown or restart; see `ndb_mgm_stop4()' (http://dev.mysql.com/doc/ndbapi/en/mgm-ndb-mgm-stop4.html), and `ndb_mgm_restart4()' (http://dev.mysql.com/doc/ndbapi/en/mgm-ndb-mgm-restart4.html), for more information about these methods. * Disk Data usage statistics (`diskpagebuffer' table) MySQL Cluster 7.1.9 introduces a new table in the *Note `ndbinfo': mysql-cluster-ndbinfo. information database. The *Note `diskpagebuffer': mysql-cluster-ndbinfo-diskpagebuffer. table provides real-time data on disk page buffer usage. These statistics can be used to monitor performance of MySQL Cluster Disk Data read and write operations, and can prove useful in the tuning of Disk Data parameters such as `DiskPageBufferMemory'. * `InnoDB' Plugin support Beginning with MySQL Cluster NDB 7.1.9, the MySQL Server supplied with MySQL Cluster supports the *Note `InnoDB': innodb-storage-engine. Plugin. For more information about enabling the plugin if you are building MySQL Cluster from source, see *Note mysql-cluster-installation::. *Note*: Due to a packaging issue, the *Note `InnoDB': innodb-storage-engine. plugin was not included in RPMs for MySQL Cluster NDB 7.1.9; this issue was corrected in MySQL Cluster NDB 7.1.9a. (Bug #58283) * `TimeBetweenEpochsTimeout' and GCP stop control Beginning with MySQL Cluster NDB 7.1.10, it is possible to disable GCP stops by setting `TimeBetweenEpochsTimeout' to 0. In addition, a warning is written to the cluster log whenever the time required for a GCP save exceeds 60 seconds or the time required for a GCP commit exceeds 10 seconds. This warning includes a report of the current value of `TimeBetweenEpochsTimeout'. For more information, see *Note mysql-cluster-ndbd-definition-gcp-stop-errors::. * Skipping corrupted tables in `NDB' native backups Beginning with MySQL Cluster NDB 7.1.10, you can cause *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to ignore tables that are corrupted due to missing blob parts tables by using the the `--skip-broken-objects' option. When this option is used, such tables are skipped, and the restoration of any remaining uncorrupted tables in the backup continues. * `BLOB' read and write batching Beginning with MySQL Cluster NDB 7.1.10, it possible to control batching of *Note `BLOB': blob. read and write operations. For SQL nodes, this can be done using the `--ndb-blob-read-batch-bytes' and `--ndb-blob-write-batch-bytes' options for *Note `mysqld': mysqld. In NDB API applications, you can control batching of *Note `BLOB': blob. reads and writes using the `NdbTransaction' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction.html) methods `setMaxPendingBlobReadBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-setmaxpendingblobreadbytes), `getMaxPendingBlobReadBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-getmaxpendingblobreadbytes), `setMaxPendingBlobWriteBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-setmaxpendingblobwritebytes), and `getMaxPendingBlobWriteBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-getmaxpendingblobwritebytes). * Restoring from a NDB native backup to a differently-named database MySQL Cluster NDB 7.1.11 adds a new `--rewrite-database' option to *Note `ndb_restore': mysql-cluster-programs-ndb-restore, which makes it possible to restore to a database having a different name from that of the database in the backup. The option can be used multiple times, and it is possible to restore from more than one source database in the backup to a single target database (although no protection against table or other object name collision is provided). See *Note mysql-cluster-programs-ndb-restore::, for more information. * Selective over-commit handling Beginning with MySQL Cluster NDB 7.1.10, it is possible to exercise more direct control over uncommitted operations from transactions aborted due to timeouts flushing redo logs to disk. This is implemented using three configuration parameters added in this version of MySQL Cluster: the data node configuration parameters `RedoOverCommitCounter' and `RedoOverCommitLimit', and the API node configuration parameter `DefaultOperationRedoProblemAction'. When an attempt to flush a given redo log takes longer than `RedoOverCommitLimit' seconds, and this occurs `RedoOverCommitLimit' times or more, the transactions contained within the redo log are aborted. Any operations left uncommitted as a result are either aborted or re-tried, according to the value of `DefaultOperationRedoProblemAction'. For more information, see *Note mysql-cluster-redo-over-commit-handling:: * `INFORMATION_SCHEMA' improvements Beginning with MySQL Cluster NDB 7.1.11, Beginning with MySQL Cluster NDB 7.0.22, `INFORMATION_SCHEMA' provides disk usage information for MySQL Cluster Disk Data tables. Previously, *Note `INFORMATION_SCHEMA.TABLES': tables-table. showed only the space usage for the in-memory data part of the table. Now, it also shows the space allocated for and used by the disk_part data of that table as well. In addition, the *Note `INFORMATION_SCHEMA.PARTITIONS': partitions-table. table (which did not show any statistics for *Note `NDB': mysql-cluster. tables) now shows correct values in this table's `TABLE_ROWS', `AVG_ROW_LENGTH', `DATA_LENGTH', `MAX_DATA_LENGTH', and `DATA_FREE' columns, for each partition. * `ndb_restore' attribute demotion Beginning with MySQL Cluster NDB 7.1.11, it is possible to enable attribute demotion when restoring a MySQL Cluster from a native backup running *Note `ndb_restore': mysql-cluster-programs-ndb-restore. with a new `--lossy-conversions' option. In general,the rules governing demotion are the same as for MySQL replication, although there are some exceptions that you may need to take into account being employing this option. See *Note replication-features-different-data-types::, for information about type conversions currently supported by attribute promotion and demotion in MySQL Cluster. * Improved multi-threaded order index building Previously, it was not possible to enable multi-threaded building of ordered indexes during initial restarts. In MySQL Cluster NDB 7.1.11, this can now be done, using the new `TwoPassInitialNodeRestartCopy' data node configuration parameter. * Configuration version information in `ndbinfo.nodes' You can see which version or versions of the MySQL Cluster configuration file are in effect on the data nodes by checking the `config_generation' column which is added to the *Note `nodes': mysql-cluster-ndbinfo-nodes. table in MySQL Cluster NDB 7.1.13. * Configuration version information in `ndbinfo.nodes' You can see which version or versions of the MySQL Cluster configuration file are in effect on the data nodes by checking the `config_generation' column which is added to the *Note `nodes': mysql-cluster-ndbinfo-nodes. table in MySQL Cluster NDB 7.1.13. * Improvements in adding data nodes online Begining with MySQL Cluster NDB 7.0.24, it is possible to add data nodes online to a running MySQL Cluster without performing a rolling restart of the cluster or starting data node processes with the `--nowait-nodes' option. This can be done by setting `Nodegroup = 65536' in the `config.ini' file for any data nodes that should be started at a later time, when first starting the cluster. The amount of time the cluster waits before doing this can be controlled using the `StartNoNodeGroupTimeout' data node configuration parameter. * Unique key updates in replication It is possible in MySQL Cluster NDB 7.1.14 and later to employ operations that update unique keys when replicating *Note `NDB': mysql-cluster. tables. Previously this could lead to duplicate key errors when trying to execute the binary log (due to the fact that row events in the binary log were ordered according to the partitioning of the base table, and could differ in order within the epoch for that in which they were executed). *Important*: Master and slave tables must both be using the *Note `NDB': mysql-cluster. storage engine for this to work. * Starting with MySQL Cluster NDB 7.1.17, the NDB kernel implements a number of statistical counters relating to actions performed by or affecting `Ndb' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) objects. Such events include starting, closing, and aborting transactions; operations using primary keys or unique keys; table, range, and pruned scans; blocking of threads by incompleted operations; and data and events sent and received by MySQL Cluster nodes. NDB API statistics counters are incremented inside the NDB kernel whenever NDB API calls are made or data is sent to or received by the data nodes. A MySQL Server running as an SQL node in the cluster can access the values of these counters as system status variables, as seen in the output of *Note `SHOW STATUS': show-status, or in the results of queries against the *Note `SESSION_STATUS': status-table. or *Note `GLOBAL_STATUS': status-table. table in the `INFORMATION_SCHEMA' database. By comparing the values of these status variables before and after the execution of statements affecting *Note `NDB': mysql-cluster. tables, you can observe the corresponding actions taken on the NDB API level. This can be highly useful when monitoring and tuning MySQL Cluster. For more information, see *Note mysql-cluster-ndb-api-statistics::. See also *Note mysql-cluster-status-variables::, for information about the individual status variables. * Version 2 binary log row events New versions of the `WRITE_ROW', `UPDATE_ROW', and `DELETE_ROW' events have been implemented in MySQL Cluster NDB 7.1.16, extending them with additional information intended to support future enhancements; these are referred to as `Version 2' binary log events. Version 2 log events are not backward compatible, and cannot be read by older slaves. A new *Note `mysqld': mysqld. option `--log-bin-use-v1-row-events' can be employed to force use of Version 1 events when writing the binary log. This can be used during upgrades to make a newer *Note `mysqld': mysqld. generate Version 1 binary log row events that can be read by older slaves. * Circular replication: `Primary wins first' conflict detection Two new conflict detection functions `NDB$EPOCH()' and `NDB$EPOCH_TRANS()' can be useful in `active-active' circular replication scenarios with two MySQL Clusters. For each case, we designate one cluster as primary and one as secondary, and implement a `primary always wins' rule for determining whether to accept conflicting changes. When using `NDB$EPOCH()', conflicting rows on the secondary are realigned with those on the primary; when using `NDB$EPOCH_TRANS()', it is transactions containing rows in conflict (and any transactions which depend on them) on the secondary that are realigned. When using `NDB$EPOCH_TRANS()' as the conflict detection function, the binary log must be written using Version 2 binary logging row events; that is, the *Note `mysqld': mysqld. processes on both the primary and the secondary must be started with `--log-bin-use-v1-row-events=0'. In addition, the secondary's binary log must include transaction IDs for all rows, that is, by setting `--ndb-log-transaction-id=1'. You can monitor conflict detection and resolution performed using these functions by reading a number of related server status variables, including `Ndb_conflict_fn_epoch', `Ndb_conflict_fn_epoch_trans', and `Ndb_conflict_trans_row_conflict_count' (among others). See *Note mysql-cluster-status-variables::. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * Fail-fast data node capability Beginning with MySQL Cluster NDB 7.1.17, it is possible to enable fail-fast behavior for data nodes by enabling the `CrashOnCorruptedTuple' configuration parameter introduced in this version (disabled by default). Doing so causes data nodes to fail whenever they detect a corrupted tuple. * Rows per partition limit removed Previously it was possible to store a maximum of 46137488 rows in a single MySQL Cluster partition--that is, per data node. Beginning with MySQL Cluster NDB 7.0.36 and MySQL Cluster NDB 7.1.25, this limitation has been lifted, and there is no longer any practical upper limit to this number. (Bug #13844405, Bug #14000373) MySQL Cluster NDB 7.1 is also supported by MySQL Cluster Manager, which provides an advanced command-line interface that can simplify many complex MySQL Cluster management tasks. See MySQL(tm) Cluster Manager 1.2.4 User Manual (http://dev.mysql.com/doc/cluster-manager/en/index.html), for more information.  File: manual.info, Node: mysql-cluster-development-5-1-ndb-7-0, Next: mysql-cluster-development-5-1-ndb-6-3, Prev: mysql-cluster-development-5-1-ndb-7-1, Up: mysql-cluster-development 17.1.4.3 MySQL Cluster Development in MySQL Cluster NDB 7.0 ........................................................... The following list provides an overview of significant feature additions and changes made in MySQL Cluster NDB 7.0. For more detailed information about all feature changes and bugfixes made in MySQL Cluster NDB 7.0, see `http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/mysql-cluster-news-7-0.html'. *Important*: Early development versions of MySQL Cluster NDB 7.0 were known as `MySQL Cluster NDB 6.4', and the first four releases in this series were identified as MySQL Cluster NDB 6.4.0 through 6.4.3. Any information relating to these MySQL Cluster NDB 6.4.x releases appearing in this documentation apply to MySQL Cluster NDB 7.0. MySQL Cluster NDB 7.0.4 is the fifth MySQL Cluster NDB 7.0 release; it is the successor to MySQL Cluster NDB 6.4.3. * MySQL Cluster on Windows (_alpha_) MySQL Cluster NDB 7.0 is available on an experimental basis for Windows operating systems (for production use on Windows, you should use MySQL Cluster NDB 7.1.3 or later). Features and behavior comparable to those found on platforms that are already supported--such as Linux and Solaris--are planned for MySQL Cluster on Windows. In MySQL Cluster NDB 7.0, you must build from source (Windows binaries are available for MySQL Cluster NDB 7.1 releases). To enable MySQL Cluster support on Windows when building from source, you must configure the build using the `WITH_NDBCLUSTER_STORAGE_ENGINE' option. For more information, see *Note windows-source-build::. * Ability to add nodes and node groups online Beginning with MySQL Cluster NDB 6.4.0, it is possible to add new node groups (and thus new data nodes) to a running MySQL Cluster without shutting down and reloading the cluster. As part of enabling this feature, a new command `CREATE NODEGROUP' has been added to the cluster management client and the functionality of the *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table. SQL statement has been extended. For more information, see *Note mysql-cluster-online-add-node::. * Data node multi-threading support Beginning with MySQL Cluster NDB 6.4.0, a multi-threaded version of the data node daemon, named *Note `ndbmtd': mysql-cluster-programs-ndbmtd, is available for use on data node hosts with multiple CPU cores. This binary is built automatically when compiling with MySQL Cluster support; no additional options other than those needed to provide MySQL Cluster support are needed when configuring the build. In most respects, *Note `ndbmtd': mysql-cluster-programs-ndbmtd. functions in the same way as *Note `ndbd': mysql-cluster-programs-ndbd, and can use the same command-line options and configuration parameters. In addition, the new `MaxNoOfExecutionThreads' configuration parameter can be used to determine the number of data node process threads for *Note `ndbmtd': mysql-cluster-programs-ndbmtd. For more information, see *Note mysql-cluster-programs-ndbmtd::. *Note*: Disk Data tables are not yet supported for use with *Note `ndbmtd': mysql-cluster-programs-ndbmtd. * Configuration cache Formerly, MySQL Cluster configuration was stateless--that is, configuration information was reloaded from the cluster's global configuration file (usually `config.ini') each time *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. was started. Beginning with MySQL Cluster NDB 6.4.0, the cluster's configuration is cached internally, and the global configuration file is no longer automatically re-read when the management server is restarted. This behavior can be controlled using the management server options `--configdir', `--initial', and `--reload'. In MySQL Cluster NDB 7.0.15 and later, the configuration cache can be disabled using the `--config-cache' option. For more information about these changes, see *Note mysql-cluster-config-file::. For more information about the new management server options, see *Note mysql-cluster-programs-ndb-mgmd::. * Detection of NDB API client connection errors In MySQL Cluster NDB 7.0 (6.4.0 and later releases), the NDB API's `Ndb_cluster_connection' class adds the `get_latest_error()' and `get_latest_error_msg()' methods for catching and diagnosing problems with NDB API client connections. * Snapshot options for backups Beginning with MySQL Cluster NDB 6.4.0, you can determine when performing a cluster backup whether the backup matches the state of the data when the backup was started or when it was completed, using the new options `SNAPSHOTSTART' and `SNAPSHOTEND' for the management client's `START BACKUP' command. See *Note mysql-cluster-backup-using-management-client::, for more information. * Dynamic NDB transporter send buffer memory allocation Previously, the NDB kernel used a fixed-size send buffer for every data node in the cluster, which was allocated when the node started. Because the size of this buffer could not be changed after the cluster was started, it was necessary to make it large enough in advance to accommodate the maximum possible load on any transporter socket. However, this was an inefficient use of memory, since much of it often went unused. Beginning with MySQL Cluster NDB 6.4.0, 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. This change is reflected by the addition of the configuration parameters `TotalSendBufferMemory', `ReservedSendBufferMemory', and `OverLoadLimit', as well as a change in how the existing `SendBufferMemory' configuration parameter is used. For more information, see *Note mysql-cluster-config-send-buffers::. * Robust DDL operations Beginning with MySQL Cluster NDB 6.4.0, DDL operations (such as *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table.) are protected from data node failures; in the event of a data node failure, such operations are now rolled back gracefully. Previously, if a data node failed while trying to perform a DDL operation, the MySQL Cluster data dictionary became locked and no further DDL statements could be executed without restarting the cluster. * IPv6 support in MySQL Cluster Replication Beginning with MySQL Cluster NDB 6.4.1, IPv6 networking is supported between MySQL Cluster SQL nodes, which makes it possible to replicate between instances of MySQL Cluster using IPv6 addresses. However, IPv6 is supported only for direct connections between MySQL servers; all connections _within_ an individual MySQL Cluster must use IPv4. For more information, see *Note mysql-cluster-replication-issues::. * Restoring specific databases, tables, or columns from a MySQL Cluster backup It is now possible to exercise more fine-grained control when restoring a MySQL Cluster from backup using *Note `ndb_restore': mysql-cluster-programs-ndb-restore. Beginning with MySQL Cluster NDB 6.4.3, you can choose to restore only specified tables or databases, or exclude specific tables or databases from being restored, using the new *Note `ndb_restore': mysql-cluster-programs-ndb-restore. options `--include-tables', `--include-databases', `--exclude-tables', and `--exclude-databases'. Beginning with MySQL Cluster NDB 7.0.7, it is also possible to restore to a table having fewer columns than the original using the `--exclude-missing-columns' option. For more information about all of these options, see *Note mysql-cluster-programs-ndb-restore::. * Improved Disk Data file system configuration As of MySQL Cluster NDB 6.4.3, you can specify default locations for MySQL Cluster Disk Data data files and undo log files using the data node configuration parameters `FileSystemPathDD', `FileSystemPathDataFiles', and `FileSystemPathUndoFiles'. This eliminates the need to use symbolic links to place Disk Data files separately from other files in data node file systems to improve Disk Data performance. For more information, see *Note mysql-cluster-ndbd-disk-data-filesystem-parameters::. * Automatic creation of Disk Data log file groups and tablespaces Beginning with MySQL Cluster NDB 6.4.3, using the data node configuration parameters `InitialLogFileGroup' and `InitialTablespace', you can cause the creation of a MySQL Cluster Disk Data log file group, tablespace, or both, when the cluster is first started. When using these parameters, no SQL statements are required to create these Disk Data objects. For more information, see `Disk Data object creation parameters'. * Improved internal message passing and record handling MySQL Cluster NDB 7.0 contains 2 changes that optimize the use of network connections by addressing the size and number of messages passed between data nodes, and between data nodes and API nodes, which can increase MySQL Cluster and application performance: * Packed reads Formerly, each read request signal contained a list of columns to be retrieved, each of these column identifiers using 4 bytes within the message. This meant that the message size increased as the number of columns being fetched increased. In addition, in the response from the data node, each column result was packed to a 4-byte boundary, which resulted in wasted space. In MySQL Cluster NDB 7.0, messaging for read operations is optimized in both directions, using a bitmap in the read request to specify the columns to be fetched. Where many fields are requested, this can result in a significant message size reduction as compared with the old method. In addition, the 4-byte packing in responses is no longer used, which means that smaller fields consume less space. * Long signal transactions This enhancement reduces the number of messages and signals that are sent to data nodes for complex requests. Prior to MySQL Cluster NDB 7.0, there was a 100 byte limit on the size of the request signal, which meant that complex requests had to be split up between multiple messages prior to transmission, then reassembled on the receiving end. In addition to actual payload data, each message required its own operating system and protocol overhead such as header information. This often wasted network bandwidth and data node CPU. The maximum size of the message is now 32 KB, which is sufficient to accommodate most queries. Both of these optimizations are internal to the NDB API, and so is transparent to applications; this is true whether an application uses the NDB API directly or does so indirectly through an SQL node. * Configuration parameter data dumps Starting with MySQL Cluster NDB 7.0.6, the *Note `ndb_config': mysql-cluster-programs-ndb-config. utility supports a `--configinfo' option that causes it to dump a list of all configuration parameters supported by the cluster, along with brief descriptions, information about the parameters' default and permitted values, and the sections of the `config.ini' file in which the parameters apply. An additional `--xml' switch causes *Note `ndb_config': mysql-cluster-programs-ndb-config. to use XML rather than plaintext output. Using *Note `ndb_config `--configinfo'': mysql-cluster-programs-ndb-config. or *Note `ndb_config `--configinfo --xml'': mysql-cluster-programs-ndb-config. requires no access to a running MySQL Cluster, any other programs, or any files. For more information and examples, see *Note mysql-cluster-programs-ndb-config::. * Per-table reporting of free space on disk The *Note `INFORMATION_SCHEMA.FILES': files-table. table shows information about used and free space in MySQL Cluster Disk Data data files, but this information is not applicable to individual tables. In MySQL Cluster NDB 7.0.8 and later, the *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility provides two additional columns in its output that show the amount of space allocated on disk for a given *Note `NDB': mysql-cluster. table as well the amount of space that remains available for additional storage of disk-based column data for that table. For more information, see *Note mysql-cluster-programs-ndb-desc::. * Improved restart times Optimizations in redo log handling and other file system operations introduced in MySQL Cluster NDB 7.0.9 have the potential to reduce considerably the time required for restarts. While actual performance benefits observed in production setups will naturally vary depending on database size, hardware, and other conditions, our own preliminary testing has shown that these improvements can yield startup times that are faster than those typical of previous MySQL Cluster NDB 7.0 releases by a factor of 50 or more. * Native support for default column values Starting with MySQL Cluster NDB 7.0.15, default values for table columns are stored in the NDB kernel rather than by the MySQL server as was done previously. This means that inserts on tables having column value defaults can be smaller and faster than before, because less data must be sent from SQL nodes to `NDBCLUSTER'. Tables created using previous MySQL Cluster releases can still be used in MySQL Cluster 7.0.15 and later; however, they do not support native default values until they are upgraded. You can upgrade a table with non-native default values to support native default values using an offline *Note `ALTER TABLE': alter-table. statement. * `--nowait-nodes' option for management servers Starting with MySQL Cluster NDB 7.0.10, it is possible to configure a cluster with two management servers, but to start the cluster using only one of them by starting the management node daemon with the `--nowait-nodes' option. The other management server can then be started at a later time to join the running MySQL Cluster. * Increased flexibility in online upgrade procedure Previously, when performing an upgrade of a running MySQL cluster, the order in which the types of cluster nodes had to be upgraded was very strict. However, beginning with MySQL Cluster NDB 7.0.10, MySQL Cluster supports online upgrading of API nodes (including MySQL servers running as SQL nodes) online upgrading management nodes, data nodes, or both. *Important*: Before attempting to use this new upgrade functionality, see *Note mysql-cluster-rolling-restart::, for additional information, especially if you are planning an online upgrade to MySQL Cluster NDB 7.0 from MySQL Cluster NDB 6.3. * New `CHANGE MASTER TO' option for circular replication Beginning with MySQL Cluster NDB 7.0.11, the *Note `CHANGE MASTER TO': change-master-to. statement 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. (Log rotation and log deletion events are preserved.) See *Note change-master-to::, as well as *Note show-slave-status::, for more information. * New replication conflict resolution strategy Beginning with MySQL Cluster NDB 7.0.11, the function `NDB$MAX_DELETE_WIN()' is available to implement `greatest timestamp, delete wins' conflict resolution. See *Note mysql-cluster-replication-ndb-max-delete-win::, for more information. * Improved lock handling for primary key lookups on `BLOB' tables A MySQL Cluster table stores all but the first 256 bytes of any *Note `BLOB': blob. or *Note `TEXT': blob. column values in a separate *Note `BLOB': blob. table; when executing queries against such tables, a shared lock is obtained. Prior to MySQL Cluster NDB 7.0.12, when the query used a primary key lookup and took place within a transaction, the lock was held for the duration of the transaction, even after no more data was being read from the *Note `NDB': mysql-cluster. table. Now in such cases, the lock is released when all *Note `BLOB': blob. data associated with the table has been read. (Bug #49190) *Note*: A shared lock is also taken for unique key lookups; it is still the case that this lock is held for the duration of the transaction. * Heartbeat thread policy and priority Beginning with MySQL Cluster NDB 7.0.13, a new configuration parameter `HeartbeatThreadPriority' makes it possible to set the policy and the priority for the heartbeat thread on management and API nodes. * Improved access to partitioning information The *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility now provides additional information about the partitioning of data stored in MySQL Cluster. Beginning with MySQL Cluster NDB 7.0.13, the `--blob-info' option causes this program to include partition information for *Note `BLOB': blob. tables in its output. Beginning with MySQL Cluster NDB 7.0.14, the `--extra-node-info' option causes *Note `ndb_desc': mysql-cluster-programs-ndb-desc. to include information about data distribution (that is, which table fragments are stored on which data nodes). Each of these options also requires the use of the `--extra-partition-info' option. Information about partition-to-node mappings can also be obtained using the `Table::getFragmentNodes()' method, also added in MySQL Cluster NDB 7.0.14. * Replication attribute promotion and demotion Beginning with MySQL Cluster NDB 7.0.14, MySQL Cluster Replication supports attribute promotion and demotion when replicating between columns of different but similar types on the master and the slave. For example, it is possible to promote an *Note `INT': integer-types. column on the master to a *Note `BIGINT': integer-types. column on the slave, and to demote a *Note `TEXT': blob. column to a *Note `VARCHAR': char. column. The implementation of type demotion 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, see *Note replication-features-attribute-promotion::. * Incompatible change in NDB API event reporting Beginning with MySQL Cluster NDB 7.0.15, DDL events are no longer reported on `Event' objects by default. Instead such event reporting must be enabled explicitly using the `Event::setReport()' method. For more information, see `Event::setReport()' (http://dev.mysql.com/doc/ndbapi/en/ndb-event-methods.html#ndb-event-setreport), and The `Event::EventReport' Type (http://dev.mysql.com/doc/ndbapi/en/ndb-event-types.html#ndb-event-eventreport). * Number of table attributes Beginning with MySQL Cluster NDB 7.0.15, the maximum number of attributes (columns plus indexes) per table has been increased from 128 to 512. * Heartbeat ordering Beginning with MySQL Cluster NDB 7.0.16, it is possible to set a specific order for transmission of heartbeats between data nodes, using the `HeartbeatOrder' data node configuration parameter introduced in this version. This parameter can be useful in situations where multiple data nodes are running on the same host and a temporary disruption in connectivity between hosts would otherwise cause the loss of a node group (and thus failure of the cluster). * Relaxed `ndb_restore' column comparison rules When restoring data, ndb_restore compares the attributes of a column for equality with the definition of the column in the target table. However, not all of these attributes need to be the same for *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to be meaningful, safe and useful. Beginning with MySQL Cluster NDB 7.0.16, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. automatically ignores differences in certain column attributes which do not necessarily have to match between the version of the column in a backup and the version of that column in the MySQL Cluster to which the column data is being restored. These attributes include the following: * `COLUMN_FORMAT' setting (`FIXED', `DYNAMIC', or `DEFAULT') * `STORAGE' setting (`MEMORY' or `DISK') * The default value * The distribution key In such cases, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. reports any such differences to minimize any chance of user error. * Storage of user data in `anyValue' When writing NDB events to the binary log, MySQL Cluster uses `OperationOptions::anyValue' (http://dev.mysql.com/doc/ndbapi/en/ndb-operationoptions.html) to store the server ID. Beginning with MySQL Cluster NDB 7.0.17, it is possible to store user data from an NDB API application in part of the `anyValue' when *Note `mysqld': mysqld. has been started with the `--server-id-bits' option set to a nondefault value. Also beginning with MySQL Cluster NDB 7.0.17, it is possible to view this data in the output of mysqlbinlog, for which its own `--server-id-bits' option is added. * `--add-drop-trigger' option for `mysqldump' Beginning with MySQL Cluster NDB 7.0.19, this option can be used to force all *Note `CREATE TRIGGER': create-trigger. statements in *Note `mysqldump': mysqldump. output to be preceded by a *Note `DROP TRIGGER IF EXISTS': drop-trigger. statement. * Forcing node shutdown and restart In MySQL Cluster NDB 7.0.19 and later, it is possible using the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. management client or the MGM API to force a data node shutdown or restart even if this would force the shutdown or restart of the entire cluster. In the management client, this is implemented through the addition of the `-f' (force) option to the `STOP' and `RESTART' commands. For more information, see *Note mysql-cluster-mgm-client-commands::. The MGM API also adds two new methods for forcing such a node shutdown or restart; see `ndb_mgm_stop4()' (http://dev.mysql.com/doc/ndbapi/en/mgm-ndb-mgm-stop4.html), and `ndb_mgm_restart4()' (http://dev.mysql.com/doc/ndbapi/en/mgm-ndb-mgm-restart4.html), for more information about these methods. * `TimeBetweenEpochsTimeout' and GCP stop control Beginning with MySQL Cluster NDB 7.0.21, it is possible to disable GCP stops by setting `TimeBetweenEpochsTimeout' to 0. In addition, a warning is written to the cluster log whenever the time required for a GCP save exceeds 60 seconds or the time required for a GCP commit exceeds 10 seconds. This warning includes a report of the current value of `TimeBetweenEpochsTimeout'. For more information, see *Note mysql-cluster-ndbd-definition-gcp-stop-errors::. * Skipping corrupted tables in `NDB' native backups Beginning with MySQL Cluster NDB 7.0.21, you can cause *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to ignore tables that are corrupted due to missing blob parts tables by using the the `--skip-broken-objects' option. When this option is used, such tables are skipped, and the restoration of any remaining uncorrupted tables in the backup continues. * `BLOB' read and write batching Beginning with MySQL Cluster NDB 7.0.21, it possible to control batching of *Note `BLOB': blob. read and write operations. For SQL nodes, this can be done using the `--ndb-blob-read-batch-bytes' and `--ndb-blob-write-batch-bytes' options for *Note `mysqld': mysqld. In NDB API applications, you can control batching of *Note `BLOB': blob. reads and writes using the `NdbTransaction' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction.html) methods `setMaxPendingBlobReadBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-setmaxpendingblobreadbytes), `getMaxPendingBlobReadBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-getmaxpendingblobreadbytes), `setMaxPendingBlobWriteBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-setmaxpendingblobwritebytes), and `getMaxPendingBlobWriteBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-getmaxpendingblobwritebytes). * Restoring from a NDB native backup to a differently-named database MySQL Cluster NDB 7.0.22 adds a new `--rewrite-database' option to *Note `ndb_restore': mysql-cluster-programs-ndb-restore, which makes it possible to restore to a database having a different name from that of the database in the backup. The option can be used multiple times, and it is possible to restore from more than one source database in the backup to a single target database (although no protection against table or other object name collision is provided). See *Note mysql-cluster-programs-ndb-restore::, for more information. * `INFORMATION_SCHEMA' inprovements Beginning with MySQL Cluster NDB 7.0.22, `INFORMATION_SCHEMA' provides disk usage information for MySQL Cluster Disk Data tables. Previously, *Note `INFORMATION_SCHEMA.TABLES': tables-table. showed only the space usage for the in-memory data part of the table. Now, it also shows the space allocated for and used by the disk_part data of that table as well. In addition, the *Note `INFORMATION_SCHEMA.PARTITIONS': partitions-table. table (which did not show any statistics for *Note `NDB': mysql-cluster. tables) now shows correct values in this table's `TABLE_ROWS', `AVG_ROW_LENGTH', `DATA_LENGTH', `MAX_DATA_LENGTH', and `DATA_FREE' columns, for each partition. * Configuration version information in `ndbinfo.nodes' You can see which version or versions of the MySQL Cluster configuration file are in effect on the data nodes by checking the `config_generation' column which is added to the *Note `nodes': mysql-cluster-ndbinfo-nodes. table in MySQL Cluster NDB 7.0.24. * Improvements in adding data nodes online Beginning with MySQL Cluster NDB 7.0.24, it is possible to add data nodes online to a running MySQL Cluster without performing a rolling restart of the cluster or starting data node processes with the `--nowait-nodes' option. This can be done by setting `Nodegroup = 65536' in the `config.ini' file for any data nodes that should be started at a later time, when first starting the cluster. The amount of time the cluster waits before doing this can be controlled using the `StartNoNodeGroupTimeout' data node configuration parameter. * Unique key updates in replication It is possible in MySQL Cluster NDB 7.0.25 and later to employ operations that update unique keys when replicating *Note `NDB': mysql-cluster. tables. Previously this could lead to duplicate key errors when trying to execute the binary log (due to the fact that row events in the binary log were ordered according to the partitioning of the base table, and could differ in order within the epoch for that in which they were executed). *Important*: Master and slave tables must both be using the *Note `NDB': mysql-cluster. storage engine for this to work. * Starting with MySQL Cluster NDB 7.0.22, the NDB kernel implements a number of statistical counters relating to actions performed by or affecting `Ndb' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) objects. Such events include starting, closing, and aborting transactions; operations using primary keys or unique keys; table, range, and pruned scans; blocking of threads by incompleted operations; and data and events sent and received by MySQL Cluster nodes. NDB API statistics counters are incremented inside the NDB kernel whenever NDB API calls are made or data is sent to or received by the data nodes. A MySQL Server running as an SQL node in the cluster can access the values of these counters as system status variables, as seen in the output of *Note `SHOW STATUS': show-status, or in the results of queries against the *Note `SESSION_STATUS': status-table. or *Note `GLOBAL_STATUS': status-table. table in the `INFORMATION_SCHEMA' database. By comparing the values of these status variables before and after the execution of statements affecting *Note `NDB': mysql-cluster. tables, you can observe the corresponding actions taken on the NDB API level. This can be highly useful when monitoring and tuning MySQL Cluster. For more information, see *Note mysql-cluster-ndb-api-statistics::. See also *Note mysql-cluster-status-variables::, for information about the individual status variables. * Version 2 binary log row events New versions of the `WRITE_ROW', `UPDATE_ROW', and `DELETE_ROW' events have been implemented in MySQL Cluster NDB 7.0.27, extending them with additional information intended to support future enhancements; these are referred to as `Version 2' binary log events. Version 2 log events are not backward compatible, and cannot be read by older slaves. A new *Note `mysqld': mysqld. option `--log-bin-use-v1-row-events' can be employed to force use of Version 1 events when writing the binary log. This can be used during upgrades to make a newer *Note `mysqld': mysqld. generate Version 1 binary log row events that can be read by older slaves. * Fail-fast data node capability Beginning with MySQL Cluster NDB 7.0.28, it is possible to enable fail-fast behavior for data nodes by enabling the `CrashOnCorruptedTuple' configuration parameter introduced in this version (disabled by default). Doing so causes data nodes to fail whenever they detect a corrupted tuple. * Rows per partition limit removed Previously it was possible to store a maximum of 46137488 rows in a single MySQL Cluster partition--that is, per data node. Beginning with MySQL Cluster NDB 7.0.36, this limitation has been lifted, and there is no longer any practical upper limit to this number.  File: manual.info, Node: mysql-cluster-development-5-1-ndb-6-3, Next: mysql-cluster-development-5-1-ndb-6-2, Prev: mysql-cluster-development-5-1-ndb-7-0, Up: mysql-cluster-development 17.1.4.4 MySQL Cluster Development in MySQL Cluster NDB 6.3 ........................................................... The following list provides an overview of significant feature additions and changes first made in MySQL Cluster NDB 6.3. For more detailed information about all feature changes and bugfixes made in MySQL Cluster NDB 6.3, see `http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/mysql-cluster-news-6-3.html'. * Conflict detection and resolution It is now possible to detect and resolve conflicts that arise in multi-master replication scenarios, such as circular replication, when different masters may try to update the same row on the slave with different data. Both `greatest timestamp wins' and `same timestamp wins' scenarios are supported. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * Recovery of `one master, many slaves' replication setups Recovery of multi-way replication setups (`one master, many slaves') is now supported using the `--ndb-log-orig' server option and changes in the `mysql.ndb_binlog_index' table. See *Note mysql-cluster-replication-schema::, for more information. * Enhanced selection options for transaction coordinator New values and behaviors are introduced for `--ndb_optimized_node_selection', enabling greater flexibility when an SQL node chooses a transaction coordinator. For more information, see the description of `ndb_optimized_node_selection' in *Note mysql-cluster-system-variables::. * Replication heartbeats Replication heartbeats facilitate the task of monitoring and detecting failures in master-slave connections in real time. This feature is implemented using a new `MASTER_HEARTBEAT_PERIOD = VALUE' clause for the *Note `CHANGE MASTER TO': change-master-to. statement and the addition of two status variables `Slave_heartbeat_period' and `Slave_received_heartbeats'. For more information, see *Note change-master-to::. * `NDB' thread locks It is possible to lock *Note `NDB': mysql-cluster. execution threads and maintenance threads (such as file system and other operating system threads) to specific CPUs on multiprocessor data node hosts, and to leverage real-time scheduling. * Improved performance of updates using primary keys or unique keys The number of unnecessary reads when performing a primary key or unique key update has been greatly reduced. Since it is seldom necessary to read a record prior to an update, this can yield a considerable improvement in performance. In addition, primary key columns are no longer written to when not needed during update operations. * Batching improvements Support of batched *Note `DELETE': delete. and *Note `UPDATE': update. operations has been significantly improved. Batching of `UPDATE WHERE...' and multiple *Note `DELETE': delete. operations is also now implemented. * Improved SQL statement performance metrics The `Ndb_execute_count' system status variable measures the number of round trips made by SQL statements to the *Note `NDB': mysql-cluster. kernel, providing an improved metric for determining efficiency with which statements are executed. For more information, see `MySQL Cluster Status Variables: `Ndb_execute_count''. * Compressed LCPs and backups Compressed local checkpoints and backups can save 50% or more of the disk space used by uncompressed LCPs and backups. These can be enabled using the two new data node configuration parameters `CompressedLCP' and `CompressedBackup', respectively. * `OPTIMIZE TABLE' support with `NDBCLUSTER' tables *Note `OPTIMIZE TABLE': optimize-table. is supported for dynamic columns of in-memory *Note `NDB': mysql-cluster. tables. In such cases, it is no longer necessary to drop (and possibly to re-create) a table, or to perform a rolling restart, in order to recover memory from deleted rows for general re-use by Cluster. The performance of `OPTIMIZE' on Cluster tables can be tuned by adjusting the value of the `ndb_optimization_delay' system variable, which controls the number of milliseconds to wait between processing batches of rows by *Note `OPTIMIZE TABLE': optimize-table. In addition, *Note `OPTIMIZE TABLE': optimize-table. on an *Note `NDBCLUSTER': mysql-cluster. table can be interrupted by, for example, killing the SQL thread performing the `OPTIMIZE' operation. * Batching of transactions It is possible to cause statements occurring within the same transaction to be run as a batch by setting the session variable `transaction_allow_batching' to `1' or `ON'. To use this feature, `autocommit' must be set to `0' or `OFF'. Batch sizes can be controlled using the `--ndb-batch-size' option for *Note `mysqld': mysqld. For additional information, see *Note mysql-cluster-program-options-mysqld::, and *Note mysql-cluster-system-variables::. * Attribute promotion with `ndb_restore' It is possible using *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to restore data reliably from a column of a given type to a column that uses a `larger' type. This is sometimes referred to as _attribute promotion_. For example, MySQL Cluster backup data that originated in a *Note `SMALLINT': integer-types. column can be restored to a *Note `MEDIUMINT': integer-types, *Note `INT': integer-types, or *Note `BIGINT': integer-types. column. See *Note mysql-cluster-programs-ndb-restore::, for more information. * Parallel data node recovery Recovery of multiple data nodes can now be done in parallel, rather than sequentially. In other words, several data nodes can be restored concurrently, which can often result in much faster recovery times than when they are restored one at a time. * Increased local checkpoint efficiency Only 2 local checkpoints are stored, rather than 3, lowering disk space requirements and the size and number of redo log files. * `NDBCLUSTER' table persistence control Persistence of *Note `NDB': mysql-cluster. tables can be controlled using the session variables `ndb_table_temporary' and `ndb_table_no_logging'. `ndb_table_no_logging' causes *Note `NDB': mysql-cluster. tables not to be checkpointed to disk; `ndb_table_temporary' does the same, and in addition, no schema files are created. See *Note mysql-cluster-option-tables::. * Epoll support (_Linux only_) _Epoll_ is an improved method for handling file descriptors, which is more efficient than scanning to determine whether a file descriptor has data to be read. (The term _epoll_ is specific to Linux and equivalent functionality is known by other names on other platforms such as Solaris and FreeBSD.) Currently, MySQL Cluster supports this functionality on Linux only. * Distribution awareness (SQL nodes) In MySQL Cluster NDB 6.3, SQL nodes can take advantage of distribution awareness. Here we provide a brief example showing how to design a table to make a given class of queries distrubtion-aware. Suppose an *Note `NDBCLUSTER': mysql-cluster. table `t1' has the following schema: CREATE TABLE t1 ( userid INT NOT NULL, serviceid INT NOT NULL AUTO_INCREMENT PRIMARY KEY, data VARCHAR(255) ) ENGINE=NDBCLUSTER; Suppose further that most of the queries to be used in our application test values of the `userid' column of this table. The form of such a query looks something like this: SELECT COLUMNS FROM t1 WHERE userid RELATION VALUE; In this query, RELATION represents some relational operator, such as `=', `<', `>', and so on. Queries using `IN' and a list of values can also be used: SELECT COLUMNS FROM t1 WHERE userid IN VALUE_LIST; To make use of distribution awareness, we need to make the `userid' column part of the table's primary key, then explicitly partition the table with this column being used as the partitioning key. (Recall that for a partitioned table having one or more unique keys, all columns of the table's partitioning key must also be part of all of the unique keys--for more information and examples, see *Note partitioning-limitations-partitioning-keys-unique-keys::.) In other words, the table schema should be equivalent to the following *Note `CREATE TABLE': create-table. statement: CREATE TABLE t1 ( userid INT NOT NULL, serviceid INT NOT NULL AUTO_INCREMENT, data VARCHAR(255), PRIMARY KEY p (userid,serviceid) ) ENGINE=NDBCLUSTER PARTITION BY KEY(userid); When the table is partitioned in this way, all rows having the same `userid' value are found on the same node group, and the MySQL Server can immediately select the optimal node to use as the transaction coordinator. * Realtime extensions for multiple CPUs When running MySQL Cluster data nodes on hosts with multiple processors, the realtime extensions make it possible to give priority to the data node process and control on which CPU cores it should operate. This can be done using the data node configuration parameters `RealtimeScheduler', `SchedulerExecutionTimer', and `SchedulerSpinTimer'. Doing so properly can significantly lower response times and make them much more predictable response. For more information about using these parameters, see Defining Data Nodes: Realtime Performance Parameters * Fully automatic database discovery It is no longer a requirement for database autodiscovery that an SQL node already be connected to the cluster at the time that a database is created on another SQL node, or for a *Note `CREATE DATABASE': create-database. or *Note `CREATE SCHEMA': create-database. statement to be issued on the new SQL node after it joins the cluster. * Detection of NDB API client connection errors Beginning with MySQL Cluster NDB 6.3.20, the NDB API's `Ndb_cluster_connection' class adds the `get_latest_error()' and `get_latest_error_msg()' methods for catching and diagnosing problems with NDB API client connections. * Restoring specific databases, tables, or columns from a MySQL Cluster backup It is now possible to exercise more fine-grained control when restoring a MySQL Cluster from backup using *Note `ndb_restore': mysql-cluster-programs-ndb-restore. Beginning with MySQL Cluster NDB 6.3.22, you can choose to restore only specified tables or databases, or exclude specific tables or databases from being restored, using the new *Note `ndb_restore': mysql-cluster-programs-ndb-restore. options `--include-tables', `--include-databases', `--exclude-tables', and `--exclude-databases'. Beginning with MySQL Cluster NDB 6.3.26, it is also possible to restore to a table having fewer columns than the original using the `--exclude-missing-columns' option. For more information about all of these options, see *Note mysql-cluster-programs-ndb-restore::. * Improved Disk Data file system configuration As of MySQL Cluster NDB 6.3.22, you can specify default locations for MySQL Cluster Disk Data data files and undo log files using the data node configuration parameters `FileSystemPathDD', `FileSystemPathDataFiles', and `FileSystemPathUndoFiles'. This eliminates the need to use symbolic links to place Disk Data files separately from other files in data node file systems to improve Disk Data performance. For more information, see *Note mysql-cluster-ndbd-disk-data-filesystem-parameters::. * Automatic creation of Disk Data log file groups and tablespaces Beginning with MySQL Cluster NDB 6.3.22, using the data node configuration parameters `InitialLogFileGroup' and `InitialTablespace', you can cause the creation of a MySQL Cluster Disk Data log file group, tablespace, or both, when the cluster is first started. When using these parameters, no SQL statements are required to create these Disk Data objects. For more information, see `Disk Data object creation parameters'. * Configuration parameter data dumps Starting with MySQL Cluster NDB 6.3.25, the *Note `ndb_config': mysql-cluster-programs-ndb-config. utility supports a `--configinfo' option that causes it to dump a list of all configuration parameters supported by the cluster, along with brief descriptions, information about the parameters' default and permitted values, and the sections of the `config.ini' file in which the parameters apply. An additional `--xml' switch causes *Note `ndb_config': mysql-cluster-programs-ndb-config. to use XML rather than plaintext output. Using *Note `ndb_config `--configinfo'': mysql-cluster-programs-ndb-config. or *Note `ndb_config `--configinfo --xml'': mysql-cluster-programs-ndb-config. requires no access to a running MySQL Cluster, any other programs, or any files. For more information and examples, see *Note mysql-cluster-programs-ndb-config::. * Per-table reporting of free space on disk The *Note `INFORMATION_SCHEMA.FILES': files-table. table shows information about used and free space in MySQL Cluster Disk Data data files, but this information is not applicable to individual tables. In MySQL Cluster NDB 6.3.27 and later, the *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility provides two additional columns in its output that show the amount of space allocated on disk for a given *Note `NDB': mysql-cluster. table as well the amount of space that remains available for additional storage of disk-based column data for that table. For more information, see *Note mysql-cluster-programs-ndb-desc::. * Improved restart times Optimizations in redo log handling and other file system operations introduced in MySQL Cluster NDB 6.3.28 have the potential to reduce considerably the time required for restarts. While actual performance benefits observed in production setups will naturally vary depending on database size, hardware, and other conditions, our own preliminary testing has shown that these improvements can yield startup times that are faster than those typical of previous MySQL Cluster NDB 6.3 releases by a factor of 50 or more. * Increased flexibility in online upgrade procedure Previously, when performing an upgrade of a running MySQL cluster, the order in which the types of cluster nodes had to be upgraded was very strict. However, beginning with MySQL Cluster NDB 6.3.29, MySQL Cluster supports online upgrading of API nodes (including MySQL servers running as SQL nodes) before upgrading management nodes, data nodes, or both. *Important*: Before attempting to use this new upgrade functionality, see *Note mysql-cluster-rolling-restart::, for additional information, especially if you are planning an online upgrade from MySQL Cluster NDB 6.3 to MySQL Cluster NDB 7.0. * New replication conflict resolution strategy Beginning with MySQL Cluster NDB 6.3.31, the function `NDB$MAX_DELETE_WIN()' is available to implement `greatest timestamp, delete wins' conflict resolution. See *Note mysql-cluster-replication-ndb-max-delete-win::, for more information. * New `CHANGE MASTER TO' option for circular replication Beginning with MySQL Cluster NDB 6.3.31, the *Note `CHANGE MASTER TO': change-master-to. statement 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. (Log rotation and log deletion events are preserved.) See *Note change-master-to::, as well as *Note show-slave-status::, for more information. * Heartbeat thread policy and priority Beginning with MySQL Cluster NDB 6.3.32, a new configuration parameter `HeartbeatThreadPriority' makes it possible to set the policy and the priority for the heartbeat thread on management and API nodes. * Improved access to partitioning information The *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility now provides additional information about the partitioning of data stored in MySQL Cluster. Beginning with MySQL Cluster NDB 6.3.32, the `--blob-info' option causes this program to include partition information for *Note `BLOB': blob. tables in its output. Beginning with MySQL Cluster NDB 6.3.33, the `--extra-node-info' option causes *Note `ndb_desc': mysql-cluster-programs-ndb-desc. to include information about data distribution (that is, which table fragments are stored on which data nodes). Each of these options also requires the use of the `--extra-partition-info' option. Information about partition-to-node mappings can also be obtained using the `Table::getFragmentNodes()' method, also added in MySQL Cluster NDB 6.3.33. * Replication attribute promotion and demotion Beginning with MySQL Cluster NDB 6.3.33, MySQL Cluster Replication supports attribute promotion and demotion when replicating between columns of different but similar types on the master and the slave. For example, it is possible to promote an *Note `INT': integer-types. column on the master to a *Note `BIGINT': integer-types. column on the slave, and to demote a *Note `TEXT': blob. column to a *Note `VARCHAR': char. column. The implementation of type demotion 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, see *Note replication-features-attribute-promotion::. * Incompatible change in NDB API event reporting Beginning with MySQL Cluster NDB 6.3.34, DDL events are no longer reported on `Event' objects by default. Instead such event reporting must be enabled explicitly using the `Event::setReport()' method. For more information, see `Event::setReport()' (http://dev.mysql.com/doc/ndbapi/en/ndb-event-methods.html#ndb-event-setreport), and The `Event::EventReport' Type (http://dev.mysql.com/doc/ndbapi/en/ndb-event-types.html#ndb-event-eventreport). * Heartbeat ordering Beginning with MySQL Cluster NDB 6.3.35, it is possible to set a specific order for transmission of heartbeats between data nodes, using the `HeartbeatOrder' data node configuration parameter introduced in this version. This parameter can be useful in situations where multiple data nodes are running on the same host and a temporary disruption in connectivity between hosts would otherwise cause the loss of a node group (and thus failure of the cluster). * Relaxed `ndb_restore' column comparison rules When restoring data, ndb_restore compares the attributes of a column for equality with the definition of the column in the target table. However, not all of these attributes need to be the same for *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to be meaningful, safe and useful. Beginning with MySQL Cluster NDB 6.3.35, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. automatically ignores differences in certain column attributes which do not necessarily have to match between the version of the column in a backup and the version of that column in the MySQL Cluster to which the column data is being restored. These attributes include the following: * `COLUMN_FORMAT' setting (`FIXED', `DYNAMIC', or `DEFAULT') * `STORAGE' setting (`MEMORY' or `DISK') * The default value * The distribution key In such cases, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. reports any such differences to minimize any chance of user error. * `--add-drop-trigger' option for `mysqldump' Beginning with MySQL Cluster NDB 6.3.38, this option can be used to force all *Note `CREATE TRIGGER': create-trigger. statements in *Note `mysqldump': mysqldump. output to be preceded by a *Note `DROP TRIGGER IF EXISTS': drop-trigger. statement. * Skipping corrupted tables in `NDB' native backups Beginning with MySQL Cluster NDB 6.3.40, you can cause *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to ignore tables that are corrupted due to missing blob parts tables by using the the `--skip-broken-objects' option. When this option is used, such tables are skipped, and the restoration of any remaining uncorrupted tables in the backup continues. * Restoring from a NDB native backup to a differently-named database MySQL Cluster NDB 6.3.41 adds a new `--rewrite-database' option to *Note `ndb_restore': mysql-cluster-programs-ndb-restore, which makes it possible to restore to a database having a different name from that of the database in the backup. The option can be used multiple times, and it is possible to restore from more than one source database in the backup to a single target database (although no protection against table or other object name collision is provided). See *Note mysql-cluster-programs-ndb-restore::, for more information.  File: manual.info, Node: mysql-cluster-development-5-1-ndb-6-2, Next: mysql-cluster-development-5-1-ndb-6-1, Prev: mysql-cluster-development-5-1-ndb-6-3, Up: mysql-cluster-development 17.1.4.5 MySQL Cluster Development in MySQL Cluster NDB 6.2 ........................................................... The following list provides an overview of significant feature additions and changes made in MySQL Cluster NDB 6.2. All of the changes in this list are also available in MySQL Cluster NDB 6.3 . For more detailed information about all feature changes and bugfixes made in MySQL Cluster NDB 6.2, see `http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/mysql-cluster-news-6-2.html'. * Enhanced backup status reporting Backup status reporting has been improved, aided in part by the introduction of a `BackupReportFrequency' configuration parameter. * Multiple cluster connections per SQL node A single MySQL server acting as a MySQL Cluster SQL node can employ multiple connections to the cluster using the `--ndb-cluster-connection-pool' startup option for *Note `mysqld': mysqld. This option is described in `MySQL Cluster-Related Command Options for *Note `mysqld': mysqld.: `--ndb-cluster-connection-pool' option'. * New data access interface The `NdbRecord' interface provides a new and simplified data handler for use in NDB API applications. * New reporting commands The new management client `REPORT BackupStatus' and `REPORT MemoryUsage' commands provide better access to information about the status of MySQL Cluster backups and how much memory is being used by MySQL Cluster for data and index storage. See *Note mysql-cluster-mgm-client-commands::, for more information about the `REPORT' commands. In addition, in-progress status reporting is provided by the *Note `ndb_restore': mysql-cluster-programs-ndb-restore. utility; see *Note mysql-cluster-programs-ndb-restore::. * Improved memory allocation and configuration Memory is now allocated by the *Note `NDB': mysql-cluster. kernel to tables on a page-by-page basis, which significantly reduces the memory overhead required for maintaining *Note `NDBCLUSTER': mysql-cluster. tables. In addition, the `MaxAllocate' configuration parameter now makes it possible to set the maximum size of the allocation unit used for table memory. * Choice of fixed-width or variable-width columns You can control whether fixed-width or variable-width storage is used for a given column of an *Note `NDB': mysql-cluster. table by employing of the `COLUMN_FORMAT' specifier as part of the column's definition in a *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. statement. In addition, the ability to control whether a given column of an *Note `NDB': mysql-cluster. table is stored in memory or on disk, using the `STORAGE' specifier as part of the column's definition in a *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. statement. For more information, see *Note create-table::, and *Note alter-table::. * Controlling management client connections The `--bind-address' cluster management server startup option makes it possible to restrict management client connections to *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. to a single host (IP address or host name) and port, which can make MySQL Cluster management operations more secure. For more information about this option, see *Note mysql-cluster-programs-ndb-mgmd::. * Micro-GCPs Due to a change in the protocol for handling of global checkpoints (GCPs handled in this manner sometimes being referred to as `micro-GCPs'), it is now possible to control how often the GCI number is updated, and how often global checkpoints are written to disk, using the `TimeBetweenEpochs' and `TimeBetweenEpochsTimeout' configuration parameters. This improves the reliability and performance of MySQL Cluster Replication. * Core online schema change support Support for the online *Note `ALTER TABLE': alter-table. operations `ADD COLUMN', `ADD INDEX', and `DROP INDEX' is available. When the `ONLINE' keyword is used, the *Note `ALTER TABLE': alter-table. is noncopying, which means that indexes do not have to be re-created, which provides these benefits: * Single user mode is no longer required for *Note `ALTER TABLE': alter-table. operations that can be performed online. * Transactions can continue during *Note `ALTER TABLE': alter-table. operations that can be performed online. * Tables being altered online are not locked against access by other SQL nodes. However, such tables are locked against other operations on the _same_ SQL node for the duration of the *Note `ALTER TABLE': alter-table. We are working to overcome this limitation in a future MySQL Cluster release. Online *Note `CREATE INDEX': create-index. and *Note `DROP INDEX': drop-index. statements are also supported. Online changes can be suppressed using the `OFFLINE' key word. See *Note alter-table-online-operations::, *Note create-index::, and *Note drop-index::, for more detailed information. * `mysql.ndb_binlog_index' improvements More information has been added to the `mysql.ndb_binlog_index' table so that it is possible to determine which originating epochs have been applied inside an epoch. This is particularly useful for 3-way replication. See *Note mysql-cluster-replication-schema::, for more information. * Epoch lag control The `MaxBufferedEpochs' data node configuration parameter provides a means to control the maximum number of unprocessed epochs by which a subscribing node can lag. Subscribers which exceed this number are disconnected and forced to reconnect. * Fully automatic database discovery It is no longer a requirement for database autodiscovery that an SQL node already be connected to the cluster at the time that a database is created on another SQL node, or for a *Note `CREATE DATABASE': create-database. or *Note `CREATE SCHEMA': create-database. statement to be issued on the new SQL node after it joins the cluster. * Multiple data node processes per host In earlier MySQL Cluster release series, we did not support MySQL Cluster deployments in production where more than one *Note `ndbd': mysql-cluster-programs-ndbd. process was run on a single physical machine. However, beginning with MySQL Cluster NDB 6.2.0, you can use multiple data node processes on a single host. *Note*: A multi-threaded version of *Note `ndbd': mysql-cluster-programs-ndbd. tailored for use on hosts with multiple CPUs or cores was introduced in MySQL Cluster NDB 7.0. See *Note mysql-cluster-development-5-1-ndb-7-0::, and *Note mysql-cluster-programs-ndbmtd::, for more information. * Improved Disk Data file system configuration As of MySQL Cluster NDB 6.2.17, you can specify default locations for MySQL Cluster Disk Data data files and undo log files using the data node configuration parameters `FileSystemPathDD', `FileSystemPathDataFiles', and `FileSystemPathUndoFiles'. This eliminates the need to use symbolic links to place Disk Data files separately from other files in data node file systems to improve Disk Data performance. For more information, see *Note mysql-cluster-ndbd-disk-data-filesystem-parameters::. * Automatic creation of Disk Data log file groups and tablespaces Beginning with MySQL Cluster NDB 6.2.17, using the data node configuration parameters `InitialLogFileGroup' and `InitialTablespace', you can cause the creation of a MySQL Cluster Disk Data log file group, tablespace, or both, when the cluster is first started. When using these parameters, no SQL statements are required to create these Disk Data objects. * Improved access to partitioning information The *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility now provides additional information about the partitioning of data stored in MySQL Cluster. Beginning with MySQL Cluster NDB 6.2.19, the `--extra-node-info' option causes *Note `ndb_desc': mysql-cluster-programs-ndb-desc. to include information about data distribution (that is, which table fragments are stored on which data nodes). This option also requires the use of the `--extra-partition-info' option. Information about partition-to-node mappings can also be obtained using the `Table::getFragmentNodes()' method, also added in MySQL Cluster NDB 6.2.19. * New `CHANGE MASTER TO' option for circular replication Beginning with MySQL Cluster NDB 6.2.19, the *Note `CHANGE MASTER TO': change-master-to. statement 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. (Log rotation and log deletion events are preserved.) See *Note change-master-to::, as well as *Note show-slave-status::, for more information.  File: manual.info, Node: mysql-cluster-development-5-1-ndb-6-1, Next: mysql-cluster-development-5-1, Prev: mysql-cluster-development-5-1-ndb-6-2, Up: mysql-cluster-development 17.1.4.6 MySQL Cluster Development in MySQL Cluster NDB 6.1 ........................................................... The following list provides an overview of significant feature additions and changes made in MySQL Cluster NDB 6.1. All of the changes in this list are also available in MySQL Cluster NDB 6.2 and 6.3 releases. For detailed information about all changes made in MySQL Cluster NDB 6.1, see `http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/mysql-cluster-news-6-1.html'. * Increased number of cluster nodes The maximum number of all nodes in a MySQL Cluster has been increased to 255. For more information, see *Note mysql-cluster-limitations-multiple-nodes::. * Disabling arbitration It is now possible to disable arbitration by setting `ArbitrationRank=0' on all cluster management and SQL nodes. For more information, see `Defining the Management Server: `ArbitrationRank'' and `Defining SQL and Other API Nodes: `ArbitrationRank''. * Additional `DUMP' commands New management client `DUMP' commands provide help with tracking transactions, scan operations, and locks. See *Note mysql-cluster-mgm-client-commands::, and `DUMP' Commands (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-dump-commands.html), for more information. * Faster Disk Data backups Improvements in backups of Disk Data tables can yield a 10 to 15% increase in backup speed of Disk Data tables. * Batched slave updates Batching of updates on cluster replication slaves, enabled using the `--slave-allow-batching' option for *Note `mysqld': mysqld, increases replication efficiency. For more information, see *Note mysql-cluster-replication-starting::.  File: manual.info, Node: mysql-cluster-development-5-1, Prev: mysql-cluster-development-5-1-ndb-6-1, Up: mysql-cluster-development 17.1.4.7 Development History of MySQL Cluster in MySQL 5.1 .......................................................... A number of features for MySQL Cluster were implemented in MySQL 5.1 through MySQL 5.1.23, when support for MySQL Cluster was moved to MySQL Cluster NDB. All of the features in the following list are also available in all MySQL Cluster NDB (6.1 and later) releases. * Integration of MySQL Cluster into MySQL Replication MySQL Cluster Replication makes it possible to replicate from one MySQL Cluster to another. Updates on any SQL node (MySQL server) in the cluster acting as the master are replicated to the slave cluster; the state of the slave side remains consistent with the cluster acting as the master. This is sometimes referred to as _asynchronous replication_ between clusters, providing _geographic redundancy_. It is also possible to replicate from a MySQL Cluster acting as the master to a standalone MySQL server acting as the slave, or from a standalone MySQL master server to to a slave cluster; in either of these cases, the standalone MySQL server uses a storage engine other than *Note `NDBCLUSTER': mysql-cluster. Multi-master replication setups such as circular replication are also supported. See *Note mysql-cluster-replication::. * Support for storage of rows on disk Storage of *Note `NDBCLUSTER': mysql-cluster. table data on disk is now supported. Indexed columns, including the primary key hash index, must still be stored in RAM; however, all other columns can be stored on disk. See *Note mysql-cluster-disk-data::. * Variable-size columns In MySQL 5.0, an *Note `NDBCLUSTER': mysql-cluster. table column defined as `VARCHAR(255)' used 260 bytes of storage independent of what was stored in any particular record. In MySQL 5.1 Cluster tables, only the portion of the column actually taken up by the record is stored. This makes possible a significant reduction in space requirements for such columns as compared to previous release series--by a factor of up to 5 in many cases. * User-defined partitioning Users can define partitions based on columns that are part of the primary key. It is possible to partition *Note `NDB': mysql-cluster. tables based on `KEY' and `LINEAR KEY' schemes. This feature is also available for many other MySQL storage engines, which support additional partitioning types that are not available with *Note `NDBCLUSTER': mysql-cluster. tables. For additional general information about user-defined partitioning in MySQL 5.1, see *Note partitioning::. Specifics of partitioning types are discussed in *Note partitioning-types::. The MySQL Server can also determine whether it is possible to `prune away' some of the partitions from the `WHERE' clause, which can greatly speed up some queries. See *Note partitioning-pruning::, for information about designing tables and queries to take advantage of partition pruning. * Autodiscovery of table schema changes In MySQL 5.0, it was necessary to issue a *Note `FLUSH TABLES': flush. statement or a `dummy' *Note `SELECT': select. for new *Note `NDBCLUSTER': mysql-cluster. tables or changes made to schemas of existing *Note `NDBCLUSTER': mysql-cluster. tables on one SQL node to be visible on the cluster's other SQL nodes. In MySQL 5.1, this is no longer necessary; new Cluster tables and changes in the definitions of existing *Note `NDBCLUSTER': mysql-cluster. tables made on one SQL node are immediately visible to all SQL nodes connected to the cluster. *Note*: When creating a new database, it is still necessary in MySQL 5.1 to issue a *Note `CREATE DATABASE': create-database. or *Note `CREATE SCHEMA': create-database. statement on each SQL node in the cluster. * Distribution awareness (NDB API) _Distribution awareness_ is a mechanism by which the best data node is automatically selected to be queried for information. (Conceptually, it is similar in some ways to partition pruning (see *Note partitioning-pruning::). To take advantage of distribution awareness, you should do the following: 1. Determine which table column is most likely to be used for finding matching records. 2. Make this column part of the table's primary key. 3. Explicitly partition the table by `KEY', using this column as the table' partitioning key. Following these steps causes records with the same value for the partitioning column to be stored on the same partition (that is, in the same node group). When reading data, transactions are begun on the data node actually having the desired rows instead of this node being determined by the usual round-robin mechanism. *Important*: To see a measureable impact on performance, the cluster must have at least four data nodes, since, with only two data nodes, both data nodes have exactly the same data. Using distribution awareness can yield performance increase of as great as 45% when using four data nodes, and possibly more when using a greater number of data nodes. *Note*: In mainline MySQL 5.1 releases, distribution awareness was supported only when using the NDB API; support was added for SQL and API nodes in MySQL Cluster NDB 6.3 (see *Note mysql-cluster-development-5-1-ndb-6-3::, which includes an example showing how to create a table to take advantage of distribution awareness). * Online adding and dropping of indexes For *Note `ALTER TABLE': alter-table. statements, `ADD INDEX' and `DROP INDEX' operations for dynamic (variable-width) columns on *Note `NDB': mysql-cluster. tables are now performed as online operations (no table copying). This is also true for *Note `CREATE INDEX': create-index. and *Note `DROP INDEX': drop-index. As a result, these operations are now performed much more quickly than previously. For more information, see *Note alter-table-online-operations::, *Note create-index::, and *Note drop-index::. See *Note mysql-cluster-limitations-resolved::, for more information.  File: manual.info, Node: mysql-cluster-compared, Next: mysql-cluster-limitations, Prev: mysql-cluster-development, Up: mysql-cluster-overview 17.1.5 MySQL Server Using `InnoDB' Compared with MySQL Cluster -------------------------------------------------------------- * Menu: * mysql-cluster-ndb-innodb-engines:: Differences Between the `NDB' and `InnoDB' Storage Engines * mysql-cluster-ndb-innodb-workloads:: `NDB' and `InnoDB' Workloads * mysql-cluster-ndb-innodb-usage:: `NDB' and `InnoDB' Feature Usage Summary MySQL Server offers a number of choices in storage engines. Since both *Note `NDBCLUSTER': mysql-cluster. and *Note `InnoDB': innodb-storage-engine. can serve as transactional MySQL storage engines, users of MySQL Server sometimes become interested in MySQL Cluster. They see *Note `NDB': mysql-cluster. as a possible alternative or upgrade to the default *Note `InnoDB': innodb-storage-engine. storage engine in MySQL 5.5. While *Note `NDB': mysql-cluster. and *Note `InnoDB': innodb-storage-engine. 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 MySQL Cluster, but not all of them. In this section, we discuss and compare some characteristics of the *Note `NDB': mysql-cluster. storage engine used by MySQL Cluster with *Note `InnoDB': innodb-storage-engine. used in MySQL 5.1 and MySQL 5.5. The next few sections provide a technical comparison. In many instances, decisions about when and where to use MySQL 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 *Note `NDB': mysql-cluster. as opposed to *Note `InnoDB': innodb-storage-engine. backends. While it is possible to use *Note `InnoDB': innodb-storage-engine. tables with MySQL Cluster, such tables are not clustered. MySQL Cluster NDB 7.1 releases use a *Note `mysqld': mysqld. based on MySQL 5.1 which includes `InnoDB' 1.0; MySQL Cluster NDB 7.2.1 and later are based on MySQL Server 5.5, which includes support for `InnoDB' 1.1. It is also not possible to use programs or libraries from a MySQL Cluster NDB 6.x or MySQL Cluster NDB 7.x distribution with MySQL Server 5.1 or MySQL Server 5.5, or the reverse. While it is also true that some types of common business applications can be run either on MySQL Cluster or on MySQL Server (most likely using the *Note `InnoDB': innodb-storage-engine. storage engine), there are some important architectural and implementation differences. *Note 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 *Note mysql-cluster-ndb-innodb-workloads::. This in turn has an impact on the types of applications that better suited for use with *Note `NDB': mysql-cluster. or *Note `InnoDB': innodb-storage-engine. See *Note 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 *Note `NDB': mysql-cluster. and *Note `MEMORY': memory-storage-engine. storage engines, see *Note memory-compared-cluster::. See *Note storage-engines::, for additional information about MySQL storage engines.  File: manual.info, Node: mysql-cluster-ndb-innodb-engines, Next: mysql-cluster-ndb-innodb-workloads, Prev: mysql-cluster-compared, Up: mysql-cluster-compared 17.1.5.1 Differences Between the `NDB' and `InnoDB' Storage Engines ................................................................... The MySQL Cluster *Note `NDB': mysql-cluster. storage engine is implemented using a distributed, shared-nothing architecture, which causes it to behave differently from *Note `InnoDB': innodb-storage-engine. in a number of ways. For those unaccustomed to working with *Note `NDB': mysql-cluster, unexpected behaviors can arise due to its distributed nature with regard to transactions, foreign keys, joins, and other characteristics. These are shown in the following table: This table lists feature differences between *Note `InnoDB': innodb-storage-engine. and *Note `NDB': mysql-cluster. storage engines. Feature *Note `InnoDB': MySQL Cluster innodb-storage-engine. _MySQL Server Version_ `InnoDB' 1.1: 5.5 MySQL Cluster NDB 6.3, 7.0, 7.1: 5.1 `InnoDB' 1.0: 5.1 MySQL Cluster NDB 7.2: 5.5 _`InnoDB' Availability _ *Note `InnoDB': _NDB 6.3, 7.0_: *Note innodb-storage-engine. `InnoDB': 1.1 plugin innodb-storage-engine. storage engine _NDB 7.1_: *Note `InnoDB': innodb-storage-engine. 1.0 plugin support (MySQL Cluster NDB 7.1.9a and later) _NDB 7.2_: *Note `InnoDB': innodb-storage-engine. 1.1 (MySQL Cluster NDB 7.2.1 and later) _Storage Limits_ 64TB 3TB (Practical upper limit based on 48 data nodes with 64GB RAM each; can be increased with disk-based data and BLOBs) _Foreign Keys_ Yes No (Ignored, as with *Note `MyISAM': myisam-storage-engine.) *Note*: A MySQL Cluster NDB 7.3 Development Milestone Release that includes a preview of foreign key support for the *Note `InnoDB': innodb-storage-engine. storage engine is now available. See `http://dev.mysql.com/tech-resources/articles/mysql-cluster-7.3.html', for more information. _Transactions_ All standard types `READ COMMITTED' _MVCC_ Yes No _Data Compression_ Yes No (MySQL Cluster checkpoint and backup files can be compressed) _Large Row Support (> Supported for *Note Supported for *Note 14K)_ `VARBINARY': `BLOB': blob. and *Note binary-varbinary, `TEXT': blob. columns `VARCHAR', *Note only `BLOB': blob, and *Note `TEXT': blob. columns (Using these types to store very large amounts of data can lower MySQL Cluster performance) _Replication Support_ Asynchronous and Automatic synchronous semi-synchronous replication within a replication using MySQL MySQL Cluster. Replication Asynchronous replication between MySQL Clusters, using MySQL Replication _Scaleout for Read Yes (MySQL Replication) Yes (Automatic Operations_ partitioning in MySQL Cluster; MySQL Replication) _Scaleout for Write Requires Yes (Automatic Operations_ application-level partitioning in MySQL partitioning (sharding) Cluster is transparent to applications) _High Availability (HA)_ Requires additional Yes (Designed for software 99.999% uptime) _Node Failure Recovery Requires additional Automatic and Failover_ software (Key element in MySQL Cluster architecture) _Time for Node Failure 30 seconds or longer Typically < 1 second Recovery_ _Real-Time Performance_ No Yes _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 Native memcached Yes Storage Engine _ interface in development (see the Multiple APIs, MySQL Dev Zone article including C++, `NoSQL to MySQL with HTTP/REST, Java and JPA Memcached' (MySQL Cluster NDB 7.1 (https://dev.mysql.com/tech-resources/articles/nosql-to-mysql-with-memcached.html))and later); Memcached (MySQL Cluster NDB 7.2 and later); Node.js under development (MySQL Cluster NDB 7.3) _Concurrent and Not supported Up to 48 writers, Parallel Writes_ optimized for concurrent writes _Conflict Detection and No Yes Resolution (Multiple Replication Masters)_ _Hash Indexes_ No Yes _Online Addition of Read-only replicas Yes (all node types) Nodes_ using MySQL Replication _Online Upgrades_ No Yes _Online Schema No Yes Modifications_  File: manual.info, Node: mysql-cluster-ndb-innodb-workloads, Next: mysql-cluster-ndb-innodb-usage, Prev: mysql-cluster-ndb-innodb-engines, Up: mysql-cluster-compared 17.1.5.2 `NDB' and `InnoDB' Workloads ..................................... MySQL 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, MySQL Cluster also has specific constraints that may keep some workloads from performing well. A number of major differences in behavior between the *Note `NDB': mysql-cluster. and *Note `InnoDB': innodb-storage-engine. storage engines with regard to some common types of database-driven application workloads are shown in the following table:: This table lists major differences in behavior between *Note `InnoDB': innodb-storage-engine. and *Note `NDB': mysql-cluster. storage engines with regard to common types of database-driven application workloads. Workload *Note `InnoDB': MySQL Cluster (*Note innodb-storage-engine. `NDB': mysql-cluster.) _High-Volume OLTP Yes Yes Applications_ _DSS Applications (data Yes Limited (Join marts, analytics)_ operations across OLTP datasets not exceeding 3TB in size) _Custom Applications_ Yes Yes _Packaged Applications_ Yes Limited (should be mostly primary key access, without any requirement for foreign keys) *Note*: A MySQL Cluster NDB 7.3 Development Milestone Release that includes a preview of foreign key support for the *Note `InnoDB': innodb-storage-engine. storage engine is now available. See `http://dev.mysql.com/tech-resources/articles/mysql-cluster-7.3.html', for more information. _In-Network Telecoms No Yes Applications (HLR, HSS, SDP)_ _Session Management and Yes Yes Caching_ _E-Commerce Yes Yes Applications_ _User Profile Yes Yes Management, AAA Protocol_  File: manual.info, Node: mysql-cluster-ndb-innodb-usage, Prev: mysql-cluster-ndb-innodb-workloads, Up: mysql-cluster-compared 17.1.5.3 `NDB' and `InnoDB' Feature Usage Summary ................................................. When comparing application feature requirements to the capabilities of *Note `InnoDB': innodb-storage-engine. with *Note `NDB': mysql-cluster, some are clearly more compatible with one storage engine than the other. For example, since *Note `NDB': mysql-cluster. does not support foreign keys, an application that requires them and cannot be re-engineered to remove this requirement is likely not to be a good match for MySQL Cluster. *Note*: A MySQL Cluster NDB 7.3 Development Milestone Release that includes a preview of foreign key support for the *Note `InnoDB': innodb-storage-engine. storage engine is now available. See `http://dev.mysql.com/tech-resources/articles/mysql-cluster-7.3.html', for more information. The following table lists supported application features according to the storage engine to which each feature is typically better suited. This table lists supported application features according to the storage engine to which each feature is typically better suited. Preferred application requirements Preferred application requirements for *Note `InnoDB': for *Note `NDB': mysql-cluster. innodb-storage-engine. * Foreign keys * Write scaling *Note*: * 99.999% uptime A MySQL Cluster NDB 7.3 * Online addition of nodes and Development Milestone Release online schema operations that includes a preview of foreign key support for the * Multiple SQL and NoSQL APIs *Note `InnoDB': (see MySQL Cluster APIs: innodb-storage-engine. storage Overview and Concepts engine is now available. See (http://dev.mysql.com/doc/ndbapi/en/mysql-cluster-api-overview.html)) `http://dev.mysql.com/tech-resources/articles/mysql-cluster-7.3.html', for more information. * Real-time performance * Full table scans * Limited use of *Note `BLOB': blob. columns * Very large databases, rows, or transactions * Transactions other than `READ COMMITTED'  File: manual.info, Node: mysql-cluster-limitations, Prev: mysql-cluster-compared, Up: mysql-cluster-overview 17.1.6 Known Limitations of MySQL Cluster ----------------------------------------- * Menu: * mysql-cluster-limitations-syntax:: Noncompliance with SQL Syntax in MySQL Cluster * mysql-cluster-limitations-limits:: Limits and Differences of MySQL Cluster from Standard MySQL Limits * mysql-cluster-limitations-transactions:: Limits Relating to Transaction Handling in MySQL Cluster * mysql-cluster-limitations-error-handling:: MySQL Cluster Error Handling * mysql-cluster-limitations-database-objects:: Limits Associated with Database Objects in MySQL Cluster * mysql-cluster-limitations-unsupported:: Unsupported or Missing Features in MySQL Cluster * mysql-cluster-limitations-performance:: Limitations Relating to Performance in MySQL Cluster * mysql-cluster-limitations-exclusive-to-cluster:: Issues Exclusive to MySQL Cluster * mysql-cluster-limitations-disk-data:: Limitations Relating to MySQL Cluster Disk Data Storage * mysql-cluster-limitations-multiple-nodes:: Limitations Relating to Multiple MySQL Cluster Nodes * mysql-cluster-limitations-resolved:: Previous MySQL Cluster Issues Resolved in MySQL 5.1, MySQL Cluster NDB 6.x, and MySQL Cluster NDB 7.x In the sections that follow, we discuss known limitations in current releases of MySQL 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 MySQL Cluster: * MySQL 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 *Note bug-reports::. If we do not plan to fix the problem in MySQL Cluster NDB 6.X or 7.X, we will add it to the list. See *Note mysql-cluster-limitations-resolved:: for a list of issues in MySQL Cluster in MySQL 5.0 that have been resolved in the current version. *Note*: Limitations and other issues specific to MySQL Cluster Replication are described in *Note mysql-cluster-replication-issues::.  File: manual.info, Node: mysql-cluster-limitations-syntax, Next: mysql-cluster-limitations-limits, Prev: mysql-cluster-limitations, Up: mysql-cluster-limitations 17.1.6.1 Noncompliance with SQL Syntax in MySQL Cluster ....................................................... Some SQL statements relating to certain MySQL features produce errors when used with *Note `NDB': mysql-cluster. tables, as described in the following list: * Temporary tables Temporary tables are not supported. Trying either to create a temporary table that uses the *Note `NDB': mysql-cluster. storage engine or to alter an existing temporary table to use *Note `NDB': mysql-cluster. 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 MySQL 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 *Note `SHOW CREATE TABLE': show-create-table. statement shows the length of the index as 3072. * `TEXT' and `BLOB' columns You cannot create indexes on *Note `NDB': mysql-cluster. table columns that use any of the *Note `TEXT': blob. or *Note `BLOB': blob. data types. * `FULLTEXT' indexes The *Note `NDB': mysql-cluster. storage engine does not support `FULLTEXT' indexes, which are possible for `MyISAM' tables only. However, you can create indexes on *Note `VARCHAR': char. columns of *Note `NDB': mysql-cluster. 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 *Note mysql-cluster-limitations-unsupported::, for additional information.) * `BIT' columns A *Note `BIT': bit-type. 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 *Note `NDB': mysql-cluster. storage engine can handle a maximum of one `AUTO_INCREMENT' column per table. However, in the case of a Cluster 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 *Note `NDB': mysql-cluster. storage engine, fails with an error. * MySQL Cluster and geometry data types Geometry data types (`WKT' and `WKB') are supported in *Note `NDB': mysql-cluster. tables in MySQL 5.1 (including MySQL Cluster NDB 6.X and 7.X through 7.1). 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 `NDBCLUSTER' tables with user-defined partitioning Support for user-defined partitioning for MySQL Cluster is restricted to [`LINEAR'] `KEY' partitioning. Beginning with MySQL 5.1.12, using any other partitioning type with `ENGINE=NDB' or `ENGINE=NDBCLUSTER' in a *Note `CREATE TABLE': create-table. statement results in an error. Default partitioning scheme As of MySQL 5.1.6, all MySQL 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 *Note `NDBCLUSTER': mysql-cluster. storage engine is used instead. For additional discussion of these and related issues, see *Note partitioning-key::. Beginning with MySQL Cluster NDB 6.2.18, MySQL Cluster NDB 6.3.25, and MySQL Cluster NDB 7.0.6, *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': alter-table. statements that would cause a user-partitioned *Note `NDBCLUSTER': mysql-cluster. table not to meet either or both of the following two requirements are not permitted, and fail with an error (Bug #40709): 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 *Note `NDBCLUSTER': mysql-cluster. 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 *Note `NDBCLUSTER': mysql-cluster. table when employing user-defined partitioning is 8 per node group. (See *Note mysql-cluster-nodes-groups::, for more information about MySQL Cluster node groups. `DROP PARTITION' not supported It is not possible to drop partitions from *Note `NDB': mysql-cluster. tables using `ALTER TABLE ... DROP PARTITION'. The other partitioning extensions to *Note `ALTER TABLE': alter-table.--`ADD PARTITION', `REORGANIZE PARTITION', and `COALESCE PARTITION'--are supported for Cluster tables, but use copying and so are not optimized. See *Note partitioning-management-range-list:: and *Note alter-table::. * Row-based replication When using row-based replication with MySQL Cluster, binary logging cannot be disabled. That is, the *Note `NDB': mysql-cluster. storage engine ignores the value of `sql_log_bin'. (Bug #16680)  File: manual.info, Node: mysql-cluster-limitations-limits, Next: mysql-cluster-limitations-transactions, Prev: mysql-cluster-limitations-syntax, Up: mysql-cluster-limitations 17.1.6.2 Limits and Differences of MySQL Cluster from Standard MySQL Limits ........................................................................... In this section, we list limits found in MySQL 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 *Note `NDB': mysql-cluster. table is not automatically recovered when deleted, as it is with other storage engines. Instead, the following rules hold true: * A *Note `DELETE': delete. statement on an *Note `NDB': mysql-cluster. 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 a rolling restart of the cluster. See *Note mysql-cluster-rolling-restart::. Beginning with MySQL Cluster NDB 6.3.7, this limitation can be overcome using *Note `OPTIMIZE TABLE': optimize-table. See *Note mysql-cluster-limitations-resolved::, for more information. * A *Note `DROP TABLE': drop-table. or *Note `TRUNCATE TABLE': truncate-table. operation on an *Note `NDB': mysql-cluster. table frees the memory that was used by this table for re-use by any *Note `NDB': mysql-cluster. table, either by the same table or by another *Note `NDB': mysql-cluster. table. *Note*: Recall that *Note `TRUNCATE TABLE': truncate-table. drops and re-creates the table. See *Note 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 *Note 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 *Note 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, *Note `TRUNCATE TABLE': truncate-table, and *Note `ALTER TABLE': 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. (Previous to MySQL Cluster NDB 6.1.1, management and API nodes were restricted to the range 1 to 63 inclusive as a node ID; starting with MySQL Cluster NDB 6.1.1, management and API nodes may use node IDs in the range 1 to 255, inclusive.) * Prior to MySQL Cluster NDB 6.1.1, the total maximum number of nodes in a MySQL Cluster was 63. Beginning with MySQL Cluster NDB 6.1.1, the total maximum number of nodes in a MySQL Cluster is 255. In either case, 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 MySQL Cluster is 20320. This limit is hard-coded. See *Note mysql-cluster-limitations-resolved::, for more information.  File: manual.info, Node: mysql-cluster-limitations-transactions, Next: mysql-cluster-limitations-error-handling, Prev: mysql-cluster-limitations-limits, Up: mysql-cluster-limitations 17.1.6.3 Limits Relating to Transaction Handling in MySQL Cluster ................................................................. A number of limitations exist in MySQL Cluster with regard to the handling of transactions. These include the following: * Transaction isolation level The *Note `NDBCLUSTER': mysql-cluster. storage engine supports only the `READ COMMITTED' transaction isolation level. (`InnoDB', for example, supports `READ COMMITTED', `READ UNCOMMITTED', `REPEATABLE READ', and `SERIALIZABLE'.) See *Note mysql-cluster-backup-troubleshooting::, for information on how this can affect backing up and restoring Cluster databases.) * Transactions and `BLOB' or `TEXT' columns *Note `NDBCLUSTER': mysql-cluster. stores only part of a column value that uses any of MySQL's *Note `BLOB': blob. or *Note `TEXT': blob. data types in the table visible to MySQL; the remainder of the *Note `BLOB': blob. or *Note `TEXT': blob. 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 *Note `SELECT': select. statements on tables that contain columns of these types: 1. For any *Note `SELECT': select. from a MySQL Cluster table: If the *Note `SELECT': select. includes a *Note `BLOB': blob. or *Note `TEXT': blob. column, the `READ COMMITTED' transaction isolation level is converted to a read with read lock. This is done to guarantee consistency. 2. Prior to MySQL Cluster NDB 7.0.12, for any *Note `SELECT': select. which used a primary key lookup or unique key lookup to retrieve any columns that used any of the *Note `BLOB': blob. or *Note `TEXT': blob. data types and that was executed within a transaction, a shared read lock was held on the table for the duration of the transaction--that is, until the transaction was either committed or aborted. In MySQL Cluster NDB 7.0.12 and later, for primary key lookups, the lock is released as soon as all *Note `BLOB': blob. or *Note `TEXT': blob. data has been read. (Bug #49190) However, for unique key lookups, the shared lock continues to be held for the lifetime of the transaction. This issue does not occur for queries that use index or table scans, even against *Note `NDB': mysql-cluster. tables having *Note `BLOB': blob. or *Note `TEXT': blob. columns. For example, consider the table `t' defined by the following *Note `CREATE TABLE': 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 *Note `BLOB': blob. or *Note `TEXT': blob. columns. You can help minimize issues with shared read locks by avoiding queries that use unique key lookups (or primary key lookups in MySQL Cluster NDB 7.0.11 and earlier) that retrieve *Note `BLOB': blob. or *Note `TEXT': blob. 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 *Note `InnoDB': innodb-storage-engine. that may roll back individual statements. * Transactions and memory usage As noted elsewhere in this chapter, MySQL 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 effected as described in the following list: * *Note `TRUNCATE TABLE': truncate-table. is not transactional when used on *Note `NDB': mysql-cluster. tables. If a *Note `TRUNCATE TABLE': 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 *Note `TRUNCATE TABLE': truncate-table. instead. * `LOAD DATA' statements *Note `LOAD DATA INFILE': load-data. is not transactional when used on *Note `NDB': mysql-cluster. tables. *Important*: When executing a *Note `LOAD DATA INFILE': load-data. statement, the *Note `NDB': mysql-cluster. 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. *Note `LOAD DATA FROM MASTER': load-data-from-master. is not supported in MySQL Cluster. * `ALTER TABLE' and transactions When copying an *Note `NDB': mysql-cluster. table as part of an *Note `ALTER TABLE': 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 MySQL 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 (*Note `INSERT': insert, *Note `DELETE': 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 *Note `NDB': mysql-cluster. storage engine. (See Bug #31321 for more information.)  File: manual.info, Node: mysql-cluster-limitations-error-handling, Next: mysql-cluster-limitations-database-objects, Prev: mysql-cluster-limitations-transactions, Up: mysql-cluster-limitations 17.1.6.4 MySQL 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 *Note mysql-cluster-limitations-limits::.  File: manual.info, Node: mysql-cluster-limitations-database-objects, Next: mysql-cluster-limitations-unsupported, Prev: mysql-cluster-limitations-error-handling, Up: mysql-cluster-limitations 17.1.6.5 Limits Associated with Database Objects in MySQL Cluster ................................................................. Some database objects such as tables and indexes have different limitations when using the *Note `NDBCLUSTER': mysql-cluster. storage engine: * Table names containing special characters *Note `NDB': mysql-cluster. tables whose names contain characters other than letters, numbers, dashes, and underscores and which are created on one SQL node were not always discovered correctly by other SQL nodes. (Bug #31470) *Note*: This issue was fixed in MySQL 5.1.23, MySQL Cluster NDB 6.2.7, and MySQL Cluster NDB 6.3.4. * Number of database objects The maximum number of _all_ *Note `NDB': mysql-cluster. database objects in a single MySQL Cluster--including databases, tables, and indexes--is limited to 20320. * Attributes per table Prior to MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, the maximum number of attributes (that is, columns and indexes) per table is limited to 128. Beginning with MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, this limit is increased to 512. * Attributes per key The maximum number of attributes per key is 32. * Row size Prior to MySQL Cluster NDB 7.0, the maximum permitted size of any one row was 8052 bytes; in MySQL Cluster NDB 7.0 and later, this is 14000 bytes. Each *Note `BLOB': blob. or *Note `TEXT': blob. column contributes 256 + 8 = 264 bytes to this total.  File: manual.info, Node: mysql-cluster-limitations-unsupported, Next: mysql-cluster-limitations-performance, Prev: mysql-cluster-limitations-database-objects, Up: mysql-cluster-limitations 17.1.6.6 Unsupported or Missing Features in MySQL Cluster ......................................................... A number of features supported by other storage engines are not supported for *Note `NDB': mysql-cluster. tables. Trying to use any of these features in MySQL Cluster does not cause errors in or of itself; however, errors may occur in applications that expects the features to be supported or enforced: * Foreign key constraints The foreign key construct is ignored, just as it is in `MyISAM' tables. * Index prefixes Prefixes on indexes are not supported for `NDBCLUSTER' tables. If a prefix is used as part of an index specification in a statement such as *Note `CREATE TABLE': create-table, *Note `ALTER TABLE': alter-table, or *Note `CREATE INDEX': create-index, the prefix is ignored. * `OPTIMIZE' operations `OPTIMIZE' operations are not supported. Beginning with MySQL Cluster NDB 6.3.7, this limitation has been lifted. See *Note mysql-cluster-limitations-resolved::, for more information. * `LOAD TABLE ... FROM MASTER' *Note `LOAD TABLE FROM MASTER': load-table-from-master. is not supported. * 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 *Note mysql-cluster-replication::, for more information. *Note*: See *Note mysql-cluster-limitations-transactions::, for more information relating to limitations on transaction handling in *Note `NDB': mysql-cluster.  File: manual.info, Node: mysql-cluster-limitations-performance, Next: mysql-cluster-limitations-exclusive-to-cluster, Prev: mysql-cluster-limitations-unsupported, Up: mysql-cluster-limitations 17.1.6.7 Limitations Relating to Performance in MySQL Cluster ............................................................. The following performance issues are specific to or especially pronounced in MySQL Cluster: * Range scans There are query performance issues due to sequential access to the *Note `NDB': mysql-cluster. 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 *Note 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.  File: manual.info, Node: mysql-cluster-limitations-exclusive-to-cluster, Next: mysql-cluster-limitations-disk-data, Prev: mysql-cluster-limitations-performance, Up: mysql-cluster-limitations 17.1.6.8 Issues Exclusive to MySQL Cluster .......................................... The following are limitations specific to the *Note `NDBCLUSTER': mysql-cluster. 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 *Note `mysql': mysql. or other clients that may be accessing the cluster's SQL nodes. * Binary logging MySQL 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. * MySQL Cluster cannot produce a binary log for tables having *Note `BLOB': blob. columns but no primary key. * Only the following schema operations are logged in a cluster binary log which is _not_ on the *Note `mysqld': mysqld. executing the statement: * *Note `CREATE TABLE': create-table. * *Note `ALTER TABLE': alter-table. * *Note `DROP TABLE': drop-table. * *Note `CREATE DATABASE': create-database. / *Note `CREATE SCHEMA': create-database. * *Note `DROP DATABASE': drop-database. / *Note `DROP SCHEMA': drop-database. * *Note `CREATE TABLESPACE': create-tablespace. * *Note `ALTER TABLESPACE': alter-tablespace. * *Note `DROP TABLESPACE': drop-tablespace. * *Note `CREATE LOGFILE GROUP': create-logfile-group. * *Note `ALTER LOGFILE GROUP': alter-logfile-group. * *Note `DROP LOGFILE GROUP': drop-logfile-group. See also *Note mysql-cluster-limitations-multiple-nodes::.  File: manual.info, Node: mysql-cluster-limitations-disk-data, Next: mysql-cluster-limitations-multiple-nodes, Prev: mysql-cluster-limitations-exclusive-to-cluster, Up: mysql-cluster-limitations 17.1.6.9 Limitations Relating to MySQL 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) * Maximum data file size: The theoretical limit is 64G; however, in MySQL 5.1 (including MySQL Cluster NDB 6.X and 7.X through 7.1), the practical upper limit is 32G. This is equivalent to 32768 extents of 1M each. Since a MySQL Cluster Disk Data table can use at most 1 tablespace, this means that the theoretical upper limit to the amount of data (in bytes) that can be stored on disk by a single `NDB' table is 32G * 65536 = 2251799813685248, or approximately 2 petabytes. * The theoretical maximum number of extents per tablespace data file is 2^16 (65536); however, for practical purposes, the recommended maximum number of extents per data file is 2^15 (32768). The minimum and maximum possible sizes of extents for tablespace data files are 32K and 2G, respectively. See *Note create-tablespace::, for more information. Disk Data tables and diskless mode Use of Disk Data tables is not supported when running the cluster in diskless mode. Beginning with MySQL 5.1.12, it is prohibited altogether. (Bug #20008)  File: manual.info, Node: mysql-cluster-limitations-multiple-nodes, Next: mysql-cluster-limitations-resolved, Prev: mysql-cluster-limitations-disk-data, Up: mysql-cluster-limitations 17.1.6.10 Limitations Relating to Multiple MySQL Cluster Nodes .............................................................. Multiple SQL nodes The following are issues relating to the use of multiple MySQL servers as MySQL Cluster SQL nodes, and are specific to the *Note `NDBCLUSTER': mysql-cluster. storage engine: * No distributed table locks A *Note `LOCK TABLES': 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 *Note `ALTER TABLE': alter-table. is not fully locking when running multiple MySQL servers (SQL nodes). (As discussed in the previous item, MySQL Cluster does not support distributed table locks.) Multiple management nodes When using multiple management servers: * You must give nodes explicit IDs in connect strings because automatic allocation of node IDs does not work across multiple management servers. * In MySQL Cluster NDB 7.0.7 and earlier, you must take extreme care to have the same configurations for all management servers; no special checks for consistency are performed. Beginning with MySQL Cluster NDB 7.0.8, a management server when first starting checks for any other management server in the same MySQL 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 a MySQL 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 MySQL Cluster. See *Note 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 *Note mysql-cluster-tcp-definition::, for more information.  File: manual.info, Node: mysql-cluster-limitations-resolved, Prev: mysql-cluster-limitations-multiple-nodes, Up: mysql-cluster-limitations 17.1.6.11 Previous MySQL Cluster Issues Resolved in MySQL 5.1, MySQL Cluster NDB 6.x, and MySQL Cluster NDB 7.x ............................................................................................................... A number of limitations and related issues existing in earlier versions of MySQL Cluster have been resolved: * Variable-length column support The *Note `NDBCLUSTER': mysql-cluster. storage engine now supports variable-length column types for in-memory tables. Previously, for example, any Cluster table having one or more *Note `VARCHAR': char. fields which contained only relatively small values, much more memory and disk space were required when using the *Note `NDBCLUSTER': mysql-cluster. storage engine than would have been the case for the same table and data using the `MyISAM' engine. In other words, in the case of a *Note `VARCHAR': char. column, such a column required the same amount of storage as a *Note `CHAR': char. column of the same size. In MySQL 5.1, this is no longer the case for in-memory tables, where storage requirements for variable-length column types such as *Note `VARCHAR': char. and `BINARY' are comparable to those for these column types when used in `MyISAM' tables (see *Note storage-requirements::). *Important*: For MySQL Cluster Disk Data tables, the fixed-width limitation continues to apply. See *Note mysql-cluster-disk-data::. * Replication with MySQL Cluster It is now possible to use MySQL replication with Cluster databases. For details, see *Note mysql-cluster-replication::. Circular Replication Circular replication is also supported with MySQL Cluster, beginning with MySQL 5.1.18. See *Note mysql-cluster-replication-multi-master::. * `auto_increment_increment' and `auto_increment_offset' The `auto_increment_increment' and `auto_increment_offset' server system variables are supported for Cluster replication beginning with MySQL 5.1.20, MySQL Cluster NDB 6.2.5, and MySQL Cluster 6.3.2. * Database autodiscovery and online schema changes Autodiscovery of databases is now supported for multiple MySQL servers accessing the same MySQL Cluster. Formerly, autodiscovery in MySQL Cluster 5.1 and MySQL Cluster NDB 6.x releases required that a given *Note `mysqld': mysqld. was already running and connected to the cluster at the time that the database was created on a different *Note `mysqld': mysqld.--in other words, when a *Note `mysqld': mysqld. process connected to the cluster after a database named DB_NAME was created, it was necessary to issue a `CREATE DATABASE DB_NAME' or `CREATE SCHEMA DB_NAME' statement on the `new' MySQL server when it first accessed that MySQL Cluster. Beginning with MySQL Cluster NDB 6.2.16 and MySQL Cluster NDB 6.3.18, such a `CREATE' statement is no longer required. (Bug #39612) This also means that online schema changes in *Note `NDB': mysql-cluster. tables are now possible. That is, the result of operations such as *Note `ALTER TABLE': alter-table. and *Note `CREATE INDEX': create-index. performed on one SQL node in the cluster are now visible to the cluster's other SQL nodes without any additional action being taken. * Backup and restore between architectures Beginning with MySQL 5.1.10, it is possible to perform a Cluster backup and restore between different architectures. Previously--for example--you could not back up a cluster running on a big-endian platform and then restore from that backup to a cluster running on a little-endian system. (Bug #19255) * Character set directory Beginning with MySQL 5.1.10, it is possible to install MySQL with Cluster support to a nondefault location and change the search path for font description files using either the `--basedir' or `--character-sets-dir' options. (Previously, *Note `ndbd': mysql-cluster-programs-ndbd. in MySQL 5.1 searched only the default path--typically `/usr/local/mysql/share/mysql/charsets'--for character sets.) * Multiple management servers In MySQL 5.1 (including all MySQL Cluster NDB 6.x and later versions), it is no longer necessary, when running multiple management servers, to restart all the cluster's data nodes to enable the management nodes to see one another. Also, when using multiple management servers and starting concurrently several API nodes (possibly including one or more SQL nodes) whose connection strings listed the management servers in different order, it was possible for 2 API nodes to be assigned the same node ID. This issue is resolved in MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3. (Bug #42973) * Multiple data node processes per host Beginning with MySQL Cluster NDB 6.2.0, you can use multiple data node processes on a single host. (In MySQL Cluster NDB 6.1, MySQL 5.1, and earlier release series, we did not support production MySQL Cluster deployments in which more than one *Note `ndbd': mysql-cluster-programs-ndbd. process was run on a single physical machine.) In addition, MySQL Cluster NDB 7.0 introduces support for multi-threaded data nodes (*Note `ndbmtd': mysql-cluster-programs-ndbmtd.). See *Note mysql-cluster-development-5-1-ndb-7-0::, and *Note mysql-cluster-programs-ndbmtd::, for more information. * Identifiers Formerly (in MySQL 5.0 and earlier), database names, table names and attribute names could not be as long for *Note `NDB': mysql-cluster. tables as tables using other storage engines, because attribute names were truncated internally. In MySQL 5.1 and later, names of MySQL Cluster databases, tables, and table columns follow the same rules regarding length as they do for any other storage engine. * Length of `CREATE TABLE' statements *Note `CREATE TABLE': create-table. statements may be no more than 4096 characters in length. _This limitation affects MySQL 5.1.6, 5.1.7, and 5.1.8 only_. (See Bug #17813) * `IGNORE' and `REPLACE' functionality In MySQL 5.1.7 and earlier, *Note `INSERT IGNORE': insert, *Note `UPDATE IGNORE': update, and *Note `REPLACE': replace. were supported only for primary keys, but not for unique keys. It was possible to work around this issue by removing the constraint, then dropping the unique index, performing any inserts, and then adding the unique index again. This limitation was removed for *Note `INSERT IGNORE': insert. and *Note `REPLACE': replace. in MySQL 5.1.8. (See Bug #17431.) * `AUTO_INCREMENT' columns In MySQL 5.1.10 and earlier versions, the maximum number of tables having `AUTO_INCREMENT' columns--including those belonging to hidden primary keys--was 2048. This limitation was lifted in MySQL 5.1.11. * Maximum number of cluster nodes Prior to MySQL Cluster NDB 6.1.1, the total maximum number of nodes in a MySQL Cluster was 63, including all SQL nodes (MySQL Servers), API nodes (applications accessing the cluster other than MySQL servers), data nodes, and management servers. Starting with MySQL Cluster NDB 6.1.1, the total maximum number of nodes in a MySQL Cluster is 255, including all SQL nodes (MySQL Servers), API nodes (applications accessing the cluster other than MySQL servers), data nodes, and management servers. The total number of data nodes and management nodes beginning with this version is 63, of which up to 48 can be data nodes. *Note*: The limitation that a data node cannot have a node ID greater than 49 continues to apply. * Recovery of memory from deleted rows Beginning with MySQL Cluster NDB 6.3.7, memory can be reclaimed from an *Note `NDB': mysql-cluster. table for reuse with any *Note `NDB': mysql-cluster. table by employing *Note `OPTIMIZE TABLE': optimize-table, subject to the following limitations: * Only in-memory tables are supported; the *Note `OPTIMIZE TABLE': optimize-table. statement still has no effect on MySQL Cluster Disk Data tables. * Only variable-length columns (such as those declared as *Note `VARCHAR': char, *Note `TEXT': blob, or *Note `BLOB': blob.) are supported. However, you can force columns defined using fixed-length data types (such as *Note `CHAR': char.) to be dynamic using the `ROW_FORMAT' or `COLUMN_FORMAT' option with a *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. statement. See *Note create-table::, and *Note alter-table::, for information on these options. You can regulate the effects of `OPTIMIZE' on performance by adjusting the value of the global system variable `ndb_optimization_delay', which sets the number of milliseconds to wait between batches of rows being processed by `OPTIMIZE'. The default value is 10 milliseconds. It is possible to set a lower value (to a minimum of `0'), but not recommended. The maximum is 100000 milliseconds (that is, 100 seconds). * Implicit Rollbacks Prior to MySQL Cluster NDB 6.2.17 and MySQL Cluster NDB 6.3.19, MySQL Cluster did not automatically roll back a transaction that was aborted by a duplicate key or similar error, and subsequent statements raised `ERROR 1296 (HY000): Got error 4350 'Transaction already aborted' from NDBCLUSTER'. In such cases, it was necessary to issue an explicit *Note `ROLLBACK': commit. statement first, and then to retry the entire transaction. Beginning with MySQL Cluster NDB 6.2.17 and MySQL Cluster NDB 6.3.19, this limitation has been removed; now, an error which causes a transaction to be aborted generates an implicit rollback of the entire transaction. This is logged with the warning `Storage engine NDB does not support rollback for this statement. Transaction rolled back and must be restarted'. A statement subsequent to this starts a new transaction. (Bug #32656) *Note*: The *Note `NDBCLUSTER': mysql-cluster. storage engine does not support partial transactions or partial rollbacks of transactions in any version of MySQL Cluster. * Number of tables Previously, the maximum number of *Note `NDBCLUSTER': mysql-cluster. tables in a single MySQL Cluster was 1792, but this is no longer the case in MySQL 5.1 and later MySQL Cluster releases. However, the number of tables is still included in the total maximum number of *Note `NDBCLUSTER': mysql-cluster. database objects (20320). (See *Note mysql-cluster-limitations-database-objects::.) * DDL operations Beginning with MySQL Cluster NDB 6.4.0, DDL operations (such as *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table.) are protected from data node failures. Previously, if a data node failed while trying to perform one of these, the data dictionary became locked and no further DDL statements could be executed without restarting the cluster (Bug #36718). * Adding and dropping of data nodes In MySQL Cluster NDB 6.3 and previous versions of MySQL Cluster, the online adding or dropping of data nodes was not possible; such operations required a complete shutdown and restart of the entire cluster. In MySQL Cluster NDB 7.0 (beginning with MySQL Cluster NDB 6.4.0) and later MySQL Cluster release series, it is possible to add new data nodes to a running MySQL Cluster by performing a rolling restart, so that the cluster and the data stored in it remain available to applications. When planning to increase the number of data nodes in the cluster online in MySQL Cluster NDB 7.0 or MySQL Cluster NDB 7.1, you should be aware of and take into account the following issues: * New data nodes can be added online to a MySQL Cluster only as part of a new node group. * New data nodes can be added online, but cannot yet be dropped online. Reducing the number of data nodes still requires a system restart of the cluster. * As in previous MySQL Cluster releases, it is not possible to change online either the number of replicas (`NoOfReplicas' configuration parameter) or the number of data nodes per node group. These changes require a system restart. * Redistribution of existing cluster data using the new data nodes is not automatic; however, this can be accomplished using simple SQL statements in the *Note `mysql': mysql. client or other MySQL client application once the nodes have been added. During this procedure, it is not possible to perform DDL operations, although DML operations can continue as normal. The distribution of new cluster data (that is, data stored in the cluster _after_ the new nodes have been added) uses the new nodes without manual intervention. For more information, see *Note mysql-cluster-online-add-node::. * Native support for default column values Starting with MySQL Cluster NDB 7.1.0, default values for table columns are stored by *Note `NDBCLUSTER': mysql-cluster, rather than by the MySQL server as was previously the case. Because less data must be sent from an SQL node to the data nodes, inserts on tables having column value defaults can be performed more efficiently than before. Tables created using previous MySQL Cluster releases can still be used in MySQL Cluster 7.1.0 and later, although they do not support native default values and continue to use defaults supplied by the MySQL server until they are upgraded. This can be done by means of an offline *Note `ALTER TABLE': alter-table. statement. *Important*: You cannot set or change a table column's default value using an online *Note `ALTER TABLE': alter-table. operation * `InnoDB' plugin support Previously, *Note `InnoDB': innodb-storage-engine. support in MySQL Cluster was limited to the version built in to the MySQl Server. Beginning with MySQL Cluster NDB 7.1.9, MySQL Cluster also provides support for the *Note `InnoDB': innodb-storage-engine. Plugin. See *Note mysql-cluster-installation::, for information about enabling *Note `InnoDB': innodb-storage-engine. storage engine and plugin support with MySQL Cluster. * Distribution of MySQL users and privileges Previously, MySQL users and privileges created on one SQL node were unique to that SQL node, due to the fact that the MySQL grant tables were restricted to using the *Note `MyISAM': myisam-storage-engine. storage engine. Beginning with MySQL Cluster NDB 7.2.0, it is possible, following installation of the MySQL Cluster software and setup of the desired users and privileges on one SQL node, to convert the grant tables to use *Note `NDB': mysql-cluster. and thus to distribute the users and privileges across all SQL nodes connected to the cluster. You can do this by loading and making use of a set of stored procedures defined in an SQL script supplied with the MySQL Cluster distribution. For more information, see *Note mysql-cluster-privilege-distribution::. * Number of rows per partition Previously, a single MySQL Cluster partition could hold a maximum of 46137488 rows. This limitation was removed in MySQL Cluster NDB 7.0.36 and MySQL Cluster NDB 7.1.25. (Bug #13844405, Bug #14000373) If you are still using a previous MySQL Cluster release, you can work around this limitation by taking advantage of the fact that the number of partitions is the same as the number of data nodes in the cluster (see *Note mysql-cluster-nodes-groups::). This means that, by increasing the number of data nodes, you can increase the available space for storing data. In MySQL Cluster NDB 7.0 and later, you can increase the number of data nodes in the cluster while the cluster remains in operation. See *Note mysql-cluster-online-add-node::, for more information. It is also possible to increase the number of partitions for *Note `NDB': mysql-cluster. tables by using explicit `KEY' or `LINEAR KEY' partitioning (see *Note partitioning-key::).  File: manual.info, Node: mysql-cluster-installation, Next: mysql-cluster-configuration, Prev: mysql-cluster-overview, Up: mysql-cluster 17.2 MySQL Cluster Installation and Upgrades ============================================ * Menu: * mysql-cluster-install-linux:: Installing MySQL Cluster on Linux * mysql-cluster-install-windows:: Installing MySQL Cluster on Windows * mysql-cluster-install-configuration:: Initial Configuration of MySQL Cluster * mysql-cluster-install-first-start:: Initial Startup of MySQL Cluster * mysql-cluster-install-example-data:: MySQL Cluster Example with Tables and Data * mysql-cluster-install-shutdown-restart:: Safe Shutdown and Restart of MySQL Cluster * mysql-cluster-upgrade-downgrade:: Upgrading and Downgrading MySQL Cluster This section describes the basics for planning, installing, configuring, and running a MySQL Cluster. Whereas the examples in *Note 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 MySQL Cluster which meets the _minimum_ requirements for availability and safeguarding of data. For information about upgrading or downgrading a MySQL Cluster between release versions, see *Note mysql-cluster-upgrade-downgrade::. This section covers hardware and software requirements; networking issues; installation of MySQL Cluster; configuration issues; starting, stopping, and restarting the cluster; loading of a sample database; and performing queries. 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: This table lists cluster nodes for an example configuration and provides the IP address of each node. Node IP Address Management node (`mgmd') 192.168.0.10 SQL node (*Note `mysqld': mysqld.) 192.168.0.20 Data node "A" (*Note `ndbd': 192.168.0.30 mysql-cluster-programs-ndbd.) Data node "B" (*Note `ndbd': 192.168.0.40 mysql-cluster-programs-ndbd.) This may be made clearer by the following diagram: MySQL 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 throughout. That is, all four machines in the cluster should have 100 Mbps cards _or_ all four machines should have 1 Gbps cards.) MySQL Cluster works in a 100 Mbps network; however, gigabit Ethernet provides better performance. *Important*: MySQL 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 a MySQL 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 Web site (see `http://dev.mysql.com/doc/index-other.html'). We assume that each machine has sufficient memory for running the operating system, required MySQL Cluster processes, and (on the data nodes) storing the database. For general information about installing MySQL, see *Note installing::. For information about installation of MySQL Cluster on Linux and other Unix-like operating systems, see *Note mysql-cluster-install-linux::. For information about installation of MySQL Cluster on Windows operating systems, see *Note mysql-cluster-install-windows::. For general information about MySQL Cluster hardware, software, and networking requirements, see *Note mysql-cluster-overview-requirements::.  File: manual.info, Node: mysql-cluster-install-linux, Next: mysql-cluster-install-windows, Prev: mysql-cluster-installation, Up: mysql-cluster-installation 17.2.1 Installing MySQL Cluster on Linux ---------------------------------------- * Menu: * mysql-cluster-install-linux-binary:: Installing a MySQL Cluster Binary Release on Linux * mysql-cluster-install-linux-rpm:: Installing MySQL Cluster from RPM * mysql-cluster-install-linux-source:: Building MySQL Cluster from Source on Linux This section covers installation of MySQL 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. Beginning with MySQL Cluster NDB 7.1.3, MySQL Cluster is also supported for production use on Windows operating systems; for installation and setup instructions specific to Windows, see *Note mysql-cluster-install-windows::. Each MySQL 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 (*Note `mysqld': mysqld.). Management nodes require the management server daemon (*Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd.); data nodes require the data node daemon (*Note `ndbd': mysql-cluster-programs-ndbd.; in MySQL Cluster NDB 7.0 and later, you can use *Note `ndbmtd': mysql-cluster-programs-ndbmtd. instead. 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 (*Note `ndb_mgm': mysql-cluster-programs-ndb-mgm.) on the management server host. Installation of MySQL 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 MySQL Cluster binaries to create configuration files for all cluster nodes, before you can start the cluster. See *Note mysql-cluster-install-configuration::.  File: manual.info, Node: mysql-cluster-install-linux-binary, Next: mysql-cluster-install-linux-rpm, Prev: mysql-cluster-install-linux, Up: mysql-cluster-install-linux 17.2.1.1 Installing a MySQL 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 latest MySQL Cluster NDB 6.3, MySQL Cluster NDB 7.0, or MySQL Cluster NDB 7.1 binary archive (`mysql-cluster-gpl-6.3.53-linux-i686-glibc23.tar.gz', `mysql-cluster-gpl-7.0.40-linux-i686-glibc23.tar.gz', or `mysql-cluster-gpl-7.1.29-linux-i686-glibc23.tar.gz', respectively) from the MySQL Cluster downloads area (http://dev.mysql.com/downloads/cluster/). We assume that you have placed this file in each machine's `/var/tmp' directory. (If you do require a custom binary, see *Note 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 *Note 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 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 that the actual file and directory names vary according to the MySQL Cluster version number. shell> cd /var/tmp shell> tar -C /usr/local -xzvf mysql-cluster-gpl-7.1.29-linux-i686-glibc23.tar.gz shell> ln -s /usr/local/mysql-cluster-gpl-7.1.29-linux-i686-glibc23 /usr/local/mysql 3. Change location to the `mysql' directory and run the supplied script for creating the system databases: shell> cd mysql shell> scripts/mysql_install_db --user=mysql 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 *Note `mysqld': mysqld. binary. Only the MySQL Cluster data node executable *Note `ndbd': mysql-cluster-programs-ndbd. (single-threaded) or *Note `ndbmtd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd. and *Note `ndbmtd': mysql-cluster-programs-ndbmtd. binaries from the archive into a suitable directory such as `/usr/local/bin': shell> cd /var/tmp shell> tar -zxvf mysql-5.1.71-ndb-7.1.29-linux-i686-glibc23.tar.gz shell> cd mysql-5.1.71-ndb-7.1.29-linux-i686-glibc23 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. and *Note `ndb_mgmd': mysql-cluster-programs-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 a MySQL Cluster data node, we have shown you how to install both *Note `ndbd': mysql-cluster-programs-ndbd. and *Note `ndbmtd': mysql-cluster-programs-ndbmtd. in the preceding instructions. We recommend that you do this when installing or upgrading MySQL 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 *Note mysql-cluster-install-configuration::.) Management nodes Installation of the management node does not require the *Note `mysqld': mysqld. binary. Only the MySQL Cluster management server (*Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd.) is required; you most likely want to install the management client (*Note `ndb_mgm': mysql-cluster-programs-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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. and *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. on the management node host: 1. Change location to the `/var/tmp' directory, and extract the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. and *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. from the archive into a suitable directory such as `/usr/local/bin': shell> cd /var/tmp shell> tar -zxvf mysql-5.1.71-ndb-7.1.29-linux-i686-glibc23.tar.gz shell> cd mysql-5.1.71-ndb-7.1.29-linux-i686-glibc23 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. and *Note `ndb_mgmd': mysql-cluster-programs-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 *Note mysql-cluster-install-configuration::, we create configuration files for all of the nodes in our example MySQL Cluster.  File: manual.info, Node: mysql-cluster-install-linux-rpm, Next: mysql-cluster-install-linux-source, Prev: mysql-cluster-install-linux-binary, Up: mysql-cluster-install-linux 17.2.1.2 Installing MySQL Cluster from RPM .......................................... This section covers the steps necessary to install the correct executables for each type of MySQL Cluster node using RPM packages supplied by Oracle. RPMs are available for both 32-bit and 64-bit Linux platforms. For a MySQL Cluster, three RPMs are required: * The *Server* RPM (for example, `MySQL-Cluster-gpl-server-6.3.53-0.sles10.i586.rpm', `MySQL-Cluster-gpl-server-7.0.40-0.sles10.i586.rpm', or `MySQL-Cluster-gpl-server-7.1.29-0.sles10.i586.rpm'), which supplies the core files needed to run a MySQL Server with *Note `NDBCLUSTER': mysql-cluster. storage engine support (that is, as a MySQL Cluster SQL node). 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-gpl-client-6.3.53-0.sles10.i586.rpm', `MySQL-Cluster-gpl-client-7.0.40-0.sles10.i586.rpm', or `MySQL-Cluster-gpl-client-7.1.29-0.sles10.i586.rpm'). * The *Cluster storage engine* RPM (for example, `MySQL-Cluster-gpl-storage-6.3.53-0.sles10.i586.rpm', `MySQL-Cluster-gpl-storage-7.0.40-0.sles10.i586.rpm', or `MySQL-Cluster-gpl-storage-7.1.29-0.sles10.i586.rpm'), which supplies the MySQL Cluster data node binary (*Note `ndbd': mysql-cluster-programs-ndbd.). * The *Cluster storage engine management RPM* (for example, `MySQL-Cluster-gpl-management-6.3.53-0.sles10.i586.rpm', `MySQL-Cluster-gpl-management-7.0.40-0.sles10.i586.rpm', or `MySQL-Cluster-gpl-management-7.1.29-0.sles10.i586.rpm') which provides the MySQL Cluster management server binary (*Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd.). In addition, you should also obtain the *NDB Cluster - Storage engine basic tools* RPM (for example, `MySQL-Cluster-gpl-tools-6.3.53-0.sles10.i586.rpm', `MySQL-Cluster-gpl-tools-7.0.40-0.sles10.i586.rpm', or `MySQL-Cluster-gpl-tools-7.1.29-0.sles10.i586.rpm'), which supplies several useful applications for working with a MySQL Cluster. The most important of these is the MySQL Cluster management client (*Note `ndb_mgm': mysql-cluster-programs-ndb-mgm.). The *NDB Cluster - Storage engine extra tools* RPM (for example, `MySQL-Cluster-gpl-extra-6.3.53-0.sles10.i586.rpm', `MySQL-Cluster-gpl-extra-7.0.40-0.sles10.i586.rpm', or `MySQL-Cluster-gpl-extra-7.1.29-0.sles10.i586.rpm') contains some additional testing and monitoring programs, but is not required to install a MySQL Cluster. (For more information about these additional programs, see *Note mysql-cluster-programs::.) The MySQL Cluster version number in the RPM file names (shown here as `6.3.53', `7.0.40', or `7.1.29') 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 `glibc' version number (if present), and architecture designation (shown here as `i586') should be appropriate to the machine on which the RPM is to be installed. Data nodes On a computer that is to host a cluster data node it is necessary to install only the *NDB Cluster - Storage engine* 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 web site: shell> rpm -Uhv MySQL-Cluster-gpl-storage-7.1.29-0.sles10.i586.rpm The previous command installs the MySQL Cluster data node binary (*Note `ndbd': mysql-cluster-programs-ndbd.) in the `/usr/sbin' directory. 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 web site: shell> rpm -Uhv MySQL-Cluster-gpl-server-7.1.29-0.sles10.i586.rpm This installs the MySQL server binary (*Note `mysqld': mysqld.) in the `/usr/sbin' directory, as well as all needed MySQL Server support files. It also installs the *Note `mysql.server': mysql-server. and *Note `mysqld_safe': 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. *Note*: To administer the SQL node (MySQL server), you should also install the *Client* RPM, as shown here: shell> rpm -Uhv MySQL-Cluster-gpl-client-7.1.29-0.sles10.i586.rpm This installs the *Note `mysql': mysql. client program. Management nodes To install the MySQL Cluster management server, it is necessary only to use the *NDB Cluster - Storage engine management* 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 *Storage engine management* RPM downloaded from the MySQL web site): shell> rpm -Uhv MySQL-Cluster-gpl-management-7.1.29-0.sles10.i586.rpm This installs the management server binary (*Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd.) to the `/usr/sbin' directory. You should also install the *Note `NDB': mysql-cluster. management client, which is supplied by the *Storage engine basic tools* RPM. Copy this RPM to the same computer as the management node, and then install it by running the following command as the system root user (again, replace the name shown for the RPM as necessary to match that of the *Storage engine basic tools* RPM downloaded from the MySQL web site): shell> rpm -Uhv MySQL-Cluster-gpl-tools-7.1.29-0.sles10.i586.rpm The *Storage engine basic tools* RPM installs the MySQL Cluster management client (*Note `ndb_mgm': mysql-cluster-programs-ndb-mgm.) to the `/usr/bin' directory. *Note*: You can also install the *Cluster storage engine extra tools* RPM, if you wish, as shown here: shell> rpm -Uhv MySQL-Cluster-gpl-extra-7.1.29-0.sles10.i586.rpm You may find the extra tools useful; however the *Cluster storage engine extra tools* RPM is _not_ required to install a working MySQL Cluster. See *Note 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 as discussed in *Note mysql-cluster-install-configuration::.  File: manual.info, Node: mysql-cluster-install-linux-source, Prev: mysql-cluster-install-linux-rpm, Up: mysql-cluster-install-linux 17.2.1.3 Building MySQL Cluster from Source on Linux .................................................... This section provides information about compiling MySQL Cluster on Linux and other Unix-like platforms. Building MySQL 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 *Note source-installation::. Beginning with MySQL Cluster NDB 7.1.3, MySQL Cluster is also supported on Windows platforms, and can be built on Windows from source. For information about compiling MySQL Cluster on Windows platforms, see *Note mysql-cluster-install-windows-source::. Building MySQL Cluster requires using the MySQL Cluster sources. These are available from the MySQL Cluster downloads page at http://dev.mysql.com/downloads/cluster/. The archived source file should have a name similar to `mysql-cluster-gpl-6.3.53.tar.gz', `mysql-cluster-gpl-7.0.40.tar.gz', or `mysql-cluster-gpl-7.1.29.tar.gz'. You can also obtain MySQL development sources from launchpad.net. Attempting to build MySQL Cluster from standard MySQL 5.1 sources is not supported. In addition to any other `configure' options you wish to use, be sure to include `--with-plugins=ndbcluster', `--with-plugins=max', or , or `--with-plugins=max-no-innodb'. Either of these options causes the binaries for the management nodes, data nodes, and other MySQL Cluster programs to be built; it also causes *Note `mysqld': mysqld. to be compiled with *Note `NDB': mysql-cluster. storage engine support. 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. However, the layout can differ. These differences are covered in the next few paragraphs. Prior to MySQL Cluster NDB 7.1.9, MySQL Cluster was not compatible with the *Note `InnoDB': innodb-storage-engine. Plugin; in earlier MySQL Cluster releases, only the version of *Note `InnoDB': innodb-storage-engine. supplied with the MySQL Server could be used. Beginning with MySQL Cluster NDB 7.1.9, you can build MySQL Cluster with *Note `InnoDB': innodb-storage-engine. storage engine or plugin support using the appropriate `--with-plugins' option for `configure'. Management nodes When building from source and running the default `make install', the management server binary (*Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd.) is placed in `/usr/local/mysql/libexec', while the management client binary (*Note `ndb_mgm': mysql-cluster-programs-ndb-mgm.) can be found in `/usr/local/mysql/bin'. Only *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. is required to be present on a management node host; however, it is also a good idea to have *Note `ndb_mgm': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd. (*Note `mysqld': mysqld, for example, does not have to be present on the host machine). By default when doing a source build, this file is placed in the directory `/usr/local/mysql/libexec'. For installing on multiple data node hosts, only *Note `ndbd': mysql-cluster-programs-ndbd. 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.) *Note `ndbd': mysql-cluster-programs-ndbd. need not be in any particular location on the host's file system, as long as the location is known. When compiling MySQL Cluster NDB 7.0 or later from source, no special options are required for building multi-threaded data node binaries. On Unix platforms, configuring the build with any of the options `--with-plugins=ndbcluster', `--with-plugins=max', or `--with-plugins=max-no-innodb' causes *Note `ndbmtd': mysql-cluster-programs-ndbmtd. to be built automatically; `make install' places the *Note `ndbmtd': mysql-cluster-programs-ndbmtd. binary in the `libexec' directory along with *Note `mysqld': mysqld, *Note `ndbd': mysql-cluster-programs-ndbd, and *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. SQL nodes If you compile MySQL with clustering support, and perform the default installation (using `make install' as the system `root' user), *Note `mysqld': mysqld. is placed in `/usr/local/mysql/bin'. Follow the steps given in *Note source-installation:: to make *Note `mysqld': mysqld. ready for use. If you want to run multiple SQL nodes, you can use a copy of the same *Note `mysqld': 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 *Note source-installation:: on each machine. If you configure the build with a nondefault `--prefix', you need to adjust the directory accordingly. In *Note mysql-cluster-install-configuration::, we create configuration files for all of the nodes in our example MySQL Cluster.  File: manual.info, Node: mysql-cluster-install-windows, Next: mysql-cluster-install-configuration, Prev: mysql-cluster-install-linux, Up: mysql-cluster-installation 17.2.2 Installing MySQL Cluster on Windows ------------------------------------------ * Menu: * mysql-cluster-install-windows-binary:: Installing MySQL Cluster on Windows from a Binary Release * mysql-cluster-install-windows-source:: Compiling and Installing MySQL Cluster from Source on Windows * mysql-cluster-install-windows-initial-start:: Initial Startup of MySQL Cluster on Windows * mysql-cluster-install-windows-service:: Installing MySQL Cluster Processes as Windows Services Experimental support for MySQL Cluster on Microsoft Windows operating systems was introduced in MySQL Cluster NDB 7.0. Beginning with MySQL Cluster NDB 7.1.3, production support is provided for MySQL Cluster on Windows, and MySQL Cluster binaries for Windows can be obtained from `http://dev.mysql.com/downloads/cluster/'. For information about installing MySQL Cluster on Windows from a binary release provided by Oracle, see *Note mysql-cluster-install-windows-binary::. It is also possible to compile and install MySQL Cluster from source on Windows using Microsoft Visual Studio. For more information, see *Note mysql-cluster-install-windows-source::.  File: manual.info, Node: mysql-cluster-install-windows-binary, Next: mysql-cluster-install-windows-source, Prev: mysql-cluster-install-windows, Up: mysql-cluster-install-windows 17.2.2.1 Installing MySQL Cluster on Windows from a Binary Release .................................................................. This section describes a basic installation of MySQL Cluster on Windows using a binary `no-install' MySQL Cluster release provided by Oracle, using the same 4-node setup outlined in the beginning of this section (see *Note mysql-cluster-installation::), as shown in the following table: This table illustrates the same 4-node MySQL cluster configuration outlined in the beginning of this section. The table lists the cluster nodes and the IP address of each node. Node IP Address Management (MGMD) node 192.168.0.10 MySQL server (SQL) node 192.168.0.20 Data (NDBD) node "A" 192.168.0.30 Data (NDBD) node "B" 192.168.0.40 As on other platforms, the MySQL Cluster host computer running an SQL node must have installed on it a MySQL Server binary (*Note `mysqld.exe': mysqld.). You should also have the MySQL client (*Note `mysql.exe': mysql.) on 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 (*Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd.); each data node requires the data node daemon (*Note `ndbd.exe': mysql-cluster-programs-ndbd. or *Note `ndbmtd.exe': mysql-cluster-programs-ndbmtd.). For this example, we refer to *Note `ndbd.exe': mysql-cluster-programs-ndbd. as the data node executable, but you can install *Note `ndbmtd.exe': mysql-cluster-programs-ndbmtd, the multi-threaded version of this program, instead, in exactly the same way. You should also install the management client (*Note `ndb_mgm.exe': mysql-cluster-programs-ndb-mgm.) on the management server host. This section covers the steps necessary to install the correct Windows binaries for each type of MySQL Cluster node. *Note `ndbmtd.exe': mysql-cluster-programs-ndbmtd. was not included in MySQL Cluster NDB 7.1.3 binary releases for Windows, due to a problem with *Note `make_win_bin_dist': make-win-bin-dist. This issue was corrected in MySQL Cluster NDB 7.1.5. *Note*: As with other Windows programs, MySQL 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 *Note `mysqld': mysqld, *Note `mysql': mysql, *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd, and so on. You should understand that, whether we refer (for example) to *Note `mysqld': mysqld. or *Note `mysqld.exe': mysqld, either name means the same thing (the MySQL Server program). For setting up a MySQL Cluster using Oracles's `no-install' binaries, the first step in the installation process is to download the latest MySQL Cluster Windows binary archive from `http://dev.mysql.com/downloads/cluster/'. This archive has a filename of the form `mysql-cluster-gpl-noinstall-VER-winARCH.zip', where VER is the `NDB' storage engine version (such as `7.1.3'), and ARCH is the architecture (`32' for 32-bit binaries, and `64' for 64-bit binaries). For example, the MySQL Cluster NDB 7.1.3 `no-install' archive for 32-bit Windows systems is named `mysql-cluster-gpl-noinstall-7.1.3-win32.zip'. You can run 32-bit MySQL Cluster binaries on both 32-bit and 64-bit versions of Windows; however, 64-bit MySQL 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 MySQL 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 `no-install' archive in the directory `C:\Documents and Settings\USERNAME\My Documents\Downloads' on the computer having the IP address 192.168.0.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 MySQL 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-noinstall-VER-winARCH'. Rename this directory to `C:\mysql'. It is possible to install the MySQL 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.1', 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.1\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 *Note windows-install-archive::. For a MySQL Server with MySQL Cluster support to run as part of a MySQL 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=192.168.0.10 # location of management server You can add other options used by this MySQL Server if desired (see *Note 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 A MySQL Cluster data node on a Windows host requires only a single executable, one of either *Note `ndbd.exe': mysql-cluster-programs-ndbd. or *Note `ndbmtd.exe': mysql-cluster-programs-ndbmtd. For this example, we assume that you are using *Note `ndbd.exe': mysql-cluster-programs-ndbd, but the same instructions apply when using *Note `ndbmtd.exe': mysql-cluster-programs-ndbmtd. On each computer where you wish to run a data node (the computers having the IP addresses 192.168.0.30 and 192.168.0.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 a MySQL 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=192.168.0.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 MySQL 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 a MySQL Cluster management node is the management server program *Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd. However, in order to administer the MySQL Cluster once it has been started, you should also install the MySQL Cluster management client program *Note `ndb_mgm.exe': mysql-cluster-programs-ndb-mgm. 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 192.168.0.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 MySQL 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 plaintext file `C:\mysql\bin\my.ini'. 2. A global configuration file from which the management node can obtain configuration information governing the MySQL Cluster as a whole. At a minimum, this file must contain a section for each node in the MySQL 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 *Note 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/bin/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=192.168.0.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=192.168.0.30 # Hostname or IP address [ndbd] # Options for data node "B": HostName=192.168.0.40 # Hostname or IP address [mysqld] # SQL node options: HostName=192.168.0.20 # Hostname or IP address Save this file as the plaintext 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 MySQL 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 a MySQL 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 MySQL Cluster program options and configuration files on Windows.  File: manual.info, Node: mysql-cluster-install-windows-source, Next: mysql-cluster-install-windows-initial-start, Prev: mysql-cluster-install-windows-binary, Up: mysql-cluster-install-windows 17.2.2.2 Compiling and Installing MySQL Cluster from Source on Windows ...................................................................... Oracle provides precompiled MySQL Cluster binaries for Windows which should be adequate for most users. However, if you wish, it is also possible to compile MySQL 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 MySQL Cluster, you must use the MySQL Cluster sources, which you can obtain from `http://dev.mysql.com/downloads/cluster/'. Attempting to build MySQL 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' option in addition to any other build options you wish to use before creating the Visual Studio project files. Once you have run `configure.js' with the desired options, you can create the project files and build from them in the same manner as you do when compiling the standard MySQL Server. For more information, see *Note windows-source-build::. Prior to MySQL Cluster NDB 7.1.9, MySQL Cluster was not compatible with the *Note `InnoDB': innodb-storage-engine. Plugin; in earlier MySQL Cluster releases, only the version of *Note `InnoDB': innodb-storage-engine. supplied with the MySQL Server could be used. Beginning with MySQL Cluster NDB 7.1.9, you can build MySQL Cluster with *Note `InnoDB': innodb-storage-engine. storage engine or plugin support on Windows using `WITH_INNOBASE_STORAGE_ENGINE' with `configure.js'- Once the build process is complete, you can create a Zip archive containing the compiled binaries by running *Note `make_win_bin_dist': make-win-bin-dist. The MySQL 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 basic information about how to accomplish these tasks, see *Note mysql-cluster-install-windows-binary::. On Windows, beginning with MySQL Cluster NDB 7.0.11, using `WITH_NDBCLUSTER_STORAGE_ENGINE' with `configure.js' causes *Note `ndbmtd.exe': mysql-cluster-programs-ndbmtd. to be built automatically, and to be found in the `bin' directory of the archive created by *Note `make_win_bin_dist': make-win-bin-dist. (It was not possible to build *Note `ndbmtd.exe': mysql-cluster-programs-ndbmtd. on Windows prior to MySQL Cluster NDB 7.0.11.)  File: manual.info, Node: mysql-cluster-install-windows-initial-start, Next: mysql-cluster-install-windows-service, Prev: mysql-cluster-install-windows-source, Up: mysql-cluster-install-windows 17.2.2.3 Initial Startup of MySQL Cluster on Windows .................................................... Once the MySQL Cluster executables and needed configuration files are in place, performing an initial start of the cluster is simply a matter of starting the MySQL 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: C:\mysql\bin> ndb_mgmd 2010-06-23 07:53:34 [MgmtSrvr] INFO -- NDB Cluster Management Server. mysql-5.1.71-ndb-7.1.29 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 MySQL 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 MySQL Cluster data node processes running on Windows.) For this reason, do not close the window in which *Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd. is running; doing so kills the management node process. (See *Note mysql-cluster-install-windows-service::, where we show how to install and run MySQL 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*: A MySQL 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 *Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd. 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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd, see *Note mysql-cluster-programs-ndb-mgmd::, as well as *Note 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 *Note `ndbd.exe': mysql-cluster-programs-ndbd. (For more information, see *Note 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 MySQL Cluster management client *Note `ndb_mgm.exe': mysql-cluster-programs-ndb-mgm, which should be in `C:\mysql\bin' on the management node host. (Do not try to re-use the console window where *Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd. 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 MySQL 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.1.71-ndb-7.1.29) Node 3: starting (Last completed phase 3) (mysql-5.1.71-ndb-7.1.29) Node 2: starting (Last completed phase 4) (mysql-5.1.71-ndb-7.1.29) Node 3: starting (Last completed phase 4) (mysql-5.1.71-ndb-7.1.29) Node 2: Started (version 7.1.29) Node 3: Started (version 7.1.29) 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client. For more information, see *Note 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 MySQL 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 *Note `ndb_mgm.exe': mysql-cluster-programs-ndb-mgm. running; it has no negative impact on the performance of the MySQL 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 MySQL Cluster binaries (if you are following our example, this is `C:\mysql\bin'). Start the SQL node by invoking *Note `mysqld.exe': mysqld. 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 (*Note `ndb_mgm.exe': mysql-cluster-programs-ndb-mgm.) 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 @192.168.0.30 (Version: 5.1.71-ndb-7.1.29, Nodegroup: 0, Master) id=3 @192.168.0.40 (Version: 5.1.71-ndb-7.1.29, Nodegroup: 0) [ndb_mgmd(MGM)] 1 node(s) id=1 @192.168.0.10 (Version: 5.1.71-ndb-7.1.29) [mysqld(API)] 1 node(s) id=4 @192.168.0.20 (Version: 5.1.71-ndb-7.1.29) You can also verify that the SQL node is connected to the MySQL Cluster in the *Note `mysql': mysql. client (*Note `mysql.exe': mysql.) using the `SHOW ENGINE NDB STATUS' statement. You should now be ready to work with database objects and data using MySQL Cluster's *Note `NDBCLUSTER': mysql-cluster. storage engine. See *Note mysql-cluster-install-example-data::, for more information and examples. Beginning with MySQL Cluster NDB 7.0.16 and MySQL Cluster NDB 7.1.5, you can install *Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd, *Note `ndbd.exe': mysql-cluster-programs-ndbd, and *Note `ndbmtd.exe': mysql-cluster-programs-ndbmtd. as Windows services. For information on how to do this, see *Note mysql-cluster-install-windows-service::).  File: manual.info, Node: mysql-cluster-install-windows-service, Prev: mysql-cluster-install-windows-initial-start, Up: mysql-cluster-install-windows 17.2.2.4 Installing MySQL Cluster Processes as Windows Services ............................................................... Once you are satisfied that MySQL Cluster is running as desired, you can--beginning with MySQL Cluster NDB 7.0.16 and MySQL Cluster NDB 7.1.5--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 *Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd. 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 'MySQL Cluster Management Server' as '"C:\mysql\bin\ndbd.exe" "--service=ndb_mgmd"' Service successfully installed. *Important*: When installing a MySQL 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 *Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd. 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 *Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd. `--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 MySQL Cluster Management Server service is starting. The MySQL Cluster Management Server service was started successfully. C:\> NET STOP ndb_mgmd The MySQL Cluster Management Server service is stopping.. The MySQL 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 'MySQL Cluster Management Server' The MySQL Cluster Management Server service is starting. The MySQL Cluster Management Server service was started successfully. C:\> NET STOP 'MySQL Cluster Management Server' The MySQL Cluster Management Server service is stopping.. The MySQL 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 'MySQL 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 MySQL Cluster Management Server service is starting. The MySQL Cluster Management Server service was started successfully. C:\> NET STOP mgmd1 The MySQL Cluster Management Server service is stopping.. The MySQL Cluster Management Server service was stopped successfully. To remove the management node service, invoke *Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd. with the `--remove' option, as shown here: C:\> C:\mysql\bin\ndb_mgmd.exe --remove Removing service 'MySQL 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 a MySQL Cluster data node process as a Windows service can be done in a similar fashion, using the `--install' option for *Note `ndbd.exe': mysql-cluster-programs-ndbd. (or *Note `ndbmtd.exe': mysql-cluster-programs-ndbmtd.), as shown here: C:\> C:\mysql\bin\ndbd.exe --install Installing service 'MySQL 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 MySQL Cluster Data Node Daemon service is starting. The MySQL Cluster Data Node Daemon service was started successfully. C:\> NET STOP ndbd The MySQL Cluster Data Node Daemon service is stopping.. The MySQL Cluster Data Node Daemon service was stopped successfully. C:\> NET START 'MySQL Cluster Data Node Daemon' The MySQL Cluster Data Node Daemon service is starting. The MySQL Cluster Data Node Daemon service was started successfully. C:\> NET STOP 'MySQL Cluster Data Node Daemon' The MySQL Cluster Data Node Daemon service is stopping.. The MySQL Cluster Data Node Daemon service was stopped successfully. To remove the data node service, invoke *Note `ndbd.exe': mysql-cluster-programs-ndbd. with the `--remove' option, as shown here: C:\> C:\mysql\bin\ndbd.exe --remove Removing service 'MySQL Cluster Data Node Daemon' Service successfully removed. As with *Note `ndb_mgmd.exe': mysql-cluster-programs-ndb-mgmd. (and *Note `mysqld.exe': mysqld.), when installing *Note `ndbd.exe': mysql-cluster-programs-ndbd. 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 MySQL Cluster Data Node Daemon service is starting. The MySQL Cluster Data Node Daemon service was started successfully. C:\> NET STOP dnode1 The MySQL Cluster Data Node Daemon service is stopping.. The MySQL 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 *Note `mysqld': mysqld. `--install', `NET START', `NET STOP', and *Note `mysqld': mysqld. `--remove'. For additional information, see *Note windows-start-service::.  File: manual.info, Node: mysql-cluster-install-configuration, Next: mysql-cluster-install-first-start, Prev: mysql-cluster-install-windows, Up: mysql-cluster-installation 17.2.3 Initial Configuration of MySQL Cluster --------------------------------------------- For our four-node, four-host MySQL Cluster, 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 *Note `NDBCLUSTER': mysql-cluster. storage engine. For more information on connection strings, see *Note 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 MySQL Cluster processes: ndb-connectstring=192.168.0.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 *Note `mysqld': 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 *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': 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 Cluster setup. [tcp default] # TCP/IP options: portnumber=2202 # This the default; however, you can use any # port that is free for all the hosts in the cluster # Note: It is recommended that you do not specify the port # number at all and simply allow the default value to be used # instead [ndb_mgmd] # Management process options: hostname=192.168.0.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=192.168.0.30 # Hostname or IP address datadir=/usr/local/mysql/data # Directory for this data node's data files [ndbd] # Options for data node "B": hostname=192.168.0.40 # Hostname or IP address datadir=/usr/local/mysql/data # Directory for this data node's data files [mysqld] # SQL node options: hostname=192.168.0.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/', where it can be found listed under `Examples'. 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 *Note mysql-cluster-install-first-start::. For more detailed information about the available MySQL Cluster configuration parameters and their uses, see *Note mysql-cluster-config-file::, and *Note mysql-cluster-configuration::. For configuration of MySQL Cluster as relates to making backups, see *Note 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.  File: manual.info, Node: mysql-cluster-install-first-start, Next: mysql-cluster-install-example-data, Prev: mysql-cluster-install-configuration, Up: mysql-cluster-installation 17.2.4 Initial Startup of MySQL 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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. must be told where to find its configuration file, using the `-f' or `--config-file' option. (See *Note mysql-cluster-programs-ndb-mgmd::, for details.) For additional options which can be used with *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd, see *Note mysql-cluster-program-options-common::. 2. On each of the data node hosts, run this command to start the *Note `ndbd': mysql-cluster-programs-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 *Note `ndb_mgm': mysql-cluster-programs-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 @192.168.0.30 (Version: 5.1.71-ndb-7.1.29, Nodegroup: 0, Master) id=3 @192.168.0.40 (Version: 5.1.71-ndb-7.1.29, Nodegroup: 0) [ndb_mgmd(MGM)] 1 node(s) id=1 @192.168.0.10 (Version: 5.1.71-ndb-7.1.29) [mysqld(API)] 1 node(s) id=4 @192.168.0.20 (Version: 5.1.71-ndb-7.1.29) The SQL node is referenced here as `[mysqld(API)]', which reflects the fact that the *Note `mysqld': mysqld. process is acting as a MySQL Cluster API node. *Note*: The IP address shown for a given MySQL 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 MySQL Cluster. See *Note mysql-cluster-install-example-data::, for a brief discussion.  File: manual.info, Node: mysql-cluster-install-example-data, Next: mysql-cluster-install-shutdown-restart, Prev: mysql-cluster-install-first-start, Up: mysql-cluster-installation 17.2.5 MySQL Cluster Example with Tables and Data ------------------------------------------------- *Note*: The information in this section applies to MySQL Cluster running on both Unix and Windows platforms. Working with database tables and data in MySQL 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 *Note `NDBCLUSTER': mysql-cluster. 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 *Note `ALTER TABLE': alter-table. to change the table to use *Note `NDBCLUSTER': mysql-cluster.: ALTER TABLE TBL_NAME ENGINE=NDBCLUSTER; * Every *Note `NDBCLUSTER': mysql-cluster. table has a primary key. If no primary key is defined by the user when a table is created, the *Note `NDBCLUSTER': mysql-cluster. 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 *Note `mysqldump': 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 MySQL 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 *Note `INSERT': 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 *Note `NDBCLUSTER': mysql-cluster. 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 *Note `ALTER TABLE': 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 *Note `mysql': 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 `192.168.0.20'). To create a copy of the entire `world' database on the SQL node, use *Note `mysqldump': 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 *Note `SELECT': 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.1.71-ndb-7.1.29 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 *Note 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 *Note 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 *Note `NDB': mysql-cluster. 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 *Note `SELECT': select. statement just shown by using the PHP 5.X `mysqli' extension running on a Web server elsewhere on the network: SIMPLE mysqli SELECT query($query) ) { ?> fetch_object()) printf("\n \n\n", $row->Name, $row->Population); ?> Affected rows: %d

\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(); ?> 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.  File: manual.info, Node: mysql-cluster-install-shutdown-restart, Next: mysql-cluster-upgrade-downgrade, Prev: mysql-cluster-install-example-data, Up: mysql-cluster-installation 17.2.6 Safe Shutdown and Restart of MySQL 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client from the shell. (See *Note mysql-cluster-program-options-common::, for more information about this option.) The command causes the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm, *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd, and any *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndbmtd': mysql-cluster-programs-ndbmtd. processes to terminate gracefully. Any SQL nodes can be terminated using *Note `mysqladmin shutdown': mysqladmin. 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 (`192.168.0.10' in our example setup): shell> ndb_mgmd -f /var/lib/mysql-cluster/config.ini * On each of the data node hosts (`192.168.0.30' and `192.168.0.40'): shell> ndbd * Use the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client to verify that both data nodes have started successfully. * On the SQL host (`192.168.0.20'): shell> mysqld_safe & On Windows platforms, assuming that you have installed all MySQL Cluster processes as Windows services using the default service names (see *Note mysql-cluster-install-windows-service::), you can restart the cluster as follows: * On the management host (`192.168.0.10' in our example setup), execute the following command: C:\> NET START ndb_mgmd * On each of the data node hosts (`192.168.0.30' and `192.168.0.40'), execute the following command: C:\> NET START ndbd * On the management node host, use the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client to verify that the management node and both data nodes have started successfully (see *Note mysql-cluster-install-windows-initial-start::). * On the SQL node host (`192.168.0.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 *Note mysql-cluster-rolling-restart::.  File: manual.info, Node: mysql-cluster-upgrade-downgrade, Prev: mysql-cluster-install-shutdown-restart, Up: mysql-cluster-installation 17.2.7 Upgrading and Downgrading MySQL Cluster ---------------------------------------------- * Menu: * mysql-cluster-upgrade-downgrade-compatibility-7.x:: Upgrade and downgrade compatibility: MySQL Cluster NDB 7.x * mysql-cluster-upgrade-downgrade-compatibility-6.x:: Upgrade and Downgrade Compatibility: MySQL Cluster NDB 6.x * mysql-cluster-upgrade-downgrade-compatibility-5.1:: Upgrade and downgrade compatibility: MySQL 5.1 This section provides information about MySQL Cluster software and table file compatibility between MySQL 5.1.23 and earlier, MySQL Cluster NDB 6.x, and MySQL Cluster NDB 7.x 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 a MySQL Cluster prior to attempting an upgrade or downgrade. See *Note mysql-cluster-configuration::. For information regarding the rolling restart procedure used to perform an online upgrade, see *Note mysql-cluster-rolling-restart::. *Important*: Only compatibility between MySQL versions with regard to *Note `NDBCLUSTER': mysql-cluster. 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 MySQL Cluster software_. See *Note upgrading::. For information about upgrades and downgrades to, from, and between different releases of MySQL Cluster NDB 7.0 and MySQL Cluster NDB 7.1, see *Note mysql-cluster-upgrade-downgrade-compatibility-7.x::. For information about upgrades and downgrades to, from, and between different releases of MySQL Cluster NDB 6.1, MySQL Cluster NDB 6.2, and MySQL Cluster NDB 6.3, see *Note mysql-cluster-upgrade-downgrade-compatibility-6.x::. For information about upgrades and downgrades to, from, and between different releases of MySQL Cluster NDB 7.2, see Upgrading and Downgrading MySQL Cluster NDB 7.2 (http://dev.mysql.com/doc/refman/5.5/en/mysql-cluster-upgrade-downgrade.html). For information about upgrades and downgrades to, from, and between different editions of MySQL Cluster as found in standard MySQL 5.1.23 and earlier releases, see *Note mysql-cluster-upgrade-downgrade-compatibility-5.1::. *Important*: Only compatibility between MySQL versions with regard to *Note `NDBCLUSTER': mysql-cluster. 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 MySQL Cluster software_. See *Note upgrading::.  File: manual.info, Node: mysql-cluster-upgrade-downgrade-compatibility-7.x, Next: mysql-cluster-upgrade-downgrade-compatibility-6.x, Prev: mysql-cluster-upgrade-downgrade, Up: mysql-cluster-upgrade-downgrade 17.2.7.1 Upgrade and downgrade compatibility: MySQL Cluster NDB 7.x ................................................................... The table shown here provides information on MySQL Cluster upgrade and downgrade compatibility among different releases of MySQL Cluster NDB 7.0 and 7.1. Additional notes about upgrades and downgrades to, from, or within the MySQL Cluster NDB 7.x release series can be found immediately following the table. MySQL Cluster upgrade/downgrade compatibility, MySQL Cluster NDB 7.x * Notes: MySQL Cluster NDB 7.x * Versions supported Online upgrades from any MySQL Cluster NDB 7.0 release up to and including MySQL Cluster NDB 7.0.4 (as well as all early releases numbered NDB 6.4.x) to MySQL Cluster NDB 7.0.5 or later are not possible. Upgrades to MySQL Cluster NDB 7.0.6 or later from MySQL Cluster NDB 6.3.8 or a later MySQL Cluster NDB 6.3 release, or from MySQL Cluster NDB 7.0.5 or later, are supported. (Bug #44294) Upgrading `ndbd' to `ndbmtd' When upgrading online from a MySQL Cluster NDB 6.3 release to a MySQL Cluster NDB 7.0 (or later) release, you should not try to upgrade the data nodes from *Note `ndbd': mysql-cluster-programs-ndbd. to *Note `ndbmtd': mysql-cluster-programs-ndbmtd. at the same time. Instead, perform the upgrade using the new *Note `ndbd': mysql-cluster-programs-ndbd. executable (from the MySQL Cluster NDB 7.0 or later distribution to which you are upgrading) to replace the one in use on the data nodes. Once the version upgrade is complete, you can perform a second (online) upgrade to replace the data node executables with *Note `ndbmtd': mysql-cluster-programs-ndbmtd. from the newer distribution. Changing the data node binary type should not be an issue when upgrading from MySQL Cluster NDB 7.0 or later version. Changes in default values In MySQL Cluster NDB 7.0.4, the default values for a number of MySQL Cluster configuration parameters relating to memory usage and buffering changed (see `http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/mysql-cluster-news-5-1-32-ndb-7-0-4.html', for a list of the parameters whose defaults changed). For this reason, you may encounter issues if you try to use a configuration that does not explicitly define each of these buffers (because it was developed for a previous version of MySQL Cluster), `SendBufferMemory' and `ReceiveBufferMemory' in particular. Other known issues include the following: * Prior to MySQL Cluster NDB 7.0.7, DML statements failed if executed while performing an online upgrade from a MySQL Cluster NDB 6.3 release. (Bug #45917) * Following an upgrade from any MySQL Cluster NDB 6.3.x release to MySQL Cluster NDB 7.0.6, DDL and backup operations failed. This issue was resolved in MySQL Cluster NDB 7.0.7. (Bug #46494, Bug #46563) * In some cases, there could be problems with online upgrades from MySQL Cluster NDB 6.3 releases to MySQL Cluster NDB 7.0 releases due to a previous change in the signalling format used between nodes. This issue was corrected in MySQL Cluster NDB 7.0.9. * Once an *Note `NDB': mysql-cluster. table had an *Note `ALTER ONLINE TABLE': alter-table. operation performed on it using a MySQL Cluster NDB 6.3.x release, it could not be upgraded online to MySQL Cluster NDB 7.0. This issue was resolved in MySQL Cluster NDB 7.0.8. (See Bug #47542.) * Following an upgrade from MySQL Cluster NDB 6.3 to MySQL Cluster NDB 7.0, if there were any tables having unique indexes prior to the upgrade, attempts to create unique indexes failed. This could also occur when performing offline *Note `ALTER TABLE': alter-table. operations on tables having indexes that were not dropped as a result of the *Note `ALTER TABLE': alter-table. This issue was due to a change in the way that *Note `NDB': mysql-cluster. tracked unique indexes internally, and was resolved in MySQL Cluster NDB 7.0.9. (Bug #48416) For upgrades to MySQL Cluster NDB 7.0 releases prior to version 7.0.9, a workaround is available: Following the upgrade, execute a _second_ rolling restart of the cluster before before performing any *Note `ALTER TABLE': alter-table. operations involving indexes. * Due to an issue discovered after the release of MySQL Cluster NDB 7.0.10 (Bug #50433), it is not possible to perform an online upgrade from MySQL Cluster NDB 7.0.9b and earlier MySQL Cluster NDB 7.0 releases to MySQL Cluster NDB 7.0.10. Instead, you should upgrade your MySQL Cluster NDB 7.0 installation directly to MySQL Cluster NDB 7.0.11 or later. This issue did not appear to affect MySQL Cluster NDB 6.3, and it should be possible to upgrade online from MySQL Cluster NDB 6.3 to MySQL Cluster NDB 7.0.10 without any problems other than those noted previously. * It was not possible to perform an online upgrade from a MySQL Cluster NDB 6.3 or 7.0 release to MySQL Cluster NDB 7.1.0 or 7.1.1. This issue was fixed in MySQL Cluster NDB 7.1.2 (see Bug #51429). * Following an upgrade to MySQL Cluster NDB 7.0.15 or later (MySQL Cluster NDB 7.0), or to MySQL Cluster NDB 7.1.4 or later (MySQL Cluster NDB 7.1), a table created in a previous version of MySQL Cluster does _not_ automatically support *Note `NDB': mysql-cluster.-native default values. Such a table continues to use default values supplied by the MySQL server until it is upgraded by performing an offline *Note `ALTER TABLE': alter-table. on it. When upgrading to a MySQL Cluster release that supports native default values from a MySQL Cluster release that does not, you should not attempt to create any new tables until all data nodes are using the new *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndbmtd': mysql-cluster-programs-ndbmtd. binaries. This is because the older binaries do not provide support for native default values. *Important*: Tables created with native default value support cannot be used with versions of MySQL Cluster that do not support native default values. * NDB API changes in MySQL Cluster NDB 7.1.16 and MySQL Cluster NDB 7.0.27 are not backward compatible. Due to these changes the version of the included NDB client library was increased from 4.0.0 to 5.0.0; NDB API applications must be recompiled as part of any upgrade to these or later MySQL Cluster releases. In addition, NDB API programs should be updated as part of such an upgrade, in order to take into account changes in the default behavior and values for the `Ndb_cluster_connection::connect()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection-methods.html#ndb-ndb-cluster-connection-connect) method. * Due to issues discovered shortly after release, MySQL Cluster NDB 7.0.20 was withdrawn and replaced with MySQL Cluster NDB 7.0.20a. Users of MySQL Cluster NDB 7.0.19 and previous MySQL Cluster NDB 7.0 releases should upgrade to MySQL Cluster NDB 7.0.20a, or to a later MySQL Cluster NDB 7.0 release. See `http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/mysql-cluster-news-5-1-51-ndb-7-0-20a.html', for more information. Due to issues discovered following release, MySQL Cluster NDB 7.1.15 was withdrawn and replaced with MySQL Cluster NDB 7.1.15a. Users of MySQL Cluster NDB 7.1.14 and previous MySQL Cluster NDB 7.1 releases should upgrade to MySQL Cluster NDB 7.1.15a, or to a later MySQL Cluster NDB 7.1 release. See `http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/mysql-cluster-news-5-1-56-ndb-7-1-15a.html', for more information. Due to issues discovered shortly after release, MySQL Cluster NDB 7.1.9 was withdrawn and replaced with MySQL Cluster NDB 7.1.9a. Users of MySQL Cluster NDB 7.1.8 and previous MySQL Cluster NDB 7.1 releases should upgrade to MySQL Cluster NDB 7.1.14 (the last release directly upgrade-compatible with MySQL Cluster 7.1.18 and earlier) before upgrading to MySQL Cluster 7.1.15a or later. See `http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/mysql-cluster-news-5-1-51-ndb-7-1-9a.html', for more information. * When performing an online upgrade or downgrade between MySQL Cluster NDB 7.1.8 or earlier and a later release up to and including MySQL Cluster NDB 7.1.14, you must upgrade or downgrade the data nodes before upgrading or downgrading any SQL nodes; otherwise *Note `mysql_upgrade': mysql-upgrade. fails on the SQL nodes due to differences between *Note `ndbinfo': mysql-cluster-ndbinfo. tables used in the `old' and `new' versions of the MySQL Cluster software. You should also upgrade or downgrade the data nodes prior to the SQL nodes when performing an online upgrade or downgrade between MySQL Cluster NDB 7.1 releases where either of the versions involved is MySQL Cluster NDB 7.1.14 or earlier, and where one or more *Note `ndbinfo': mysql-cluster-ndbinfo. tables has more, fewer, or differing columns between the two versions. This issue is resolved in MySQL Cluster NDB 7.1.15. (Bug #11885602) * It was not possible to downgrade online to MySQL Cluster NDB 7.1 from some later versions of MySQL Cluster due to a change in the size used for table hash maps by *Note `NDB': mysql-cluster. (Bug #14645319) This issue was resolved in MySQL Cluster NDB 7.1.26, where the size is made configurable using the `DefaultHashMapSize' parameter. (Bug #14800539) See the description of this parameter for more information.  File: manual.info, Node: mysql-cluster-upgrade-downgrade-compatibility-6.x, Next: mysql-cluster-upgrade-downgrade-compatibility-5.1, Prev: mysql-cluster-upgrade-downgrade-compatibility-7.x, Up: mysql-cluster-upgrade-downgrade 17.2.7.2 Upgrade and Downgrade Compatibility: MySQL Cluster NDB 6.x ................................................................... The table shown here provides information on MySQL Cluster upgrade and downgrade compatibility among different releases of MySQL Cluster NDB 6.1, 6.2, and 6.3. Additional notes about upgrades and downgrades to, from, or within the MySQL Cluster NDB 6.x release series can be found immediately following the table. MySQL Cluster upgrade/downgrade compatibility, MySQL Cluster NDB 6.x * Notes: MySQL Cluster NDB 6.1 * Availability of older releases MySQL Cluster NDB 6.1 is no longer in production; information about this series of releases is of historical interest only. MySQL Cluster NDB 6.2 is still available, but is no longer supported in new deployments. If you are still using a MySQL Cluster NDB 6.1 or MySQL Cluster NDB 6.2 release, you should upgrade to the most recent MySQL Cluster NDB 7.0 or MySQL Cluster NDB 7.1 release as soon as possible. * It is not possible to upgrade from MySQL Cluster NDB 6.1.2 (or an older 6.1 release) directly to 6.1.4 or a newer NDB 6.1 release, or to downgrade from 6.1.4 (or a newer 6.1 release) directly to 6.1.2 or an older NDB 6.1 release; in either case, you must upgrade or downgrade to MySQL Cluster NDB 6.1.3 first. * It is not possible to perform an online downgrade from MySQL Cluster NDB 6.1.8 (or a newer 6.1 release) to MySQL Cluster NDB 6.1.7 (or an older 6.1 release). * MySQL Cluster NDB 6.1.6 and 6.1.18 were not released. * It is not possible to perform an online upgrade or downgrade between MySQL Cluster NDB 6.2 and any previous release series (including mainline MySQL 5.1 and MySQL Cluster NDB 6.1); it is necessary to perform a dump and reload. However, it should be possible to perform online upgrades or downgrades between any MySQL Cluster NDB 6.2 release and any MySQL Cluster NDB 6.3 release up to and including 6.3.7. * Notes: MySQL Cluster NDB 6.2 and MySQL Cluster NDB 6.3 * Internal column specification changes The internal specifications for columns in *Note `NDB': mysql-cluster. tables changed in MySQL Cluster NDB 6.1.17 and 6.2.1 to enable compatibility with later MySQL Cluster releases implementing online adding and dropping of columns (MySQL 5.1.17 through MySQL 5.1.23; MySQL Cluster NDB 6.2.3 and later; MySQL Cluster NDB 6.3.2 and later). This change is not backward-compatible with earlier MySQL Server or MySQL Cluster releases. To make tables created in earlier versions compatible with online adding and dropping of columns in later versions, it is necessary to force MySQL Cluster to convert the tables to the new format by following this procedure following an upgrade: 1. Upgrade the MySQL Cluster software on all data, management, and SQL nodes 2. Back up all *Note `NDB': mysql-cluster. tables 3. Shut down the cluster (all data, management, and SQL nodes) 4. Restart the cluster, starting all data nodes with the `--initial' option (to clear and rebuild the data node file systems) 5. Restore the tables from backup To minimize possible later difficulties, it is strongly advised that the procedure outlined above be followed as soon as possible after to upgrading between the versions indicated. The procedure is _not_ necessary for *Note `NDBCLUSTER': mysql-cluster. tables created in any of the following versions: * MySQL Cluster NDB 6.1.8 or a later MySQL Cluster NDB 6.1 release * MySQL Cluster 6.2.1 or a later MySQL Cluster NDB 6.2 release * Any MySQL Cluster NDB 6.3 release (or later MySQL Cluster release series) Tables created in the versions listed previously (or later versions, as indicated) are already compatible with adding and dropping of columns online (as implemented beginning with MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB 6.3.2). Additional issues encountered when upgrading or downgrading to or from MySQL Cluster NDB 6.2 and MySQL Cluster NDB 6.3 releases are listed here: * It was not possible to perform an online upgrade between any MySQL Cluster NDB 6.2 release and MySQL Cluster NDB 6.3.8 and later MySQL Cluster 6.3 releases. This issue was fixed in MySQL Cluster NDB 6.3.21. (Bug #41435) * Online downgrades between MySQL Cluster NDB 6.2.5 and earlier releases are not supported. * Online downgrades between MySQL Cluster NDB 6.3.8 and earlier releases are not supported.  File: manual.info, Node: mysql-cluster-upgrade-downgrade-compatibility-5.1, Prev: mysql-cluster-upgrade-downgrade-compatibility-6.x, Up: mysql-cluster-upgrade-downgrade 17.2.7.3 Upgrade and downgrade compatibility: MySQL 5.1 ....................................................... The table shown here provides information on MySQL Cluster upgrade and downgrade compatibility among different releases of MySQL 5.1 prior to MySQL 5.1.24. Additional notes about upgrades and downgrades to, from, or within the MySQL 5.1 release series can be found immediately following the table. MySQL Cluster upgrade/downgrade compatibility, MySQL 5.1 * Notes: MySQL 5.1 * * MySQL 5.1.3 was the first public release in this series. * Direct upgrades or downgrades between MySQL Cluster 5.0 and 5.1 are not supported; you must dump all *Note `NDBCLUSTER': mysql-cluster. tables using *Note `mysqldump': mysqldump, install the new version of the software, and then reload the tables from the dump. * You cannot downgrade a MySQL Cluster based on MySQL 5.1.6 or later and using Disk Data tables to MySQL 5.1.5 or earlier unless you convert all such tables to in-memory *Note `NDB': mysql-cluster. tables first. * MySQL 5.1.8, MySQL 5.1.10, and MySQL 5.1.13 were not released. * Online cluster upgrades and downgrades between MySQL 5.1.11 (or an earlier version) and 5.1.12 (or a later version) are not possible due to major changes in the cluster file system. In such cases, you must perform a backup or dump, upgrade (or downgrade) the software, start each data node with `--initial', and then restore from the backup or dump. You can use native *Note `NDB': mysql-cluster. backup and restore, or *Note `mysqldump': mysqldump. and *Note `LOAD DATA INFILE': load-data. for this purpose. * Online downgrades from MySQL 5.1.14 or later to versions previous to 5.1.14 are not supported due to incompatible changes in the cluster system tables. MySQL Cluster Replication: changes in `ndb_apply_status' Online upgrades from MySQL 5.1.17 and earlier to 5.1.18 and later MySQL 5.1.x releases are not supported for clusters using replication due to incompatible changes in the `mysql.ndb_apply_status' table. (Online upgrades from MySQL 5.1 to MySQL Cluster NDB 6.2 and later are not supported, as discussed elsewhere in this section.) However, it should not be necessary to shut down the cluster entirely, if you follow this modified rolling restart procedure: 1. Stop the management server, update the management server software, then start the management server again. For multiple management servers, repeat this step for each management server in turn. 2. For each data node in turn: Stop the data node, update the data node daemon (in MySQL Cluster NDB 7.0 and later, this can be either *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndbmtd': mysql-cluster-programs-ndbmtd.) with the new version, then restart the data node. It should not be necessary to use `--initial' when restarting any of the data nodes after updating the software. 3. Stop _all_ SQL nodes. Upgrade the existing MySQL server installations to the new version on all SQL nodes, then restart them. It is not necessary to start them one at a time after upgrading the MySQL server software, but _there must be a time when none of them is running before starting any of them again using the 5.1.18 (or later) *Note `mysqld': mysqld._. Otherwise--due to the fact that `mysql.ndb_apply_status' uses the *Note `NDB': mysql-cluster. storage engine and is thus shared between all SQL nodes--there may be conflicts between the old and new versions of the table on different SQL nodes. You can find more information about the changes to `ndb_apply_status' in *Note mysql-cluster-replication-schema::. *Note*: You should upgrade the MySQL Cluster software on each node using the same method by which it was originally installed. See *Note mysql-cluster-installation::, for more information. As with any other MySQL Cluster version upgrade, you should also update the MySQL Cluster management client (*Note `ndb_mgm': mysql-cluster-programs-ndb-mgm.) and other MySQL Cluster client programs such as *Note `ndb_config': mysql-cluster-programs-ndb-config. and *Note `ndb_error_reporter': mysql-cluster-programs-ndb-error-reporter.; however, this does not have to be done in any particular order. Internal column specification changes The internal specifications for columns in *Note `NDBCLUSTER': mysql-cluster. tables changed in MySQL 5.1.18 to enable compatibility with later MySQL Cluster releases that permit online adding and dropping of columns. _This change is not backward-compatible with earlier MySQL versions_. To make tables created in MySQL 5.1.17 and earlier compatible with online adding and dropping of columns (available beginning with beginning with MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB 6.3.2--see *Note alter-table::, for more information), it is necessary to force MySQL 5.1.18 and later to convert the tables to the new format by following this procedure: 1. Back up all *Note `NDBCLUSTER': mysql-cluster. tables. 2. Upgrade the MySQL Cluster software on all data, management, and SQL nodes. 3. Shut down the cluster completely (this includes all data, management, and API or SQL nodes). 4. Restart the cluster, starting all data nodes with the `--initial' option (to clear and rebuild the data node file systems). 5. Restore the *Note `NDBCLUSTER': mysql-cluster. tables from backup. It is not necessary to follow this procedure for *Note `NDBCLUSTER': mysql-cluster. tables created in MySQL 5.1.18 and later; such tables are already compatible with online adding and dropping of columns (as implemented beginning with MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB 6.3.2). To minimize possible later difficulties, it is strongly advised that the procedure outlined above be followed as soon as possible after to upgrading from MySQL 5.1.17 or earlier to MySQL 5.1.18 or later. Information about how this change effects users of MySQL Cluster NDB 6.x and 7.x is provided later in this section. MySQL Cluster not supported in MySQL Server 5.1.24 and later MySQL Cluster is not supported in standard MySQL 5.1 releases beginning with MySQL 5.1.24. If you are using MySQL Cluster in a standard MySQL 5.1 release, you should upgrade to the most recent MySQL Cluster NDB 7.0 or MySQL Cluster NDB 7.1 release.  File: manual.info, Node: mysql-cluster-configuration, Next: mysql-cluster-programs, Prev: mysql-cluster-installation, Up: mysql-cluster 17.3 Configuration of MySQL Cluster NDB 6.1-7.1 =============================================== * Menu: * mysql-cluster-quick:: Quick Test Setup of MySQL Cluster * mysql-cluster-config-file:: MySQL Cluster Configuration Files * mysql-cluster-params-overview:: Overview of MySQL Cluster Configuration Parameters * mysql-cluster-options-variables:: MySQL Server Options and Variables for MySQL Cluster * mysql-cluster-interconnects:: Using High-Speed Interconnects with MySQL Cluster A MySQL server that is part of a MySQL Cluster differs in one chief respect from a normal (nonclustered) MySQL server, in that it employs the *Note `NDB': mysql-cluster. storage engine. This engine is also referred to sometimes as *Note `NDBCLUSTER': mysql-cluster, although `NDB' is preferred. To avoid unnecessary allocation of resources, the server is configured by default with the *Note `NDB': mysql-cluster. storage engine disabled. To enable *Note `NDB': mysql-cluster, 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 an 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 *Note `mysql': mysql. client. Before the *Note `NDB': mysql-cluster. 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 *Note `mysqld': mysqld. options specific to MySQL Cluster, see *Note mysql-cluster-program-options-mysqld::. For information about installing MySQL Cluster, see *Note mysql-cluster-installation::.  File: manual.info, Node: mysql-cluster-quick, Next: mysql-cluster-config-file, Prev: mysql-cluster-configuration, Up: mysql-cluster-configuration 17.3.1 Quick Test Setup of MySQL Cluster ---------------------------------------- To familiarize you with the basics, we will describe the simplest possible configuration for a functional MySQL 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 SQL nodes. # The empty default sections are not required, and are shown only for # the sake of completeness. # Data nodes must provide a hostname but SQL nodes are not required # to do so. # If you do not 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 *Note `ndb_mgmd': mysql-cluster-programs-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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd.: shell> cd /var/lib/mysql-cluster shell> ndb_mgmd Then start a single data node by running *Note `ndbd': mysql-cluster-programs-ndbd.: shell> ndbd For command-line options which can be used when starting *Note `ndbd': mysql-cluster-programs-ndbd, see *Note mysql-cluster-program-options-common::. By default, *Note `ndbd': mysql-cluster-programs-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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. and *Note `ndbd': mysql-cluster-programs-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 *Note `NDB': mysql-cluster. 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.1.73 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 *Note `NDB': mysql-cluster. 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: 3.5.3, Nodegroup: 0, Master) [ndb_mgmd(MGM)] 1 node(s) id=1 @127.0.0.1 (Version: 3.5.3) [mysqld(API)] 3 node(s) id=3 @127.0.0.1 (Version: 3.5.3) 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 MySQL Cluster. You can now store data in the cluster by using any table created with `ENGINE=NDBCLUSTER' or its alias `ENGINE=NDB'.  File: manual.info, Node: mysql-cluster-config-file, Next: mysql-cluster-params-overview, Prev: mysql-cluster-quick, Up: mysql-cluster-configuration 17.3.2 MySQL Cluster Configuration Files ---------------------------------------- * Menu: * mysql-cluster-config-example:: MySQL Cluster Configuration: Basic Example * mysql-cluster-config-starting:: Recommended Starting Configurations for MySQL Cluster NDB 6.2 and Later * mysql-cluster-connection-strings:: MySQL Cluster Connection Strings * mysql-cluster-computer-definition:: Defining Computers in a MySQL Cluster * mysql-cluster-mgm-definition:: Defining a MySQL Cluster Management Server * mysql-cluster-ndbd-definition:: Defining MySQL Cluster Data Nodes * mysql-cluster-api-definition:: Defining SQL and Other API Nodes in a MySQL Cluster * mysql-cluster-tcp-definition:: MySQL Cluster TCP/IP Connections * mysql-cluster-tcp-definition-direct:: MySQL Cluster TCP/IP Connections Using Direct Connections * mysql-cluster-shm-definition:: MySQL Cluster Shared-Memory Connections * mysql-cluster-sci-definition:: SCI Transport Connections in MySQL Cluster * mysql-cluster-config-lcp-params:: Configuring MySQL Cluster Parameters for Local Checkpoints * mysql-cluster-config-send-buffers:: Configuring MySQL Cluster Send Buffer Parameters Configuring MySQL Cluster requires working with two files: * `my.cnf': Specifies options for all MySQL 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 MySQL 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 Beginning with MySQL Cluster NDB 6.4.0, MySQL Cluster uses _stateful configuration_. The global configuration file is no longer read every time the management server is restarted. Instead, 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 items is true: * The management server is started using the `--initial' option In this case, 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 In this case, the management server compares 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 a `--config-cache' option Beginning with MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, this option 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 Beginning with MySQL Cluster 6.4.0, the management server by default creates configuration cache files in a directory named `mysql-cluster' in the MySQL installation directory. (If you build MySQL 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', `--initial', and `--reload' options for the MySQL Cluster management server, see *Note 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 *Note bug-reports::.  File: manual.info, Node: mysql-cluster-config-example, Next: mysql-cluster-config-starting, Prev: mysql-cluster-config-file, Up: mysql-cluster-config-file 17.3.2.1 MySQL Cluster Configuration: Basic Example ................................................... To support MySQL 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 MySQL Cluster # (valid in MySQL 5.1) # 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 *Note mysql-cluster-connection-strings::.) # my.cnf # example additions to my.cnf for MySQL 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 *Note `mysqld': mysqld. process with the *Note `NDBCLUSTER': mysql-cluster. and `ndb-connectstring' parameters in the `[mysqld]' in the `my.cnf' file as shown previously, you cannot execute any *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': 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 *Note `NDB': mysql-cluster. variables that can be set in the `my.cnf' file, see *Note mysql-cluster-system-variables::. The MySQL Cluster global configuration file is by convention named `config.ini' (but this is not required). It is read by *Note `ndb_mgmd': mysql-cluster-programs-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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. on the command line. Beginning with MySQL Cluster NDB 6.4.0, this option has no default value, and is ignored if *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. uses the configuration cache. The global configuration file for MySQL 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'. (Prior to MySQL Cluster NDB 6.3.25 and MySQL Cluster NDB 7.0.6, there was no default value for `NoOfReplicas', which always had to be specified explicitly in the `[ndbd default]' section. Beginning with versions just stated, the default value is 2, which is the recommended setting in most common usage scenarios.) 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. 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 SQL nodes 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 SQL node 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 MySQL Cluster, and is almost certain not to be sufficient for production settings. See *Note mysql-cluster-config-starting::, which provides more complete example starting configurations for use with MySQL Cluster NDB 6.2 and newer versions of MySQL Cluster. 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 MySQL Cluster, but be may used as a convenience when setting up a large cluster. See *Note mysql-cluster-computer-definition::, for more information. * `[ndbd]': Defines a cluster data node (*Note `ndbd': mysql-cluster-programs-ndbd. process). See *Note 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 *Note mysql-cluster-api-definition::. * `[mgm]' or `[ndb_mgmd]': Defines a cluster management server (MGM) node. For information concerning the configuration of management nodes, see *Note 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 a MySQL Cluster, as the cluster handles this automatically; however, it may be necessary in some situations to override the defaults provided by the cluster. See *Note mysql-cluster-tcp-definition::, for information about available TCP/IP configuration parameters and how to use them. (You may also find *Note mysql-cluster-tcp-definition-direct:: to be of interest in some cases.) * `[shm]': Defines shared-memory connections between nodes. In MySQL 5.1, it is enabled by default, but should still be considered experimental. For a discussion of SHM interconnects, see *Note mysql-cluster-shm-definition::. * `[sci]':Defines _Scalable Coherent Interface_ connections between cluster data nodes. Such connections require software which, while freely available, is not part of the MySQL Cluster distribution, as well as specialized hardware. See *Note mysql-cluster-sci-definition:: for detailed information about SCI interconnects. You can define `default' values for each section. All Cluster parameter names are case-insensitive, which differs from parameters specified in `my.cnf' or `my.ini' files.  File: manual.info, Node: mysql-cluster-config-starting, Next: mysql-cluster-connection-strings, Prev: mysql-cluster-config-example, Up: mysql-cluster-config-file 17.3.2.2 Recommended Starting Configurations for MySQL Cluster NDB 6.2 and Later ................................................................................ Achieving the best performance from a MySQL Cluster depends on a number of factors including the following: * MySQL 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 MySQL 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 MySQL 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 recommended base configurations for MySQL Cluster NDB 6.2 and 6.3 that can serve as reasonable starting points. Starting configuration for MySQL Cluster NDB 6.2 The following is a recommended starting point for configuring a cluster running MySQL Cluster NDB 6.2. # 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-1-HOSTNAME # `NodeId'=MANAGEMENT-SERVER-1-NODEID [ndb_mgmd] `HostName'=MANAGEMENT-SERVER-2-HOSTNAME # 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 node ID 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 *Note ndb_size.pl: mysql-cluster-programs-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 MySQL Cluster NDB 6.2.3 or # newer on systems running Linux kernel 2.6 or later. `NoOfFragmentLogFiles'=300 `DataDir'=PATH/TO/DATA/NODE/DATA/DIRECTORY `MaxNoOfConcurrentOperations'=100000 `TimeBetweenGlobalCheckpoints'=1000 `TimeBetweenEpochs'=200 `DiskCheckpointSpeed'=10M `DiskCheckpointSpeedInRestart'=100M `RedoBuffer'=32M # `MaxNoOfLocalScans'=64 `MaxNoOfTables'=1024 `MaxNoOfOrderedIndexes'=256 [ndbd] `HostName'=DATA-NODE-A-HOSTNAME # `NodeId'=DATA-NODE-A-NODEID [ndbd] `HostName'=DATA-NODE-B-HOSTNAME # `NodeId'=DATA-NODE-B-NODEID # 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 an Id 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-1-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 (Id 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. Starting configuration for MySQL Cluster NDB 6.3 The following is a recommended starting point for configuring a cluster running MySQL Cluster NDB 6.3. It is similar to the recommendation for MySQL Cluster NDB 6.2, with the addition of parameters for better control of *Note `NDBCLUSTER': mysql-cluster. process threads. # 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 *Note ndb_size.pl: mysql-cluster-programs-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 MySQL Cluster NDB 6.2.3 or # newer 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 (introduced in MySQL Cluster NDB 6.3.4) to achieve increased # throughput when using *Note `ndbd': mysql-cluster-programs-ndbd. They are not needed when using *Note `ndbmtd': mysql-cluster-programs-ndbmtd.; in # particular, you should not set `RealTimeScheduler' for *Note `ndbmtd': mysql-cluster-programs-ndbmtd. data nodes. `TimeBetweenGlobalCheckpoints'=1000 `TimeBetweenEpochs'=200 `DiskCheckpointSpeed'=10M `DiskCheckpointSpeedInRestart'=100M `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 MySQL 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 *Note `mysqld': 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'  File: manual.info, Node: mysql-cluster-connection-strings, Next: mysql-cluster-computer-definition, Prev: mysql-cluster-config-starting, Up: mysql-cluster-config-file 17.3.2.3 MySQL Cluster Connection Strings ......................................... With the exception of the MySQL Cluster management server (*Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd.), each node that is part of a MySQL 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,192.168.0.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. A MySQL 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. Beginning with MySQL Cluster NDB 6.3.19, it is also possible in a connection string to specify 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 `192.168.178.242' regardless of the management server to which it connects: bind-address=192.168.178.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=192.168.178.242 In this case, the node uses `localhost' to connect to the management server running on the host named `poseidon' and `192.168.178.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 `192.168.178.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=192.168.178.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. Previous to MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, the maximum length of a connection string was 1024 characters.  File: manual.info, Node: mysql-cluster-computer-definition, Next: mysql-cluster-mgm-definition, Prev: mysql-cluster-connection-strings, Up: mysql-cluster-config-file 17.3.2.4 Defining Computers in a MySQL 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 string [none] ... *Restart Type:* IS 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 name or IP [none] ... address *Restart Type:* S This is the computer's hostname or IP address.  File: manual.info, Node: mysql-cluster-mgm-definition, Next: mysql-cluster-ndbd-definition, Prev: mysql-cluster-computer-definition, Up: mysql-cluster-config-file 17.3.2.5 Defining a MySQL Cluster Management Server ................................................... The `[ndb_mgmd]' section is used to configure the behavior of the management server. `[mgm]' can be used as an alias; the two section names are equivalent. 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 1 - 63 NDB 6.1.1 unsigned [none] 1 - 255 *Restart Type:* IS 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 63 inclusive (previous to MySQL Cluster NDB 6.1.1), or in the range 1 to 255 inclusive (MySQL Cluster NDB 6.1.1 and later). This ID is used by all internal cluster messages for addressing the node, and so must be unique for each MySQL Cluster node, regardless of the type of node. *Note*: Data node IDs must be less than 49, regardless of the MySQL 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 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' beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.39, MySQL Cluster NDB 7.0.20, and MySQL Cluster NDB 7.1.9. Although `Id' continues to be supported for backward compatibility, it now generates a warning. * `NodeId' This table provides type and value information for the NodeId management node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 1 - 63 NDB 6.1.1 unsigned [none] 1 - 255 *Restart Type:* IS 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 63 inclusive (previous to MySQL Cluster NDB 6.1.1), or in the range 1 to 255 inclusive (MySQL Cluster NDB 6.1.1 and later). This ID is used by all internal cluster messages for addressing the node, and so must be unique for each MySQL Cluster node, regardless of the type of node. *Note*: Data node IDs must be less than 49, regardless of the MySQL 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 management nodes (and API nodes) to values greater than 48. `NodeId' is the preferred parameter name to use when identifying management nodes beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.39, MySQL Cluster NDB 7.0.20, and MySQL Cluster NDB 7.1.9. Although `Id' continues to be supported for backward compatibility, it is now deprecated and generates a warning when used. * `ExecuteOnComputer' This table provides type and value information for the ExecuteOnComputer management node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 name [none] ... *Restart Type:* S This refers to the `Id' set for one of the computers defined in a `[computer]' section of the `config.ini' file. * `PortNumber' This table provides type and value information for the PortNumber management node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned 1186 0 - 64K *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 name or IP [none] ... address *Restart Type:* S 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. * `LogDestination' This table provides type and value information for the LogDestination management node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 {CONSOLE|SYSLOG|FILE}[see text] ... *Restart Type:* N 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. Prior to MySQL Cluster NDB 7.0.43 and MySQL Cluster NDB 7.1.23, the log file's default name, used if `FILE' was specified without also setting `filename', was `logger.log'. Beginning with MySQL Cluster NDB 7.0.43 and MySQL Cluster NDB 7.1.23, 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 0-2 1 0 - 2 *Restart Type:* N 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). Beginning with MySQL 5.1.16 and MySQL Cluster NDB 6.1.3, it is possible to disable arbitration completely by setting `ArbitrationRank' to 0 on all management and SQL nodes. In MySQL Cluster NDB 7.0.7 and later releases, you can also control arbitration by overriding this parameter; to do this, 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 management node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 0 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 path . ... *Restart Type:* N 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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. is located. * `HeartbeatThreadPriority' Beginning with MySQL Cluster NDB 6.3.32, MySQL Cluster NDB 7.0.13, and MySQL Cluster NDB 7.1.2, it is possible to 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 out) or `RR' (round robin). The policy value is followed optionally by the priority (an integer). * `ExtraSendBufferMemory' This table provides type and value information for the ExtraSendBufferMemory management node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.0.39 bytes 0 0 - 32G *Restart Type:* N 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. This parameter was added in MySQL Cluster NDB 7.0.39 and MySQL Cluster NDB 7.1.28. (Bug #14555359) * `TotalSendBufferMemory' This table provides type and value information for the TotalSendBufferMemory management node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.4.0 bytes 256K 0 - 4G *Restart Type:* N This parameter is available beginning with MySQL Cluster NDB 6.4.0. It 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; the maxmimum is 4294967039. For more detailed information about the behavior and use of `TotalSendBufferMemory' and configuring send buffer memory parameters in MySQL Cluster NDB 6.4.0 and later, see *Note mysql-cluster-config-send-buffers::. *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 MySQL 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 *Note mysql-cluster-limitations-multiple-nodes::.  File: manual.info, Node: mysql-cluster-ndbd-definition, Next: mysql-cluster-api-definition, Prev: mysql-cluster-mgm-definition, Up: mysql-cluster-config-file 17.3.2.6 Defining MySQL 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 *Note `ndbd': mysql-cluster-programs-ndbd. or (in MySQL Cluster NDB 6.4.0 and later) *Note `ndbmtd': mysql-cluster-programs-ndbmtd. binaries for the data node processes. There are many parameters which control buffer sizes, pool sizes, timeouts, and so forth. The only mandatory parameters are: * Either `ExecuteOnComputer' or `HostName', which must be defined in the local `[ndbd]' section. * The parameter `NoOfReplicas', which must be defined in the `[ndbd default]' section, as it is common to all Cluster data nodes. *Note*: It is no longer strictly necessary to set `NoOfReplicas' starting with MySQL Cluster NDB 6.3.25 and MySQL Cluster NDB 7.0.6, where it acquires a default value (2). However, it remains 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 currently case-sensitive. Information about configuration parameters specific to MySQL Cluster Disk Data tables can be found later in this section (see *Note mysql-cluster-ndbd-definition-disk-data-parameters::). Beginning with MySQL Cluster NDB 6.4.0, all of these parameters also apply to *Note `ndbmtd': mysql-cluster-programs-ndbmtd. (the multi-threaded version of *Note `ndbd': mysql-cluster-programs-ndbd.). Two additional data node configuration parameters--`MaxNoOfExecutionThreads' and `ThreadConfig'--apply to *Note `ndbmtd': mysql-cluster-programs-ndbmtd. only; these have no effect when used with *Note `ndbd': mysql-cluster-programs-ndbd. For more information, see *Note mysql-cluster-ndbd-definition-ndbmtd-parameters::. See also *Note 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. * `Id' This table provides type and value information for the Id data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 1 - 48 *Restart Type:* IS 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 preferred parameter name to use when identifying data nodes beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.39, MySQL Cluster NDB 7.0.20, and MySQL Cluster NDB 7.1.9. Although `Id' continues to be supported for backward compatibility, it is now deprecated and generates a warning when used. * `NodeId' This table provides type and value information for the NodeId data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 1 - 48 *Restart Type:* IS 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 preferred parameter name to use when identifying data nodes beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.39, MySQL Cluster NDB 7.0.20, and MySQL Cluster NDB 7.1.9. Although `Id' continues to be supported for backward compatibility, it is now deprecated and generates a warning when used. * `ExecuteOnComputer' This table provides type and value information for the ExecuteOnComputer data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 name [none] ... *Restart Type:* S This refers to the `Id' set for one of the computers defined in a `[computer]' section. * `HostName' This table provides type and value information for the HostName data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 name or IP localhost ... address *Restart Type:* S 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 1 - 64K *Restart Type:* N 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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. management port (the management server's `PortNumber'; see *Note mysql-cluster-mgm-definition::) 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'). This parameter was added in MySQL Cluster NDB 6.2.0. * `NodeGroup' This table provides type and value information for the NodeGroup data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.4.0 [none] 0 - 65536 *Restart Type:* IS 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 MySQL 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 *Note mysql-cluster-online-add-node-example::. This parameter was added in MySQL Cluster NDB 6.4.0. * `NoOfReplicas' This table provides type and value information for the NoOfReplicas data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer [none] 1 - 4 NDB 6.3.25 integer 2 1 - 4 NDB 7.0.6 integer 2 1 - 4 *Restart Type:* IS 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. Prior to MySQL Cluster NDB 6.3.25 and MySQL Cluster NDB 7.0.6, there was no default value for `NoOfReplicas'; beginning with these versions, the default value is 2, which is the recommended setting in most common usage scenarios. (Bug #44746) The maximum possible value is 4; _currently, only the values 1 and 2 are actually supported_. *Important*: 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 path . ... *Restart Type:* IN 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 path DataDir ... *Restart Type:* IN 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 *Note `ndbd': mysql-cluster-programs-ndbd. process is initiated. The recommended directory hierarchy for MySQL 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 path [see text] ... *Restart Type:* IN 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: * `DataMemory' This table provides type and value information for the DataMemory data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 80M 1M - 1024G *Restart Type:* N 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 in MySQL 5.1, the data is stored on separate datapages, 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. Prior to MySQL Cluster NDB 7.0, the maximum record size was 8052 bytes; in MySQL Cluster NDB 7.0 and later, it is 14000 bytes. 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 *Note `ndb_desc -d DB_NAME TABLE_NAME': mysql-cluster-programs-ndb-desc. in the management client. Currently, MySQL 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 *Note `ndb_mgm -e "ALL REPORT MEMORYUSAGE"': mysql-cluster-programs-ndb-mgm. shows significant free `DataMemory'. This can also pose a problem with data node restarts on nodes that are heavily loaded with data. You can force *Note `NDB': mysql-cluster. to create extra partitions for MySQL Cluster tables and thus have more memory available for hash indexes by using the `MAX_ROWS' option for *Note `CREATE TABLE': create-table. In general, setting `MAX_ROWS' to twice the number of rows that you expect to store in the table should be sufficient. In MySQL Cluster 7.1.18 and later, you can also use the `MinFreePct' configuration parameter to help avoid problems with node restarts. (Bug #13436216) 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'. In addition, due to the way in which new pages are allocated when the capacity of the current page is exhausted, there is an additional overhead of approximately 18.75%. When more `DataMemory' is required, more than one new page is allocated, according to the following formula: number of new pages = FLOOR(number of current pages x 0.1875) + 1 For example, if 15 pages are currently allocated to a given table and an insert to this table requires additional storage space, the number of new pages allocated to the table is `FLOOR(15 x 0.1875) + 1 = FLOOR(2.8125) + 1 = 2 + 1 = 3'. Now 15 + 3 = 18 memory pages are allocated to the table. When the last of these 18 pages becomes full, `FLOOR(18 x 0.1875) + 1 = FLOOR(3.3750) + 1 = 3 + 1 = 4' new pages are allocated, so the total number of pages allocated to the table is now 22. *Note*: The `18.75% + 1' overhead is no longer required beginning with MySQL Cluster NDB 6.2.3 and MySQL Cluster NDB 6.3.0. 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 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 The default value for `DataMemory' is 80MB; the minimum 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 18M 1M - 1T *Restart Type:* N This parameter controls the amount of storage used for hash indexes in MySQL Cluster. Hash indexes are always used for primary key indexes, unique indexes, and unique constraints. Note that when defining a primary key and a unique index, two indexes will be created, one of which is a hash index used for all tuple accesses as well as lock handling. It is also used to enforce unique constraints. The size of the hash index is 25 bytes per record, plus the size of the primary key. For primary keys larger than 32 bytes another 8 bytes is added. The default value for `IndexMemory' is 18MB. The minimum is 1MB. * `StringMemory' This table provides type and value information for the StringMemory data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 % or bytes 0 0 - 4G MySQL 5.1.32 % or bytes 25 0 - 4G MySQL 5.1.6 % or bytes 5 0 - 4G NDB 7.2.1 % or bytes 25 0 - 4G *Restart Type:* S 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. (Previously, prior to MySQL Cluster NDB 6.2.18, MySQL Cluster NDB 6.3.24, and MySQL Cluster NDB 7.0.5, the default value was 5; prior to MySQL 5.1.6, the default was 0.) Under most circumstances, the default value should be sufficient, but when you have a great many Cluster 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 MySQL 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 MySQL 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. Beginning with MySQL Cluster NDB 7.0.29 and MySQL Cluster NDB 7.1.18, 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) introduced in the same versions of MySQL Cluster. This table provides type and value information for the MinFreePct data node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.0.29 unsigned 5 0 - 100 NDB 7.1.18 unsigned 5 0 - 100 NDB 7.2.3 unsigned 5 0 - 100 *Restart Type:* N 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', added in MySQL Cluster NDB 7.0.26 and MySQL Cluster NDB 7.1.15, 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 4096 32 - 4G *Restart Type:* S 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 an SQL node requires at least one transaction record, plus an additional transaction object per table accessed by that connection. This means that a reasonable minimum for this parameter is MaxNoOfConcurrentTransactions = (maximum number of tables accessed in any single transaction + 1) * number of cluster 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 SQL node, or 110 * 10 = 1100 transaction records total. Each data node can be expected to handle TotalNoOfConcurrentTransactions / number of data nodes. For a MySQL 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 insuring 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 transaction 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. Changing the value of `MaxNoOfConcurrentTransactions' requires a complete shutdown and restart of the cluster. The default value is 4096. * `MaxNoOfConcurrentOperations' This table provides type and value information for the MaxNoOfConcurrentOperations data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 32K 32 - 4G *Restart Type:* N It is a good idea to adjust the value of this parameter according to the size and number of transactions. When performing transactions of only a few operations each and not involving a great many records, there is no need to set this parameter very high. When performing large transactions involving many records need to set this parameter higher. 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 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer UNDEFINED 32 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values NDB 7.0.26 operations (DML) 4294967295 32 - 4294967295 NDB 7.1.15 operations (DML) 4294967295 32 - 4294967295 *Restart Type:* N Added in MySQL Cluster NDB 7.0.26 and MySQL Cluster NDB 7.1.15, 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 8K 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 4000 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 1M 1K - 4G *Restart Type:* N 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. * `MaxNoOfConcurrentScans' This table provides type and value information for the MaxNoOfConcurrentScans data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 256 2 - 500 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer UNDEFINED 32 - 4G *Restart Type:* N Specifies the number of local scan records if many scans are not fully parallelized. In MySQL Cluster NDB 7.2.0 and later, when the number of local scan records is not provided, it is calculated as 4 times the product of `MaxNoOfConcurrentScans' and the number of data nodes in the system. (Previously, it was calculated as the product of `MaxNoOfConcurrentScans' and the number of data nodes.) The minimum value is 32. * `BatchSizePerLocalScan' This table provides type and value information for the BatchSizePerLocalScan data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 64 1 - 992 NDB 7.2.1 integer 256 1 - 992 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 1M 512K - 4G NDB 7.0.4 bytes 4M 512K - 4G *Restart Type:* N This is an internal buffer used for passing messages within individual nodes and between nodes. In MySQL Cluster NDB 6.4.3 and earlier, the default is 1MB; beginning with MySQL Cluster NDB 7.0.4, it is 4MB. This parameter seldom needs to be changed from the default. However, when replicating a MySQL Cluster using *Note `ndbmtd': mysql-cluster-programs-ndbmtd. for the data nodes, you may need to increase this value to 8MB (or possibly more) to prevent data node instability, because *Note `ndbmtd': mysql-cluster-programs-ndbmtd. uses much more of this resource than *Note `ndbd': mysql-cluster-programs-ndbd. does. Beginning with MySQL Cluster NDB 7.0.13 and MySQL Cluster NDB 7.1.2, this should no longer be necessary when using *Note `ndbmtd': mysql-cluster-programs-ndbmtd. with MySQL Cluster Replication (Bug #46914). * `MaxParallelScansPerFragment' This table provides type and value information for the MaxParallelScansPerFragment data node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.0.23 bytes 32 1 - 1G NDB 7.1.12 bytes 32 1 - 1G NDB 7.2.0 bytes 256 1 - 1G *Restart Type:* N Beginning with MySQL Cluster NDB 7.0.23 and MySQL Cluster NDB 7.1.12, it is possible to configure the maximum number of parallel scans (`TUP' scans and `TUX' scans) allowed before they begin queuing for serial handling. (Previously, the maximum number of parallel scans per fragment was fixed at 32.) You can increase this to take advantage of any unused CPU when performing large number of scans in parallel and improve their performance. Beginning with MySQL Cluster NDB 7.2.0, the default value for this parameter is increased from 32 to 256. * Memory Allocation * `MaxAllocate' This table provides type and value information for the MaxAllocate data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.1.19 unsigned 32M 1M - 1G NDB 6.2.3 unsigned 32M 1M - 1G MySQL 5.1.20 unsigned 32M 1M - 1G *Restart Type:* N This is the maximum size of the memory unit to use when allocating memory for tables. In cases where *Note `NDB': mysql-cluster. gives `Out of memory' errors, but it is evident by examining the cluster logs or the output of `DUMP 1000' (see `DUMP 1000' (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-dump-command-1000.html)) that all available memory has not yet been used, you can increase the value of this parameter (or `MaxNoOfTables', or both) to cause *Note `NDB': mysql-cluster. to make sufficient memory available. This parameter was introduced in MySQL 5.1.20, MySQL Cluster NDB 6.1.12 and MySQL Cluster NDB 6.2.3. * Hash Map Size * `DefaultHashMapSize' This table provides type and value information for the DefaultHashMapSize data node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.0.38 LDM threads 240 0 - 3840 NDB 7.1.27 LDM threads 240 0 - 3840 *Restart Type:* N Beginning with MySQL Cluster NDB 7.0.38 and MySQL Cluster NDB 7.1.26, the size of the table hash maps used by *Note `NDB': mysql-cluster. is configurable using this parameter; previously this value was hard-coded. `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 and their effects 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 MySQL Cluster NDB 7.1 and MySQL Cluster NDB 7.0 (and earlier) releases; effectively the only value prior to versions 7.0.38 and 7.1.26 (when this parameter was introduced). `3840' Larger hash map size available beginning with MySQL Cluster NDB 7.0.38 and MySQL Cluster NDB 7.1.26 The primary intended use for this parameter is to facilitate upgrades and esecially downgrades between MySQL Cluster NDB 7.1 and later MySQL Cluster versions in which the larger hash map size (3840) is the default; by setting this parameter to 240 prior to performing an upgrade, you can cause the cluster to continue using the smaller size for table hash maps, in which case the tables remain compatible with earlier versions. `DefaultHashMapSize' can be set for individual data nodes, API nodes, or both, but setting it once only, in the `[ndbd default]' section of the `config.ini' file, is the recommended practice. You can also set this parameter to 0, in which case the default value is used. After increasing this parameter, to have existing tables to take advantage of the new size, you can run *Note `ALTER TABLE ... REORGANIZE PARTITION': alter-table-partition-operations. on them, after which they can use the larger hash map size. This is in addition to performing a rolling restart, which makes the larger hash maps available to new tables, but does not enable existing tables to use them. Decreasing this parameter online after any tables have been created or modified with `DefaultHashMapSize' equal to 3840 is not currently supported. Logging and checkpointing The following `[ndbd]' parameters control log and checkpoint behavior. * `NoOfFragmentLogFiles' This table provides type and value information for the NoOfFragmentLogFiles data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 8 3 - 4G MySQL 5.1.0 integer 16 3 - 4G *Restart Type:* IN 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 the required number of local checkpoints has been completed since that log record was inserted (prior to MySQL Cluster NDB 6.3.8, this was 3 local checkpoints; in later versions of MySQL Cluster, only 2 local checkpoints are necessary). Checkpointing frequency is determined by its own set of configuration parameters discussed elsewhere in this chapter. How these parameters interact and proposals for how to configure them are discussed in *Note mysql-cluster-config-lcp-params::. The default parameter value is 16, which by default means 16 sets of 4 16MB files for a total of 1024MB. Beginning with MySQL Cluster NDB 6.1.1, 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). * `FragmentLogFileSize' This table provides type and value information for the FragmentLogFileSize data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.1.11 bytes 16M 4M - 1G *Restart Type:* IN Setting this parameter enables you to control directly the size of redo log files. This can be useful in situations when MySQL 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. `FragmentLogFileSize' was added in MySQL Cluster NDB 6.1.11. For more information about fragment log files, see the description for `NoOfFragmentLogFiles'. * `InitFragmentLogFiles' This table provides type and value information for the InitFragmentLogFiles data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.19 [see values] SPARSE SPARSE, FULL *Restart Type:* IN 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. Beginning with MySQL Cluster NDB 6.3.19, 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 mean of this parameter. `InitFragmentLogFiles' takes one 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. * `MaxNoOfOpenFiles' This table provides type and value information for the MaxNoOfOpenFiles data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 40 20 - 4G MySQL 5.1.16 unsigned 0 20 - 4G *Restart Type:* N 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. (Prior to MySQL 5.1.16, the default was 40.) However, the minimum value to which this parameter can be set is 20. * `InitialNoOfOpenFiles' This table provides type and value information for the InitialNoOfOpenFiles data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.9 files 27 20 - 4G *Restart Type:* N This parameter sets the initial number of internal threads to allocate for open files. The default value is 27. * `MaxNoOfSavedMessages' This table provides type and value information for the MaxNoOfSavedMessages data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 25 0 - 4G *Restart Type:* N This parameter sets the maximum number of trace files that are kept before overwriting old ones. Trace files are generated when, for whatever reason, the node crashes. The default is 25 trace files. * `MaxLCPStartDelay' This table provides type and value information for the MaxLCPStartDelay data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.23 seconds 0 0 - 600 NDB 6.4.3 seconds 0 0 - 600 *Restart Type:* N In parallel data node recovery (supported in MySQL Cluster NDB 6.3.8 and later), 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. Beginning with MySQL Cluster NDB 6.3.23 and MySQL Cluster NDB 6.4.3, 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, you can 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. 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 that 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 1000 32 - 4G *Restart Type:* N 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. Prior to MySQL Cluster NDB 6.3.45, MySQL Cluster NDB 7.0.26, and MySQL Cluster NDB 7.1.15, this parameter was sometimes treated as a hard limit for certain operations. This caused problems with MySQL 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. (Bug #61684) 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 *Note `ALTER TABLE': alter-table. statements that you might want to perform in the future. This is due to the fact, during the execution of *Note `ALTER TABLE': 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 MySQL 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 *Note `ALTER TABLE': 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 128 8 - 20320 *Restart Type:* N 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. Prior to MySQL Cluster NDB 6.3.45, MySQL Cluster NDB 7.0.26, and MySQL Cluster NDB 7.1.15, this parameter was sometimes treated as a hard limit for certain operations. This caused problems with MySQL 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 *Note `BLOB': blob. data type an extra table is used to store most of the *Note `BLOB': 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 128 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 64 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 768 0 - 4G *Restart Type:* N 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. * `MaxNoOfIndexes' This parameter is deprecated. You should use `MaxNoOfOrderedIndexes' and `MaxNoOfUniqueHashIndexes' instead. This parameter is used only by unique hash indexes. There needs to be one record in this pool for each unique hash index defined in the cluster. The default value of this parameter is 128. * `MaxNoOfSubscriptions' This table provides type and value information for the MaxNoOfSubscriptions data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.2.10 unsigned 0 0 - 4G NDB 6.3.7 unsigned 0 0 - 4G *Restart Type:* N Each *Note `NDB': mysql-cluster. table in a MySQL Cluster requires a subscription in the NDB kernel. For some NDB API applications, it may be necessary or desirable to change this parameter, which became available in MySQL Cluster NDB 6.2.10 and MySQL Cluster NDB 6.3.7. 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 Effective Version Type/Units Default Range/Values NDB 6.2.10 unsigned 0 0 - 4G NDB 6.3.7 unsigned 0 0 - 4G *Restart Type:* N This parameter, added in MySQL Cluster NDB 6.2.10 and MySQL Cluster NDB 6.3.7, is of interest only when using MySQL Cluster Replication. The default value is 0, which is treated as `2 * MaxNoOfTables'; that is, there is one subscription per *Note `NDB': mysql-cluster. 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 *Note `mysqld': 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 MySQL Clusters, with one *Note `mysqld': mysqld. attached to each cluster, and each of these *Note `mysqld': mysqld. processes acts as a master and as a slave, you should set `MaxNoOfSubscribers' equal to `3 * MaxNoOfTables'. For more information, see *Note mysql-cluster-replication::. * `MaxNoOfConcurrentSubOperations' This table provides type and value information for the MaxNoOfConcurrentSubOperations data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.2.10 unsigned 256 0 - 4G NDB 6.3.7 unsigned 256 0 - 4G *Restart Type:* N 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. This parameter was added in MySQL Cluster NDB 6.2.10 and MySQL Cluster NDB 6.3.7. 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'. * `LockPagesInMainMemory' This table provides type and value information for the LockPagesInMainMemory data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 numeric 0 0 - 2 MySQL 5.1.0 true|false (1|0) 0 0 - 1 MySQL 5.1.15 numeric 0 0 - 2 *Restart Type:* N 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. Beginning with MySQL 5.1.15 and MySQL Cluster NDB 6.1.1, this parameter takes one of the integer values `0', `1', or `2', which act as follows: * `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. Previously, 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. *Important*: Beginning with MySQL 5.1.15 and MySQL Cluster NDB 6.1.1, it is no longer possible to use `true' or `false' for the value of this parameter; when upgrading from a previous version, you must change the value to `0', `1', or `2'. Prior to MySQL Cluster NDB 6.3.31 and MySQL Cluster NDB 7.0.11, setting this parameter did not cause the stated memory to be allocated when the node was started, but rather only when the memory was used by the data node process for other reasons. (Bug #37430) *Note*: 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'). *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 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 boolean true true, false *Restart Type:* N This parameter specifies whether a data node process should exit or perform an automatic restart when an error condition is encountered. This feature is enabled by default. * `CrashOnCorruptedTuple' This table provides type and value information for the CrashOnCorruptedTuple data node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.0.28, boolean false true, false 5.1.56-ndb-7.1.17 NDB 7.2.1 boolean true true, false *Restart Type:* S This parameter was introduced in MySQL Cluster NDB 7.0.28 and MySQL Cluster NDB 7.1.17. When enabled, it forces a data node to shut down whenever it encounters a corrupted tuple. By default, it is disabled. * `Diskless' This table provides type and value information for the Diskless data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 true|false (1|0) false true, false *Restart Type:* IS It is possible to specify MySQL 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 *Note `ndbd': mysql-cluster-programs-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 Effective Version Type/Units Default Range/Values NDB 6.1.11 boolean false true, false NDB 6.2.3 boolean false true, false NDB 6.3.0 boolean false true, false *Restart Type:* N Enabling this parameter causes *Note `NDB': mysql-cluster. to attempt using `O_DIRECT' writes for LCP, backups, and redo logs, often lowering `kswapd' and CPU usage. When using MySQL Cluster on Linux, enable `ODirect' if you are using a 2.6 or later kernel. This parameter was added in MySQL 5.1.20, MySQL Cluster NDB 6.1.11, MySQL Cluster NDB 6.2.3, and MySQL Cluster NDB 6.3.0. `ODirect' is disabled by default. * `RestartOnErrorInsert' This table provides type and value information for the RestartOnErrorInsert data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 error code 2 0 - 4 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values NDB 6.3.7 boolean false true, false *Restart Type:* N Setting this parameter to `1' 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). This parameter was introduced in MySQL Cluster NDB 6.3.7. * `CompressedLCP' This table provides type and value information for the CompressedLCP data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.7 boolean false true, false *Restart Type:* N 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). This parameter was introduced in MySQL Cluster NDB 6.3.7. * 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 6000 70 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.20 milliseconds 6000 70 - 4G *Restart Type:* N This is similar to the `TimeBetweenWatchDogCheck' parameter, except that `TimeBetweenWatchDogCheckInitial' controls the amount of time that passes between execution checks inside a database node in the early start phases during which memory is allocated. The default timeout is 6000 milliseconds (6 seconds). This parameter was added in MySQL 5.1.20. * `StartPartialTimeout' This table provides type and value information for the StartPartialTimeout data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 30000 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 60000 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 0 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values NDB 7.0.24 milliseconds 15000 0 - 4294967039 *Restart Type:* N 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. This parameter was added in MySQL Cluster NDB 7.0.24 and MySQL Cluster NDB 7.1.13. See *Note mysql-cluster-online-add-node::, for more information. * `HeartbeatIntervalDbDb' This table provides type and value information for the HeartbeatIntervalDbDb data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 1500 10 - 4G NDB 7.2.0 milliseconds 5000 10 - 4G *Restart Type:* N 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. After missing three heartbeat intervals in a row, the node is declared dead. Thus, the maximum time for discovering a failure through the heartbeat mechanism is four times the heartbeat interval. In MySQL Cluster NDB 7.2.0 and later, the default heartbeat interval is 5000 milliseconds (5 seconds). Previously, the default was 1500 milliseconds (1.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 *Note mysql-cluster-network-latency-issues::. * `HeartbeatIntervalDbApi' This table provides type and value information for the HeartbeatIntervalDbApi data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 1500 100 - 4G *Restart Type:* N 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 *Note mysql-cluster-network-latency-issues::. * `HeartbeatOrder' This table provides type and value information for the HeartbeatOrder data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.35 numeric 0 0 - 65535 NDB 7.0.16 numeric 0 0 - 65535 NDB 7.1.5 numeric 0 0 - 65535 *Restart Type:* S 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: This table helps illustrate a setup in which there are four data nodes A, B, C, and D running on two host computers, `host1' and `host2', with each data node belonging 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. Priot to MySQL Cluster NDB 6.3.35, MySQL Cluster NDB 7.0.16, and MySQL Cluster NDB 7.1.5, the order of of heartbeat transmission between data nodes was always automatically determined by `NDB'. However, beginning with these versions, 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: This table lists each node and the heartbeat order value to illustrate the previously described scenario in which `HeartbeatOrder' values are set to force a heartbeat transition order of A->B->D->C->A. Node `HeartbeatOrder' A 10 B 20 C 30 D 25 To use this parameter to change the heartbeat transmission order in a running MySQL 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' 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 Effective Version Type/Units Default Range/Values NDB 7.1.13 string 1500 0 - 4G NDB 7.2.1 string 0 0 - 4G *Restart Type:* N Enables connection checking between data nodes. A data node that fails to respond within an interval of `ConnectCheckIntervalDelay' seconds is considered suspect, and is considered dead after two such intervals. * `TimeBetweenLocalCheckpoints' This table provides type and value information for the TimeBetweenLocalCheckpoints data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 number of 4-byte 20 0 - 31 words, as a base-2 logarithm *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 2000 10 - 32000 NDB 6.2.0 milliseconds 2000 20 - 32000 *Restart Type:* N 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. * `TimeBetweenEpochs' This table provides type and value information for the TimeBetweenEpochs data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.2.5 milliseconds 100 0 - 32000 *Restart Type:* N This parameter defines the interval between synchronization epochs for MySQL 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 MySQL Cluster Replication. This parameter was introduced in MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB 6.3.2. * `TimeBetweenEpochsTimeout' This table provides type and value information for the TimeBetweenEpochsTimeout data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.22 milliseconds 4000 0 - 32000 MySQL 5.1.51 milliseconds 4000 0 - 256000 *Restart Type:* N This parameter defines a timeout for synchronization epochs for MySQL Cluster Replication. If a node fails to participate in a global checkpoint within the time determined by this parameter, the node is shut down. In MySQL Cluster NDB 7.2.0 and later, the default value is 0; in other words, the timeout is disabled. This represents a change from previous versions of MySQL Cluster, in which the default value was 4000 milliseconds (4 seconds). `TimeBetweenEpochsTimeout' is part of the implementation of `micro-GCPs', which can be used to improve the performance of MySQL Cluster Replication. This parameter was introduced in MySQL Cluster NDB 6.2.7 and MySQL Cluster NDB 6.3.4. The following changes regarding this parameter were made in MySQL Cluster NDB 7.0.21 and MySQL Cluster NDB 7.1.10: * The maximum possible value for this parameter was increased from 32000 milliseconds to 256000 milliseconds. * Setting this parameter to zero now has the effect of disabling GCP stops caused by save timeouts, commit timeouts, or both. * The current value of this parameter and a warning are now written to the cluster log whenever a GCP save takes longer than 1 minute or a GCP save takes longer than 10 seconds. * `MaxBufferedEpochs' This table provides type and value information for the MaxBufferedEpochs data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.2.14 epochs 100 0 - 100000 *Restart Type:* N 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 *Note `NDB': mysql-cluster. 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 Effective Version Type/Units Default Range/Values NDB 6.3.52 bytes 26214400 26214400 (0x01900000) - 4294967039 (0xFFFFFEFF) NDB 7.0.38 bytes 26214400 26214400 (0x01900000) - 4294967039 (0xFFFFFEFF) NDB 7.1.27 bytes 26214400 26214400 (0x01900000) - 4294967039 (0xFFFFFEFF) *Restart Type:* N The total number of bytes allocated for buffering epochs by this node. This parameter was introduced in MySQL Cluster NDB 6.3.52, MySQL Cluster NDB 7.0.38, and MySQL Cluster NDB 7.1.27. (Bug #16203623) * `TimeBetweenInactiveTransactionAbortCheck' This table provides type and value information for the TimeBetweenInactiveTransactionAbortCheck data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 1000 1000 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 4G 0 - 4G *Restart Type:* N 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. The unit is milliseconds. * `TransactionDeadlockDetectionTimeout' This table provides type and value information for the TransactionDeadlockDetectionTimeout data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 1200 50 - 4G *Restart Type:* N When a node executes a query involving a transaction, the node waits for the other nodes in the cluster to respond before continuing. 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. In MySQL 5.1.10 and earlier versions, setting it too high could cause undesirable behavior in situations involving deadlocks and node failure. Beginning with MySQL 5.1.11, active transactions occurring during node failures are actively aborted by the MySQL Cluster Transaction Coordinator, and so high settings are no longer an issue with this parameter. The default timeout value is 1200 milliseconds (1.2 seconds). Prior to MySQL Cluster NDB versions 6.2.18, 6.3.24, and 7.0.5, the effective minimum for this parameter was 100 milliseconds. (Bug #44099) Beginning with these versions, the actual minimum is 50 milliseconds. * `DiskSyncSize' This table provides type and value information for the DiskSyncSize data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.12 bytes 4M 32K - 4G *Restart Type:* N 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). This parameter was added in MySQL 5.1.12. * `DiskCheckpointSpeed' This table provides type and value information for the DiskCheckpointSpeed data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.12 bytes 10M 1M - 4G *Restart Type:* N The amount of data,in bytes per second, that is sent to disk during a local checkpoint. This allocation is shared by DML operations and backups (but not backup logging), which means that backups started during times of intensive DML may be impaired by flooding of the redo log buffer and may fail altogether if the contention is sufficiently severe. The default value is 10M (10 megabytes per second). This parameter was added in MySQL 5.1.12. * `DiskCheckpointSpeedInRestart' This table provides type and value information for the DiskCheckpointSpeedInRestart data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 100M 1M - 4G *Restart Type:* N The amount of data,in bytes per second, that is sent to disk during a local checkpoint as part of a restart operation. The default value is 100M (100 megabytes per second). This parameter was added in MySQL 5.1.12. * `NoOfDiskPagesToDiskAfterRestartTUP' This table provides type and value information for the NoOfDiskPagesToDiskAfterRestartTUP data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 8K pages/100 40 1 - 4G milliseconds *Restart Type:* N When executing a local checkpoint, the algorithm flushes all data pages to disk. Merely doing so as quickly as possible without any moderation is likely to impose excessive loads on processors, networks, and disks. To control the write speed, this parameter specifies how many pages per 100 milliseconds are to be written. In this context, a `page' is defined as 8KB. This parameter is specified in units of 80KB per second, so setting `NoOfDiskPagesToDiskAfterRestartTUP' to a value of `20' entails writing 1.6MB in data pages to disk each second during a local checkpoint. This value includes the writing of UNDO log records for data pages. That is, this parameter handles the limitation of writes from data memory. (See the entry for `IndexMemory' for information about index pages.) In short, this parameter specifies how quickly to execute local checkpoints. It operates in conjunction with `NoOfFragmentLogFiles', `DataMemory', and `IndexMemory'. For more information about the interaction between these parameters and possible strategies for choosing appropriate values for them, see *Note mysql-cluster-config-lcp-params::. The default value is 40 (3.2MB of data pages per second). *Note*: This parameter is deprecated as of MySQL 5.1.6. For MySQL 5.1.12 and later versions, use `DiskCheckpointSpeed' and `DiskSyncSize' instead. * `NoOfDiskPagesToDiskAfterRestartACC' This table provides type and value information for the NoOfDiskPagesToDiskAfterRestartACC data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 8K pages/100 20 1 - 4G milliseconds *Restart Type:* N This parameter uses the same units as `NoOfDiskPagesToDiskAfterRestartTUP' and acts in a similar fashion, but limits the speed of writing index pages from index memory. The default value of this parameter is 20 (1.6MB of index memory pages per second). *Note*: This parameter is deprecated as of MySQL 5.1.6. For MySQL 5.1.12 and later versions, use `DiskCheckpointSpeed' and `DiskSyncSize'. * `NoOfDiskPagesToDiskDuringRestartTUP' (DEPRECATED) This table provides type and value information for the NoOfDiskPagesToDiskDuringRestartTUP data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 8K pages/100 40 1 - 4G milliseconds *Restart Type:* N This parameter is used in a fashion similar to `NoOfDiskPagesToDiskAfterRestartTUP' and `NoOfDiskPagesToDiskAfterRestartACC', only it does so with regard to local checkpoints executed in the node when a node is restarting. A local checkpoint is always performed as part of all node restarts. During a node restart it is possible to write to disk at a higher speed than at other times, because fewer activities are being performed in the node. This parameter covers pages written from data memory. The default value is 40 (3.2MB per second). *Note*: This parameter is deprecated as of MySQL 5.1.6. For MySQL 5.1.12 and later versions, use `DiskCheckpointSpeedInRestart' and `DiskSyncSize'. * `NoOfDiskPagesToDiskDuringRestartACC' (DEPRECATED) This table provides type and value information for the NoOfDiskPagesToDiskDuringRestartACC data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 8K pages/100 20 1 - 4G milliseconds *Restart Type:* N Controls the number of index memory pages that can be written to disk during the local checkpoint phase of a node restart. As with `NoOfDiskPagesToDiskAfterRestartTUP' and `NoOfDiskPagesToDiskAfterRestartACC', values for this parameter are expressed in terms of 8KB pages written per 100 milliseconds (80KB/second). The default value is 20 (1.6MB per second). *Note*: This parameter is deprecated as of MySQL 5.1.6. For MySQL 5.1.12 and later versions, use `DiskCheckpointSpeedInRestart' and `DiskSyncSize'. * `ArbitrationTimeout' This table provides type and value information for the ArbitrationTimeout data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 3000 10 - 4G NDB 7.2.0 milliseconds 7500 10 - 4G *Restart Type:* N 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. In MySQL Cluster NDB 7.2.0 and later, the default value is 7500 milliseconds (7.5 seconds). Previously, this was 3000 milliseconds (3 seconds). * `Arbitration' This table provides type and value information for the Arbitration data node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.0.7 enumeration Default Default, Disabled, WaitExternal *Restart Type:* N The `Arbitration' parameter, added in MySQL Cluster NDB 7.0.7, 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' Previously, it was possible to disable arbitration only by setting `ArbitrationRank' to 0 on all management and API nodes. Now, you can now use `Arbitration = Disabled' in the `[ndbd default]' section of the `config.ini' file to accomplish this task. In this case, 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. 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 *Note `NDB': mysql-cluster. storage engine's file system abstraction layer. * `UndoIndexBuffer' This table provides type and value information for the UndoIndexBuffer data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned 2M 1M - 4G *Restart Type:* N The UNDO index buffer, whose size is set by this parameter, is used during local checkpoints. The *Note `NDB': mysql-cluster. 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned 16M 1M - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 8M 1M - 4G NDB 7.0.4 bytes 32M 1M - 4G *Restart Type:* N 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. In MySQL Cluster NDB 6.4.3 and earlier, the default value is 8MB; beginning with MySQL Cluster NDB 7.0.4, the default is 32MB. The minimum value is 1MB. If this buffer is too small, the *Note `NDB': mysql-cluster. 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. 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 1 0 - 15 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 0 0 - 15 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 0 0 - 15 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 log level 0 0 - 15 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 0 0 - 15 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 0 0 - 15 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 0 0 - 15 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 levelr 0 0 - 15 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 integer 0 0 - 15 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values NDB 6.1.0 unsigned 0 0 - 4G MySQL 5.1.16 unsigned 0 0 - 4G *Restart Type:* N 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 *Note mysql-cluster-log-events::. This parameter was added in MySQL Cluster 5.1.16 and MySQL Cluster NDB 6.1.0. * `StartupStatusReportFrequency' This table provides type and value information for the StartupStatusReportFrequency data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.4.0 seconds [none] ... *Restart Type:* N When a data node is started with the `--initial', it initializes the redo log file during Start Phase 4 (see *Note mysql-cluster-start-phases::). When very large values are set for `NoOfFragmentLogFiles', `FragmentLogFileSize', or both, this initialization can take a long time. Previous to MySQL Cluster NDB 6.4.0, only the beginning and end of the redo log file initialization process were logged. Beginning with this version, it is possible to 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. Debugging Parameters Beginning with MySQL Cluster NDB 6.3.36, MySQL Cluster NDB 7.0.17, and MySQL Cluster NDB 7.1.6, it is 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; currently, 0 (default - no logging) and 1 (logging enabled) are the only supported values. 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 2M 0 - 4G NDB 6.3.23 bytes 16M 0 - 4G NDB 7.0.4 bytes 16M 0 - 4G *Restart Type:* N 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 freed up memory so that scanning may continue. In MySQL Cluster NDB 6.4.3 and earlier, the default value is 2MB; in MySQL Cluster NDB 7.0.4 and later, it is 16MB. * `BackupLogBufferSize' This table provides type and value information for the BackupLogBufferSize data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 2M 0 - 4G NDB 6.3.23 bytes 16M 0 - 4G NDB 7.0.4 bytes 16M 0 - 4G *Restart Type:* N 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 *Note 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. In MySQL Cluster NDB 6.4.3 and earlier, the default value is 2MB; in MySQL Cluster NDB 7.0.4 and later, it is 16MB. * `BackupMemory' This table provides type and value information for the BackupMemory data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 4M 0 - 4G NDB 7.0.4 bytes 32M 0 - 4G *Restart Type:* N This parameter is simply the sum of `BackupDataBufferSize' and `BackupLogBufferSize'. In MySQL Cluster NDB 7.0.4 and later, the default value is 16MB + 16MB = 32MB. (Previously, it was 2MB + 2MB = 4MB.) *Important*: If `BackupDataBufferSize' and `BackupLogBufferSize' taken together exceed the default value for `BackupMemory', then this parameter must be set explicitly in the `config.ini' file to their sum. * `BackupReportFrequency' This table provides type and value information for the BackupReportFrequency data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.2.3 seconds 0 0 - 4G *Restart Type:* N 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 *Note mysql-cluster-logging-and-checkpointing::). `BackupReportFrequency' represents the time in seconds between backup status reports. The default value is 0. This parameter was added in MySQL Cluster NDB 6.2.3. * `BackupWriteSize' This table provides type and value information for the BackupWriteSize data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 32K 2K - 4G NDB 7.0.4 bytes 256K 2K - 4G *Restart Type:* N This parameter specifies the default size of messages written to disk by the backup log and backup data buffers. In MySQL Cluster 6.4.3 and earlier, the default value for this parameter was 32KB; beginning with MySQL Cluster NDB 7.0.4, it is 256KB. * `BackupMaxWriteSize' This table provides type and value information for the BackupMaxWriteSize data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 256K 2K - 4G MySQL 5.1.32 bytes 1M 2K - 4G NDB 7.2.1 bytes 1M 2K - 4G *Restart Type:* N This parameter specifies the maximum size of messages written to disk by the backup log and backup data buffers. In MySQL Cluster 6.4.3 and earlier, the default value for this parameter was 256KB; beginning with MySQL Cluster NDB 7.0.4, it is 1MB. *Important*: 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' * MySQL 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. They were introduced in MySQL Cluster NDB 6.3.4. *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 Effective Version Type/Units Default Range/Values NDB 6.3.4 CPU ID 64K 0 - 64K *Restart Type:* N Previous to MySQL Cluster NDB 7.0 This parameter specifies the ID of the CPU assigned to handle the *Note `NDBCLUSTER': mysql-cluster. execution thread. The value of this parameter is an integer in the range 0 to 65535 (inclusive). The default is 65535. MySQL Cluster NDB 7.0 and later (beginning with MySQL Cluster NDB 6.4.0) When used with *Note `ndbd': mysql-cluster-programs-ndbd, this parameter (now a string) specifies the ID of the CPU assigned to handle the *Note `NDBCLUSTER': mysql-cluster. execution thread. When used with *Note `ndbmtd': mysql-cluster-programs-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; beginning with in MySQL Cluster NDB 7.0.31 and MySQL Cluster NDB 7.1.20, you can obtain more finely-grained control of this type using `ThreadConfig'. `LockExecuteThreadToCPU' has no default value. Prior to MySQL Cluster NDB 7.0.18 and MySQL Cluster NDB 7.1.7, the effective maximum value recognized by this parameter as a valid CPU ID was 255; using a greater value caused thread locking to be disabled. (Bug #56185) * `LockMaintThreadsToCPU' This table provides type and value information for the LockMaintThreadsToCPU data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.4 CPU ID 64K 0 - 64K NDB 6.4.0 CPU ID [none] 0 - 64K *Restart Type:* N This parameter specifies the ID of the CPU assigned to handle *Note `NDBCLUSTER': mysql-cluster. maintenance threads. The value of this parameter is an integer in the range 0 to 65535 (inclusive). This parameter was added in MySQL Cluster NDB 6.3.4. Prior to MySQL Cluster NDB 6.4.0, the default is 65535; in MySQL Cluster NDB 7.0 and later MySQL Cluster release series, there is no default value. * `RealtimeScheduler' This table provides type and value information for the RealtimeScheduler data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.4 boolean false true, false *Restart Type:* N Setting this parameter to 1 enables real-time scheduling of *Note `ndbd': mysql-cluster-programs-ndbd. threads. This parameter is not intended or recommended for use with data nodes running *Note `ndbmtd': mysql-cluster-programs-ndbmtd, and enabling it in such cases is known to have adverse effects. The default is 0 (scheduling disabled). * `SchedulerExecutionTimer' This table provides type and value information for the SchedulerExecutionTimer data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.4 µsec 50 0 - 11000 *Restart Type:* N 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. This parameter was added in MySQL Cluster NDB 6.3.4. * `SchedulerSpinTimer' This table provides type and value information for the SchedulerSpinTimer data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.4 µsec 0 0 - 500 *Restart Type:* N 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 Effective Version Type/Units Default Range/Values NDB 6.3.30 numeric 0 0 - 128 NDB 7.0.11 numeric 0 0 - 128 *Restart Type:* S This parameter determines the number of threads to create when rebuilding indexes during a system or node start. It is supported only when there is more than one fragment for the table per data node (for example, when the `MAX_ROWS' option has been used with *Note `CREATE TABLE': create-table.). Setting this parameter to 0 (which is also the default value) disables multi-threaded building of ordered indexes. The maximum allowed value is 128. This parameter was added in MySQL Cluster NDB 6.3.30 and MySQL Cluster NDB 7.0.11. Prior to MySQL Cluster NDB 7.0.16 and MySQL Cluster NDB 7.1.5, it was supported only when using *Note `ndbd': mysql-cluster-programs-ndbd.; in these and later MySQL Cluster releases, `BuildIndexThreads' is also supported for data nodes running *Note `ndbmtd': mysql-cluster-programs-ndbmtd. (see Bug #54521). Prior to MySQL Cluster NDB 7.1.11, multi-threaded building of ordered indexes was not supported during node initial restarts. Starting with MySQL Cluster NDB 7.1.11, 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 Effective Version Type/Units Default Range/Values NDB 7.1.11 boolean false true, false *Restart Type:* N In MySQL Cluster NDB 7.1.11 and later, 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. You must also set `BuildIndexThreads' to a nonzero value. * `Numa' This table provides type and value information for the Numa data node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.0.20 boolean 1 ... NDB 7.1.9 boolean 1 ... *Restart Type:* N *Note `NDB': mysql-cluster. is extremely sensitive to Non-Uniform Memory Access settings and multi-CPU systems due to timeouts that it can cause. Due to this fact, and because most MySQL Cluster users do not employ `numactl', support for NUMA is ignored by default by *Note `ndbd': mysql-cluster-programs-ndbd. when running on a Linux system. If your Linux system provides NUMA support and you wish for data node memory to be subject to NUMA control, you can set this parameter equal to 0. The `Numa' configuration parameter is supported only on Linux systems where `libnuma.so' is installed. Multi-Threading Configuration Parameters (`ndbmtd') *Note `ndbmtd': mysql-cluster-programs-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. In MySQL Cluster NDB 7.1.17 and later, a second method is also supported, whereby it is possible to set up more complex rules for *Note `ndbmtd': mysql-cluster-programs-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 Effective Version Type/Units Default Range/Values NDB 6.4.0 integer [none] 2 - 8 NDB 7.0.4 integer 2 2 - 8 *Restart Type:* N This parameter controls the number of execution threads used by *Note `ndbmtd': mysql-cluster-programs-ndbmtd, up to a maximum of 8 threads, 4 of which can be LDM (LQH) threads. Although this parameter is set in the `[ndbd]' or `[ndbd default]' sections of the `config.ini' file, it is exclusive to *Note `ndbmtd': mysql-cluster-programs-ndbmtd. and does not apply to *Note `ndbd': mysql-cluster-programs-ndbd. Setting `MaxNoOfExecutionThreads' sets the number of threads by type as determined in the following table: This table shows `MaxNoOfExecutionThreads' values and the corresponding number of threads by thread type (LQH, TC, Send, Receive). `MaxNoOfExecutionThreads' Value LQH TC Send Receive Threads Threads Threads Threads 0 .. 3 1 1 0 1 4 .. 6 2 1 0 1 7 .. 8 4 1 0 1 There is always one SUMA (replication) thread. 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 *Note `NDB': mysql-cluster. 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 least 4 threads, listed here: * 1 local query handler (LQH) thread * 1 transaction coordinator (TC) thread * 1 receive thread * 1 subscription manager (SUMA or replication) thread In MySQL Cluster NDB 7.1 and earlier, it is not possible to cause *Note `ndbmtd': mysql-cluster-programs-ndbmtd. to use more than 1 TC thread. (This is possible in MySQL Cluster NDB 7.2.) * `ThreadConfig' This table provides type and value information for the ThreadConfig multi-threaded data node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.1.17 string " ... NDB 7.2.3 string " ... *Restart Type:* N This parameter is used with *Note `ndbmtd': mysql-cluster-programs-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 | rep | io PARAM := count=NUMBER | cpubind=CPU_LIST The curly braces (`{'...`}') surrounding the list of parameters is required, even if there is only one parameter in the list. A PARAM (parameter) specifies the number of threads of the given type (`count'), the CPUs to which the threads of the given type are to be bound (`cpubind'), or both. The TYPE attribute represents an NDB thread type. The thread types supported in MySQL Cluster NDB 7.1 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. In MySQL Cluster NDB 7.1, the maximum is 4 such threads. Range: 1 - 4. * `tc': Transaction coordinator thread (`DBTC' kernel block) containing the state of an ongoing transaction. In MySQL Cluster NDB 7.1, there can be only 1 TC thread. (In MySQL Cluster NDB 7.2, this number is configurable.) Range: 1 only. * `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 a MySQL Cluster, with one socket per node. Previously, this was limited to a single thread, but MySQL Cluster 7.2 implements multiple receive threads (up to 8). Range: 1 only. * `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. 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 CPUs for operating system and other tasks. Thus, for a host machine with 8 CPUs, you might want to use 8 CPU threads bound to 7 CPUs (leaving one for operating system and other functions), with 4 LDM threads, 1 TC thread, 1 receive thread, 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 8.) The following `ThreadConfig' setting performs these assignments, additionally binding all of these threads to specific CPUs: ThreadConfig=ldm{count=4,cpubind=1,2,3,4},main={cpubind=5}, \ io={cpubind=5},rep={cpubind=6},tc{cpubind=7},recv={cpubind=8} 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. 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. In MySQL Cluster NDB 7.1 and earlier, it is not possible to cause *Note `ndbmtd': mysql-cluster-programs-ndbmtd. to use more than 1 TC thread; this capability is introduced in MySQL Cluster NDB 7.2. Disk Data Configuration Parameters Configuration parameters affecting Disk Data behavior include the following: * `DiskPageBufferMemory' This table provides type and value information for the DiskPageBufferMemory data node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.6 bytes 64M 4M - 1T *Restart Type:* N 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 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). This parameter was added in MySQL 5.1.6. Beginning with MySQL Cluster NDB 7.1.9, you can query the *Note `ndbinfo.diskpagebuffer': mysql-cluster-ndbinfo-diskpagebuffer. table to help determine whether the value for this parameter should be increased to minimize unnecessary disk seeks. See *Note mysql-cluster-ndbinfo-diskpagebuffer::, for more information. * `SharedGlobalMemory' This table provides type and value information for the SharedGlobalMemory data node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.2.0 bytes 128M 0 - 64T MySQL 5.1.6 bytes 20M 0 - 64T *Restart Type:* N 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 `INITIAL_SIZE' and `UNDO_BUFFER_SIZE' options used with *Note `CREATE LOGFILE GROUP': create-logfile-group. and *Note `ALTER LOGFILE GROUP': alter-logfile-group. statements, including any default value implied for these 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. As of MySQL Cluster NDB 7.2.0, the default value is `128M'. (Previously, this was `20M'.) This parameter was added in MySQL 5.1.6. * `DiskIOThreadPool' This table provides type and value information for the DiskIOThreadPool data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.4.3 threads 8 0 - 4G NDB 7.0.7 threads 2 0 - 4G NDB 7.1.0 threads 2 0 - 4G *Restart Type:* N 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. Currently, this parameter applies to Disk Data I/O threads only, but we plan in the future to make the number of such threads configurable for in-memory data as well. 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'. This parameter was added in MySQL Cluster NDB 6.4.0. Previous to MySQL Cluster NDB 6.4.3, it was named `ThreadPool'. Previous to MySQL Cluster NDB 7.0.7, the default value was 8. Beginning with MySQL Cluster NDB 7.0.7 and MySQL Cluster NDB 7.1.0, the default is 2. * Disk Data file system parameters The parameters in the following list were added in MySQL Cluster NDB 6.2.17, 6.3.22, and 6.4.3 to make it possible to place MySQL 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 Effective Type/Units Default Range/Values Version NDB 6.3.22 filename [see text] ... NDB 6.2.17 filename [see text] ... NDB 6.4.3 filename [see text] ... *Restart Type:* IN If this parameter is specified, then MySQL 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 *Note `CREATE TABLESPACE': create-tablespace. or *Note `ALTER TABLESPACE': alter-tablespace. statement, and for undo log files by specifying a path in the `ADD UNDOFILE' clause of a *Note `CREATE LOGFILE GROUP': create-logfile-group. or *Note `ALTER LOGFILE GROUP': 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 Effective Type/Units Default Range/Values Version NDB 6.3.22 filename [see text] ... NDB 6.2.17 filename [see text] ... NDB 6.4.3 filename [see text] ... *Restart Type:* IN If this parameter is specified, then MySQL 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 *Note `CREATE TABLESPACE': create-tablespace. or *Note `ALTER TABLESPACE': 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 Effective Type/Units Default Range/Values Version NDB 6.3.22 filename [see text] ... NDB 6.2.17 filename [see text] ... NDB 6.4.3 filename [see text] ... *Restart Type:* IN If this parameter is specified, then MySQL 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 *Note `CREATE LOGFILE GROUP': create-logfile-group. or *Note `CREATE LOGFILE GROUP': create-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 *Note 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 Effective Type/Units Default Range/Values Version NDB 6.3.22 string [see text] ... NDB 6.2.17 string [see text] ... NDB 6.4.3 string [see text] ... *Restart Type:* S 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 *Note `CREATE LOGFILE GROUP': create-logfile-group. or *Note `ALTER LOGFILE GROUP': 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 taken from the global memory pool whose size is determined by the value of the `SharedGlobalMemory' data node configuration parameter; if this parameter is set too low and the values set in `InitialLogFileGroup' for the logfile group's initial size or undo buffer size are too high, the cluster may fail to create the default log file group when starting, or fail to start altogether. This parameter, if used, should always be set in the `[ndbd default]' section of the `config.ini' file. The behavior of a MySQL 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 Effective Type/Units Default Range/Values Version NDB 6.3.22 string [see text] ... NDB 6.2.17 string [see text] ... NDB 6.4.3 string [see text] ... *Restart Type:* S This parameter can be used to specify a MySQL 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 *Note `CREATE TABLESPACE': create-tablespace. or *Note `ALTER TABLESPACE': 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 a MySQL 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 UNDOFILE '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 MySQL 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, adjusting the cluster configuration as discussed here can also help: * MySQL Cluster NDB 6.2 and 6.3 When working with large amounts of data on disk under high load, the default value for `DiskPageBufferMemory' may not be large enough. In such cases, you should increase its value to include most of the memory available to the data nodes after accounting for index memory, data memory, internal buffers, and memory needed by the data node host operating system. You can use this formula as a guide: DiskPageBufferMemory = 0.8 x ( [total memory] - ([operating system memory] + [buffer memory] + DataMemory + IndexMemory) ) Once you have established that sufficient memory is reserved for `DataMemory', `IndexMemory', NDB internal buffers, and operating system overhead, it is possible (and sometimes desirable) to allocate more than the above amount of the remainder to `DiskPageBufferMemory'. * MySQL Cluster NDB 7.X 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, beginning with MySQL Cluster NDB 7.0.21 and MySQL Cluster NDB 7.1.10, it is possible to disable both types of timeouts by setting this parameter to 0. Parameters for configuring send buffer memory allocation (MySQL Cluster NDB 7.0 and later) Beginning with MySQL Cluster NDB 6.4.0, 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 following data node configuration parameters were added in MySQL Cluster NDB 6.4.0 to permit the setting of limits on this memory allocation; this change is reflected by the addition of the configuration parameters `TotalSendBufferMemory' and `OverLoadLimit', as well as a change in how the existing `SendBufferMemory' configuration parameter is used. For more information, see *Note 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. This parameter was added in MySQL Cluster NDB 7.0.31 and MySQL Cluster NDB 7.1.20. (Bug #13633845, Bug #11760629, Bug #53053) * `TotalSendBufferMemory' This parameter is available beginning with MySQL Cluster NDB 6.4.0. It is used to determine the total amount of memory to allocate on this node for shared send buffer memory among all configured transporters. Prior to MySQL Cluster NDB 7.0.31 and MySQL Cluster NDB 7.1.20, this parameter did not work correctly with *Note `ndbmtd': mysql-cluster-programs-ndbmtd. (Bug #13633845) If this parameter is set, its minimum permitted value is 256KB; the maxmimum is 4294967039. * `ReservedSendBufferMemory' This parameter is present in *Note `NDBCLUSTER': mysql-cluster. source code beginning with MySQL Cluster NDB 6.4.0. However, it is not currently enabled. As of MySQL Cluster NDB 7.0.31 and MySQL Cluster NDB 7.1.20, this parameter is deprecated, and is subject to removal in a future release of MySQL Cluster (Bug #11760629, Bug #53053). For more detailed information about the behavior and use of `TotalSendBufferMemory' and about configuring send buffer memory parameters in MySQL Cluster NDB 6.4.0 and later, see *Note mysql-cluster-config-send-buffers::. *Note*: Previous to MySQL Cluster NDB 7.0, to add new data nodes to a MySQL Cluster, it was necessary to shut down the cluster completely, update the `config.ini' file, and then restart the cluster (that is, you had to perform a system restart). All data node processes had to be started with the `--initial' option. Beginning with MySQL Cluster NDB 7.0, it is possible to add new data node groups to a running cluster online. See *Note mysql-cluster-online-add-node::, for more information. Redo log over-commit handling Beginning with MySQL Cluster NDB 7.1.10, it is possible to control 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 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 Effective Version Type/Units Default Range/Values NDB 7.1.10 numeric 3 0 - 4G *Restart Type:* N 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. This parameter was added in MySQL Cluster NDB 7.1.10. * `RedoOverCommitLimit' This table provides type and value information for the RedoOverCommitLimit data node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.1.10 seconds 20 0 - 4G *Restart Type:* N 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. This parameter was added in MySQL Cluster NDB 7.1.10. Controlling restart attempts Beginning in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.37, MySQL Cluster NDB 7.0.18, and MySQL Cluster NDB 7.1.7, it is possible to exercise more finely-grained control over restart attempts by data nodes when they fail to start using two data node configuration parameters added in these releases. `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, as described in the following list: * `StartFailRetryDelay' This table provides type and value information for the StartFailRetryDelay data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.37 unsigned 0 0 - 4G NDB 7.0.18 unsigned 0 0 - 4G NDB 7.1.7 unsigned 0 0 - 4G NDB 6.2.19 unsigned 0 0 - 4G *Restart Type:* N Beginning in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.37, MySQL Cluster NDB 7.0.18, and MySQL Cluster NDB 7.1.7, it is possible 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). *Note*: This parameter is ignored unless `StopOnError' is equal to 0. * `MaxStartFailRetries' This table provides type and value information for the MaxStartFailRetries data node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.37 unsigned 3 0 - 4G NDB 7.0.18 unsigned 3 0 - 4G NDB 7.1.7 unsigned 3 0 - 4G NDB 6.2.19 unsigned 3 0 - 4G *Restart Type:* N Beginning in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.37, MySQL Cluster NDB 7.0.18, and MySQL Cluster NDB 7.1.7, it is possible to limit the number restart attempts made by the data node in the event that it fails on startup. The default is 3 attempts. *Note*: This parameter is ignored unless `StopOnError' is equal to 0.  File: manual.info, Node: mysql-cluster-api-definition, Next: mysql-cluster-tcp-definition, Prev: mysql-cluster-ndbd-definition, Up: mysql-cluster-config-file 17.3.2.7 Defining SQL and Other API Nodes in a MySQL 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 *Note `mysqld': 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 MySQL Cluster, see *Note mysql-cluster-program-options-mysqld::; for information about MySQL server system variables relating to MySQL Cluster, see *Note mysql-cluster-system-variables::. * `Id' This table provides type and value information for the Id API node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 1 - 63 NDB 6.1.1 unsigned [none] 1 - 255 *Restart Type:* IS The `Id' is an integer value used to identify the node in all cluster internal messages. Prior to MySQL Cluster NDB 6.1.1, the permitted range of values for this parameter was 1 to 63 inclusive. Beginning with MySQL Cluster NDB 6.1.1, the permitted range 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 MySQL 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 beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.39, MySQL Cluster NDB 7.0.20, and MySQL Cluster NDB 7.1.9. Although `Id' continues to be supported for backward compatibility, it is now deprecated and generates a warning when used. * `NodeId' This table provides type and value information for the NodeId API node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 1 - 63 NDB 6.1.1 unsigned [none] 1 - 255 *Restart Type:* IS The `NodeId' is an integer value used to identify the node in all cluster internal messages. Prior to MySQL Cluster NDB 6.1.1, the permitted range of values for this parameter was 1 to 63 inclusive. Beginning with MySQL Cluster NDB 6.1.1, the permitted range 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 MySQL 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 beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.39, MySQL Cluster NDB 7.0.20, and MySQL Cluster NDB 7.1.9. Although `Id' continues to be supported for backward compatibility, it is now deprecated and generates a warning when used. * `ExecuteOnComputer' This table provides type and value information for the ExecuteOnComputer API node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 name [none] ... *Restart Type:* S This refers to the `Id' set for one of the computers (hosts) defined in a `[computer]' section of the configuration file. * `HostName' This table provides type and value information for the HostName API node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 name or IP [none] ... address *Restart Type:* S 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_. * `ArbitrationRank' This table provides type and value information for the ArbitrationRank API node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 0-2 0 0 - 2 *Restart Type:* N 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). Beginning with MySQL 5.1.16 and MySQL Cluster NDB 6.1.3, it is possible to disable arbitration completely by setting `ArbitrationRank' to 0 on all management and SQL nodes. In MySQL Cluster NDB 7.0.7 and later releases, you can also control arbitration by overriding this parameter; to do this, 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 milliseconds 0 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 32K 1024 - 1M NDB 7.2.1 bytes 16K 1024 - 1M *Restart Type:* N 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 32K. * `BatchSize' This table provides type and value information for the BatchSize API node configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 records 64 1 - 992 NDB 7.2.1 records 256 1 - 992 *Restart Type:* N This parameter is measured in number of records and is by default set to 64. The maximum size is 992. * `ExtraSendBufferMemory' This table provides type and value information for the ExtraSendBufferMemory API node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.0.39 bytes 0 0 - 32G *Restart Type:* N 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. This parameter was added in MySQL Cluster NDB 7.0.39 and MySQL Cluster NDB 7.1.28. (Bug #14555359) * `HeartbeatThreadPriority' Beginning with MySQL Cluster NDB 6.3.32, MySQL Cluster NDB 7.0.13, and MySQL Cluster NDB 7.1.2, it is possible to 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 256K 32K - 16M *Restart Type:* N 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 Effective Version Type/Units Default Range/Values NDB 6.4.0 bytes 256K 0 - 4G *Restart Type:* N This parameter is available beginning with MySQL Cluster NDB 6.4.0. It 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; the maxmimum is 4294967039. For more detailed information about the behavior and use of `TotalSendBufferMemory' and configuring send buffer memory parameters in MySQL Cluster NDB 6.4.0 and later, see *Note mysql-cluster-config-send-buffers::. * `AutoReconnect' This table provides type and value information for the AutoReconnect API node configuration parameter Effective Version Type/Units Default Range/Values NDB 6.3.26 boolean false true, false NDB 7.0.7 boolean false true, false *Restart Type:* N This parameter is available beginning with MySQL Cluster NDB 6.3.26 and MySQL Cluster NDB 7.0.7. By default, its value is `false', which forces disconnected API nodes (including MySQL Servers acting as SQL nodes) the use a new connection to the cluster rather than attempting to re-use an existing one, which 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-methods.html#ndb-ndb-cluster-connection-set-auto-reconnect), and `Ndb_cluster_connection::get_auto_reconnect()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection-methods.html#ndb-ndb-cluster-connection-get-auto-reconnect). * `DefaultOperationRedoProblemAction' This table provides type and value information for the DefaultOperationRedoProblemAction API node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.1.10 enumeration ABORT ABORT, QUEUE NDB 7.2.1 enumeration ABORT ABORT, QUEUE *Restart Type:* S This parameter was introduced in MySQL Cluster NDB 7.1.10 (along with `RedoOverCommitLimit' and `RedoOverCommitCounter') for controlling 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. Prior to MySQL Cluster NDB 7.1.26, setting this parameter did not have any effect. (Bug #15855588) * `DefaultHashMapSize' This table provides type and value information for the DefaultHashMapSize API node configuration parameter Effective Version Type/Units Default Range/Values NDB 7.0.38 LDM threads 240 0 - 3840 NDB 7.1.27 LDM threads 240 0 - 3840 *Restart Type:* N Beginning with MySQL Cluster NDB 7.0.38 and MySQL Cluster NDB 7.1.26, the size of the table hash maps used by *Note `NDB': mysql-cluster. is configurable using this parameter; previously this value was hard-coded. `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 and their effects 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 MySQL Cluster NDB 7.1 and MySQL Cluster NDB 7.0 (and earlier) releases; effectively the only value prior to versions 7.0.38 and 7.1.26 (when this parameter was introduced). `3840' Larger hash map size available beginning with MySQL Cluster NDB 7.0.38 and MySQL Cluster NDB 7.1.26 The primary intended use for this parameter is to facilitate upgrades and especially downgrades between MySQL Cluster NDB 7.1 and later MySQL Cluster versions in which the larger hash map size (3840) is the default; by setting this parameter to 240 prior to performing an upgrade, you can cause the cluster to continue using the smaller size for table hash maps, in which case the tables remain compatible with earlier versions. `DefaultHashMapSize' can be set for individual data nodes, API nodes, or both, but setting it once only, in the `[ndbd default]' section of the `config.ini' file, is the recommended practice. You can also set this parameter to 0, in which case the default value is used. After increasing this parameter, to have existing tables to take advantage of the new size, you can run *Note `ALTER TABLE ... REORGANIZE PARTITION': alter-table-partition-operations. on them, after which they can use the larger hash map size. This is in addition to performing a rolling restart, which makes the larger hash maps available to new tables, but does not enable existing tables to use them. Decreasing this parameter online after any tables have been created or modified with `DefaultHashMapSize' equal to 3840 is not currently supported. You can obtain some information from a MySQL server running as a Cluster SQL node using *Note `SHOW STATUS': 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 | 192.168.0.112 | | Ndb_config_from_port | 1186 | | Ndb_number_of_storage_nodes | 4 | +-----------------------------+---------------+ 4 rows in set (0.02 sec) For information about these Cluster system status variables, see *Note server-status-variables::. *Note*: To add new SQL or API nodes to the configuration of a running MySQL 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.  File: manual.info, Node: mysql-cluster-tcp-definition, Next: mysql-cluster-tcp-definition-direct, Prev: mysql-cluster-api-definition, Up: mysql-cluster-config-file 17.3.2.8 MySQL Cluster TCP/IP Connections ......................................... TCP/IP is the default transport mechanism for all connections between nodes in a MySQL Cluster. Normally it is not necessary to define TCP/IP connections; MySQL 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 *Note 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 MySQL 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 MySQL 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 numeric [none] ... *Restart Type:* N `NodeId2' This table provides type and value information for the NodeId2 TCP configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 numeric [none] ... *Restart Type:* N To identify a connection between two nodes it is necessary to provide their node IDs in the `[tcp]' section of the configuration file. These are the same unique `NodeId' (or `Id') values for each of these nodes as described in *Note mysql-cluster-api-definition::. * `HostName1' This table provides type and value information for the HostName1 TCP configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 name or IP [none] ... address *Restart Type:* N `HostName2' This table provides type and value information for the HostName1 TCP configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 name or IP [none] ... address *Restart Type:* N 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 hostnames or IP addresses. * `OverloadLimit' This table provides type and value information for the OverloadLimit TCP configuration parameter Effective Version Type/Units Default Range/Values NDB 6.4.0 bytes 0 0 - 4G *Restart Type:* N Beginning in MySQL Cluster NDB 6.4.0, 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 *Note mysql-cluster-config-send-buffers::, for more information. Prior to MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.16, the effective value of this parameter was limited by the size of `SendBufferMemory'; beginning with these releases, the actual value for `OverloadLimit' (up to the stated maximum of 4G) is used instead. * `SendBufferMemory' This table provides type and value information for the SendBufferMemory TCP configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned 256K 64K - 4G NDB 7.0.4 unsigned 2M 256K - 4G *Restart Type:* N 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. Prior to MySQL Cluster NDB 7.0, this parameter determines a fixed amount of memory allocated at startup for each configured TCP connection. Beginning with MySQL Cluster NDB 6.4.0, 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 MySQL Cluster NDB 7.0 and later, see *Note mysql-cluster-config-send-buffers::. In MySQL Cluster NDB 6.4.3 and earlier, the default size of the send buffer was 256 KB; in MySQL Cluster NDB 7.0.4 and later, it 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 boolean [see text] true, false *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 boolean false true, false *Restart Type:* N 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 formerly specified the port number to be used for listening for connections from other nodes. This parameter should no longer be used; use the `ServerPort' data node configuration parameter for this purpose instead. * `ReceiveBufferMemory' This table provides type and value information for the ReceiveBufferMemory TCP configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 64K 16K - 4G NDB 7.0.4 bytes 2M 16K - 4G *Restart Type:* N Specifies the size of the buffer used when receiving data from the TCP/IP socket. In MySQL Cluster NDB 6.4.3 and earlier, the default value of this parameter was 64 KB; beginning with MySQL Cluster NDB 7.0.4, 2MB is the default. 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 Effective Version Type/Units Default Range/Values NDB 6.1.1 unsigned 70080 1 - 2G *Restart Type:* N Determines the size of the receive buffer set during TCP transporter initialization. The default is recommended for most common usage cases. `TCP_RCV_BUF_SIZE' was added in MySQL Cluster NDB 6.1.1. * `TCP_SND_BUF_SIZE' This table provides type and value information for the TCP_SND_BUF_SIZE TCP configuration parameter Effective Version Type/Units Default Range/Values NDB 6.1.1 unsigned 71540 1 - 2G *Restart Type:* N Determines the size of the send buffer set during TCP transporter initialization. The default is recommended for most common usage cases. `TCP_SND_BUF_SIZE' was added in MySQL Cluster NDB 6.1.1.  File: manual.info, Node: mysql-cluster-tcp-definition-direct, Next: mysql-cluster-shm-definition, Prev: mysql-cluster-tcp-definition, Up: mysql-cluster-config-file 17.3.2.9 MySQL 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. It is important to note that 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.  File: manual.info, Node: mysql-cluster-shm-definition, Next: mysql-cluster-sci-definition, Prev: mysql-cluster-tcp-definition-direct, Up: mysql-cluster-config-file 17.3.2.10 MySQL Cluster Shared-Memory Connections ................................................. MySQL 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 MySQL 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 numeric [none] ... *Restart Type:* N `NodeId2' This table provides type and value information for the NodeId2 shared memory configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 numeric [none] ... *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 name or IP [none] ... address *Restart Type:* N `HostName2' This table provides type and value information for the HostName1 shared memory configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 name or IP [none] ... address *Restart Type:* N 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 hostnames or IP addresses. * `ShmKey' This table provides type and value information for the ShmKey shared memory configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 bytes 1M 64K - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 boolean false true, false *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 boolean true true, false *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 0 - 4G *Restart Type:* N 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 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.  File: manual.info, Node: mysql-cluster-sci-definition, Next: mysql-cluster-config-lcp-params, Prev: mysql-cluster-shm-definition, Up: mysql-cluster-config-file 17.3.2.11 SCI Transport Connections in MySQL Cluster .................................................... `[sci]' sections in the `config.ini' file explicitly define SCI (Scalable Coherent Interface) connections between cluster nodes. Using SCI transporters in MySQL Cluster is supported only when the MySQL binaries are built using `--with-ndb-sci=/YOUR/PATH/TO/SCI'. The PATH should point to a directory that contains at a minimum `lib' and `include' directories containing SISCI libraries and header files. (See *Note mysql-cluster-interconnects:: for more information about SCI.) In addition, SCI requires specialized hardware. It is strongly recommended to use SCI Transporters only for communication between *Note `ndbd': mysql-cluster-programs-ndbd. processes. Note also that using SCI Transporters means that the *Note `ndbd': mysql-cluster-programs-ndbd. processes never sleep. For this reason, SCI Transporters should be used only on machines having at least two CPUs dedicated for use by *Note `ndbd': mysql-cluster-programs-ndbd. processes. There should be at least one CPU per *Note `ndbd': mysql-cluster-programs-ndbd. process, with at least one CPU left in reserve to handle operating system activities. * `NodeId1' This table provides type and value information for the NodeId1 SCI configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 numeric [none] ... *Restart Type:* N `NodeId2' This table provides type and value information for the NodeId2 SCI configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 numeric [none] ... *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned 0 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned [none] 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned 0 0 - 4G *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 name or IP [none] ... address *Restart Type:* N `HostName2' This table provides type and value information for the HostName1 SCI configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 name or IP [none] ... address *Restart Type:* N 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 hostnames or IP addresses. * `SharedBufferSize' This table provides type and value information for the SharedBufferSize SCI configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned 10M 64K - 4G *Restart Type:* N 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 *Note `ndbd': mysql-cluster-programs-ndbd. process. * `SendLimit' This table provides type and value information for the SendLimit SCI configuration parameter Effective Version Type/Units Default Range/Values MySQL 5.1.0 unsigned 8K 128 - 32K *Restart Type:* N 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 Effective Version Type/Units Default Range/Values NDB 6.3.23 boolean true true, false *Restart Type:* N 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 Effective Version Type/Units Default Range/Values MySQL 5.1.0 boolean false true, false *Restart Type:* N 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 Effective Version Type/Units Default Range/Values NDB 6.4.0 bytes 0 0 - 4G *Restart Type:* N When more than this many unsent bytes are in the send buffer, the connection is considered overloaded. See *Note mysql-cluster-config-send-buffers::, for more information.  File: manual.info, Node: mysql-cluster-config-lcp-params, Next: mysql-cluster-config-send-buffers, Prev: mysql-cluster-sci-definition, Up: mysql-cluster-config-file 17.3.2.12 Configuring MySQL Cluster Parameters for Local Checkpoints .................................................................... The parameters discussed in Logging and Checkpointing and in Data Memory, Index Memory, and String Memory that are used to configure local checkpoints for a MySQL Cluster do not exist in isolation, but rather are very much interdepedent on each other. In this section, we illustrate how these parameters--including `DataMemory', `IndexMemory', `NoOfDiskPagesToDiskAfterRestartTUP', `NoOfDiskPagesToDiskAfterRestartACC', and `NoOfFragmentLogFiles'--relate to one another in a working Cluster. *Important*: The parameters `NoOfDiskPagesToDiskAfterRestartTUP' and `NoOfDiskPagesToDiskAfterRestartACC' were deprecated in MySQL 5.1.6. From MySQL 5.1.6 through 5.1.11, disk writes during LCPs took place at the maximum speed possible. Beginning with MySQL 5.1.12, the speed and throughput for LCPs are controlled using the parameters `DiskSyncSize', `DiskCheckpointSpeed', and `DiskCheckpointSpeedInRestart'. See *Note mysql-cluster-ndbd-definition::. In this example, we assume that our application performs the following numbers of types of operations per hour: * 50000 selects * 15000 inserts * 15000 updates * 15000 deletes We also make the following assumptions about the data used in the application: * We are working with a single table having 40 columns. * Each column can hold up to 32 bytes of data. * A typical *Note `UPDATE': update. run by the application affects the values of 5 columns. * No `NULL' values are inserted by the application. A good starting point is to determine the amount of time that should elapse between local checkpoints (LCPs). It is worth noting that, in the event of a system restart, it takes 40-60 percent of this interval to execute the REDO log--for example, if the time between LCPs is 5 minutes (300 seconds), then it should take 2 to 3 minutes (120 to 180 seconds) for the REDO log to be read. The maximum amount of data per node can be assumed to be the size of the `DataMemory' parameter. In this example, we assume that this is 2 GB. The `NoOfDiskPagesToDiskAfterRestartTUP' parameter represents the amount of data to be checkpointed per unit time--however, this parameter is actually expressed as the number of 8K memory pages to be checkpointed per 100 milliseconds. 2 GB per 300 seconds is approximately 6.8 MB per second, or 700 KB per 100 milliseconds, which works out to roughly 85 pages per 100 milliseconds. Similarly, we can calculate `NoOfDiskPagesToDiskAfterRestartACC' in terms of the time for local checkpoints and the amount of memory required for indexes--that is, the `IndexMemory'. Assuming that we permit 512 MB for indexes, this works out to approximately 20 8-KB pages per 100 milliseconds for this parameter. Next, we need to determine the number of REDO log files required--that is, fragment log files--the corresponding parameter being `NoOfFragmentLogFiles'. We need to make sure that there are sufficient REDO log files for keeping records for at least 3 local checkpoints (in MySQL Cluster NDB 6.3.8 and later, we need only allow for 2 local checkpoints). In a production setting, there are always uncertainties--for instance, we cannot be sure that disks always operate at top speed or with maximum throughput. For this reason, it is best to err on the side of caution, so we double our requirement and calculate a number of fragment log files which should be enough to keep records covering 6 local checkpoints (in MySQL Cluster NDB 6.3.8 and later, a number of fragment log files accommodating 4 local checkpoints should be sufficient). It is also important to remember that the disk also handles writes to the REDO log, so if you find that the amount of data being written to disk as determined by the values of `NoOfDiskPagesToDiskAfterRestartACC' and `NoOfDiskPagesToDiskAfterRestartTUP' is approaching the amount of disk bandwidth available, you may wish to increase the time between local checkpoints. Given 5 minutes (300 seconds) per local checkpoint, this means that we need to support writing log records at maximum speed for 6 * 300 = 1800 seconds (_MySQL Cluster NDB 6.3.8 and later_: 4 * 300 = 1200 seconds). The size of a REDO log record is 72 bytes plus 4 bytes per updated column value plus the maximum size of the updated column, and there is one REDO log record for each table record updated in a transaction, on each node where the data reside. Using the numbers of operations set out previously in this section, we derive the following: * 50000 select operations per hour yields 0 log records (and thus 0 bytes), since *Note `SELECT': select. statements are not recorded in the REDO log. * 15000 *Note `DELETE': delete. statements per hour is approximately 5 delete operations per second. (Since we wish to be conservative in our estimate, we round up here and in the following calculations.) No columns are updated by deletes, so these statements consume only 5 operations * 72 bytes per operation = 360 bytes per second. * 15000 *Note `UPDATE': update. statements per hour is roughly the same as 5 updates per second. Each update uses 72 bytes, plus 4 bytes per column * 5 columns updated, plus 32 bytes per column * 5 columns--this works out to 72 + 20 + 160 = 252 bytes per operation, and multiplying this by 5 operation per second yields 1260 bytes per second. * 15000 *Note `INSERT': insert. statements per hour is equivalent to 5 insert operations per second. Each insert requires REDO log space of 72 bytes, plus 4 bytes per record * 40 columns, plus 32 bytes per column * 40 columns, which is 72 + 160 + 1280 = 1512 bytes per operation. This times 5 operations per second yields 7560 bytes per second. So the total number of REDO log bytes being written per second is approximately 0 + 360 + 1260 + 7560 = 9180 bytes. Multiplied by 1800 seconds, this yields 16524000 bytes required for REDO logging, or approximately 15.75 MB. The unit used for `NoOfFragmentLogFiles' represents a set of 4 16-MB log files--that is, 64 MB. Thus, the minimum value (3) for this parameter is sufficient for the scenario envisioned in this example, since 3 times 64 = 192 MB, or about 12 times what is required; the default value of 8 (or 512 MB) is more than ample in this case.  File: manual.info, Node: mysql-cluster-config-send-buffers, Prev: mysql-cluster-config-lcp-params, Up: mysql-cluster-config-file 17.3.2.13 Configuring MySQL Cluster Send Buffer Parameters .......................................................... Formerly, the NDB kernel used a send buffer whose size was fixed at 2MB for every node in the cluster, which was allocated when the node started. Because the size of this buffer could not be changed after the cluster was started, it was necessary to make it large enough in advance to accommodate the maximum possible load on any transporter socket. However, this was an inefficient use of memory, since much of it often went unused, and could result in large amounts of resources being wasted when scaling up to many API nodes. Beginning with MySQL Cluster NDB 7.0, this problem is solved by employing 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 MySQL 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: This table lists transporter types and the maximum send buffer size (bytes). 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 MySQL Cluster NDB 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' In MySQL Cluster NDB 6.3 and earlier, this TCP configuration parameter represented the amount of memory allocated at startup for each configured TCP connection. Beginning with MySQL Cluster NDB 7.0, 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.  File: manual.info, Node: mysql-cluster-params-overview, Next: mysql-cluster-options-variables, Prev: mysql-cluster-config-file, Up: mysql-cluster-configuration 17.3.3 Overview of MySQL Cluster Configuration Parameters --------------------------------------------------------- * Menu: * mysql-cluster-params-ndbd:: MySQL Cluster Data Node Configuration Parameters * mysql-cluster-params-mgmd:: MySQL Cluster Management Node Configuration Parameters * mysql-cluster-params-api:: MySQL Cluster SQL Node and API Node Configuration Parameters * mysql-cluster-params-other:: Other MySQL Cluster Configuration Parameters The next four sections provide summary tables of MySQL Cluster configuration parameters used in the `config.ini' file to govern the cluster's functioning. Each table lists the parameters for one of the Cluster node process types (*Note `ndbd': mysql-cluster-programs-ndbd, *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd, and *Note `mysqld': mysqld.), and includes the parameter's type as well as its default, minimum, and maximum values as applicable. 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 *Note `ndbd': mysql-cluster-programs-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 *Note `NDBCLUSTER': mysql-cluster. sources as `MAX_INT_RNIL' and is equal to `0xFFFFFEFF', or `2^32 - 2^8 - 1'.  File: manual.info, Node: mysql-cluster-params-ndbd, Next: mysql-cluster-params-mgmd, Prev: mysql-cluster-params-overview, Up: mysql-cluster-params-overview 17.3.3.1 MySQL Cluster Data Node Configuration Parameters ......................................................... The summary table in this section provides information about parameters used in the `[ndbd]' or `[ndbd default]' sections of a `config.ini' file for configuring MySQL Cluster data nodes. For detailed descriptions and other additional information about each of these parameters, see *Note mysql-cluster-ndbd-definition::. Beginning with MySQL Cluster NDB 6.4.0, these parameters also apply to *Note `ndbmtd': mysql-cluster-programs-ndbmtd, which is a multi-threaded version of *Note `ndbd': mysql-cluster-programs-ndbd. For more information, see *Note mysql-cluster-programs-ndbmtd::. Restart types Changes in MySQL Cluster configuration parameters do not take effect until the cluster is restarted. The type of restart required to change a given parameter is indicated in the summary table as follows: * `N'--Node restart: The parameter can be updated using a rolling restart (see *Note mysql-cluster-rolling-restart::). * `S'--System restart: The cluster must be shut down completely, then restarted, to effect a change in this parameter. * `I'--Initial restart: Data nodes must be restarted using the `--initial' option. For more information about restart types, see *Note mysql-cluster-params-overview::. *Data Node Configuration Parameters* This table describes MySQL Cluster Data Node configuration parameters Parameter Name Type or Restart In Units Type Version ... (and later) Default Value Minimum/Maximum or Permitted Values `Arbitration' enumeration N NDB 7.0.7 Default Default, Disabled, WaitExternal `ArbitrationTimeout' milliseconds N NDB 7.2.0 7500 10 / 4G `BackupDataBufferSize' bytes N NDB 7.0.4 16M 0 / 4G `BackupDataDir' path IN all 5.1-based FileSystemPath ... `BackupLogBufferSize' bytes N NDB 7.0.4 16M 0 / 4G `BackupMaxWriteSize' bytes N 5.1.32 1M 2K / 4G `BackupMemory' bytes N NDB 7.0.4 32M 0 / 4G `BackupReportFrequency' seconds N NDB 6.2.3 0 0 / 4G `BackupWriteSize' bytes N NDB 7.0.4 256K 2K / 4G `BatchSizePerLocalScan' integer N NDB 7.2.1 256 1 / 992 `BuildIndexThreads' numeric S NDB 7.0.11 0 0 / 128 `CompressedBackup' boolean N NDB 6.3.7 false true, false `CompressedLCP' boolean N NDB 6.3.7 false true, false `ConnectCheckIntervalDelay' string N NDB 7.1.13 1500 0 / 4G `CrashOnCorruptedTuple' boolean S NDB 7.0.28, 5.1.56-ndb-7.1.17 false true, false `DataDir' path IN all 5.1-based . ... `DataMemory' bytes N all 5.1-based 80M 1M / 1024G `DefaultHashMapSize' LDM threads N NDB 7.1.27 240 0 / 3840 `DictTrace' bytes N 5.1.12 undefined 0 / 100 `DiskCheckpointSpeed' bytes N 5.1.12 10M 1M / 4G `DiskCheckpointSpeedInRestart' bytes N all 5.1-based 100M 1M / 4G `DiskIOThreadPool' threads N NDB 7.1.0 2 0 / 4G `Diskless' true|false IS all (1|0) 5.1-based false true, false `DiskPageBufferMemory' bytes N 5.1.6 64M 4M / 1T `DiskSyncSize' bytes N 5.1.12 4M 32K / 4G `ExecuteOnComputer' name S all 5.1-based [none] ... `ExtraSendBufferMemory' bytes N NDB 6.4.0 0 0 / 32G `FileSystemPath' path IN all 5.1-based DataDir ... `FileSystemPathDataFiles' filename IN NDB 6.4.3 [see text] ... `FileSystemPathDD' filename IN NDB 6.4.3 FileSystemPath ... `FileSystemPathUndoFiles' filename IN NDB 6.4.3 [see text] ... `FragmentLogFileSize' bytes IN NDB 6.1.11 16M 4M / 1G `HeartbeatIntervalDbApi' milliseconds N all 5.1-based 1500 100 / 4G `HeartbeatIntervalDbDb' milliseconds N NDB 7.2.0 5000 10 / 4G `HeartbeatOrder' numeric S NDB 7.1.5 0 0 / 65535 `HostName' name or IP S all address 5.1-based localhost ... `Id' unsigned IS all 5.1-based [none] 1 / 48 `IndexMemory' bytes N all 5.1-based 18M 1M / 1T `InitFragmentLogFiles' [see values] IN NDB 6.3.19 SPARSE SPARSE, FULL `InitialLogFileGroup' string S NDB 6.4.3 [see text] ... `InitialNoOfOpenFiles' files N 5.1.9 27 20 / 4G `InitialTablespace' string S NDB 6.4.3 [see text] ... `IOThreadPool' threads N NDB 6.4.0 8 0 / 4G `LockExecuteThreadToCPU' CPU ID N NDB 6.3.4 64K 0 / 64K `LockMaintThreadsToCPU' CPU ID N NDB 6.4.0 [none] 0 / 64K `LockPagesInMainMemory' numeric N 5.1.15 0 0 / 2 `LogLevelCheckpoint' log level N all 5.1-based 0 0 / 15 `LogLevelCongestion' levelr N all 5.1-based 0 0 / 15 `LogLevelConnection' integer N all 5.1-based 0 0 / 15 `LogLevelError' integer N all 5.1-based 0 0 / 15 `LogLevelInfo' integer N all 5.1-based 0 0 / 15 `LogLevelNodeRestart' integer N all 5.1-based 0 0 / 15 `LogLevelShutdown' integer N all 5.1-based 0 0 / 15 `LogLevelStartup' integer N all 5.1-based 1 0 / 15 `LogLevelStatistic' integer N all 5.1-based 0 0 / 15 `LongMessageBuffer' bytes N NDB 7.0.4 4M 512K / 4G `MaxAllocate' unsigned N 5.1.20 32M 1M / 1G `MaxBufferedEpochs' epochs N NDB 6.2.14 100 0 / 100000 `MaxBufferedEpochBytes' bytes N NDB 7.1.27 26214400 26214400 (0x01900000) / 4294967039 (0xFFFFFEFF) `MaxDMLOperationsPerTransaction' operations N NDB (DML) 7.1.15 4294967295 32 / 4294967295 `MaxLCPStartDelay' seconds N NDB 6.4.3 0 0 / 600 `MaxNoOfAttributes' integer N all 5.1-based 1000 32 / 4G `MaxNoOfConcurrentIndexOperations' integer N all 5.1-based 8K 0 / 4G `MaxNoOfConcurrentOperations' integer N all 5.1-based 32K 32 / 4G `MaxNoOfConcurrentScans' integer N all 5.1-based 256 2 / 500 `MaxNoOfConcurrentSubOperations' unsigned N NDB 6.3.7 256 0 / 4G `MaxNoOfConcurrentTransactions' integer S all 5.1-based 4096 32 / 4G `MaxNoOfFiredTriggers' integer N all 5.1-based 4000 0 / 4G `MaxNoOfLocalOperations' integer N all 5.1-based UNDEFINED 32 / 4G `MaxNoOfLocalScans' integer N all 5.1-based UNDEFINED 32 / 4G `MaxNoOfOpenFiles' unsigned N 5.1.16 0 20 / 4G `MaxNoOfOrderedIndexes' integer N all 5.1-based 128 0 / 4G `MaxNoOfSavedMessages' integer N all 5.1-based 25 0 / 4G `MaxNoOfSubscribers' unsigned N NDB 6.3.7 0 0 / 4G `MaxNoOfSubscriptions' unsigned N NDB 6.3.7 0 0 / 4G `MaxNoOfTables' integer N all 5.1-based 128 8 / 20320 `MaxNoOfTriggers' integer N all 5.1-based 768 0 / 4G `MaxNoOfUniqueHashIndexes' integer N all 5.1-based 64 0 / 4G `MaxParallelScansPerFragment' bytes N NDB 7.2.0 256 1 / 1G `MaxStartFailRetries' unsigned N NDB 6.2.19 3 0 / 4G `MemReportFrequency' unsigned N 5.1.16 0 0 / 4G `MinFreePct' unsigned N NDB 7.1.18 5 0 / 100 `NodeGroup' IS NDB 6.4.0 [none] 0 / 65536 `NodeId' unsigned IS all 5.1-based [none] 1 / 48 `NoOfDiskPagesToDiskAfterRestartACC' 8K N all pages/100 5.1-based milliseconds 20 1 / 4G `NoOfDiskPagesToDiskAfterRestartTUP' 8K N all pages/100 5.1-based milliseconds 40 1 / 4G `NoOfDiskPagesToDiskDuringRestartACC' 8K N all pages/100 5.1-based milliseconds 20 1 / 4G `NoOfDiskPagesToDiskDuringRestartTUP' 8K N all pages/100 5.1-based milliseconds 40 1 / 4G `NoOfFragmentLogFiles' integer IN 5.1.0 16 3 / 4G `NoOfReplicas' integer IS NDB 7.0.6 2 1 / 4 `Numa' boolean N NDB 7.1.9 1 ... `ODirect' boolean N NDB 6.3.0 false true, false `RealtimeScheduler' boolean N NDB 6.3.4 false true, false `RedoBuffer' bytes N NDB 7.0.4 32M 1M / 4G `RedoOverCommitCounter' numeric N NDB 7.1.10 3 0 / 4G `RedoOverCommitLimit' seconds N NDB 7.1.10 20 0 / 4G `ReservedSendBufferMemory' bytes N NDB 6.4.0 256K 0 / 4G `RestartOnErrorInsert' error code N all 5.1-based 2 0 / 4 `SchedulerExecutionTimer' µsec N NDB 6.3.4 50 0 / 11000 `SchedulerSpinTimer' µsec N NDB 6.3.4 0 0 / 500 `ServerPort' unsigned N all 5.1-based [none] 1 / 64K `SharedGlobalMemory' bytes N 5.1.6 20M 0 / 64T `StartFailRetryDelay' unsigned N NDB 6.2.19 0 0 / 4G `StartFailureTimeout' milliseconds N all 5.1-based 0 0 / 4G `StartNoNodeGroupTimeout' milliseconds N NDB 7.0.24 15000 0 / 4294967039 `StartPartialTimeout' milliseconds N all 5.1-based 30000 0 / 4G `StartPartitionedTimeout' milliseconds N all 5.1-based 60000 0 / 4G `StartupStatusReportFrequency' seconds N NDB 6.4.0 [none] ... `StopOnError' boolean N all 5.1-based true true, false `StringMemory' % or bytes S 5.1.6 5 0 / 4G `TcpBind_INADDR_ANY' boolean N NDB 6.2.0 false true, false `TimeBetweenEpochs' milliseconds N NDB 6.2.5 100 0 / 32000 `TimeBetweenEpochsTimeout' milliseconds N 5.1.51 4000 0 / 256000 `TimeBetweenGlobalCheckpoints' milliseconds N NDB 6.2.0 2000 20 / 32000 `TimeBetweenInactiveTransactionAbortCheck' milliseconds N all 5.1-based 1000 1000 / 4G `TimeBetweenLocalCheckpoints' number of N all 4-byte 5.1-based words, as a base-2 logarithm 20 0 / 31 `TimeBetweenWatchDogCheck' milliseconds N all 5.1-based 6000 70 / 4G `TimeBetweenWatchDogCheckInitial' milliseconds N 5.1.20 6000 70 / 4G `TotalSendBufferMemory' bytes N NDB 6.4.0 256K 0 / 4G `TransactionBufferMemory' bytes N all 5.1-based 1M 1K / 4G `TransactionDeadlockDetectionTimeout' milliseconds N all 5.1-based 1200 50 / 4G `TransactionInactiveTimeout' milliseconds N all 5.1-based 4G 0 / 4G `TwoPassInitialNodeRestartCopy' boolean N NDB 7.1.11 false true, false `UndoDataBuffer' unsigned N all 5.1-based 16M 1M / 4G `UndoIndexBuffer' unsigned N all 5.1-based 2M 1M / 4G *Multi-Threaded Data Node Configuration Parameters* This table describes MySQL Cluster Multi-Threaded Data Node configuration parameters Parameter Name Type or Restart In Units Type Version ... (and later) Default Value Minimum/Maximum or Permitted Values `MaxNoOfExecutionThreads' integer N NDB 7.0.4 2 2 / 8 `ThreadConfig' string N NDB 7.1.17 " ... *Note*: Prior to MySQL Cluster NDB 7.0, to add new data nodes to a MySQL Cluster, it is necessary to shut down the cluster completely, update the `config.ini' file, and then restart the cluster, starting all data node processes using the `--initial' option--that is, you must perform a system restart. Beginning in MySQL Cluster NDB 7.0, it is possible to add new data node groups to a running cluster online. For more information, see *Note mysql-cluster-online-add-node::.  File: manual.info, Node: mysql-cluster-params-mgmd, Next: mysql-cluster-params-api, Prev: mysql-cluster-params-ndbd, Up: mysql-cluster-params-overview 17.3.3.2 MySQL Cluster Management Node Configuration Parameters ............................................................... The summary table in this section provides information about parameters used in the `[ndb_mgmd]' or `[mgm]' sections of a `config.ini' file for configuring MySQL Cluster management nodes. For detailed descriptions and other additional information about each of these parameters, see *Note mysql-cluster-mgm-definition::. Restart types Changes in MySQL Cluster configuration parameters do not take effect until the cluster is restarted. The type of restart required to change a given parameter is indicated in the summary table as follows: * `N'--Node restart: The parameter can be updated using a rolling restart (see *Note mysql-cluster-rolling-restart::). * `S'--System restart: The cluster must be shut down completely, then restarted, to effect a change in this parameter. * `I'--Initial restart: Data nodes must be restarted using the `--initial' option. For more information about restart types, see *Note mysql-cluster-params-overview::. *Management Node Configuration Parameters* This table describes MySQL Cluster Management Node configuration parameters Parameter Name Type or Restart In Units Type Version ... (and later) Default Value Minimum/Maximum or Permitted Values `ArbitrationDelay' milliseconds N all 5.1-based 0 0 / 4G `ArbitrationRank' 0-2 N all 5.1-based 1 0 / 2 `DataDir' path N all 5.1-based . ... `ExecuteOnComputer' name S all 5.1-based [none] ... `ExtraSendBufferMemory' bytes N NDB 7.0.39 0 0 / 32G `HeartbeatThreadPriority' string S NDB 7.1.2 [none] ... `HostName' name or IP S all address 5.1-based [none] ... `Id' unsigned IS NDB 6.1.1 [none] 1 / 255 `LogDestination' {CONSOLE|SYSLOG|FILE}N all 5.1-based [see text] ... `MaxNoOfSavedEvents' unsigned N all 5.1-based 100 0 / 4G `NodeId' unsigned IS NDB 6.1.1 [none] 1 / 255 `PortNumber' unsigned N all 5.1-based 1186 0 / 64K `PortNumberStats' unsigned N all 5.1-based [none] 0 / 64K `TotalSendBufferMemory' bytes N NDB 6.4.0 256K 0 / 4G `wan' boolean N NDB 6.1.1 false true, false *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 *Note mysql-cluster-mgm-definition::, for more information. To add new management servers to a running MySQL 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 *Note mysql-cluster-limitations-multiple-nodes::.  File: manual.info, Node: mysql-cluster-params-api, Next: mysql-cluster-params-other, Prev: mysql-cluster-params-mgmd, Up: mysql-cluster-params-overview 17.3.3.3 MySQL Cluster SQL Node and API Node Configuration Parameters ..................................................................... The summary table in this section provides information about parameters used in the `[mysqld]' and `[api]' sections of a `config.ini' file for configuring MySQL Cluster SQL nodes and API nodes. For detailed descriptions and other additional information about each of these parameters, see *Note mysql-cluster-api-definition::. *Note*: For a discussion of MySQL server options for MySQL Cluster, see *Note mysql-cluster-program-options-mysqld::; for information about MySQL server system variables relating to MySQL Cluster, see *Note mysql-cluster-system-variables::. Restart types Changes in MySQL Cluster configuration parameters do not take effect until the cluster is restarted. The type of restart required to change a given parameter is indicated in the summary table as follows: * `N'--Node restart: The parameter can be updated using a rolling restart (see *Note mysql-cluster-rolling-restart::). * `S'--System restart: The cluster must be shut down completely, then restarted, to effect a change in this parameter. * `I'--Initial restart: Data nodes must be restarted using the `--initial' option. For more information about restart types, see *Note mysql-cluster-params-overview::. *SQL Node / API Node Configuration Parameters* This table describes MySQL Cluster SQL Node / API Node configuration parameters Parameter Name Type or Restart In Units Type Version ... (and later) Default Value Minimum/Maximum or Permitted Values `ArbitrationDelay' milliseconds N all 5.1-based 0 0 / 4G `ArbitrationRank' 0-2 N all 5.1-based 0 0 / 2 `AutoReconnect' boolean N NDB 7.0.7 false true, false `BatchByteSize' bytes N NDB 7.2.1 16K 1024 / 1M `BatchSize' records N NDB 7.2.1 256 1 / 992 `ConnectionMap' string N NDB 6.1.0 [none] ... `DefaultHashMapSize' LDM threads N NDB 7.1.27 240 0 / 3840 `DefaultOperationRedoProblemAction' enumeration S NDB 7.1.10 ABORT ABORT, QUEUE `ExecuteOnComputer' name S all 5.1-based [none] ... `ExtraSendBufferMemory' bytes N NDB 7.0.39 0 0 / 32G `HeartbeatThreadPriority' string S NDB 7.1.2 [none] ... `HostName' name or IP S all address 5.1-based [none] ... `Id' unsigned IS NDB 6.1.1 [none] 1 / 255 `MaxScanBatchSize' bytes N all 5.1-based 256K 32K / 16M `NodeId' unsigned IS NDB 6.1.1 [none] 1 / 255 `TotalSendBufferMemory' bytes N NDB 6.4.0 256K 0 / 4G `wan' boolean N NDB 6.1.1 false true, false *Note*: To add new SQL or API nodes to the configuration of a running MySQL 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.  File: manual.info, Node: mysql-cluster-params-other, Prev: mysql-cluster-params-api, Up: mysql-cluster-params-overview 17.3.3.4 Other MySQL Cluster Configuration Parameters ..................................................... The summary tables in this section provide information about parameters used in the `[computer]', `[tcp]', `[shm]', and `[sci]' sections of a `config.ini' file for configuring MySQL Cluster management nodes. For detailed descriptions and other additional information about individual parameters, see *Note mysql-cluster-tcp-definition::, *Note mysql-cluster-shm-definition::, or *Note mysql-cluster-sci-definition::, as appropriate. Restart types Changes in MySQL Cluster configuration parameters do not take effect until the cluster is restarted. The type of restart required to change a given parameter is indicated in the summary tables as follows: * `N'--Node restart: The parameter can be updated using a rolling restart (see *Note mysql-cluster-rolling-restart::). * `S'--System restart: The cluster must be shut down completely, then restarted, to effect a change in this parameter. * `I'--Initial restart: Data nodes must be restarted using the `--initial' option. For more information about restart types, see *Note mysql-cluster-params-overview::. *Computer Configuration Parameters* This table describes MySQL Cluster Computer configuration parameters Parameter Name Type or Restart In Units Type Version ... (and later) Default Value Minimum/Maximum or Permitted Values `HostName' name or IP S all address 5.1-based [none] ... `Id' string IS all 5.1-based [none] ... *TCP Configuration Parameters* This table describes MySQL Cluster TCP configuration parameters Parameter Name Type or Restart In Units Type Version ... (and later) Default Value Minimum/Maximum or Permitted Values `Checksum' boolean N all 5.1-based false true, false `Group' unsigned N all 5.1-based 55 0 / 200 `NodeId1' numeric N all 5.1-based [none] ... `NodeId2' numeric N all 5.1-based [none] ... `NodeIdServer' numeric N all 5.1-based [none] ... `OverloadLimit' bytes N NDB 6.4.0 0 0 / 4G `PortNumber' unsigned N all 5.1-based [none] 0 / 64K `Proxy' string N all 5.1-based [none] ... `ReceiveBufferMemory' bytes N NDB 7.0.4 2M 16K / 4G `SendBufferMemory' unsigned N NDB 7.0.4 2M 256K / 4G `SendSignalId' boolean N all 5.1-based [see text] true, false `TCP_MAXSEG_SIZE' unsigned N NDB 6.1.1 0 0 / 2G `TCP_RCV_BUF_SIZE' unsigned N NDB 6.1.1 70080 1 / 2G `TCP_SND_BUF_SIZE' unsigned N NDB 6.1.1 71540 1 / 2G `TcpBind_INADDR_ANY' boolean N NDB 6.2.0 false true, false *Shared Memory Configuration Parameters* This table describes MySQL Cluster Shared Memory configuration parameters Parameter Name Type or Restart In Units Type Version ... (and later) Default Value Minimum/Maximum or Permitted Values `Checksum' boolean N all 5.1-based true true, false `Group' unsigned N all 5.1-based 35 0 / 200 `NodeId1' numeric N all 5.1-based [none] ... `NodeId2' numeric N all 5.1-based [none] ... `NodeIdServer' numeric N all 5.1-based [none] ... `OverloadLimit' bytes N NDB 6.4.0 0 0 / 4G `PortNumber' unsigned N all 5.1-based [none] 0 / 64K `SendSignalId' boolean N all 5.1-based false true, false `ShmKey' unsigned N all 5.1-based [none] 0 / 4G `ShmSize' bytes N all 5.1-based 1M 64K / 4G `Signum' unsigned N all 5.1-based [none] 0 / 4G *SCI Configuration Parameters* This table describes MySQL Cluster SCI configuration parameters Parameter Name Type or Restart In Units Type Version ... (and later) Default Value Minimum/Maximum or Permitted Values `Checksum' boolean N all 5.1-based false true, false `Group' unsigned N all 5.1-based 15 0 / 200 `Host1SciId0' unsigned N all 5.1-based [none] 0 / 4G `Host1SciId1' unsigned N all 5.1-based 0 0 / 4G `Host2SciId0' unsigned N all 5.1-based [none] 0 / 4G `Host2SciId1' unsigned N all 5.1-based 0 0 / 4G `NodeId1' numeric N all 5.1-based [none] ... `NodeId2' numeric N all 5.1-based [none] ... `NodeIdServer' numeric N all 5.1-based [none] ... `OverloadLimit' bytes N NDB 6.4.0 0 0 / 4G `PortNumber' unsigned N all 5.1-based [none] 0 / 64K `SendLimit' unsigned N all 5.1-based 8K 128 / 32K `SendSignalId' boolean N NDB 6.3.23 true true, false `SharedBufferSize' unsigned N all 5.1-based 10M 64K / 4G  File: manual.info, Node: mysql-cluster-options-variables, Next: mysql-cluster-interconnects, Prev: mysql-cluster-params-overview, Up: mysql-cluster-configuration 17.3.4 MySQL Server Options and Variables for MySQL Cluster ----------------------------------------------------------- * Menu: * mysql-cluster-option-tables:: MySQL Cluster `mysqld' Option and Variable Reference * mysql-cluster-program-options-mysqld:: MySQL Server Options for MySQL Cluster * mysql-cluster-system-variables:: MySQL Cluster System Variables * mysql-cluster-status-variables:: MySQL Cluster Status Variables This section provides information about MySQL server options, server and status variables that are specific to MySQL Cluster. For general information on using these, and for other options and variables not specific to MySQL Cluster, see *Note mysqld-server::. For MySQL Cluster configuration parameters used in the cluster configuration file (usually named `config.ini'), see *Note mysql-cluster-configuration::.  File: manual.info, Node: mysql-cluster-option-tables, Next: mysql-cluster-program-options-mysqld, Prev: mysql-cluster-options-variables, Up: mysql-cluster-options-variables 17.3.4.1 MySQL 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 a MySQL Cluster. For a table showing _all_ command-line options, server and status variables available for use with *Note `mysqld': mysqld, see *Note mysqld-option-tables::. *MySQL Cluster `mysqld' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes MySQL Server options and variables relating to MySQL Cluster Option or Variable Name Command System Scope Line Variable Option File Status Dynamic Variable Notes `Handler_discover' N N Both N Y N The number of times that tables have been discovered `Ndb_api_wait_exec_complete_count_session' N N Session N Y N 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' N N Global N Y N Number of times thread has been blocked while waiting for execution of an operation to complete by this slave. `Ndb_api_wait_exec_complete_count' N N Global N Y N 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_scan_result_count_session' N N Session N Y N 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' N N Global N Y N Number of times thread has been blocked while waiting for a scan-based signal by this slave. `Ndb_api_wait_scan_result_count' N N Global N Y N Number of times thread has been blocked while waiting for a scan-based signal by this MySQL Server (SQL node). `Ndb_api_wait_meta_request_count_session' N N Session N Y N Number of times thread has been blocked waiting for a metadata-based signal in this client session. `Ndb_api_wait_meta_request_count_slave' N N Global N Y N Number of times thread has been blocked waiting for a metadata-based signal by this slave. `Ndb_api_wait_meta_request_count' N N Global N Y N Number of times thread has been blocked waiting for a metadata-based signal by this MySQL Server (SQL node). `Ndb_api_wait_nanos_count_session' N N Session N Y N 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' N N Global N Y N Total time (in nanoseconds) spent waiting for some type of signal from the data nodes by this slave. `Ndb_api_wait_nanos_count' N N Global N Y N Total time (in nanoseconds) spent waiting for some type of signal from the data nodes by this MySQL Server (SQL node). `Ndb_api_bytes_sent_count_session' N N Session N Y N Amount of data (in bytes) sent to the data nodes in this client session. `Ndb_api_bytes_sent_count_slave' N N Global N Y N Amount of data (in bytes) sent to the data nodes by this slave. `Ndb_api_bytes_sent_count' N N Global N Y N Amount of data (in bytes) sent to the data nodes by this MySQL Server (SQL node). `Ndb_api_bytes_received_count_session' N N Session N Y N Amount of data (in bytes) received from the data nodes in this client session. `Ndb_api_bytes_received_count_slave' N N Global N Y N Amount of data (in bytes) received from the data nodes by this slave. `Ndb_api_bytes_received_count' N N Global N Y N Amount of data (in bytes) received from the data nodes by this MySQL Server (SQL node). `Ndb_api_trans_start_count_session' N N Session N Y N Number of transactions started in this client session. `Ndb_api_trans_start_count_slave' N N Global N Y N Number of transactions started by this slave. `Ndb_api_trans_start_count' N N Global N Y N Number of transactions started by this MySQL Server (SQL node). `Ndb_api_trans_commit_count_session' N N Session N Y N Number of transactions committed in this client session. `Ndb_api_trans_commit_count_slave' N N Global N Y N Number of transactions committed by this slave. `Ndb_api_trans_commit_count' N N Global N Y N Number of transactions committed by this MySQL Server (SQL node). `Ndb_api_trans_abort_count_session' N N Session N Y N Number of transactions aborted in this client session. `Ndb_api_trans_abort_count_slave' N N Global N Y N Number of transactions aborted by this slave. `Ndb_api_trans_abort_count' N N Global N Y N Number of transactions aborted by this MySQL Server (SQL node). `Ndb_api_trans_close_count_session' N N Session N Y N Number of transactions aborted (may be greater than the sum of TransCommitCount and TransAbortCount) in this client session. `Ndb_api_trans_close_count_slave' N N Global N Y N Number of transactions aborted (may be greater than the sum of TransCommitCount and TransAbortCount) by this slave. `Ndb_api_trans_close_count' N N Global N Y N Number of transactions aborted (may be greater than the sum of TransCommitCount and TransAbortCount) by this MySQL Server (SQL node). `Ndb_api_pk_op_count_session' N N Session N Y N Number of operations based on or using primary keys in this client session. `Ndb_api_pk_op_count_slave' N N Global N Y N Number of operations based on or using primary keys by this slave. `Ndb_api_pk_op_count' N N Global N Y N Number of operations based on or using primary keys by this MySQL Server (SQL node). `Ndb_api_uk_op_count_session' N N Session N Y N Number of operations based on or using unique keys in this client session. `Ndb_api_uk_op_count_slave' N N Global N Y N Number of operations based on or using unique keys by this slave. `Ndb_api_uk_op_count' N N Global N Y N Number of operations based on or using unique keys by this MySQL Server (SQL node). `Ndb_api_table_scan_count_session' N N Session N Y N Number of table scans that have been started, including scans of internal tables, in this client session. `Ndb_api_table_scan_count_slave' N N Global N Y N Number of table scans that have been started, including scans of internal tables, by this slave. `Ndb_api_table_scan_count' N N Global N Y N Number of table scans that have been started, including scans of internal tables, by this MySQL Server (SQL node). `Ndb_api_range_scan_count_session' N N Session N Y N Number of range scans that have been started in this client session. `Ndb_api_range_scan_count_slave' N N Global N Y N Number of range scans that have been started by this slave. `Ndb_api_range_scan_count' N N Global N Y N Number of range scans that have been started by this MySQL Server (SQL node). `Ndb_api_pruned_scan_count_session' N N Session N Y N Number of scans that have been pruned to a single partition in this client session. `Ndb_api_pruned_scan_count_slave' N N Global N Y N Number of scans that have been pruned to a single partition by this slave. `Ndb_api_pruned_scan_count' N N Global N Y N Number of scans that have been pruned to a single partition by this MySQL Server (SQL node). `Ndb_api_scan_batch_count_session' N N Session N Y N Number of batches of rows received in this client session. `Ndb_api_scan_batch_count_slave' N N Global N Y N Number of batches of rows received by this slave. `Ndb_api_scan_batch_count' N N Global N Y N Number of batches of rows received by this MySQL Server (SQL node). `Ndb_api_read_row_count_session' N N Session N Y N Total number of rows that have been read in this client session. `Ndb_api_read_row_count_slave' N N Global N Y N Total number of rows that have been read by this slave. `Ndb_api_read_row_count' N N Global N Y N Total number of rows that have been read by this MySQL Server (SQL node). `Ndb_api_trans_local_read_row_count_session' N N Session N Y N Total number of rows that have been read in this client session. `Ndb_api_trans_local_read_row_count_slave' N N Global N Y N Total number of rows that have been read by this slave. `Ndb_api_trans_local_read_row_count' N N Global N Y N Total number of rows that have been read by this MySQL Server (SQL node). `Ndb_api_event_data_count_injector' N N Global N Y N Number of row change events received by the NDB binlog injector thread. `Ndb_api_event_data_count' N N Global N Y N Number of row change events received by this MySQL Server (SQL node). `Ndb_api_event_nondata_count_injector' N N Global N Y N Number of events received, other than row change events, by the NDB binlog injector thread. `Ndb_api_event_nondata_count' N N Global N Y N Number of events received, other than row change events, by this MySQL Server (SQL node). `Ndb_api_event_bytes_count_injector' N N Global N Y N Number of bytes of events received by the NDB binlog injector thread. `Ndb_api_event_bytes_count' N N Global N Y N Number of bytes of events received by this MySQL Server (SQL node). `Ndb_number_of_data_nodes' N N Global N Y N If the server is part of a MySQL Cluster, the value of this variable is the number of data nodes in the cluster `Ndb_conflict_fn_max' N N Global N Y N If the server is part of a MySQL 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' N N Global N Y N If the server is part of a MySQL 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_fn_epoch' N N Global N Y N Number of rows that have been found in conflict by the NDB$EPOCH() conflict detection function `Ndb_conflict_fn_epoch_trans' N N Global N Y N Number of rows that have been found in conflict by the NDB$EPOCH_TRANS() conflict detection function `Ndb_conflict_trans_row_conflict_count' N N Global N Y N Number of rows found to be in conflict by a transactional conflict function `Ndb_conflict_trans_row_reject_count' N N Global N Y N 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_conflict_trans_reject_count' N N Global N Y N Number of transactions rejected after being found in conflict by a transactional conflict function. `Ndb_conflict_trans_detect_iter_count' N N Global N Y N 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. `Ndb_conflict_trans_conflict_commit_count' N N Global N Y N The number of epoch transactions committed after requiring transactional conflict handling. `ndb_optimization_delay' N Y Global N N Y Sets the number of milliseconds to wait between processing sets of rows by OPTIMIZE TABLE on NDB tables. `ndb_table_temporary' N Y Session N N Y NDB tables are not persistent on disk: no schema files are created and the tables are not logged `ndb_table_no_logging' N Y Session N N Y 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_autoincrement_prefetch_sz' Y Y Both Y N Y NDB auto-increment prefetch size `ndb-batch-size' Y Y Global Y N N The size (in bytes) to use for NDB transaction batches `ndb-blob-read-batch-bytes' Y Y Both Y N Y Specifies the size in bytes that large BLOB reads should be batched into. 0 = no limit. `ndb-blob-write-batch-bytes' Y Y Both Y N Y Specifies the size in bytes that large BLOB writes should be batched into. 0 = no limit. `ndb_cache_check_time' Y Y Global Y N Y The number of milliseconds between checks of cluster SQL nodes made by the MySQL query cache `ndb-cluster-connection-pool' Y Y Global Y Y N The number of connections to the cluster used by MySQL `ndb_join_pushdown' N Y Global N N N Enables pushing down of joins to data nodes `Ndb_execute_count' N N Global N Y N Provides the number of round trips to the NDB kernel made by operations `Ndb_scan_count' N N Global N Y N The total number of scans executed by NDB since the cluster was last started `Ndb_pruned_scan_count' N N Global N Y N The number of scans executed by NDB since the cluster was last started where partition pruning could be used `ndb-connectstring' Y N Y N N Point to the management server that distributes the cluster configuration `ndb_extra_logging' Y Y Global Y N Y Controls logging of MySQL Cluster schema, connection, and data distribution events in the MySQL error log `ndb_force_send' Y Y Both Y N Y Forces sending of buffers to NDB immediately, without waiting for other threads `ndb_use_exact_count' N Y Both N N Y Use exact row count when planning queries `ndb-log-apply-status' Y Y Global Y N N 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_bin' Y Y Both N N Y Write updates to NDB tables in the binary log. Effective only if binary logging is enabled with -log-bin. `ndb_log_binlog_index' Y Y Global N N Y 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-orig' Y Y Global Y N N Log originating server id and epoch in mysql.ndb_binlog_index table. `ndb-log-transaction-id' Y Y Global Y N N Write NDB transaction IDs in the binary log. Requires -log-bin-v1-events=OFF. `ndb_log_transaction_id' N Y Global N N N Whether NDB transaction IDs are written into the binary log. (Read-only.) `ndb_log_updated_only' Y Y Global Y N Y Log complete rows (ON) or updates only (OFF) `ndb-log-update-as-write' Y Y Global Y N Y Toggles logging of updates on the master between updates (OFF) and writes (ON) `ndb-log-empty-epochs' Y Y Global Y N Y 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_epochs' Y Y Global Y N Y 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-transid-mysql-connection-map' Y N N N N Enable or disable the ndb_transid_mysql_connection_map plugin; that is, enable or disable the INFORMATION_SCHEMA table having that name. `Ndb_pushed_reads' N N Global N Y N Number of reads executed on the data nodes by pushed-down joins `Ndb_pushed_queries_defined' N N Global N Y N Number of joins that API nodes have attempted to push down to the data nodes `Ndb_pushed_queries_dropped' N N Global N Y N Number of joins that API nodes have tried to push down, but failed `Ndb_pushed_queries_executed' N N Global N Y N Number of joins successfully pushed down and executed on the data nodes `ndb-nodeid' Y N Global Y Y N MySQL Cluster node ID for this MySQL server `ndb-mgmd-host' Y N Y N N Set the host (and port, if desired) for connecting to the management server `ndb-wait-connected' Y Y Global Y N N 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' Y Y Global Y N N Time (in seconds) for the MySQL server to wait for NDB engine setup to complete. `ndbcluster' Y N Y N N Enable NDB Cluster (if this version of MySQL supports it) `ndbinfo_database' N Y Global N N N The name used for the NDB information database; read only. `ndbinfo_max_bytes' Y Y Both N N Y Used for debugging only. `ndbinfo_max_rows' Y Y Both N N Y Used for debugging only. `ndbinfo_show_hidden' Y Y Both N N Y Whether to show ndbinfo internal base tables in the mysql client. The default is OFF. `ndbinfo_table_prefix' Y Y Both N N Y The prefix to use for naming ndbinfo internal base tables. Defaults to 'ndb$'. `ndbinfo_version' N Y Global N N N The version of the ndbinfo engine; read only. `server-id-bits' Y Y Global Y N N 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. `transaction_allow_batching' N Y Session N N Y Allows batching of statements within a transaction. Disable AUTOCOMMIT to use. `have_ndbcluster' N Y Global N N N Whether mysqld supports NDB Cluster tables (set by -ndbcluster option) `ndb-deferred-constraints' Y Y Both Y N Y 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_deferred_constraints' Y Y Both Y N Y Specifies that constraint checks should be deferred (where these are supported). Not normally needed or used; for testing purposes only. `ndb-distribution' Y Y Both Y N Y Default distribution for new tables in NDBCLUSTER (KEYHASH or LINHASH, default is KEYHASH) `ndb_distribution' Y Y Both Y N Y Default distribution for new tables in NDBCLUSTER (KEYHASH or LINHASH, default is KEYHASH) `ndb_index_stat_cache_entries' Y N Y N N Sets the granularity of the statistics by determining the number of starting and ending keys `ndb_index_stat_enable' Y N Y N N Use NDB index statistics in query optimization `ndb_index_stat_update_freq' Y N Y N N How often to query data nodes instead of the statistics cache `ndb_optimized_node_selection' Y N Y N N Determines how an SQL node chooses a cluster data node to use as transaction coordinator `ndb_report_thresh_binlog_epoch_slip' Y N Y N N This is a threshold on the number of epochs to be behind before reporting binlog status `ndb_report_thresh_binlog_mem_usage' Y N Y N N This is a threshold on the percentage of free memory remaining before reporting binlog status `ndb_use_transactions' Y Y Both Y N Y Forces NDB to use a count of records during SELECT COUNT(*) query planning to speed up this type of query `Ndb_cluster_node_id' N N Both N Y N If the server is acting as a MySQL Cluster node, then the value of this variable its node ID in the cluster `Ndb_config_from_host' N N Both N Y N The host name or IP address of the Cluster management server. Formerly Ndb_connected_host `Ndb_config_from_port' N N Both N Y N The port for connecting to the Cluster management server. Formerly Ndb_connected_port `Com_show_ndb_status' N N Both N Y N Count of SHOW NDB STATUS statements  File: manual.info, Node: mysql-cluster-program-options-mysqld, Next: mysql-cluster-system-variables, Prev: mysql-cluster-option-tables, Up: mysql-cluster-options-variables 17.3.4.2 MySQL Server Options for MySQL Cluster ............................................... This section provides descriptions of *Note `mysqld': mysqld. server options relating to MySQL Cluster. For information about *Note `mysqld': mysqld. options not specific to MySQL Cluster, and for general information about the use of options with *Note `mysqld': mysqld, see *Note server-options::. For information about command-line options used with other MySQL Cluster processes (*Note `ndbd': mysql-cluster-programs-ndbd, *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd, and *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm.), see *Note mysql-cluster-program-options-common::. For information about command-line options used with *Note `NDB': mysql-cluster. utility programs (such as *Note `ndb_desc': mysql-cluster-programs-ndb-desc, *Note `ndb_size.pl': mysql-cluster-programs-ndb-size-pl, and *Note `ndb_show_tables': mysql-cluster-programs-ndb-show-tables.), see *Note mysql-cluster-programs::. * `--ndb-batch-size=#' Options for ndb-batch-size *Introduced* 5.1.23-ndb-6.3.8 *Command-Line `--ndb-batch-size' Format* *Option-File Format* `ndb-batch-size' *System Variable `ndb_batch_size' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `32768' *Range* `0 .. 31536000' This sets the size in bytes that is used for NDB transaction batches. * `--ndb-cluster-connection-pool=#' Options for ndb-cluster-connection-pool *Introduced* 5.1.19-ndb-6.2.2 *Command-Line `--ndb-cluster-connection-pool' Format* *Option-File Format* `ndb-cluster-connection-pool' *Status Variable `Ndb_cluster_connection_pool' Name* *Variable Scope* Global *Dynamic Variable* No *System Variable `ndb_cluster_connection_pool' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `1' *Range* `1 .. 63' By setting this option to a value greater than 1 (the default), a *Note `mysqld': 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 *Note `mysqld': 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 *Note `mysqld': 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 *Note `mysqld': 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. This option was introduced in MySQL Cluster NDB 6.2.2. Beginning with MySQL Cluster NDB 6.2.16 and MySQL Cluster NDB 6.3.13, the value used for this option is available as a system variable (Bug #35573). Prior to MySQL Cluster NDB 7.0.23 and MySQL Cluster NDB 7.1.12, there was also a status variable corresponding to this option; however, the status variable was removed as redundant as of these versions. (Bug #60119) * `--ndb-blob-read-batch-bytes=BYTES' Options for ndb-blob-read-batch-bytes *Introduced* 5.1.51-ndb-7.0.21, 5.1.51-ndb-7.1.10 *Command-Line `--ndb-blob-read-batch-bytes' Format* *Option-File Format* `ndb-blob-read-batch-bytes' *System Variable `ndb_blob_read_batch_bytes' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `65535' *Range* `0 .. 4294967295' This option can be used to set the size (in bytes) for batching of *Note `BLOB': blob. data reads in MySQL Cluster applications. When this batch size is exceeded by the amount of *Note `BLOB': blob. data to be read within the current transaction, any pending *Note `BLOB': blob. read operations are immediately executed. The maximum value for this option is 4294967295; the default is 65535. Setting it to 0 has the effect of disabling *Note `BLOB': blob. read batching. *Note*: In NDB API applications, you can control *Note `BLOB': blob. write batching with the `setMaxPendingBlobReadBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-setmaxpendingblobreadbytes) and `getMaxPendingBlobReadBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-getmaxpendingblobreadbytes) methods. This option was introduced in MySQL Cluster NDB 7.0.21 and MySQL Cluster NDB 7.1.10. * `--ndb-blob-write-batch-bytes=BYTES' Options for ndb-blob-write-batch-bytes *Introduced* 5.1.51-ndb-7.0.21, 5.1.51-ndb-7.1.10 *Command-Line `--ndb-blob-write-batch-bytes' Format* *Option-File Format* `ndb-blob-write-batch-bytes' *System Variable `ndb_blob_write_batch_bytes' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `65535' *Range* `0 .. 4294967295' This option can be used to set the size (in bytes) for batching of *Note `BLOB': blob. data writes in MySQL Cluster applications. When this batch size is exceeded by the amount of *Note `BLOB': blob. data to be written within the current transaction, any pending *Note `BLOB': blob. write operations are immediately executed. The maximum value for this option is 4294967295; the default is 65535. Setting it to 0 has the effect of disabling *Note `BLOB': blob. write batching. *Note*: In NDB API applications, you can control *Note `BLOB': blob. write batching with the `setMaxPendingBlobWriteBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-setmaxpendingblobwritebytes) and `getMaxPendingBlobWriteBytes()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-getmaxpendingblobwritebytes) methods. This option was introduced in MySQL Cluster NDB 7.0.21 and MySQL Cluster NDB 7.1.10. * `--ndb-connectstring=CONNECT_STRING' Options for ndb-connectstring *Command-Line `--ndb-connectstring' Format* *Option-File Format* `ndb-connectstring' *Permitted Values* *Type* `string' When using the *Note `NDBCLUSTER': mysql-cluster. storage engine, this option specifies the management server that distributes cluster configuration data. See *Note mysql-cluster-connection-strings::, for syntax. * `--ndb-deferred-constraints=[0|1]' Options for ndb-deferred-constraints *Introduced* 5.1.56-ndb-7.0.28, 5.1.56-ndb-7.1.14 *Command-Line `--ndb-deferred-constraints' Format* *Option-File Format* `ndb-deferred-constraints' *System Variable `ndb_deferred_constraints' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `integer' *Default* `0' *Range* `0 .. 1' 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 MySQL Cluster or MySQL Cluster Replication, and is intended primarily for use in testing. This option was added in MySQL Cluster NDB 7.0.28 and MySQL Cluster NDB 7.1.14. * `--ndb-distribution=[KEYHASH|LINHASH]' Options for ndb-distribution *Introduced* 5.1.32-ndb-7.0.4 *Command-Line `--ndb-distribution={KEYHASH|LINHASH}' Format* *Option-File Format* `ndb-distribution' *System Variable `ndb_distribution' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `KEYHASH' *Valid Values* `LINHASH' `KEYHASH' Controls the default distribution method for *Note `NDB': mysql-cluster. tables. Can be set to either of `KEYHASH' (key hashing) or `LINHASH' (linear hashing). `KEYHASH' is the default. * `--ndb-mgmd-host=HOST[:PORT]' Options for ndb-mgmd-host *Command-Line `--ndb-mgmd-host=host[:port]' Format* *Option-File Format* `ndb-mgmd-host' *Permitted Values* *Type* `string' *Default* `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. * `--ndbcluster' Options for ndbcluster *Command-Line `--ndbcluster' Format* *Option-File Format* `ndbcluster' *Disabled by* `skip-ndbcluster' *Permitted Values* *Type* `boolean' *Default* `FALSE' The *Note `NDBCLUSTER': mysql-cluster. storage engine is necessary for using MySQL Cluster. If a *Note `mysqld': mysqld. binary includes support for the *Note `NDBCLUSTER': mysql-cluster. storage engine, the engine is disabled by default. Use the `--ndbcluster' option to enable it. Use `--skip-ndbcluster' to explicitly disable the engine. * `--ndb-log-apply-status' Options for ndb-log-apply-status *Introduced* 5.1.51-ndb-7.0.21, 5.1.51-ndb-7.1.10 *Command-Line `--ndb-log-apply-status' Format* *Option-File Format* `ndb-log-apply-status' *System Variable `ndb_log_apply_status' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `OFF' Causes a slave *Note `mysqld': 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 *Note `mysqld': 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 MySQL 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 was added in MySQL Cluster NDB 7.0.21 and MySQL Cluster NDB 7.1.10. It has no effect unless the MySQL server is started with the `--ndbcluster' option. * `--ndb-log-orig' Options for ndb-log-orig *Introduced* 5.1.22-ndb-6.3.2 *Command-Line `--ndb-log-orig' Format* *Option-File Format* `ndb-log-orig' *System Variable `ndb_log_orig' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `OFF' Log the originating server ID and epoch in the `ndb_binlog_index' table. Note that 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 *Note mysql-cluster-replication-schema::. * `--ndb-log-transaction-id' Options for ndb-log-transaction-id *Introduced* 5.1.56-ndb-7.1.16 *Command-Line `--ndb-log-transaction-id[={0|1}]' Format* *Option-File Format* `ndb-log-transaction-id' *System Variable `ndb_log_transaction_id' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `OFF' Causes a slave *Note `mysqld': 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 available beginning with MySQL Cluster NDB 7.1.16 (and is not supported in mainline MySQL Server 5.1). It is required to enable MySQL Cluster Replication conflict detection and resolution using the `NDB$EPOCH_TRANS()' function introduced in the same MySQL Cluster release. The default value is `FALSE'. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `--ndb-nodeid=#' Options for ndb-nodeid *Introduced* 5.1.15 *Command-Line `--ndb-nodeid=#' Format* *Option-File Format* `ndb-nodeid' *Status Variable `Ndb_cluster_node_id' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values (>= 5.1.5)* *Type* `numeric' *Range* `1 .. 255' Set this MySQL server's node ID in a MySQL Cluster. Prior to MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, this option can be used _instead_ of specifying the node ID as part of the connection string or in the `config.ini' file, or permitting the cluster to determine an arbitrary node ID. If you use this option, then `--ndb-nodeid' must be specified _before_ `--ndb-connectstring'. If `--ndb-nodeid' is used _and_ a node ID is specified in the connection string, then the MySQL server cannot connect to the cluster. Beginning with MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, 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 (regardless of the MySQL Cluster version), 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 *Note `SHOW STATUS': show-status, and as `cluster_node_id' in the `connection' row of the output of *Note `SHOW ENGINE NDBCLUSTER STATUS': show-engine. For more information about node IDs for MySQL Cluster SQL nodes, see *Note mysql-cluster-api-definition::. * `--ndb-log-empty-epochs=[0|1]' Options for ndb-log-empty-epochs *Introduced* 5.1.31-ndb-6.3.21, 5.1.31-ndb-6.4.1 *Command-Line `--ndb-log-empty-epochs' Format* *Option-File Format* `ndb-log-empty-epochs' *System Variable `ndb_log_empty_epochs' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' 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' (Bug #49559, Bug #11757505). Because `--ndb-log-empty-epochs=1' causes the size of `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. This option was introduced in MySQL Cluster NDB 6.3.21 and MySQL Cluster NDB 6.4.1. Prior to MySQL Cluster NDB 6.3.33, MySQL Cluster NDB 7.0.14, and MySQL Cluster NDB 7.1.3, setting `--ndb-log-empty-epochs=0' also caused no row to be written in `ndb_binlog_index' for an empty epoch. * `--server-id-bits=#' Options for server-id-bits *Introduced* 5.1.47-ndb-7.0.17, 5.1.47-ndb-7.1.6 *Command-Line `--server-id-bits=#' Format* *Option-File Format* `server-id-bits' *System Variable `server_id_bits' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `32' *Range* `7 .. 32' 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' structure (MySQL 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 *Note `mysqlbinlog': 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, *Note `mysqld': mysqld. refuses to start. This system variable was added in MySQL Cluster NDB 7.0.17 and MySQL Cluster NDB 7.1.6; it is supported only in these and later releases of MySQL Cluster. It is not supported by the standard MySQL Server. * `--skip-ndbcluster' Options for skip-ndbcluster *Command-Line `--skip-ndbcluster' Format* *Option-File Format* `skip-ndbcluster' Disable the *Note `NDBCLUSTER': mysql-cluster. storage engine. This is the default for binaries that were built with *Note `NDBCLUSTER': mysql-cluster. storage engine support; the server allocates memory and other resources for this storage engine only if the `--ndbcluster' option is given explicitly. See *Note mysql-cluster-quick::, for an example. * `ndb-transid-mysql-connection-map=STATE' Options for ndb-transid-mysql-connection-map *Introduced* 5.1.56-ndb-7.1.17 *Command-Line `--ndb-transid-mysql-connection-map[=state]'from Format* 5.1.16-ndb-7.1.17 *Permitted Values* *Type* `enumeration' *Default* `ON' *Valid Values* `OFF' `FORCE' Enables or disables the plugin that handles the *Note `ndb_transid_mysql_connection_map': ndb-transid-mysql-connection-map-table. 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 *Note `ndb_transid_mysql_connection_map': ndb-transid-mysql-connection-map-table. table plugin is running by checking the output of *Note `SHOW PLUGINS': show-plugins. This option was added in MySQL Cluster NDB 7.1.17. * `--ndb-wait-connected=SECONDS' Options for ndb-wait-connected *Introduced* 5.1.16-ndb-6.2.0 *Command-Line `--ndb-wait-connected=#' Format* *Option-File Format* `ndb-wait-connected' *System Variable `ndb_wait_connected' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 31536000' *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 31536000' *Permitted Values* *Type* `numeric' *Default* `30' *Range* `0 .. 31536000' *Permitted Values* *Type* `numeric' *Default* `30' *Range* `0 .. 31536000' This option sets the period of time that the MySQL server waits for connections to MySQL Cluster management and data nodes to be established before accepting MySQL client connections. The time is specified in seconds. Prior to MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.16, there existed a hard-coded 30-second timeout (which was removed in these versions), and the default value for this option was `0'. Starting with these releases, the default value is `30', and user-supplied values are handled correctly. (Bug #12543299) * `--ndb-wait-setup=SECONDS' Options for ndb-wait-setup *Introduced* 5.1.39-ndb-6.2.19, 5.1.39-ndb-6.3.28, 5.1.39-ndb-7.0.9 *Command-Line `--ndb-wait-setup=#' Format* *Option-File Format* `ndb-wait-setup' *System Variable `ndb_wait_setup' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `15' *Range* `0 .. 31536000' *Permitted Values* *Type* `numeric' *Default* `15' *Range* `0 .. 31536000' *Permitted Values* *Type* `numeric' *Default* `30' *Range* `0 .. 31536000' *Permitted Values* *Type* `numeric' *Default* `30' *Range* `0 .. 31536000' This variable shows the period of time that the MySQL server waits for the *Note `NDB': mysql-cluster. storage engine to complete setup before timing out and treating *Note `NDB': mysql-cluster. as unavailable. The time is specified in seconds. Prior to MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.16, the default value for this option was `15'. In these and later releases, the default value is `30'. (Bug #12543299) * `--ndb_optimization_delay=MILLISECONDS' Options for ndb_optimization_delay *Introduced* 5.1.23-ndb-6.3.7 *System Variable `ndb_optimization_delay' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `10' *Range* `0 .. 100000' Set the number of milliseconds to wait between sets of rows by *Note `OPTIMIZE TABLE': optimize-table. statements on *Note `NDB': mysql-cluster. tables. The default is 15.  File: manual.info, Node: mysql-cluster-system-variables, Next: mysql-cluster-status-variables, Prev: mysql-cluster-program-options-mysqld, Up: mysql-cluster-options-variables 17.3.4.3 MySQL Cluster System Variables ....................................... This section provides detailed information about MySQL server system variables that are specific to MySQL Cluster and the *Note `NDB': mysql-cluster. storage engine. For system variables not specific to MySQL Cluster, see *Note server-system-variables::. For general information on using system variables, see *Note using-system-variables::. * `have_ndbcluster' Options for have_ndbcluster *System Variable `have_ndbcluster' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' `YES' if *Note `mysqld': mysqld. supports *Note `NDBCLUSTER': mysql-cluster. tables. `DISABLED' if `--skip-ndbcluster' is used. This variable is deprecated and is removed in MySQL 5.6. Use *Note `SHOW ENGINES': show-engines. instead. * `multi_range_count' Options for multi_range_count *Command-Line `--multi_range_count=#' Format* *Option-File Format* `multi_range_count' *System Variable `multi_range_count' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `256' *Range* `1 .. 4294967295' The maximum number of ranges to send to a table handler at once during range selects. The default value is 256. Sending multiple ranges to a handler at once can improve the performance of certain selects dramatically. This is especially true for the *Note `NDBCLUSTER': mysql-cluster. table handler, which needs to send the range requests to all nodes. Sending a batch of those requests at once reduces communication costs significantly. This variable is deprecated in MySQL 5.1, and is no longer supported in MySQL 5.5, in which arbitrarily long lists of ranges can be processed. * `ndb_autoincrement_prefetch_sz' Options for ndb_autoincrement_prefetch_sz *Command-Line `--ndb_autoincrement_prefetch_sz' Format* *Option-File Format* `ndb_autoincrement_prefetch_sz' *Option Sets Yes, Variable* `ndb_autoincrement_prefetch_sz' *Variable Name* `ndb_autoincrement_prefetch_sz' *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values (>= 5.1.1, <= 5.1.22)* *Type* `numeric' *Default* `32' *Range* `1 .. 256' *Permitted Values (>= 5.1.23, <= 5.1.24)* *Type* `numeric' *Default* `1' *Range* `1 .. 256' *Permitted Values (>= NDB 6.2.0, <= NDB 6.2.9)* *Type* `numeric' *Default* `32' *Range* `1 .. 256' *Permitted Values (>= NDB 6.2.10)* *Type* `numeric' *Default* `32' *Range* `1 .. 256' *Permitted Values (>= NDB 6.3.0, <= 6.3.6)* *Type* `numeric' *Default* `32' *Range* `1 .. 256' *Permitted Values (>= NDB 6.3.7, <= 6.3.30)* *Type* `numeric' *Default* `1' *Range* `1 .. 256' *Permitted Values (>= NDB 6.3.31)* *Type* `numeric' *Default* `1' *Range* `1 .. 65536' *Permitted Values (>= NDB 6.4.0, <= 7.0.10)* *Type* `numeric' *Default* `32' *Range* `1 .. 256' *Permitted Values (>= NDB 7.0.11)* *Type* `numeric' *Default* `1' *Range* `1 .. 65536' *Permitted Values (>= NDB 7.1.1)* *Type* `numeric' *Default* `1' *Range* `1 .. 65536' 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 minimum value is 1. Prior to MySQL 5.1.23, MySQL Cluster NDB 6.2.9, and MySQL Cluster NDB 6.3.7, the default value was 32; in these and all later versions, the default is 1. Prior to MySQL Cluster NDB 6.3.31 and MySQL Cluster NDB 7.0.11, the maximum value was 256; in these and all later versions of MySQL Cluster (including all MySQL Cluster NDB 7.1 releases), the maximum is 65536 (Bug #50621). Beginning with MySQL Cluster NDB 6.2.10, MySQL Cluster NDB 6.3.7, and MySQL 5.1.23, this variable affects the number of `AUTO_INCREMENT' IDs that are fetched between statements only. Within a statement, at least 32 IDs are now obtained at a time. The default value for `ndb_autoincrement_prefetch_sz' is now `1', to increase the speed of statements inserting single rows. (Bug #31956) *Important*: This variable does not affect inserts performed using *Note `INSERT ... SELECT': insert-select. * `ndb_cache_check_time' Options for ndb_cache_check_time *Command-Line `--ndb_cache_check_time' Format* *Option-File Format* `ndb_cache_check_time' *System Variable `ndb_cache_check_time' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' The number of milliseconds that elapse between checks of MySQL 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. * `ndb_deferred_constraints' Options for ndb_deferred_constraints *Introduced* 5.1.56-ndb-7.0.28, 5.1.56-ndb-7.1.14 *Command-Line `--ndb-deferred-constraints' Format* *Option-File Format* `ndb_deferred_constraints' *System Variable `ndb_deferred_constraints' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `integer' *Default* `0' *Range* `0 .. 1' Controls whether or not constraint checks are deferred, where these are supported. `0' is the default. This variable was added in MySQL Cluster NDB 7.0.28 and MySQL Cluster NDB 7.1.14. This variable is not normally needed for operation of MySQL Cluster or MySQL Cluster Replication, and is intended primarily for use in testing. * `ndb_distribution' Options for ndb_distribution *Introduced* 5.1.32-ndb-7.0.4 *Command-Line `--ndb-distribution={KEYHASH|LINHASH}' Format* *Option-File Format* `ndb_distribution' *System Variable `ndb_distribution={KEYHASH|LINHASH}' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `enumeration' *Default* `KEYHASH' *Valid Values* `LINHASH' `KEYHASH' Controls the default distribution method for *Note `NDB': mysql-cluster. tables. Can be set to either of `KEYHASH' (key hashing) or `LINHASH' (linear hashing). `KEYHASH' is the default. * `ndb_extra_logging' Options for ndb_extra_logging *Introduced* 5.1.6 *Command-Line `ndb_extra_logging=#' Format* *Option-File Format* `ndb_extra_logging' *System Variable `ndb_extra_logging' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' This variable can be used to enable recording in the MySQL error log of information specific to the *Note `NDB': mysql-cluster. storage engine. It is normally of interest only when debugging *Note `NDB': mysql-cluster. storage engine code. The default value is 0, which means that the only *Note `NDB': mysql-cluster.-specific information written to the MySQL error log relates to transaction handling. If the value is greater than 0 but less than 10, *Note `NDB': mysql-cluster. table schema and connection events are also logged, as well as whether or not conflict resolution is in use, and other *Note `NDB': mysql-cluster. errors and information. If the value is set to 10 or more, information about *Note `NDB': mysql-cluster. internals, such as the progress of data distribution among cluster nodes, is also written to the MySQL error log. This variable was added in MySQL 5.1.6. * `ndb_force_send' Options for ndb_force_send *Command-Line `--ndb-force-send' Format* *Option-File Format* `ndb_force_send' *System Variable `ndb_force_send' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `TRUE' Forces sending of buffers to *Note `NDB': mysql-cluster. immediately, without waiting for other threads. Defaults to `ON'. * `ndb_index_stat_cache_entries' Options for ndb_index_stat_cache_entries *Removed* 5.1.14 *Command-Line `--ndb_index_stat_cache_entries' Format* *Option-File Format* `ndb_index_stat_cache_entries' *Permitted Values* *Type* `numeric' *Default* `32' *Range* `0 .. 4294967295' Sets the granularity of the statistics by determining the number of starting and ending keys to store in the statistics memory cache. Zero means no caching takes place; in this case, the data nodes are always queried directly. Default value: `32'. *Note*: If `ndb_index_stat_enable' is `OFF', then setting this variable has no effect. * `ndb_index_stat_enable' Options for ndb_index_stat_enable *Removed* 5.1.19 *Command-Line `--ndb_index_stat_enable' Format* *Option-File Format* `ndb_index_stat_enable' *Permitted Values* *Type* `boolean' *Default* `ON' Use *Note `NDB': mysql-cluster. index statistics in query optimization. Defaults to `ON'. * `ndb_index_stat_update_freq' Options for ndb_index_stat_update_freq *Removed* 5.1.14 *Command-Line `--ndb_index_stat_update_freq' Format* *Option-File Format* `ndb_index_stat_update_freq' *Permitted Values* *Type* `numeric' *Default* `20' *Range* `0 .. 4294967295' How often to query data nodes instead of the statistics cache. For example, a value of `20' (the default) means to direct every 20^th query to the data nodes. *Note*: If `ndb_index_stat_cache_entries' is `0', then setting this variable has no effect; in this case, every query is sent directly to the data nodes. * `ndb_join_pushdown' Options for ndb_join_pushdown *Introduced* 5.1.51-ndb-7.2.0 *System Variable `ndb_join_pushdown' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `TRUE' Added in MySQL Cluster NDB 7.2.0, this variable controls whether joins on *Note `NDB': mysql-cluster. tables are pushed down to the NDB kernel (data nodes). Previously, a join was handled using multiple accesses of *Note `NDB': mysql-cluster. 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 *Note `mysqld': 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. 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 *Note `INT': integer-types. column and a *Note `BIGINT': integer-types. column also cannot be pushed down. 2. Queries referencing *Note `BLOB': blob. or *Note `TEXT': blob. columns are not supported. 3. Explicit locking is not supported; however, the *Note `NDB': mysql-cluster. 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 *Note `EXPLAIN': 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' (all introduced in MySQL Cluster NDB 7.2.0). 2. The counters in the *Note `ndbinfo.counters': mysql-cluster-ndbinfo-counters. table that belong to the `DBSPJ' kernel block. (These counters and the `DBSPJ' block were also introduced in MySQL Cluster NDB 7.2.0). See *Note mysql-cluster-ndbinfo-counters::, for information about these counters. See also The `DBSPJ' Block (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-kernel-blocks-dbspj.html), in the `MySQL Cluster API Developer Guide'. * `ndb_log_apply_status' Options for ndb-log-apply-status *Introduced* 5.1.51-ndb-7.0.21, 5.1.51-ndb-7.1.10 *Command-Line `--ndb-log-apply-status' Format* *Option-File Format* `ndb-log-apply-status' *System Variable `ndb_log_apply_status' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `OFF' A read-only variable which shows whether the server was started with the `--ndb-log-apply-status' option. This variable was added in MySQL Cluster NDB 7.0.21 and MySQL Cluster NDB 7.1.10. * `ndb_log_bin' Options for ndb_log_bin *Introduced* 5.1.6 *Command-Line `--ndb-log-bin={1|0}' Format* *System Variable `ndb_log_bin' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `ON' 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. This variable was added in MySQL 5.1.6. * `ndb_log_binlog_index' Options for ndb_log_binlog_index *Introduced* 5.1.6 *Command-Line `--ndb-log-binlog-index={1|0}' Format* *System Variable `ndb_log_binlog_index' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `ON' 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. This variable was added in MySQL 5.1.6. * `ndb_log_orig' Options for ndb-log-orig *Introduced* 5.1.22-ndb-6.3.2 *Command-Line `--ndb-log-orig' Format* *Option-File Format* `ndb-log-orig' *System Variable `ndb_log_orig' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `OFF' Shows whether the originating server ID and epoch are logged in the `ndb_binlog_index' table. Set using the `--ndb-log-orig' server option. This variable was added in MySQL Cluster NDB 6.3.2. * `ndb_optimized_node_selection' Options for ndb_optimized_node_selection *Command-Line `--ndb-optimized-node-selection=#'from Format* 5.1.22-ndb-6.3.4 *Option-File Format* `ndb_optimized_node_selection' *Permitted Values* *Type* `boolean' *Default* `ON' *Permitted Values* *Type* `numeric' *Default* `3' *Range* `0 .. 3' Prior to MySQL Cluster NDB 6.3.4 Causes an SQL node to use the `closest' data node as transaction coordinator. Enabled by default. Set to `0' or `OFF' to disable, in which case the SQL node uses each data node in the cluster in succession. When this option is disabled each SQL thread attempts to use a given data node 8 times before proceeding to the next one. Beginning with MySQL Cluster NDB 6.3.4 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. (This is the same `round-robin' behavior as caused by setting this option to `0' or `OFF' in previous versions of MySQL Cluster.) * `1': Proximity to the SQL node is used to determine the transaction coordinator. (This is the same behavior as caused by setting this option to `1' or `ON' in previous MySQL versions.) * `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 in MySQL Cluster NDB 6.3.4 and later.) *Important*: Beginning with MySQL Cluster NDB 6.3.4, it is no longer possible to set `--ndb_optimized_node_selection' to `ON' or `OFF'; attempting to do so causes *Note `mysqld': mysqld. to abort with an error. * `ndb_report_thresh_binlog_epoch_slip' Options for ndb_report_thresh_binlog_epoch_slip *Command-Line `--ndb_report_thresh_binlog_epoch_slip' Format* *Option-File Format* `ndb_report_thresh_binlog_epoch_slip' *Permitted Values* *Type* `numeric' *Default* `3' *Range* `0 .. 256' This is a threshold on the number of epochs to be behind before reporting binary log status. For example, 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 will be sent to the cluster log. * `ndb_report_thresh_binlog_mem_usage' Options for ndb_report_thresh_binlog_mem_usage *Command-Line `--ndb_report_thresh_binlog_mem_usage' Format* *Option-File Format* `ndb_report_thresh_binlog_mem_usage' *Permitted Values* *Type* `numeric' *Default* `10' *Range* `0 .. 10' 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 will be sent to the cluster log. * `slave_allow_batching' Options for slave_allow_batching *Introduced* 5.1.19-ndb-6.2.3 *Command-Line `--slave-allow-batching' Format* *Option-File Format* `slave_allow_batching' *System Variable `slave_allow_batching' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `off' Whether or not batched updates are enabled on MySQL Cluster replication slaves. This variable is available beginning with MySQL Cluster NDB 6.2.3. Currently, it is available for *Note `mysqld': mysqld. only as supplied with MySQL Cluster or built from the MySQL Cluster sources. For more information, see *Note mysql-cluster-replication-starting::. * `ndb_table_no_logging' Options for ndb_table_no_logging *Introduced* 5.1.23-ndb-6.3.8 *System Variable `ndb_table_no_logging' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `FALSE' When this variable is set to `ON' or `1', it causes *Note `NDB': mysql-cluster. 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 *Note `NDB': mysql-cluster. 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 *Note `NDB': mysql-cluster. table schema files; to suppress these, use `ndb_table_temporary' instead. * `ndb_table_temporary' Options for ndb_table_temporary *Introduced* 5.1.23-ndb-6.3.8 *System Variable `ndb_table_temporary' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `FALSE' When set to `ON' or `1', this variable causes *Note `NDB': mysql-cluster. 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 in MySQL Cluster NDB 7.0 and later. This is a known issue; see Bug #34036. * `ndb_use_copying_alter_table' Options for ndb_use_copying_alter_table *Introduced* 5.1.12 *System Variable `ndb_use_copying_alter_table' Name* *Variable Scope* Global, Session *Dynamic Variable* No Forces *Note `NDB': mysql-cluster. to use copying of tables in the event of problems with online *Note `ALTER TABLE': alter-table. operations. The default value is `OFF'. This variable was added in MySQL 5.1.12. * `ndb_use_exact_count' Options for ndb_use_exact_count *System Variable `ndb_use_exact_count' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `ON' Forces *Note `NDB': mysql-cluster. to use a count of records during `SELECT COUNT(*)' query planning to speed up this type of query. The default value is `ON'. For faster queries overall, disable this feature by setting the value of `ndb_use_exact_count' to `OFF'. * `ndb_use_transactions' Options for ndb_use_transactions *Command-Line `--ndb_use_transactions' Format* *Option-File Format* `ndb_use_transactions' *System Variable `ndb_use_transactions' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `ON' You can disable *Note `NDB': mysql-cluster. transaction support by setting this variable's values to `OFF' (not recommended). The default is `ON'. *Note*: The setting for this variable was not honored in MySQL Cluster NDB 6.4.3 and MySQL Cluster NDB 7.0.4. (Bug #43236) * `transaction_allow_batching' Options for transaction_allow_batching *Introduced* 5.1.23-ndb-6.3.7 *System Variable `transaction_allow_batching' Name* *Variable Scope* Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `FALSE' 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 *Note `COMMIT': commit. if desired) before issuing a *Note `SELECT': 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 was added in MySQL Cluster NDB 6.3.7, and is currently supported in MySQL Cluster only. The system variables in the following list all relate to the *Note `ndbinfo': mysql-cluster-ndbinfo. information database. They were added in MySQL Cluster NDB 7.1.1. * `ndbinfo_database' Options for ndbinfo_database *Introduced* 5.1.41-ndb-7.1.1 *System Variable `ndbinfo_database' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' *Default* `ndbinfo' 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' Options for ndbinfo_max_bytes *Introduced* 5.1.41-ndb-7.1.1 *Command-Line `--ndbinfo-max-bytes=#' Format* *System Variable `ndbinfo_max_bytes' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `0' Used in testing and debugging only. * `ndbinfo_max_rows' Options for ndbinfo_max_rows *Introduced* 5.1.41-ndb-7.1.1 *Command-Line `--ndbinfo-max-rows=#' Format* *System Variable `ndbinfo_max_rows' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `numeric' *Default* `10' Used in testing and debugging only. * `ndbinfo_show_hidden' Options for ndbinfo_show_hidden *Introduced* 5.1.41-ndb-7.1.1 *Command-Line `--ndbinfo-show-hidden={0|1}' Format* *System Variable `ndbinfo_show_hidden' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' Whether or not the *Note `ndbinfo': mysql-cluster-ndbinfo. database's underlying internal tables are shown in the `mysql' client. The default is `OFF'. * `ndbinfo_table_prefix' Options for ndbinfo_table_prefix *Introduced* 5.1.41-ndb-7.1.1 *Command-Line `--ndbinfo-table-prefix=name' Format* *System Variable `ndbinfo_table_prefix' Name* *Variable Scope* Global, Session *Dynamic Variable* Yes *Permitted Values* *Type* `string' *Default* `ndb$' 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' Options for ndbinfo_version *Introduced* 5.1.41-ndb-7.1.1 *System Variable `ndbinfo_version' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `string' *Default* `' Shows the version of the *Note `ndbinfo': mysql-cluster-ndbinfo. engine in use; read-only. * `ndb_log_transaction_id' Options for ndb_log_transaction_id *Introduced* 5.1.56-ndb-7.1.16 *System Variable `ndb_log_transaction_id' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `boolean' *Default* `OFF' This read-only, Boolean system variable shows whether a slave *Note `mysqld': mysqld. writes NDB transaction IDs in the binary log (required to use `active-active' MySQL Cluster Replication with `NDB$EPOCH_TRANS()' conflict detection). To change the setting, use the `--ndb-log-transaction-id' option. `ndb_log_transaction_id' is available in MySQL Cluster NDB 7.1.16 and later. It is not supported in mainline MySQL Server 5.1. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `ndb_log_empty_epochs' Options for ndb_log_empty_epochs *Introduced* 5.1.31-ndb-6.3.21, 5.1.31-ndb-6.4.1 *Command-Line `--ndb-log-empty-epochs' Format* *Option-File Format* `ndb_log_empty_epochs' *System Variable `ndb_log_empty_epochs' Name* *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `OFF' 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' (Bug #49559, Bug #11757505). * `server_id_bits' Options for server-id-bits *Introduced* 5.1.47-ndb-7.0.17, 5.1.47-ndb-7.1.6 *Command-Line `--server-id-bits=#' Format* *Option-File Format* `server-id-bits' *System Variable `server_id_bits' Name* *Variable Scope* Global *Dynamic Variable* No *Permitted Values* *Type* `numeric' *Default* `32' *Range* `7 .. 32' 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', *Note `mysqld': mysqld. refuses to start. This system variable was added in MySQL Cluster NDB 7.0.17 and MySQL Cluster NDB 7.1.6; it is supported only in these and later releases of MySQL Cluster. `server_id_bits' is not supported by the standard MySQL Server.  File: manual.info, Node: mysql-cluster-status-variables, Prev: mysql-cluster-system-variables, Up: mysql-cluster-options-variables 17.3.4.4 MySQL Cluster Status Variables ....................................... This section provides detailed information about MySQL server status variables that relate to MySQL Cluster and the *Note `NDB': mysql-cluster. storage engine. For status variables not specific to MySQL Cluster, and for general information on using status variables, see *Note server-status-variables::. * `Handler_discover' The MySQL server can ask the *Note `NDBCLUSTER': mysql-cluster. 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_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-methods.html#ndb-ndbtransaction-execute) 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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-methods.html#ndb-ndbtransaction-execute) 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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-methods.html#ndb-ndbtransaction-execute) 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note mysql-cluster-ndb-api-statistics::. * `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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it relates to the current session only, and is not affected by any other clients of this *Note `mysqld': mysqld. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-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. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note mysql-cluster-ndb-api-statistics::. * `Ndb_api_event_nondata_count_injector' The number of events received, other than row change events, by the NDB binlog injector thread. Although this variable can be read using either *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note 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 *Note `SHOW GLOBAL STATUS': show-status. or *Note `SHOW SESSION STATUS': show-status, it is effectively global in scope. This variable was added in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. For more information, see *Note mysql-cluster-ndb-api-statistics::. * `Ndb_cluster_node_id' If the server is acting as a MySQL Cluster node, then the value of this variable its node ID in the cluster. If the server is not part of a MySQL Cluster, then the value of this variable is 0. * `Ndb_config_from_host' If the server is part of a MySQL 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 a MySQL Cluster, then the value of this variable is an empty string. Prior to MySQL 5.1.12, this variable was named `Ndb_connected_host'. * `Ndb_config_from_port' If the server is part of a MySQL 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 a MySQL Cluster, then the value of this variable is 0. Prior to MySQL 5.1.12, this variable was named `Ndb_connected_port'. * `Ndb_conflict_fn_max' Used in MySQL 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 *Note `mysqld': mysqld. was started. This variable was added in MySQL Cluster NDB 6.3.3. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `Ndb_conflict_fn_old' Used in MySQL 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 *Note `mysqld': mysqld. since the last time it was restarted. This variable was added in MySQL Cluster NDB 6.3.4. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `Ndb_conflict_fn_epoch' Used in MySQL Cluster Replication conflict resolution, this variable shows the number of rows found to be in conflict using `NDB$EPOCH()' conflict resolution on a given *Note `mysqld': mysqld. since the last time it was restarted. This variable was added in MySQL Cluster NDB 7.1.16. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `Ndb_conflict_fn_epoch_trans' Used in MySQL 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 *Note `mysqld': mysqld. since the last time it was restarted. This variable was added in MySQL Cluster NDB 7.1.16. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `Ndb_conflict_trans_row_conflict_count' Used in MySQL 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 *Note `mysqld': mysqld. since the last time it was restarted. Currently, the only transactional conflict detection function supported by MySQL Cluster is NDB$EPOCH_TRANS(), so this status variable is effectively the same as `Ndb_conflict_fn_epoch_trans'. This variable was added in MySQL Cluster NDB 7.1.16. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `Ndb_conflict_trans_row_reject_count' Used in MySQL 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. This variable was added in MySQL Cluster NDB 7.1.16. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `Ndb_conflict_trans_reject_count' Used in MySQL Cluster Replication conflict resolution, this status variable shows the number of transactions found to be in conflict by a transactional conflict detection function. This variable was added in MySQL Cluster NDB 7.1.16. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `Ndb_conflict_trans_detect_iter_count' Used in MySQL 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'. This variable was added in MySQL Cluster NDB 7.1.16. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `Ndb_conflict_trans_conflict_commit_count' Used in MySQL Cluster Replication conflict resolution, this shows the number of epoch transactions committed after they required transactional conflict handling. This variable was added in MySQL Cluster NDB 7.1.16. For more information, see *Note mysql-cluster-replication-conflict-resolution::. * `Ndb_execute_count' Provides the number of round trips to the *Note `NDB': mysql-cluster. kernel made by operations. Added in MySQL Cluster NDB 6.3.6. * `Ndb_number_of_data_nodes' If the server is part of a MySQL Cluster, the value of this variable is the number of data nodes in the cluster. If the server is not part of a MySQL Cluster, then the value of this variable is 0. Prior to MySQL 5.1.12, this variable was named `Ndb_number_of_storage_nodes'. * `Ndb_pushed_queries_defined' The total number of joins pushed down to the NDB kernel for distributed handling on the data nodes. Note that joins tested using *Note `EXPLAIN': explain. that can be pushed down contribute to this number. Added in MySQL Cluster NDB 7.2.0. * `Ndb_pushed_queries_dropped' The number of joins that were pushed down to the NDB kernel but that could not be handled there. Added in MySQL Cluster NDB 7.2.0. * `Ndb_pushed_queries_executed' The number of joins successfully pushed down to *Note `NDB': mysql-cluster. and executed there. Added in MySQL Cluster NDB 7.2.0. * `Ndb_pushed_reads' The number of rows returned to *Note `mysqld': mysqld. from the NDB kernel by joins that were pushed down. Note that executing *Note `EXPLAIN': explain. on joins that can be pushed down to *Note `NDB': mysql-cluster. does not add to this number. Added in MySQL Cluster NDB 7.2.0. * `Slave_heartbeat_period' Shows the replication heartbeat interval (in seconds) on a replication slave. This variable was added in MySQL Cluster NDB 6.3.4. * `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 *Note `CHANGE MASTER TO': change-master-to. statement was issued. This variable was added in MySQL Cluster NDB 6.3.4. * `Ndb_pruned_scan_count' This variable holds a count of the number of scans executed by *Note `NDBCLUSTER': mysql-cluster. since the MySQL Cluster was last started where *Note `NDBCLUSTER': mysql-cluster. 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. This variable was added in MySQL Cluster NDB 6.3.25 and MySQL Cluster NDB 7.0.5. * `Ndb_scan_count' This variable holds a count of the total number of scans executed by *Note `NDBCLUSTER': mysql-cluster. since the MySQL Cluster was last started. This variable was added in MySQL Cluster NDB 6.3.25 and MySQL Cluster NDB 7.0.5.  File: manual.info, Node: mysql-cluster-interconnects, Prev: mysql-cluster-options-variables, Up: mysql-cluster-configuration 17.3.5 Using High-Speed Interconnects with MySQL Cluster -------------------------------------------------------- * Menu: * mysql-cluster-sci-sockets:: Configuring MySQL Cluster to use SCI Sockets * mysql-cluster-interconnects-performance:: MySQL Cluster Interconnects and Performance Even before design of *Note `NDBCLUSTER': mysql-cluster. 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, *Note `NDBCLUSTER': mysql-cluster. 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 MySQL Cluster codebase provides for four different transporters: * _TCP/IP using 100 Mbps or gigabit Ethernet_, as discussed in *Note 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 MySQL Cluster. See *Note mysql-cluster-tcp-definition-direct::, for details. * _Shared memory (SHM)_. For more information about SHM, see *Note mysql-cluster-shm-definition::. *Note*: SHM is considered experimental only, and is not officially supported. * _Scalable Coherent Interface (SCI)_, as described in the next section of this chapter, *Note mysql-cluster-sci-definition::. 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 MySQL Cluster. We are working to make sure that communication with the *Note `ndbd': mysql-cluster-programs-ndbd. process is made in `chunks' that are as large as possible because this benefits all types of data transmission. For users who desire it, it is also possible to use cluster interconnects to enhance performance even further. There are two ways to achieve this: Either a custom transporter can be designed to handle this case, or you can use socket implementations that bypass the TCP/IP stack to one extent or another. We have experimented with both of these techniques using the SCI (Scalable Coherent Interface) technology developed by Dolphin Interconnect Solutions (http://www.dolphinics.com/).  File: manual.info, Node: mysql-cluster-sci-sockets, Next: mysql-cluster-interconnects-performance, Prev: mysql-cluster-interconnects, Up: mysql-cluster-interconnects 17.3.5.1 Configuring MySQL Cluster to use SCI Sockets ..................................................... It is possible employing Scalable Coherent Interface (SCI) technology to achieve a significant increase in connection speeds and throughput between MySQL Cluster data and SQL nodes. To use SCI, it is necessary to obtain and install Dolphin SCI network cards and to use the drivers and other software supplied by Dolphin. You can get information on obtaining these, from Dolphin Interconnect Solutions (http://www.dolphinics.com/). SCI SuperSocket or SCI Transporter support is available for 32-bit and 64-bit Linux, Solaris, Windows, and other platforms. See the Dolphin documentation referenced later in this section for more detailed information regarding platforms supported for SCI. *Note*: Prior to MySQL 5.1.20, there were issues with building MySQL Cluster with SCI support (see Bug #25470), but these have been resolved due to work contributed by Dolphin. SCI Sockets are now correctly supported for MySQL Cluster hosts running recent versions of Linux using the `-max' builds, and versions of MySQL Cluster with SCI Transporter support can be built using either of `compile-amd64-max-sci' or `compile-pentium64-max-sci'. Both of these build scripts can be found in the `BUILD' directory of the MySQL Cluster source trees; it should not be difficult to adapt them for other platforms. Generally, all that is necessary is to compile MySQL Cluster with SCI Transporter support is to configure the MySQL Cluster build using `--with-ndb-sci=/opt/DIS'. Once you have acquired the required Dolphin hardware and software, you can obtain detailed information on how to adapt a MySQL Cluster configured for normal TCP/IP communication to use SCI from the from the Dolphin SCI online documentation (http://www.dolphinics.com/support/sci-product-documentation-software.html).  File: manual.info, Node: mysql-cluster-interconnects-performance, Prev: mysql-cluster-sci-sockets, Up: mysql-cluster-interconnects 17.3.5.2 MySQL Cluster Interconnects and Performance .................................................... The *Note `ndbd': mysql-cluster-programs-ndbd. process has a number of simple constructs which are used to access the data in a MySQL Cluster. We have created a very simple benchmark to check the performance of each of these and the effects which various interconnects have on their performance. There are four access methods: * Primary key access This is access of a record through its primary key. In the simplest case, only one record is accessed at a time, which means that the full cost of setting up a number of TCP/IP messages and a number of costs for context switching are borne by this single request. In the case where multiple primary key accesses are sent in one batch, those accesses share the cost of setting up the necessary TCP/IP messages and context switches. If the TCP/IP messages are for different destinations, additional TCP/IP messages need to be set up. * Unique key access Unique key accesses are similar to primary key accesses, except that a unique key access is executed as a read on an index table followed by a primary key access on the table. However, only one request is sent from the MySQL Server, and the read of the index table is handled by *Note `ndbd': mysql-cluster-programs-ndbd. Such requests also benefit from batching. * Full table scan When no indexes exist for a lookup on a table, a full table scan is performed. This is sent as a single request to the *Note `ndbd': mysql-cluster-programs-ndbd. process, which then divides the table scan into a set of parallel scans on all cluster *Note `ndbd': mysql-cluster-programs-ndbd. processes. In future versions of MySQL Cluster, an SQL node will be able to filter some of these scans. * Range scan using ordered index When an ordered index is used, it performs a scan in the same manner as the full table scan, except that it scans only those records which are in the range used by the query transmitted by the MySQL server (SQL node). All partitions are scanned in parallel when all bound index attributes include all attributes in the partitioning key. With benchmarks developed internally by MySQL for testing simple and batched primary and unique key accesses, we have found that using SCI sockets improves performance by approximately 100% over TCP/IP, except in rare instances when communication performance is not an issue. This can occur when scan filters make up most of processing time or when very large batches of primary key accesses are achieved. In that case, the CPU processing in the *Note `ndbd': mysql-cluster-programs-ndbd. processes becomes a fairly large part of the overhead. Using the SCI transporter instead of SCI Sockets is only of interest in communicating between *Note `ndbd': mysql-cluster-programs-ndbd. processes. Using the SCI transporter is also only of interest if a CPU can be dedicated to the *Note `ndbd': mysql-cluster-programs-ndbd. process because the SCI transporter ensures that this process will never go to sleep. It is also important to ensure that the *Note `ndbd': mysql-cluster-programs-ndbd. process priority is set in such a way that the process does not lose priority due to running for an extended period of time, as can be done by locking processes to CPUs in Linux 2.6. If such a configuration is possible, the *Note `ndbd': mysql-cluster-programs-ndbd. process will benefit by 10-70% as compared with using SCI sockets. (The larger figures will be seen when performing updates and probably on parallel scan operations as well.) There are several other optimized socket implementations for computer clusters, including Myrinet, Gigabit Ethernet, Infiniband and the VIA interface. However, we have tested MySQL Cluster so far only with SCI sockets. See *Note mysql-cluster-sci-sockets::, for information on how to set up SCI sockets using ordinary TCP/IP for MySQL Cluster.  File: manual.info, Node: mysql-cluster-programs, Next: mysql-cluster-management, Prev: mysql-cluster-configuration, Up: mysql-cluster 17.4 MySQL Cluster Programs =========================== * Menu: * mysql-cluster-programs-ndbd:: `ndbd' --- The MySQL Cluster Data Node Daemon * mysql-cluster-programs-ndbinfo-select-all:: `ndbinfo_select_all' --- Select From ndbinfo Tables * mysql-cluster-programs-ndbmtd:: `ndbmtd' --- The MySQL Cluster Data Node Daemon (Multi-Threaded) * mysql-cluster-programs-ndb-mgmd:: `ndb_mgmd' --- The MySQL Cluster Management Server Daemon * mysql-cluster-programs-ndb-mgm:: `ndb_mgm' --- The MySQL Cluster Management Client * mysql-cluster-programs-ndb-blob-tool:: `ndb_blob_tool' --- Check and Repair BLOB and TEXT columns of MySQL Cluster Tables * mysql-cluster-programs-ndb-config:: `ndb_config' --- Extract MySQL Cluster Configuration Information * mysql-cluster-programs-ndb-cpcd:: `ndb_cpcd' --- Automate Testing for NDB Development * mysql-cluster-programs-ndb-delete-all:: `ndb_delete_all' --- Delete All Rows from an NDB Table * mysql-cluster-programs-ndb-desc:: `ndb_desc' --- Describe NDB Tables * mysql-cluster-programs-ndb-drop-index:: `ndb_drop_index' --- Drop Index from an NDB Table * mysql-cluster-programs-ndb-drop-table:: `ndb_drop_table' --- Drop an NDB Table * mysql-cluster-programs-ndb-error-reporter:: `ndb_error_reporter' --- NDB Error-Reporting Utility * mysql-cluster-programs-ndb-index-stat:: `ndb_index_stat' --- NDB Index Statistics Utility * mysql-cluster-programs-ndb-print-backup-file:: `ndb_print_backup_file' --- Print NDB Backup File Contents * mysql-cluster-programs-ndb-print-schema-file:: `ndb_print_schema_file' --- Print NDB Schema File Contents * mysql-cluster-programs-ndb-print-sys-file:: `ndb_print_sys_file' --- Print NDB System File Contents * mysql-cluster-programs-ndbd-redo-log-reader:: `ndbd_redo_log_reader' --- Check and Print Content of Cluster Redo Log * mysql-cluster-programs-ndb-restore:: `ndb_restore' --- Restore a MySQL Cluster Backup * mysql-cluster-programs-ndb-select-all:: `ndb_select_all' --- Print Rows from an NDB Table * mysql-cluster-programs-ndb-select-count:: `ndb_select_count' --- Print Row Counts for NDB Tables * mysql-cluster-programs-ndb-show-tables:: `ndb_show_tables' --- Display List of NDB Tables * mysql-cluster-programs-ndb-size-pl:: `ndb_size.pl' --- NDBCLUSTER Size Requirement Estimator * mysql-cluster-programs-ndb-waiter:: `ndb_waiter' --- Wait for MySQL Cluster to Reach a Given Status * mysql-cluster-program-options-common:: Options Common to MySQL Cluster Programs --- Options Common to MySQL Cluster Programs Using and managing a MySQL Cluster requires several specialized programs, which we describe in this chapter. We discuss the purposes of these programs in a MySQL Cluster, how to use the programs, and what startup options are available for each of them. These programs include the MySQL Cluster data, management, and SQL node processes (*Note `ndbd': mysql-cluster-programs-ndbd, *Note `ndbmtd': mysql-cluster-programs-ndbmtd, *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd, and *Note `mysqld': mysqld.) and the management client (*Note `ndb_mgm': mysql-cluster-programs-ndb-mgm.). For information about using *Note `mysqld': mysqld. as a MySQL Cluster process, see *Note mysql-cluster-mysqld::. Other *Note `NDB': mysql-cluster. utility, diagnostic, and example programs are included with the MySQL Cluster distribution. These include *Note `ndb_restore': mysql-cluster-programs-ndb-restore, *Note `ndb_show_tables': mysql-cluster-programs-ndb-show-tables, and *Note `ndb_config': mysql-cluster-programs-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 MySQL Cluster programs.  File: manual.info, Node: mysql-cluster-programs-ndbd, Next: mysql-cluster-programs-ndbinfo-select-all, Prev: mysql-cluster-programs, Up: mysql-cluster-programs 17.4.1 `ndbd' -- The MySQL Cluster Data Node Daemon --------------------------------------------------- *Note `ndbd': mysql-cluster-programs-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 a MySQL Cluster, a set of *Note `ndbd': mysql-cluster-programs-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 MySQL Cluster data node program *Note `ndbd': mysql-cluster-programs-ndbd. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndbd': mysql-cluster-programs-ndbd.), see *Note mysql-cluster-program-options-common::. *`ndbd' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndbd': mysql-cluster-programs-ndbd. program Format Description Added / Removed ` --initial ' Perform initial start of All MySQL 5.1 ndbd, including cleaning based releases the file system. Consult the documentation before using this option `--nostart', Don't start ndbd All MySQL 5.1 immediately; ndbd waits based releases ` -n ' for command to start from ndb_mgmd `--daemon', Start ndbd as daemon All MySQL 5.1 (default); override with based releases ` -d ' -nodaemon ` --nodaemon ' Do not start ndbd as All MySQL 5.1 daemon; provided for based releases testing purposes ` --foreground ' Run ndbd in foreground, All MySQL 5.1 provided for debugging based releases purposes (implies -nodaemon) ` --nowait-nodes=list ' Do not wait for these ADDED: 5.1.9 data nodes to start (takes comma-separated list of node IDs). Also requires -ndb-nodeid to be used. ` --initial-start ' Perform partial initial ADDED: 5.1.11 start (requires -nowait-nodes) ` --bind-address=name ' Local bind address ADDED: 5.1.12 ` --install[=name] ' Used to install the data ADDED: NDB node process as a 7.0.16, NDB Windows service. Does not 7.1.5 apply on non-Windows platforms. ` --remove[=name] ' Used to remove a data ADDED: NDB node process that was 7.0.16, NDB previously installed as a 7.1.5 Windows service. Does not apply on non-Windows platforms. ` --connect-retries=# ' Number of times to try ADDED: NDB contacting the 7.0.36, NDB management server; set 7.1.25 to -1 to keep trying indefinitely ` --connect-delay=# ' Time to wait between ADDED: NDB attempts to contact a 7.0.36, NDB management server, in 7.1.25 seconds *Note*: All of these options also apply to the multi-threaded version of this program (*Note `ndbmtd': mysql-cluster-programs-ndbmtd, available in MySQL Cluster NDB 7.0 and later) and you may substitute `*Note `ndbmtd': mysql-cluster-programs-ndbmtd.' for `*Note `ndbd': mysql-cluster-programs-ndbd.' wherever the latter occurs in this section. * `--bind-address' Options for bind-address *Introduced* 5.1.12 *Command-Line `--bind-address=name' Format* *Permitted Values* *Type* `string' *Default* `' Causes *Note `ndbd': mysql-cluster-programs-ndbd. to bind to a specific network interface (host name or IP address). This option has no default value. This option was added in MySQL 5.1.12. * `--daemon', `-d' Options for daemon *Command-Line `--daemon' Format* `-d' *Permitted Values* *Type* `boolean' *Default* `TRUE' Instructs *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndbmtd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndbmtd': mysql-cluster-programs-ndbmtd. on Windows platforms. * `--nodaemon' Options for nodaemon *Command-Line `--nodaemon' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Prevents *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndbmtd': mysql-cluster-programs-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. As of MySQL Cluster NDB 7.0.8, the default behavior for *Note `ndbd': mysql-cluster-programs-ndbd. and *Note `ndbmtd': mysql-cluster-programs-ndbmtd. on Windows is to run in the foreground, making this option unnecessary on Windows platforms, where it has no effect. (Bug #45588) * `--foreground' Options for foreground *Command-Line `--foreground' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Causes *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndbmtd': mysql-cluster-programs-ndbmtd. to execute as a foreground process, primarily for debugging purposes. This option implies the `--nodaemon' option. This option has no effect when running *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndbmtd': mysql-cluster-programs-ndbmtd. on Windows platforms. * `--initial' Options for initial *Command-Line `--initial' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Instructs *Note `ndbd': mysql-cluster-programs-ndbd. to perform an initial start. An initial start erases any files created for recovery purposes by earlier instances of *Note `ndbd': mysql-cluster-programs-ndbd. It also re-creates recovery log files. Note that on some operating systems this process can take a substantial amount of time. An `--initial' start is to be used _only_ when starting the *Note `ndbd': mysql-cluster-programs-ndbd. process under very special circumstances; this is because this option causes all files to be removed from the MySQL 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 *Note `ndbd': mysql-cluster-programs-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. 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 * MySQL Cluster Disk Data files (see *Note 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 a MySQL 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' Options for initial-start *Introduced* 5.1.11 *Command-Line `--initial-start' Format* *Permitted Values* *Type* `boolean' *Default* `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 Prior to MySQL 5.1.19, it was not possible to perform DDL operations involving Disk Data tables on a partially started cluster. (See Bug #24631.) When using this option, you must also specify the node ID for the data node being started with the `--ndb-nodeid' option. This option was added in MySQL 5.1.11. *Important*: Do not confuse this option with the `--nowait-nodes' option added for *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. in MySQL Cluster NDB 7.0.10, which can be used to enable a cluster configured with multiple management servers to be started without all management servers being online. * `--nowait-nodes=NODE_ID_1[, NODE_ID_2[, ...]]' Options for nowait-nodes *Introduced* 5.1.9 *Command-Line `--nowait-nodes=list' Format* *Permitted Values* *Type* `string' *Default* `' 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 *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-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. This option was added in MySQL 5.1.9. * `--nostart', `-n' Options for nostart *Command-Line `--nostart' Format* `-n' *Permitted Values* *Type* `boolean' *Default* `FALSE' Instructs *Note `ndbd': mysql-cluster-programs-ndbd. not to start automatically. When this option is used, *Note `ndbd': mysql-cluster-programs-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 *Note mysql-cluster-mgm-client-commands::). * `--install[=NAME]' Options for install *Introduced* 5.1.47-ndb-7.1.5 *Command-Line `--install[=name]' Format* *Permitted Values* *Type* `string' *Default* `ndbd' Causes *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-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. This option became available in MySQL Cluster NDB 7.0.16 and MySQL Cluster NDB 7.1.5. * `--remove[=NAME]' Options for remove *Introduced* 5.1.47-ndb-7.1.5 *Command-Line `--remove[=name]' Format* *Permitted Values* *Type* `string' *Default* `ndbd' Causes an *Note `ndbd': mysql-cluster-programs-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. This option became available in MySQL Cluster NDB 7.0.16 and MySQL Cluster NDB 7.1.5. * `--connect-retries=#' Options for connect-retries *Introduced* 5.1.63-ndb-7.1.25 *Command-Line `--connect-retries=#' Format* *Permitted Values* *Type* `numeric' *Default* `12' *Range* `-1 .. 65535' Determines the number of times that the data node attempts to contact a management server when starting. Setting this option to -1 causes the data node to keep trying to make contact indefinitely. The default is 12 attempts. The time to wait between attempts is controlled by the `--connect-delay' option. This option was added in MySQL Cluster NDB 7.0.36 and MySQL Cluster 7.1.25. * `--connect-delay=#' Options for connect-delay *Introduced* 5.1.63-ndb-7.1.25 *Command-Line `--connect-delay=#' Format* *Permitted Values* *Type* `numeric' *Default* `5' *Range* `0 .. 3600' 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 attempts. This option was added in MySQL Cluster NDB 7.0.36 and MySQL Cluster 7.1.25. *Note `ndbd': mysql-cluster-programs-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 the node's unique identifier. Note that NODE_ID 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 *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd. exit codes and messages generated when a data node process shuts down prematurely can be found in `ndbd' Error Messages (http://dev.mysql.com/doc/ndbapi/en/ndbd-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 MySQL 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 *Note `ndbd': mysql-cluster-programs-ndbd. process. This file is created only if *Note `ndbd': mysql-cluster-programs-ndbd. is started as a daemon, which is the default behavior. * `ndb_NODE_ID.pid' is a file containing the process ID of the *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd, where it is possible to trace all incoming, outgoing, and internal messages with their data in the *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-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 *Note mysql-cluster-connection-strings::, for additional information about this issue. *Note mysql-cluster-programs-ndbd::, describes other options for *Note `ndbd': mysql-cluster-programs-ndbd. When *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd. process if it is configured to do so. Thus, if you attempt to kill *Note `ndbd': mysql-cluster-programs-ndbd. using the Unix *Note `kill': kill. command, it is necessary to kill both processes, beginning with the angel process. The preferred method of terminating an *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd. process. In a multi-processor system performing a large number of operations (including updates), the *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd. processes which belong to different node groups; however, such a configuration is still considered experimental and is not supported for MySQL 5.1 in a production setting. See *Note mysql-cluster-limitations::.  File: manual.info, Node: mysql-cluster-programs-ndbinfo-select-all, Next: mysql-cluster-programs-ndbmtd, Prev: mysql-cluster-programs-ndbd, Up: mysql-cluster-programs 17.4.2 `ndbinfo_select_all' -- Select From ndbinfo Tables --------------------------------------------------------- *Note `ndbinfo_select_all': mysql-cluster-programs-ndbinfo-select-all. is a client program that selects all rows and columns from one or more tables in the *Note `ndbinfo': mysql-cluster-ndbinfo. database. It is included with the MySQL Cluster distribution beginning with MySQL Cluster NDB 7.1.17. Not all `ndbinfo' tables can be accessed by this program. `ndbinfo_select_all' can access the *Note `counters': mysql-cluster-ndbinfo-counters, *Note `diskpagebuffer': mysql-cluster-ndbinfo-diskpagebuffer, *Note `logbuffers': mysql-cluster-ndbinfo-logbuffers, *Note `logspaces': mysql-cluster-ndbinfo-logspaces, *Note `nodes': mysql-cluster-ndbinfo-nodes, *Note `resources': mysql-cluster-ndbinfo-resources, `threadblocks', `threadstat', and *Note `transporters': mysql-cluster-ndbinfo-transporters. tables. To select from one or more `ndbinfo' tables using *Note `ndbinfo_select_all': mysql-cluster-programs-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 *Note `ndbinfo_select_all': mysql-cluster-programs-ndbinfo-select-all. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndbinfo_select_all': mysql-cluster-programs-ndbinfo-select-all.), see *Note mysql-cluster-program-options-common::. *`ndbinfo_select_all' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndbinfo_select_all': mysql-cluster-programs-ndbinfo-select-all. program Format Description Added / Removed ` --delay=# ' Set the delay in seconds All MySQL 5.1 between loops. Default based releases is 5. `--loops=#', Set the number of times All MySQL 5.1 to perform the select. based releases ` -l ' Default is 1. `--database=db_name', Name of the database All MySQL 5.1 where the table located. based releases ` -d ' `--parallelism=#', Set the degree of All MySQL 5.1 parallelism. based releases ` -p ' * `--delay=`seconds'' Options for delay *Command-Line `--delay=#' Format* *Permitted Values* *Type* `numeric' *Default* `5' *Range* `0 .. 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' Options for loops *Command-Line `--loops=#' Format* `-l' *Permitted Values* *Type* `numeric' *Default* `1' *Range* `0 .. MAX_INT' This option sets the number of times to execute the select. Use `--delay' to set the time between loops.  File: manual.info, Node: mysql-cluster-programs-ndbmtd, Next: mysql-cluster-programs-ndb-mgmd, Prev: mysql-cluster-programs-ndbinfo-select-all, Up: mysql-cluster-programs 17.4.3 `ndbmtd' -- The MySQL Cluster Data Node Daemon (Multi-Threaded) ---------------------------------------------------------------------- *Note `ndbmtd': mysql-cluster-programs-ndbmtd. is a multi-threaded version of *Note `ndbd': mysql-cluster-programs-ndbd, the process that is used to handle all the data in tables using the *Note `NDBCLUSTER': mysql-cluster. storage engine. *Note `ndbmtd': mysql-cluster-programs-ndbmtd. is intended for use on host computers having multiple CPU cores. Except where otherwise noted, *Note `ndbmtd': mysql-cluster-programs-ndbmtd. functions in the same way as *Note `ndbd': mysql-cluster-programs-ndbd.; therefore, in this section, we concentrate on the ways in which *Note `ndbmtd': mysql-cluster-programs-ndbmtd. differs from *Note `ndbd': mysql-cluster-programs-ndbd, and you should consult *Note mysql-cluster-programs-ndbd::, for additional information about running MySQL 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 *Note `ndbd': mysql-cluster-programs-ndbd. also apply to *Note `ndbmtd': mysql-cluster-programs-ndbmtd. For more information about these options and parameters, see *Note mysql-cluster-programs-ndbd::, and *Note mysql-cluster-ndbd-definition::, respectively. *Note `ndbmtd': mysql-cluster-programs-ndbmtd. is also file system-compatible with *Note `ndbd': mysql-cluster-programs-ndbd. In other words, a data node running *Note `ndbd': mysql-cluster-programs-ndbd. can be stopped, the binary replaced with *Note `ndbmtd': mysql-cluster-programs-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 *Note `ndbmtd': mysql-cluster-programs-ndbmtd. to run in multi-threaded fashion.) Similarly, an *Note `ndbmtd': mysql-cluster-programs-ndbmtd. binary can be replaced with *Note `ndbd': mysql-cluster-programs-ndbd. simply by stopping the node and then starting *Note `ndbd': mysql-cluster-programs-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'. Prior to MySQL Cluster NDB 7.0.6, there were known issues when using *Note `ndbmtd': mysql-cluster-programs-ndbmtd. with MySQL Cluster Disk Data tables. If you wish to use multi-threaded data nodes with disk-based `NDB' tables, you should ensure that you are running MySQL Cluster NDB 7.0.6 or later (see Bug #41915 and Bug #44915) Using *Note `ndbmtd': mysql-cluster-programs-ndbmtd. differs from using *Note `ndbd': mysql-cluster-programs-ndbd. in two key respects: 1. Because *Note `ndbmtd': mysql-cluster-programs-ndbmtd. runs by default in single-threaded mode (that is, it behaves like *Note `ndbd': mysql-cluster-programs-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. For more information about this parameter and its use, see *Note mysql-cluster-ndbd-definition-ndbmtd-parameters::. 2. Trace files are generated by critical errors in *Note `ndbmtd': mysql-cluster-programs-ndbmtd. processes in a somewhat different fashion from how these are generated by *Note `ndbd': mysql-cluster-programs-ndbd. failures. These differences are discussed in more detail in the next few paragraphs. Like *Note `ndbd': mysql-cluster-programs-ndbd, *Note `ndbmtd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd. In the event of a critical error, *Note `ndbmtd': mysql-cluster-programs-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 MySQL Cluster Development and Support teams. One trace file is generated for each *Note `ndbmtd': mysql-cluster-programs-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 *Note `ndbmtd': mysql-cluster-programs-ndbmtd. process running as a MySQL 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 *Note `ndbd': mysql-cluster-programs-ndbd. trace files. The *Note `ndbd': mysql-cluster-programs-ndbd. exit codes and messages that are generated when a data node process shuts down prematurely are also used by *Note `ndbmtd': mysql-cluster-programs-ndbmtd. See `ndbd' Error Messages (http://dev.mysql.com/doc/ndbapi/en/ndbd-error-messages.html), for a listing of these. *Note*: It is possible to use *Note `ndbd': mysql-cluster-programs-ndbd. and *Note `ndbmtd': mysql-cluster-programs-ndbmtd. concurrently on different data nodes in the same MySQL Cluster. However, such configurations have not been tested extensively; thus, we cannot recommend doing so in a production setting at this time.  File: manual.info, Node: mysql-cluster-programs-ndb-mgmd, Next: mysql-cluster-programs-ndb-mgm, Prev: mysql-cluster-programs-ndbmtd, Up: mysql-cluster-programs 17.4.4 `ndb_mgmd' -- The MySQL 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 MySQL Cluster management server program *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd.), see *Note mysql-cluster-program-options-common::. *`ndb_mgmd' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. program Format Description Added / Removed `--config-file=file', Specify the cluster All MySQL 5.1 configuration file; in based releases `-f', NDB-6.4.0 and later, needs -reload or ` -c ' -initial to override configuration cache if present ` --configdir=directory ' Specify the cluster ADDED: NDB management server's 6.4.0 configuration cache directory ` --bind-address=ip_address ' Local bind address ADDED: NDB 6.2.5, NDB 6.3.2 `--print-full-config', Print full configuration All MySQL 5.1 and exit based releases ` -P ' `--daemon', Run ndb_mgmd in daemon All MySQL 5.1 mode (default) based releases ` -d ' ` --nodaemon ' Do not run ndb_mgmd as a ADDED: NDB daemon 7.0.8 ` --interactive ' Run ndb_mgmd in All MySQL 5.1 interactive mode (not based releases officially supported in production; for testing purposes only) ` --log-name=name ' A name to use when ADDED: NDB writing messages 7.0.8 applying to this node in the cluster log. ` --no-nodeid-checks ' Do not provide any node All MySQL 5.1 id checks based releases ` --mycnf ' Read cluster All MySQL 5.1 configuration data from based releases the my.cnf file ` --reload ' Causes the management ADDED: NDB server to compare the 6.4.0 configuration file with its configuration cache ` --initial ' Causes the management ADDED: NDB server reload its 6.4.0 configuration data from the configuration file, bypassing the configuration cache ` --nowait-nodes=list ' Do not wait for these ADDED: NDB management nodes when 7.0.10, NDB starting this management 7.1.0 server. Also requires -ndb-nodeid to be used. ` --config-cache=value ' Enable the management ADDED: NDB server configuration 7.0.15, NDB cache; ON by default. 7.1.4 ` --install[=name] ' Used to install the ADDED: NDB management server 7.0.16, NDB process as a Windows 7.1.5 service. Does not apply on non-Windows platforms. ` --remove[=name] ' Used to remove a ADDED: NDB management server 7.0.16, NDB process that was 7.1.5 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[:PORT]' Options for bind-address *Introduced* 5.1.22-ndb-6.3.2 *Command-Line `--bind-address=ip_address' Format* *Permitted Values* *Type* `string' *Default* `[none]' When specified, this option limits management server connections by management clients to clients at the specified host name or IP address (and possibly port, if this is also specified). In such cases, a management client attempting to connect to the management server from any other address fails with the error `Unable to setup port: HOST:PORT!' If the PORT is not specified, the management client attempts to use port 1186. This option was added in MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB 6.3.2. * `--no-nodeid-checks' Options for no-nodeid-checks *Command-Line `--no-nodeid-checks' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Do not perform any checks of node IDs. * `--configdir=PATH' Options for configdir *Introduced* 5.1.30-ndb-6.4.0 *Command-Line `--configdir=directory' Format* *Permitted Values* *Type* `file name' *Default* `$INSTALLDIR/mysql-cluster' In MySQL Cluster NDB 7.0 and later, specifies the cluster management server's configuration cache directory. Starting with MySQL Cluster NDB 7.0.8, `--config-dir' is accepted as an alias for this option. * 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 *Note mysql-cluster-config-file::). You can do this by starting the *Note `ndb_mgmd': mysql-cluster-programs-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 *Note `ndb_mgmd': mysql-cluster-programs-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. This option was added in MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4. Beginning with MySQL Cluster NDB 7.0.31 and MySQL Cluster NDB 7.1.20, *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. no longer checks for the configuration directory (`--configdir') or attempts to create one when `--skip-config-cache' is used. (Bug #13428853) * `--config-file=FILENAME', `-f FILENAME' Options for config-file *Command-Line `--config-file=file' Format* `-f' *Permitted Values* *Type* `file name' *Default* `./config.ini' *Permitted Values* *Type* `file name' *Default* `[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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. executable; otherwise the file name and location must be specified explicitly. Beginning with MySQL Cluster NDB 6.4.0, this option has no default value, and is ignored unless the management server is forced to read the configuration file, either because *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. was started with the `--reload' or `--initial' option, or because the management server could not find any configuration cache. Beginning with MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, this option is also read if *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. was started with `--config-cache=OFF'. See *Note mysql-cluster-config-file::, for more information. Formerly, using this option together with `--initial' caused removal of the configuration cache even if the file was not found. This issue was resolved in MySQL Cluster NDB 7.0.38 and MySQL Cluster NDB 7.1.27. (Bug #1299289) * `--mycnf' Options for mycnf *Command-Line `--mycnf' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Read configuration data from the `my.cnf' file. * `--daemon', `-d' Options for daemon *Command-Line `--daemon' Format* `-d' *Permitted Values* *Type* `boolean' *Default* `TRUE' Instructs *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. to start as a daemon process. This is the default behavior. This option has no effect when running *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. on Windows platforms. * `--interactive' Options for interactive *Command-Line `--interactive' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Starts *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. in interactive mode; that is, an *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client session is started as soon as the management server is running. This option does not start any other MySQL Cluster nodes. * `--initial' Options for initial *Introduced* 5.1.30-ndb-6.4.0 *Command-Line `--initial' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Beginning with MySQL Cluster NDB 6.4.0, configuration data is cached internally rather than being read from the cluster global configuration file each time the management server is started (see *Note mysql-cluster-config-file::). Using this 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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. is invoked with `--initial' but cannot find a global configuration file, the management server cannot start. In MySQL Cluster NDB 7.0.8 and later, when starting, the management server checks for another management server in the same MySQL Cluster and tries to use its configuration data. In other words, *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. ignores `--initial' unless it is the only management server running. This behavior has implications when performing a rolling restart of a MySQL Cluster with multiple management nodes. See *Note mysql-cluster-rolling-restart::, for more information. Formerly, using this option together with the `--config-file' option caused removal of the configuration cache even if the file was not found. Starting with MySQL Cluster NDB 7.0.38 and MySQL Cluster NDB 7.1.27, the cache is cleared in such cases only if the configuration file is actually found. (Bug #1299289) This option was introduced in MySQL Cluster NDB 6.4.0. * `--log-name=NAME' Options for log-name *Introduced* 5.1.37-ndb-7.0.8 *Command-Line `--log-name=name' Format* *Permitted Values* *Type* `string' *Default* `MgmtSrvr' Provides a name to be used for this node in the cluster log. This option was added in MySQL Cluster NDB 7.0.8. * `--nodaemon' Options for nodaemon *Introduced* 5.1.37-ndb-7.0.8 *Command-Line `--nodaemon' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Instructs *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. not to start as a daemon process. As of MySQL Cluster NDB 7.0.8, the default behavior for *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. on Windows is to run in the foreground, making this option unnecessary on Windows platforms. (Bug #45588) * `--print-full-config', `-P' Options for print-full-config *Command-Line `--print-full-config' Format* `-P' *Permitted Values* *Type* `boolean' *Default* `FALSE' Shows extended information regarding the configuration of the cluster. With this option on the command line the *Note `ndb_mgmd': mysql-cluster-programs-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' Options for reload *Introduced* 5.1.30-ndb-6.4.0 *Command-Line `--reload' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Beginning with MySQL Cluster NDB 6.4.0, configuration data is stored internally rather than being read from the cluster global configuration file each time the management server is started (see *Note 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. In MySQL Cluster NDB 7.0.8 and later, when starting, the management server checks for another management server in the same MySQL Cluster and tries to use its configuration data. In other words, *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. ignores `--reload' unless it is the only management server running. This behavior has implications when performing a rolling restart of a MySQL Cluster with multiple management nodes. See *Note mysql-cluster-rolling-restart::, for more information. This option was introduced in MySQL Cluster NDB 6.4.0. * `--nowait-nodes' Options for nowait-nodes *Introduced* 5.1.39-ndb-7.1.0 *Command-Line `--nowait-nodes=list' Format* *Permitted Values* *Type* `numeric' *Default* `' *Range* `1 .. 255' When starting a MySQL Cluster is configured with two management nodes and running MySQL Cluster NDB 7.0 and later, each management server normally checks to see whether the other *Note `ndb_mgmd': mysql-cluster-programs-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 *Note `ndb_mgmd': mysql-cluster-programs-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 = 192.168.0.101 [ndbd] NodeId = 2 HostName = 192.168.0.102 [ndbd] NodeId = 3 HostName = 192.168.0.103 [ndbd] NodeId = 4 HostName = 192.168.0.104 [ndb_mgmd] NodeId = 10 HostName = 192.168.0.150 [ndb_mgmd] NodeId = 11 HostName = 192.168.0.151 [api] NodeId = 20 HostName = 192.168.0.200 [api] NodeId = 21 HostName = 192.168.0.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 192.168.0.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 192.168.0.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 *Note `ndb_mgmd': mysql-cluster-programs-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 192.168.0.150,192.168.0.151 The same is true with regard to the connection string used with any *Note `mysqld': mysqld. processes that you wish to start as MySQL Cluster SQL nodes connected to this cluster. See *Note mysql-cluster-connection-strings::, for more information. When used with *Note `ndb_mgmd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd. (or *Note `ndbmtd': mysql-cluster-programs-ndbmtd. in MySQL Cluster NDB 7.0 and later) 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 MySQL 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. This option was introduced in MySQL Cluster NDB 7.0.10 and MySQL Cluster NDB 7.1.0. 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 *Note mysql-cluster-connection-strings::, for information about using connection strings. *Note mysql-cluster-programs-ndb-mgmd::, describes other options for *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. The following files are created or used by *Note `ndb_mgmd': mysql-cluster-programs-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. *Note 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 *Note mysql-cluster-management::. 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'.) * `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]' Options for install *Introduced* 5.1.47-ndb-7.1.5 *Command-Line `--install[=name]' Format* *Permitted Values* *Type* `string' *Default* `ndb_mgmd' Causes *Note `ndb_mgmd': mysql-cluster-programs-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 *Note `ndb_mgmd': mysql-cluster-programs-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 *Note `ndb_mgmd': mysql-cluster-programs-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. This option became available in MySQL Cluster NDB 7.0.16 and MySQL Cluster NDB 7.1.5. * `--remove[=NAME]' Options for remove *Introduced* 5.1.47-ndb-7.1.5 *Command-Line `--remove[=name]' Format* *Permitted Values* *Type* `string' *Default* `ndb_mgmd' Causes an *Note `ndb_mgmd': mysql-cluster-programs-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. This option became available in MySQL Cluster NDB 7.0.16 and MySQL Cluster NDB 7.1.5.  File: manual.info, Node: mysql-cluster-programs-ndb-mgm, Next: mysql-cluster-programs-ndb-blob-tool, Prev: mysql-cluster-programs-ndb-mgmd, Up: mysql-cluster-programs 17.4.5 `ndb_mgm' -- The MySQL Cluster Management Client ------------------------------------------------------- The *Note `ndb_mgm': mysql-cluster-programs-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 *Note `ndb_mgm': mysql-cluster-programs-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 MySQL Cluster management client program *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm.), see *Note mysql-cluster-program-options-common::. *`ndb_mgm' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. program Format Description Added / Removed `--try-reconnect=#', Specify number of tries All MySQL 5.1 for connecting to based releases ` -t ' ndb_mgmd (0 = infinite) `--execute=name', Execute command and exit All MySQL 5.1 based releases ` -e ' * `--execute=`command'', `-e `command'' Options for execute *Command-Line `--execute=name' Format* `-e' This option can be used to send a command to the MySQL 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 *Note `mysql': mysql. command-line client. See *Note 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' Options for try-reconnect *Command-Line `--try-reconnect=#' Format* `-t' *Permitted Values* *Type* `boolean' *Default* `TRUE' 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. Additional information about using *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. can be found in *Note mysql-cluster-mgm-client-commands::.  File: manual.info, Node: mysql-cluster-programs-ndb-blob-tool, Next: mysql-cluster-programs-ndb-config, Prev: mysql-cluster-programs-ndb-mgm, Up: mysql-cluster-programs 17.4.6 `ndb_blob_tool' -- Check and Repair BLOB and TEXT columns of MySQL Cluster Tables ---------------------------------------------------------------------------------------- This tool, which is available in MySQL Cluster NDB 7.0.4 and later, can be used to check for and remove orphaned BLOB column parts from *Note `NDB': mysql-cluster. 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 *Note `BLOB': blob. or *Note `TEXT': blob. columns. The basic syntax for *Note `ndb_blob_tool': mysql-cluster-programs-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 *Note `ndb_blob_tool': mysql-cluster-programs-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 *Note `ndb_blob_tool': mysql-cluster-programs-ndb-blob-tool. In addition, you can optionally follow the table name with the (comma-separated) names of one or more *Note `BLOB': blob. or *Note `TEXT': blob. columns from that table. If no columns are listed, the tool works on all of the table's *Note `BLOB': blob. and *Note `TEXT': blob. 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 *Note `ndb_blob_tool': mysql-cluster-programs-ndb-blob-tool. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_blob_tool': mysql-cluster-programs-ndb-blob-tool.), see *Note mysql-cluster-program-options-common::. *`ndb_blob_tool' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_blob_tool': mysql-cluster-programs-ndb-blob-tool. program Format Description Added / Removed ` --check-orphans ' Check for orphan blob ADDED: NDB parts 7.0.4 `--database=db_name', Database to find the ADDED: NDB table in. 7.0.4 ` -d ' ` --delete-orphans ' Delete orphan blob parts ADDED: NDB 7.0.4 ` --dump-file=file ' Write orphan keys to ADDED: NDB specified file 7.0.4 `--verbose', Verbose output ADDED: NDB 7.0.4 ` -v ' * `--check-orphans' Options for check-orphans *Introduced* 5.1.32-ndb-7.0.4 *Command-Line `--check-orphans' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Check for orphaned BLOB parts in MySQL Cluster tables. * `--database=DB_NAME', `-d' Options for database *Introduced* 5.1.32-ndb-7.0.4 *Command-Line `--database=db_name' Format* `-d' *Permitted Values* *Type* `string' *Default* `[none]' Specify the database to find the table in. * `--delete-orphans' Options for delete-orphans *Introduced* 5.1.32-ndb-7.0.4 *Command-Line `--delete-orphans' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Remove orphaned BLOB parts from MySQL Cluster tables. * `--dump-file=FILE' Options for dump-file *Introduced* 5.1.32-ndb-7.0.4 *Command-Line `--dump-file=file' Format* *Permitted Values* *Type* `file name' *Default* `[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' Options for verbose *Introduced* 5.1.32-ndb-7.0.4 *Command-Line `--verbose' Format* `-v' *Permitted Values* *Type* `boolean' *Default* `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 *Note `CREATE TABLE': 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, *Note `ndb_blob_tool': mysql-cluster-programs-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 *Note `TEXT': blob. column. This is due to the fact that, in an *Note `NDB': mysql-cluster. table, only the first 256 bytes of a *Note `BLOB': blob. or *Note `TEXT': blob. 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 *Note storage-requirements::, for more information.  File: manual.info, Node: mysql-cluster-programs-ndb-config, Next: mysql-cluster-programs-ndb-cpcd, Prev: mysql-cluster-programs-ndb-blob-tool, Up: mysql-cluster-programs 17.4.7 `ndb_config' -- Extract MySQL Cluster Configuration Information ---------------------------------------------------------------------- This tool extracts current configuration information for data nodes, SQL nodes, and API nodes from one of a number of sources: a MySQL 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. Beginning with MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.16, it is also possible to use a data node as the source by specifying its node ID using `--config_from_node=NODE_ID'. Beginning with MySQL Cluster NDB 6.3.25 and MySQL Cluster NDB 7.0.6, *Note `ndb_config': mysql-cluster-programs-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). Beginning with MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.16, 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 *Note `ndb_config': mysql-cluster-programs-ndb-config. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_config': mysql-cluster-programs-ndb-config.), see *Note mysql-cluster-program-options-common::. *`ndb_config' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_config': mysql-cluster-programs-ndb-config. program Format Description Added / Removed ` --nodes ' Print node information All MySQL 5.1 (DB section) only. based releases ` --connections ' Print CONNECTIONS All MySQL 5.1 section information based releases only. Cannot be used with -nodes or -system option. `--query=string', One or more query All MySQL 5.1 options (attributes) based releases ` -q ' ` --host=name ' Specify host All MySQL 5.1 based releases ` --type=name ' Specify node type All MySQL 5.1 based releases `--nodeid', Get configuration of All MySQL 5.1 node with this ID based releases ` --id ' `--fields=string', Field separator All MySQL 5.1 based releases ` -f ' `--rows=string', Row separator All MySQL 5.1 based releases ` -r ' ` --config-file=path ' Set the path to All MySQL 5.1 config.ini file based releases ` --mycnf ' Read configuration data All MySQL 5.1 from my.cnf file based releases ` -c ' Short form for ADDED: 5.1.12 -ndb-connectstring ` --configinfo ' Dumps information about ADDED: NDB all NDB configuration 6.3.25, NDB parameters in text format 7.0.6 with default, maximum, and minimum values. Use with -xml to obtain XML output. ` --configinfo --xml ' Use -xml with ADDED: NDB -configinfo to obtain a 6.3.25, NDB dump of all NDB 7.0.6 configuration parameters in XML format with default, maximum, and minimum values. ` --system ' Print SYSTEM section ADDED: NDB information only. Cannot 7.0.27, NDB be used with -nodes or 7.1.16 -connections option. ` --config_from_node=# ' Obtain configuration ADDED: NDB data from the node 7.0.27, NDB having this ID (must be 7.1.16 a data node). * `--usage', `--help', or `-?' Options for help *Command-Line `--help' Format* `--usage' `-?' Causes *Note `ndb_config': mysql-cluster-programs-ndb-config. to print a list of available options, and then exit. * `--config_from_node=#' Options for config_from_node *Introduced* 5.1.56-ndb-7.1.16 *Command-Line `--config_from_node=#' Format* *Permitted Values* *Type* `numeric' *Default* `none' *Range* `1 .. 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, *Note `ndb_config': mysql-cluster-programs-ndb-config. fails with an error. (To obtain configuration data from the management node instead, simply omit this option.) `--config_from_node' was added in MySQL Cluster NDB 7.0.27 and MySQL NDB 7.1.16. * `--version', `-V' Options for version *Command-Line `--version' Format* `-V' Causes *Note `ndb_config': mysql-cluster-programs-ndb-config. to print a version information string, and then exit. * `--ndb-connectstring=CONNECT_STRING' Options for ndb-connectstring *Command-Line `--ndb-connectstring=connectstring' Format* `--connect-string=connectstring' `-c' *Permitted Values* *Type* `string' *Default* `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 *Note mysql-cluster-connection-strings::, and defaults to `localhost:1186'. The use of `-c' as a short version for this option is supported for *Note `ndb_config': mysql-cluster-programs-ndb-config. beginning with MySQL 5.1.12. * `--config-file=PATH-TO-FILE' Options for config-file *Command-Line `--config-file=path' Format* *Permitted Values* *Type* `file name' *Default* `' 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 *Note `ndb_config': mysql-cluster-programs-ndb-config. is invoked, then an absolute path must be used. * `--mycnf' Options for mycnf *Command-Line `--mycnf' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Read configuration data from the `my.cnf' file. * `--query=QUERY-OPTIONS', `-q' QUERY-OPTIONS Options for query *Command-Line `--query=string' Format* `-q' *Permitted Values* *Type* `string' *Default* `' 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=id,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. * `--host=HOSTNAME' Options for host *Command-Line `--host=name' Format* *Permitted Values* *Type* `string' *Default* `' 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 *Note `ndb_config `--host=localhost'': mysql-cluster-programs-ndb-config. to fail if *Note `ndb_config': mysql-cluster-programs-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 MySQL Cluster configuration values relating to hosts, or verify that all MySQL Cluster hosts handle `localhost' in the same fashion. * `--id=NODE_ID' `--nodeid=NODE_ID' Options for ndb-nodeid *Command-Line `--ndb-nodeid=#' Format* *Permitted Values* *Type* `numeric' *Default* `0' Either of these options can be used to specify the node ID of the node for which configuration information is to be obtained. `--nodeid' is the preferred form. * `--nodes' Options for nodes *Command-Line `--nodes' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Tells *Note `ndb_config': mysql-cluster-programs-ndb-config. to print information from parameters defined in `DB' sections only. Prior to MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.16, this option had no affect. This option cannot be used together with `--connections' or `--system'. * `--connections' Options for connections *Command-Line `--connections' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Tells *Note `ndb_config': mysql-cluster-programs-ndb-config. to print `CONNECTIONS' information only. This option existed prior to MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.16, but had no affect before then. This option cannot be used together with `--nodes' or `--system'. * `--system' Options for system *Introduced* 5.1.56-ndb-7.1.16 *Command-Line `--system' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Tells *Note `ndb_config': mysql-cluster-programs-ndb-config. to print `SYSTEM' information only. This option was introduced in MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.16. It cannot be used together with the `--nodes' or `--system' options. * `--type=NODE_TYPE' Options for type *Command-Line `--type=name' Format* *Permitted Values* *Type* `enumeration' *Default* `' *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. * `--fields=DELIMITER', `-f' DELIMITER Options for fields *Command-Line `--fields=string' Format* `-f' *Permitted Values* *Type* `string' *Default* `' 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. * `--rows=SEPARATOR', `-r' SEPARATOR Options for rows *Command-Line `--rows=string' Format* `-r' *Permitted Values* *Type* `string' *Default* `' 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. * `--configinfo' The `--configinfo' option, added in MySQL Cluster NDB 6.3.25 and MySQL Cluster NDB 7.0.6, causes *Note `ndb_config': mysql-cluster-programs-ndb-config. to dump a list of each MySQL Cluster configuration parameter supported by the MySQL Cluster distribution of which *Note `ndb_config': mysql-cluster-programs-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 * A brief description of the parameter's purpose, effects, and usage * MySQL 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) ... `--configinfo' `--xml' Options for xml *Introduced* 5.1.34-ndb-7.0.6 *Command-Line `--configinfo Format* --xml' *Permitted Values* *Type* `boolean' *Default* `false' You can obtain the output of *Note `ndb_config': mysql-cluster-programs-ndb-config. `--configinfo' as XML by adding the `--xml' option (like the `--configinfo' option, available beginning with MySQL Cluster NDB 6.3.25 and MySQL Cluster NDB 7.0.6). A portion of the resulting output is shown in this example: shell> ndb_config --configinfo --xml
...
... *Note*: Normally, the XML output produced by *Note `ndb_config': mysql-cluster-programs-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. Beginning with MySQL Cluster NDB 6.3.29 and MySQL Cluster NDB 7.0.10, 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 `' element. In addition (also beginning with MySQL Cluster NDB 6.3.29 and MySQL Cluster NDB 7.0.10), 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 `' 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): Currently, no `initial' attribute is included in the XML output for `' 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). *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 MySQL Cluster sources when *Note `ndb_config': mysql-cluster-programs-ndb-config. was compiled. For this reason, no connection to a running MySQL Cluster or access to a `config.ini' or `my.cnf' file is required for these two options. Combining other *Note `ndb_config': mysql-cluster-programs-ndb-config. options (such as `--query' or `--type') with `--configinfo' or `--xml' 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 *Note `ndb_config': mysql-cluster-programs-ndb-config, when used with the `--configinfo' option, does not access the MySQL 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 192.168.0.179:1186 3. This invocation of *Note `ndb_config': mysql-cluster-programs-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 : 192.168.0.193 : 83886080 : 18874368 : /usr/local/mysql/cluster-data 2 : 192.168.0.112 : 83886080 : 18874368 : /usr/local/mysql/cluster-data 3 : 192.168.0.176 : 83886080 : 18874368 : /usr/local/mysql/cluster-data 4 : 192.168.0.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=192.168.0.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 `--id' or `--nodeid' option.  File: manual.info, Node: mysql-cluster-programs-ndb-cpcd, Next: mysql-cluster-programs-ndb-delete-all, Prev: mysql-cluster-programs-ndb-config, Up: mysql-cluster-programs 17.4.8 `ndb_cpcd' -- Automate Testing for NDB Development --------------------------------------------------------- This utility is found in the `libexec' directory. It is part of an internal automated test framework used in testing and debugging MySQL Cluster. Because it can control processes on remote systems, it is not advisable to use *Note `ndb_cpcd': mysql-cluster-programs-ndb-cpcd. in a production cluster. The source files for *Note `ndb_cpcd': mysql-cluster-programs-ndb-cpcd. may be found in the directory `storage/ndb/src/cw/cpcd', in the MySQL Cluster source tree. Deprecated feature As of MySQL Cluster NDB 7.0, this program is deprecated and no longer actively maintained. It is subject to removal in a future MySQL Cluster version.  File: manual.info, Node: mysql-cluster-programs-ndb-delete-all, Next: mysql-cluster-programs-ndb-desc, Prev: mysql-cluster-programs-ndb-cpcd, Up: mysql-cluster-programs 17.4.9 `ndb_delete_all' -- Delete All Rows from an NDB Table ------------------------------------------------------------ *Note `ndb_delete_all': mysql-cluster-programs-ndb-delete-all. deletes all rows from the given *Note `NDB': mysql-cluster. table. In some cases, this can be much faster than *Note `DELETE': delete. or even *Note `TRUNCATE TABLE': truncate-table. * Usage * ndb_delete_all -c CONNECT_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 *Note `ndb_delete_all': mysql-cluster-programs-ndb-delete-all. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_delete_all': mysql-cluster-programs-ndb-delete-all.), see *Note mysql-cluster-program-options-common::. *`ndb_delete_all' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_delete_all': mysql-cluster-programs-ndb-delete-all. program Format Description Added / Removed `--database=dbname', Name of the database in All MySQL 5.1 which the table is found based releases `-d' `--transactional', Perform the delete in a All MySQL 5.1 single transaction (may based releases ` -t ' run out of operations) `--tupscan' Run tup scan All MySQL 5.1 based releases `--diskscan' Run disk scan All MySQL 5.1 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.  File: manual.info, Node: mysql-cluster-programs-ndb-desc, Next: mysql-cluster-programs-ndb-drop-index, Prev: mysql-cluster-programs-ndb-delete-all, Up: mysql-cluster-programs 17.4.10 `ndb_desc' -- Describe NDB Tables ----------------------------------------- *Note `ndb_desc': mysql-cluster-programs-ndb-desc. provides a detailed description of one or more *Note `NDB': mysql-cluster. tables. * Usage * ndb_desc -c CONNECT_STRING TBL_NAME -d DB_NAME [-p] (_MySQL Cluster NDB 7.0.36 and later; MySQL Cluster NDB 7.1.25 and later:_) ndb_desc -c CONNECT_STRING INDEX_NAME -d DB_NAME -t TBL_NAME * 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 ('','guppy', 35, 2), ('','tuna', 2500, 150000), ('','shark', 3000, 110000), ('','manta ray', 1500, 50000), ('','grouper', 900, 125000), ('','puffer', 250, 2500); Output from *Note `ndb_desc': mysql-cluster-programs-ndb-desc.: shell> ./ndb_desc -c localhost fish -d test -p -- fish -- Version: 2 Fragment type: 9 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: 311 Row Checksum: 1 Row GCI: 1 SingleUserMode: 0 ForceVarPart: 1 FragmentCount: 2 TableStatus: Retrieved -- 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=MEMORY weight_gm Int NOT NULL AT=FIXED ST=MEMORY -- Indexes -- PRIMARY KEY(id) - UniqueHashIndex PRIMARY(id) - OrderedIndex uk$unique(name) - UniqueHashIndex uk(name) - OrderedIndex -- Per partition info -- Partition Row count Commit count Frag fixed memory ... 0 2 2 32768 ... 1 4 4 32768 ... ... Frag varsized memory Extent_space Free extent_space ... 32768 0 0 ... 32768 0 0 NDBT_ProgramExit: 0 - OK Information about multiple tables can be obtained in a single invocation of *Note `ndb_desc': mysql-cluster-programs-ndb-desc. by using their names, separated by spaces. All of the tables must be in the same database. Beginning with MySQL Cluster NDB 7.0.36 and MySQL Cluster NDB 7.1.25, it is possible to obtain additional information about a specific index using the `--table' (short form: `-t') option introduced in these versions and supplying the name of the index as the first argument to *Note `ndb_desc': mysql-cluster-programs-ndb-desc, as shown here: shell> ./ndb_desc uk -d test -t fish -- uk -- Version: 3 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: 3 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 Row Checksum: 1 Row GCI: 1 SingleUserMode: 2 ForceVarPart: 0 FragmentCount: 4 ExtraRowGciBits: 0 ExtraRowAuthorBits: 0 TableStatus: Retrieved -- 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/ndbapi/en/ndb-internals-schema-object-versions.html). The `Extent_space' and `Free extent_space' columns were added in MySQL Cluster NDB 6.3.27 and MySQL Cluster NDB 7.0.8. They 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 *Note mysql-cluster-disk-data-objects::, as well as *Note create-logfile-group::, and *Note 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 ('','guppy', 35, 2), ('','tuna', 2500, 150000), ('','shark', 3000, 110000), ('','manta ray', 1500, 50000), ('','grouper', 900, 125000), ('','puffer', 250, 2500); When run against this version of the table, *Note `ndb_desc': mysql-cluster-programs-ndb-desc. displays the following output: shell> ./ndb_desc -c localhost fish -d test -p -- fish -- Version: 3 Fragment type: 9 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: 321 Row Checksum: 1 Row GCI: 1 SingleUserMode: 0 ForceVarPart: 1 FragmentCount: 2 TableStatus: Retrieved -- 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$unique(name) - UniqueHashIndex uk(name) - OrderedIndex -- Per partition info -- Partition Row count Commit count Frag fixed memory ... 0 2 2 32768 ... 1 4 4 32768 ... ... Frag varsized memory Extent_space Free extent_space ... 32768 0 0 ... 32768 0 0 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 *Note `INFORMATION_SCHEMA.FILES': files-table. table. The following table includes options that are specific to *Note `ndb_desc': mysql-cluster-programs-ndb-desc. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_desc': mysql-cluster-programs-ndb-desc.), see *Note mysql-cluster-program-options-common::. *`ndb_desc' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_desc': mysql-cluster-programs-ndb-desc. program Format Description Added / Removed `--blob-info', Include partition ADDED: NDB information for BLOB 6.3.32, NDB ` -b ' tables in output. 7.0.13, NDB Requires that the -p 7.1.2 option also be used `--database=dbname', Name of database All MySQL 5.1 containing table based releases ` -d ' `--extra-node-info', Include ADDED: NDB partition-to-data-node 6.2.19, NDB ` -n ' mappings in output. 6.3.33, NDB Requires that the -p 7.0.14, NDB option also be used 7.1.2 `--extra-partition-info', Display information All MySQL 5.1 about partitions based releases ` -p ' `--retries=#', Number of times to retry All MySQL 5.1 the connection (once per based releases ` -r ' second) `--table=tbl_name', Specify the table in ADDED: NDB which to find an index. 7.0.36, NDB ` -t ' When this option is used, 7.1.25 -p and -n have no effect and are ignored. `--unqualified', Use unqualified table All MySQL 5.1 names based releases ` -u ' * `--blob-info', `-b' Include information about subordinate *Note `BLOB': blob. and *Note `TEXT': blob. columns. Use of this option also requires the use of the `--extra-partition-info' (`-p') option. This option was added in MySQL Cluster NDB 6.3.32, MySQL Cluster NDB 7.0.13, and MySQL Cluster NDB 7.1.2. * `--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 MySQL Cluster. Use of this option also requires the use of the `--extra-partition-info' (`-p') option. This option was added in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.33, MySQL Cluster NDB 7.0.14, and MySQL Cluster NDB 7.1.2. * `--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. This option was added in MySQL Cluster NDB 7.0.36 and MySQL Cluster NDB 7.1.25. * `--unqualified', `-u' Use unqualified table names.  File: manual.info, Node: mysql-cluster-programs-ndb-drop-index, Next: mysql-cluster-programs-ndb-drop-table, Prev: mysql-cluster-programs-ndb-desc, Up: mysql-cluster-programs 17.4.11 `ndb_drop_index' -- Drop Index from an NDB Table -------------------------------------------------------- *Note `ndb_drop_index': mysql-cluster-programs-ndb-drop-index. drops the specified index from an *Note `NDB': mysql-cluster. 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 CONNECT_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 *Note `ndb_drop_index': mysql-cluster-programs-ndb-drop-index. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_drop_index': mysql-cluster-programs-ndb-drop-index.), see *Note mysql-cluster-program-options-common::. *`ndb_drop_index' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_drop_index': mysql-cluster-programs-ndb-drop-index. program Format Description Added / Removed `--database=dbname', Name of the database in All MySQL 5.1 which the table is found based 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.1.71-ndb-7.1.29 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*Note `DROP TABLE': drop-table. or the *Note `ndb_drop_table': mysql-cluster-programs-ndb-drop-table. utility (see *Note mysql-cluster-programs-ndb-drop-table::) to drop the table.  File: manual.info, Node: mysql-cluster-programs-ndb-drop-table, Next: mysql-cluster-programs-ndb-error-reporter, Prev: mysql-cluster-programs-ndb-drop-index, Up: mysql-cluster-programs 17.4.12 `ndb_drop_table' -- Drop an NDB Table --------------------------------------------- *Note `ndb_drop_table': mysql-cluster-programs-ndb-drop-table. drops the specified *Note `NDB': mysql-cluster. table. (If you try to use this on a table created with a storage engine other than *Note `NDB': mysql-cluster, 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 *Note `DROP TABLE': drop-table. statement on an *Note `NDB': mysql-cluster. table. * Usage * ndb_drop_table -c CONNECT_STRING TBL_NAME -d DB_NAME The following table includes options that are specific to *Note `ndb_drop_table': mysql-cluster-programs-ndb-drop-table. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_drop_table': mysql-cluster-programs-ndb-drop-table.), see *Note mysql-cluster-program-options-common::. *`ndb_drop_table' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_drop_table': mysql-cluster-programs-ndb-drop-table. program Format Description Added / Removed `--database=dbname', Name of the database in All MySQL 5.1 which the table is found based releases `-d'  File: manual.info, Node: mysql-cluster-programs-ndb-error-reporter, Next: mysql-cluster-programs-ndb-index-stat, Prev: mysql-cluster-programs-ndb-drop-table, Up: mysql-cluster-programs 17.4.13 `ndb_error_reporter' -- NDB Error-Reporting Utility ----------------------------------------------------------- *Note `ndb_error_reporter': mysql-cluster-programs-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 MySQL Cluster_. The following table includes command options specific to the MySQL Cluster program *Note `ndb_error_reporter': mysql-cluster-programs-ndb-error-reporter. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_error_reporter': mysql-cluster-programs-ndb-error-reporter.), see *Note mysql-cluster-program-options-common::. *`ndb_error_reporter' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_error_reporter': mysql-cluster-programs-ndb-error-reporter. program Format Description Added / Removed ` --fs ' Include file system data All MySQL 5.1 in error report; can use based releases a large amount of disk space * Usage * ndb_error_reporter PATH/TO/CONFIG-FILE [USERNAME] [--fs] This utility is intended for use on a management node host, and requires the path to the management host configuration file (`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. If the `--fs' is used, then the data node file systems are also copied to the management host and included in the archive that is produced by this script. As 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. Options for fs *Command-Line Format* `--fs' *Permitted Values* *Type* `boolean' *Default* `FALSE'  File: manual.info, Node: mysql-cluster-programs-ndb-index-stat, Next: mysql-cluster-programs-ndb-print-backup-file, Prev: mysql-cluster-programs-ndb-error-reporter, Up: mysql-cluster-programs 17.4.14 `ndb_index_stat' -- NDB Index Statistics Utility -------------------------------------------------------- *Note `ndb_index_stat': mysql-cluster-programs-ndb-index-stat ... * Usage * To obtain basic index statistics about a given *Note `NDB': mysql-cluster. table, invoke *Note `ndb_index_stat': mysql-cluster-programs-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 *Note `ndb_index_stat': mysql-cluster-programs-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:mytable index:PRIMARY fragCount:4 sampleVersion:2 loadTime:1336751773 sampleCount:0 keyBytes:0 query cache: valid:1 sampleCount:0 totalBytes:0 times in ms: save: 12.380 sort: 0.001 NDBT_ProgramExit: 0 - OK 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> * Options * The following table includes options that are specific to the MySQL Cluster *Note `ndb_index_stat': mysql-cluster-programs-ndb-index-stat. utility. Additional descriptions are listed following the table. For options common to most MySQL Cluster programs (including *Note `ndb_index_stat': mysql-cluster-programs-ndb-index-stat.), see *Note mysql-cluster-program-options-common::. *`ndb_index_stat' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_index_stat': mysql-cluster-programs-ndb-index-stat. program Format Description Added / Removed `--database=name', Name of the database All MySQL 5.1 containing the table. based releases `-d' `--delete' Delete index statistics All MySQL 5.1 for the given table, based releases stopping any auto-update previously configured. `--update' Update index statistics All MySQL 5.1 for the given table, based releases restarting any auto-update previously configured. `--dump' Print the query cache. All MySQL 5.1 based releases `--query=#' Perform a number of All MySQL 5.1 random range queries on based releases first key attr (must be int unsigned). `--sys-drop' Drop any statistics All MySQL 5.1 tables and events in NDB based releases kernel (all statistics are lost) `--sys-create' Create all statistics All MySQL 5.1 tables and events in NDB based releases kernel, if none of them already exist `--sys-create-if-not-exist' Create any statistics All MySQL 5.1 tables and events in NDB based releases kernel that do not already exist. `--sys-create-if-not-valid' Create any statistics All MySQL 5.1 tables or events that do based releases not already exist in the NDB kernel. after dropping any that are invalid. `--sys-check' Verify that NDB system All MySQL 5.1 index statistics and based releases event tables exist. `--sys-skip-tables' Do not apply sys-* All MySQL 5.1 options to tables. based releases `--sys-skip-events' Do not apply sys-* All MySQL 5.1 options to events. based releases `--verbose', Turn on verbose output All MySQL 5.1 based releases `-v' `--loops=#' Set the number of times All MySQL 5.1 to perform a given based releases 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 *Note ndb-index-stat-options-system::. * `--database=NAME', `-d NAME' Options for database *Command-Line `--database=name' Format* `-d' *Permitted Values* *Type* `string' *Default* `[none]' *Range* ` .. ' The name of the database that contains the table being queried. * `--delete' Options for delete *Command-Line `--delete' Format* *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' Delete the index statistics for the given table, stopping any auto-update that was previously configured. * `--update' Options for update *Command-Line `--update' Format* *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' Update the index statistics for the given table, and restart any auto-update that previously configured. * `--dump' Options for dump *Command-Line `--dump' Format* *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' Dump the contents of the query cache. * `--query=#' Options for query *Command-Line `--query=#' Format* *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. 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. They cannot be mixed with *Note ndb-index-stat-options-statistics::. * `--sys-drop' Options for sys-drop *Command-Line `--sys-drop' Format* *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' Drop all statistics tables and events in the NDB kernel. _This causes all statistics to be lost_. * `--sys-create' Options for sys-create *Command-Line `--sys-create' Format* *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' Create all statistics tables and events in the NDB kernel. This works only if none of them exist previously. * `sys-create-if-not-exist' Options for sys-create-if-not-exist *Command-Line `--sys-create-if-not-exist' Format* *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' 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' Options for sys-create-if-not-valid *Command-Line `--sys-create-if-not-valid' Format* *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' Create any NDB system statistics tables or events that do not already exist, after dropping any that are invalid. * `--sys-check' Options for sys-check *Command-Line `--sys-check' Format* *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' Verify that all required system statistics tables and events exist in the NDB kernel. * `--sys-skip-tables' Options for sys-skip-tables *Command-Line `--sys-skip-tables' Format* *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' Do not apply any `--sys-*' options to any statistics tables. * `--sys-skip-events' Options for sys-skip-events *Command-Line `--sys-skip-events' Format* *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' Do not apply any `--sys-*' options to any events. * `--verbose' Options for verbose *Command-Line `--verbose' Format* `-v' *Permitted Values* *Type* `boolean' *Default* `true' *Range* ` .. ' Turn on verbose output. * `--loops=#' Options for loops *Command-Line `--loops=#' Format* *Permitted Values* *Type* `numeric' *Default* `0' *Range* `0 .. MAX_INT' Repeat commands this number of times (for use in testing).  File: manual.info, Node: mysql-cluster-programs-ndb-print-backup-file, Next: mysql-cluster-programs-ndb-print-schema-file, Prev: mysql-cluster-programs-ndb-index-stat, Up: mysql-cluster-programs 17.4.15 `ndb_print_backup_file' -- Print NDB Backup File Contents ----------------------------------------------------------------- *Note `ndb_print_backup_file': mysql-cluster-programs-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 *Note mysql-cluster-backup-concepts::. Like *Note `ndb_print_schema_file': mysql-cluster-programs-ndb-print-schema-file. and *Note `ndb_print_sys_file': mysql-cluster-programs-ndb-print-sys-file. (and unlike most of the other *Note `NDB': mysql-cluster. utilities that are intended to be run on a management server host or to connect to a management server) *Note `ndb_print_backup_file': mysql-cluster-programs-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.  File: manual.info, Node: mysql-cluster-programs-ndb-print-schema-file, Next: mysql-cluster-programs-ndb-print-sys-file, Prev: mysql-cluster-programs-ndb-print-backup-file, Up: mysql-cluster-programs 17.4.16 `ndb_print_schema_file' -- Print NDB Schema File Contents ----------------------------------------------------------------- *Note `ndb_print_schema_file': mysql-cluster-programs-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 MySQL Cluster Data Node `FileSystemDir' Files (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-ndbd-filesystemdir-files.html). Like *Note `ndb_print_backup_file': mysql-cluster-programs-ndb-print-backup-file. and *Note `ndb_print_sys_file': mysql-cluster-programs-ndb-print-sys-file. (and unlike most of the other *Note `NDB': mysql-cluster. utilities that are intended to be run on a management server host or to connect to a management server) `ndb_schema_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.  File: manual.info, Node: mysql-cluster-programs-ndb-print-sys-file, Next: mysql-cluster-programs-ndbd-redo-log-reader, Prev: mysql-cluster-programs-ndb-print-schema-file, Up: mysql-cluster-programs 17.4.17 `ndb_print_sys_file' -- Print NDB System File Contents -------------------------------------------------------------- *Note `ndb_print_sys_file': mysql-cluster-programs-ndb-print-sys-file. obtains diagnostic information from a MySQL 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 MySQL Cluster Data Node `FileSystemDir' Files (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-ndbd-filesystemdir-files.html). Like *Note `ndb_print_backup_file': mysql-cluster-programs-ndb-print-backup-file. and *Note `ndb_print_schema_file': mysql-cluster-programs-ndb-print-schema-file. (and unlike most of the other *Note `NDB': mysql-cluster. utilities that are intended to be run on a management server host or to connect to a management server) *Note `ndb_print_backup_file': mysql-cluster-programs-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.  File: manual.info, Node: mysql-cluster-programs-ndbd-redo-log-reader, Next: mysql-cluster-programs-ndb-restore, Prev: mysql-cluster-programs-ndb-print-sys-file, Up: mysql-cluster-programs 17.4.18 `ndbd_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. *Note `ndbd_redo_log_reader': mysql-cluster-programs-ndbd-redo-log-reader. is intended for use primarily by MySQL Cluster developers and Support personnel in debugging and diagnosing problems. This utility was made available as part of default builds beginning with MySQL Cluster NDB 6.1.3. It remains under development, and its syntax and behavior are subject to change in future releases. For this reason, it should be considered experimental at this time. The C++ source files for *Note `ndbd_redo_log_reader': mysql-cluster-programs-ndbd-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 MySQL Cluster program *Note `ndbd_redo_log_reader': mysql-cluster-programs-ndbd-redo-log-reader. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndbd_redo_log_reader': mysql-cluster-programs-ndbd-redo-log-reader.), see *Note mysql-cluster-program-options-common::. *`ndbd_redo_log_reader' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndbd_redo_log_reader': mysql-cluster-programs-ndbd-redo-log-reader. program Format Description Added / Removed ` -noprint ' Do not print records All MySQL 5.1 based releases ` -nocheck ' Do not check records for All MySQL 5.1 errors based releases * Usage * ndbd_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_#_fs/D#/LCP/#/T#F#.Data'. In each case, the # represents a number (not necessarily the same number). For more information, see MySQL Cluster Data Node `FileSystemDir' Files (http://dev.mysql.com/doc/ndbapi/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: * Options for noprint *Command-Line `-noprint' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' `-noprint': Do not print the contents of the log file. * Options for nocheck *Command-Line `-nocheck' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' `-nocheck': Do not check the log file for errors. Like *Note `ndb_print_backup_file': mysql-cluster-programs-ndb-print-backup-file. and *Note `ndb_print_schema_file': mysql-cluster-programs-ndb-print-schema-file. (and unlike most of the *Note `NDB': mysql-cluster. utilities that are intended to be run on a management server host or to connect to a management server) *Note `ndbd_redo_log_reader': mysql-cluster-programs-ndbd-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.  File: manual.info, Node: mysql-cluster-programs-ndb-restore, Next: mysql-cluster-programs-ndb-select-all, Prev: mysql-cluster-programs-ndbd-redo-log-reader, Up: mysql-cluster-programs 17.4.19 `ndb_restore' -- Restore a MySQL Cluster Backup ------------------------------------------------------- The cluster restoration program is implemented as a separate command-line utility *Note `ndb_restore': mysql-cluster-programs-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. *Note `ndb_restore': mysql-cluster-programs-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 *Note 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 *Note `ndb_restore': mysql-cluster-programs-ndb-restore, it is recommended that the cluster be running in single user mode, unless you are restoring multiple data nodes in parallel. See *Note mysql-cluster-single-user-mode::, for more information. The following table includes options that are specific to the MySQL Cluster native backup restoration program *Note `ndb_restore': mysql-cluster-programs-ndb-restore. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_restore': mysql-cluster-programs-ndb-restore.), see *Note mysql-cluster-program-options-common::. *`ndb_restore' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_restore': mysql-cluster-programs-ndb-restore. program Format Description Added / Removed `--connect', Alias for -connectstring. All MySQL 5.1 based releases ` -c ' `--nodeid=#', Back up files from node All MySQL 5.1 with this ID based releases ` -n ' `--backupid=#', Restore from the backup All MySQL 5.1 with the given ID based releases ` -b ' ` --restore_data ' Restore table data and All MySQL 5.1 logs into NDB Cluster based releases using the NDB API `--restore_meta', Restore metadata to NDB All MySQL 5.1 Cluster using the NDB API based releases ` -m ' `--no-upgrade', Do not upgrade array ADDED: 5.1.19 type for varsize ` -u ' attributes which do not already resize VAR data, and do not change column attributes `--promote-attributes', Allow attributes to be ADDED: NDB promoted when restoring 6.3.8 ` -A ' data from backup `--preserve-trailing-spaces', Allow preservation of ADDED: NDB trailing spaces 6.3.8 ` -P ' (including padding) when promoting fixed-width string types to variable-width types `--no-restore-disk-objects', Do not restore objects ADDED: 5.1.6 relating to Disk Data ` -d ' `--restore_epoch', Restore epoch info into All MySQL 5.1 the status table. based 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. `--skip-table-check', Skip table structure ADDED: 5.1.17 check during restoring ` -s ' of data `--parallelism=#', Number of parallel All MySQL 5.1 transactions to use based releases ` -p ' while restoring data ` --print ' Print metadata, data and All MySQL 5.1 log to stdout based releases (equivalent to -print_meta -print_data -print_log) ` --print_meta ' Print metadata to stdout All MySQL 5.1 based releases ` --print_data ' Print data to stdout All MySQL 5.1 based releases ` --print_log ' Print to stdout All MySQL 5.1 based releases ` --backup_path=path ' Path to backup files ADDED: directory 5.1.17, NDB 6.1.5 `--dont_ignore_systab_0', Do not ignore system All MySQL 5.1 table during restore. based releases ` -f ' Experimental only; not for production use `--ndb-nodegroup-map=map', Nodegroup map for All MySQL 5.1 NDBCLUSTER storage based releases ` -z ' engine. Syntax: list of (source_nodegroup, destination_nodegroup) ` --fields-enclosed-by=char ' Fields are enclosed with ADDED: 5.1.18 the indicated character ` --fields-terminated-by=char ' Fields are terminated by ADDED: 5.1.18 the indicated character ` Fields are optionally ADDED: 5.1.18 --fields-optionally-enclosed-by enclosed with the ' indicated character ` --lines-terminated-by=char ' Lines are terminated by ADDED: 5.1.18 the indicated character ` --hex ' Print binary types in ADDED: 5.1.18 hexadecimal format `--tab=path', Creates a tab-separated ADDED: 5.1.18 .txt file for each table ` -T ' in the given path ` --append ' Append data to a ADDED: 5.1.18 tab-delimited file ` --progress-frequency=# ' Print status of All MySQL 5.1 restoration each given based releases number of seconds ` --no-binlog ' If a mysqld is connected ADDED: NDB and using binary 6.2.16, NDB logging, do not log the 6.3.16 restored data ` --verbose=# ' Level of verbosity in All MySQL 5.1 output based releases ` --include-databases=db-list ' List of one or more ADDED: NDB databases to restore 6.3.22, NDB (excludes those not 6.4.3 named) ` --exclude-databases=db-list ' List of one or more ADDED: NDB databases to exclude 6.3.22, NDB (includes those not 6.4.3 named) ` --include-tables=table-list ' List of one or more ADDED: NDB tables to restore 6.3.22, NDB (excludes those in same 6.4.3 database that are not named); each table reference must include the database name ` --exclude-tables=table-list ' List of one or more ADDED: NDB tables to exclude 6.3.22, NDB (includes those in same 6.4.3 database that are not not named); each table reference must include the database name ` --exclude-missing-columns ' Causes columns from the ADDED: NDB backup version of a 6.3.26, NDB table that are missing 7.0.7 from the version of the table in the database to be ignored. ` --disable-indexes ' Causes indexes from a ADDED: NDB backup to be ignored; 6.3.31, NDB may decrease time needed 7.0.11, NDB to restore data. 7.1.2 ` --rebuild-indexes ' Causes multi-threaded ADDED: NDB ordered index rebuilding 6.3.31, NDB of indexes found in the 7.0.11, NDB backup. 7.1.2 ` --skip-broken-objects ' Causes missing blob ADDED: NDB tables in the backup 6.3.40, NDB file to be ignored. 7.0.21, NDB 7.1.10 ` --skip-unknown-objects ' Causes schema objects ADDED: NDB not recognized by 6.3.34, NDB ndb_restore to be 7.0.15, NDB ignored when restoring a 7.1.4 backup made from a newer MySQL Cluster version to an older version. ` --rewrite-database=olddb,newdb Restores to a database ADDED: NDB ' with a different name 6.3.41, NDB than the original 7.0.22, NDB 7.1.11 `--lossy-conversions', Allow lossy conversions ADDED: NDB of column values (type 7.1.11 ` -L ' demotions or changes in sign) when restoring data from backup ` --restore-privilege-tables ' Restore MySQL privilege ADDED: NDB tables that were 7.2.0 previously moved to NDB. Typical options for this utility are shown here: ndb_restore [-c CONNECTSTRING] -n NODE_ID [-m] -b BACKUP_ID \ -r --backup_path=/PATH/TO/BACKUP/FILES The `-c' option is used to specify a connection string which tells `ndb_restore' where to locate the cluster management server. (See *Note mysql-cluster-connection-strings::, for information on connection strings.) If this option is not used, then *Note `ndb_restore': mysql-cluster-programs-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 *Note mysql-cluster-api-definition::). You can verify that *Note `ndb_restore': mysql-cluster-programs-ndb-restore. is connected to the cluster by using the `SHOW' command in the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. management client. You can also accomplish this from a system shell, as shown here: shell> ndb_mgm -e "SHOW" `-n' is used to specify the node ID of the data node on which the backups were taken. The first time you run the *Note `ndb_restore': mysql-cluster-programs-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 metdata need be done only on a single data node; this is sufficient to restore it to the entire cluster. Note that the cluster should have an empty database when starting to restore a backup. (In other words, you should start *Note `ndbd': mysql-cluster-programs-ndbd. with `--initial' prior to performing the restore.) It is possible to restore data without restoring table metadata. Prior to MySQL 5.1.17, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. did not perform any checks of table schemas; if a table was altered between the time the backup was taken and when *Note `ndb_restore': mysql-cluster-programs-ndb-restore. was run, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. would still attempt to restore the data to the altered table. Beginning with MySQL 5.1.17, the default behavior is for *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to fail with an error if table data do not match the table schema; this can be overridden using the `--skip-table-check' or `-s' option. Prior to MySQL 5.1.21, if this option is used, then *Note `ndb_restore': mysql-cluster-programs-ndb-restore. attempts to fit data into the existing table schema, but the result of restoring a backup to a table schema that does not match the original is unspecified. Beginning with MySQL Cluster NDB 6.3.35, MySQL Cluster NDB 7.0.16, and MySQL Cluster NDB 7.1.5, some of the restrictions on mismatches in column definitions when restoring data using *Note `ndb_restore': mysql-cluster-programs-ndb-restore. are relaxed; when one of these types of mismatches is encountered, *Note `ndb_restore': mysql-cluster-programs-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 Beginning with MySQL Cluster NDB 6.3.8, *Note `ndb_restore': mysql-cluster-programs-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 *Note `MEDIUMINT': integer-types. column can be restored to a column of type *Note `INT': integer-types. or *Note `BIGINT': integer-types. See *Note replication-features-different-data-types::, for a table of type conversions currently supported by attribute promotion. Attribute promotion by *Note `ndb_restore': mysql-cluster-programs-ndb-restore. must be enabled explicitly, as follows: 1. Prepare the table to which the backup is to be restored. *Note `ndb_restore': mysql-cluster-programs-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 *Note `ALTER TABLE': alter-table. after restoring the table metadata but before restoring the data. 2. Invoke *Note `ndb_restore': mysql-cluster-programs-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. `--lossy-conversions', `-L' Options for lossy-conversions *Introduced* 5.1.51-ndb-7.1.11 *Command-Line Format* `--lossy-conversions' `-L' *Permitted Values* *Type* `boolean' *Default* `FALSE' 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 *Note replication-features-different-data-types::, for information about specific type conversions currently supported by attribute demotion. *Note `ndb_restore': mysql-cluster-programs-ndb-restore. reports any truncation of data that it performs during lossy conversions once per attribute and column. This option was added in MySQL Cluster NDB 7.1.11. The `--preserve-trailing-spaces' option is also available beginning with MySQL Cluster NDB 6.3.8. This option (short form `-R') causes trailing spaces to be preserved when promoting a fixed-width character data type to its variable-width equivalent--that is, when promoting a *Note `CHAR': char. column value to *Note `VARCHAR': char. or a `BINARY' column value to *Note `VARBINARY': binary-varbinary. Otherwise, any trailing spaces are dropped from such column values when they are inserted into the new columns. *Note*: Although you can promote *Note `CHAR': char. columns to *Note `VARCHAR': char. and `BINARY' columns to *Note `VARBINARY': binary-varbinary, you cannot promote *Note `VARCHAR': char. columns to *Note `CHAR': char. or *Note `VARBINARY': binary-varbinary. columns to `BINARY'. The `-b' 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 *Note 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. `--restore_epoch' (short form: `-e') adds (or restores) epoch information to the cluster replication status table. This is useful for starting replication on a MySQL 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 *Note mysql-cluster-replication-backups::.) `--restore_data' This option causes *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to output *Note `NDB': mysql-cluster. table data and logs. `--restore_meta' This option causes *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to print *Note `NDB': mysql-cluster. table metadata. Generally, you need only use this option when restoring the first data node of a cluster; additional data nodes can obtain the metadata from the first one. `--restore-privilege-tables' *Note `ndb_restore': mysql-cluster-programs-ndb-restore. does not by default restore distributed MySQL privilege tables (MySQL Cluster NDB 7.2.0 and later). This option causes *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to restore the privilege tables. This works only if the privilege tables were converted to *Note `NDB': mysql-cluster. before the backup was taken. For more information, see *Note mysql-cluster-privilege-distribution::. `--backup_path' The path to the backup directory is required; this is supplied to *Note `ndb_restore': mysql-cluster-programs-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 *Note `ndb_restore': mysql-cluster-programs-ndb-restore. executable is located, and may be optionally prefixed with `backup_path='. *Note*: Previous to MySQL 5.1.17 and MySQL Cluster NDB 6.1.5, the path to the backup directory was specified as shown here, with `backup_path=' being optional: [backup_path=]/PATH/TO/BACKUP/FILES Beginning with MySQL 5.1.17 and MySQL Cluster NDB 6.1.5, this syntax changed to `--backup_path=/PATH/TO/BACKUP/FILES', to conform more closely with options used by other MySQL programs; `--backupid' is required, and there is no short form for this option. 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 database nodes having the node IDs `2' and `3', is to be restored to a cluster with four nodes. Then *Note `ndb_restore': mysql-cluster-programs-ndb-restore. must be run twice--once for each database node in the cluster where the backup was taken. However, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. cannot always restore backups made from a cluster running one version of MySQL to a cluster running a different MySQL version. See *Note mysql-cluster-upgrade-downgrade::, for more information. *Important*: It is not possible to restore a backup made from a newer version of MySQL Cluster using an older version of *Note `ndb_restore': mysql-cluster-programs-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 *Note `ndb_restore': mysql-cluster-programs-ndb-restore. from the newer MySQL Cluster version to do so. For example, to restore a cluster backup taken from a cluster running MySQL Cluster NDB 7.1.8 to a cluster running MySQL Cluster NDB 7.0.16, you must use the *Note `ndb_restore': mysql-cluster-programs-ndb-restore. that comes with the MySQL Cluster NDB 7.1.8 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 *Note `ndb_restore': mysql-cluster-programs-ndb-restore. process. However, the data files must always be applied before the logs. `--no-upgrade' Formerly, when using *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to restore a backup made from a MySQL 5.0 cluster to a 5.1 cluster, *Note `VARCHAR': char. columns were not resized and were recreated using the 5.0 fixed format. Beginning with MySQL 5.1.19, `ndb_restore' recreates such *Note `VARCHAR': char. columns using MySQL Cluster 5.1's variable-width format. Also beginning with MySQL 5.1.19, this behavior can be overridden using the `--no-upgrade' option (short form: `-u') when running *Note `ndb_restore': mysql-cluster-programs-ndb-restore. `--print_data' The `--print_data' option causes *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to direct its output to `stdout'. *Note `TEXT': blob. and *Note `BLOB': blob. column values are always truncated to the first 256 bytes in the output; this cannot currently be overridden when using `--print_data'. Beginning with MySQL 5.1.18, several additional options are available for use with the `--print_data' option in generating data dumps, either to `stdout', or to a file. These are similar to some of the options used with *Note `mysqldump': mysqldump, and are shown in the following list: * `--tab', `-T' Options for tab *Introduced* 5.1.18 *Command-Line `--tab=path' Format* `-T' This option 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. * `--fields-enclosed-by=STRING' Options for fields-enclosed-by *Introduced* 5.1.18 *Command-Line `--fields-enclosed-by=char' Format* *Permitted Values* *Type* `string' *Default* `' Each column values are enclosed by the string passed to this option (regardless of data type; see next item). * `--fields-optionally-enclosed-by=STRING' Options for fields-optionally-enclosed-by *Introduced* 5.1.18 *Command-Line `--fields-optionally-enclosed-by' Format* *Permitted Values* *Type* `string' *Default* `' The string passed to this option is used to enclose column values containing character data (such as *Note `CHAR': char, *Note `VARCHAR': char, *Note `BINARY': binary-varbinary, *Note `TEXT': blob, or *Note `ENUM': enum.). * `--fields-terminated-by=STRING' Options for fields-terminated-by *Introduced* 5.1.18 *Command-Line `--fields-terminated-by=char' Format* *Permitted Values* *Type* `string' *Default* `\t (tab)' The string passed to this option is used to separate column values. The default value is a tab character (`\t'). * `--hex' Options for hex *Introduced* 5.1.18 *Command-Line `--hex' Format* If this option is used, all binary values are output in hexadecimal format. * `--fields-terminated-by=STRING' Options for fields-terminated-by *Introduced* 5.1.18 *Command-Line `--fields-terminated-by=char' Format* *Permitted Values* *Type* `string' *Default* `\t (tab)' This option specifies the string used to end each line of output. The default is a linefeed character (`\n'). * `--append' Options for append *Introduced* 5.1.18 *Command-Line `--append' Format* When used with the `--tab' and `--print_data' options, this causes the data to be appended to any existing files having the same names. *Note*: If a table has no explicit primary key, then the output generated when using the `--print_data' option includes the table's hidden primary key. `--print_meta' This option causes *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to print all metadata to `stdout'. `--print_log' The `--print_log' option causes *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to output its log to `stdout'. `--print' Causes *Note `ndb_restore': mysql-cluster-programs-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, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. makes no attempt to restore data or metadata to a MySQL Cluster. `--dont_ignore_systab_0' Normally, when restoring table data and metadata, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. ignores the copy of the *Note `NDB': mysql-cluster. 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_. `--ndb-nodegroup-map', `-z' 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'. `--no-binlog' This option prevents any connected SQL nodes from writing data restored by *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to their binary logs. Available beginning with MySQL Cluster NDB 6.2.16 and MySQL Cluster NDB 6.3.16. `--no-restore-disk-objects', `-d' This option stops *Note `ndb_restore': mysql-cluster-programs-ndb-restore. from restoring any MySQL Cluster Disk Data objects, such as tablespaces and log file groups; see *Note mysql-cluster-disk-data::, for more information about these. Added in MySQL 5.1.6. `--parallelism=#', `-p' Determines the maximum number of parallel transactions that *Note `ndb_restore': mysql-cluster-programs-ndb-restore. tries to use. By default, this is 128; the minimum is 1, and the maximum is 1024. `--progress-frequency=N' 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. `--verbose=#' Sets the level for the verbosity of the output. The minimum is 0; the maximum is 255. The default value is 1. Beginning with MySQL 5.1.18, it is possible to restore only selected databases, or selected tables from a single database, 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 `--include-databases=DB_NAME[,DB_NAME][,...]' Options for include-databases *Introduced* 5.1.32-ndb-6.4.3 *Command-Line Format* `--include-databases=db-list' *Permitted Values* *Type* `string' *Default* `' `--include-tables=DB_NAME.TBL_NAME[,DB_NAME.TBL_NAME][,...]' Options for include-tables *Introduced* 5.1.32-ndb-6.4.3 *Command-Line Format* `--include-tables=table-list' *Permitted Values* *Type* `string' *Default* `' Beginning with MySQL Cluster NDB 6.3.22 and MySQL Cluster NDB 6.4.3, you can (and should) use instead the `--include-databases' option or the `--include-tables' option for restoring only specific databases or tables, respectively. `--include-databases' takes a comma-delimited list of databases to be restored. `--include-tables' takes a comma-delimited list of tables (in `DATABASE.TABLE' format) to be restored. 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 *Note `ndb_restore': mysql-cluster-programs-ndb-restore, and are not restored. The following table shows several invocations of *Note `ndb_restore': mysql-cluster-programs-ndb-restore. using `--include-*' options (other options possibly required have been omitted for clarity), and the effects these have on restoring from a MySQL Cluster backup: This table shows several invocations of *Note `ndb_restore': mysql-cluster-programs-ndb-restore. using `--include-*' options, and the effects these have on restoring from a MySQL Cluster backup. Option Used 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' (or Only the table `t2' in database `--include-tables=db1.t2' `db1' and the table `t1' in database `--include-tables=db2.t1') `db2' are restored; no other tables in `db1', `db2', or any other database are restored Beginning with MySQL Cluster NDB 6.3.29 and MySQL Cluster NDB 7.0.10, you can 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.) *Note*: Prior to MySQL Cluster NDB 6.3.29 and MySQL Cluster NDB 7.0.10, multiple `--include-*' options were not handled correctly, and the result of the options shown in the previous example was that only the tables `db3.t1' and `db3.t2' were actually restored. (Bug #48907) `--exclude-databases=DB_NAME[,DB_NAME][,...]' Options for exclude-databases *Introduced* 5.1.32-ndb-6.4.3 *Command-Line Format* `--exclude-databases=db-list' *Permitted Values* *Type* `string' *Default* `' `--exclude-tables=DB_NAME.TBL_NAME[,DB_NAME.TBL_NAME][,...]' Options for exclude-tables *Introduced* 5.1.32-ndb-6.4.3 *Command-Line Format* `--exclude-tables=table-list' *Permitted Values* *Type* `string' *Default* `' Beginning with MySQL Cluster NDB 6.3.22 and MySQL Cluster NDB 6.4.3, it is possible to prevent one or more databases or tables from being restored using the *Note `ndb_restore': mysql-cluster-programs-ndb-restore. options `--exclude-databases' and `--exclude-tables'. `--exclude-databases' takes a comma-delimited list of one or more databases which should not be restored. `--exclude-tables' takes a comma-delimited list of one or more tables (using `DATABASE.TABLE' format) which should not be restored. 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 *Note `ndb_restore': mysql-cluster-programs-ndb-restore. This table shows several invocations of *Note `ndb_restore': mysql-cluster-programs-ndb-restore. usng `--exclude-*' options (other options possibly required have been omitted for clarity), and the effects these options have on restoring from a MySQL Cluster backup: This table shows several invocations of *Note `ndb_restore': mysql-cluster-programs-ndb-restore. usng `--exclude-*' options, and the effects these options have on restoring from a MySQL Cluster backup. Option Used 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' (or All tables in database `db1' except `--exclude-tables=db1.t2' for `t2' and all tables in database `--exclude-tables=db2.t1)' `db2' except for table `t1' are restored; no other tables in `db1' or `db2' are restored; all tables in all other databases are restored Beginning with MySQL Cluster NDB 6.3.29 and MySQL Cluster NDB 7.0.10, you can use these two options together. For example, the following causes all tables in all databases _except for_ databases `db1' and `db2', along with the tables `t1' and `t2' in database `db3', _not_ 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.) *Note*: Prior to MySQL Cluster NDB 6.3.29 and MySQL Cluster NDB 7.0.10, multiple `--exclude-*' options were not handled correctly, with the result that the options shown in the previous example caused ndb_restore to exclude only the tables `db3.t1' and `db3.t2'. (Bug #48907) Beginning with MySQL Cluster NDB 6.3.29 and MySQL Cluster NDB 7.0.10, 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 *Note `ndb_restore': mysql-cluster-programs-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 *Note*: Prior to MySQL Cluster NDB 6.3.29 and MySQL Cluster NDB 7.0.10, it was not possible to use `--include-databases' or `--include-tables' together with `--exclude-databases' or `--exclude-tables', as these combinations were evaluated inconsistently. (Bug #48907) `--exclude-missing-columns' Options for exclude-missing-columns *Introduced* 5.1.35-ndb-7.0.7 *Command-Line Format* `--exclude-missing-columns' Beginning with MySQL Cluster NDB 6.3.26 and MySQL Cluster NDB 7.0.7, it is also possible to restore only selected table columns using the `--exclude-missing-columns' option. When this option is used, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. ignores 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 options described in the previous paragraph to do so, then restore data to the remaining tables using a complementary set of these options. `--disable-indexes' Options for disable-indexes *Introduced* 5.1.41-ndb-7.1.2 *Command-Line Format* `--disable-indexes' Beginning with MySQL Cluster NDB 6.3.31, MySQL Cluster NDB 7.0.11, and MySQL CLuster NDB 7.1.2, you can use this option with *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to 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. `--rebuild-indexes' Options for rebuild-indexes *Introduced* 5.1.41-ndb-7.1.2 *Command-Line Format* `--rebuild-indexes' Beginning with MySQL Cluster NDB 6.3.31, MySQL Cluster NDB 7.0.11, and MySQL CLuster NDB 7.1.2, you can use this option with *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to cause multi-threaded rebuilding of the ordered indexes while restoring a native `NDB' backup. `--skip-broken-objects' Options for skip-broken-objects *Introduced* 5.1.51-ndb-7.1.10 *Command-Line Format* `--skip-broken-objects' This option causes *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to ignore corrupt tables while reading a native *Note `NDB': mysql-cluster. 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. This option was added in MySQL Cluster NDB 6.3.40, MySQL Cluster NDB 7.0.21, and MySQL CLuster NDB 7.1.10. `--skip-unknown-objects' Options for skip-unknown-objects *Introduced* 5.1.41-ndb-7.1.4 *Command-Line Format* `--skip-unknown-objects' This option causes *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to ignore any schema objects it does not recognize while reading a native *Note `NDB': mysql-cluster. backup. This can be used for restoring a backup made from a cluster running MySQL Cluster NDB 7.0 to a cluster running MySQL Cluster NDB 6.3. This option was added in MySQL Cluster NDB 6.3.34, MySQL Cluster NDB 7.0.15, and MySQL CLuster NDB 7.1.4. `--rewrite-database=OLD_DBNAME,NEW_DBNAME' Options for rewrite-database *Introduced* 5.1.51-ndb-7.1.11 *Command-Line Format* `--rewrite-database=olddb,newdb' *Permitted Values* *Type* `string' *Default* `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 *Note `ndb_restore': mysql-cluster-programs-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 *Note `ndb_restore': mysql-cluster-programs-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. This option was added in MySQL Cluster NDB 6.3.41, MySQL Cluster NDB 7.0.22, and MySQL Cluster NDB 7.1.11. Error reporting *Note `ndb_restore': mysql-cluster-programs-ndb-restore. reports both temporary and permanent errors. In the case of temporary errors, it may able to recover from them. Beginning with MySQL 5.1.12, it reports `Restore successful, but encountered temporary error, please look at configuration' in such cases. *Important*: After using *Note `ndb_restore': mysql-cluster-programs-ndb-restore. to initialize a MySQL 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 *Note `SHOW TABLES': show-tables. statement on that SQL node before running *Note `START SLAVE': start-slave. This is a known issue in MySQL Cluster.  File: manual.info, Node: mysql-cluster-programs-ndb-select-all, Next: mysql-cluster-programs-ndb-select-count, Prev: mysql-cluster-programs-ndb-restore, Up: mysql-cluster-programs 17.4.20 `ndb_select_all' -- Print Rows from an NDB Table -------------------------------------------------------- *Note `ndb_select_all': mysql-cluster-programs-ndb-select-all. prints all rows from an *Note `NDB': mysql-cluster. table to `stdout'. * Usage * ndb_select_all -c CONNECT_STRING TBL_NAME -d DB_NAME [> FILE_NAME] The following table includes options that are specific to the MySQL Cluster native backup restoration program *Note `ndb_select_all': mysql-cluster-programs-ndb-select-all. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_select_all': mysql-cluster-programs-ndb-select-all.), see *Note mysql-cluster-program-options-common::. *`ndb_select_all' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_select_all': mysql-cluster-programs-ndb-select-all. program Format Description Added / Removed `--database=dbname', Name of the database in All MySQL 5.1 which the table is found based releases ` -d ' `--parallelism=#', Degree of parallelism All MySQL 5.1 based releases ` -p ' `--lock=#', Lock type All MySQL 5.1 based releases ` -l ' `--order=index', Sort resultset according All MySQL 5.1 to index whose name is based releases ` -o ' supplied `--descending', Sort resultset in All MySQL 5.1 descending order based releases ` -z ' (requires order flag) `--header', Print header (set to All MySQL 5.1 0|FALSE to disable based releases ` -h ' headers in output) `--useHexFormat', Output numbers in All MySQL 5.1 hexadecimal format based releases ` -x ' `--delimiter=char', Set a column delimiter All MySQL 5.1 based releases ` -D ' ` --disk ' Print disk references All MySQL 5.1 (useful only for Disk based releases Data tables having nonindexed columns) ` --rowid ' Print rowid All MySQL 5.1 based releases ` --gci ' Include GCI in output All MySQL 5.1 based releases `--tup', Scan in tup order All MySQL 5.1 based releases ` -t ' ` --nodata ' Do not print table All MySQL 5.1 column data based 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 that this is the name of an index, not of a column, and that 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 column to the output showing the global checkpoint at which each row was last updated. See *Note mysql-cluster-overview::, and *Note mysql-cluster-log-events::, for more information about checkpoints. * `--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 *Note `SELECT': 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 *Note `ndb_select_all': mysql-cluster-programs-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 Note that all string values are enclosed by square brackets (``['...`]'') in the output of *Note `ndb_select_all': mysql-cluster-programs-ndb-select-all. For a further 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 *Note `ndb_select_all': mysql-cluster-programs-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 *Note*: In earlier MySQL Cluster NDB 7.0 and 7.1 releases, *Note `ndb_select_all': mysql-cluster-programs-ndb-select-all. did not print any output for `NULL' values as it did in MySQL Cluster NDB 6.3 and earlier release series. This issue was fixed in MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11. (Bug #60045)  File: manual.info, Node: mysql-cluster-programs-ndb-select-count, Next: mysql-cluster-programs-ndb-show-tables, Prev: mysql-cluster-programs-ndb-select-all, Up: mysql-cluster-programs 17.4.21 `ndb_select_count' -- Print Row Counts for NDB Tables ------------------------------------------------------------- *Note `ndb_select_count': mysql-cluster-programs-ndb-select-count. prints the number of rows in one or more *Note `NDB': mysql-cluster. 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 CONNECT_STRING] -dDB_NAME TBL_NAME[, TBL_NAME2[, ...]] The following table includes options that are specific to the MySQL Cluster native backup restoration program *Note `ndb_select_count': mysql-cluster-programs-ndb-select-count. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_select_count': mysql-cluster-programs-ndb-select-count.), see *Note mysql-cluster-program-options-common::. *`ndb_select_count' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_select_count': mysql-cluster-programs-ndb-select-count. program Format Description Added / Removed `--database=dbname', Name of the database in All MySQL 5.1 which the table is found based releases `-d' `--parallelism=#', Degree of parallelism All MySQL 5.1 based releases `-p' `--lock=#', Lock type All MySQL 5.1 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  File: manual.info, Node: mysql-cluster-programs-ndb-show-tables, Next: mysql-cluster-programs-ndb-size-pl, Prev: mysql-cluster-programs-ndb-select-count, Up: mysql-cluster-programs 17.4.22 `ndb_show_tables' -- Display List of NDB Tables ------------------------------------------------------- *Note `ndb_show_tables': mysql-cluster-programs-ndb-show-tables. displays a list of all *Note `NDB': mysql-cluster. database objects in the cluster. By default, this includes not only both user-created tables and *Note `NDB': mysql-cluster. system tables, but *Note `NDB': mysql-cluster.-specific indexes, internal triggers, and MySQL Cluster Disk Data objects as well. The following table includes options that are specific to the MySQL Cluster native backup restoration program *Note `ndb_show_tables': mysql-cluster-programs-ndb-show-tables. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_show_tables': mysql-cluster-programs-ndb-show-tables.), see *Note mysql-cluster-program-options-common::. *`ndb_show_tables' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_show_tables': mysql-cluster-programs-ndb-show-tables. program Format Description Added / Removed `--database=string', Specifies the database All MySQL 5.1 in which the table is based releases ` -d ' found `--loops=#', Number of times to All MySQL 5.1 repeat output based releases ` -l ' `--type=#', Limit output to objects All MySQL 5.1 of this type based releases ` -t ' `--unqualified', Do not qualify table All MySQL 5.1 names based releases ` -u ' `--parsable', Return output suitable All MySQL 5.1 for MySQL LOAD DATA based releases ` -p ' INFILE statement ` --show-temp-status ' Show table temporary flag All MySQL 5.1 based releases * Usage * ndb_show_tables [-c CONNECT_STRING] * `--database', `-d' Specifies the name of the database in which the tables are found. * `--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 *Note `LOAD DATA INFILE': load-data. * `--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 *Note `NDB': mysql-cluster. database objects to be listed (the default). * `--unqualified', `-u' If specified, this causes unqualified object names to be displayed. *Note*: Only user-created MySQL Cluster tables may be accessed from MySQL; system tables such as `SYSTAB_0' are not visible to *Note `mysqld': mysqld. However, you can examine the contents of system tables using *Note `NDB': mysql-cluster. API applications such as *Note `ndb_select_all': mysql-cluster-programs-ndb-select-all. (see *Note mysql-cluster-programs-ndb-select-all::).  File: manual.info, Node: mysql-cluster-programs-ndb-size-pl, Next: mysql-cluster-programs-ndb-waiter, Prev: mysql-cluster-programs-ndb-show-tables, Up: mysql-cluster-programs 17.4.23 `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 *Note `NDBCLUSTER': mysql-cluster. storage engine. Unlike the other utilities discussed in this section, it does not require access to a MySQL 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 MySQL 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.) * Previous to MySQL 5.1.18, *Note `ndb_size.pl': mysql-cluster-programs-ndb-size-pl. also required the `HTML::Template' module and an associated template file `share/mysql/ndb_size.tmpl'. Beginning with MySQL 5.1.18, `ndb_size.tmpl' is no longer needed (or included). * 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 MySQL Cluster program *Note `ndb_size.pl': mysql-cluster-programs-ndb-size-pl. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_size.pl': mysql-cluster-programs-ndb-size-pl.), see *Note mysql-cluster-program-options-common::. *`ndb_size.pl' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_size.pl': mysql-cluster-programs-ndb-size-pl. program Format Description Added / Removed ` --database=dbname ' The database or All MySQL 5.1 databases to examine; based releases accepts a comma-delimited list; the default is ALL (use all databases found on the server) ` --hostname[:port] ' Specify host and All MySQL 5.1 optional port as based releases host[:port] ` --socket=file ' Specify a socket to ADDED: NDB connect to 6.2.5 ` --user=string ' Specify a MySQL user name All MySQL 5.1 based releases ` --password=string ' Specify a MySQL user All MySQL 5.1 password based releases ` --format=string ' Set output format (text All MySQL 5.1 or HTML) based releases ` --excludetables=tbl_list ' Skip any tables in a All MySQL 5.1 comma-separated list of based releases tables ` --excludedbs=db_list ' Skip any databases in a All MySQL 5.1 comma-separated list of based releases databases ` --savequeries=file ' Saves all queries to the All MySQL 5.1 database into the file based releases specified ` --loadqueries=file ' Loads all queries from All MySQL 5.1 the file specified; does based releases not connect to a database ` --real_table_name=table ' Designates a table to ADDED: NDB handle unique index size 6.2.5 calculations * 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 (and possibly a port as well) can be specified using `--hostname'; the default is `localhost'. Beginning with MySQL Cluster NDB 6.3.49, MySQL Cluster NDB 7.0.32, and MySQL Cluster NDB 7.1.21, 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', `MaxNoOfUniqueHashIndexes', 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. *Note*: Prior to MySQL 5.1.23, MySQL Cluster NDB 6.2.5, and MySQL Cluster NDB 6.3.7, `ndb_size.pl' was invoked as shown here: perl ndb_size.pl DB_NAME HOSTNAME USERNAME PASSWORD > FILE_NAME.html For more information about this change, see Bug #28683 and Bug #28253.  File: manual.info, Node: mysql-cluster-programs-ndb-waiter, Next: mysql-cluster-program-options-common, Prev: mysql-cluster-programs-ndb-size-pl, Up: mysql-cluster-programs 17.4.24 `ndb_waiter' -- Wait for MySQL Cluster to Reach a Given Status ---------------------------------------------------------------------- *Note `ndb_waiter': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-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 MySQL Cluster native backup restoration program *Note `ndb_waiter': mysql-cluster-programs-ndb-waiter. Additional descriptions follow the table. For options common to most MySQL Cluster programs (including *Note `ndb_waiter': mysql-cluster-programs-ndb-waiter.), see *Note mysql-cluster-program-options-common::. *`ndb_waiter' Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options for the *Note `ndb_waiter': mysql-cluster-programs-ndb-waiter. program Format Description Added / Removed `--no-contact', Wait for cluster to All MySQL 5.1 reach NO CONTACT state based releases ` -n ' ` --not-started ' Wait for cluster to All MySQL 5.1 reach NOT STARTED state based releases ` --single-user ' Wait for cluster to All MySQL 5.1 enter single user mode based releases `--timeout=#', Wait this many seconds, All MySQL 5.1 then exit whether or not based releases ` -t ' cluster has reached desired state; default is 2 minutes (120 seconds) ` --nowait-nodes=list ' List of nodes not to be ADDED: NDB waited for. 6.2.1 `--wait-nodes=list', List of nodes to be ADDED: NDB waited for. 6.3.34, NDB ` -w ' 7.0.15, NDB 7.1.4 * Usage * ndb_waiter [-c CONNECT_STRING] * Additional Options * * `--no-contact', `-n' Instead of waiting for the `STARTED' state, *Note `ndb_waiter': mysql-cluster-programs-ndb-waiter. continues running until the cluster reaches `NO_CONTACT' status before exiting. * `--not-started' Instead of waiting for the `STARTED' state, *Note `ndb_waiter': mysql-cluster-programs-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. This option was added in MySQL Cluster NDB 6.2.1. * `--wait-nodes=LIST', `-w LIST' When this option is used, *Note `ndb_waiter': mysql-cluster-programs-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. This option was added in MySQL Cluster NDB 6.3.34, 7.0.15, and 7.1.4. Sample Output Shown here is the output from *Note `ndb_waiter': mysql-cluster-programs-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 *Note `ndb_waiter': mysql-cluster-programs-ndb-waiter. tries to connect to a management on `localhost', and reports `Connecting to mgmsrv at (null)'.  File: manual.info, Node: mysql-cluster-program-options-common, Prev: mysql-cluster-programs-ndb-waiter, Up: mysql-cluster-programs 17.4.25 Options Common to MySQL Cluster Programs -- Options Common to MySQL Cluster Programs -------------------------------------------------------------------------------------------- All MySQL Cluster programs accept the options described in this section, with the following exceptions: * *Note `mysqld': mysqld. * *Note `ndb_print_backup_file': mysql-cluster-programs-ndb-print-backup-file. * *Note `ndb_print_schema_file': mysql-cluster-programs-ndb-print-schema-file. * *Note `ndb_print_sys_file': mysql-cluster-programs-ndb-print-sys-file. Users of earlier MySQL Cluster versions should note that some of these options have been changed to make them consistent with one another as well as with *Note `mysqld': mysqld. You can use the `--help' option with any MySQL Cluster program--with the exception of *Note `ndb_print_backup_file': mysql-cluster-programs-ndb-print-backup-file, *Note `ndb_print_schema_file': mysql-cluster-programs-ndb-print-schema-file, and *Note `ndb_print_sys_file': mysql-cluster-programs-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 MySQL Cluster executables (except those noted previously in this section). *Common MySQL Cluster Program Options and Variables: MySQL 5.1, MySQL Cluster NDB 6.3-7.1* This table describes command-line options common to all MySQL Cluster programs Format Description Added / Removed `--help', Display help message and All MySQL 5.1 exit based releases `--usage', ` -? ' `--ndb-connectstring=connectstring',Set connection string All MySQL 5.1 for connecting to based releases `--connect-string=connectstring',ndb_mgmd. Syntax: [nodeid=;][host=][:]. ` -c ' Overrides entries specified in NDB_CONNECTSTRING or my.cnf. ` --ndb-mgmd-host=host[:port] ' Set the host (and port, All MySQL 5.1 if desired) for based releases connecting to the management server ` --ndb-nodeid=# ' Set node id for this node All MySQL 5.1 based releases ` --ndb-shm ' Allow for optimization REMOVED: NDB using shared memory 7.0.16, NDB connections where 7.1.5 available (was EXPERIMENTAL, later REMOVED) ` --ndb-optimized-node-selection Select nodes for All MySQL 5.1 ' transactions in a more based releases optimal way ` --character-sets-dir=path ' Directory where All MySQL 5.1 character sets are based releases ` --debug=options ' Enable output from debug All MySQL 5.1 calls. Can be used only based releases for versions compiled with debugging enabled ` --core-file ' Write core on errors All MySQL 5.1 (defaults to TRUE in based releases debug builds) `--version', Output version All MySQL 5.1 information and exit based releases ` -V ' For options specific to individual MySQL Cluster programs, see *Note mysql-cluster-programs::. See *Note mysql-cluster-program-options-mysqld::, for *Note `mysqld': mysqld. options relating to MySQL Cluster. * `--help', `--usage', `-?' Options for help *Command-Line `--help' Format* `--usage' `-?' Prints a short list with descriptions of the available command options. * `--character-sets-dir=NAME' Options for character-sets-dir *Command-Line `--character-sets-dir=path' Format* *Permitted Values* *Type* `file name' *Default* `' Tells the program where to find character set information. * `--ndb-connectstring=CONNECT_STRING', `--connect-string=CONNECT_STRING', `-c CONNECT_STRING' Options for ndb-connectstring *Command-Line `--ndb-connectstring=connectstring' Format* `--connect-string=connectstring' `-c' *Permitted Values* *Type* `string' *Default* `localhost:1186' This option takes a MySQL 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 *Note mysql-cluster-connection-strings::. * `--core-file' Options for core-file *Command-Line `--core-file' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' Write a core file if the program dies. The name and location of the core file are system-dependent. (For MySQL 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 MySQL 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]' Options for debug *Command-Line `--debug=options' Format* *Permitted Values* *Type* `string' *Default* `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 *Note `mysqld': mysqld. process. * `--ndb-mgmd-host=HOST[:PORT]' Options for ndb-mgmd-host *Command-Line `--ndb-mgmd-host=host[:port]' Format* *Option-File Format* `ndb-mgmd-host' *Permitted Values* *Type* `string' *Default* `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=#' Options for ndb-nodeid *Command-Line `--ndb-nodeid=#' Format* *Permitted Values* *Type* `numeric' *Default* `0' Sets this node's MySQL Cluster node ID. _The range of permitted values depends on the node's type (data, management, or API) and the MySQL Cluster software version_. See *Note mysql-cluster-limitations-limits::, for more information. * `--ndb-optimized-node-selection' Options for ndb-optimized-node-selection *Command-Line `--ndb-optimized-node-selection' Format* *Permitted Values* *Type* `boolean' *Default* `TRUE' Optimize selection of nodes for transactions. Enabled by default. * `--version', `-V' Options for version *Command-Line `--version' Format* `-V' Prints the MySQL Cluster version number of the executable. The version number is relevant because not all versions can be used together, and the MySQL 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 MySQL Cluster. See *Note mysql-cluster-rolling-restart::), for more information. * `--ndb-shm' Options for ndb-shm *Removed* 5.1.47-ndb-7.1.5 *Command-Line `--ndb-shm' Format* *Permitted Values* *Type* `boolean' *Default* `FALSE' In older versions of MySQL Cluster, this experimental option allowed the application to use shared memory for optimization when available. `--ndb-shm' was removed from all MySQL Cluster programs beginning with MySQL Cluster NDB 7.0.16 and MySQL Cluster 7.1.5.  File: manual.info, Node: mysql-cluster-management, Next: mysql-cluster-replication, Prev: mysql-cluster-programs, Up: mysql-cluster 17.5 Management of MySQL Cluster ================================ * Menu: * mysql-cluster-start-phases:: Summary of MySQL Cluster Start Phases * mysql-cluster-mgm-client-commands:: Commands in the MySQL Cluster Management Client * mysql-cluster-backup:: Online Backup of MySQL Cluster * mysql-cluster-mysqld:: MySQL Server Usage for MySQL Cluster * mysql-cluster-rolling-restart:: Performing a Rolling Restart of a MySQL Cluster * mysql-cluster-event-reports:: Event Reports Generated in MySQL Cluster * mysql-cluster-logs-ndb-messages:: MySQL Cluster Log Messages * mysql-cluster-single-user-mode:: MySQL Cluster Single User Mode * mysql-cluster-sql-statements:: Quick Reference: MySQL Cluster SQL Statements * mysql-cluster-ndbinfo:: The `ndbinfo' MySQL Cluster Information Database * mysql-cluster-security:: MySQL Cluster Security Issues * mysql-cluster-disk-data:: MySQL Cluster Disk Data Tables * mysql-cluster-online-add-node:: Adding MySQL Cluster Data Nodes Online * mysql-cluster-privilege-distribution:: Distributed MySQL Privileges for MySQL Cluster * mysql-cluster-ndb-api-statistics:: NDB API Statistics Counters and Variables Managing a MySQL Cluster involves a number of tasks, the first of which is to configure and start MySQL Cluster. This is covered in *Note mysql-cluster-configuration::, and *Note mysql-cluster-programs::. The next few sections cover the management of a running MySQL Cluster. For information about security issues relating to management and deployment of a MySQL Cluster, see *Note mysql-cluster-security::. There are essentially two methods of actively managing a running MySQL 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 *Note `ndbd': mysql-cluster-programs-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 *Note `SHOW ENGINE NDB STATUS': show-engine. statement. In MySQL Cluster NDB 7.1.1 and later, detailed information about cluster operations is available in real time through an SQL interface using the *Note `ndbinfo': mysql-cluster-ndbinfo. database. For more information, see *Note mysql-cluster-ndbinfo::. Beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, NDB statistics counters provide improved monitoring using the *Note `mysql': 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 MySQL 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. *Note `mysqld': 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 *Note `mysql': mysql. client from the output of a *Note `SHOW STATUS': show-status. statement, or by querying either the *Note `SESSION_STATUS': status-table. table or the *Note `GLOBAL_STATUS': status-table. 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 *Note `NDB': mysql-cluster. 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 MySQL Cluster. MySQL Enterprise Monitor can also be used to monitor MySQL Servers that are part of a MySQL Cluster deployment. MySQL Enterprise Monitor 2.3, added a MySQL Cluster advisor, including a set of graphs providing information on MySQL Cluster resources, and defining rules for alerts on key information from data nodes such as `DataMemory' usage. This information is made available to MySQL Enterprise Monitor 2.3 or later by any MySQL Server which is connected to the MySQL Cluster, using *Note `ndbinfo': mysql-cluster-ndbinfo. The advisor could be run against a single MySQL Server in the Cluster, or against a pair in order to provide a higher level of availability for the monitoring service. For more information, see the `MySQL Enterprise Monitor 2.3 Manual' (http://dev.mysql.com/doc/mysql-monitor/2.3/en/index.html). MySQL Cluster Manager provides an advanced command-line interface that simplifies many otherwise complex MySQL Cluster management tasks, such as starting, stopping, or restarting a MySQL 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 *Note `mysqld': mysqld. server options and variables relating to MySQL Cluster. MySQL Cluster Manager 1.1 provides support for adding data nodes online. See the `MySQL Cluster Manager 1.1 User Manual' (http://dev.mysql.com/doc/mysql-cluster-manager/1.1/en/), for more information.  File: manual.info, Node: mysql-cluster-start-phases, Next: mysql-cluster-mgm-client-commands, Prev: mysql-cluster-management, Up: mysql-cluster-management 17.5.1 Summary of MySQL Cluster Start Phases -------------------------------------------- This section provides a simplified outline of the steps involved when MySQL Cluster data nodes are started. More complete information can be found in MySQL Cluster Start Phases (http://dev.mysql.com/doc/ndbapi/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 *Note mysql-cluster-mgm-client-commands::). In MySQL Cluster NDB 7.1.1 and later, these start phases are also reported in the `start_phase' column of the *Note `ndbinfo.nodes': mysql-cluster-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 (*Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-ndbd. reports that this node is connected. This retention of the node ID is guarded by the connection between the node in question and *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. Normally, in the event of a problem with the node, the node disconnects from the management server, the socket used for the connection is closed, and the reserved node ID is freed. However, if a node is disconnected abruptly--for example, due to a hardware failure in one of the cluster hosts, or because of network issues--the normal closing of the socket by the operating system may not take place. In this case, the node ID continues to be reserved and not released until a TCP timeout occurs 10 or so minutes later. To take care of this problem, you can use `PURGE STALE SESSIONS'. Running this statement forces all reserved node IDs to be checked; any that are not being used by nodes actually connected to the cluster are then freed. Beginning with MySQL 5.1.11, timeout handling of node ID assignments is implemented. This performs the ID usage checks automatically after approximately 20 seconds, so that `PURGE STALE SESSIONS' should no longer be necessary in a normal Cluster start. 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/ndbapi/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 *Note `NDB': mysql-cluster. kernel blocks are started. MySQL 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.  File: manual.info, Node: mysql-cluster-mgm-client-commands, Next: mysql-cluster-backup, Prev: mysql-cluster-start-phases, Up: mysql-cluster-management 17.5.2 Commands in the MySQL 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. This is the primary administrative interface to a running cluster. Commands for the event logs are given in *Note mysql-cluster-event-reports::; commands for creating backups and restoring from them are provided in *Note mysql-cluster-backup::. `ndb_mgm' and MySQL Cluster Manager MySQL Cluster Manager handles starting and stopping processes and tracks their states internally, so it is not necessary to use *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. for these tasks for a MySQL Cluster that is under MySQL Cluster Manager control. it is recommended _not_ to use the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. command-line client that comes with the MySQL 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/cluster-manager/en/mcm-process-commands.html). The management client has the following basic commands. In the listing that follows, NODE_ID denotes either a database 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. * `SHOW' Displays information on the cluster's status. Possible node status values include `UNKNOWN', `NO_CONTACT', `NOT_STARTED', `STARTING', `STARTED', `SHUTTING_DOWN', and `RESTARTING'. Beginning with MySQL Cluster NDB 6.2.8 and MySQL Cluster NDB 6.3.6, the output from this command indicates when the cluster is in single user mode (status `SINGLE USER MODE'). Prior to MySQL Cluster NDB 7.0.26 and MySQL Cluster NDB 7.1.5, in a cluster having multiple management nodes, this command displayed information only for data nodes that were actually connected to the current management server; in addition, management servers could not find each other until all nodes had been started. Beginning with these versions, such issues are fixed (see Bug #12352191), and management nodes can be additionally be reported with status `RESUME' or `CONNECTED'. * `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 *Note `ndbd `--nostart'': mysql-cluster-programs-ndbd. or *Note `ndbd `-n'': mysql-cluster-programs-ndbd. * `NODE_ID STOP [-a] [-f]' Stops the data or management node identified by NODE_ID. Note that `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 *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndb_mgmd': mysql-cluster-programs-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, added in MySQL Cluster NDB 7.0.19 and MySQL Cluster NDB 7.1.8, 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 *Note `NDB': mysql-cluster. * `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 *Note `ndbd `--initial'': mysql-cluster-programs-ndbd. from the system shell. Note that 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 *Note `ndbd `--nostart'': mysql-cluster-programs-ndbd. or *Note `ndbd `-n'': mysql-cluster-programs-ndbd. 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, added in MySQL Cluster NDB 7.0.19 and MySQL Cluster NDB 7.1.8, 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). Beginning with MySQL Cluster NDB 6.2.8 and MySQL Cluster NDB 6.3.6, the output from this command 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 two 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) In MySQL Cluster NDB 7.1.1 and later, this information is also available from the *Note `ndbinfo.memoryusage': mysql-cluster-ndbinfo-memoryusage. table. 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. Prior to MySQL Cluster NDB 7.0.37 and MySQL Cluster NDB 7.1.26, `ALL REPORT BackupStatus' did not work correctly with multi-threaded data nodes. (Bug #15908907) The `REPORT' command was introduced in MySQL Cluster NDB 6.2.3 and MySQL Cluster NDB 6.3.0. * `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 a MySQL 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 *Note `mysqld': 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 MySQL Cluster node group and causes data nodes to join it. This command is used after adding new data nodes online to a MySQL 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 MySQL Cluster node group must have the same number of nodes). In other words, if the MySQL 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. This command was introduced in MySQL Cluster NDB 6.4.0. For more information, see *Note mysql-cluster-online-add-node::. * `DROP NODEGROUP NODEGROUP_ID' Drops the MySQL Cluster node group with the given NODEGROUP_ID. This command can be used to drop a node group from a MySQL 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.1.71-ndb-7.1.29, *no nodegroup*) Prior to MySQL Cluster NDB 7.0.4, the `SHOW' output was not updated correctly following `DROP NODEGROUP'. (Bug #43413) `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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. or the *Note `mysql': 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client, but before issuing any *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table. statements in the *Note `mysql': mysql. client. 2. After dropping all *Note `NDBCLUSTER': mysql-cluster. tables using *Note `DROP TABLE': drop-table. *Note `TRUNCATE TABLE': truncate-table. does not work for this purpose because this removes only the table data; the data nodes continue to store an *Note `NDBCLUSTER': mysql-cluster. table's definition until a *Note `DROP TABLE': drop-table. statement is issued that causes the table metadata to be dropped. `DROP NODEGROUP' was introduced in MySQL Cluster NDB 6.4.0. For more information, see *Note mysql-cluster-online-add-node::.  File: manual.info, Node: mysql-cluster-backup, Next: mysql-cluster-mysqld, Prev: mysql-cluster-mgm-client-commands, Up: mysql-cluster-management 17.5.3 Online Backup of MySQL Cluster ------------------------------------- * Menu: * mysql-cluster-backup-concepts:: MySQL Cluster Backup Concepts * mysql-cluster-backup-using-management-client:: Using The MySQL Cluster Management Client to Create a Backup * mysql-cluster-backup-configuration:: Configuration for MySQL Cluster Backups * mysql-cluster-backup-troubleshooting:: MySQL Cluster Backup Troubleshooting The next few sections describe how to prepare for and then to create a MySQL Cluster backup using the functionality for this purpose found in the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. management client. To distinguish this type of backup from a backup made using *Note `mysqldump': mysqldump, we sometimes refer to it as a `native' MySQL Cluster backup. (For information about the creation of backups with *Note `mysqldump': mysqldump, see *Note mysqldump::.) Restoration of MySQL Cluster backups is done using the *Note `ndb_restore': mysql-cluster-programs-ndb-restore. utility provided with the MySQL Cluster distribution; for information about *Note `ndb_restore': mysql-cluster-programs-ndb-restore. and its use in restoring MySQL Cluster backups, see *Note mysql-cluster-programs-ndb-restore::.  File: manual.info, Node: mysql-cluster-backup-concepts, Next: mysql-cluster-backup-using-management-client, Prev: mysql-cluster-backup, Up: mysql-cluster-backup 17.5.3.1 MySQL 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 above, BACKUP_ID stands for the backup identifier and NODE_ID is the unique identifier for the node creating the file.  File: manual.info, Node: mysql-cluster-backup-using-management-client, Next: mysql-cluster-backup-configuration, Prev: mysql-cluster-backup-concepts, Up: mysql-cluster-backup 17.5.3.2 Using The MySQL Cluster Management Client to Create a Backup ..................................................................... Before starting a backup, make sure that the cluster is properly configured for performing one. (See *Note 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. Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, backup IDs greater than 2147483648 (2^31) were not supported correctly. (Bug #43042) Beginning with these versions, the maximum possible backup ID is 4294967296 (2^32). *Note*: Prior to MySQL Cluster NDB 7.0.5, when starting a backup using *Note `ndb_mgm -e "START BACKUP"': mysql-cluster-programs-ndb-mgm, the BACKUP_ID was required. (Bug #31754) 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. Beginning with MySQL Cluster NDB 6.4.0, 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 MySQL 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 (*Note `ndb_mgm': mysql-cluster-programs-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 *Note `ndb_mgm': mysql-cluster-programs-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. To abort a backup that is already in progress: 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.  File: manual.info, Node: mysql-cluster-backup-configuration, Next: mysql-cluster-backup-troubleshooting, Prev: mysql-cluster-backup-using-management-client, Up: mysql-cluster-backup 17.5.3.3 Configuration for MySQL 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.  File: manual.info, Node: mysql-cluster-backup-troubleshooting, Prev: mysql-cluster-backup-configuration, Up: mysql-cluster-backup 17.5.3.4 MySQL 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. *Note `NDB': mysql-cluster. does not support repeatable reads, which can cause problems with the restoration process. Although the backup process is `hot', restoring a MySQL 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.  File: manual.info, Node: mysql-cluster-mysqld, Next: mysql-cluster-rolling-restart, Prev: mysql-cluster-backup, Up: mysql-cluster-management 17.5.4 MySQL Server Usage for MySQL Cluster ------------------------------------------- *Note `mysqld': mysqld. is the traditional MySQL server process. To be used with MySQL Cluster, *Note `mysqld': mysqld. needs to be built with support for the *Note `NDBCLUSTER': mysql-cluster. 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 `configure' with one of the options to enable *Note `NDBCLUSTER': mysql-cluster. storage engine support: * `--with-plugins=ndbcluster' * `--with-plugins=max' * `--with-plugins=max-no-innodb' (`--with-ndbcluster' also works to enable *Note `NDBCLUSTER': mysql-cluster. support, but is deprecated and so produces a `configure' warning as of MySQL 5.1.9.) For information about other MySQL server options and variables relevant to MySQL Cluster in addition to those discussed in this section, see *Note mysql-cluster-options-variables::. If the *Note `mysqld': mysqld. binary has been built with Cluster support, the *Note `NDBCLUSTER': mysql-cluster. 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 *Note `mysqld': 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 *Note `NDBCLUSTER': mysql-cluster. storage engine enabled is to issue the *Note `SHOW ENGINES': show-engines. statement in the MySQL Monitor (*Note `mysql': mysql.). You should see the value `YES' as the `Support' value in the row for *Note `NDBCLUSTER': mysql-cluster. If you see `NO' in this row or if there is no such row displayed in the output, you are not running an *Note `NDB': mysql-cluster.-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 *Note `mysqld': mysqld. parameter `ndb-connectstring' is used to specify the connection string either on the command line when starting *Note `mysqld': 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 *Note 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 *Note `mysqld': 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 *Note `mysql': mysql. client whether a MySQL server is connected to the cluster using *Note `SHOW PROCESSLIST': 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 a MySQL Cluster, the *Note `mysqld': mysqld. process must be started with _both_ the options `--ndbcluster' and `--ndb-connectstring' (or their equivalents in `my.cnf'). If *Note `mysqld': mysqld. is started with only the `--ndbcluster' option, or if it is unable to contact the cluster, it is not possible to work with *Note `NDB': mysql-cluster. 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 *Note `NDB': mysql-cluster. tables while the SQL node is not connected to the cluster. If you wish to create tables using a different storage engine while the *Note `mysqld': mysqld. process is not participating in a MySQL Cluster, you must restart the server _without_ the `--ndbcluster' option.  File: manual.info, Node: mysql-cluster-rolling-restart, Next: mysql-cluster-event-reports, Prev: mysql-cluster-mysqld, Up: mysql-cluster-management 17.5.5 Performing a Rolling Restart of a MySQL Cluster ------------------------------------------------------ This section discusses how to perform a _rolling restart_ of a MySQL 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. MySQL Cluster software upgrade or downgrade To upgrade the cluster to a newer version of the MySQL 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 MySQL Cluster). Change on node host To make changes in the hardware or operating system on which one or more MySQL 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 (*Note `ndbd': mysql-cluster-programs-ndbd, or possibly *Note `ndbmtd': mysql-cluster-programs-ndbmtd. in MySQL Cluster NDB 7.0 and later) with the `--initial' option, which forces the data node to clear its file system and to reload all MySQL Cluster data and metadata from the other data nodes. * Create a backup using the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client `BACKUP' command prior to performing the restart. Following the upgrade, restore the node or nodes using *Note `ndb_restore': mysql-cluster-programs-ndb-restore. See *Note mysql-cluster-backup::, and *Note mysql-cluster-programs-ndb-restore::, for more information. * Use *Note `mysqldump': mysqldump. to create a backup prior to the upgrade; afterward, restore the dump using *Note `LOAD DATA INFILE': load-data. Resource Recovery To free memory previously allocated to a table by successive *Note `INSERT': insert. and *Note `DELETE': delete. operations, for re-use by other MySQL Cluster tables. The process for performing a rolling restart may be generalized as follows: 1. Stop all cluster management nodes (*Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. processes), reconfigure them, then restart them. (If there are multiple management servers and you are using MySQL Cluster NDB 7.0.8 or later, see *Note mysql-cluster-rolling-restart-multiple-ndb-mgmd::.) 2. Stop, reconfigure, then restart each cluster data node (*Note `ndbd': mysql-cluster-programs-ndbd. process) in turn. 3. Stop, reconfigure, then restart each cluster SQL node (*Note `mysqld': mysqld. process) in turn. The specifics for implementing a given rolling upgrade depend upon the changes being made. A more detailed view of the process is presented here: MySQL Cluster Rolling Restarts (By Type) In the previous diagram, the *Stop* and *Start* steps indicate that the process must be stopped completely using a shell command (such as *Note `kill': kill. on most Unix systems) or the management client `STOP' command, then started again from a system shell by invoking the *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. executable as appropriate. On Windows (MySQL Cluster NDB 7.1.3 and later), you can also use the system `NET START' and `NET STOP' commands or the Windows Service Manager to start and stop nodes which have been installed as Windows services (see *Note mysql-cluster-install-windows-service::). *Restart* indicates that the process may be restarted using the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. management client `RESTART' command (see *Note mysql-cluster-mgm-client-commands::). Prior to MySQL Cluster NDB 6.3.29 and MySQL Cluster NDB 7.0.10 When performing an upgrade or downgrade of the cluster software, you must upgrade or downgrade the management nodes first, then the data nodes, and finally the SQL nodes. Doing so in any other order may leave the cluster in an unusable state. MySQL Cluster NDB 6.3.29 and later; MySQL Cluster NDB 7.0.10 and later MySQL Cluster supports a more flexible order for upgrading the cluster nodes. When upgrading a cluster running MySQL Cluster NDB 6.3.29 or later, or a cluster that is running MySQL Cluster NDB 7.0.10 or later, 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 MySQL Cluster releases is neither intended nor supported for constant, 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. * For MySQL Cluster NDB 6.3, the ability to upgrade API nodes in any order relative to upgrading management nodes and data nodes is supported only for MySQL Cluster NDB 6.3.29 and later; for MySQL Cluster NDB 7.0, it supported only for MySQL Cluster NDB 7.0.10 and later. This means that, if you are upgrading from a MySQL Cluster NDB 6.3 release to a MySQL Cluster NDB 7.0 release, the `old' *Note `NDB': mysql-cluster. engine version must be 6.3.29 or later, and the `new' *Note `NDB': mysql-cluster. engine version must be 7.0.10 or later. * When upgrading the cluster from a MySQL Cluster NDB 6.3 release to a MySQL Cluster NDB 7.0 release: Once you have started upgrading the API nodes, you should not perform DDL operations until all management nodes and data nodes have been upgraded. DML operations should be unaffected, and can continue while the upgrade is in progress. However, it is possible to perform DDL from an `old' (NDB 6.3 version) API node as long as the master data node is also running the `old' version of MySQL Cluster. You should keep in mind that a data node restart could result in the master node running a `new' (NDB 7.0 version) binary while one or more data nodes are still using the `old' (NDB 6.3) version; in this situation, no DDL can be performed from _any_ API node, because the master data node is no longer using an NDB 6.3 binary, but the cluster still contains nodes which are not yet using NDB 7.0. For this reason, we recommend that you avoid performing DDL at any time while the upgrade is in progress. * 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 MySQL Cluster in general.) See also Bug #48528 and Bug #49163. Rolling restarts with multiple management servers (MySQL Cluster NDB 7.0.8 and later) A change in MySQL Cluster NDB 7.0.8 in the way in which management nodes obtain configuration data makes it necessary to alter the procedure previously outlined, when performing a rolling restart of a MySQL Cluster with multiple management nodes. (Previously, a management node checked only its own configuration cache, but in MySQL Cluster NDB 7.0.8 and later, *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. also 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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. to reread its configuration file, perform the following steps: 1. Stop all MySQL Cluster *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. processes. 2. Update all `config.ini' files. 3. Start a single *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. with `--reload', `--initial', or both options as desired. 4. If you started the first *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. with the `--initial' option, you must also start any remaining *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. processes using `--initial'. Regardless of any other options used when starting the first *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd, you should not start any remaining *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. processes after the first one using `--reload'. 5. Complete the rolling restarts of the data nodes and API nodes as normal. See also Bug #45495 and Bug #46488. MySQL Cluster NDB 7.0.24 and later; MySQL Cluster NDB 7.1.13 and later When performing a rolling restart to update the cluster's configuration, you can use the `config_generation' column of the *Note `ndbinfo.nodes': mysql-cluster-ndbinfo-nodes. table to keep track of which data nodes have been successfully restarted with the new configuration. See *Note mysql-cluster-ndbinfo-nodes::.  File: manual.info, Node: mysql-cluster-event-reports, Next: mysql-cluster-logs-ndb-messages, Prev: mysql-cluster-rolling-restart, Up: mysql-cluster-management 17.5.6 Event Reports Generated in MySQL Cluster ----------------------------------------------- * Menu: * mysql-cluster-logging-management-commands:: MySQL Cluster Logging Management Commands * mysql-cluster-log-events:: MySQL Cluster Log Events * mysql-cluster-log-statistics:: Using `CLUSTERLOG STATISTICS' in the MySQL Cluster Management Client In this section, we discuss the types of event logs provided by MySQL Cluster, and the types of events that are logged. MySQL 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 same directory where the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. binary resides. 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 *Note 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 1 to 15 inclusive, where 1 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.1.71-ndb-7.1.29 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.1.71-ndb-7.1.29 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.1.71-ndb-7.1.29 2007-01-26 19:39:42 [MgmSrvr] INFO -- Node 4: Node 9: API 5.1.71-ndb-7.1.29 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.  File: manual.info, Node: mysql-cluster-logging-management-commands, Next: mysql-cluster-log-events, Prev: mysql-cluster-event-reports, Up: mysql-cluster-event-reports 17.5.6.1 MySQL Cluster Logging Management Commands .................................................. *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. supports a number of management commands related to the cluster log. In the listing that follows, NODE_ID denotes either a database 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 that events are reported per data node, and that the threshold can be set to different values on different nodes. This table lists cluster log categories and provides the default threshold setting (for all data nodes). 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 *Note 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. This table lists event severity level values along with the event severity and a description. 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 *Note `NDBCLUSTER': mysql-cluster. 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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd, per subscriber basis. This means that, in a MySQL Cluster with multiple management servers, using a `CLUSTERLOG' command in an instance of *Note `ndb_mgm': mysql-cluster-programs-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.  File: manual.info, Node: mysql-cluster-log-events, Next: mysql-cluster-log-statistics, Prev: mysql-cluster-logging-management-commands, Up: mysql-cluster-event-reports 17.5.6.2 MySQL 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. This table lists events that are associated with connections between cluster nodes. In order, the table shows the event, priority, severity level, and provides a description. Event PrioritySeverityDescription Level data nodes connected 8 `INFO' Data nodes connected data nodes disconnected 8 `INFO' Data nodes disconnected Communication closed 8 `INFO' SQL node or data node connection closed Communication opened 8 `INFO' SQL node or data node connection opened *`CHECKPOINT' Events* The logging messages shown here are associated with checkpoints. This table lists events that are associated with checkpoints. In order, the table shows the event, priority, severity level, and provides a description. Event PrioritySeverityDescription Level LCP stopped in calc keep 0 `ALERT' LCP stopped GCI Local checkpoint 11 `INFO' LCP on a fragment has been fragment completed completed Global checkpoint 10 `INFO' GCP finished completed Global checkpoint started 9 `INFO' Start of GCP: REDO log is written to disk Local checkpoint 8 `INFO' LCP completed normally completed Local checkpoint started 7 `INFO' Start of LCP: data written to disk *`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. This table lists events that are generated in response to the startup of a node or cluster and events that provide information about startup progress, including information about logging activities. In order, the table shows the event, priority, severity level, and provides a description. Event PrioritySeverityDescription Level Internal start signal 15 `INFO' Blocks received after received STTORRY completion of restart New REDO log started 10 `INFO' GCI keep X, newest restorable GCI Y New log started 10 `INFO' Log part X, start MB Y, stop MB Z Node has been refused 8 `INFO' Node cannot be included in for inclusion in the cluster due to cluster misconfiguration, inability to establish communication, or other problem data node neighbors 8 `INFO' Shows neighboring data nodes data node start phase X 4 `INFO' A data node start phase has completed been completed Node has been 3 `INFO' Displays the node, managing successfully included node, and dynamic ID into the cluster data node start phases 1 `INFO' NDB Cluster nodes starting initiated data node all start 1 `INFO' NDB Cluster nodes started phases completed data node shutdown 1 `INFO' Shutdown of data node has initiated commenced data node shutdown 1 `INFO' Unable to shut down data node aborted normally *`NODERESTART' Events* The following events are generated when restarting a node and relate to the success or failure of the node restart process. This table lists events that are generated when restarting a node and that relate to the success or failure of the node restart process. In order, the table shows the event, priority, severity level, and provides a description. Event PrioritySeverityDescription Level Node failure phase 8 `ALERT' Reports completion of node completed failure phases Node has failed, node 8 `ALERT' Reports that a node has failed state was X Report arbitrator results 2 `ALERT' There are eight different possible results for arbitration attempts: * 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 Completed copying a 10 `INFO' fragment Completed copying of 8 `INFO' dictionary information Completed copying 8 `INFO' distribution information Starting to copy 8 `INFO' fragments Completed copying all 8 `INFO' fragments GCP takeover started 7 `INFO' GCP takeover completed 7 `INFO' LCP takeover started 7 `INFO' LCP takeover completed 7 `INFO' (state = X) Report whether an 6 `INFO' There are seven different arbitrator is found or possible outcomes when seeking not an arbitrator: * 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 [state=Y] *`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. This table lists events that are of a statistical nature. In order, the table shows the event, priority, severity level, and provides a description. Event PrioritySeverityDescription Level Report job scheduling 9 `INFO' Mean internal job scheduling statistics statistics Sent number of bytes 9 `INFO' Mean number of bytes sent to node X Received # of bytes 9 `INFO' Mean number of bytes received from node X Report transaction 8 `INFO' Numbers of: transactions, statistics commits, reads, simple reads, writes, concurrent operations, attribute information, and aborts Report operations 8 `INFO' Number of operations Report table create 7 `INFO' Memory usage 5 `INFO' Data and index memory usage (80%, 90%, and 100%) *`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. This table lists events that relate to cluster errors and warnings. In order, the table shows the event, priority, severity, and provides a description. Event PrioritySeverityDescription Dead due to missed 8 `ALERT' Node X declared `dead' due to heartbeat missed heartbeat Transporter errors 2 ERROR Transporter warnings 8 `WARNING' Missed heartbeats 8 `WARNING'Node X missed heartbeat #Y General warning events 2 `WARNING' *`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. This table lists events that provide general information about the state of the cluster and about activities associated with cluster maintenance, such as logging and heartbeat transmission. In order, the table shows the event, priority, severity, and provides a description. Event PrioritySeverityDescription Sent heartbeat 12 `INFO' Heartbeat sent to node X Create log bytes 11 `INFO' Log part, log file, MB General information 2 `INFO' events  File: manual.info, Node: mysql-cluster-log-statistics, Prev: mysql-cluster-log-events, Up: mysql-cluster-event-reports 17.5.6.3 Using `CLUSTERLOG STATISTICS' in the MySQL Cluster Management Client ............................................................................. The *Note `NDB': mysql-cluster. 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 * (_Beginning with MySQL Cluster NDB 6.3.4_:) 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. This is a subset of `Read count'. Because the value of `Simple read count' is incremented at a different point in time from `Read count', it can lag behind `Read count' slightly, so it is conceivable that `Simple read count' is not equal to `Read count' for a given reporting interval, even if all reads made during that time were in fact simple reads. * `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 *Note 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 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 *Note `ndbd': mysql-cluster-programs-ndbd. process has a scheduler which also provides useful metrics relating to the performance of a MySQL 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 *Note `NDB': mysql-cluster. 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 MySQL Cluster. For more information about MySQL Cluster management client commands relating to logging and reporting, see *Note mysql-cluster-logging-management-commands::.  File: manual.info, Node: mysql-cluster-logs-ndb-messages, Next: mysql-cluster-single-user-mode, Prev: mysql-cluster-event-reports, Up: mysql-cluster-management 17.5.7 MySQL Cluster Log Messages --------------------------------- * Menu: * mysql-cluster-logs-cluster-log:: MySQL Cluster: Messages in the Cluster Log * mysql-cluster-ndb-transporter-errors:: MySQL Cluster: `NDB' Transporter Errors 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 *Note `NDB': mysql-cluster. transporter errors.  File: manual.info, Node: mysql-cluster-logs-cluster-log, Next: mysql-cluster-ndb-transporter-errors, Prev: mysql-cluster-logs-ndb-messages, Up: mysql-cluster-logs-ndb-messages 17.5.7.1 MySQL Cluster: Messages in the Cluster Log ................................................... The following table lists the most common *Note `NDB': mysql-cluster. cluster log messages. For information about the cluster log, log events, and event types, see *Note 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. This table lists the most common *Note `NDB': mysql-cluster. cluster log messages. The first column provides the log message and a description of the log message. The second column lists the corresponding event name, event type, priority, and severity. Log Message Event Name `Node MGM_NODE_ID: Node DATA_NODE_ID `Connected' Connected' Event Type Description `Connection' The data node having node ID NODE_ID has connected to the management server (node Priority MGM_NODE_ID). 8 Severity `INFO' Log Message Event Name `Node MGM_NODE_ID: Node DATA_NODE_ID `Disconnected' Disconnected' Event Type Description `Connection' The data node having node ID DATA_NODE_ID has disconnected from the management Priority server (node MGM_NODE_ID). 8 Severity `ALERT' Log Message Event Name `Node DATA_NODE_ID: Communication to Node `CommunicationClosed' API_NODE_ID closed' Event Type Description `Connection' The API node or SQL node having node ID API_NODE_ID is no longer communicating Priority with data node DATA_NODE_ID. 8 Severity `INFO' Log Message Event Name `Node DATA_NODE_ID: Communication to Node `CommunicationOpened' API_NODE_ID opened' Event Type Description `Connection' The API node or SQL node having node ID API_NODE_ID is now communicating with data Priority node DATA_NODE_ID. 8 Severity `INFO' Log Message Event Name `Node MGM_NODE_ID: Node API_NODE_ID: API `ConnectedApiVersion' VERSION' Event Type Description `Connection' The API node having node ID API_NODE_ID has connected to management node Priority MGM_NODE_ID using *Note `NDB': mysql-cluster. API version VERSION 8 (generally the same as the MySQL version number). Severity `INFO' Log Message Event Name `Node NODE_ID: Global checkpoint GCI `GlobalCheckpointStarted' started' Event Type Description `Checkpoint' A global checkpoint with the ID GCI has been started; node NODE_ID is the master Priority responsible for this global checkpoint. 9 Severity `INFO' Log Message Event Name `Node NODE_ID: Global checkpoint GCI `GlobalCheckpointCompleted' completed' Event Type Description `Checkpoint' The global checkpoint having the ID GCI has been completed; node NODE_ID was the Priority master responsible for this global checkpoint. 10 Severity `INFO' Log Message Event Name `Node NODE_ID: Local checkpoint LCP `LocalCheckpointStarted' started. Keep GCI = CURRENT_GCI oldest restorable GCI = OLD_GCI' Event Type Description `Checkpoint' The local checkpoint having sequence ID Priority LCP has been started on node NODE_ID. The most recent GCI that can be used has the 7 index CURRENT_GCI, and the oldest GCI from which the cluster can be restored has the Severity index OLD_GCI. `INFO' Log Message Event Name `Node NODE_ID: Local checkpoint LCP `LocalCheckpointCompleted' completed' Event Type Description `Checkpoint' The local checkpoint having sequence ID LCP on node NODE_ID has been completed. Priority 8 Severity `INFO' Log Message Event Name `Node NODE_ID: Local Checkpoint stopped in `LCPStoppedInCalcKeepGci' CALCULATED_KEEP_GCI' Event Type Description `Checkpoint' The node was unable to determine the most recent usable GCI. Priority 0 Severity `ALERT' Log Message Event Name `Node NODE_ID: Table ID = TABLE_ID, `LCPFragmentCompleted' fragment ID = FRAGMENT_ID has completed LCP on Node NODE_ID maxGciStarted: Event Type STARTED_GCI maxGciCompleted: COMPLETED_GCI' `Checkpoint' Description Priority A table fragment has been checkpointed to disk on node NODE_ID. The GCI in progress 11 has the index STARTED_GCI, and the most recent GCI to have been completed has the Severity index COMPLETED_GCI. `INFO' Log Message Event Name `Node NODE_ID: ACC Blocked NUM_1 and TUP `UndoLogBlocked' Blocked NUM_2 times last second' Event Type Description `Checkpoint' Undo logging is blocked because the log buffer is close to overflowing. Priority 7 Severity `INFO' Log Message Event Name `Node NODE_ID: Start initiated VERSION' `NDBStartStarted' Description Event Type Data node NODE_ID, running *Note `NDB': `StartUp' mysql-cluster. version VERSION, is beginning its startup process. Priority 1 Severity `INFO' Log Message Event Name `Node NODE_ID: Started VERSION' `NDBStartCompleted' Description Event Type Data node NODE_ID, running *Note `NDB': `StartUp' mysql-cluster. version VERSION, has started successfully. Priority 1 Severity `INFO' Log Message Event Name `Node NODE_ID: STTORRY received after `STTORRYRecieved' restart finished' Event Type Description `StartUp' The node has received a signal indicating that a cluster restart has completed. Priority 15 Severity `INFO' Log Message Event Name `Node NODE_ID: Start phase PHASE completed `StartPhaseCompleted' (TYPE)' Event Type Description `StartUp' The node has completed start phase PHASE of a TYPE start. For a listing of start Priority phases, see *Note mysql-cluster-start-phases::. (TYPE is 4 one of `initial', `system', `node', `initial node', or `'.) Severity `INFO' Log Message Event Name `Node NODE_ID: CM_REGCONF president = `CM_REGCONF' PRESIDENT_ID, own Node = OWN_ID, our dynamic id = DYNAMIC_ID' Event Type Description `StartUp' Node PRESIDENT_ID has been selected as Priority `president'. OWN_ID and DYNAMIC_ID should always be the same as the ID (NODE_ID) of 3 the reporting node. Severity `INFO' Log Message Event Name `Node NODE_ID: CM_REGREF from Node `CM_REGREF' PRESIDENT_ID to our Node NODE_ID. Cause = CAUSE' Event Type Description `StartUp' The reporting node (ID NODE_ID) was unable Priority to accept node PRESIDENT_ID as president. The CAUSE of the problem is given as one of 8 `Busy', `Election with wait = false', `Not president', `Election without selecting new Severity candidate', or `No such cause'. `INFO' Log Message Event Name `Node NODE_ID: We are Node OWN_ID with `FIND_NEIGHBOURS' dynamic ID DYNAMIC_ID, our left neighbor is Node ID_1, our right is Node ID_2' Event Type Description `StartUp' The node has discovered its neighboring Priority nodes in the cluster (node ID_1 and node ID_2). NODE_ID, OWN_ID, and DYNAMIC_ID 8 should always be the same; if they are not, this indicates a serious Severity misconfiguration of the cluster nodes. `INFO' Log Message Event Name `Node NODE_ID: TYPE shutdown initiated' `NDBStopStarted' Description Event Type The node has received a shutdown signal. `StartUp' The TYPE of shutdown is either `Cluster' or `Node'. Priority 1 Severity `INFO' Log Message Event Name `Node NODE_ID: Node shutdown completed '[`, `NDBStopCompleted' ACTION'] [`Initiated by signal SIGNAL.'] Event Type Description `StartUp' The node has been shut down. This report may include an ACTION, which if present is Priority one of `restarting', `no start', or `initial'. The report may also include a 1 reference to an *Note `NDB': mysql-cluster. Protocol SIGNAL; for Severity possible signals, refer to Operations and Signals `INFO' (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-ndb-protocol-operations-signals.html). Log Message Event Name `Node NODE_ID: Forced node shutdown `NDBStopForced' completed '[`, action']`.' [`Occured during startphase START_PHASE.'] [` Event Type Initiated by SIGNAL.'] [`Caused by error ERROR_CODE: `StartUp' 'ERROR_MESSAGE(ERROR_CLASSIFICATION). ERROR_STATUS'.' [`(extra info Priority EXTRA_CODE)']] 1 Description Severity The node has been forcibly shut down. The ACTION (one of `restarting', `no start', `ALERT' or `initial') subsequently being taken, if any, is also reported. If the shutdown occurred while the node was 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/ndbapi/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 *Note `NDB': mysql-cluster. error messages and classifications, see MySQL Cluster API Errors (http://dev.mysql.com/doc/ndbapi/en/ndb-errors.html). Log Message Event Name `Node NODE_ID: Node shutdown aborted' `NDBStopAborted' Description Event Type The node shutdown process was aborted by `StartUp' the user. Priority 1 Severity `INFO' Log Message Event Name `Node NODE_ID: StartLog: [GCI Keep: `StartREDOLog' KEEP_POS LastCompleted: LAST_POS NewestRestorable: RESTORE_POS]' Event Type Description `StartUp' This reports global checkpoints referenced Priority during a node start. The redo log prior to KEEP_POS is dropped. LAST_POS is the last 4 global checkpoint in which data node the participated; RESTORE_POS is the global Severity checkpoint which is actually used to restore all data nodes. `INFO' Log Message Event Name STARTUP_MESSAGE [_Listed separately; see `StartReport' below._] Event Type Description `StartUp' There are a number of possible startup messages that can be logged under Priority different circumstances. 4 Severity `INFO' Log Message Event Name `Node NODE_ID: Node restart completed copy `NR_CopyDict' of dictionary information' Event Type Description `NodeRestart' Copying of data dictionary information to the restarted node has been completed. Priority 8 Severity `INFO' Log Message Event Name `Node NODE_ID: Node restart completed copy `NR_CopyDistr' of distribution information' Event Type Description `NodeRestart' Copying of data distribution information to the restarted node has been completed. Priority 8 Severity `INFO' Log Message Event Name `Node NODE_ID: Node restart starting to `NR_CopyFragsStarted' copy the fragments to Node NODE_ID' Event Type Description `NodeRestart' Copy of fragments to starting data node NODE_ID has begun Priority 8 Severity `INFO' Log Message Event Name `Node NODE_ID: Table ID = TABLE_ID, `NR_CopyFragDone' fragment ID = FRAGMENT_ID have been copied to Node NODE_ID' Event Type Description `NodeRestart' Fragment FRAGMENT_ID from table TABLE_ID Priority has been copied to data node NODE_ID 10 Severity `INFO' Log Message Event Name `Node NODE_ID: Node restart completed `NR_CopyFragsCompleted' copying the fragments to Node NODE_ID' Event Type Description `NodeRestart' Copying of all table fragments to restarting data node NODE_ID has been Priority completed 8 Severity `INFO' Log Message Event Name Any of the following: `NodeFailCompleted' 1. `Node NODE_ID: Node NODE1_ID completed Event Type failure of Node NODE2_ID' `NodeRestart' 2. `All nodes completed failure of Node NODE_ID' Priority 3. `Node failure of NODE_IDBLOCK 8 completed' Description Severity One of the following (each corresponding `ALERT' to the same-numbered message listed above): 1. Data node NODE1_ID has detected the failure of data node NODE2_ID 2. All (remaining) data nodes have detected the failure of data node NODE_ID 3. The failure of data node NODE_ID has been detected in the BLOCK*Note `NDB': mysql-cluster. kernel block, where block is 1 of `DBTC', `DBDICT', `DBDIH', or `DBLQH'; for more information, see `NDB' Kernel Blocks (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-kernel-blocks.html) Log Message Event Name `Node MGM_NODE_ID: Node DATA_NODE_ID has `NODE_FAILREP' failed. The Node state at failure was STATE_CODE' Event Type Description `NodeRestart' A data node has failed. Its state at the Priority time of failure is described by an arbitration state code STATE_CODE: possible 8 state code values can be found in the file `include/kernel/signaldata/ArbitSignalData.hpp'.Severity `ALERT' Log Message Event Name `President restarts arbitration thread `ArbitState' [state=STATE_CODE]' or `Prepare arbitrator node NODE_ID [ticket=TICKET_ID]' or Event Type `Receive arbitrator node NODE_ID [ticket=TICKET_ID]' or `Started arbitrator `NodeRestart' node NODE_ID [ticket=TICKET_ID]' or `Lost arbitrator node NODE_ID - process failure Priority [state=STATE_CODE]' or `Lost arbitrator node NODE_ID - process exit 6 [state=STATE_CODE]' or `Lost arbitrator node NODE_ID - ERROR_MESSAGE Severity [state=STATE_CODE]' `INFO' Description This is a report on the current state and progress of arbitration in the cluster. NODE_ID is the node ID of the management node or SQL node selected as the arbitrator. STATE_CODE is an arbitration state code, as found in `include/kernel/signaldata/ArbitSignalData.hpp'. When an error has occurred, an ERROR_MESSAGE, also defined in `ArbitSignalData.hpp', is provided. TICKET_ID is a unique identifier 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. Log Message Event Name `Arbitration check lost - less than 1/2 `ArbitResult' nodes left' or `Arbitration check won - all node groups and more than 1/2 nodes Event Type left' or `Arbitration check won - node group majority' or `Arbitration check lost `NodeRestart' - missing node group' or `Network partitioning - arbitration required' or Priority `Arbitration won - positive reply from node NODE_ID' or `Arbitration lost - negative 2 reply from node NODE_ID' or `Network partitioning - no arbitrator available' or Severity `Network partitioning - no arbitrator configured' or `Arbitration failure - `ALERT' ERROR_MESSAGE [state=STATE_CODE]' Description This message reports on the result of arbitration. In the event of arbitration failure, an ERROR_MESSAGE and an arbitration STATE_CODE are provided; definitions for both of these are found in `include/kernel/signaldata/ArbitSignalData.hpp'. Log Message Event Name `Node NODE_ID: GCP Take over started' `GCP_TakeoverStarted' Description Event Type This node is attempting to assume `NodeRestart' responsibility for the next global checkpoint (that is, it is becoming the Priority master node) 7 Severity `INFO' Log Message Event Name `Node NODE_ID: GCP Take over completed' `GCP_TakeoverCompleted' Description Event Type This node has become the master, and has `NodeRestart' assumed responsibility for the next global checkpoint Priority 7 Severity `INFO' Log Message Event Name `Node NODE_ID: LCP Take over started' `LCP_TakeoverStarted' Description Event Type This node is attempting to assume `NodeRestart' responsibility for the next set of local checkpoints (that is, it is becoming the Priority master node) 7 Severity `INFO' Log Message Event Name `Node NODE_ID: LCP Take over completed' `LCP_TakeoverCompleted' Description Event Type This node has become the master, and has `NodeRestart' assumed responsibility for the next set of local checkpoints Priority 7 Severity `INFO' Log Message Event Name `Node NODE_ID: Trans. Count = `TransReportCounters' TRANSACTIONS, Commit Count = COMMITS, Read Count = READS, Simple Read Count = Event Type SIMPLE_READS, Write Count = WRITES, AttrInfo Count = ATTRINFO_OBJECTS, `Statistic' Concurrent Operations = CONCURRENT_OPERATIONS, Abort Count = Priority ABORTS, Scans = SCANS, Range scans = RANGE_SCANS' 8 Description Severity This report of transaction activity is `INFO' given approximately once every 10 seconds Log Message Event Name `Node NODE_ID: Operations=OPERATIONS' `OperationReportCounters' Description Event Type Number of operations performed by this `Statistic' node, provided approximately once every 10 seconds Priority 8 Severity `INFO' Log Message Event Name `Node NODE_ID: Table with ID = TABLE_ID `TableCreated' created' Event Type Description `Statistic' A table having the table ID shown has been created Priority 7 Severity `INFO' Log Message Event Name `Node NODE_ID: Mean loop Counter in doJob `JobStatistic' last 8192 times = COUNT' Event Type Description `Statistic' Priority 9 Severity `INFO' Log Message Event Name `Mean send size to Node = NODE_ID last `SendBytesStatistic' 4096 sends = BYTES bytes' Event Type Description `Statistic' This node is sending an average of BYTES bytes per send to node NODE_ID Priority 9 Severity `INFO' Log Message Event Name `Mean receive size to Node = NODE_ID last `ReceiveBytesStatistic' 4096 sends = BYTES bytes' Event Type Description `Statistic' This node is receiving an average of BYTES of data each time it receives data from Priority node NODE_ID 9 Severity `INFO' Log Message Event Name `Node NODE_ID: Data usage is `MemoryUsage' DATA_MEMORY_PERCENTAGE% (DATA_PAGES_USED 32K pages of total DATA_PAGES_TOTAL)' / Event Type `Node NODE_ID: Index usage is INDEX_MEMORY_PERCENTAGE% (INDEX_PAGES_USED `Statistic' 8K pages of total INDEX_PAGES_TOTAL) ' Priority Description 5 This report is generated when a `DUMP 1000' command is issued in the cluster Severity management client; for more information, see `DUMP 1000' `INFO' (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-dump-command-1000.html), in MySQL Cluster Internals (http://dev.mysql.com/doc/ndbapi/en/ndb-internals.html) Log Message Event Name `Node NODE1_ID: Transporter to node `TransporterError' NODE2_ID reported error ERROR_CODE: ERROR_MESSAGE' Event Type Description `Error' A transporter error occurred while Priority communicating with node NODE2_ID; for a listing of transporter error codes and 2 messages, see `NDB' Transporter Errors (http://dev.mysql.com/doc/ndbapi/en/ndb-transporter-errors.html),Severity in MySQL Cluster Internals (http://dev.mysql.com/doc/ndbapi/en/ndb-internals.html)`ERROR' Log Message Event Name `Node NODE1_ID: Transporter to node `TransporterWarning' NODE2_ID reported error ERROR_CODE: ERROR_MESSAGE' Event Type Description `Error' A warning of a potential transporter Priority problem while communicating with node NODE2_ID; for a listing of transporter 8 error codes and messages, see `NDB' Transporter Errors Severity (http://dev.mysql.com/doc/ndbapi/en/ndb-transporter-errors.html), for more information `WARNING' Log Message Event Name `Node NODE1_ID: Node NODE2_ID missed `MissedHeartbeat' heartbeat HEARTBEAT_ID' Event Type Description `Error' This node missed a heartbeat from node NODE2_ID Priority 8 Severity `WARNING' Log Message Event Name `Node NODE1_ID: Node NODE2_ID declared `DeadDueToHeartbeat' dead due to missed heartbeat' Event Type Description `Error' This node has missed at least 3 heartbeats from node NODE2_ID, and so has declared Priority that node `dead' 8 Severity `ALERT' Log Message Event Name `Node NODE1_ID: Node Sent Heartbeat to `SentHeartbeat' node = NODE2_ID' Event Type Description `Info' This node has sent a heartbeat to node NODE2_ID Priority 12 Severity `INFO' Log Message Event Name `Node NODE_ID: Event buffer status: `EventBufferStatus' used=BYTES_USED (PERCENT_USED%) alloc=BYTES_ALLOCATED (PERCENT_AVAILABLE%) Event Type max=BYTES_AVAILABLE apply_gci=LATEST_RESTORABLE_GCI `Info' latest_gci=LATEST_GCI' Priority Description 7 This report is seen during heavy event buffer usage, for example, when many Severity updates are being applied in a relatively short period of time; the report shows the `INFO' number of bytes and the percentage of event buffer memory used, the bytes allocated and percentage still available, and the latest and latest restorable global checkpoints Log Message Event Name `Node NODE_ID: Entering single user mode', `SingleUser' `Node NODE_ID: Entered single user mode Node API_NODE_ID has exclusive access', Event Type `Node NODE_ID: Entering single user mode' `Info' Description Priority These reports are written to the cluster log when entering and exiting single user 7 mode; API_NODE_ID is the node ID of the API or SQL having exclusive access to the Severity cluster (for more information, see *Note mysql-cluster-single-user-mode::); the `INFO' message `Unknown single user report API_NODE_ID' indicates an error has taken place and should never be seen in normal operation Log Message Event Name `Node NODE_ID: Backup BACKUP_ID started `BackupStarted' from node MGM_NODE_ID' Event Type Description `Backup' A backup has been started using the management node having MGM_NODE_ID; this Priority message is also displayed in the cluster management client when the `START BACKUP' 7 command is issued; for more information, see *Note Severity mysql-cluster-backup-using-management-client:: `INFO' Log Message Event Name `Node NODE_ID: Backup BACKUP_ID started `BackupCompleted' from node MGM_NODE_ID completed. StartGCP: START_GCP StopGCP: STOP_GCP #Records: Event Type RECORDS #LogRecords: LOG_RECORDS Data: DATA_BYTES bytes Log: LOG_BYTES bytes' `Backup' Description Priority The backup having the ID BACKUP_ID has been 7 completed; for more information, see *Note mysql-cluster-backup-using-management-client::Severity `INFO' Log Message Event Name `Node NODE_ID: Backup request from `BackupFailedToStart' MGM_NODE_ID failed to start. Error: ERROR_CODE' Event Type Description `Backup' The backup failed to start; for error Priority codes, see MGM`' API Errors (http://dev.mysql.com/doc/ndbapi/en/mgm-errors.html)7 Severity `ALERT' Log Message Event Name `Node NODE_ID: Backup BACKUP_ID started `BackupAborted' from MGM_NODE_ID has been aborted. Error: ERROR_CODE' Event Type Description `Backup' The backup was terminated after starting, Priority possibly due to user intervention 7 Severity `ALERT'  File: manual.info, Node: mysql-cluster-ndb-transporter-errors, Prev: mysql-cluster-logs-cluster-log, Up: mysql-cluster-logs-ndb-messages 17.5.7.2 MySQL 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. This table lists error codes along with error names and error text that are written to the cluster log in the event of 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'  File: manual.info, Node: mysql-cluster-single-user-mode, Next: mysql-cluster-sql-statements, Prev: mysql-cluster-logs-ndb-messages, Up: mysql-cluster-management 17.5.8 MySQL 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 *Note `ndb_restore': mysql-cluster-programs-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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client to see when the cluster has entered single user mode. Beginning with MySQL Cluster NDB 7.1.1, you can also check the `status' column of the *Note `ndbinfo.nodes': mysql-cluster-ndbinfo-nodes. table (see *Note 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 database nodes prior to entering single user mode.  File: manual.info, Node: mysql-cluster-sql-statements, Next: mysql-cluster-ndbinfo, Prev: mysql-cluster-single-user-mode, Up: mysql-cluster-management 17.5.9 Quick Reference: MySQL Cluster SQL Statements ---------------------------------------------------- This section discusses several SQL statements that can prove useful in managing and monitoring a MySQL server that is connected to a MySQL Cluster, and in some cases provide information about the cluster itself. * *Note `SHOW ENGINE NDB STATUS': show-engine, *Note `SHOW ENGINE NDBCLUSTER STATUS': show-engine. The output of this statement contains information about the server's connection to the cluster, creation and usage of MySQL Cluster objects, and binary logging for MySQL Cluster replication. See *Note show-engine::, for a usage example and more detailed information. * *Note `SHOW ENGINES': 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 *Note show-engines::, for more detailed information. *Note*: In MySQL 5.1 and later, this statement does not support a `LIKE' clause. However, you can use `LIKE' to filter queries against the *Note `INFORMATION_SCHEMA.ENGINES': engines-table, as discussed in the next item. * `SELECT * FROM INFORMATION_SCHEMA.ENGINES [WHERE ENGINE LIKE 'NDB%']' This is the equivalent of *Note `SHOW ENGINES': show-engines, but uses the *Note `ENGINES': engines-table. table of the `INFORMATION_SCHEMA' database (available beginning with MySQL 5.1.5). Unlike the case with the *Note `SHOW ENGINES': 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 *Note `NDB': mysql-cluster. support and, if so, whether it is enabled: mysql> SELECT SUPPORT FROM INFORMATION_SCHEMA.ENGINES -> WHERE ENGINE LIKE 'NDB%'; +---------+ | support | +---------+ | ENABLED | +---------+ See *Note engines-table::, for more information. * `SHOW VARIABLES LIKE 'NDB%'' This statement provides a list of most server system variables relating to the *Note `NDB': mysql-cluster. 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 *Note 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 *Note variables-table::, and *Note 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 | 192.168.0.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 *Note show-status::. * `SELECT * FROM INFORMATION_SCHEMA.GLOBAL_STATUS WHERE VARIABLE_NAME LIKE 'NDB%';' Beginning with MySQL 5.1.12, this statement provides similar output to the `SHOW' command discussed in the previous item. However, unlike the case with *Note `SHOW STATUS': show-status, it is possible using the *Note `SELECT': select. to extract values in SQL for use in scripts for monitoring and automation purposes. See *Note status-table::, for more information. Beginning with MySQL Cluster NDB 7.1.1, you can also query the tables in the *Note `ndbinfo': mysql-cluster-ndbinfo. information database for real-time data about many MySQL Cluster operations. See *Note mysql-cluster-ndbinfo::.  File: manual.info, Node: mysql-cluster-ndbinfo, Next: mysql-cluster-security, Prev: mysql-cluster-sql-statements, Up: mysql-cluster-management 17.5.10 The `ndbinfo' MySQL Cluster Information Database -------------------------------------------------------- * Menu: * mysql-cluster-ndbinfo-arbitrator-validity-detail:: The `ndbinfo arbitrator_validity_detail' Table * mysql-cluster-ndbinfo-arbitrator-validity-summary:: The `ndbinfo arbitrator_validity_summary' Table * mysql-cluster-ndbinfo-blocks:: The `ndbinfo blocks' Table * mysql-cluster-ndbinfo-cluster-operations:: The `ndbinfo cluster_operations' Table * mysql-cluster-ndbinfo-cluster-transactions:: The `ndbinfo cluster_transactions' Table * mysql-cluster-ndbinfo-config-params:: The `ndbinfo config_params' Table * mysql-cluster-ndbinfo-counters:: The `ndbinfo counters' Table * mysql-cluster-ndbinfo-diskpagebuffer:: The `ndbinfo diskpagebuffer' Table * mysql-cluster-ndbinfo-logbuffers:: The `ndbinfo logbuffers' Table * mysql-cluster-ndbinfo-logspaces:: The `ndbinfo logspaces' Table * mysql-cluster-ndbinfo-membership:: The `ndbinfo membership' Table * mysql-cluster-ndbinfo-memoryusage:: The `ndbinfo memoryusage' Table * mysql-cluster-ndbinfo-nodes:: The `ndbinfo nodes' Table * mysql-cluster-ndbinfo-pools:: The `ndbinfo pools' Table * mysql-cluster-ndbinfo-resources:: The `ndbinfo resources' Table * mysql-cluster-ndbinfo-server-operations:: The `ndbinfo server_operations' Table * mysql-cluster-ndbinfo-server-transactions:: The `ndbinfo server_transactions' Table * mysql-cluster-ndbinfo-threadblocks:: The `ndbinfo threadblocks' Table * mysql-cluster-ndbinfo-threadstat:: The `ndbinfo threadstat' Table * mysql-cluster-ndbinfo-transporters:: The `ndbinfo transporters' Table `ndbinfo' is a database storing containing information specific to MySQL Cluster, available beginning with MySQL Cluster NDB 7.1.1. This database contains a number of tables, each providing a different sort of data about MySQL 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 MySQL 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 *Note `SHOW PLUGINS': 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 | | 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 | | MyISAM | ACTIVE | STORAGE ENGINE | NULL | GPL | | MRG_MYISAM | ACTIVE | STORAGE ENGINE | NULL | GPL | | ndbcluster | ACTIVE | STORAGE ENGINE | NULL | GPL | _| ndbinfo | ACTIVE | STORAGE ENGINE | NULL | GPL |_ +------------+----------+----------------+---------+---------+ 12 rows in set (0.00 sec) You can also do this by checking the output of *Note `SHOW ENGINES': show-engines. for a row that has `ndbinfo' for `Engine' and `YES' for `Support', 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: MRG_MYISAM Support: YES Comment: Collection of identical MyISAM tables Transactions: NO XA: NO Savepoints: NO _*************************** 3. row *************************** Engine: ndbinfo Support: YES Comment: MySQL Cluster system information storage engine Transactions: NO XA: NO Savepoints: NO_ *************************** 4. row *************************** Engine: CSV Support: YES Comment: CSV storage engine Transactions: NO XA: NO Savepoints: NO *************************** 5. row *************************** Engine: MEMORY Support: YES Comment: Hash based, stored in memory, useful for temporary tables Transactions: NO XA: NO Savepoints: NO *************************** 6. row *************************** Engine: FEDERATED Support: NO Comment: Federated MySQL storage engine Transactions: NULL XA: NULL Savepoints: NULL *************************** 7. row *************************** Engine: ARCHIVE Support: YES Comment: Archive storage engine Transactions: NO XA: NO Savepoints: NO *************************** 8. row *************************** Engine: InnoDB Support: YES Comment: Supports transactions, row-level locking, and foreign keys Transactions: YES XA: YES Savepoints: YES *************************** 9. row *************************** Engine: MyISAM Support: DEFAULT Comment: Default engine as of MySQL 3.23 with great performance Transactions: NO XA: NO Savepoints: NO *************************** 10. row *************************** Engine: BLACKHOLE Support: YES Comment: /dev/null storage engine (anything you write to it disappears) 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 *Note `mysql': mysql. or another MySQL client. For example, you can see `ndbinfo' listed in the output of *Note `SHOW DATABASES': show-databases, as shown here: mysql> SHOW DATABASES; +--------------------+ | Database | +--------------------+ | information_schema | | mysql | | ndbinfo | | test | +--------------------+ 4 rows in set (0.00 sec) If the *Note `mysqld': mysqld. process was not started with the `--ndbcluster' option, `ndbinfo' is not available and is not displayed by *Note `SHOW DATABASES': show-databases. If *Note `mysqld': mysqld. was formerly connected to a MySQL 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 *Note `NDB': mysql-cluster. 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. Beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, `ndbinfo' tables are not included in the query cache. (Bug #59831) You can select the `ndbinfo' database with a *Note `USE': use. statement, and then issue a *Note `SHOW TABLES': 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 | +----------------------+ | blocks | | cluster_operations | | cluster_transactions | | config_params | | counters | | diskpagebuffer | | logbuffers | | logspaces | | memoryusage | | nodes | | resources | | server_operations | | server_transactions | | threadblocks | | threadstat | | transporters | +----------------------+ 16 rows in set (0.04 sec) The *Note `diskpagebuffer': mysql-cluster-ndbinfo-diskpagebuffer. table was added in MySQL Cluster NDB 7.1.9. The *Note `cluster_operations': mysql-cluster-ndbinfo-cluster-operations, *Note `cluster_transactions': mysql-cluster-ndbinfo-cluster-transactions, *Note `server_operations': mysql-cluster-ndbinfo-server-operations, *Note `server_transactions': mysql-cluster-ndbinfo-server-transactions, *Note `threadblocks': mysql-cluster-ndbinfo-threadblocks, and *Note `threadstat': mysql-cluster-ndbinfo-threadstat. tables were added in MySQL Cluster NDB 7.1.17. In early versions of MySQL Cluster NDB 7.1, there was an additional *Note `pools': mysql-cluster-ndbinfo-pools. table in the `ndbinfo' database; however, this table was removed in MySQL Cluster NDB 7.1.3. You can execute *Note `SELECT': select. statements against these tables, just as you would normally expect: mysql> SELECT * FROM memoryusage; +---------+--------------+------+-------+ | node_id | memory_type | used | max | +---------+--------------+------+-------+ | 1 | Data memory | 3230 | 6408 | | 2 | Data memory | 3230 | 6408 | | 1 | Index memory | 16 | 12832 | | 2 | Index memory | 16 | 12832 | +---------+--------------+------+-------+ 4 rows in set (0.37 sec) More complex queries, such as the two following *Note `SELECT': select. statements using the *Note `memoryusage': mysql-cluster-ndbinfo-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' Beginning with MySQL Cluster NDB 7.1.7, *Note `mysqldump': mysqldump. ignores `ndbinfo' entirely, and excludes it from any output. This is true even when using the `--databases' or `--all-databases' option. MySQL Cluster also maintains tables in the `INFORMATION_SCHEMA' information database, including the *Note `FILES': files-table. table which contains information about files used for MySQL Cluster Disk Data storage. For more information, see *Note mysql-cluster-i_s-tables::.  File: manual.info, Node: mysql-cluster-ndbinfo-arbitrator-validity-detail, Next: mysql-cluster-ndbinfo-arbitrator-validity-summary, Prev: mysql-cluster-ndbinfo, Up: mysql-cluster-ndbinfo 17.5.10.1 The `ndbinfo arbitrator_validity_detail' Table ........................................................ The `arbitrator_validity_detail' table shows the view that each data node in the cluster of the arbitrator. It is a subset of the *Note `membership': mysql-cluster-ndbinfo-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. This table describes the columns in the `arbitrator_validity_detail' table. The table shows the column name, data type, and provides a brief description. 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 *Note `ndb_mgm -e "SHOW"': mysql-cluster-programs-ndb-mgm. 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'. Like the *Note `membership': mysql-cluster-ndbinfo-membership. and *Note `arbitrator_validity_summary': mysql-cluster-ndbinfo-arbitrator-validity-summary. tables, this table was added in MySQL Cluster NDB 7.0.37 and MySQL Cluster NDB 7.1.26.  File: manual.info, Node: mysql-cluster-ndbinfo-arbitrator-validity-summary, Next: mysql-cluster-ndbinfo-blocks, Prev: mysql-cluster-ndbinfo-arbitrator-validity-detail, Up: mysql-cluster-ndbinfo 17.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. This table describes the columns in the `arbitrator_validity_summary' table. The table shows the column name, data type, and provides a brief description. 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. Like the *Note `membership': mysql-cluster-ndbinfo-membership. and *Note `arbitrator_validity_detail': mysql-cluster-ndbinfo-arbitrator-validity-detail. tables, this table was added in MySQL Cluster NDB 7.0.37 and MySQL Cluster NDB 7.1.26.  File: manual.info, Node: mysql-cluster-ndbinfo-blocks, Next: mysql-cluster-ndbinfo-cluster-operations, Prev: mysql-cluster-ndbinfo-arbitrator-validity-summary, Up: mysql-cluster-ndbinfo 17.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/ndbapi/en/ndb-internals-kernel-blocks.html)). It is for use by the other *Note `ndbinfo': mysql-cluster-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. This table provides information about the columns in the `blocks' table. The table shows the column name, data type, and provides a brief description. 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 MySQL Cluster releases.  File: manual.info, Node: mysql-cluster-ndbinfo-cluster-operations, Next: mysql-cluster-ndbinfo-cluster-transactions, Prev: mysql-cluster-ndbinfo-blocks, Up: mysql-cluster-ndbinfo 17.5.10.4 The `ndbinfo cluster_operations' Table ................................................ The `cluster_operations' table provides a per-operation (stateful primary key op) view of all activity in the MySQL Cluster from the point of view of the local data management (LQH) blocks (see The `DBLQH' Block (http://dev.mysql.com/doc/ndbapi/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. This table provides information about the columns in the `cluster_operations' table. The table shows the column name, data type, and provides a brief description. 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-methods.html#ndb-ndbtransaction-gettransactionid) 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 `'. 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 *Note `ndb_show_tables': mysql-cluster-programs-ndb-show-tables. The `fragid' is the same as the partition number seen in the output of *Note `ndb_desc': mysql-cluster-programs-ndb-desc. `--extra-partition-info' (short form `-p'). In `client_node_id' and `client_block_ref', `client' refers to a MySQL Cluster API or SQL node (that is, an NDB API client or a MySQL Server attached to the cluster). This table was added in MySQL Cluster NDB 7.1.17.  File: manual.info, Node: mysql-cluster-ndbinfo-cluster-transactions, Next: mysql-cluster-ndbinfo-config-params, Prev: mysql-cluster-ndbinfo-cluster-operations, Up: mysql-cluster-ndbinfo 17.5.10.5 The `ndbinfo cluster_transactions' Table .................................................. The `cluster_transactions' table shows information about all ongoing transactions in a MySQL 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. This table provides information about the columns in the `cluster_transactions' table. The table shows the column name, data type, and provides a brief description. 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-methods.html#ndb-ndbtransaction-gettransactionid) 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 a MySQL Cluster API or SQL node (that is, an NDB API client or a MySQL Server attached to the cluster). This table was added in MySQL Cluster NDB 7.1.17.  File: manual.info, Node: mysql-cluster-ndbinfo-config-params, Next: mysql-cluster-ndbinfo-counters, Prev: mysql-cluster-ndbinfo-cluster-transactions, Up: mysql-cluster-ndbinfo 17.5.10.6 The `ndbinfo config_params' Table ........................................... The `config_params' table is a static table which provides the names and internal ID numbers of all MySQL 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 provides information about the columns in the `config_params' table. The table shows the column name, data type, and provides a brief description. Column Name Type Description `param_number' integer The parameter's internal ID number `param_name' string The name of the parameter Although this is a static table, its content can vary between MySQL Cluster installations, since supported parameters can vary due to differences between software releases, cluster hardware configurations, and other factors.  File: manual.info, Node: mysql-cluster-ndbinfo-counters, Next: mysql-cluster-ndbinfo-diskpagebuffer, Prev: mysql-cluster-ndbinfo-config-params, Up: mysql-cluster-ndbinfo 17.5.10.7 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. This table provides information about the columns in the `counters' table. The table shows the column name, data type, and provides a brief description. 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/ndbapi/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. Prior to MySQL Cluster NDB 7.2.0, this was limited to either the `DBLQH' kernel block or the `DBTC' kernel block. The `OPERATIONS' counter is associated with the `DBLQH' (local query handler) kernel block (see The `DBLQH' Block (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-kernel-blocks-dblqh.html)). The `ATTRINFO', `TRANSACTIONS', `COMMITS', `READS', `SIMPLE_READS', `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/ndbapi/en/ndb-internals-kernel-blocks-dbtc.html)). MySQL Cluster NDB 7.2.0, as part of its implementation of distributed pushed-down joins, adds 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. These counters are associated with the `DBSPJ' (select push-down join) kernel block (see The `DBSPJ' Block (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-kernel-blocks-dbspj.html)). A number of counters increasing the visibility of transporter overload and send buffer sizing when troubleshooting such issues were added in MySQL Cluster NDB 7.0.37 and MySQL Cluster NDB 7.1.26. (Bug #15935206) 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.  File: manual.info, Node: mysql-cluster-ndbinfo-diskpagebuffer, Next: mysql-cluster-ndbinfo-logbuffers, Prev: mysql-cluster-ndbinfo-counters, Up: mysql-cluster-ndbinfo 17.5.10.8 The `ndbinfo diskpagebuffer' Table ............................................ The `diskpagebuffer' table provides statistics about disk page buffer usage by MySQL 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. This table provides information about the columns in the `diskpagebuffer' table. The table shows the column names, data type, and provides a brief description. 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 MySQL 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.  File: manual.info, Node: mysql-cluster-ndbinfo-logbuffers, Next: mysql-cluster-ndbinfo-logspaces, Prev: mysql-cluster-ndbinfo-diskpagebuffer, Up: mysql-cluster-ndbinfo 17.5.10.9 The `ndbinfo logbuffers' Table ........................................ The `logbuffer' table provides information on MySQL 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. This table provides information about the columns in the `logbuffers' table. The table shows the column names, data type, and provides a brief description. 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.  File: manual.info, Node: mysql-cluster-ndbinfo-logspaces, Next: mysql-cluster-ndbinfo-membership, Prev: mysql-cluster-ndbinfo-logbuffers, Up: mysql-cluster-ndbinfo 17.5.10.10 The `ndbinfo logspaces' Table ........................................ This table provides information about MySQL 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. This table provides information about the columns in the `logspaces' table. The table shows the column name, data type, and provides a brief description. 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.  File: manual.info, Node: mysql-cluster-ndbinfo-membership, Next: mysql-cluster-ndbinfo-memoryusage, Prev: mysql-cluster-ndbinfo-logspaces, Up: mysql-cluster-ndbinfo 17.5.10.11 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. This table provides information about the columns in the `membership' table. The table shows the name, data type, and provides a brief description. 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 *Note `ndb_mgm -e "SHOW"': mysql-cluster-programs-ndb-mgm. `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: Arrangement of nodes in a circle 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 MySQL Cluster Start Phases (http://dev.mysql.com/doc/ndbapi/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 MySQL 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. Like the *Note `arbitrator_validity_detail': mysql-cluster-ndbinfo-arbitrator-validity-detail. and *Note `arbitrator_validity_summary': mysql-cluster-ndbinfo-arbitrator-validity-summary. tables, this table was added in MySQL Cluster NDB 7.0.37 and MySQL Cluster NDB 7.1.26.  File: manual.info, Node: mysql-cluster-ndbinfo-memoryusage, Next: mysql-cluster-ndbinfo-nodes, Prev: mysql-cluster-ndbinfo-membership, Up: mysql-cluster-ndbinfo 17.5.10.12 The `ndbinfo memoryusage' Table .......................................... Querying this table provides information similar to that provided by the `ALL REPORT MemoryUsage' command in the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client, or logged by `ALL DUMP 1000'. The following table provides information about the columns in the `memoryusage' table in MySQL Cluster NDB 7.1.3 and later. 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 provides information about the columns in the `memoryusage' table in MySQL Cluster NDB 7.1.3 and later. The table shows the column name, data type, and provides a brief description. Column Name Type Description `node_id' integer The node ID of this data node. `memory_type' string One of `Data memory' or `Index memory'. `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 `1' and `2', and the `config.ini' file contains the following: [ndbd default] DataMemory = 100M IndexMemory = 100M The following query shows approximately the same values: mysql> SELECT node_id, memory_type, total > FROM ndbinfo.memoryusage; +---------+--------------+-----------+ | node_id | memory_type | total | +---------+--------------+-----------+ | 1 | Data memory | 104857600 | | 1 | Index memory | 105119744 | | 2 | Data memory | 104857600 | | 2 | Index memory | 105119744 | +---------+--------------+-----------+ 4 rows in set (0.30 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'. MySQL Cluster NDB 7.1.2 and earlier The the remainder of this section provides information about the `memoryusage' table as implemented prior to MySQL Cluster NDB 7.1.3. (If you are using MySQL Cluster NDB 7.1.3 or later, refer to the beginning of this section.) For each column, the table shown here provides the name, data type, and a brief description. Additional information can be found in the notes following the table. This table provides information about the `memoryusage' table as implemented prior to MySQL Cluster NDB 7.1.3. The table shows the column name, data type, and provides a brief description. Column Name Type Description `node_id' integer The node ID of this data node. `memory_type' string One of `Data memory' or `Index memory' `used' integer Number of memory pages used; see text. `max' integer Total number of memory pages available; see text. For the `used' and `max' columns, resources are measured in pages, which (in MySQL Cluster NDB 7.1.2 and earlier) are 16K in size for `DataMemory' and 8K for `IndexMemory'. This example shows how to use this information in obtaining totals for `DataMemory', `IndexMemory', or both, which you can do by summing across data nodes and table columns, like this: mysql> USE ndbinfo; Database changed mysql> SET @IPAGE := 8 * 1024; Query OK, 0 rows affected (0.03 sec) mysql> SET @DPAGE := 2 * @IPAGE; Query OK, 0 rows affected (0.00 sec) mysql> SELECT -> @DPAGE * SUM(used) as 'Total DataMemory Used', -> @DPAGE * SUM(max) as 'Total DataMemory Available', -> @DPAGE * SUM(used) DIV COUNT(*) as 'Average DataMemory Used Per Node', -> @DPAGE * SUM(max) DIV COUNT(*) as 'Average DataMemory Available Per Node' -> FROM memoryusage WHERE memory_type = 'Data memory'\G *************************** 1. row *************************** Total DataMemory Used: 106102784 Total DataMemory Available: 209977344 Average DataMemory Used Per Node: 53051392 Average DataMemory Available Per Node: 104988672 1 row in set (0.34 sec) mysql> SELECT -> @IPAGE * SUM(used) as 'Total IndexMemory Used', -> @IPAGE * SUM(max) as 'Total IndexMemory Available', -> @IPAGE * SUM(used) DIV COUNT(*) as 'Average IndexMemory Used Per Node', -> @IPAGE * SUM(max) DIV COUNT(*) as 'Average IndexMemory Available Per Node' -> FROM memoryusage WHERE memory_type = 'INDEX_MEMORY'\G *************************** 1. row *************************** Total IndexMemory Used: 376832 Total IndexMemory Available: 210239488 Average IndexMemory Used Per Node: 188416 Average IndexMemory Available Per Node: 105119744 1 row in set (0.33 sec) (We use `DIV' rather than `/' in both queries so that the results in all of the output columns are integers.) Prior to MySQL Cluster NDB 7.1.2, the `memory_type' column was named `DATA_MEMORY'. (Bug #50926)  File: manual.info, Node: mysql-cluster-ndbinfo-nodes, Next: mysql-cluster-ndbinfo-pools, Prev: mysql-cluster-ndbinfo-memoryusage, Up: mysql-cluster-ndbinfo 17.5.10.13 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. This table provides information about the columns of the `nodes' table. The table shows the column name, data type, and provides a brief description. 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 *Note `BIGINT': integer-types. value. This figure includes the time actually needed to start the node; in other words, this counter starts running the moment that *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndbmtd': mysql-cluster-programs-ndbmtd. is first invoked; thus, even for a node that has not yet finished starting, `uptime' may show a non-zero 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 *Note 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client `NODE_ID STATUS' command (see *Note mysql-cluster-mgm-client-commands::). If the node is not currently starting, then this column shows `0'. For a listing of MySQL Cluster start phases with descriptions, see *Note mysql-cluster-start-phases::. The `config_generation' column was added in MySQL Cluster NDB 7.0.24 and MySQL Cluster NDB 7.1.13. This 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 *Note `SELECT': 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. *Note*: When upgrading to MySQL Cluster NDB 7.0.24 or MySQL Cluster NDB 7.1.13 from a previous version of MySQL Cluster, you should run *Note `mysql_upgrade': mysql-upgrade. on all MySQL Servers that should connect to the cluster, in order to enable support for the new `config_generation' column. Otherwise, when you attempt to access this table, you get the warning `Table 'ndb$nodes' is defined differently in NDB, there are more columns available...' Nodes that are stopped are not accounted for in this table. Suppose that you have a MySQL 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 *Note `SELECT': 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)  File: manual.info, Node: mysql-cluster-ndbinfo-pools, Next: mysql-cluster-ndbinfo-resources, Prev: mysql-cluster-ndbinfo-nodes, Up: mysql-cluster-ndbinfo 17.5.10.14 The `ndbinfo pools' Table .................................... *Important*: This table was part of the original `ndbinfo' implementation, but was later removed (in MySQL Cluster NDB 7.1.3). The information in this section is now obsolete, and subject to removal in a future version of the documentation. The `pools' table was originally intended to provide information about *Note `NDB': mysql-cluster. memory pool usage, but was later removed. For each column, this table shows the name, data type, and a brief description of each `ndbinfo.pools' column (as it appeared prior to MySQL Cluster NDB 7.1.3). Additional information can be found in the notes afterward. This table provides information about the columns in the `ndbinfo.pools' table (as it appeared prior to MySQL Cluster NDB 7.1.3). The table shows the column name, data type, and provides a brief description. Column Name Type Description `node_id' integer The data node's node ID. `block_name' string Name of the NDB kernel block using this pool. `block_instance' integer Kernel block instance ID. `pool_name' string The name of the pool. `used' integer Amount of the pool in use. `total' integer Total size of the pool. `high' integer The maximum used from this pool (since the node was last started). `entry_size' integer The size of each object, in bytes. `param_name1' string Name of a configuration parameter associated with this pool (or `NULL'); see text. `param_name2' string Name of a configuration parameter associated with this pool (or `NULL'); see text. `param_name3' string Name of a configuration parameter associated with this pool (or `NULL'); see text. `param_name4' string Name of a configuration parameter associated with this pool (or `NULL'); see text. The columns `param_name1', `param_name2', `param_name3', and `param_name4' contain names of configuration parameters that are associated with a given pool. If no parameters are associated with the pool, then all 4 of these columns are `NULL'. For pools that are associated with configuration parameters, these columns are filled with non-`NULL' values, but not in any particular order. You can use a query such as the one shown here to generate a table showing the associations of pools, NDB kernel blocks, and (where applicable) configuration parameters: SELECT DISTINCT(pool_name) as 'Pool', block_name as 'Block', IF( (param_name1 && param_name2 && param_name3 && param_name4) IS NULL, '[NONE]', REPLACE( TRIM( CONCAT( IFNULL(param_name1, ''), IFNULL(CONCAT(' ', param_name2), ''), IFNULL(CONCAT(' ', param_name3), ''), IFNULL(CONCAT(' ', param_name4), '') ) ), ' ', ', ' ) ) as 'Parameter(s)' FROM pools ORDER BY pool_name; You may also find the following stored procedure useful. It returns a list of pools associated with a given configuration parameter, along with the kernel blocks to which these pools belong. You can see here the statement used to create this stored procedure along with sample output for some typical parameters: mysql> DELIMITER | mysql> CREATE PROCEDURE get_pools (p VARCHAR(50)) -> BEGIN -> SELECT -> DISTINCT(pool_name) as Pool, -> block_name as Block -> FROM ndbinfo.pools -> WHERE p -> IN (param_name1, param_name2, param_name3, param_name4) .> ORDER BY Pool; -> END -> | Query OK, 0 rows affected (0.02 sec) mysql> DELIMITER ; mysql> CALL get_pools('MaxNoOfTables'); +-----------------+------------+ | pool_name | block_name | +-----------------+------------+ | Table Record | DBDICT | | DictObject | DBDICT | | Index | DBTC | | Table | BACKUP | | Trigger | BACKUP | | Fragment | BACKUP | | Subscriber | SUMA | | Table | SUMA | | Subscription | SUMA | | Index | DBTUX | | Descriptor page | DBTUX | +-----------------+------------+ 11 rows in set (0.30 sec) Query OK, 0 rows affected (0.30 sec) mysql> CALL get_pools('MaxNoOfOrderedIndexes'); +-----------------+------------+ | pool_name | block_name | +-----------------+------------+ | DictObject | DBDICT | | Index | DBTC | | Table | BACKUP | | Trigger | BACKUP | | Fragment | BACKUP | | Index | DBTUX | | Fragment | DBTUX | | Descriptor page | DBTUX | +-----------------+------------+ 8 rows in set (0.29 sec)  File: manual.info, Node: mysql-cluster-ndbinfo-resources, Next: mysql-cluster-ndbinfo-server-operations, Prev: mysql-cluster-ndbinfo-pools, Up: mysql-cluster-ndbinfo 17.5.10.15 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. This table provides information about the columns in the `resources' table. The table shows the column name, data type, and provides a brief description. 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 `RESERVED', `DISK_OPERATIONS', `DISK_RECORDS', `DATA_MEMORY', `JOBBUFFER', `FILE_BUFFERS', or `TRANSPORTER_BUFFERS'.  File: manual.info, Node: mysql-cluster-ndbinfo-server-operations, Next: mysql-cluster-ndbinfo-server-transactions, Prev: mysql-cluster-ndbinfo-resources, Up: mysql-cluster-ndbinfo 17.5.10.16 The `ndbinfo server_operations' Table ................................................ The `server_operations' table contains entries for all ongoing *Note `NDB': mysql-cluster. operations that the current SQL node (MySQL Server) is currently involved in. It effectively is a subset of the the *Note `cluster_operations': mysql-cluster-ndbinfo-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. This table provides information about the columns in the `server_operations' table. The table shows the column name, data type, and provides a brief description. 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 *Note `SHOW PROCESSLIST': show-processlist. It is obtained from the `INFORMATION_SCHEMA' table *Note `NDB_TRANSID_MYSQL_CONNECTION_MAP': ndb-transid-mysql-connection-map-table. 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-methods.html#ndb-ndbtransaction-gettransactionid) 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 `'. 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 *Note `ndb_show_tables': mysql-cluster-programs-ndb-show-tables. The `fragid' is the same as the partition number seen in the output of *Note `ndb_desc': mysql-cluster-programs-ndb-desc. `--extra-partition-info' (short form `-p'). In `client_node_id' and `client_block_ref', `client' refers to a MySQL Cluster API or SQL node (that is, an NDB API client or a MySQL Server attached to the cluster). This table was added in MySQL Cluster NDB 7.1.17.  File: manual.info, Node: mysql-cluster-ndbinfo-server-transactions, Next: mysql-cluster-ndbinfo-threadblocks, Prev: mysql-cluster-ndbinfo-server-operations, Up: mysql-cluster-ndbinfo 17.5.10.17 The `ndbinfo server_transactions' Table .................................................. The `server_transactions' table is subset of the *Note `cluster_transactions': mysql-cluster-ndbinfo-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. This table provides information about columns in the `server_transactions' table. The table shows the column name, data type, and provides a brief description. 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 *Note `SHOW PROCESSLIST': show-processlist. It is obtained from the `INFORMATION_SCHEMA' table *Note `NDB_TRANSID_MYSQL_CONNECTION_MAP': ndb-transid-mysql-connection-map-table. 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-methods.html#ndb-ndbtransaction-gettransactionid) 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 a MySQL Cluster API or SQL node (that is, an NDB API client or a MySQL Server attached to the cluster). This table was added in MySQL Cluster NDB 7.1.17.  File: manual.info, Node: mysql-cluster-ndbinfo-threadblocks, Next: mysql-cluster-ndbinfo-threadstat, Prev: mysql-cluster-ndbinfo-server-transactions, Up: mysql-cluster-ndbinfo 17.5.10.18 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. This table provides information about columns in the `threadblocks' table. The table shows the column name, data type, and provides a brief description. 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 `block_name' is one of the values found in the `block_name' column when selecting from the *Note `ndbinfo.blocks': mysql-cluster-ndbinfo-blocks. table. Although the list of possible values is static for a given MySQL Cluster release, the list may vary between releases. This table was added in MySQL Cluster NDB 7.1.17.  File: manual.info, Node: mysql-cluster-ndbinfo-threadstat, Next: mysql-cluster-ndbinfo-transporters, Prev: mysql-cluster-ndbinfo-threadblocks, Up: mysql-cluster-ndbinfo 17.5.10.19 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. This table provides information about the columns in the `threadstat' table. The table shows the column names, data type, and provides a brief description. 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 *Note events::. This table was added in MySQL Cluster NDB 7.1.17.  File: manual.info, Node: mysql-cluster-ndbinfo-transporters, Prev: mysql-cluster-ndbinfo-threadstat, Up: mysql-cluster-ndbinfo 17.5.10.20 The `ndbinfo transporters' Table ........................................... This table contains information about *Note `NDB': mysql-cluster. 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. This table provides information about the columns in the `transporters' table. The table shows the column name, data type, and provides a brief description. 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' Number of bytes received using this connection `connect_count' Number of times connection established on this transporter `overloaded' 1 if this transporter is currently overloaded, otherwise 0 `overload_count' Number of times this transporter has entered overload state since connecting `slowdown' 1 if this transporter is in scan slowdown state, otherwise 0 `slowdown_count' Number of times this transporter has entered scan 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 nodes which is not currently connected are not shown in this table. (This is similar omission of disconnected nodes in the *Note `ndbinfo.nodes': mysql-cluster-ndbinfo-nodes. table. The `remote_address', `bytes_sent', and `bytes_received' columns were added in MySQL Cluster NDB 7.0.36 and MySQL Cluster NDB 7.1.25. The `remote_address' is the 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'. The `connect_count', `overloaded', `overload_count' ,`slowdown', and `slowdown_count' columns were added in MySQL Cluster NDB 7.0.37 and MySQL Cluster NDB 7.1.26. These counters are reset on connection, and retain their values after the remote node disconnects. Also beginning with MySQL Cluster NDB 7.0.37 and MySQL Cluster NDB 7.1.26, the `bytes_send' and `bytes_received' counters are reset on connection as well, and so retain their values following disconnection. (Previously, the values in these columns were reset on disconnection.) (Bug #15935206) 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 *Note `ndb_mgm': mysql-cluster-programs-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.1.71-ndb-7.1.29, Nodegroup: 0, Master) id=2 @10.100.10.2 (5.1.71-ndb-7.1.29, Nodegroup: 0) [ndb_mgmd(MGM)] 1 node(s) id=10 @10.100.10.10 (5.1.71-ndb-7.1.29) [mysqld(API)] 2 node(s) id=20 @10.100.10.20 (5.1.71-ndb-7.1.29) id=21 @10.100.10.21 (5.1.71-ndb-7.1.29) 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client, then repeat the previous query (again using the *Note `mysql': 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)  File: manual.info, Node: mysql-cluster-security, Next: mysql-cluster-disk-data, Prev: mysql-cluster-ndbinfo, Up: mysql-cluster-management 17.5.11 MySQL Cluster Security Issues ------------------------------------- * Menu: * mysql-cluster-security-networking-issues:: MySQL Cluster Security and Networking Issues * mysql-cluster-security-mysql-privileges:: MySQL Cluster and MySQL Privileges * mysql-cluster-security-mysql-security-procedures:: MySQL Cluster and MySQL Security Procedures This section discusses security considerations to take into account when setting up and running MySQL Cluster. Topics covered in this section include the following: * MySQL Cluster and network security issues * Configuration issues relating to running MySQL Cluster securely * MySQL Cluster and the MySQL privilege system * MySQL standard security procedures as applicable to MySQL Cluster  File: manual.info, Node: mysql-cluster-security-networking-issues, Next: mysql-cluster-security-mysql-privileges, Prev: mysql-cluster-security, Up: mysql-cluster-security 17.5.11.1 MySQL Cluster Security and Networking Issues ...................................................... In this section, we discuss basic network security issues as they relate to MySQL Cluster. It is extremely important to remember that MySQL 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 a MySQL 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 *Note 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 *Note mysql-cluster-quick::, for configuration examples using `HostName' with API nodes. * Any *Note `ndb_mgm': mysql-cluster-programs-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 a MySQL Cluster setup using such a physically segregated network here: MySQL Cluster on a private network protected with a 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 *Note 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 MySQL Cluster is illustrated here: MySQL Cluster deployed on a network using software firewalls to create public and private zones Using this type of network setup means that there are two zones of MySQL 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: This table lists node types that are accessed in a _host-based firewall_ cluster configuration and the traffic to permit for each node type. Type of Node to Traffic to Permit be Accessed 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 * It originates from the IP address of a Management node 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 a MySQL 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 a MySQL Cluster using hardware and software firewalls in combination is shown here: Network setup for MySQL Cluster using a combination of hardware and software firewalls to provide protection 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 MySQL 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 a MySQL 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 *Note `ndb_mgm': mysql-cluster-programs-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.  File: manual.info, Node: mysql-cluster-security-mysql-privileges, Next: mysql-cluster-security-mysql-security-procedures, Prev: mysql-cluster-security-networking-issues, Up: mysql-cluster-security 17.5.11.2 MySQL Cluster and MySQL Privileges ............................................ In this section, we discuss how the MySQL privilege system works in relation to MySQL Cluster and the implications of this for keeping a MySQL Cluster secure. Standard MySQL privileges apply to MySQL 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 *Note `NDB': mysql-cluster. tables, databases containing such tables, and columns within such tables are identical in all respects with the *Note `GRANT': grant. and *Note `REVOKE': revoke. statements used in connection with database objects involving any (other) MySQL storage engine. The same thing is true with respect to the *Note `CREATE USER': create-user. and *Note `DROP USER': 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 duplicated or shared among MySQL servers acting as SQL nodes in a MySQL Cluster. By way of example, suppose that two SQL nodes *A* and *B* are connected to the same MySQL Cluster, which has an *Note `NDB': mysql-cluster. table named `mytable' in a database named `mydb', and that you execute an SQL statement on server *A* that creates a new user `jon@localhost' and grants this user the `SELECT' privilege on that table: mysql> GRANT SELECT ON mydb.mytable -> TO jon@localhost IDENTIFIED BY 'mypass'; This user is _not_ created on server *B*. For this to take place, the statement must also be run on server *B*. Similarly, statements run on server *A* and affecting the privileges of existing users on server *A* do not affect users on server *B* unless those statements are actually run on server *B* as well. In other words, _changes in users and their privileges do not automatically propagate between SQL nodes by default_. Prior to MySQL Cluster NDB 7.2, any synchronization of privileges between SQL nodes must be done either manually or by scripting an application that periodically synchronizes the privilege tables on all SQL nodes in the cluster. In MySQL Cluster NDB 7.2 and later, you can enable automatic distribution of MySQL users and privileges across MySQL Cluster SQL nodes; see *Note 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 *Note `NDB': mysql-cluster. tables on one SQL node from users that have privileges on another SQL node. (This is true even if you are not using the automatic distribution of user privileges available in MySQl Cluster NDB 7.2 and later.) The most far-reaching 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 MySQL Cluster management server performs no checking of the host from which a MySQL Server (or other API node) accesses the MySQL Cluster. * There is no firewall, or the firewall fails to protect against access to the MySQL Cluster from hosts external to the network. * The host name or IP address of the MySQL Cluster's 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 MySQL Cluster. Using the MySQL `root' account, this person can then perform the following actions: * Execute a *Note `SHOW DATABASES': show-databases. statement to obtain a list of all *Note `NDB': mysql-cluster. databases * Execute a *Note `SHOW TABLES FROM SOME_DATABASE': show-tables. statement to obtain a list of all *Note `NDB': mysql-cluster. tables in a given database * Run any legal MySQL statements on any of those 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 *Note `NDB': mysql-cluster, and so not visible to a `rogue' SQL node. *Note*: 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 cluster SQL nodes (unless you are using distributed privileges as supported in MySQL Cluster NDB 7.2 and later). In sum, you cannot have a safe MySQL 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 a MySQL 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 a MySQL Cluster. Prior to MySQL Cluster NDB 7.2, you should never convert the system tables in the `mysql' database to use the *Note `NDB': mysql-cluster. storage engine. There are a number of reasons why you should not do this, but the most important reason is this: _Many of the SQL statements that affect `mysql' tables storing information about user privileges, stored routines, scheduled events, and other database objects cease to function if these tables are changed to use any storage engine other than `MyISAM'_. This is a consequence of various MySQL Server internals. Beginning with MySQL Cluster NDB 7.2, you can use a stored procedure provided for this purpose (see *Note mysql-cluster-privilege-distribution::), but you are strongly advised not to attempt convert the system tables manually. 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 two most important points to remember regarding the MySQL privilege system with regard to MySQL Cluster are: 1. Prior to MySQL Cluster NDB 7.2 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. In MySQL Cluster NDB 7.2 and later 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 MySQL Cluster distribution. 2. Once a MySQL user is granted privileges on an *Note `NDB': mysql-cluster. table from one SQL node in a MySQL Cluster, that user can `see' any data in that table regardless of the SQL node from which the data originated. (This is true even if you are not using the privilege distribution support available in MySQl Cluster NDB 7.2 or later.)  File: manual.info, Node: mysql-cluster-security-mysql-security-procedures, Prev: mysql-cluster-security-mysql-privileges, Up: mysql-cluster-security 17.5.11.3 MySQL Cluster and MySQL Security Procedures ..................................................... In this section, we discuss MySQL standard security procedures as they apply to running MySQL Cluster. In general, any standard procedure for running MySQL securely also applies to running a MySQL Server as part of a MySQL 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 *Note `mysqld': 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 *Note `mysqld': 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 *Note `mysqld': 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 *Note `mysqld': mysqld. running as another user unintentionally. The *Note `mysqld_safe': mysqld-safe. startup script forces MySQL to run as the `mysql' user. *Important*: Never run *Note `mysqld': 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 *Note 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 *Note `DELETE': delete. statement not to omit the `WHERE' clause, or you risk deleting _all_ MySQL users. Be sure to run the *Note `FLUSH PRIVILEGES': flush. statement as soon as you have modified the `mysql.user' table, so that the changes take immediate effect. Without *Note `FLUSH PRIVILEGES': flush, the changes do not take effect until the next time that the server is restarted. *Note*: Many of the MySQL Cluster utilities such as *Note `ndb_show_tables': mysql-cluster-programs-ndb-show-tables, *Note `ndb_desc': mysql-cluster-programs-ndb-desc, and *Note `ndb_select_all': mysql-cluster-programs-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 *Note mysql-cluster-programs::, for more information about these utilities.  File: manual.info, Node: mysql-cluster-disk-data, Next: mysql-cluster-online-add-node, Prev: mysql-cluster-security, Up: mysql-cluster-management 17.5.12 MySQL Cluster Disk Data Tables -------------------------------------- * Menu: * mysql-cluster-disk-data-objects:: MySQL Cluster Disk Data Objects * mysql-cluster-disk-data-symlinks:: Using Symbolic Links with Disk Data Objects * mysql-cluster-disk-data-storage-requirements:: MySQL Cluster Disk Data Storage Requirements Beginning with MySQL 5.1.6, it is possible to store the nonindexed columns of *Note `NDB': mysql-cluster. tables on disk, rather than in RAM as with previous versions of MySQL Cluster. As part of implementing MySQL Cluster Disk Data work, a number of improvements were made in MySQL 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 MySQL Cluster 5.1 (http://www.vldb2005.org/program/paper/wed/p1108-ronstrom.pdf)', by MySQL Cluster developers Mikael Ronstro"m and Jonas Oreland. MySQL Cluster Disk Data performance can be influenced by a number of configuration parameters. For information about these parameters and their effects, see `MySQL Cluster Disk Data configuration parameters' and `MySQL Cluster Disk Data storage and `GCP Stop' errors' The performance of a MySQL 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 *Note mysql-cluster-disk-data-symlinks::.  File: manual.info, Node: mysql-cluster-disk-data-objects, Next: mysql-cluster-disk-data-symlinks, Prev: mysql-cluster-disk-data, Up: mysql-cluster-disk-data 17.5.12.1 MySQL Cluster Disk Data Objects ......................................... MySQL 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 MySQL 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. MySQL 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 a MySQL Cluster with all nodes (including management and SQL nodes) running MySQL 5.1.6 or newer, the basic steps for creating a 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*: In MySQL 5.1 and later, undo log files are necessary only for Disk Data tables. They are no longer used for *Note `NDBCLUSTER': mysql-cluster. 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 *Note `mysql': 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 *Note `CREATE LOGFILE GROUP': 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 *Note `CREATE LOGFILE GROUP': 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 *Note `ALTER LOGFILE GROUP': 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 *Note `CREATE LOGFILE GROUP': create-logfile-group. and *Note `ALTER LOGFILE GROUP': alter-logfile-group. statement must include an `ENGINE' clause. In MySQL 5.1 (including MySQL Cluster NDB 6.X and 7.X through 7.1), the permitted values for this clause are *Note `NDBCLUSTER': mysql-cluster. and *Note `NDB': mysql-cluster. *Important*: In MySQL 5.1.8 and later, there can exist only one log file group in the same MySQL 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 a MySQL Cluster has 4 data nodes, then the *Note `ALTER LOGFILE GROUP': 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 *Note `CREATE LOGFILE GROUP': create-logfile-group. statement, see *Note create-logfile-group::. For more information about *Note `ALTER LOGFILE GROUP': alter-logfile-group, see *Note alter-logfile-group::. 2. Now we can create a tablespace, which contains files to be used by MySQL 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 *Note `CREATE TABLESPACE': 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 *Note `ALTER TABLESPACE': 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 a MySQL Cluster has 4 data nodes, then the *Note `ALTER TABLESPACE': 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 *Note `CREATE TABLESPACE': create-tablespace. and *Note `ALTER TABLESPACE': alter-tablespace. statements must contain an `ENGINE' clause; only tables using the same storage engine as the tablespace can be created in the tablespace. In MySQL 5.1 (including MySQL Cluster NDB 6.X and 7.X through 7.1), the only permitted values for this clause are *Note `NDBCLUSTER': mysql-cluster. and *Note `NDB': mysql-cluster. * For more information about the *Note `CREATE TABLESPACE': create-tablespace. and *Note `ALTER TABLESPACE': alter-tablespace. statements, see *Note create-tablespace::, and *Note 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 *Note `NDBCLUSTER': mysql-cluster. storage engine to use tablespace `ts_1' for disk data storage. *Note*: Beginning with MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB 6.3.2, 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 *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. statement. `STORAGE DISK' causes the column to be stored on disk, and `STORAGE MEMORY' causes in-memory storage to be used. See *Note create-table::, for more information. Once table `ts_1' has been created as shown, you can perform *Note `INSERT': insert, *Note `SELECT': select, *Note `UPDATE': update, and *Note `DELETE': delete. statements on it just as you would with any other MySQL table. For table `dt_1' as it has been defined here, 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. In MySQL 5.1 (including MySQL Cluster NDB 6.X and 7.X through 7.1), 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. 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 *Note 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. * Beginning with MySQL 5.1.12, it is no longer 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 *Note `FILES': files-table. table in the `INFORMATION_SCHEMA' database. An extra ``NULL' row' was added to this table in MySQL 5.1.14 for providing additional information about undo log files. For more information and examples of use, see *Note files-table::. Beginning with MySQL Cluster NDB 6.3.27 and MySQL Cluster NDB 7.0.8, it is also possible to view information about allocated and free disk space for each Disk Data table or table partition using the *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility. For more information, see *Note mysql-cluster-programs-ndb-desc::.  File: manual.info, Node: mysql-cluster-disk-data-symlinks, Next: mysql-cluster-disk-data-storage-requirements, Prev: mysql-cluster-disk-data-objects, Up: mysql-cluster-disk-data 17.5.12.2 Using Symbolic Links with Disk Data Objects ..................................................... The performance of a MySQL 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. Previous to MySQL Cluster NDB 6.2.17, MySQL Cluster NDB 6.3.22, and MySQL Cluster NDB 6.4.3, there was no direct support for this in MySQL Cluster, but it was possible to achieve this separation using symbolic links as described in this section. Beginning with MySQL Cluster NDB 6.2.17, MySQL Cluster NDB 6.3.22, and MySQL Cluster NDB 6.4.3, the data node configuration parameters `FileSystemPathDD', `FileSystemPathDataFiles', and `FileSystemPathUndoFiles' make the use of symbolic links for this purpose unnecessary. For information about these parameters, see *Note 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 *Note `mysql': 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  File: manual.info, Node: mysql-cluster-disk-data-storage-requirements, Prev: mysql-cluster-disk-data-symlinks, Up: mysql-cluster-disk-data 17.5.12.3 MySQL 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 *Note storage-requirements::. You can obtain an estimate the amount of space available in data files and undo log files by querying the *Note `INFORMATION_SCHEMA.FILES': files-table. table. For more information and examples, see *Note files-table::. *Note*: The *Note `OPTIMIZE TABLE': optimize-table. statement does not have any effect on Disk Data tables. * In a Disk Data table, the first 256 bytes of a *Note `TEXT': blob. or *Note `BLOB': 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 *Note `diskpagebuffer': mysql-cluster-ndbinfo-diskpagebuffer. table to help determine whether the value for this parameter needs to be increased.  File: manual.info, Node: mysql-cluster-online-add-node, Next: mysql-cluster-privilege-distribution, Prev: mysql-cluster-disk-data, Up: mysql-cluster-management 17.5.13 Adding MySQL Cluster Data Nodes Online ---------------------------------------------- * Menu: * mysql-cluster-online-add-node-remarks:: Adding MySQL Cluster Data Nodes Online: General Issues * mysql-cluster-online-add-node-basics:: Adding MySQL Cluster Data Nodes Online: Basic procedure * mysql-cluster-online-add-node-example:: Adding MySQL Cluster Data Nodes Online: Detailed Example This section describes how to add MySQL Cluster data nodes `online'--that is, without needing to shut down the cluster completely and restart it as part of the process. This capability is available in MySQL Cluster NDB 7.0 (beginning with MySQL Cluster NDB 6.4.0) and later MySQL Cluster release series. *Important*: Currently, you must add new data nodes to a MySQL 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.  File: manual.info, Node: mysql-cluster-online-add-node-remarks, Next: mysql-cluster-online-add-node-basics, Prev: mysql-cluster-online-add-node, Up: mysql-cluster-online-add-node 17.5.13.1 Adding MySQL Cluster Data Nodes Online: General Issues ................................................................ This section provides general information about the behavior of and current limitations in adding MySQL Cluster nodes online. Redistribution of Data The ability to add new nodes online includes a means to reorganize *Note `NDBCLUSTER': mysql-cluster. table data and indexes so that they are distributed across all data nodes, including the new ones, by means of the *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table-partition-operations. 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). Prior to MySQL Cluster NDB 7.0.40 and MySQL Cluster NDB 7.1.28, `BLOB' table data is also not redistributed using this method (Bug #13714148). The redistribution for *Note `NDBCLUSTER': mysql-cluster. tables already existing before the new data nodes were added is not automatic, but can be accomplished using simple SQL statements in *Note `mysql': 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 MySQL 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 *Note `ALTER TABLE ... REORGANIZE PARTITION': alter-table. 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: This table describes how data node failures during node group creation and table reorganization are handled. The first column identifies when the failure occurs (during node group creation or table reorganization). The second column describes where the failures occur and is divided into three sub columns (Old data nodes, New data nodes, and System). Failure occurs Failure occurs in: during: `Old' data nodes `New' data nodes System Node group * If a node * If a node * If the creation other than other than execution of the master the master `CREATE fails: fails: NODEGROUP' has reached The creation The creation the internal of the node of the node commit point: group is group is always rolled always rolled When forward. forward. restarted, the cluster * If the * If the includes the master fails: master fails: new node group. * If the * If the Otherwise it internal internal without. commit commit point point * If the has has execution of been been `CREATE reached: reached: NODEGROUP' has not yet The The reached the creation creation internal of the of the commit 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 not has 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 * If a node * If a node * If the reorganization other than other than execution of the master the master an `ALTER fails: fails: ONLINE TABLE TABLE The table The table REORGANIZE reorganization reorganization PARTITION' is always is always statement rolled rolled has reached forward. forward. the internal commit point: * If the * If the master fails: master fails: When the cluster is * If the * If the restarted, internal internal the data and commit commit indexes point point belonging to has has TABLE are been been distributed reached: reached: using the `new' data The The nodes. table table reorganization reorganization * If the is is execution of rolled rolled an `ALTER forward. forward. ONLINE TABLE TABLE * If the * If the REORGANIZE internal internal PARTITION' commit commit statement point point has not yet has not has not reached the yet yet internal been been commit point: reached reached When the The The cluster is table table restarted, reorganization reorganization the data and is is indexes rolled rolled belonging to back. back. TABLE are distributed using only the `old' data nodes. Dropping node groups The *Note `ndb_mgm': mysql-cluster-programs-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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client, but before issuing any *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table. statements in the *Note `mysql': mysql. client. 2. After dropping all *Note `NDBCLUSTER': mysql-cluster. tables using *Note `DROP TABLE': drop-table. *Note `TRUNCATE TABLE': truncate-table. does not work for this purpose because the data nodes continue to store the table definitions.  File: manual.info, Node: mysql-cluster-online-add-node-basics, Next: mysql-cluster-online-add-node-example, Prev: mysql-cluster-online-add-node-remarks, Up: mysql-cluster-online-add-node 17.5.13.2 Adding MySQL Cluster Data Nodes Online: Basic procedure ................................................................. In this section, we list the basic steps required to add new data nodes to a MySQL Cluster. For a detailed example, see *Note mysql-cluster-online-add-node-example::. *Note*: Beginning with MySQL Cluster NDB 7.0.4, this procedure applies whether you are using *Note `ndbd': mysql-cluster-programs-ndbd. or *Note `ndbmtd': mysql-cluster-programs-ndbmtd. binaries for the data node processes. Previously, this did not work with multi-threaded data nodes. (Bug #43108) Assuming that you already have a running MySQL 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 MySQL 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 MySQL 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 MySQL 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 MySQL 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) by issuing an *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table. statement in the *Note `mysql': mysql. client for each *Note `NDBCLUSTER': mysql-cluster. table. *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 using *Note `ALTER ONLINE TABLE tbl REORGANIZE PARTITION': alter-table. 8. Reclaim the space freed on the `old' nodes by issuing, for each *Note `NDBCLUSTER': mysql-cluster. table, an *Note `OPTIMIZE TABLE': optimize-table. statement in the *Note `mysql': mysql. client. You can add all the nodes desired, then issue several `CREATE NODEGROUP' commands in succession to add the new node groups to the cluster. Prior to MySQL Cluster NDB 7.0.16 and MySQL Cluster NDB 7.1.5, when adding multiple new node groups to a MySQL Cluster, it was necessary to add only the nodes to be assigned to a given new node group, create that node group using `CREATE NODEGROUP', then repeat this process for each new node group to be added to the cluster. (Bug #54497)  File: manual.info, Node: mysql-cluster-online-add-node-example, Prev: mysql-cluster-online-add-node-basics, Up: mysql-cluster-online-add-node 17.5.13.3 Adding MySQL Cluster Data Nodes Online: Detailed Example .................................................................. In this section we provide a detailed example illustrating how to add new MySQL Cluster data nodes online, starting with a MySQL 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 = 192.168.0.1 [ndbd] Id = 2 HostName = 192.168.0.2 [mgm] HostName = 192.168.0.10 Id = 10 [api] Id=20 HostName = 192.168.0.20 [api] Id=21 HostName = 192.168.0.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: 192.168.0.10:1186 Cluster Configuration --------------------- [ndbd(NDB)] 2 node(s) id=1 @192.168.0.1 (5.1.71-ndb-7.1.29, Nodegroup: 0, Master) id=2 @192.168.0.2 (5.1.71-ndb-7.1.29, Nodegroup: 0) [ndb_mgmd(MGM)] 1 node(s) id=10 @192.168.0.10 (5.1.71-ndb-7.1.29) [mysqld(API)] 2 node(s) id=20 @192.168.0.20 (5.1.71-ndb-7.1.29) id=21 @192.168.0.21 (5.1.71-ndb-7.1.29) Finally, we assume that the cluster contains a single *Note `NDBCLUSTER': mysql-cluster. 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 *Note `ndbd': mysql-cluster-programs-ndbd. being used for the data node processes. However--beginning with MySQL Cluster NDB 7.0.4--you can also apply this example, if you are using the multi-threaded *Note `ndbmtd': mysql-cluster-programs-ndbmtd. by substituting *Note `ndbmtd': mysql-cluster-programs-ndbmtd. for *Note `ndbd': mysql-cluster-programs-ndbd. wherever it appears in the steps that follow. (Bug #43108) 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 192.168.0.3 and 192.168.0.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 = 192.168.0.1 [ndbd] Id = 2 HostName = 192.168.0.2 *[ndbd] Id = 3 HostName = 192.168.0.3 [ndbd] Id = 4 HostName = 192.168.0.4* [mgm] HostName = 192.168.0.10 Id = 10 [api] Id=20 HostName = 192.168.0.20 [api] Id=21 HostName = 192.168.0.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.1.71-ndb-7.1.29 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. process, you should now see something like this: -- NDB Cluster -- Management Client -- ndb_mgm> SHOW Connected to Management Server at: 192.168.0.10:1186 Cluster Configuration --------------------- [ndbd(NDB)] 2 node(s) id=1 @192.168.0.1 (5.1.71-ndb-7.1.29, Nodegroup: 0, Master) id=2 @192.168.0.2 (5.1.71-ndb-7.1.29, Nodegroup: 0) id=3 (not connected, accepting connect from 192.168.0.3) id=4 (not connected, accepting connect from 192.168.0.4) [ndb_mgmd(MGM)] 1 node(s) id=10 @192.168.0.10 (5.1.71-ndb-7.1.29) [mysqld(API)] 2 node(s) id=20 @192.168.0.20 (5.1.71-ndb-7.1.29) id=21 @192.168.0.21 (5.1.71-ndb-7.1.29) 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.1.29) Node 1: Started (version 7.1.29) 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.1.29) ndb_mgm> Node 2: Started (version 7.1.29) *Important*: After issuing each `X RESTART' command, wait until the management client reports `Node X: Started (version ...)' _before_ proceeding any further. Beginning with MySQL Cluster NDB 7.0.24 and MySQL Cluster NDB 7.1.13, you can verify that all existing data nodes were restarted using the updated configuration by checking the *Note `ndbinfo.nodes': mysql-cluster-ndbinfo-nodes. table in the *Note `mysql': 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 *Note `mysqladmin shutdown': mysqladmin. followed by *Note `mysqld_safe': 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=192.168.0.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 192.168.0.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: 192.168.0.10:1186 Cluster Configuration --------------------- [ndbd(NDB)] 2 node(s) id=1 @192.168.0.1 (5.1.71-ndb-7.1.29, Nodegroup: 0, Master) id=2 @192.168.0.2 (5.1.71-ndb-7.1.29, Nodegroup: 0) id=3 @192.168.0.3 (5.1.71-ndb-7.1.29, *no nodegroup*) id=4 @192.168.0.4 (5.1.71-ndb-7.1.29, *no nodegroup*) [ndb_mgmd(MGM)] 1 node(s) id=10 @192.168.0.10 (5.1.71-ndb-7.1.29) [mysqld(API)] 2 node(s) id=20 @192.168.0.20 (5.1.71-ndb-7.1.29) id=21 @192.168.0.21 (5.1.71-ndb-7.1.29) 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: 192.168.0.10:1186 Cluster Configuration --------------------- [ndbd(NDB)] 2 node(s) id=1 @192.168.0.1 (5.1.71-ndb-7.1.29, Nodegroup: 0, Master) id=2 @192.168.0.2 (5.1.71-ndb-7.1.29, Nodegroup: 0) id=3 @192.168.0.3 (5.1.71-ndb-7.1.29, *Nodegroup: 1*) id=4 @192.168.0.4 (5.1.71-ndb-7.1.29, *Nodegroup: 1*) [ndb_mgmd(MGM)] 1 node(s) id=10 @192.168.0.10 (5.1.71-ndb-7.1.29) [mysqld(API)] 2 node(s) id=20 @192.168.0.20 (5.1.71-ndb-7.1.29) id=21 @192.168.0.21 (5.1.71-ndb-7.1.29) 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 *Note `ndb_desc': mysql-cluster-programs-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 192.168.0.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 *Note `NDBCLUSTER': mysql-cluster. table, an *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table. statement in the *Note `mysql': mysql. client. After issuing the statement `ALTER ONLINE TABLE ips REORGANIZE PARTITION', you can see using *Note `ndb_desc': mysql-cluster-programs-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 192.168.0.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, *Note `ALTER [ONLINE] TABLE TABLE_NAME REORGANIZE PARTITION': alter-table. 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 MySQL Cluster node group is an exception in this regard; when used in this way, only the name of the table is used following the `TABLE' keyword, and no other keywords or identifiers follow `REORGANIZE PARTITION'. Prior to MySQL Cluster NDB 6.4.3, *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table. with no `PARTITION_NAMES INTO (PARTITION_DEFINITIONS)' option did not work correctly with Disk Data tables or with in-memory *Note `NDBCLUSTER': mysql-cluster. tables having one or more disk-based columns. (Bug #42549) For more information, see *Note alter-table::. In addition, for each table, the *Note `ALTER ONLINE TABLE': alter-table. statement should be followed by an *Note `OPTIMIZE TABLE': optimize-table. to reclaim wasted space. You can obtain a list of all *Note `NDBCLUSTER': mysql-cluster. tables using the following query against the *Note `INFORMATION_SCHEMA.TABLES': tables-table. table: SELECT TABLE_SCHEMA, TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE ENGINE = 'NDBCLUSTER'; *Note*: The `INFORMATION_SCHEMA.TABLES.ENGINE' value for a MySQL Cluster table is always *Note `NDBCLUSTER': mysql-cluster, regardless of whether the `CREATE TABLE' statement used to create the table (or *Note `ALTER TABLE': alter-table. statement used to convert an existing table from a different storage engine) used *Note `NDB': mysql-cluster. or *Note `NDBCLUSTER': mysql-cluster. 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 *Note `NDBCLUSTER': mysql-cluster. tables can be executed at a time, you must wait for each *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table. statement to finish before issuing the next one. It is not necessary to issue *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table. statements for *Note `NDBCLUSTER': mysql-cluster. tables created _after_ the new data nodes have been added; data added to such tables is distributed among all data nodes automatically. However, in *Note `NDBCLUSTER': mysql-cluster. 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 *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table. 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 = 192.168.0.1 [ndbd] Id = 2 HostName = 192.168.0.2 [ndbd] Id = 3 HostName = 192.168.0.3 Nodegroup = 65536 # MySQL Cluster NDB 7.0.24 and later; # MySQL Cluster NDB 7.1.13 and later [ndbd] Id = 4 HostName = 192.168.0.4 Nodegroup = 65536 # MySQL Cluster NDB 7.0.24 and later; # MySQL Cluster NDB 7.1.13 and later [mgm] HostName = 192.168.0.10 Id = 10 [api] Id=20 HostName = 192.168.0.20 [api] Id=21 HostName = 192.168.0.21 Prior to MySQL Cluster NDB 7.0.24 and MySQL Cluster NDB 7.1.13, you must perform the initial start of the cluster using the `--nowait-nodes' option with *Note `ndbd': mysql-cluster-programs-ndbd. (or *Note `ndbmtd': mysql-cluster-programs-ndbmtd. in MySQL Cluster NDB 7.0.4 and later) for each of the data nodes that you wish to have online immediately, so that the cluster does not wait for the remaining nodes to start: shell> ndbd -c 192.168.0.10 --initial --nowait-nodes=3,4 Beginning with MySQL Cluster NDB 7.0.24 and MySQL Cluster NDB 7.1.13, the data nodes to be brought online at a later time (nodes 3 and 4) can be configured with `NodeGroup = 65536', in which case it is not necessary to start the nodes to be started immediately (nodes 1 and 2) with the `--nowait-nodes' option, so nodes 1 and 2 can each be started as shown here: shell> ndbd -c 192.168.0.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 (also introduced in MySQL Cluster NDB 7.0.24 and MySQL Cluster NDB 7.1.13). 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 192.168.0.10 --initial 2. Issue the appropriate `CREATE NODEGROUP' command in the management client: ndb_mgm> CREATE NODEGROUP 3,4 3. In the *Note `mysql': mysql. client, issue *Note `ALTER ONLINE TABLE ... REORGANIZE PARTITION': alter-table. and *Note `OPTIMIZE TABLE': optimize-table. statements for each existing *Note `NDBCLUSTER': mysql-cluster. table. (As noted elsewhere in this section, existing MySQL Cluster tables cannot use the new nodes for data distribution until this has been done.)  File: manual.info, Node: mysql-cluster-privilege-distribution, Next: mysql-cluster-ndb-api-statistics, Prev: mysql-cluster-online-add-node, Up: mysql-cluster-management 17.5.14 Distributed MySQL Privileges for MySQL Cluster ------------------------------------------------------ MySQL Cluster NDB 7.2 introduces support for distributing MySQL users and privileges across all SQL nodes in a MySQL 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 *Note `MyISAM': myisam-storage-engine. 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. In MySQL Cluster NDB 7.2 and later, an SQL file `ndb_dist_priv.sql' is provided with the MySQL Cluster distribution. This file can be found in the `share/mysql' 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/mysql/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 *Note `mysql': 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 *Note `NDB': mysql-cluster. Two sets of copies are created in the `mysql' database: * A set of local copies that use the *Note `MyISAM': myisam-storage-engine. storage engine, and named by adding the suffix `_backup' to the original privilege table names. * A set of distributed copies (using *Note `NDBCLUSTER': mysql-cluster.). These tables are named by prefixing `ndb_' and appending `_backup' to the names of the original tables. 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 *Note `mysqldump': mysqldump. in a manner similar to what is shown here: shell> mysqldump OPTIONS -uroot \ mysql host 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 *Note `mysql': 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 | +-------------------------+------------+ | host_backup | MyISAM | | db_backup | MyISAM | | columns_priv_backup | MyISAM | | user_backup | MyISAM | | tables_priv_backup | MyISAM | | proxies_priv_backup | MyISAM | | procs_priv_backup | MyISAM | | ndb_user_backup | ndbcluster | | ndb_tables_priv_backup | ndbcluster | | ndb_proxies_priv_backup | ndbcluster | | ndb_procs_priv_backup | ndbcluster | | ndb_host_backup | ndbcluster | | ndb_db_backup | ndbcluster | | ndb_columns_priv_backup | ndbcluster | +-------------------------+------------+ 14 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 *Note `FLUSH PRIVILEGES': flush. 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 privileges associated with views and stored routines. While automatic distribution of views and stored routines is not currently supported, you can attempt to distribute stored routines by issuing a statement such as *Note `ALTER TABLE mysql.proc ENGINE = NDB': alter-table, but you must verify manually that any tables referenced by the stored routines exist on all SQL nodes, since MySQL Cluster has no support at the present time for doing this automatically. There is currently no way to distribute views among MySQL Cluster SQL nodes, other than by creating them manually on each SQL node. If you do this, you must make certain that all base tables referenced by the views use the *Note `NDB': mysql-cluster. storage engine; otherwise, the views are likely to diverge very quickly. 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 *Note `DROP TABLE IF EXISTS mysql.user mysql.db mysql.tables_priv mysql.columns_priv mysql.procs_priv': drop-table. 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 *Note `mysqldump': 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 *Note `ndb_restore': mysql-cluster-programs-ndb-restore. `--restore-privilege-tables' from a backup made using `START BACKUP' in the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client. (The *Note `MyISAM': myisam-storage-engine. tables created by `mysql_cluster_move_privileges' are not backed up by the `START BACKUP' command.) *Note `ndb_restore': mysql-cluster-programs-ndb-restore. does not restore the privilege tables by default; the `--restore-privilege-tables' option causes it to do so. *Important*: Applications that access MySQL 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 *Note `NDB': mysql-cluster. 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_.  File: manual.info, Node: mysql-cluster-ndb-api-statistics, Prev: mysql-cluster-privilege-distribution, Up: mysql-cluster-management 17.5.15 NDB API Statistics Counters and Variables ------------------------------------------------- Beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, 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 added. 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. *Note `mysqld': mysqld. exposes these counters as system status variables; their values can be read in the output of *Note `SHOW STATUS': show-status, or by querying the *Note `INFORMATION_SCHEMA.SESSION_STATUS': status-table. or *Note `INFORMATION_SCHEMA.GLOBAL_STATUS': status-table. table. By comparing the values before and after statements operating on *Note `NDB': mysql-cluster. 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 *Note `SHOW STATUS': 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 *Note `SESSION_STATUS': status-table. and *Note `GLOBAL_STATUS': status-table. 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 *Note `mysql': mysql. client_. This means that specifying the `SESSION' or `GLOBAL' keyword with *Note `SHOW STATUS': 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 *Note `SESSION_STATUS': status-table. or the *Note `GLOBAL_STATUS': status-table. 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 *Note `mysqld': mysqld. does not act as a replication slave, or does not use *Note `NDB': mysql-cluster. 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 binlog injector thread. Even when not writing a binary log, *Note `mysqld': mysqld. processes attached to a MySQL 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 *Note `mysqld': mysqld. This includes all MySQL client applications, the slave SQL thread (if any), the binlog injector, and the *Note `NDB': mysql-cluster. utility thread. We refer to the status variables that correspond to these counters as `global variables' or `*Note `mysqld': 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 *Note `mysqld': 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 *Note `mysqld': 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. The first column of this table lists NDB API statistics counter names. The second column, the rows of which are split into two cells, provides a description of statistics counter in the first cell, followed by a list of corresponding MySQL server status variables in the second cell. Status variables are listed by type in the following order: Session, Slave, Injector, Server. Counter Name Description Status Variables (by statistic type): * Session * Slave * Injector * Server `WaitExecCompleteCount' Number of times thread has been blocked while waiting for execution of an operation to complete. Includes all `execute()' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-methods.html#ndb-ndbtransaction-execute) calls as well as implicit executes for blob operations and auto-increment not visible to clients. * `Ndb_api_wait_exec_complete_count_session' * `Ndb_api_wait_exec_complete_count_slave' * [none] * `Ndb_api_wait_exec_complete_count' `WaitScanResultCount' Number of times thread has been blocked while waiting for a scan-based signal, such waiting for additional results, or for a scan to close. * `Ndb_api_wait_scan_result_count_session' * `Ndb_api_wait_scan_result_count_slave' * [none] * `Ndb_api_wait_scan_result_count' `WaitMetaRequestCount' Number of times thread has been blocked waiting for a metadata-based signal; this can occur when waiting for a DDL operation or for an epoch to be started (or ended). * `Ndb_api_wait_meta_request_count_session' * `Ndb_api_wait_meta_request_count_slave' * [none] * `Ndb_api_wait_meta_request_count' `WaitNanosCount' Total time (in nanoseconds) spent waiting for some type of signal from the data nodes. * `Ndb_api_wait_nanos_count_session' * `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 sum of `TransCommitCount' and `TransAbortCount'.) * `Ndb_api_trans_close_count_session' * `Ndb_api_trans_close_count_slave' * [none] * `Ndb_api_trans_close_count' `PkOpCount' Number of operations based on or using primary keys. This count includes blob-part table operations, implicit unlocking operations, and auto-increment operations, as well as primary key operations normally visible to MySQL clients. * `Ndb_api_pk_op_count_session' * `Ndb_api_pk_op_count_slave' * [none] * `Ndb_api_pk_op_count' `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 internal tables. * `Ndb_api_table_scan_count_session' * `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 is a set of scan results from a single fragment.) * `Ndb_api_scan_batch_count_session' * `Ndb_api_scan_batch_count_slave' * [none] * `Ndb_api_scan_batch_count' `ReadRowCount' Total number of rows that have been read. Includes rows read using primary key, unique key, and scan operations. * `Ndb_api_read_row_count_session' * `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 transaction was being run. * `Ndb_api_trans_local_read_row_count_session' * `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 row change events. * [none] * [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 *Note `SHOW STATUS': 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 *Note `mysql': mysql. client session, and 2 transactions have been committed on this *Note `mysqld': 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 *Note `SHOW STATUS': show-status, we create in the `test' database an *Note `NDB': mysql-cluster. 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 *Note `SHOW STATUS': 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 *Note `SHOW STATUS': 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 *Note `NDB': mysql-cluster. storage engine. * By comparing successive values for `Ndb_api_wait_nanos_count_session', we can see that the NDB API operations implementing the *Note `CREATE TABLE': 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 *Note `INSERT': insert. (707370418 - 706871709 = 498709 ns or roughly .0005 second). The execution times reported for these statements in the *Note `mysql': mysql. client correlate roughly with these figures. On platforms with 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 *Note `INSERT': 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'.  File: manual.info, Node: mysql-cluster-replication, Next: mysql-cluster-news, Prev: mysql-cluster-management, Up: mysql-cluster 17.6 MySQL Cluster Replication ============================== * Menu: * mysql-cluster-replication-abbreviations:: MySQL Cluster Replication: Abbreviations and Symbols * mysql-cluster-replication-general:: General Requirements for MySQL Cluster Replication * mysql-cluster-replication-issues:: Known Issues in MySQL Cluster Replication * mysql-cluster-replication-schema:: MySQL Cluster Replication Schema and Tables * mysql-cluster-replication-preparation:: Preparing the MySQL Cluster for Replication * mysql-cluster-replication-starting:: Starting MySQL Cluster Replication (Single Replication Channel) * mysql-cluster-replication-two-channels:: Using Two Replication Channels for MySQL Cluster Replication * mysql-cluster-replication-failover:: Implementing Failover with MySQL Cluster Replication * mysql-cluster-replication-backups:: MySQL Cluster Backups With MySQL Cluster Replication * mysql-cluster-replication-multi-master:: MySQL Cluster Replication: Multi-Master and Circular Replication * mysql-cluster-replication-conflict-resolution:: MySQL Cluster Replication Conflict Resolution Previous to MySQL 5.1.6, _asynchronous replication_, more usually referred to simply as `replication', was not available when using MySQL Cluster. MySQL 5.1.6 introduces master-slave replication of this type for MySQL Cluster databases. This section explains how to set up and manage a configuration wherein one group of computers operating as a MySQL 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 *Note replication::). 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 MySQL 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 a MySQL Cluster itself depends on the *Note `NDB': mysql-cluster. storage engine for clustering functionality, it is not necessary to use *Note `NDB': mysql-cluster. as the storage engine for the slave's copies of the replicated tables (see *Note mysql-cluster-replication-ndb-non-ndb::). However, for maximum availability, it is possible (and preferable) to replicate from one MySQL Cluster to another, and it is this scenario that we discuss, as shown in the following figure: MySQL 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 binlog 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 MySQL Cluster and MySQL Cluster Replication, see *Note mysql-cluster-replication-pitr::. NDB API `_slave' status variables Beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, NDB API counters provide enhanced monitoring capabilities on MySQL Cluster replication slaves. These are implelemented as NDB statistics `_slave' status variables, as seen in the output of *Note `SHOW STATUS': show-status, or in the results of queries against the *Note `SESSION_STATUS': status-table. or *Note `GLOBAL_STATUS': status-table. table in a *Note `mysql': mysql. client session connected to a MySQL Server that is acting as a slave in MySQL Cluster Replication. By comparing the values of these status variables before and after the execution of statements affecting replicated *Note `NDB': mysql-cluster. tables, you can observe the corresponding actions taken on the NDB API level by the slave, which can be useful when monitoring or troubleshooting MySQL Cluster Replication. *Note mysql-cluster-ndb-api-statistics::, provides additional information. Replication from `NDB' to non-`NDB' tables It is possible to replicate *Note `NDB': mysql-cluster. tables from a MySQL Cluster acting as the master to tables using other MySQL storage engines such as *Note `InnoDB': innodb-storage-engine. or *Note `MyISAM': myisam-storage-engine. on a slave *Note `mysqld': mysqld. However, because of differences between the version of *Note `mysqld': mysqld. provided with MySQL Cluster and that included with MySQL Server 5.1, the slave server must also use a *Note `mysqld': mysqld. binary from the MySQL Cluster distribution. See *Note mysql-cluster-replication-general::.  File: manual.info, Node: mysql-cluster-replication-abbreviations, Next: mysql-cluster-replication-general, Prev: mysql-cluster-replication, Up: mysql-cluster-replication 17.6.1 MySQL 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: This table lists abbreviations used throughout this section for symbols referring to master and slave clusters, and to processes and commands run on the clusters or cluster 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  File: manual.info, Node: mysql-cluster-replication-general, Next: mysql-cluster-replication-issues, Prev: mysql-cluster-replication-abbreviations, Up: mysql-cluster-replication 17.6.2 General Requirements for MySQL 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 a MySQL 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 started with `--binlog-format=ROW' or `--binlog-format=MIXED', as described in *Note mysql-cluster-replication-starting::. For general information about row-based replication, see *Note replication-formats::. *Important*: If you attempt to use MySQL 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 *Note 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. In all MySQL Cluster NDB 6.x and 7.x releases, the default value for the `--binlog-format' option 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 MySQL Cluster binaries are of the same release version. It is generally true in MySQL Replication that both MySQL servers (*Note `mysqld': 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 *Note replication-compatibility::). It is due to such differences between the binaries in the MySQL Cluster and MySQL Server 5.1 distributions that MySQL Cluster Replication has the additional requirement that both *Note `mysqld': mysqld. binaries come from a MySQL Cluster distribution. The simplest and easiest way to assure that the *Note `mysqld': mysqld. servers are compatible is to use the same MySQL Cluster distribution for all master and slave *Note `mysqld': 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. *Note*: It is possible to replicate a MySQL 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 *Note replication-sbr-rbr::, for more specific information concerning the differences between the two replication formats.  File: manual.info, Node: mysql-cluster-replication-issues, Next: mysql-cluster-replication-schema, Prev: mysql-cluster-replication-general, Up: mysql-cluster-replication 17.6.3 Known Issues in MySQL Cluster Replication ------------------------------------------------ This section discusses known problems or issues when using replication with MySQL Cluster in MySQL 5.1 (including MySQL Cluster NDB 6.X and 7.X through 7.1). 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. MySQL Cluster is not designed to perform such monitoring on its own; for this, an external application is required. Prior to MySQL 5.1.18, a MySQL Cluster replication slave *Note `mysqld': mysqld. had no way of detecting that the connection from the master had been interrupted. For this reason, it was possible for the slave to become inconsistent with the master. Beginning with MySQL 5.1.18, 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 *Note `SHOW SLAVE STATUS': 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 *Note mysql-cluster-replication-failover::, for more information about what to do in such circumstances. *Important*: Because MySQL 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 *Note `mysqld': 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 *Note mysql-cluster-replication-two-channels::, and *Note mysql-cluster-replication-failover::. However, if you are replicating from a standalone MySQL server to a MySQL Cluster, one channel is usually sufficient. Multi-byte character sets Previously, there were several known issues with regard to the use of multi-byte characters sets with MySQL Cluster Replication. These were resolved in MySQL 5.1.21, MySQL Cluster NDB 6.2.14, and MySQL Cluster NDB 6.3.11. (See Bug #27404 and Bug #29562.) Circular replication Prior to MySQL 5.1.18, circular replication was not supported with MySQL Cluster replication, due to the fact that all log events created in a particular MySQL Cluster were wrongly tagged with the server ID of the MySQL server used as master and not with the server ID of the originating server. Beginning with MySQL 5.1.18, this limitation is lifted, as discussed in the next few paragraphs, in which we consider the example of a replication setup involving three MySQL 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: MySQL Cluster circular replication scheme in which all master SQL nodes are also 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: MySQL Cluster circular replication scheme in which all master SQL nodes are not also necessarily 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 MySQL 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*: Beginning with MySQL 5.1.24, the *Note `NDB': mysql-cluster. storage engine uses _idempotent execution mode_, which suppresses duplicate-key and other errors that otherwise break circular replication of MySQL Cluster. This is equivalent to setting the global `slave_exec_mode' system variable to `IDEMPOTENT'. This is also required for multi-master replication when using MySQL Cluster. (Bug #31609) It is not necessary to set `slave_exec_mode' in MySQL Cluster replication; MySQL Cluster does this automatically for all *Note `NDB': mysql-cluster. tables and ignores any attempts to set this variable explicitly. MySQL Cluster replication and primary keys In MySQL 5.1.6, only those *Note `NDB': mysql-cluster. tables having explicit primary keys could be replicated. This limitation was lifted in MySQL 5.1.7. However, in the event of a node failure, errors in replication of *Note `NDB': mysql-cluster. 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 *Note `NDB': mysql-cluster. tables being replicated have primary keys. MySQL Cluster Replication and Unique Keys Prior to MySQL Cluster NDB 7.0.25 and MySQL Cluster NDB 7.1.14, operations that updated values of unique key columns of *Note `NDB': mysql-cluster. tables could result in duplicate-key errors when replicated. This was due to the ordering of row events in the binary log according to the partitioning of the base table, which meant that they could appear in a different order from that in which they were originally executed. (Bug #11756082) In MySQL Cluster NDB 7.0.25, MySQL Cluster NDB 7.1.14, and later, this issue is solved for replication between *Note `NDB': mysql-cluster. 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 *Note `NDB': mysql-cluster. Thus, updates of unique keys when replicating from *Note `NDB': mysql-cluster. to a different storage engine such as *Note `MyISAM': myisam-storage-engine. or *Note `InnoDB': innodb-storage-engine. are still not supported. The problem encountered when replicating without deferred checking of unique key updates can be illustrated using *Note `NDB': mysql-cluster. 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 *Note `UPDATE': 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*: In MySQL 5.1.6 and later, every *Note `NDB': mysql-cluster. table is implicitly partitioned by key when it is created. This also applies to all MySQL Cluster NDB 6.x and MySQL Cluster NDB 7.x releases. See *Note partitioning-key::, for more information. 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 MySQL 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 *Note `RESET MASTER': reset-master. and *Note `RESET SLAVE': reset-slave. statements to clear the invalid `ndb_binlog_index' and `ndb_apply_status' tables, respectively. `auto_increment_offset' and `auto_increment_increment' variables The use of the `auto_increment_offset' and `auto_increment_increment' server system variables is supported beginning with MySQL 5.1.20. Previously, these produced unpredictable results when used with *Note `NDB': mysql-cluster. tables or MySQL Cluster replication. Replication from `NDB' to other storage engines It is possible to replicate an *Note `NDB': mysql-cluster. 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 *Note `NDB': mysql-cluster. storage engine for this to work). * Using a storage engine 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 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 *Note `NDB': mysql-cluster. 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 MySQL Cluster and other storage engines. In addition, it is not possible to configure more than one replication channel when replicating between *Note `NDB': mysql-cluster. and a different storage engine. (However, a MySQL Cluster database _can_ simultaneously replicate to multiple slave MySQL Cluster databases.) If the master uses *Note `NDB': mysql-cluster. 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 a MySQL 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 *Note `ALTER TABLE mysql.ndb_apply_status ENGINE=MyISAM': alter-table. on the slave. It is safe to do this when using a non-*Note `NDB': mysql-cluster. 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 MySQL Cluster to another. See *Note mysql-cluster-replication-issues-filtering::, for details. Replication from `NDB' to a nontransactional storage engine When replicating from *Note `NDB': mysql-cluster. to a nontransactional storage engine such as *Note `MyISAM': myisam-storage-engine, you may encounter unnecessary duplicate key errors when replicating *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. statements. You can suppress these in MySQL Cluster NDB 6.2 and later MySQL Cluster releases by using `--ndb-log-update-as-write=0', which forces updates to be logged as writes (rather than as updates). In addition, when replicating from *Note `NDB': mysql-cluster. to a storage engine that does not implement transactions, if the slave fails to apply any row changes from a given transaction, it does not roll back the rest of the transaction. (This is true when replicating tables using any transactional storage engine--not only *Note `NDB': mysql-cluster.--to a nontransactional storage engine.) Because of this, it cannot be guaranteed that transactional consistency will be maintained on the slave in such cases. Replication and binary log filtering rules with replication between MySQL 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 MySQL 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 *Note 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 *Note binary-log::. If you are replicating a MySQL Cluster to a slave that uses a storage engine other than *Note `NDB': mysql-cluster, the considerations just given previously may not apply, as discussed elsewhere in this section. MySQL Cluster Replication and IPv6 Currently, the NDB API and MGM API do not support IPv6. However, beginning with MySQL Cluster NDB 6.4.1, MySQL Servers--including those acting as SQL nodes in a MySQL Cluster--can use IPv6 to contact other MySQL Servers. This means that you can replicate between MySQL Clusters using IPv6 to connect the master and slave SQL nodes as shown by the dotted arrow in the following diagram: IPv6 Used to Connect Between MySQL Cluster SQL Nodes in Replication However, all connections originating _within_ the MySQL Cluster--represented in the preceding diagram by solid arrows--must use IPv4. In other words, all MySQL 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 Formerly, support in MySQL Cluster for type conversions between columns of similar but different types on the master and the slave was extremely limited. However, starting with MySQL Cluster NDB 6.3.33, 7.0.14, and 7.1.3, MySQL 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 MySQL Cluster, see *Note replication-features-attribute-promotion::.  File: manual.info, Node: mysql-cluster-replication-schema, Next: mysql-cluster-replication-preparation, Prev: mysql-cluster-replication-issues, Up: mysql-cluster-replication 17.6.4 MySQL Cluster Replication Schema and Tables -------------------------------------------------- Replication in MySQL 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 *Note `mysql_install_db': 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 `MyISAM' storage engine. This means that it must be created separately on each *Note `mysqld': 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` BIGINT(20) UNSIGNED NOT NULL, `updates` BIGINT(20) UNSIGNED NOT NULL, `deletes` BIGINT(20) UNSIGNED NOT NULL, `schemaops` BIGINT(20) UNSIGNED NOT NULL, `next_position` bigint(20) unsigned NOT NULL, `next_file` varchar(255) NOT NULL, PRIMARY KEY (`epoch`) ) ENGINE=MYISAM DEFAULT CHARSET=latin1; 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 binlog 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. It should be noted that, when the `--ndb-log-empty-epochs' option is `ON', then even empty epochs result in inserts to the `ndb_binlog_index' file, 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 MySQL Cluster writes to the binary log regularly and presumably rotates binary log files more quickly than a quiet one. This means that a `quiet' MySQL 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 *Note `mysqld': 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 MySQL Cluster replication setups employing multiple masters. The *Note `SELECT': select. statement used to to find the closest binlog position to the highest applied epoch on the slave in a multi-master setup (see *Note 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'. The `next_position' and `next_file' columns were added in MySQL Cluster NDB 7.2.6; see *Note mysql-cluster-replication-failover::, for more information about using these columns. *Important*: Prior to MySQL 5.1.14, the `ndb_binlog_index' table was known as `binlog_index', and was kept in a separate `cluster' database, which in MySQL 5.1.7 and earlier was known as the `cluster_replication' database. Similarly, the `ndb_apply_status' and `ndb_schema' tables were known as `apply_status' and `schema', and were also found in the `cluster' (earlier `cluster_replication') database. However, beginning with MySQL 5.1.14, all MySQL Cluster replication tables reside in the `mysql' system database. Information about how this change affects upgrades from MySQL Cluster 5.1.13 and earlier to 5.1.14 and later versions can be found in `http://dev.mysql.com/doc/relnotes/mysql/5.1/en/news-5-1-14.html'. Beginning with MySQL Cluster NDB 6.3.2, this table has been changed to facilitate 3-way replication recovery. Two columns `orig_server_id' and `orig_epoch' have been added to this table; when *Note `mysqld': mysqld. is started with the `--ndb-log-orig' option, these 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. In addition, the table's primary key now includes these two columns. The modified table definition is shown here: 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=MyISAM DEFAULT CHARSET=latin1; The `gci' column was added in MySQL Cluster NDB 6.2.6 and MySQL Cluster NDB 6.3.2. The `next_position' and `next_file' columns were added in MySQL Cluster NDB 7.0.33 and MySQL Cluster NDB 7.1.22; see *Note mysql-cluster-replication-failover::, for more information about using these columns. The following figure shows the relationship of the MySQL Cluster replication master server, its binlog injector thread, and the `mysql.ndb_binlog_index' table. The replication master cluster, the binlog injector thread, and the `ndb_binlog_index' table 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; This table is populated only on slaves; on the master, no `DataMemory' is allocated to it. Since 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 *Note mysql-cluster-replication-issues-filtering::. The `log_name', `start_pos', and `end_pos' columns were added in MySQL 5.1.18. *Important*: If you are using MySQL Cluster replication, see *Note mysql-cluster-upgrade-downgrade-compatibility-5.1:: before upgrading to MySQL 5.1.18 or later from an earlier version. 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 *Note `NDB': mysql-cluster. binary log (binlog) injector thread. This keeps the master *Note `mysqld': mysqld. process updated to changes performed by the *Note `NDB': mysql-cluster. storage engine. The *Note `NDB': mysql-cluster. _binlog injector thread_ receives events directly from the *Note `NDB': mysql-cluster. storage engine. The *Note `NDB': mysql-cluster. 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 a MySQL 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 *Note `SHOW BINLOG EVENTS': show-binlog-events. statement on either the replication master or slave MySQL servers. (See *Note show-binlog-events::.) You can also obtain useful information from the output of *Note `SHOW ENGINE NDB STATUS': show-engine. The `ndb_schema' table is used to track schema changes made to *Note `NDB': mysql-cluster. 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 *Note `SHOW': show. statements, or in any `INFORMATION_SCHEMA' tables; however, it can be seen in the output of *Note `ndb_show_tables': mysql-cluster-programs-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 *Note `SELECT': select. from this table in *Note `mysql': 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 *Note `NDB': mysql-cluster. tables, applications should wait until the *Note `ALTER TABLE': alter-table. statement has returned in the MySQL client connection that issued the statement before attempting to use the updated definition of the table. The `ndb_schema' table was added in MySQL 5.1.8. Beginning with MySQL 5.1.14, if the `ndb_apply_status' table or the `ndb_schema' table does not exist on the slave, *Note `ndb_restore': mysql-cluster-programs-ndb-restore. re-creates the missing table or tables (Bug #14612). Conflict resolution for MySQL 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 *Note mysql-cluster-replication-conflict-resolution::.  File: manual.info, Node: mysql-cluster-replication-preparation, Next: mysql-cluster-replication-starting, Prev: mysql-cluster-replication-schema, Up: mysql-cluster-replication 17.6.5 Preparing the MySQL Cluster for Replication -------------------------------------------------- Preparing the MySQL Cluster for replication consists of the following steps: 1. Check all MySQL servers for version compatibility (see *Note 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 *Note `GRANT': 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 *Note `CHANGE MASTER TO': 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 *Note 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 *Note mysql-cluster-replication-backups::, for details. For additional options that can be set in `my.cnf' for replication slaves, see *Note 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 MySQL Cluster, this can be accomplished using the backup and restore procedure described in *Note mysql-cluster-replication-backups::. ndb-connectstring=MANAGEMENT_HOST[:PORT] In the event that you are _not_ using MySQL 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 *Note `mysql': 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 *Note `mysqldump': 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 *Note `mysqldump': mysqldump, see *Note 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 *Note 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 *Note `mysqld': mysqld. process. See *Note mysql-cluster-replication-starting::, for information regarding the latter option.  File: manual.info, Node: mysql-cluster-replication-starting, Next: mysql-cluster-replication-two-channels, Prev: mysql-cluster-replication-preparation, Up: mysql-cluster-replication 17.6.6 Starting MySQL Cluster Replication (Single Replication Channel) ---------------------------------------------------------------------- This section outlines the procedure for starting MySQL 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 --binlog-format=ROW & In the previous statement, ID is this server's unique ID (see *Note mysql-cluster-replication-general::). This starts the server's *Note `mysqld': 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 MySQL Cluster Replication (see *Note 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 *Note `START SLAVE': 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 *Note 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 *Note `mysql': 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 *Note mysql-cluster-replication-two-channels::. Beginning with MySQL Cluster NDB 6.2.3, it is 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 *Note `mysqld': 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 *Note `SHOW VARIABLES': 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)  File: manual.info, Node: mysql-cluster-replication-two-channels, Next: mysql-cluster-replication-failover, Prev: mysql-cluster-replication-starting, Up: mysql-cluster-replication 17.6.7 Using Two Replication Channels for MySQL 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: This table lists server IDs (unique identifiers) for the MySQL cluster replication servers described in the preceding text. The table also provides a description of each cluster replication server. 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 *Note `mysqld': 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 *Note `START SLAVE': 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 --binlog-format=ROW & 2. Start the secondary replication master: shellM'> mysqld --ndbcluster --server-id=2 \ --log-bin --binlog-format=ROW & 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 *Note `START SLAVE': 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 *Note 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.  File: manual.info, Node: mysql-cluster-replication-failover, Next: mysql-cluster-replication-backups, Prev: mysql-cluster-replication-two-channels, Up: mysql-cluster-replication 17.6.8 Implementing Failover with MySQL 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; 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. Prior to MySQL Cluster NDB 7.0.33 and MySQL Cluster 7.1.22, you should use the following query to accomplish this task: mysqlM'> SELECT -> @file:=SUBSTRING_INDEX(File, '/', -1), -> @pos:=Position -> FROM mysql.ndb_binlog_index -> WHERE epoch > @latest -> ORDER BY epoch ASC LIMIT 1; Beginning with MySQL Cluster NDB 7.0.33 and MySQL Cluster NDB 7.1.22, you can take advantage of the improved binary logging of DDL statements implemented in those and later versions by using 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; In either case, 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 *Note `mysqld': 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*: If (and only if) you use the second of the two queries just shown against `ndb_binlog_index' (that is, the query that employs the `next_position' and `next_file' columns), you must ensure that the slave *Note `mysqld': mysqld. is started with `--slave-skip-errors=ddl_exist_errors' before executing *Note `START SLAVE': 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 *Note `mysqld': 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.  File: manual.info, Node: mysql-cluster-replication-backups, Next: mysql-cluster-replication-multi-master, Prev: mysql-cluster-replication-failover, Up: mysql-cluster-replication 17.6.9 MySQL Cluster Backups With MySQL Cluster Replication ----------------------------------------------------------- * Menu: * mysql-cluster-replication-auto-sync:: MySQL Cluster Replication: Automating Synchronization of the Replication Slave to the Master Binary Log * mysql-cluster-replication-pitr:: Point-In-Time Recovery Using MySQL Cluster Replication This section discusses making backups and restoring from them using MySQL Cluster replication. We assume that the replication servers have already been configured as covered previously (see *Note 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 *Note `NDB': mysql-cluster. 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 *Note mysql-cluster-install-configuration::, for more information about ports and port allocation in MySQL 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 *Note `NDB': mysql-cluster. 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 *Note 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 *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-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 *Note `CREATE DATABASE': create-database. (or *Note `CREATE SCHEMA': create-database.) 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; It is important to make sure that the slave's `apply_status' table does not contain any records prior to running the restore process. You can accomplish this by running this SQL statement on the slave: mysqlS> DELETE FROM mysql.ndb_apply_status; 5. You can now start the cluster restoration process on the replication slave using the *Note `ndb_restore': mysql-cluster-programs-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 *Note `ndb_restore': mysql-cluster-programs-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 *Note 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 *Note `ndb_restore': mysql-cluster-programs-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 *Note 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 *Note 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 *Note `SHOW MASTER STATUS': 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 *Note `CHANGE MASTER TO': change-master-to. statement in the slave's *Note `mysql': 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 `binlog' 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 *Note mysql-cluster-backup::.  File: manual.info, Node: mysql-cluster-replication-auto-sync, Next: mysql-cluster-replication-pitr, Prev: mysql-cluster-replication-backups, Up: mysql-cluster-replication-backups 17.6.9.1 MySQL 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 *Note 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  File: manual.info, Node: mysql-cluster-replication-pitr, Prev: mysql-cluster-replication-auto-sync, Up: mysql-cluster-replication-backups 17.6.9.2 Point-In-Time Recovery Using MySQL 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 MySQL Cluster tables with MySQL Cluster and MySQL Cluster Replication can be accomplished using a native *Note `NDB': mysql-cluster. data backup (taken by issuing `CREATE BACKUP' in the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client) and restoring the `ndb_binlog_index' table (from a dump made using *Note `mysqldump': mysqldump.). To perform point-in-time recovery of MySQL 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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client (see *Note 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 *Note `mysqldump': 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 *Note `ndbd': mysql-cluster-programs-ndbd. `--initial' or, in MySQL Cluster NDB 7.0 and later, *Note `ndbmtd': mysql-cluster-programs-ndbmtd. `--initial'). *Note*: MySQL Cluster Disk Data tablespace and log files are not removed by `--initial'. You must delete these manually. 6. Use *Note `DROP TABLE': drop-table. or *Note `TRUNCATE TABLE': truncate-table. with the `mysql.ndb_binlog_index' table. 7. Execute *Note `ndb_restore': mysql-cluster-programs-ndb-restore, restoring all data. You must include the `--restore_epoch' option when you run *Note `ndb_restore': mysql-cluster-programs-ndb-restore, so that the `ndb_apply_status' table is populated correctly. (See *Note mysql-cluster-programs-ndb-restore::, for more information.) 8. Restore the `ndb_binlog_index' table from the output of *Note `mysqldump': 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 _@LAST_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 > _@LAST_EPOCH_ ORDER BY epoch ASC LIMIT 1; 11. Using *Note `mysqlbinlog': mysqlbinlog, replay the binary log events from the given file and position up to the point of the failure. (See *Note mysqlbinlog::.) See also *Note point-in-time-recovery::, for more information about the binary log, replication, and incremental recovery.  File: manual.info, Node: mysql-cluster-replication-multi-master, Next: mysql-cluster-replication-conflict-resolution, Prev: mysql-cluster-replication-backups, Up: mysql-cluster-replication 17.6.10 MySQL Cluster Replication: Multi-Master and Circular Replication ------------------------------------------------------------------------ Beginning with MySQL 5.1.18, it is possible to use MySQL Cluster in multi-master replication, including circular replication between a number of MySQL Clusters. *Note*: Prior to MySQL 5.1.18, multi-master replication including circular replication was not supported with MySQL Cluster replication. This was because log events created in a particular MySQL Cluster were wrongly tagged with the server ID of the master rather than the server ID of the originating server. Circular replication example In the next few paragraphs we consider the example of a replication setup involving three MySQL 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: MySQL Cluster circular replication scheme in which all master SQL nodes are also 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: MySQL Cluster circular replication scheme in which all master SQL nodes are not also necessarily 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 MySQL 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. *Important*: Beginning with MySQL 5.1.24, you should execute the following statement before starting circular replication: mysql> SET GLOBAL SLAVE_EXEC_MODE = 'IDEMPOTENT'; This is necessary to suppress duplicate-key and other errors that otherwise break circular replication in MySQL Cluster. `IDEMPOTENT' mode is also required for multi-master replication when using MySQL Cluster. (Bug #31609) See `slave_exec_mode', for more information. Using NDB-native backup and restore to initialize a slave MySQL Cluster When setting up circular replication, it is possible to initialize the slave cluster by using the management client `BACKUP' command on one MySQL Cluster to create a backup and then applying this backup on another MySQL Cluster using *Note `ndb_restore': mysql-cluster-programs-ndb-restore. However, this does not automatically create binary logs on the second MySQL Cluster's SQL node acting as the replication slave. In order to cause the binary logs to be created, you must issue a *Note `SHOW TABLES': show-tables. statement on that SQL node; this should be done prior to running *Note `START SLAVE': 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 MySQL Cluster replication setup with three MySQL 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: Multi-master MySQL Cluster replication setup, with three MySQL Clusters 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 MySQL Cluster might use different SQL nodes for different replication channels. Such a case is shown here: Multi-master MySQL Cluster replication setup, detail with MySQL Servers MySQL servers acting as replication slaves must be run with the `--log-slave-updates' option. Which *Note `mysqld': 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 MySQL 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 *Note 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 *Note `CHANGE MASTER TO': 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 *Note `START SLAVE': start-slave. statement on MySQL server F, and any missing updates originating from server B will be replicated to server F. Beginning with MySQL Cluster MySQL Cluster NDB 6.1.29, MySQL Cluster NDB 6.3.31, MySQL Cluster NDB 7.0.11, and MySQL Cluster NDB 7.1.0, the *Note `CHANGE MASTER TO': 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 *Note change-master-to::, and *Note show-slave-status::.  File: manual.info, Node: mysql-cluster-replication-conflict-resolution, Prev: mysql-cluster-replication-multi-master, Up: mysql-cluster-replication 17.6.11 MySQL 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 MySQL 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 MySQL Cluster (`NDB$OLD()', `NDB$MAX()', `NDB$MAX_DELETE_WIN()') implement this user-defined column as a `timestamp' column (although its type cannot be *Note `TIMESTAMP': datetime, 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 introduced in MySQL Cluster NDB 7.1.16 (`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 *Note `mysqld': 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 *Note mysql-cluster-ndb-replication-table::). *Note*: If you are replicating tables with very large columns (such as *Note `TEXT': blob. or *Note `BLOB': 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 *Note 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', or none). This is done using the `mysql.ndb_replication' system table, on a per-table basis (see *Note mysql-cluster-ndb-replication-table::). * Prior to MySQL Cluster NDB 7.0.31 and MySQL Cluster NDB 7.1.20, conflict detection and resolution did not always work properly unless set up for *Note `NDB': mysql-cluster. tables created on the same server only (Bug #13578660). 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, but the data type of this column is never *Note `TIMESTAMP': datetime.; rather, its data type should be *Note `INT': integer-types. (*Note `INTEGER': integer-types.) or *Note `BIGINT': integer-types. The `timestamp' column should also be `UNSIGNED' and `NOT NULL'. 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 *Note `mysqld': 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 *Note `mysqld': mysqld, or start a new *Note `mysqld': mysqld. instance with different logging options. * Logging Full or Partial Rows (`--ndb-log-updated-only' Option) * Options for ndb_log_updated_only *Introduced* 5.1.19-ndb-6.3.0 *Command-Line Format* `--ndb-log-updated-only' *Option-File Format* `ndb_log_updated_only' *System Variable Name* `ndb_log_updated_only' *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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 *Note `mysqld': 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 * Options for ndb-log-update-as-write *Introduced* 5.1.19-ndb-6.3.0, 5.1.22-ndb-6.2.5 *Command-Line Format* `--ndb-log-update-as-write' *Option-File Format* `ndb-log-update-as-write' *System Variable Name* `ndb_log_update_as_write' *Variable Scope* Global *Dynamic Variable* Yes *Permitted Values* *Type* `boolean' *Default* `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 *Note `mysqld': mysqld. with `--ndb-log-update-as-write=0' or `--ndb-log-update-as-write=OFF'. 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. `table_name' The name of the table to be replicated. `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: This table lists `binlog_type' values and provides the internal value and a description for each. Value Internal Value Description 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 (equal to `NBT_UPDATED_ONLY values are unchanged | NBT_USE_UPDATE') 7 `NBT_FULL_USE_UPDATE' (equal Use full row, even if values are to `NBT_FULL | unchanged 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: * *Note mysql-cluster-replication-ndb-old:: * *Note mysql-cluster-replication-ndb-max:: * *Note mysql-cluster-replication-ndb-max-delete-win:: * *Note mysql-cluster-replication-ndb-epoch:: (MySQL Cluster NDB 7.1.16 and later) * *Note mysql-cluster-replication-ndb-epoch-trans:: (MySQL Cluster NDB 7.1.16 and later) * `NULL' 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(COLUMN_NAME') 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()' The `NDB$EPOCH()' function, available beginning with MySQL Cluster NDB 7.1.16, tracks the order in which replicated epochs are applied on a slave MySQL 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 MySQL 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 secondaryis 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 MySQL 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 MySQL 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 MySQL 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 exception table schema rules as described elsewhere in this section (see *Note mysql-cluster-replication-ndb-old::). Note that you need to create any exception 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 *Note mysql-cluster-ndb-replication-table::). The roles of the primary and secondary MySQL Clusters in this scenario are fully determined by `mysql.ndb_replication' table entries. *Note*: 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. `NDB$EPOCH()' and `NDB$EPOCH_TRANS()' status variables MySQL Cluster NDB 7.1.16 introduces several status variables that can be used to monitor `NDB$EPOCH()' and `NDB$EPOCH_TRANS()' 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()'; 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 *Note 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 MySQL 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 MySQL Clusters in a circular `active-active' configuration are currently supported when using `NDB$EPOCH()' or `NDB$EPOCH_TRANS()' for conflict detection. * Tables having *Note `BLOB': blob. or *Note `TEXT': blob. columns are not currently supported with `NDB$EPOCH()' or `NDB$EPOCH_TRANS()'. `NDB$EPOCH_TRANS()' `NDB$EPOCH_TRANS()' extends the `NDB$EPOCH()' function, and, like `NDB$EPOCH()', is available beginning with MySQL Cluster NDB 7.1.16. Conflicts are detected and handled in the same way using the `primary wins all' rule (see *Note 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 *Note mysql-cluster-replication-ndb-epoch::. `NULL' Indicates that conflict resolution is not to be used for the corresponding table. Status information Beginning with MySQL Cluster NDB 6.3.3, 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 *Note `mysqld': mysqld. was started. Beginning with MySQL Cluster NDB 6.3.4, the number of times that a row was not applied as the result of `same timestamp wins' conflict resolution on a given *Note `mysqld': 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. Exceptions table To use the `NDB$OLD()' conflict resolution function, it is also necessary to create an exceptions table corresponding to each *Note `NDB': mysql-cluster. table for which this type of conflict resolution is to be employed. This is also true when using `NDB$EPOCH()' or `NDB$EPOCH_TRANS()' in MySQL Cluster NDB 7.1.16 and later. 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 exception table name should be `mytable$EX'.) This table is created as follows: CREATE TABLE ORIGINAL_TABLE$EX ( server_id INT UNSIGNED, master_server_id INT UNSIGNED, master_epoch BIGINT UNSIGNED, count INT UNSIGNED, ORIGINAL_TABLE_PK_COLUMNS, [ADDITIONAL_COLUMNS,] PRIMARY KEY(server_id, master_server_id, master_epoch, count) ) ENGINE=NDB; The first four columns are required. 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. *Note*: 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. The data types for the columns duplicating the primary key columns of the original table should be the same as for (or larger than) the original columns. Additional columns may optionally be defined following these columns, but not before any of them; any such extra columns cannot be `NOT NULL'. The exception table's primary key must be defined as shown. The exception table must use the *Note `NDB': mysql-cluster. storage engine. An example that uses `NDB$OLD()' with an exceptions table is shown later in this section. *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 MySQL Cluster replication setup, as described in *Note mysql-cluster-replication-preparation::, and *Note 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 *Note `mysqld': mysqld. with `--ndb-log-update-as-write=OFF'. 2. On the master, perform this *Note `INSERT': 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 *Note `mysqld': 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 *Note `NDB': mysql-cluster. 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 SMALLINT UNSIGNED, master_server_id INT UNSIGNED, master_epoch BIGINT UNSIGNED, count BIGINT 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; 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.  File: manual.info, Node: mysql-cluster-news, Prev: mysql-cluster-replication, Up: mysql-cluster 17.7 MySQL Cluster NDB 6.1 - 7.1 Release Notes ============================================== MySQL Cluster release notes are no longer published in the MySQL Reference Manual. Release notes for the changes in each release of MySQL Cluster are located at MySQL Cluster 7.1 Release Notes (http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/).  File: manual.info, Node: partitioning, Next: stored-programs-views, Prev: mysql-cluster, Up: Top 18 Partitioning *************** * Menu: * partitioning-overview:: Overview of Partitioning in MySQL * partitioning-types:: Partitioning Types * partitioning-management:: Partition Management * partitioning-pruning:: Partition Pruning * partitioning-limitations:: Restrictions and Limitations on Partitioning This chapter discusses MySQL's implementation of _user-defined partitioning_. You can determine whether your MySQL Server supports partitioning by means of a *Note `SHOW VARIABLES': show-variables. statement such as this one: *Note*: The `have_partitioning' variable is deprecated, and removed in MySQL 5.6.1. mysql> SHOW VARIABLES LIKE '%partition%'; +-------------------+-------+ | Variable_name | Value | +-------------------+-------+ | have_partitioning | YES | +-------------------+-------+ 1 row in set (0.00 sec) *Note*: Prior to MySQL 5.1.6, this variable was named `have_partition_engine'. (Bug #16718) You can also check the output of the *Note `SHOW PLUGINS': show-plugins. statement, as shown here: 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) In MySQL 5.1.5 and later, you can also check the *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. 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.6 | ACTIVE | *| partition | 1.0 | ACTIVE |* +--------------------+---------+--------+ 10 rows in set (0.00 sec) Whichever of the preceding statements you employ, 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.1 Community binaries provided by Oracle include partitioning support. For information about partitioning support offered in commercial MySQL Server binaries, see `MySQL Enterprise Server 5.1' on the MySQL Web site at http://www.mysql.com/products/enterprise/server.html. If you are compiling MySQL 5.1 from source, the build must be configured using `--with-partition' to enable partitioning. Using `--with-plugins=max' to configure the build includes this option automatically. 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, in which case the value of `have_partitioning' is `DISABLED'. 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. An introduction to partitioning and partitioning concepts may be found in *Note partitioning-overview::. MySQL supports several types of partitioning, which are discussed in *Note partitioning-types::, as well as subpartitioning, which is described in *Note partitioning-subpartitions::. Methods of adding, removing, and altering partitions in existing partitioned tables are covered in *Note partitioning-management::. Table maintenance commands for use with partitioned tables are discussed in *Note partitioning-maintenance::. Beginning with MySQL 5.1.6, the *Note `PARTITIONS': partitions-table. table in the `INFORMATION_SCHEMA' database provides information about partitions and partitioned tables. See *Note partitions-table::, for more information; for some examples of queries against this table, see *Note partitioning-handling-nulls::. *Important*: Partitioned tables created with MySQL versions prior to 5.1.6 cannot be read by a 5.1.6 or later MySQL Server. In addition, the *Note `INFORMATION_SCHEMA.TABLES': tables-table. table cannot be used if such tables are present on a 5.1.6 server. Beginning with MySQL 5.1.7, a suitable warning message is generated instead, to alert the user that incompatible partitioned tables have been found by the server. If you are using partitioned tables which were created in MySQL 5.1.5 or earlier, be sure to see the Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/) for MySQL 5.1.6 for more information and suggested workarounds _before_ upgrading to MySQL 5.1.6 or later. For known issues with partitioning in MySQL 5.1, see *Note 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 MySQL 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.1 binaries are available from `http://dev.mysql.com/downloads/mysql/5.1.html'. However, for the latest partitioning bugfixes and feature additions, you can obtain the source from our Bazaar repository. To enable partitioning, you need to compile the server using the `--with-partition' option. For more information about building MySQL, see *Note source-installation::. If you have problems compiling a partitioning-enabled MySQL 5.1 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.  File: manual.info, Node: partitioning-overview, Next: partitioning-types, Prev: partitioning, Up: partitioning 18.1 Overview of Partitioning in MySQL ====================================== This section provides a conceptual overview of partitioning in MySQL 5.1. For information on partitioning restrictions and feature limitations, see *Note 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 *Note 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', the partitioning expression consists of a list of one or more columns, and the partitioning function is supplied by MySQL. For more information about permitted partitioning column types and partitioning functions, see *Note partitioning-types::, as well as *Note create-table::, which provides partitioning syntax descriptions and additional examples. For information about restrictions on partitioning functions, see *Note 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.1 does not support _vertical partitioning_, in which different columns of a table are assigned to different physical partitions. There are not at this time any plans to introduce vertical partitioning into MySQL 5.1. For information about determining whether your MySQL Server binary supports user-defined partitioning, see *Note 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.1, 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' or `CSV' storage engines. Beginning with MySQL 5.1.15, `FEDERATED' tables also cannot be partitioned (Bug #22451). Prior to MySQL 5.1.6, it was also not feasible to create a partitioned table using the `BLACKHOLE' storage engine (Bug #14524). See *Note partitioning-limitations-storage-engines::. Partitioning by `KEY' or `LINEAR KEY' is possible with *Note `NDBCLUSTER': mysql-cluster, but other types of user-defined partitioning are not supported for tables using this storage engine. In addition, an *Note `NDBCLUSTER': mysql-cluster. 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 *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table-partition-operations. statement used to create or modify a user-partitioned *Note `NDBCLUSTER': mysql-cluster. table, then the table is not required to have an explicit primary key. For more information, see *Note 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 *Note `CREATE TABLE': 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.1 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 *Note `CREATE TABLE': create-table. statement used to create the partitioned table. Prior to MySQL 5.1.18, these options were permitted even when the `NO_DIR_IN_CREATE' server SQL mode was in effect (Bug #24633). The `DATA DIRECTORY' and `INDEX DIRECTORY' options have no effect when defining partitions for tables using the `InnoDB' storage engine. `DATA DIRECTORY' and `INDEX DIRECTORY' are not supported for individual partitions or subpartitions on Windows. Beginning with MySQL 5.1.24, these options are ignored on Windows, except that a warning is generated (Bug #30459)- 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. The `MAX_ROWS' option can be useful for causing MySQL Cluster tables to be created with extra partitions, thus allowing for greater storage of hash indexes. See the documentation for the `DataMemory' data node configuration parameter, as well as *Note 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 excluding 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_, and was implemented in MySQL 5.1.6. For more information, see *Note partitioning-pruning::. 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.  File: manual.info, Node: partitioning-types, Next: partitioning-management, Prev: partitioning-overview, Up: partitioning 18.2 Partitioning Types ======================= * Menu: * partitioning-range:: `RANGE' Partitioning * partitioning-list:: `LIST' Partitioning * partitioning-hash:: `HASH' Partitioning * partitioning-key:: `KEY' Partitioning * partitioning-subpartitions:: Subpartitioning * partitioning-handling-nulls:: How MySQL Partitioning Handles `NULL' This section discusses the types of partitioning which are available in MySQL 5.1. 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 *Note partitioning-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 *Note partitioning-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 *Note 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 *Note 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.1. However, it is not difficult in MySQL to create partitioning schemes based on *Note `DATE': datetime, *Note `TIME': time, or *Note `DATETIME': datetime. columns, or based on expressions making use of such columns. When partitioning by `KEY' or `LINEAR KEY', you can use a *Note `DATE': datetime, *Note `TIME': time, or *Note `DATETIME': 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; 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 *Note `DATE': datetime, *Note `TIME': time, or *Note `DATETIME': 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: * *Note partitioning-range:: * *Note partitioning-hash:: * *Note partitioning-linear-hash:: For more complex examples of date-based partitioning, see the following sections: * *Note partitioning-pruning:: * *Note partitioning-subpartitions:: MySQL partitioning is optimized for use with the `TO_DAYS()' and `YEAR()' functions. However, you can use other date and time functions that return an integer or `NULL', such as `WEEKDAY()', `DAYOFYEAR()', or `MONTH()'. See *Note 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 function employed must return 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 *Note `CREATE TABLE': 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. (Beginning with MySQL 5.1.12, decimal fractions are no longer truncated, but instead are prohibited entirely.) 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 *Note create-table::.  File: manual.info, Node: partitioning-range, Next: partitioning-list, Prev: partitioning-types, Up: partitioning-types 18.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 ); 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, 'Michael', 'Widenius', '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 *Note `CREATE TABLE': 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 *Note `INSERT': insert. statement. For an example, see *Note partitioning-list::. Also see *Note 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 *Note `ALTER TABLE': alter-table-partition-operations. statement to add new partitions for stores 21-25, 26-30, and so on (see *Note 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 *Note `DATE': datetime. 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 *Note `CREATE TABLE': 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'. Beginning with MySQL 5.1.43, it is also possible to partition a table by `RANGE' based on the value of a *Note `TIMESTAMP': datetime. 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) ); Also beginning with MySQL 5.1.43, any other expressions involving *Note `TIMESTAMP': datetime. values are not permitted. (See Bug #42849.) *Note*: It is also possible in MySQL 5.1.43 and later 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. 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 immediately above, 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 *Note alter-table::, and *Note partitioning-management::, for more information.) For a table with a great many rows, this can be much more efficient than running a *Note `DELETE': 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 PARTITIONS 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 *Note partitioning-pruning::, for more information about how this is accomplished.  File: manual.info, Node: partitioning-list, Next: partitioning-hash, Prev: partitioning-range, Up: partitioning-types 18.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.1, it is possible to match against only a list of integers (and possibly `NULL'--see *Note partitioning-handling-nulls::) when partitioning by `LIST'. 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 *Note create-table::. For the examples that follow, we assume that the basic definition of the table to be partitioned is provided by the *Note `CREATE TABLE': 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 *Note partitioning-range::.) Suppose that there are 20 video stores distributed among 4 franchises as shown in the following table. This table illustrates an example of 20 video stores distributed among 4 regional franchises, as described in the preceding text. 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 *Note `CREATE TABLE': 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. All rows relating to employees working at stores in that region can be deleted with an `ALTER TABLE employees DROP PARTITION pWest' statement, which can be executed much more efficiently than the equivalent *Note `DELETE': delete. statement (`DELETE FROM employees WHERE store_id IN (4,12,13,14,18)'). However, the *Note `ALTER TABLE ... DROP PARTITION': alter-table. statement also removes the partition itself from the definition for the table, and you must execute an *Note `ALTER TABLE ... ADD PARTITION': alter-table. statement to restore the table's original partitioning scheme. (This problem is resolved in MySQL 5.5, which adds the *Note `ALTER TABLE ... TRUNCATE PARTITION': alter-table. statement for removing all rows from a given partition without affecting the table definition.) As with `RANGE' partitioning, it is possible to combine `LIST' partitioning with partitioning by hash or key to produce a composite partitioning (subpartitioning). See *Note 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 *Note `INSERT': 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 *Note `INSERT': insert. statement, any rows coming before the row containing the unmatched value are inserted, but any coming after it are not: mysql> SELECT * FROM h2; Empty set (0.00 sec) mysql> INSERT INTO h2 VALUES (4, 7), (3, 5), (6, 0); `ERROR 1525 (HY000): Table has no partition for value 3' mysql> SELECT * FROM h2; +------+------+ | c1 | c2 | +------+------+ | 4 | 7 | +------+------+ 1 row in set (0.00 sec) 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)  File: manual.info, Node: partitioning-hash, Next: partitioning-key, Prev: partitioning-list, Up: partitioning-types 18.2.3 `HASH' Partitioning -------------------------- * Menu: * partitioning-linear-hash:: `LINEAR 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 *Note `CREATE TABLE': 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 will most likely want to follow this with a `PARTITIONS NUM' clause, where NUM is a positive integer representing the number of partitions into which the table is to be divided. For example, 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 *Note 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 *Note `DATE': datetime, 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 *Note `INT': integer-types. 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 by widely different 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 user function. In other words, for an 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.1 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 *Note partitioning-linear-hash::, for a description of this algorithm. The user function is evaluated each time a record is inserted or updated. It may also--depending on the circumstances--be evaluated when records are deleted. *Note*: If a table to be partitioned has a `UNIQUE' key, then any columns supplied as arguments to the `HASH' user function or to the `KEY''s COLUMN_LIST must be part of that key.  File: manual.info, Node: partitioning-linear-hash, Prev: partitioning-hash, Up: partitioning-hash 18.2.3.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 = CEIL(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 & CEILING(8 / 2) = 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.  File: manual.info, Node: partitioning-key, Next: partitioning-subpartitions, Prev: partitioning-hash, Up: partitioning-types 18.2.4 `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. MySQL 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 one or more column names. Beginning with MySQL 5.1.5, the column or columns used as the partitioning key must comprise part or all of the table's primary key, if the table has one. Beginning with MySQL 5.1.6, `KEY' takes a list of zero or more column names. 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 *Note `CREATE TABLE': create-table. statement is valid in MySQL 5.1.6 or later: 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 *Note `SHOW CREATE TABLE': show-create-table. or in the `PARTITION_EXPRESSION' column of the *Note `INFORMATION_SCHEMA.PARTITIONS': partitions-table. 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 *Note `CREATE TABLE': 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 *Note partitioning-limitations::. *Note*: Also beginning with MySQL 5.1.6, tables using the *Note `NDBCLUSTER': mysql-cluster. storage engine are implicitly partitioned by `KEY', again using the table's primary key as the partitioning key. In the event that the MySQL Cluster table has no explicit primary key, the `hidden' primary key generated by the *Note `NDBCLUSTER': mysql-cluster. storage engine for each MySQL Cluster table is used as the partitioning key. Beginning with MySQL Cluster NDB 6.2.18, MySQL Cluster NDB 6.3.25, and MySQL Cluster NDB 7.0.6, if you define an explicit partitioning scheme for an *Note `NDBCLUSTER': mysql-cluster. 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 *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility (with the `-p' option). *Important*: For a key-partitioned table using any MySQL storage engine other than *Note `NDBCLUSTER': mysql-cluster, 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 MySQL 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 *Note 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 *Note partitioning-linear-hash::, for a description of this algorithm and its implications.  File: manual.info, Node: partitioning-subpartitions, Next: partitioning-handling-nulls, Prev: partitioning-key, Up: partitioning-types 18.2.5 Subpartitioning ---------------------- Subpartitioning--also known as _composite partitioning_--is the further division of each partition in a partitioned table. Consider the following *Note `CREATE TABLE': 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.1, 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 *Note 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. * In MySQL 5.1.7 and earlier, names of subpartitions were required to be unique within each partition, but did not have to be unique within the table as a whole. Beginning with MySQL 5.1.8, subpartition names must be unique across the entire table. For example, the following *Note `CREATE TABLE': create-table. statement is valid in MySQL 5.1.8 and later: 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 ) ); (The previous statement is also valid for versions of MySQL prior to 5.1.8.) Subpartitions can be used with especially large 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) 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) 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 *Note partitioning-management::, for an explanation of how this can be done. Beginning with MySQL 5.1.18, 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. However, this not true when defining subpartitions; this is a known issue which is fixed in MySQL 5.5 (Bug #42954).  File: manual.info, Node: partitioning-handling-nulls, Prev: partitioning-subpartitions, Up: partitioning-types 18.2.6 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. Beginning with MySQL 5.1.8, the 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 *Note `CREATE TABLE': create-table. statements using the following query against the *Note `PARTITIONS': partitions-table. 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 *Note 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 *Note `SELECT': 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 *Note `INFORMATION_SCHEMA.PARTITIONS': partitions-table. 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 *Note `SELECT': 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) *Important*: Prior to MySQL 5.1.8, `RANGE' partitioning treated a partitioning expression value of `NULL' as 0 with respect to determining placement. (The only way to circumvent this behavior was to design tables so as not to permit nulls, usually by declaring columns `NOT NULL'.) If you have a `RANGE' partitioning scheme that depends on this earlier behavior, you must re-implement it when upgrading to MySQL 5.1.8 or later. (Bug #15447) `NULL' is also treated in this way for partitioning expressions that use SQL functions. Suppose that we define a table using a *Note `CREATE TABLE': 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 *Note `INFORMATION_SCHEMA.PARTITIONS': partitions-table, 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 *Note `SELECT': 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) Note that `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 *Note `INFORMATION_SCHEMA.PARTITIONS': partitions-table. 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) If you repeat this example using `PARTITION BY KEY' in place of `PARTITION BY HASH' in the definition of the table, you can verify easily that `NULL' is also treated like 0 for this type of partitioning.  File: manual.info, Node: partitioning-management, Next: partitioning-pruning, Prev: partitioning-types, Up: partitioning 18.3 Partition Management ========================= * Menu: * partitioning-management-range-list:: Management of `RANGE' and `LIST' Partitions * partitioning-management-hash-key:: Management of `HASH' and `KEY' Partitions * partitioning-maintenance:: Maintenance of Partitions * partitioning-info:: Obtaining Information About Partitions MySQL 5.1 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 *Note `ALTER TABLE': alter-table-partition-operations. statement *Note alter-table::. 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 *Note partitioning-management-range-list::. * For a discussion of managing `HASH' and `KEY' partitions, see *Note partitioning-management-hash-key::. * See *Note partitioning-info::, for a discussion of mechanisms provided in MySQL 5.1 for obtaining information about partitioned tables and partitions. * For a discussion of performing maintenance operations on partitions, see *Note partitioning-maintenance::. *Note*: In MySQL 5.1, 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. The statement *Note `ALTER TABLE ... PARTITION BY ...': alter-table-partition-operations. is available and is functional beginning with MySQL 5.1.6; previously in MySQL 5.1, this was accepted as valid syntax, but the statement did nothing. To change a table's partitioning scheme, it is necessary only to use the *Note `ALTER TABLE': alter-table-partition-operations. statement with a PARTITION_OPTIONS clause. This clause has the same syntax as that as used with *Note `CREATE TABLE': 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 *Note `CREATE TABLE': 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;'. In MySQL 5.1.7 and earlier MySQL 5.1 releases, `ALTER TABLE ... ENGINE = ...' removed all partitioning from the affected table. Beginning with MySQL 5.1.8, this statement changes only the storage engine used by the table, and leaves the table's partitioning scheme intact. As of MySQL 5.1.8, use `ALTER TABLE ... REMOVE PARTITIONING' to remove a table's partitioning. See *Note alter-table::. *Important*: Only a single `PARTITION BY', `ADD PARTITION', `DROP PARTITION', `REORGANIZE PARTITION', or `COALESCE PARTITION' clause can be used in a given *Note `ALTER TABLE': alter-table-partition-operations. statement. If you (for example) wish to drop a partition and reorganize a table's remaining partitions, you must do so in two separate *Note `ALTER TABLE': alter-table-partition-operations. statements (one using `DROP PARTITION' and then a second one using `REORGANIZE PARTITIONS').  File: manual.info, Node: partitioning-management-range-list, Next: partitioning-management-hash-key, Prev: partitioning-management, Up: partitioning-management 18.3.1 Management of `RANGE' and `LIST' Partitions -------------------------------------------------- Range and list partitions are very similar with regard to how the adding and dropping of partitions are handled. For this reason 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 *Note partitioning-management-hash-key::. Dropping a `RANGE' or `LIST' partition is more straightforward than adding one, so we discuss this first. Dropping a partition from a table that is partitioned by either `RANGE' or by `LIST' can be accomplished using the *Note `ALTER TABLE': alter-table-partition-operations. statement with a `DROP PARTITION' clause. Here is a very basic example, which supposes that you have already created a table which is partitioned by range and then populated with 10 records using the following *Note `CREATE TABLE': create-table. and *Note `INSERT': 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) -> ); Query OK, 0 rows affected (0.01 sec) mysql> INSERT INTO tr 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'); Query OK, 10 rows affected (0.01 sec) 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 | +------+-----------+------------+ | 3 | TV set | 1996-03-10 | | 10 | lava lamp | 1998-12-25 | +------+-----------+------------+ 2 rows in set (0.00 sec) 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 *Note `NDBCLUSTER': mysql-cluster. storage engine does not support `ALTER TABLE ... DROP PARTITION'. It does, however, support the other partitioning-related extensions to *Note `ALTER TABLE': alter-table-partition-operations. 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 *Note `SELECT': select. query: mysql> SELECT * FROM tr WHERE purchased -> BETWEEN '1995-01-01' AND '1999-12-31'; Empty set (0.00 sec) Because of this, the requirement was added in MySQL 5.1.10 that you 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 *Note `TRUNCATE TABLE': truncate-table. statement. (See *Note 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 *Note alter-table::, for information about `REORGANIZE PARTITION'. If you now execute a *Note `SHOW CREATE TABLE': 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=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 p3 VALUES LESS THAN (2005) ENGINE = MyISAM ) 1 row in set (0.01 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 | +------+----------------+------------+ | 11 | pencil holder | 1995-07-12 | | 1 | desk organiser | 2003-10-15 | | 5 | exercise bike | 2004-05-09 | | 7 | popcorn maker | 2001-11-22 | +------+----------------+------------+ 4 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) Note that 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 *Note `DELETE': 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 *Note 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 (1970), PARTITION p1 VALUES LESS THAN (1980), PARTITION p2 VALUES LESS THAN (1990) ); Suppose further that the minimum age for members is 16. As the calendar approaches the end of 2005, you realize that you will soon be admitting members who were born in 1990 (and later in years to come). You can modify the `members' table to accommodate new members born in the years 1990 to 1999 as shown here: ALTER TABLE members ADD PARTITION (PARTITION p3 VALUES LESS THAN (2000)); 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 (1960)); 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 (1960), PARTITION n1 VALUES LESS THAN (1970) ); Using *Note `SHOW CREATE TABLE': 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 (1960) ENGINE = MyISAM, PARTITION n1 VALUES LESS THAN (1970) ENGINE = MyISAM, PARTITION p1 VALUES LESS THAN (1980) ENGINE = MyISAM, PARTITION p2 VALUES LESS THAN (1990) ENGINE = MyISAM, PARTITION p3 VALUES LESS THAN (2000) ENGINE = MyISAM) */ 1 row in set (0.00 sec) See also *Note 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 *Note `CREATE TABLE': 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)); Note 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 *Note `CREATE TABLE ... SELECT ...': create-table, 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. Beginning with MySQL 5.1.6, 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=MyISAM DEFAULT CHARSET=latin1 PARTITION BY RANGE ( YEAR(dob) ) ( PARTITION p0 VALUES LESS THAN (1970) ENGINE = MyISAM, PARTITION p1 VALUES LESS THAN (1980) ENGINE = MyISAM, PARTITION p2 VALUES LESS THAN (1990) ENGINE = MyISAM. PARTITION p3 VALUES LESS THAN (2000) ENGINE = MyISAM ) 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 *Note `ALTER TABLE ... ADD PARTITION': alter-table-partition-operations. However, you can use another partition-related extension to *Note `ALTER TABLE': alter-table-partition-operations. to accomplish this: ALTER TABLE members REORGANIZE PARTITION p0 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 return the `members' table to its previous partitioning 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 *Note `CREATE TABLE': create-table. (see *Note create-table::). It should be noted that 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, as follows: 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' clauses used to determine the new partitioning scheme are subject to the same rules as those used with a *Note `CREATE TABLE': create-table. statement. Most importantly, you should remember that the new partitioning scheme cannot have any overlapping ranges (applies to tables partitioned by `RANGE') or sets of values (when reorganizing tables partitioned by `LIST'). *Note*: Prior to MySQL 5.1.4, you could not reuse the names of existing partitions in the `INTO' clause, even when those partitions were being dropped or redefined. See the Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/) for MySQL 5.1.4 for more information. * 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 instance, in the `members' table used as an example in this section, partitions `p1' and `p2' together cover the years 1980 through 1999. Therefore, 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 `members' table used as an example in this section 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, and thus the two are not adjacent partitions. * You cannot use `REORGANIZE PARTITION' to change the table's partitioning type; that is, you cannot (for example) change `RANGE' partitions to `HASH' partitions or _vice versa_. You also cannot use this command to change the partitioning expression or column. To accomplish either of these tasks without dropping and re-creating the table, you can use *Note `ALTER TABLE ... PARTITION BY ...': alter-table-partition-operations. For example: ALTER TABLE members PARTITION BY HASH( YEAR(dob) ) PARTITIONS 8;  File: manual.info, Node: partitioning-management-hash-key, Next: partitioning-maintenance, Prev: partitioning-management-range-list, Up: partitioning-management 18.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 *Note 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 *Note `ALTER TABLE': alter-table-partition-operations. 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 Note that 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;  File: manual.info, Node: partitioning-maintenance, Next: partitioning-info, Prev: partitioning-management-hash-key, Up: partitioning-management 18.3.3 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.1. Table maintenance of partitioned tables can be accomplished using the statements *Note `CHECK TABLE': check-table, *Note `OPTIMIZE TABLE': optimize-table, *Note `ANALYZE TABLE': analyze-table, and *Note `REPAIR TABLE': repair-table, which are supported for partitioned tables as of MySQL 5.1.27. Also beginning with MySQL 5.1.27, you can use a number of extensions to *Note `ALTER TABLE': alter-table-partition-operations. 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 *Note `InnoDB': innodb-storage-engine, do not support per-partition optimization; in these cases, *Note `ALTER TABLE ... OPTIMIZE PARTITION': alter-table-partition-operations. rebuilds the entire table. In MySQL 5.1.68 and later, running this statement on such a table causes the entire table to rebuilt and analyzed, and 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; * 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. 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. *Note*: The statements `ALTER TABLE ... ANALYZE PARTITION', `ALTER TABLE ... CHECK PARTITION', `ALTER TABLE ... OPTIMIZE PARTITION', and `ALTER TABLE ... REPAIR PARTITION' were originally introduced in MySQL 5.1.5, but did not work properly and were disabled in MySQL 5.1.24. They were re-introduced in MySQL 5.1.27. (Bug #20129) The use of these partitioning-specific `ALTER TABLE' statements with tables which are not partitioned is not supported; beginning with MySQL 5.1.31, it is expressly not permitted. (Bug #39434) `ALTER TABLE ... REBUILD PARTITION' was also introduced in MySQL 5.1.5. The use of *Note `mysqlcheck': mysqlcheck. and *Note `myisamchk': myisamchk. is not supported with partitioned tables.  File: manual.info, Node: partitioning-info, Prev: partitioning-maintenance, Up: partitioning-management 18.3.4 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 *Note `SHOW CREATE TABLE': show-create-table. statement to view the partitioning clauses used in creating a partitioned table. * Using the *Note `SHOW TABLE STATUS': show-table-status. statement to determine whether a table is partitioned. * Querying the *Note `INFORMATION_SCHEMA.PARTITIONS': partitions-table. table. * Using the statement *Note `EXPLAIN PARTITIONS SELECT': explain. to see which partitions are used by a given *Note `SELECT': select. As discussed elsewhere in this chapter, *Note `SHOW CREATE TABLE': 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) *Note*: In early MySQL 5.1 releases, the `PARTITIONS' clause was not shown for tables partitioned by `HASH' or `KEY'. This issue was fixed in MySQL 5.1.6. *Note `SHOW TABLE STATUS': show-table-status. works with partitioned tables. Beginning with MySQL 5.1.9, its output is the same as that for nonpartitioned tables, except that the `Create_options' column contains the string `partitioned'. In MySQL 5.1.8 and earlier, the `Engine' column always contained the value `PARTITION'; beginning with MySQL 5.1.9, this column contains the name of the storage engine used by all partitions of the table. (See *Note show-table-status::, for more information about this statement.) You can also obtain information about partitions from `INFORMATION_SCHEMA', which contains a *Note `PARTITIONS': partitions-table. table. See *Note partitions-table::. Beginning with MySQL 5.1.5, it is possible to determine which partitions of a partitioned table are involved in a given *Note `SELECT': select. query using *Note `EXPLAIN PARTITIONS': explain. The `PARTITIONS' keyword adds a `partitions' column to the output of *Note `EXPLAIN': explain. listing 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 PARTITIONS 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 PARTITIONS 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 *Note `EXPLAIN PARTITIONS': explain. provides information about keys used and possible keys, just as with the standard *Note `EXPLAIN SELECT': explain. statement: mysql> ALTER TABLE trb1 ADD PRIMARY KEY (id); Query OK, 10 rows affected (0.03 sec) Records: 10 Duplicates: 0 Warnings: 0 mysql> EXPLAIN PARTITIONS 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 You should take note of the following restrictions and limitations on *Note `EXPLAIN PARTITIONS': explain.: * You cannot use the `PARTITIONS' and `EXTENDED' keywords together in the same *Note `EXPLAIN ... SELECT': explain. statement. Attempting to do so produces a syntax error. * If *Note `EXPLAIN PARTITIONS': explain. is used to examine a query against a nonpartitioned table, no error is produced, but the value of the `partitions' column is always `NULL'. As of MySQL 5.1.28, the `rows' column of *Note `EXPLAIN PARTITIONS': explain. output always displays the total number of rows in the table. Previously, this was the number of matching rows (see Bug #35745). See also *Note explain::.  File: manual.info, Node: partitioning-pruning, Next: partitioning-limitations, Prev: partitioning-management, Up: partitioning 18.4 Partition Pruning ====================== This section discusses an optimization known as _partition pruning_, which was implemented for partitioned tables in MySQL 5.1.6. 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 query 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 a 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. The query 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. 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 three values in the list are found in partition `p1', the remaining three values in partition `p2', and that the other partitions contain no relevant values and so do not need to be searched for matching rows. 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 *Note `DATE': datetime. or *Note `DATETIME': datetime. column when the partitioning expression uses the `YEAR()' or `TO_DAYS()' function. Suppose that table `t2', defined as shown here, is partitioned on a *Note `DATE': datetime. 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 queries on `t2' can make of use partition pruning: SELECT * FROM t2 WHERE dob = '1982-06-23'; SELECT * FROM t2 WHERE dob BETWEEN '1991-02-15' AND '1997-04-25'; SELECT * FROM t2 WHERE dob >= '1984-06-21' AND dob <= '1999-06-21' In the case of the last query, 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' clause of a query on 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 query 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 `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; Any query, such as this one, that compares a column value with a constant can be pruned: SELECT * FROM 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 query: SELECT * 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 previous query cannot be pruned. Pruning can be used only on integer columns of tables partitioned by `HASH' or `KEY'. For example, this query on table `t4' cannot use pruning because `dob' is a *Note `DATE': datetime. column: SELECT * FROM t4 WHERE dob >= '2001-04-14' AND dob <= '2005-10-15'; However, if the table stores year values in an *Note `INT': integer-types. column, then a query having `WHERE year_col >= 2001 AND year_col <= 2005' can be pruned. For a table that is partitioned by `KEY', has a composite primary key, and uses a composite partitioning key, it is possible to perform pruning for queries meeting the following two criteria: * The query must have a `WHERE' clause of the form `pkcol1 = c1 AND pkcol2 = c2 AND ... pkcolN = cN', where `pkcol1' ... `pkcolN' are the partitioning key columns and `c1' ... `cN' are constant values. * All columns of the partitioning key must be referenced in the `WHERE' clause. For example, suppose a table named `cities' is created as shown here: CREATE TABLE cities ( id INT NOT NULL AUTO_INCREMENT, name CHAR(35) NOT NULL DEFAULT '', country_code CHAR(3) NOT NULL DEFAULT '', district CHAR(20) NOT NULL DEFAULT '', population INT NOT NULL DEFAULT 0, PRIMARY KEY (ID, Population) ) PARTITION BY KEY () PARTITIONS 8; (Note that `PARTITION BY KEY()' is equivalent in this case to `PARTITION BY KEY(id, population)'.) Only a query that references both the `id' and `population' columns of this table can be pruned, as shown here: mysql> SELECT * FROM cities WHERE id = 101; +-----+------------+--------------+----------+------------+ | id | name | country_code | district | population | +-----+------------+--------------+----------+------------+ | 101 | Godoy Cruz | ARG | Mendoza | 206998 | +-----+------------+--------------+----------+------------+ 1 row in set (0.00 sec) mysql> SELECT * FROM cities WHERE population = 206998; +-----+------------+--------------+----------+------------+ | id | name | country_code | district | population | +-----+------------+--------------+----------+------------+ | 101 | Godoy Cruz | ARG | Mendoza | 206998 | +-----+------------+--------------+----------+------------+ 1 row in set (0.00 sec) mysql> EXPLAIN PARTITIONS SELECT * FROM cities WHERE id = 101\G *************************** 1. row *************************** id: 1 select_type: SIMPLE table: cities partitions: p0,p1,p2,p3,p4,p5,p6,p7 type: ref possible_keys: PRIMARY key: PRIMARY key_len: 4 ref: const rows: 6 Extra: 1 row in set (0.00 sec) mysql> EXPLAIN PARTITIONS SELECT * FROM cities WHERE population = 206998\G *************************** 1. row *************************** id: 1 select_type: SIMPLE table: cities partitions: p0,p1,p2,p3,p4,p5,p6,p7 type: ALL possible_keys: NULL key: NULL key_len: NULL ref: NULL rows: 1973 Extra: Using where 1 row in set (0.00 sec) mysql> EXPLAIN PARTITIONS SELECT * FROM cities WHERE id = 101 AND population = 206998\G *************************** 1. row *************************** id: 1 select_type: SIMPLE table: cities partitions: p2 type: const possible_keys: PRIMARY key: PRIMARY key_len: 8 ref: const,const rows: 1 Extra: 1 row in set (0.00 sec) This limitation on pruning with composite partitioning keys is removed in MySQL 5.5.  File: manual.info, Node: partitioning-limitations, Prev: partitioning-pruning, Up: partitioning 18.5 Restrictions and Limitations on Partitioning ================================================= * Menu: * partitioning-limitations-partitioning-keys-unique-keys:: Partitioning Keys, Primary Keys, and Unique Keys * partitioning-limitations-storage-engines:: Partitioning Limitations Relating to Storage Engines * partitioning-limitations-functions:: Partitioning Limitations Relating to Functions * partitioning-limitations-locking:: Partitioning and Table-Level Locking This section discusses current restrictions and limitations on MySQL partitioning support. Prohibited constructs Beginning with MySQL 5.1.12, 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 *Note 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 *Note partitioning-types::, for more information). Beginning with MySQL 5.1.23, the `DIV' operator is also supported, and the `/' operator is not permitted. (Bug #30188, Bug #33182) Beginning with MySQL 5.1.12, the bit operators `|', `&', `^', `<<', `>>', and `~' are not permitted in partitioning expressions. `HANDLER' statements In MySQL 5.1, the *Note `HANDLER': handler. statement is not supported with partitioned tables. 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 *Note server-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 *Note `INSERT': 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 *Note `CREATE TABLE': 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' Server SQL modes also impact replication of partitioned tables. Differing 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 affects of partitioning operations on performance are given in the following list: * File system operations Partitioning and repartitioning operations (such as *Note `ALTER TABLE': alter-table-partition-operations. with `PARTITION BY ...', `REORGANIZE PARTITIONS', 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 *Note partitioning-limitations-max-partitions::. * Table locks The process executing a partitioning operation on a table takes a write lock on the table. Reads from such tables are relatively unaffected; pending *Note `INSERT': insert. and *Note `UPDATE': update. operations are performed as soon as the partitioning operation has completed. * Storage engine Partitioning operations, queries, and update operations generally tend to be faster with `MyISAM' tables than with `InnoDB' or *Note `NDB': mysql-cluster. tables. * Use of indexes and 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 *Note partitioning-pruning::, for more information. * Performance with `LOAD DATA' Prior to MySQL 5.1.23, *Note `LOAD DATA': load-data. performed very poorly when importing into partitioned tables. The statement now uses buffering to improve performance; however, the buffer uses 130 KB memory per partition to achieve this. (Bug #26527) Maximum number of partitions The maximum possible number of partitions for a given table (that does not use the *Note `NDB': mysql-cluster. storage engine) is 1024. This number includes subpartitions. The maximum possible number of user-defined partitions for a table using the *Note `NDBCLUSTER': mysql-cluster. storage engine is determined according to the version of the MySQL Cluster software being used, the number of data nodes, and other factors. See *Note 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 *Note 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 *Note partitioning-limitations-file-system-ops::. Foreign keys not supported for partitioned `InnoDB' tables Partitioned tables using the *Note `InnoDB': innodb-storage-engine. 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. *Note `CREATE TABLE': create-table-foreign-keys. and *Note `ALTER TABLE': 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. `FULLTEXT' indexes Partitioned tables do not support `FULLTEXT' indexes or searches. This includes partitioned tables employing the *Note `MyISAM': myisam-storage-engine. storage engine. Spatial columns Columns with spatial data types such as `POINT' or `GEOMETRY' cannot be used in partitioned tables. Temporary tables As of MySQL 5.1.8, temporary tables cannot be partitioned. (Bug #17497) Log tables Beginning with MySQL 5.1.20, it is no longer possible to partition the log tables; beginning with that version, an *Note `ALTER TABLE ... PARTITION BY ...': alter-table-partition-operations. statement on such a table fails with an error. (Bug #27816) Data type of partitioning key A partitioning key must be either an integer column or an expression that resolves to an integer. The column or expression value may also be `NULL'. (See *Note partitioning-handling-nulls::.) The lone exception to this restriction occurs when partitioning by [`LINEAR'] `KEY', where it is possible to use columns of other types as partitioning keys, because MySQL's internal key-hashing functions produce the correct data type from these types. For example, the following *Note `CREATE TABLE': create-table. statement is valid: CREATE TABLE tkc (c1 CHAR) PARTITION BY KEY(c1) PARTITIONS 4; This exception does _not_ apply to *Note `BLOB': blob. or *Note `TEXT': blob. 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. Currently, `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). Query cache not supported The query cache is not supported for partitioned tables. Beginning with MySQL 5.1.63, the query cache is automatically disabled for queries involving partitioned tables, and cannot be enabled for such queries. (Bug #53775) Key cache not supported Caching is not supported for partitioned tables. The *Note `CACHE INDEX': cache-index. and *Note `LOAD INDEX INTO CACHE': load-index. statements, when you attempt to use them on tables having user-defined partitioning, fail with the errors `The storage engine for the table doesn't support assign_to_keycache' and `The storage engine for the table doesn't support preload_keys', respectively. This issue is fixed in MySQL 5.5. `DELAYED' option not supported Use of *Note `INSERT DELAYED': insert-delayed. to insert rows into a partitioned table is not supported. Beginning with MySQL 5.1.23, attempting to do so fails with an error (see Bug #31210). `DATA DIRECTORY' and `INDEX DIRECTORY' options `DATA DIRECTORY' and `INDEX DIRECTORY' are subject to the following restrictions when used with partitioned tables: * Beginning with MySQL 5.1.23, 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 (Bug #30459). Repairing and rebuilding partitioned tables The statements *Note `CHECK TABLE': check-table, *Note `OPTIMIZE TABLE': optimize-table, *Note `ANALYZE TABLE': analyze-table, and *Note `REPAIR TABLE': repair-table. are supported for partitioned tables beginning with MySQL 5.1.27. (See Bug #20129.) 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. Both of these statements were added in MySQL 5.1.5. See *Note alter-table::, for more information about these two statements. *Note `mysqlcheck': mysqlcheck. and *Note `myisamchk': myisamchk. are not supported with partitioned tables.  File: manual.info, Node: partitioning-limitations-partitioning-keys-unique-keys, Next: partitioning-limitations-storage-engines, Prev: partitioning-limitations, Up: partitioning-limitations 18.5.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 *Note `CREATE TABLE': 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 *Note `ALTER TABLE': alter-table-partition-operations. 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 *Note `ALTER TABLE ... PARTITION BY': alter-table-partition-operations. 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 *Note `ALTER TABLE': alter-table-partition-operations. 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.  File: manual.info, Node: partitioning-limitations-storage-engines, Next: partitioning-limitations-functions, Prev: partitioning-limitations-partitioning-keys-unique-keys, Up: partitioning-limitations 18.5.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. Beginning with MySQL 5.1.15, it is not possible to create partitioned `FEDERATED' tables at all. `CSV' storage engine Partitioned tables using the `CSV' storage engine are not supported. Starting with MySQL 5.1.12, it is not possible to create partitioned `CSV' tables at all. `BLACKHOLE' storage engine Prior to MySQL 5.1.6, tables using the `BLACKHOLE' storage engine also could not be partitioned. `InnoDB' storage engine *Note `InnoDB': innodb-storage-engine. 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. In addition, *Note `ALTER TABLE ... OPTIMIZE PARTITION': alter-table-partition-operations. 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 *Note alter-table-partition-operations::. `NDBCLUSTER' storage engine (MySQL Cluster) Partitioning by `KEY' (including `LINEAR KEY') is the only type of partitioning supported for the *Note `NDBCLUSTER': mysql-cluster. storage engine. Beginning with MySQL 5.1.12, it is not possible to create a MySQL Cluster table using any partitioning type other than [`LINEAR'] `KEY', and attempting to do so fails with an error. In addition, the maximum number of partitions that can be defined for an *Note `NDBCLUSTER': mysql-cluster. table depends on the number of data nodes and node groups in the cluster, the version of the MySQL Cluster software in use, and other factors. See *Note mysql-cluster-nodes-groups-user-partitioning::, for more information. Beginning with MySQL Cluster NDB 6.2.18, MySQL Cluster NDB 6.3.25, and MySQL Cluster NDB 7.0.6, *Note `CREATE TABLE': create-table. and *Note `ALTER TABLE': alter-table-partition-operations. statements that would cause a user-partitioned *Note `NDBCLUSTER': mysql-cluster. table not to meet either or both of the following two requirements are not permitted, and fail with an error (Bug #40709): 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 *Note `NDBCLUSTER': mysql-cluster. 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 *Note `NDBCLUSTER': mysql-cluster. 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  File: manual.info, Node: partitioning-limitations-functions, Next: partitioning-limitations-locking, Prev: partitioning-limitations-storage-engines, Up: partitioning-limitations 18.5.3 Partitioning Limitations Relating to Functions ----------------------------------------------------- This section discusses limitations in MySQL Partitioning relating specifically to functions used in partitioning expressions. Beginning with MySQL 5.1.12, only the MySQL functions shown in the following table are supported in partitioning expressions. This table lists the functions that are supported in partitioning expressions as of MySQL 5.1.12. Functions are presented in a three column table format and in alphabetical order from left to right. `ABS()' `CEILING()' (see *Note `DAY()' partitioning-limitations-ceiling-floor::) `DAYOFMONTH()' `DAYOFWEEK()' `DAYOFYEAR()' `DATEDIFF()' `EXTRACT()' (see *Note `FLOOR()' (see *Note partitioning-limitations-extract::)partitioning-limitations-ceiling-floor::) `HOUR()' `MICROSECOND()' `MINUTE()' `MOD()' `MONTH()' `QUARTER()' `SECOND()' `TIME_TO_SEC()' `TO_DAYS()' `UNIX_TIMESTAMP()' `WEEKDAY()' `YEAR()' (permitted in MySQL 5.1.43 and later, with *Note `TIMESTAMP': datetime. columns) `YEARWEEK()' In MySQL 5.1, partition pruning is supported only for the `TO_DAYS()' and `YEAR()' functions. See *Note 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 *Note `INT': integer-types. types or *Note `DECIMAL': fixed-point-types. This means, for example, that the following *Note `CREATE TABLE': 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, beginning with MySQL 5.1.55, `EXTRACT()' is longer permitted as a partitioning function when it specifies the unit as `WEEK'. (Bug #54483) See *Note mathematical-functions::, for more information about the return types of these functions, as well as *Note numeric-types::.  File: manual.info, Node: partitioning-limitations-locking, Prev: partitioning-limitations-functions, Up: partitioning-limitations 18.5.4 Partitioning and Table-Level Locking ------------------------------------------- For storage engines such as *Note `MyISAM': myisam-storage-engine. that actually execute table-level locks when executing DML or DDL statements, such a statement affecting a partitioned table imposes a lock on the table as a whole; that is, all partitions are locked until the statement was finished. For example, a *Note `SELECT': select. from a partitioned `MyISAM' table causes a lock on the entire table. In practical terms, what this means is that the statements discussed later in this section tend to execute more slowly as the number of partitions increases. This limitation is greatly reduced in MySQL 5.6, with the introduction of _partition lock pruning_ in MySQL 5.6.6. This is not true for statements effecting partitioned tables using storage engines such as *Note `InnoDB': innodb-storage-engine, that employ row-level locking and do not actually perform (or need to perform) the locks prior to partition pruning. The next few paragraphs discuss the effects of MySQL statements on partitioned tables using storage engines that employ table-level locks. * DML statements * *Note `SELECT': select. statements lock the entire table. `SELECT' statements containing unions or joins lock all tables named in the union or join. *Note `UPDATE': update. also locks the entire table. *Note `REPLACE': replace. and *Note `INSERT': insert. (including *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate.) lock the entire table. *Note `INSERT ... SELECT': insert-select. locks both the source table and the target table. *Note*: *Note `INSERT DELAYED': insert-delayed. is not supported for partitioned tables. A *Note `LOAD DATA': load-data. statement on a partitioned table locks the entire table. A trigger on a partitioned table, once activated, locks the entire table. * DDL statements * *Note `CREATE VIEW': create-view. causes a lock on any partitioned table from which it reads. *Note `ALTER TABLE': alter-table. locks the affected partitioned table. * Other statements * *Note `LOCK TABLES': lock-tables. locks all partitions of a partioned table. Evaluating the EXPR in a *Note `CALL stored_procedure(EXPR)': call. statement locks all partitions of any partitioned table referenced by EXPR. *Note `ALTER TABLE': alter-table. also takes a metadata lock on the table level.  File: manual.info, Node: stored-programs-views, Next: information-schema, Prev: partitioning, Up: Top 19 Stored Programs and Views **************************** * Menu: * stored-programs-defining:: Defining Stored Programs * stored-routines:: Using Stored Routines (Procedures and Functions) * triggers:: Using Triggers * events:: Using the Event Scheduler * views:: Using Views * stored-programs-security:: Access Control for Stored Programs and Views * stored-programs-logging:: Binary Logging of Stored Programs 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 *Note `CALL': 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 *Note sql-syntax-data-definition::. * The *Note `CALL': call. statement is used to invoke stored procedures. See *Note call::. * Stored program definitions include a body that may use compound statements, loops, conditionals, and declared variables. See *Note sql-syntax-compound-statements::.  File: manual.info, Node: stored-programs-defining, Next: stored-routines, Prev: stored-programs-views, Up: stored-programs-views 19.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 *Note `BEGIN ... END': begin-end. block that contains a *Note `SET': set-statement. statement and a *Note `REPEAT': repeat. loop that itself contains another *Note `SET': set-statement. 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 *Note `mysql': mysql. client program to define a stored program containing semicolon characters, a problem arises. By default, *Note `mysql': mysql. itself recognizes the semicolon as a statement delimiter, so you must redefine the delimiter temporarily to cause *Note `mysql': mysql. to pass the entire stored program definition to the server. To redefine the *Note `mysql': 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 *Note `mysql': 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)  File: manual.info, Node: stored-routines, Next: triggers, Prev: stored-programs-defining, Up: stored-programs-views 19.2 Using Stored Routines (Procedures and Functions) ===================================================== * Menu: * stored-routines-syntax:: Stored Routine Syntax * stored-routines-privileges:: Stored Routines and MySQL Privileges * stored-routines-metadata:: Stored Routine Metadata * stored-routines-last-insert-id:: Stored Procedures, Functions, Triggers, and `LAST_INSERT_ID()' Stored routines (procedures and functions) are supported in MySQL 5.1. 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 5.1 installation procedure. If you are upgrading to MySQL 5.1 from an earlier version, be sure to update your grant tables to make sure that the `proc' table exists. See *Note 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 *Note faqs-stored-procs::. * There are some restrictions on the use of stored routines. See *Note stored-program-restrictions::. * Binary logging for stored routines takes place as described in *Note stored-programs-logging::.  File: manual.info, Node: stored-routines-syntax, Next: stored-routines-privileges, Prev: stored-routines, Up: stored-routines 19.2.1 Stored Routine Syntax ---------------------------- A stored routine is either a procedure or a function. Stored routines are created with the *Note `CREATE PROCEDURE': create-procedure. and *Note `CREATE FUNCTION': create-function. statements (see *Note create-procedure::). A procedure is invoked using a *Note `CALL': call. statement (see *Note 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 *Note sql-syntax-compound-statements::). Stored routines can be dropped with the *Note `DROP PROCEDURE': drop-procedure. and *Note `DROP FUNCTION': drop-function. statements (see *Note drop-procedure::), and altered with the *Note `ALTER PROCEDURE': alter-procedure. and *Note `ALTER FUNCTION': alter-function. statements (see *Note 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). *Note `USE': 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 *Note server-system-variables::, for more information. MySQL supports a very useful extension that enables the use of regular *Note `SELECT': 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 *Note `SELECT': 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 *Note `mysql_real_connect()': mysql-real-connect. C API function. See *Note mysql-real-connect::, and *Note c-api-multiple-queries::.  File: manual.info, Node: stored-routines-privileges, Next: stored-routines-metadata, Prev: stored-routines-syntax, Up: stored-routines 19.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.  File: manual.info, Node: stored-routines-metadata, Next: stored-routines-last-insert-id, Prev: stored-routines-privileges, Up: stored-routines 19.2.3 Stored Routine Metadata ------------------------------ Metadata about stored routines can be obtained as follows: * Query the *Note `ROUTINES': routines-table. table of the `INFORMATION_SCHEMA' database. See *Note routines-table::. * Use the *Note `SHOW CREATE PROCEDURE': show-create-procedure. and *Note `SHOW CREATE FUNCTION': show-create-function. statements to see routine definitions. See *Note show-create-procedure::. * Use the *Note `SHOW PROCEDURE STATUS': show-procedure-status. and *Note `SHOW FUNCTION STATUS': show-function-status. statements to see routine characteristics. See *Note show-procedure-status::. * `INFORMATION_SCHEMA' does not have a `PARAMETERS' table until MySQL 5.5, so applications that need to acquire routine parameter information at runtime must use workarounds such as parsing the output of `SHOW CREATE' statements or the `param_list' column of the `mysql.proc' table. `param_list' contents can be processed from within a stored routine, unlike the output from *Note `SHOW': show.  File: manual.info, Node: stored-routines-last-insert-id, Prev: stored-routines-metadata, Up: stored-routines 19.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 *Note 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.  File: manual.info, Node: triggers, Next: events, Prev: stored-routines, Up: stored-programs-views 19.3 Using Triggers =================== * Menu: * trigger-syntax:: Trigger Syntax and Examples * trigger-metadata:: Trigger Metadata 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 *Note `INSERT': insert. or *Note `LOAD DATA': 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. They do not activate for changes in views, nor by changes to tables made by APIs that do not transmit SQL statements to the MySQL Server. This means that: * Triggers are not activated by changes in `INFORMATION_SCHEMA' tables, because these tables are actually views. * Triggers are not activated by updates made using the *Note `NDB': mysql-cluster. API. To use triggers if you have upgraded to MySQL 5.1 from an older release that did not support triggers, you should upgrade your grant tables so that they contain the trigger-related privileges. See *Note mysql-upgrade::. 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 *Note faqs-triggers::. * There are some restrictions on the use of triggers; see *Note stored-program-restrictions::. * Binary logging for triggers takes place as described in *Note stored-programs-logging::.  File: manual.info, Node: trigger-syntax, Next: trigger-metadata, Prev: triggers, Up: triggers 19.3.1 Trigger Syntax and Examples ---------------------------------- To create a trigger or drop a trigger, use the *Note `CREATE TRIGGER': create-trigger. or *Note `DROP TRIGGER': drop-trigger. statement, described in *Note create-trigger::, and *Note drop-trigger::. Here is a simple example that associates a trigger with a table, to activate for *Note `INSERT': 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.06 sec) The *Note `CREATE TRIGGER': 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, *Note `INSERT': insert. operations cause trigger activation. You can also create triggers for *Note `DELETE': delete. and *Note `UPDATE': 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 *Note `SET': set-statement. 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 *Note `INSERT': 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 *Note `INSERT': insert. statement has executed is `14.98 + 1937.50 - 100', or `1852.48'. To destroy the trigger, use a *Note `DROP TRIGGER': 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. In addition to the requirement that trigger names be unique for a schema, there are other limitations on the types of triggers you can create. In particular, 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 *Note `BEGIN ... END': 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 *Note `SELECT': 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 *Note `BEGIN ... END': 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 *Note `mysql': mysql. program to define a trigger that executes multiple statements, it is necessary to redefine the *Note `mysql': 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 *Note `CALL': 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 *Note `CALL': 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 *Note `START TRANSACTION': commit, *Note `COMMIT': commit, or *Note `ROLLBACK': commit. See also *Note 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. In MySQL 5.1, 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)  File: manual.info, Node: trigger-metadata, Prev: trigger-syntax, Up: triggers 19.3.2 Trigger Metadata ----------------------- Metadata about triggers can be obtained as follows: * Query the *Note `TRIGGERS': triggers-table. table of the `INFORMATION_SCHEMA' database. See *Note triggers-table::. * Use the *Note `SHOW CREATE TRIGGER': show-create-trigger. statement. See *Note show-create-trigger::. * Use the *Note `SHOW TRIGGERS': show-triggers. statement. See *Note show-triggers::.  File: manual.info, Node: events, Next: views, Prev: triggers, Up: stored-programs-views 19.4 Using the Event Scheduler ============================== * Menu: * events-overview:: Event Scheduler Overview * events-configuration:: Event Scheduler Configuration * events-syntax:: Event Syntax * events-metadata:: Event Metadata * events-status-info:: Event Scheduler Status * events-privileges:: The Event Scheduler and MySQL Privileges The _MySQL Event Scheduler_ manages the scheduling and execution of events: Tasks that run according to schedule. Event support was added in MySQL 5.1.6. The following discussion covers the Event Scheduler and is divided into the following sections: * *Note events-overview::, provides an introduction to and conceptual overview of MySQL Events. * *Note events-syntax::, discusses the SQL statements for creating, altering, and dropping MySQL Events. * *Note events-metadata::, shows how to obtain information about events and how this information is stored by the MySQL Server. * *Note 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.1 installation procedure. If you are upgrading to MySQL 5.1 from an earlier version, be sure to update your grant tables to make sure that the `event' table exists. See *Note 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 *Note stored-program-restrictions::. * Binary logging for events takes place as described in *Note stored-programs-logging::.  File: manual.info, Node: events-overview, Next: events-configuration, Prev: events, Up: events 19.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 *Note 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 5.1.12 and later, an event is uniquely identified by its name and the schema to which it is assigned. (Previously, an event was also unique to its definer.) * 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 *Note `BEGIN ... END': begin-end. block if desired (see *Note 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 *Note 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 *Note 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 *Note `ALTER EVENT': 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. (Prior to MySQL 5.1.12, only an event's definer, or a user having privileges on the `mysql.event' table, could modify a given event.) See *Note events-privileges::. * An event's action statement may include most SQL statements permitted within stored routines. For restrictions, see *Note stored-program-restrictions::.  File: manual.info, Node: events-configuration, Next: events-syntax, Prev: events-overview, Up: events 19.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 *Note `SHOW PROCESSLIST': 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. Beginning with MySQL 5.1.12, 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 *Note `SHOW PROCESSLIST': 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 *Note `SHOW PROCESSLIST': 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 *Note `SHOW PROCESSLIST': 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 *Note `SET': set-statement.). 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 *Note `mysql': 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 *Note `SELECT': select. or *Note `SHOW VARIABLES': 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. In MySQL 5.1.11, `event_scheduler' behaved as follows: this variable could take one of the values `0' (or `OFF'), `1' (or `ON'), or `2'. Setting it to `0' turned event scheduling off, so that the event scheduler thread did not run; the `event_scheduler' variable could not be set to this value while the server was running. Setting it to `1' so that the event scheduler thread ran and executed scheduled events. In this state, the event scheduler thread appeared to be sleeping when viewed with *Note `SHOW PROCESSLIST': show-processlist. When `event_scheduler' was set to `2' (which was the default value), the Event Scheduler was considered to be `suspended'; the event scheduler thread ran and could be seen in the output of *Note `SHOW PROCESSLIST': show-processlist. (where `Suspended' was displayed in the `State' column), but did not execute any scheduled events. The value of `event_scheduler' could be changed only between `1' (or `ON') and `2' while the server was running. Setting it to `0' (or `OFF') required a server restart, as did changing its value from `0' (or `OFF') to `1' (or `ON') or `2'. Prior to MySQL 5.1.11, `event_scheduler' could take one of only the 2 values `0'|`OFF' or `1'|`ON', and the default value was `0'|`OFF'. It was also possible to start and stop the event scheduler thread while the MySQL server was running. For more information concerning the reasons for these changes in behavior, see Bug #17619. Beginning with MySQL 5.1.17, 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 *Note events-syntax::. MySQL 5.1.6 and later provides an *Note `EVENTS': events-table. 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 *Note events-metadata::, and *Note events-table::, for more information. For information regarding event scheduling and the MySQL privilege system, see *Note events-privileges::.  File: manual.info, Node: events-syntax, Next: events-metadata, Prev: events-configuration, Up: events 19.4.3 Event Syntax ------------------- MySQL 5.1.6 and later provides several SQL statements for working with scheduled events: * New events are defined using the *Note `CREATE EVENT': create-event. statement. See *Note create-event::. * The definition of an existing event can be changed by means of the *Note `ALTER EVENT': alter-event. statement. See *Note alter-event::. * When a scheduled event is no longer wanted or needed, it can be deleted from the server by its definer using the *Note `DROP EVENT': drop-event. statement. See *Note drop-event::. Whether an event persists past the end of its schedule also depends on its `ON COMPLETION' clause, if it has one. See *Note create-event::. An event can be dropped by any user having the `EVENT' privilege for the database on which the event is defined. Prior to MySQL 5.1.12, a user other than the definer required privileges on the `mysql.event' table. See *Note events-privileges::.  File: manual.info, Node: events-metadata, Next: events-status-info, Prev: events-syntax, Up: events 19.4.4 Event Metadata --------------------- Metadata about events can be obtained as follows: * Query the `event' table of the `mysql' database. * Query the *Note `EVENTS': events-table. table of the `INFORMATION_SCHEMA' database. See *Note events-table::. * Use the *Note `SHOW CREATE EVENT': show-create-event. statement. See *Note show-create-event::. * Use the *Note `SHOW EVENTS': show-events. statement. See *Note 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 *Note `CREATE EVENT': create-event. or *Note `ALTER EVENT': 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 *Note `INFORMATION_SCHEMA.EVENTS': events-table. table or from *Note `SHOW EVENTS': 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. This table summarizes the representation of event times (as UTC, EZT, or STZ values) from `mysql.event', *Note `INFORMATION_SCHEMA.EVENTS': events-table, and *Note `SHOW EVENTS': show-events. Value `mysql.event' *Note *Note `SHOW `INFORMATION_SCHEMA.EVENTS':EVENTS': events-table. 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 The preceding table applies for MySQL 5.1.17 and up. Prior to MySQL 5.1.17, the event time zone is not stored in the `mysql.event' table or available from *Note `INFORMATION_SCHEMA.EVENTS': events-table. or *Note `SHOW EVENTS': show-events. Times that are displayed using ETZ from 5.1.17 and up are displayed in UTC before 5.1.17, as shown in the following table. This table summarizes the representation of event times (as UTC, EZT, or STZ values) from `mysql.event', *Note `INFORMATION_SCHEMA.EVENTS': events-table, and *Note `SHOW EVENTS': show-events. prior to MySQL 5.1.17. Value `mysql.event' *Note *Note `SHOW `INFORMATION_SCHEMA.EVENTS':EVENTS': events-table. show-events. Execute at UTC UTC UTC Starts UTC UTC UTC Ends UTC UTC UTC Last executed UTC UTC n/a Created STZ STZ n/a Last altered STZ STZ n/a  File: manual.info, Node: events-status-info, Next: events-privileges, Prev: events-metadata, Up: events 19.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 *Note events-privileges:: for an example. (Before MySQL 5.1.31, the Event Scheduler also logged messages when events started execution and terminated successfully.) Information about the state of the Event Scheduler for debugging and troubleshooting purposes can be obtained as follows: * In debugging builds of MySQL 5.1.11, you can use the `SHOW SCHEDULER STATUS' statement; see *Note show-scheduler-status::. This statement was removed in MySQL 5.1.12. We intend to implement an SQL statement providing similar functionality in a future MySQL release. * Beginning with MySQL 5.1.12, event scheduler status information can be obtained by running *Note `mysqladmin debug': mysqladmin. (see *Note 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 *Note 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.  File: manual.info, Node: events-privileges, Prev: events-status-info, Up: events 19.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. MySQL 5.1.6 introduces a privilege governing the creation, modification, and deletion of events, the `EVENT' privilege. This privilege can be bestowed using *Note `GRANT': grant. For example, this *Note `GRANT': 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, as indicated by `RetCode=0': 060209 22:39:44 [Note] EVEX EXECUTING event newdb.e [EXPR:10] 060209 22:39:44 [Note] EVEX EXECUTED event newdb.e [EXPR:10]. RetCode=0 060209 22:39:54 [Note] EVEX EXECUTING event newdb.e [EXPR:10] 060209 22:39:54 [Note] EVEX EXECUTED event newdb.e [EXPR:10]. RetCode=0 060209 22:40:04 [Note] EVEX EXECUTING event newdb.e [EXPR:10] 060209 22:40:04 [Note] EVEX EXECUTED event newdb.e [EXPR:10]. RetCode=0 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 *Note `INFORMATION_SCHEMA.EVENTS': events-table. 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) *Note*: Prior to MySQL 5.1.12, there was no `EVENT_DEFINITION' column, and `EVENT_BODY' contained the SQL statement or statements to be executed. See *Note events-table::, for more information. To rescind the `EVENT' privilege, use the *Note `REVOKE': 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 *Note `INFORMATION_SCHEMA.EVENTS': events-table. table (see *Note events-table::) before and after issuing a *Note `DROP USER': drop-user. or *Note `RENAME USER': rename-user. statement. Event definitions are stored in the `mysql.event' table, which was added in MySQL 5.1.6. 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. *Note*: The namespace for scheduled events changed in MySQL 5.1.12. Prior to that MySQL version, different users could create different events having the same name in the same database; in MySQL 5.1.12 and later, that is no longer the case. When upgrading to MySQL 5.1.12 or later from MySQL 5.1.11 or earlier, it is extremely important to make sure that no events in the same database share the same name, _prior to performing the upgrade_. 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, *Note `GRANT': 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 *Note `GRANT EVENT': grant. and `REVOKE EVENT' statements perform the required operations on them. MySQL 5.1.6 introduces five status variables providing counts of event-related operations (but _not_ of statements executed by events; see *Note stored-program-restrictions::). These are: * `Com_create_event': The number of *Note `CREATE EVENT': create-event. statements executed since the last server restart. * `Com_alter_event': The number of *Note `ALTER EVENT': alter-event. statements executed since the last server restart. * `Com_drop_event': The number of *Note `DROP EVENT': drop-event. statements executed since the last server restart. * `Com_show_create_event': The number of *Note `SHOW CREATE EVENT': show-create-event. statements executed since the last server restart. * `Com_show_events': The number of *Note `SHOW EVENTS': 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%';'.  File: manual.info, Node: views, Next: stored-programs-security, Prev: events, Up: stored-programs-views 19.5 Using Views ================ * Menu: * view-syntax:: View Syntax * view-algorithms:: View Processing Algorithms * view-updatability:: Updatable and Insertable Views * view-metadata:: View Metadata Views (including updatable views) are available in MySQL Server 5.1. Views are stored queries that when invoked produce a result set. A view acts as a virtual table. To use views if you have upgraded to MySQL 5.1 from an older release that did not support views, you should upgrade your grant tables so that they contain the view-related privileges. See *Note mysql-upgrade::. 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 *Note faqs-views::. * There are some restrictions on the use of views; see *Note view-restrictions::.  File: manual.info, Node: view-syntax, Next: view-algorithms, Prev: views, Up: views 19.5.1 View Syntax ------------------ The *Note `CREATE VIEW': create-view. statement creates a new view (see *Note create-view::). To alter the definition of a view or drop a view, use *Note `ALTER VIEW': alter-view. (see *Note alter-view::), or *Note `DROP VIEW': drop-view. (see *Note drop-view::). A view can be created from many kinds of *Note `SELECT': select. statements. It can refer to base tables or other views. It can use joins, *Note `UNION': union, and subqueries. The *Note `SELECT': 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 | +------+-------+-------+  File: manual.info, Node: view-algorithms, Next: view-updatability, Prev: view-syntax, Up: views 19.5.2 View Processing Algorithms --------------------------------- The optional `ALGORITHM' clause for *Note `CREATE VIEW': create-view. or *Note `ALTER VIEW': alter-view. is a MySQL extension to standard SQL. It affects how MySQL processes the view. `ALGORITHM' takes three values: `MERGE', `TEMPTABLE', or `UNDEFINED'. The default algorithm is `UNDEFINED' if no `ALGORITHM' clause is present. 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. A reason to choose `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 *Note `CREATE VIEW': create-view. statement. * The *Note `CREATE VIEW': 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. `MERGE' cannot be used if the view contains any of the following constructs: * Aggregate functions (`SUM()', `MIN()', `MAX()', `COUNT()', and so forth) * `DISTINCT' * `GROUP BY' * `HAVING' * `LIMIT' * *Note `UNION': union. or *Note `UNION ALL': union. * Subquery in the select list * Refers only to literal values (in this case, there is no underlying table)  File: manual.info, Node: view-updatability, Next: view-metadata, Prev: view-algorithms, Up: views 19.5.3 Updatable and Insertable Views ------------------------------------- Some views are updatable. That is, you can use them in statements such as *Note `UPDATE': update, *Note `DELETE': delete, or *Note `INSERT': 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. 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' * *Note `UNION': union. or *Note `UNION ALL': union. * Subquery in the select list * Certain joins (see additional join discussion later in this section) * Nonupdatable view in the `FROM' clause * A 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) * Uses `ALGORITHM = TEMPTABLE' (use of a temporary table always makes a view nonupdatable) * Multiple references to any column of a base table. With respect to insertability (being updatable with *Note `INSERT': 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 and not derived columns. A derived column is one that is not a simple column reference but is derived from an expression. These are examples of derived columns: 3.14159 col1 + 3 UPPER(col2) col3 / col4 (SUBQUERY) A view that has a mix of simple column references and derived columns is not insertable, but it can be updatable if you update only those columns that are not derived. Consider this view: CREATE VIEW v AS SELECT col1, 1 AS col2 FROM t; This view is not insertable because `col2' is derived from 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 a derived column: UPDATE v SET col2 = 0; 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 *Note `UNION': 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 *Note `UNION ALL': union. are not permitted even though they might be theoretically updatable, because the implementation uses temporary tables to process them. For a multiple-table updatable view, *Note `INSERT': insert. can work if it inserts into a single table. *Note `DELETE': delete. is not supported. *Note `INSERT DELAYED': insert-delayed. is not supported for views. 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. 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'. Consider the definitions for the following table and set of views: mysql> CREATE TABLE t1 (a INT); mysql> CREATE VIEW v1 AS SELECT * FROM t1 WHERE a < 2 -> WITH CHECK OPTION; mysql> CREATE VIEW v2 AS SELECT * FROM v1 WHERE a > 0 -> WITH LOCAL CHECK OPTION; mysql> 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'. `v2' has a `LOCAL' check option, so inserts are tested only against the `v2' check. `v3' has a `CASCADED' check option, so inserts are tested not only against its own 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' MySQL sets a flag, called the view updatability flag, at *Note `CREATE VIEW': create-view. time. The flag is set to `YES' (true) if *Note `UPDATE': update. and *Note `DELETE': delete. (and similar operations) are legal for the view. Otherwise, the flag is set to `NO' (false). The `IS_UPDATABLE' column in the *Note `INFORMATION_SCHEMA.VIEWS': views-table. table displays the status of this flag. It means that the server always knows whether a view is updatable. If the view is not updatable, statements such *Note `UPDATE': update, *Note `DELETE': delete, and *Note `INSERT': insert. are illegal and will be 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 updatability of views may be affected by the value of the `updatable_views_with_limit' system variable. See *Note server-system-variables::.  File: manual.info, Node: view-metadata, Prev: view-updatability, Up: views 19.5.4 View Metadata -------------------- Metadata about views can be obtained as follows: * Query the *Note `VIEWS': views-table. table of the `INFORMATION_SCHEMA' database. See *Note views-table::. * Use the *Note `SHOW CREATE VIEW': show-create-view. statement. See *Note show-create-view::.  File: manual.info, Node: stored-programs-security, Next: stored-programs-logging, Prev: views, Up: stored-programs-views 19.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 a `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 *Note `CALL': 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.  File: manual.info, Node: stored-programs-logging, Prev: stored-programs-security, Up: stored-programs-views 19.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 *Note 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 *Note recovery-from-backups::. However, there are certain binary logging issues that apply with respect to stored programs (stored procedures and functions, triggers, and events), if logging occurs at the statement level: * In some cases, it is possible that a statement will affect different sets of rows on a master and a 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 a master and slave, or cause restored data to differ from the original data. This section describes how MySQL 5.1 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 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. 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 *Note `CALL': 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. For general information about row-based logging, see *Note replication-formats::. Unless noted otherwise, the remarks here assume that you have enabled binary logging by starting the server with the `--log-bin' option. (See *Note binary-log::.) If the binary log is not enabled, replication is not possible, nor is the binary log available for data recovery. The current conditions on the use of stored functions in MySQL 5.1 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 *Note 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 *Note `CREATE FUNCTION': 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. * Although it is possible to create a deterministic stored function without specifying `DETERMINISTIC', you cannot as of MySQL 5.1.15 execute this function using statement-based binary logging. To execute such a function, you must use row-based or mixed binary logging. Alternatively, if you explicitly specify `DETERMINISTIC' in the function definition, you can use any kind of logging, including statement-based logging. * 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 *Note replication-features::. Triggers are similar to stored functions, so the preceding remarks regarding functions also apply to triggers with the following exception: *Note `CREATE TRIGGER': create-trigger. does not have an optional `DETERMINISTIC' characteristic, so triggers are assumed to be always deterministic. However, this assumption might in some cases be invalid. For example, the `UUID()' function is nondeterministic (and does not replicate). You should be careful about using such functions in triggers. Triggers can update tables, so error messages similar to those for stored functions occur with *Note `CREATE TRIGGER': 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 *Note `CREATE EVENT': create-event, *Note `CREATE PROCEDURE': create-procedure, *Note `CREATE FUNCTION': create-function, *Note `ALTER EVENT': alter-event, *Note `ALTER PROCEDURE': alter-procedure, *Note `ALTER FUNCTION': alter-function, *Note `DROP EVENT': drop-event, *Note `DROP PROCEDURE': drop-procedure, and *Note `DROP FUNCTION': drop-function. statements to the binary log. * A stored function invocation is logged as a *Note `SELECT': 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, *Note `SELECT': select. statements are not written to the binary log, but a *Note `SELECT': 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 *Note `SELECT': select. statement executes, the function `f1()' is invoked three times. Two of those invocations insert a row, and MySQL logs a *Note `SELECT': 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 *Note `SELECT': 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 *Note `SELECT': 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. Note: Before MySQL 5.1.7, you will see these `SELECT FUNC_NAME()' statements logged as `DO FUNC_NAME()'. The change to *Note `SELECT': select. was made because use of *Note `DO': do. was found to yield insufficient control over error code checking. * 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 *Note `CREATE FUNCTION': create-function. and *Note `INSERT': 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 *Note `ALTER FUNCTION': 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 *Note `CREATE FUNCTION': 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 *Note `CALL': call. level. That is, the server does not log the *Note `CALL': 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 *Note `CREATE TABLE ... SELECT': create-table. 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 *Note `SET': set-statement. 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 *Note `BEGIN': commit, *Note `COMMIT': commit, and *Note `ROLLBACK': commit. 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, *Note `BEGIN': commit. and *Note `COMMIT': 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 *Note `BEGIN': commit. and *Note `ROLLBACK': commit. 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 *Note `DO': 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.  File: manual.info, Node: information-schema, Next: connectors-apis, Prev: stored-programs-views, Up: Top 20 `INFORMATION_SCHEMA' Tables ****************************** * Menu: * character-sets-table:: The `INFORMATION_SCHEMA CHARACTER_SETS' Table * collations-table:: The `INFORMATION_SCHEMA COLLATIONS' Table * collation-character-set-applicability-table:: The `INFORMATION_SCHEMA COLLATION_CHARACTER_SET_APPLICABILITY' Table * columns-table:: The `INFORMATION_SCHEMA COLUMNS' Table * column-privileges-table:: The `INFORMATION_SCHEMA COLUMN_PRIVILEGES' Table * engines-table:: The `INFORMATION_SCHEMA ENGINES' Table * events-table:: The `INFORMATION_SCHEMA EVENTS' Table * status-table:: The `INFORMATION_SCHEMA GLOBAL_STATUS' and `SESSION_STATUS' Tables * variables-table:: The `INFORMATION_SCHEMA GLOBAL_VARIABLES' and `SESSION_VARIABLES' Tables * key-column-usage-table:: The `INFORMATION_SCHEMA KEY_COLUMN_USAGE' Table * partitions-table:: The `INFORMATION_SCHEMA PARTITIONS' Table * plugins-table:: The `INFORMATION_SCHEMA PLUGINS' Table * processlist-table:: The `INFORMATION_SCHEMA PROCESSLIST' Table * profiling-table:: The `INFORMATION_SCHEMA PROFILING' Table * referential-constraints-table:: The `INFORMATION_SCHEMA REFERENTIAL_CONSTRAINTS' Table * routines-table:: The `INFORMATION_SCHEMA ROUTINES' Table * schemata-table:: The `INFORMATION_SCHEMA SCHEMATA' Table * schema-privileges-table:: The `INFORMATION_SCHEMA SCHEMA_PRIVILEGES' Table * statistics-table:: The `INFORMATION_SCHEMA STATISTICS' Table * tables-table:: The `INFORMATION_SCHEMA TABLES' Table * table-constraints-table:: The `INFORMATION_SCHEMA TABLE_CONSTRAINTS' Table * table-privileges-table:: The `INFORMATION_SCHEMA TABLE_PRIVILEGES' Table * triggers-table:: The `INFORMATION_SCHEMA TRIGGERS' Table * user-privileges-table:: The `INFORMATION_SCHEMA USER_PRIVILEGES' Table * views-table:: The `INFORMATION_SCHEMA VIEWS' Table * mysql-cluster-i_s-tables:: `INFORMATION_SCHEMA' Tables for MySQL Cluster * extended-show:: Extensions to `SHOW' Statements `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_. * Usage Notes for the `INFORMATION_SCHEMA' Database * `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 *Note `USE': use. statement, you can only read the contents of tables, not perform *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': 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 *Note 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 *Note `SHOW': show. statements that MySQL supports (*Note `SHOW DATABASES': show-databases, *Note `SHOW TABLES': show-tables, and so forth). Using *Note `SELECT': select. has these advantages, compared to *Note `SHOW': show.: * It conforms to Codd's rules, because all access is done on tables. * You can use the familiar syntax of the *Note `SELECT': 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 *Note `SHOW': show. is familiar and widely used, the *Note `SHOW': show. statements remain as an alternative. In fact, along with the implementation of `INFORMATION_SCHEMA', there are enhancements to *Note `SHOW': show. as described in *Note 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 *Note `INFORMATION_SCHEMA.ROUTINES': routines-table. table), users who have insufficient privileges see `NULL'. These restrictions do not apply for *Note `InnoDB': innodb-storage-engine. 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 *Note `SHOW': 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 *Note `EXPLAIN': explain. For information about using *Note `EXPLAIN': explain. output to tune `INFORMATION_SCHEMA' queries, see *Note 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 *Note `INFORMATION_SCHEMA.TABLES': tables-table. 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 *Note `TABLES': tables-table. table.) See the list of reserved words near the end of this article: `http://web.archive.org/web/20070409075643rn_1/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.' * `*Note `SHOW': show. Name' indicates the equivalent field name in the closest *Note `SHOW': 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 *Note `SHOW': show. statement is equivalent to a *Note `SELECT': select. that retrieves information from `INFORMATION_SCHEMA'. For *Note `SHOW': 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. For information about `INFORMATION_SCHEMA' tables specific to the *Note `NDB': mysql-cluster. storage engine (MySQL Cluster), see *Note mysql-cluster-i_s-tables::. For answers to questions that are often asked concerning the `INFORMATION_SCHEMA' database, see *Note faqs-information-schema::.  File: manual.info, Node: character-sets-table, Next: collations-table, Prev: information-schema, Up: information-schema 20.1 The `INFORMATION_SCHEMA CHARACTER_SETS' Table ================================================== The *Note `CHARACTER_SETS': character-sets-table. table provides information about available character sets. This table describes the `INFORMATION_SCHEMA' *Note `CHARACTER_SETS': character-sets-table. table. `INFORMATION_SCHEMA' Name *Note `SHOW': 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']  File: manual.info, Node: collations-table, Next: collation-character-set-applicability-table, Prev: character-sets-table, Up: information-schema 20.2 The `INFORMATION_SCHEMA COLLATIONS' Table ============================================== The *Note `COLLATIONS': collations-table. table provides information about collations for each character set. This table describes the `INFORMATION_SCHEMA' *Note `COLLATIONS': collations-table. table. `INFORMATION_SCHEMA' Name *Note `SHOW': 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 *Note `SHOW COLLATION': show-collation. statement. The following statements are equivalent: SELECT COLLATION_NAME FROM INFORMATION_SCHEMA.COLLATIONS [WHERE COLLATION_NAME LIKE 'WILD'] SHOW COLLATION [LIKE 'WILD']  File: manual.info, Node: collation-character-set-applicability-table, Next: columns-table, Prev: collations-table, Up: information-schema 20.3 The `INFORMATION_SCHEMA COLLATION_CHARACTER_SET_APPLICABILITY' Table ========================================================================= The *Note `COLLATION_CHARACTER_SET_APPLICABILITY': collation-character-set-applicability-table. table indicates what character set is applicable for what collation. The columns are equivalent to the first two display fields that we get from *Note `SHOW COLLATION': show-collation. This table describes the `INFORMATION_SCHEMA COLLATION_CHARACTER_SET_APPLICABILITY' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `COLLATION_NAME' `Collation' `CHARACTER_SET_NAME' `Charset'  File: manual.info, Node: columns-table, Next: column-privileges-table, Prev: collation-character-set-applicability-table, Up: information-schema 20.4 The `INFORMATION_SCHEMA COLUMNS' Table =========================================== The *Note `COLUMNS': columns-table. table provides information about columns in tables. This table describes the `INFORMATION_SCHEMA COLUMNS' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `TABLE_CATALOG' `NULL' `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' `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 *Notes*: * In *Note `SHOW': show, the `Type' display includes values from several different *Note `COLUMNS': columns-table. columns. * `ORDINAL_POSITION' is necessary because you might want to say `ORDER BY ORDINAL_POSITION'. Unlike *Note `SHOW': show, *Note `SELECT': select. does not have automatic ordering. * `CHARACTER_OCTET_LENGTH' should be the same as `CHARACTER_MAXIMUM_LENGTH', except for multi-byte 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'. 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']  File: manual.info, Node: column-privileges-table, Next: engines-table, Prev: columns-table, Up: information-schema 20.5 The `INFORMATION_SCHEMA COLUMN_PRIVILEGES' Table ===================================================== The *Note `COLUMN_PRIVILEGES': column-privileges-table. table provides information about column privileges. This information comes from the `mysql.columns_priv' grant table. This table describes the `INFORMATION_SCHEMA COLUMN_PRIVILEGES' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `GRANTEE' `'USER_NAME'@'HOST_NAME'' value `TABLE_CATALOG' `NULL' `TABLE_SCHEMA' `TABLE_NAME' `COLUMN_NAME' `PRIVILEGE_TYPE' `IS_GRANTABLE' *Notes*: * In the output from *Note `SHOW FULL COLUMNS': show-columns, the privileges are all in one field and in lowercase, for example, `select,insert,update,references'. In *Note `COLUMN_PRIVILEGES': column-privileges-table, 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 ...  File: manual.info, Node: engines-table, Next: events-table, Prev: column-privileges-table, Up: information-schema 20.6 The `INFORMATION_SCHEMA ENGINES' Table =========================================== The *Note `ENGINES': engines-table. table provides information about storage engines. This table describes the `INFORMATION_SCHEMA ENGINES' table. `INFORMATION_SCHEMA' Name *Note `SHOW': 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 *Note `ENGINES': engines-table. table is a nonstandard table. It was added in MySQL 5.1.5. See also *Note show-engines::.  File: manual.info, Node: events-table, Next: status-table, Prev: engines-table, Up: information-schema 20.7 The `INFORMATION_SCHEMA EVENTS' Table ========================================== The *Note `EVENTS': events-table. table provides information about scheduled events, which are discussed in *Note events::. The `SHOW Name' values correspond to column names of the *Note `SHOW EVENTS': show-events. statement. This table describes the `INFORMATION_SCHEMA EVENTS' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `EVENT_CATALOG' `NULL', 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 *Note `EVENTS': events-table. table is a nonstandard table. It was added in MySQL 5.1.6. * `EVENT_CATALOG': The value of this column is always `NULL'. * `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'. This column was added in MySQL 5.1.17. See Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/) for MySQL 5.1.17 for important information if you are using the Event Scheduler and are upgrading to MySQL 5.1.17 or later from an earlier version. * `EVENT_BODY': The language used for the statements in the event's *Note `DO': do. clause; in MySQL 5.1, this is always `SQL'. This column was added in MySQL 5.1.12. It 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 *Note `DO': do. clause; in other words, the statement executed by this event. *Note*: Prior to MySQL 5.1.12, this column was named `EVENT_BODY'. * `EVENT_TYPE': The event repetition type, either `ONE TIME' (transient) or `RECURRING' (repeating). * `EXECUTE_AT': For a one-time event, this is the *Note `DATETIME': datetime. value specified in the `AT' clause of the *Note `CREATE EVENT': create-event. statement used to create the event, or of the last *Note `ALTER EVENT': 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 '*Note `YEAR': year.', '`QUARTER'', '`DAY'', and so on. *Note*: In early MySQL 5.1 releases, this value was prefixed with '`INTERVAL_'', and was displayed as '`INTERVAL_YEAR'', '`INTERVAL_QUARTER'', '`INTERVAL_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 *Note server-sql-mode::. * `STARTS': For a recurring event whose definition includes a `STARTS' clause, this column contains the corresponding *Note `DATETIME': 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'. (Prior to MySQL 5.1.8, it contained `0000-00-00 00:00:00' in such cases.) * `ENDS': For a recurring event whose definition includes a `ENDS' clause, this column contains the corresponding *Note `DATETIME': 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' was added to the list of possible values for this column in MySQL 5.1.18. This value 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 *Note 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 *Note `TIMESTAMP': datetime. value. * `LAST_ALTERED': The date and time when the event was last modified. This is a *Note `TIMESTAMP': datetime. 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 *Note `DATETIME': datetime. value. If the event has never executed, this column is `NULL'. Before MySQL 5.1.23, `LAST_EXECUTED' indicates when event finished executing. As of 5.1.23, `LAST_EXECUTED' instead 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. This column was added in MySQL 5.1.18. * `CHARACTER_SET_CLIENT': The session value of the `character_set_client' system variable when the event was created. This column was added in MySQL 5.1.21. * `COLLATION_CONNECTION': The session value of the `collation_connection' system variable when the event was created. This column was added in MySQL 5.1.21. * `DATABASE_COLLATION': The collation of the database with which the event is associated. This column was added in MySQL 5.1.21. *Example*: Suppose that the user `jon@ghidora' creates an event named `e_daily', and then modifies it a few minutes later using an *Note `ALTER EVENT': 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 ENABLED; (Note that comments can span multiple lines.) This user can then run the following *Note `SELECT': 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: NULL 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 *Note `EVENTS': events-table. table are displayed using the event time zone or the current session time zone. Prior to MySQL 5.1.17, some of the times are displayed in UTC rather than the event time zone. For details, see *Note events-metadata::. See also *Note show-events::.  File: manual.info, Node: status-table, Next: variables-table, Prev: events-table, Up: information-schema 20.8 The `INFORMATION_SCHEMA GLOBAL_STATUS' and `SESSION_STATUS' Tables ======================================================================= The *Note `GLOBAL_STATUS': status-table. and *Note `SESSION_STATUS': status-table. tables provide information about server status variables. Their contents correspond to the information produced by the *Note `SHOW GLOBAL STATUS': show-status. and *Note `SHOW SESSION STATUS': show-status. statements (see *Note show-status::). This table describes the *Note `INFORMATION_SCHEMA GLOBAL_STATUS': status-table. and *Note `SESSION_STATUS': status-table. tables. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name VARIABLE_NAME Variable_name VARIABLE_VALUE Value *Notes*: * The *Note `GLOBAL_STATUS': status-table. and *Note `SESSION_STATUS': status-table. tables were added in MySQL 5.1.12. * Beginning with MySQL 5.1.19, the `VARIABLE_VALUE' column for each of these tables is defined as `VARCHAR(20480)'. Previously, this column had the data type `DECIMAL(22,7)', but was changed to avoid loss of data when working with status variables whose values were strings (Bug #26994).  File: manual.info, Node: variables-table, Next: key-column-usage-table, Prev: status-table, Up: information-schema 20.9 The `INFORMATION_SCHEMA GLOBAL_VARIABLES' and `SESSION_VARIABLES' Tables ============================================================================= The *Note `GLOBAL_VARIABLES': variables-table. and *Note `SESSION_VARIABLES': variables-table. tables provide information about server status variables. Their contents correspond to the information produced by the *Note `SHOW GLOBAL VARIABLES': show-variables. and *Note `SHOW SESSION VARIABLES': show-variables. statements (see *Note show-variables::). This table describes the *Note `INFORMATION_SCHEMA GLOBAL_VARIABLES': variables-table. and *Note `SESSION_VARIABLES': variables-table. tables. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name VARIABLE_NAME Variable_name VARIABLE_VALUE Value *Notes*: * The *Note `GLOBAL_VARIABLES': variables-table. and *Note `SESSION_VARIABLES': variables-table. tables were added in MySQL 5.1.12. * Beginning with MySQL 5.1.19, the `VARIABLE_VALUE' column for each of these tables is defined as `VARCHAR(20480)'. Previously, this column had the data type *Note `LONGTEXT': blob.; this was changed to make these tables consistent with the *Note `GLOBAL_STATUS': status-table. and *Note `SESSION_STATUS': status-table. tables, whose definitions had been changed in that version (see *Note status-table::).  File: manual.info, Node: key-column-usage-table, Next: partitions-table, Prev: variables-table, Up: information-schema 20.10 The `INFORMATION_SCHEMA KEY_COLUMN_USAGE' Table ===================================================== The *Note `KEY_COLUMN_USAGE': key-column-usage-table. table describes which key columns have constraints. This table describes the `INFORMATION_SCHEMA KEY_COLUMN_USAGE' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `CONSTRAINT_CATALOG' `NULL' `CONSTRAINT_SCHEMA' `CONSTRAINT_NAME' `TABLE_CATALOG' `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 *Note `KEY_COLUMN_USAGE': key-column-usage-table. 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'.  File: manual.info, Node: partitions-table, Next: plugins-table, Prev: key-column-usage-table, Up: information-schema 20.11 The `INFORMATION_SCHEMA PARTITIONS' Table =============================================== The *Note `PARTITIONS': partitions-table. table provides information about table partitions. See *Note partitioning::, for more information about partitioning tables. This table describes the `INFORMATION_SCHEMA PARTITIONS' table. `INFORMATION_SCHEMA' Name *Note `SHOW': 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 *Note `PARTITIONS': partitions-table. table is a nonstandard table. It was added in MySQL 5.1.6. Each record in this table corresponds to an individual partition or subpartition of a partitioned table. * `TABLE_CATALOG': This column is always `NULL'. * `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 *Note `PARTITIONS': partitions-table. 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 *Note 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 *Note partitioning-subpartitions::. * `PARTITION_EXPRESSION': This is the expression for the partitioning function used in the *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': 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 *Note `InnoDB': innodb-storage-engine. 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. Beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, `TABLE_ROWS' shows correct information for *Note `NDB': mysql-cluster. tables. Previously, for partitions of *Note `NDB': mysql-cluster. tables, the `TABLE_ROWS' column value was always 0. For *Note `NDB': mysql-cluster. tables, you can also obtain this information using the *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility. * `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'. Beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, `AVG_ROW_LENGTH' includes statistics for partitions of *Note `NDB': mysql-cluster. tables, whether the tables use implicit or explicit partitioning. (Previously the value of this column was always 0 for partitions of *Note `NDB': mysql-cluster. tables.) You can also obtain equivalent information using the *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility. * `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. Beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, `DATA_LENGTH' shows correct information for in-memory data in *Note `NDB': mysql-cluster. tables. Previously, for partitions of *Note `NDB': mysql-cluster. tables, the `DATA_LENGTH' column value was always 0. For *Note `NDB': mysql-cluster. tables, you can also obtain this information using the *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility. * `MAX_DATA_LENGTH': The maximum number of bytes that can be stored in this partition or subpartition. Beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, `MAX_DATA_LENGTH' shows the space allocated for the disk part of a MySQL Cluster Disk Data table or fragment. (Previously, for partitions of *Note `NDB': mysql-cluster. tables, the `MAX_DATA_LENGTH' column value was always `NULL'.) For *Note `NDB': mysql-cluster. tables, you can also obtain this information using the *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility. * `INDEX_LENGTH': The length of the index file for this partition or subpartition, in bytes. For partitions of *Note `NDB': mysql-cluster. tables, whether the tables use implicit or explicit partitioning, the `INDEX_LENGTH' column value is always 0. However, you can obtain equivalent information using the *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility. * `DATA_FREE': The number of bytes allocated to the partition or subpartition but not used. For MySQL Cluster Disk Data tables, beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, `DATA_FREE' shows the space allocated on disk for, but not used by, a Disk Data table or fragment on disk. (Previously, for partitions of *Note `NDB': mysql-cluster. tables, the value of this column was always 0.) For *Note `NDB': mysql-cluster. tables, you can also obtain this information using the *Note `ndb_desc': mysql-cluster-programs-ndb-desc. utility. * `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. *Note*: Some storage engines do not update this time; for tables using these storage engines, this value 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.1, the display width of this column is 80 characters, and partition comments which exceed this length are truncated to fit. This issue is fixed in MySQL 5.6. (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 MySQL 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. Currently, the value of this column is always `DEFAULT'. * *Important*: If any partitioned tables created in a MySQL version prior to MySQL 5.1.6 are present following an upgrade to MySQL 5.1.6 or later, it is not possible to *Note `SELECT': select. from, *Note `SHOW': show, or *Note `DESCRIBE': describe. the *Note `PARTITIONS': partitions-table. table. See the Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/) for MySQL 5.1.6 _before_ upgrading from MySQL 5.1.5 or earlier to MySQL 5.1.6 or later. * A nonpartitioned table has one record in *Note `INFORMATION_SCHEMA.PARTITIONS': partitions-table.; 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.) In MySQL 5.1, there is also only one record in the *Note `PARTITIONS': partitions-table. table for a table using the *Note `NDBCLUSTER': mysql-cluster. storage engine. The same columns are also `NULL' (or empty) as for a nonpartitioned table.  File: manual.info, Node: plugins-table, Next: processlist-table, Prev: partitions-table, Up: information-schema 20.12 The `INFORMATION_SCHEMA PLUGINS' Table ============================================ The *Note `PLUGINS': plugins-table. table provides information about server plugins. This table describes the `INFORMATION_SCHEMA PLUGINS' table. `INFORMATION_SCHEMA' Name *Note `SHOW': 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' MySQL extension *Notes*: * The *Note `PLUGINS': plugins-table. table is a nonstandard table. It was added in MySQL 5.1.5. * `PLUGIN_NAME' is the name used to refer to the plugin in statements such as *Note `INSTALL PLUGIN': install-plugin. and *Note `UNINSTALL PLUGIN': 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' or `INFORMATION_SCHEMA'. * `PLUGIN_TYPE_VERSION' is the version from the plugin's type-specific descriptor. * `PLUGIN_LIBRARY' is the name of the plugin shared object file. This is the name used to refer to the plugin file in statements such as *Note `INSTALL PLUGIN': install-plugin. and *Note `UNINSTALL PLUGIN': 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 *Note `UNINSTALL PLUGIN': 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'. This column was added in MySQL 5.1.12. For plugins installed with *Note `INSTALL PLUGIN': 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 *Note `PLUGINS': plugins-table. table, see *Note plugin-api::. Plugin information is also available using the *Note `SHOW PLUGINS': show-plugins. statement. See *Note show-plugins::.  File: manual.info, Node: processlist-table, Next: profiling-table, Prev: plugins-table, Up: information-schema 20.13 The `INFORMATION_SCHEMA PROCESSLIST' Table ================================================ The *Note `PROCESSLIST': processlist-table. table provides information about which threads are running. This table describes the `INFORMATION_SCHEMA PROCESSLIST' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `ID' `Id' MySQL extension `USER' `User' MySQL extension `HOST' `Host' MySQL extension `DB' `db' MySQL extension `COMMAND' `Command' MySQL extension *Note `TIME': time. `Time' MySQL extension `STATE' `State' MySQL extension `INFO' `Info' MySQL extension For an extensive description of the table columns, see *Note show-processlist::. *Notes*: * The *Note `PROCESSLIST': processlist-table. table is a nonstandard table. It was added in MySQL 5.1.7. * Like the output from the corresponding *Note `SHOW': show. statement, the *Note `PROCESSLIST': processlist-table. 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 *Note `INFORMATION_SCHEMA.PROCESSLIST': processlist-table, then MySQL will populate 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. The following statements are equivalent: SELECT * FROM INFORMATION_SCHEMA.PROCESSLIST SHOW FULL PROCESSLIST  File: manual.info, Node: profiling-table, Next: referential-constraints-table, Prev: processlist-table, Up: information-schema 20.14 The `INFORMATION_SCHEMA PROFILING' Table ============================================== The *Note `PROFILING': profiling-table. table provides statement profiling information. Its contents correspond to the information produced by the *Note `SHOW PROFILES': show-profiles. and *Note `SHOW PROFILE': show-profile. statements (see *Note show-profiles::). The table is empty unless the `profiling' session variable is set to 1. This table describes the `INFORMATION_SCHEMA PROFILING' table. `INFORMATION_SCHEMA' Name *Note `SHOW': 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*: * The *Note `PROFILING': profiling-table. table was added in MySQL 5.1.24 but contains no information unless the *Note `SHOW PROFILE': show-profile. feature is enabled. The *Note `SHOW PROFILE': show-profile. feature is not included in binary distributions by default until MySQL 5.1.28. * `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.  File: manual.info, Node: referential-constraints-table, Next: routines-table, Prev: profiling-table, Up: information-schema 20.15 The `INFORMATION_SCHEMA REFERENTIAL_CONSTRAINTS' Table ============================================================ The *Note `REFERENTIAL_CONSTRAINTS': referential-constraints-table. table provides information about foreign keys. This table describes the *Note `REFERENTIAL_CONSTRAINTS': referential-constraints-table. table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name CONSTRAINT_CATALOG NULL CONSTRAINT_SCHEMA CONSTRAINT_NAME UNIQUE_CONSTRAINT_CATALOG NULL UNIQUE_CONSTRAINT_SCHEMA UNIQUE_CONSTRAINT_NAME MATCH_OPTION UPDATE_RULE DELETE_RULE TABLE_NAME REFERENCED_TABLE_NAME *Notes*: * The *Note `REFERENTIAL_CONSTRAINTS': referential-constraints-table. table was added in MySQL 5.1.10. The `REFERENCED_TABLE_NAME' column was added in MySQL 5.1.16. * `TABLE_NAME' has the same value as `TABLE_NAME' in *Note `INFORMATION_SCHEMA.TABLE_CONSTRAINTS': table-constraints-table. * `CONSTRAINT_SCHEMA' and `CONSTRAINT_NAME' identify the foreign key. * `UNIQUE_CONSTRAINT_SCHEMA', `UNIQUE_CONSTRAINT_NAME', and `REFERENCED_TABLE_NAME' identify the referenced key. (Note: Before MySQL 5.1.16, `UNIQUE_CONSTRAINT_NAME' incorrectly named the referenced table, not the constraint.) * 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'.  File: manual.info, Node: routines-table, Next: schemata-table, Prev: referential-constraints-table, Up: information-schema 20.16 The `INFORMATION_SCHEMA ROUTINES' Table ============================================= The *Note `ROUTINES': routines-table. table provides information about stored routines (both procedures and functions). The *Note `ROUTINES': routines-table. table does not include user-defined functions (UDFs). The column named ``mysql.proc' name' indicates the `mysql.proc' table column that corresponds to the *Note `INFORMATION_SCHEMA.ROUTINES': routines-table. table column, if any. This table describes the `INFORMATION_SCHEMA ROUTINES' table. `INFORMATION_SCHEMA' Name `mysql.proc' Name Remarks `SPECIFIC_NAME' `specific_name' `ROUTINE_CATALOG' `NULL' `ROUTINE_SCHEMA' `db' `ROUTINE_NAME' `name' `ROUTINE_TYPE' `type' `{PROCEDURE|FUNCTION}' `DTD_IDENTIFIER' data type descriptor `ROUTINE_BODY' `SQL' `ROUTINE_DEFINITION' `body or body_utf8' see Notes `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'. * `ROUTINE_DEFINITION' is what is in `mysql.proc.body_utf8' as of MySQL 5.1.21, `mysql.proc.body' before 5.1.21. * `CREATED': The date and time when the routine was created. This is a *Note `TIMESTAMP': datetime. value. * `LAST_ALTERED': The date and time when the routine was last modified. This is a *Note `TIMESTAMP': datetime. 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 *Note server-sql-mode::. * `CHARACTER_SET_CLIENT': The session value of the `character_set_client' system variable when the routine was created. This column was added in MySQL 5.1.21. * `COLLATION_CONNECTION': The session value of the `collation_connection' system variable when the routine was created. This column was added in MySQL 5.1.21. * `DATABASE_COLLATION': The collation of the database with which the routine is associated. This column was added in MySQL 5.1.21.  File: manual.info, Node: schemata-table, Next: schema-privileges-table, Prev: routines-table, Up: information-schema 20.17 The `INFORMATION_SCHEMA SCHEMATA' Table ============================================= A schema is a database, so the *Note `SCHEMATA': schemata-table. table provides information about databases. This table describes the `INFORMATION_SCHEMA SCHEMATA' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `CATALOG_NAME' `NULL' `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']  File: manual.info, Node: schema-privileges-table, Next: statistics-table, Prev: schemata-table, Up: information-schema 20.18 The `INFORMATION_SCHEMA SCHEMA_PRIVILEGES' Table ====================================================== The *Note `SCHEMA_PRIVILEGES': schema-privileges-table. table provides information about schema (database) privileges. This information comes from the `mysql.db' grant table. This table describes the `INFORMATION_SCHEMA SCHEMA_PRIVILEGES' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `GRANTEE' `'USER_NAME'@'HOST_NAME'' value, MySQL extension `TABLE_CATALOG' `NULL', 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.  File: manual.info, Node: statistics-table, Next: tables-table, Prev: schema-privileges-table, Up: information-schema 20.19 The `INFORMATION_SCHEMA STATISTICS' Table =============================================== The *Note `STATISTICS': statistics-table. table provides information about table indexes. This table describes the `INFORMATION_SCHEMA STATISTICS' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `TABLE_CATALOG' `NULL' `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 *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 *Note `SHOW INDEX': 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  File: manual.info, Node: tables-table, Next: table-constraints-table, Prev: statistics-table, Up: information-schema 20.20 The `INFORMATION_SCHEMA TABLES' Table =========================================== The *Note `TABLES': tables-table. table provides information about tables in databases. This table describes the `INFORMATION_SCHEMA TABLES' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `TABLE_CATALOG' `NULL' `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*: * `TABLE_SCHEMA' and `TABLE_NAME' are a single field in a *Note `SHOW': show. display, for example `Table_in_db1'. * `TABLE_TYPE' should be `BASE TABLE' or `VIEW'. Currently, the *Note `TABLES': tables-table. table does not list `TEMPORARY' tables. * For partitioned tables, beginning with MySQL 5.1.9, 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 *Note `InnoDB': innodb-storage-engine. tables, the row count is only a rough estimate used in SQL optimization. (This is also true if the *Note `InnoDB': innodb-storage-engine. table is partitioned.) * Prior to MySQL 5.1.12, MySQL Cluster allocated storage for variable-width columns in 10-page extents of 32 kilobytes each; thus, the `DATA_LENGTH' for such columns was reported in increments of 320 KB. Beginning with MySQL 5.1.12, the `DATA_LENGTH' column reflects the true amount of storage for variable-width columns of *Note `NDB': mysql-cluster. tables. (Bug #18413) For *Note `NDB': mysql-cluster. tables, `DATA_LENGTH' includes data stored in main memory only; the `MAX_DATA_LENGTH' and `DATA_FREE' columns apply to Disk Data. * Beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, for MySQL Cluster Disk Data tables, `MAX_DATA_LENGTH' shows the space allocated for the disk part of a Disk Data table or fragment. (In-memory data resource usage is reported by the `DATA_LENGTH' column.) * Beginning with MySQL 5.1.28, the `DATA_FREE' column shows the free space in bytes for `InnoDB' tables. Beginning with MySQL Cluster NDB 7.0.22 and MySQL Cluster NDB 7.1.11, `DATA_FREE' shows the space allocated on disk for, but not used by, a Disk Data table or fragment on disk. (In-memory data resource usage is reported by the `DATA_LENGTH' column.) * We have nothing for the table's default character set. `TABLE_COLLATION' is close, because collation names begin with a character set name. * Beginning with MySQL 5.1.9, 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']  File: manual.info, Node: table-constraints-table, Next: table-privileges-table, Prev: tables-table, Up: information-schema 20.21 The `INFORMATION_SCHEMA TABLE_CONSTRAINTS' Table ====================================================== The *Note `TABLE_CONSTRAINTS': table-constraints-table. table describes which tables have constraints. This table describes the `INFORMATION_SCHEMA TABLE_CONSTRAINTS' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `CONSTRAINT_CATALOG' `NULL' `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 *Note `SHOW INDEX': 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 *Note `CHAR': char. (not *Note `ENUM': enum.) column. The `CHECK' value is not available until we support `CHECK'.  File: manual.info, Node: table-privileges-table, Next: triggers-table, Prev: table-constraints-table, Up: information-schema 20.22 The `INFORMATION_SCHEMA TABLE_PRIVILEGES' Table ===================================================== The *Note `TABLE_PRIVILEGES': table-privileges-table. table provides information about table privileges. This information comes from the `mysql.tables_priv' grant table. This table describes the `INFORMATION_SCHEMA TABLE_PRIVILEGES' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `GRANTEE' `'USER_NAME'@'HOST_NAME'' value `TABLE_CATALOG' `NULL' `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 ...  File: manual.info, Node: triggers-table, Next: user-privileges-table, Prev: table-privileges-table, Up: information-schema 20.23 The `INFORMATION_SCHEMA TRIGGERS' Table ============================================= The *Note `TRIGGERS': triggers-table. table provides information about triggers. You must have the `TRIGGER' privilege to access this table (prior to MySQL 5.1.23, you must have the `SUPER' privilege). You can see information only for databases and tables for which you have the `TRIGGER' privilege, or (prior to MySQL 5.1.23) if you have the `SUPER' privilege). This table describes the `INFORMATION_SCHEMA TRIGGERS' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `TRIGGER_CATALOG' `NULL' `TRIGGER_SCHEMA' `TRIGGER_NAME' `Trigger' `EVENT_MANIPULATION' `Event' `EVENT_OBJECT_CATALOG' `NULL' `EVENT_OBJECT_SCHEMA' `EVENT_OBJECT_TABLE' `Table' `ACTION_ORDER' `0' `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 `*Note `SHOW': show. Name' column refer to the *Note `SHOW TRIGGERS': show-triggers. statement, not *Note `SHOW CREATE TRIGGER': show-create-trigger. See *Note 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 *Note 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 all similar triggers on the same table. Currently, this value is always `0', because it is not possible to have more than one trigger with the same `EVENT_MANIPULATION' and `ACTION_TIMING' on the same table. * `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''. * `SQL_MODE': The SQL mode in effect when the trigger was created, and under which the trigger executes. For the permitted values, see *Note server-sql-mode::. * `DEFINER': The account of the user who created the trigger, in `'USER_NAME'@'HOST_NAME'' format. This column was added in MySQL 5.1.2. * `CHARACTER_SET_CLIENT': The session value of the `character_set_client' system variable when the trigger was created. This column was added in MySQL 5.1.21. * `COLLATION_CONNECTION': The session value of the `collation_connection' system variable when the trigger was created. This column was added in MySQL 5.1.21. * `DATABASE_COLLATION': The collation of the database with which the trigger is associated. This column was added in MySQL 5.1.21. * The following columns currently always contain `NULL': `TRIGGER_CATALOG', `EVENT_OBJECT_CATALOG', `ACTION_CONDITION', `ACTION_REFERENCE_OLD_TABLE', `ACTION_REFERENCE_NEW_TABLE', and `CREATED'. Example, using the `ins_sum' trigger defined in *Note 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: 0 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: NULL SQL_MODE: DEFINER: me@localhost CHARACTER_SET_CLIENT: utf8 COLLATION_CONNECTION: utf8_general_ci DATABASE_COLLATION: latin1_swedish_ci  File: manual.info, Node: user-privileges-table, Next: views-table, Prev: triggers-table, Up: information-schema 20.24 The `INFORMATION_SCHEMA USER_PRIVILEGES' Table ==================================================== The *Note `USER_PRIVILEGES': user-privileges-table. table provides information about global privileges. This information comes from the `mysql.user' grant table. This table describes the `INFORMATION_SCHEMA USER_PRIVILEGES' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `GRANTEE' `'USER_NAME'@'HOST_NAME'' value, MySQL extension `TABLE_CATALOG' `NULL', 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.  File: manual.info, Node: views-table, Next: mysql-cluster-i_s-tables, Prev: user-privileges-table, Up: information-schema 20.25 The `INFORMATION_SCHEMA VIEWS' Table ========================================== The *Note `VIEWS': views-table. table provides information about views in databases. You must have the `SHOW VIEW' privilege to access this table. This table describes the `INFORMATION_SCHEMA VIEWS' table. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `TABLE_CATALOG' `NULL' `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 *Note `SHOW CREATE VIEW': show-create-view. produces. Skip the words before *Note `SELECT': 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 *Note `CREATE VIEW': create-view. time. The flag is set to `YES' (true) if *Note `UPDATE': update. and *Note `DELETE': delete. (and similar operations) are legal for the view. Otherwise, the flag is set to `NO' (false). The `IS_UPDATABLE' column in the *Note `VIEWS': views-table. table displays the status of this flag. It means that the server always knows whether a view is updatable. If the view is not updatable, statements such *Note `UPDATE': update, *Note `DELETE': delete, and *Note `INSERT': 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 *Note create-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. This column was added in MySQL 5.1.21. * `COLLATION_CONNECTION': The session value of the `collation_connection' system variable when the view was created. This column was added in MySQL 5.1.21. 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 *Note `SELECT': select. are stripped from the definition by the server.  File: manual.info, Node: mysql-cluster-i_s-tables, Next: extended-show, Prev: views-table, Up: information-schema 20.26 `INFORMATION_SCHEMA' Tables for MySQL Cluster =================================================== * Menu: * files-table:: The `INFORMATION_SCHEMA FILES' Table * ndb-transid-mysql-connection-map-table:: The `INFORMATION_SCHEMA ndb_transid_mysql_connection_map' Table The following sections provide information about `INFORMATION_SCHEMA' tables which are specific to MySQL Cluster. The *Note `FILES': files-table. table was added in MySQL Server 5.1.6 as part of MySQL Cluster data-on-disk support (it is available in standard MySQL 5.5 but is not used there). The *Note `ndb_transid_mysql_connection_map': ndb-transid-mysql-connection-map-table. table was added as part of additions made to MySQL Cluster's *Note `ndbinfo': mysql-cluster-ndbinfo. information database in MySQL Cluster NDB 7.1.17; it is implemented as an `INFORMATION_SCHEMA' plugin available only in MySQL Cluster binaries or source, and does not exist in MySQL Server 5.1. Additional statistical and other data about MySQL Cluster transactions, operations, threads, blocks, and other aspects of performance can be obtained from the tables in the *Note `ndbinfo': mysql-cluster-ndbinfo. database. Information about these tables, see *Note mysql-cluster-ndbinfo::.  File: manual.info, Node: files-table, Next: ndb-transid-mysql-connection-map-table, Prev: mysql-cluster-i_s-tables, Up: mysql-cluster-i_s-tables 20.26.1 The `INFORMATION_SCHEMA FILES' Table -------------------------------------------- The *Note `FILES': files-table. table provides information about the files in which MySQL *Note `NDB': mysql-cluster. Disk Data tables are stored. *Note*: This table provides information about Disk Data _files_ only; you cannot use it for determining disk space allocation or availability for individual `NDB' tables. However, beginning with MySQL Cluster NDB 6.3.27 and MySQL Cluster NDB 7.0.8, it is possible to see how much space is allocated for each *Note `NDB': mysql-cluster. table having data stored on disk, as well as how much remains available for storage of data on disk for that table, using *Note `ndb_desc': mysql-cluster-programs-ndb-desc. For more information, see *Note mysql-cluster-programs-ndb-desc::. This table describes the `INFORMATION_SCHEMA FILES' table. The table lists `INFORMATION_SCHEMA' names along with the corresponding *Note `SHOW': show. names (if applicable), and remarks. `INFORMATION_SCHEMA' Name *Note `SHOW': 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 *Notes*: * `FILE_ID' column values are auto-generated. * `FILE_NAME' is the name of an `UNDO' log file created by *Note `CREATE LOGFILE GROUP': create-logfile-group. or *Note `ALTER LOGFILE GROUP': alter-logfile-group, or of a data file created by *Note `CREATE TABLESPACE': create-tablespace. or *Note `ALTER TABLESPACE': alter-tablespace. * `FILE_TYPE' is one of the values `UNDOFILE' or `DATAFILE'. Beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.32, MySQL Cluster NDB 7.0.13, and MySQL Cluster NDB 7.1.2, this column can also have the value `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 a MySQL Cluster Disk Data log file or data file, the value of the `ENGINE' column is always *Note `NDB': mysql-cluster. or *Note `NDBCLUSTER': mysql-cluster. * For a MySQL 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 *Note `CREATE TABLESPACE': create-tablespace. statement. See *Note 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 *Note `CREATE LOGFILE GROUP': create-logfile-group, *Note `ALTER LOGFILE GROUP': alter-logfile-group, *Note `CREATE TABLESPACE': create-tablespace, or *Note `ALTER TABLESPACE': alter-tablespace. statement used to create the file. For MySQL 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 *Note `NDB': mysql-cluster. storage engine. Where no value is provided by the operating system, these columns display `0000-00-00 00:00:00'. * For MySQL Cluster Disk Data files, the value of the `RECOVER_TIME' and `TRANSACTION_COUNTER' columns is always `0'. * For MySQL 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 MySQL Cluster Disk Data files, the value of the `STATUS' column is always `NORMAL'. * For MySQL 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 a MySQL Cluster with four data nodes: CREATE LOGFILE GROUP mygroup ADD UNDOFILE 'new_undo.dat' INITIAL_SIZE 2G ENGINE NDB; After running the *Note `CREATE LOGFILE GROUP': create-logfile-group. statement successfully, you should see a result similar to the one shown here for this query against the *Note `FILES': files-table. 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 *Note `FILES': files-table. table is a nonstandard table. It was added in MySQL 5.1.6. * Beginning with MySQL 5.1.14, an additional row is present in the *Note `FILES': files-table. 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 *Note `NDBCLUSTER': mysql-cluster. 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 MySQL 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 *Note `FILES': files-table. 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 *Note `FILES': files-table. 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 a MySQL 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) * Beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.32, MySQL Cluster NDB 7.0.13, and MySQL Cluster NDB 7.1.2, an additional row is present in the *Note `FILES': files-table. table for any 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 *Note `NDBCLUSTER': mysql-cluster. * There are no *Note `SHOW': show. statements associated with the *Note `FILES': files-table. table. * For additional information, and examples of creating and dropping MySQL Cluster Disk Data objects, see *Note mysql-cluster-disk-data::.  File: manual.info, Node: ndb-transid-mysql-connection-map-table, Prev: files-table, Up: mysql-cluster-i_s-tables 20.26.2 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 a MySQL Cluster as API nodes. This information is used when populating the *Note `server_operations': mysql-cluster-ndbinfo-server-operations. and *Note `server_transactions': mysql-cluster-ndbinfo-server-transactions. tables of the *Note `ndbinfo': mysql-cluster-ndbinfo. MySQL Cluster information database. This table describes the `INFORMATION_SCHEMA ndb_transid_mysql_connection_map' table. The table lists `INFORMATION_SCHEMA' names along with corresponding *Note `SHOW': show. names (if applicable), and remarks. `INFORMATION_SCHEMA' Name *Note `SHOW': show. Remarks Name `mysql_connection_id' MySQL Server connection ID `node_id' Transaction coordinator node ID `ndb_transid' *Note `NDB': mysql-cluster. transaction ID The `mysql_connection_id' is the same as the connection or session ID shown in the output of *Note `SHOW PROCESSLIST': show-processlist. There are no `SHOW' statements associated with this table. This is a nonstandard table, added in MySQL Cluster NDB 7.1.17. It is implemented as an `INFORMATION_SCHEMA' plugin; you can verify that it is supported by checking the output of *Note `SHOW PLUGINS': 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 | | mysql_old_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 *Note `SHOW PLUGINS': 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 that wass supplied with the MySQL Cluster distribution, or one that was built from the MySQL Cluster sources with *Note `NDB': mysql-cluster. storage engine support enabled. It is not available in the standard MySQL 5.1 Server.  File: manual.info, Node: extended-show, Prev: mysql-cluster-i_s-tables, Up: information-schema 20.27 Extensions to `SHOW' Statements ===================================== Some extensions to *Note `SHOW': show. statements accompany the implementation of `INFORMATION_SCHEMA': * *Note `SHOW': show. can be used to get information about the structure of `INFORMATION_SCHEMA' itself. * Several *Note `SHOW': 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 *Note `SHOW DATABASES': show-databases. Similarly, *Note `SHOW TABLES': 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 | +---------------------------------------+ 27 rows in set (0.00 sec) *Note `SHOW COLUMNS': show-columns. and *Note `DESCRIBE': describe. can display information about the columns in individual `INFORMATION_SCHEMA' tables. *Note `SHOW': 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 *Note `SHOW': show. statement. For example, the *Note `SHOW CHARACTER SET': 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 *Note `SHOW CHARACTER SET': 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 multi-byte 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 | +---------+---------------------------+---------------------+--------+  File: manual.info, Node: connectors-apis, Next: extending-mysql, Prev: information-schema, Up: Top 21 Connectors and APIs ********************** * Menu: * connector-odbc:: MySQL Connector/ODBC * connector-net:: MySQL Connector/Net * connector-j:: MySQL Connector/J * connector-cpp:: MySQL Connector/C++ * connector-c:: MySQL Connector/C * connector-python:: MySQL Connector/Python * libmysqld:: libmysqld, the Embedded MySQL Server Library * c-api:: MySQL C API * apis-php:: MySQL PHP API * apis-perl:: MySQL Perl API * apis-python:: MySQL Python API * apis-ruby:: MySQL Ruby APIs * apis-tcl:: MySQL Tcl API * apis-eiffel:: MySQL Eiffel Wrapper 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. *Note*: Connector version numbers do not correlate with MySQL Server version numbers. See *Note connectors-apis-versions::. * MySQL Connectors * Oracle develops a number of connectors: * *Note Connector/ODBC: connector-odbc. provides driver support for connecting to MySQL using the Open Database Connectivity (ODBC) API. Support is available for ODBC connectivity from Windows, Unix, and Mac OS X platforms. * *Note Connector/Net: connector-net. 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. The MySQL *Note Visual Studio Plugin: connector-net-visual-studio. works with Connector/Net and Visual Studio 2005. The plugin is a MySQL DDEX Provider, which means that you can use the schema and data manipulation tools available in Visual Studio to create and edit objects within a MySQL database. * *Note Connector/J: connector-j. provides driver support for connecting to MySQL from Java applications using the standard Java Database Connectivity (JDBC) API. * *Note Connector/Python: connector-python. 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. * *Note Connector/C++: connector-cpp. enables C++ applications to connect to MySQL. * *Note Connector/C: connector-c. is a standalone replacement for the MySQL Client Library (`libmysqlclient'), to be used for C applications. * The MySQL C API * For direct access to using MySQL natively within a C application, there are two methods: * The *Note C API: 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 MySQL 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 MySQL Connector/C distributions. See also *Note 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 *Note C API: c-api. is where to start. A number of programmer's utilities are available to help with the process; see *Note 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. *Note connectors-apis-summary:: lists many of the libraries and interfaces available for MySQL. *Note connectors-apis-versions:: shows which MySQL Server versions each connector supports. *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 *Note c-api::. C Connector/C Replacement See *Note connector-c::. for `libmysqlclient' C++ Connector/C++ `libmysqlclient'See *Note connector-cpp::. MySQL++ `libmysqlclient'See MySQL++ Web site (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 *Note 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/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 *Note connector-j::. Driver Kaya MyDB `libmysqlclient'See MyDB (http://kayalang.org/library/latest/MyDB). Lua LuaSQL `libmysqlclient'See LuaSQL (http://www.keplerproject.org/luasql/). .NET/MonoConnector/Net Native See *Note connector-net::. Driver 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 *Note connector-odbc::. Perl `DBI'/`DBD::mysql' `libmysqlclient'See *Note 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 See section interface (deprecated) "apis-php-mysql" in the online manual. `mysqli', `ext/mysqli' `libmysqlclient'See See section interface "apis-php-mysqli" in the online manual. `PDO_MYSQL' `libmysqlclient'See See section "apis-php-ref.pdo-mysql" in the online manual. PDO mysqlnd Native Driver Python Connector/Python Native See *Note connector-python::. Driver MySQLdb `libmysqlclient'See *Note apis-python::. Ruby MySQL/Ruby `libmysqlclient'Uses `libmysqlclient'. See *Note apis-ruby-mysqlruby::. Ruby/MySQL Native See *Note Driver apis-ruby-rubymysql::. Scheme `Myscsh' `libmysqlclient'See `Myscsh' (http://www-pu.informatik.uni-tuebingen.de/users/knauel/myscsh/). SPL `sql_mysql' `libmysqlclient'See `sql_mysql' for SPL (http://www.clifford.at/spl/spldoc/sql_mysql.html). Tcl MySQLtcl `libmysqlclient'See *Note apis-tcl::. *MySQL Connector Versions and MySQL Server Versions* Connector Connector version MySQL Server version Connector/C 6.1.0 GA 5.6, 5.5, 5.1, 5.0, 4.1 Connector/C++ 1.0.5 GA 5.6, 5.5, 5.1 Connector/J 5.1.8 5.6, 5.5, 5.1, 5.0, 4.1 Connector/Net 6.5 5.6, 5.5, 5.1, 5.0 Connector/Net 6.4 5.6, 5.5, 5.1, 5.0 Connector/Net 6.3 5.6, 5.5, 5.1, 5.0 Connector/Net 6.2 (No longer 5.6, 5.5, 5.1, 5.0 supported) Connector/Net 6.1 (No longer 5.6, 5.5, 5.1, 5.0 supported) Connector/Net 6.0 (No longer 5.6, 5.5, 5.1, 5.0 supported) Connector/Net 5.2 (No longer 5.6, 5.5, 5.1, 5.0 supported) Connector/Net 1.0 (No longer 5.0, 4.0 supported) Connector/ODBC 5.1 5.6, 5.5, 5.1, 5.0, 4.1.1+ Connector/ODBC 3.51 (Unicode not 5.6, 5.5, 5.1, supported) 5.0, 4.1  File: manual.info, Node: connector-odbc, Next: connector-net, Prev: connectors-apis, Up: connectors-apis 21.1 MySQL Connector/ODBC ========================= * Menu: * connector-odbc-versions:: Connector/ODBC Versions * connector-odbc-introduction:: Connector/ODBC Introduction * connector-odbc-installation:: Connector/ODBC Installation * connector-odbc-configuration:: Configuring Connector/ODBC * connector-odbc-examples:: Connector/ODBC Examples * connector-odbc-reference:: Connector/ODBC Reference * connector-odbc-usagenotes:: Connector/ODBC Notes and Tips * connector-odbc-support:: Connector/ODBC Support The MySQL Connector/ODBC is the name for the family of MySQL ODBC drivers (previously called MyODBC drivers) that provide access to a MySQL database using the industry standard Open Database Connectivity (ODBC) API. This reference covers Connector/ODBC 5.2, which includes the functionality of the Unicode driver and the ANSI driver, which formerly were split between Connector/ODBC 5.1 and Connector/ODBC 3.51. MySQL Connector/ODBC provides both driver-manager based and native interfaces to the MySQL database, with full support for MySQL functionality, including stored procedures, transactions (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction) and, with Connector/ODBC 5.1 and higher, full Unicode compliance. For more information on the ODBC API standard and how to use it, refer to `http://support.microsoft.com/kb/110093'. The application development section of the ODBC API reference assumes a good working knowledge of C, general DBMS, and a familiarity with MySQL. For more information about MySQL functionality and its syntax, refer to `http://dev.mysql.com/doc/'. Typically, you need to install Connector/ODBC only on Windows machines. For Unix and Mac OS X, you can use the native MySQL network or named pipes to communicate with your MySQL database. You may need Connector/ODBC for Unix or Mac OS X if you have an application that requires an ODBC interface to communicate with the database. Applications that require ODBC to communicate with MySQL include ColdFusion, Microsoft Office, and Filemaker Pro. For release notes detailing the changes in each release of Connector/ODBC, see MySQL Connector/ODBC Release Notes (http://dev.mysql.com/doc/relnotes/connector-odbc/en/). * Key connector/ODBC topics include: * * Installing Connector/ODBC: *Note connector-odbc-installation::. * The configuration options: *Note connector-odbc-configuration-connection-parameters::. * An example that connects to a MySQL database from a Windows host: *Note connector-odbc-examples-walkthrough::. * An example that uses Microsoft Access as an interface to a MySQL database: *Note connector-odbc-examples-tools-with-access::. * General tips and notes, including how to obtain the last auto-increment ID: *Note connector-odbc-usagenotes-functionality::. * Application-specific usage tips and notes: *Note connector-odbc-usagenotes-apptips::. * A FAQ (Frequently Asked Questions) list: *Note connector-odbc-errors::. * Additional Connector/ODBC support options: *Note connector-odbc-support::.  File: manual.info, Node: connector-odbc-versions, Next: connector-odbc-introduction, Prev: connector-odbc, Up: connector-odbc 21.1.1 Connector/ODBC Versions ------------------------------ These are the versions of Connector/ODBC that are currently available: * Connector/ODBC 5.2, currently in GA status, upgrades the ANSI driver of Connector/ODBC 3.51 to the 5.x code base. It also includes new features, such as enabling server-side prepared statements by default. At installation time, you can choose the Unicode driver for the broadest compatibility with data sources using various character sets, or the ANSI driver for optimal performance with a more limited range of character sets. It works with MySQL versions 4.1.1 and higher. * Connector/ODBC 5.1, now superseded by 5.2, is a partial rewrite of the of the 3.51 code base, and is designed to work with MySQL versions 4.1.1 and newer. Connector/ODBC 5.1 also includes the following changes and improvements over the 3.51 release: * Improved support on Windows 64-bit platforms. * Full Unicode support at the driver level. This includes support for the `SQL_WCHAR' data type, and support for Unicode login, password and DSN configurations. For more information, see Microsoft Knowledgebase Article #716246 (http://msdn2.microsoft.com/en-us/library/ms716246.aspx). * Support for the `SQL_NUMERIC_STRUCT' data type, which provides easier access to the precise definition of numeric values. For more information, see Microsoft Knowledgebase Article #714556 (http://msdn2.microsoft.com/en-us/library/ms714556.aspx) * Native Windows setup library. This replaces the Qt library based interface for configuring DSN information within the ODBC Data Sources application. * Support for the ODBC descriptor, which improves the handling and metadata of columns and parameter data. For more information, see Microsoft Knowledgebase Article #716339 (http://msdn2.microsoft.com/en-us/library/ms716339.aspx). * Connector/ODBC 3.51 is the current release of the 32-bit ODBC driver, also known as the MySQL ODBC 3.51 driver. Connector/ODBC 3.51 has support for ODBC 3.5x specification level 1 (complete core API + level 2 features) to continue to provide all functionality of ODBC for accessing MySQL. With MySQL Connector/ODBC 5.2 now offering both ANSI and Unicode drivers, you should expect to upgrade relatively soon. The manual for versions of Connector/ODBC older than 5.2 can be located in the corresponding binary or source distribution. Please note that versions of Connector/ODBC earlier than the 3.51 revision were not fully compliant with the ODBC specification. *Note*: From this section onward, the primary focus of this guide is the Connector/ODBC 5.2 driver. *Note*: Version numbers for MySQL products are formatted as X.X.X. However, Windows tools (Control Panel, properties display) may show the version numbers as XX.XX.XX. For example, the official MySQL formatted version number 5.0.9 may be displayed by Windows tools as 5.00.09. The two versions are the same; only the number display format is different.  File: manual.info, Node: connector-odbc-introduction, Next: connector-odbc-installation, Prev: connector-odbc-versions, Up: connector-odbc 21.1.2 Connector/ODBC Introduction ---------------------------------- * Menu: * connector-odbc-general-information:: General Information About ODBC and Connector/ODBC ODBC (Open Database Connectivity) provides a way for client programs to access a wide range of databases or data sources. ODBC is a standardized API that enables connections to SQL database servers. It was developed according to the specifications of the SQL Access Group and defines a set of function calls, error codes, and data types that can be used to develop database-independent applications. ODBC usually is used when database independence or simultaneous access to different data sources is required. For more information about ODBC, refer to `http://support.microsoft.com/kb/110093'.  File: manual.info, Node: connector-odbc-general-information, Prev: connector-odbc-introduction, Up: connector-odbc-introduction 21.1.2.1 General Information About ODBC and Connector/ODBC .......................................................... * Menu: * connector-odbc-architecture:: Connector/ODBC Architecture * connector-odbc-driver-manager:: ODBC Driver Managers Open Database Connectivity (ODBC) is a widely accepted application-programming interface (API) for database access. It is based on the Call-Level Interface (CLI) specifications from X/Open and ISO/IEC for database APIs and uses Structured Query Language (SQL) as its database access language. A survey of ODBC functions supported by Connector/ODBC is given at *Note connector-odbc-reference-api::. For general information about ODBC, see `http://support.microsoft.com/kb/110093'.  File: manual.info, Node: connector-odbc-architecture, Next: connector-odbc-driver-manager, Prev: connector-odbc-general-information, Up: connector-odbc-general-information 21.1.2.2 Connector/ODBC Architecture .................................... The Connector/ODBC architecture is based on five components, as shown in the following diagram: Connector/ODBC Architecture * *Application:* The Application uses the ODBC API to access the data from the MySQL server. The ODBC API in turn communicates with the Driver Manager. The Application communicates with the Driver Manager using the standard ODBC calls. The Application does not care where the data is stored, how it is stored, or even how the system is configured to access the data. It needs to know only the Data Source Name (DSN). A number of tasks are common to all applications, no matter how they use ODBC. These tasks are: * Selecting the MySQL server and connecting to it. * Submitting SQL statements for execution. * Retrieving results (if any). * Processing errors. * Committing (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_commit) or rolling back (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_rollback) the transaction (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction) enclosing the SQL statement. * Disconnecting from the MySQL server. Because most data access work is done with SQL, the primary tasks for applications that use ODBC are submitting SQL statements and retrieving any results generated by those statements. * *Driver manager:* The Driver Manager is a library that manages communication between application and driver or drivers. It performs the following tasks: * Resolves Data Source Names (DSN). The DSN is a configuration string that identifies a given database driver, database, database host and optionally authentication information that enables an ODBC application to connect to a database using a standardized reference. Because the database connectivity information is identified by the DSN, any ODBC-compliant application can connect to the data source using the same DSN reference. This eliminates the need to separately configure each application that needs access to a given database; instead you instruct the application to use a pre-configured DSN. * Loading and unloading of the driver required to access a specific database as defined within the DSN. For example, if you have configured a DSN that connects to a MySQL database then the driver manager will load the Connector/ODBC driver to enable the ODBC API to communicate with the MySQL host. * Processes ODBC function calls or passes them to the driver for processing. * *Connector/ODBC Driver:* The Connector/ODBC driver is a library that implements the functions supported by the ODBC API. It processes ODBC function calls, submits SQL requests to MySQL server, and returns results back to the application. If necessary, the driver modifies an application's request so that the request conforms to syntax supported by MySQL. * *DSN Configuration:* The ODBC configuration file stores the driver and database information required to connect to the server. It is used by the Driver Manager to determine which driver to be loaded according to the definition in the DSN. The driver uses this to read connection parameters based on the DSN specified. For more information, *Note connector-odbc-configuration::. * *MySQL Server:* The MySQL database where the information is stored. The database is used as the source of the data (during queries) and the destination for data (during inserts and updates).  File: manual.info, Node: connector-odbc-driver-manager, Prev: connector-odbc-architecture, Up: connector-odbc-general-information 21.1.2.3 ODBC Driver Managers ............................. An ODBC Driver Manager is a library that manages communication between the ODBC-aware application and any drivers. Its main functionality includes: * Resolving Data Source Names (DSN). * Driver loading and unloading. * Processing ODBC function calls or passing them to the driver. Most ODBC Driver Manager implementations also include an administration application that makes the configuration of DSN and drivers easier. Examples and information on ODBC Driver Managers for different operating systems are listed below: * Windows: Microsoft Windows ODBC Driver Manager (`odbc32.dll'). It is included in the Windows operating system. See `http://support.microsoft.com/kb/110093' for more information. * Mac OS X: ODBC Administrator is a GUI application for Mac OS X. It provides a simplified configuration mechanism for the iODBC Driver Manager. You can configure DSN and driver information either through ODBC Administrator or through the iODBC configuration files. This also means that you can test ODBC Administrator configurations using the `iodbctest' command. See `http://support.apple.com/kb/DL895' for more information. * Unix: * `unixODBC' Driver Manager for Unix (`libodbc.so'). See `http://www.unixodbc.org', for more information. * `iODBC' Driver Manager for Unix (`libiodbc.so'). See `http://www.iodbc.org', for more information.  File: manual.info, Node: connector-odbc-installation, Next: connector-odbc-configuration, Prev: connector-odbc-introduction, Up: connector-odbc 21.1.3 Connector/ODBC Installation ---------------------------------- * Menu: * connector-odbc-installation-binary-windows:: Installing Connector/ODBC on Windows * connector-odbc-installation-binary-unix:: Installing Connector/ODBC on Unix * connector-odbc-installation-binary-macosx:: Installing Connector/ODBC on Mac OS X * connector-odbc-installation-source-windows:: Building Connector/ODBC from a Source Distribution on Windows * connector-odbc-installation-source-unix:: Building Connector/ODBC from a Source Distribution on Unix * connector-odbc-installation-source-unix-macosx:: Building Connector/ODBC from a Source Distribution on Mac OS X * connector-odbc-installation-source-development:: Installing Connector/ODBC from the Development Source Tree This section explains where to download Connector/ODBC, and how to run the installer, copy the files manually, or build from source. * Where to Get Connector/ODBC * You can get a copy of the latest version of Connector/ODBC binaries and sources from our Web site at `http://dev.mysql.com/downloads/connector/odbc/'. For more information about Connector/ODBC, visit http://www.mysql.com/products/myodbc/. For more information about licensing, visit http://www.mysql.com/company/legal/licensing/. * Choosing Unicode or ANSI Driver * Connector/ODBC offers the flexibility to handle data using any character set through its *Unicode-enabled* driver, or the maximum raw speed for a more limited range of character sets through its *ANSI* driver. Some users postponed their upgrade to Connector/ODBC 5.1, remaining with the older 3.51 version to keep this performance edge. As of Connector/ODBC 5.2, both kinds of drivers are available based on the 5.x code base: you can choose either a Unicode-enabled driver or an ANSI driver on the download page. The Unicode-enabled driver, recommended for most users, has no special qualifier in the download filename. The ANSI driver includes `-ansi-' in the download filename. *Note*: You can install either the Unicode driver on a Windows system, or the ANSI driver, or both. The drivers are distinguished in the list of installed software and in the names of libraries and directories by a `w' (for `wide characters') for the Unicode driver, and `a' in the ANSI driver. * Choosing Binary or Source Installation Method * You can install the Connector/ODBC drivers using two different methods: * The *binary installation* is the easiest and most straightforward method of installation. You receive all the necessary libraries and other files pre-built, with an installer program or batch script to perform all necessary copying and configuration. * The *source installation* method is intended for platforms where a binary installation package is not available, or in situations where you want to customize or modify the installation process or Connector/ODBC drivers before installation. If a binary distribution is not available for a particular platform, and you build the driver from the original source code, you can contribute the binaries you create to MySQL by sending a mail message to , so that it becomes available for other users. * Supported Platforms * Connector/ODBC can be used on all major platforms supported by MySQL. You can install it on: * Windows XP, 2003, Vista and 7. * All Unix-like Operating Systems, including: Amiga, BSDI, DEC, FreeBSD, HP-UX 10/11, Linux, NetBSD, OpenBSD, OS/2, SGI Irix, Solaris, SunOS, SCO OpenServer, SCO UnixWare, Tru64 Unix. * Mac OS X and Mac OS X Server. *Note*: On all non-Windows platforms except Mac OS X, the driver is built against `unixODBC' and is expecting a 2-byte `SQLWCHAR', not 4 bytes as `iODBC' is using. For this reason, the binaries are *only* compatible with `unixODBC'; recompile the driver against `iODBC' to use them together. For further information, see *Note connector-odbc-driver-manager::. For further instructions, consult the documentation corresponding to the platform where you are installing and whether you are running a binary installer or building from source: Connector/ODBC installation instructions for each platform, for both the binary installer or building from source. Platform Binary Installer Build from Source Windows *Note Installation *Note Build Instructions: Instructions: connector-odbc-installation-binary-windows.connector-odbc-installation-source-windows. Unix/Linux *Note Installation *Note Build Instructions: Instructions: connector-odbc-installation-binary-unix.connector-odbc-installation-source-unix. Mac OS X *Note Installation Instructions: connector-odbc-installation-binary-macosx.  File: manual.info, Node: connector-odbc-installation-binary-windows, Next: connector-odbc-installation-binary-unix, Prev: connector-odbc-installation, Up: connector-odbc-installation 21.1.3.1 Installing Connector/ODBC on Windows ............................................. * Menu: * connector-odbc-installation-binary-windows-installer:: Installing the Windows Connector/ODBC Driver Using an Installer * connector-odbc-installation-binary-windows-dll:: Installing the Windows Connector/ODBC Driver Using the Zipped DLL Package Before installing the Connector/ODBC drivers on Windows, ensure that your Microsoft Data Access Components (MDAC) are up to date. You can obtain the latest version from the Microsoft Data Access and Storage (http://support.microsoft.com/kb/110093) Web site. There are different distribution types to use when installing for Windows. The software that is installed is identical in each case, only the installation method is different. * The *zipped installer* consists of a zipped package containing a standalone installation application. To install from this package, unzip the installer, and then run the installation application. The *MSI installer* is an installation file that can be used with the installer included in Windows 2000, Windows XP and Windows Server 2003. See *Note connector-odbc-installation-binary-windows-installer:: for the steps to complete the installation with either of these installers. * The *zipped DLL* package contains DLL files that must be manually installed. See *Note connector-odbc-installation-binary-windows-dll:: for the steps to complete this type of installation. *Note*: An OLEDB/ODBC driver for Windows 64-bit is available from Microsoft Downloads (http://www.microsoft.com/downloads/details.aspx?FamilyID=000364db-5e8b-44a8-b9be-ca44d18b059b&displaylang=en).  File: manual.info, Node: connector-odbc-installation-binary-windows-installer, Next: connector-odbc-installation-binary-windows-dll, Prev: connector-odbc-installation-binary-windows, Up: connector-odbc-installation-binary-windows 21.1.3.2 Installing the Windows Connector/ODBC Driver Using an Installer ........................................................................ The zipped or MSI installer packages offer a very simple method for installing the Connector/ODBC drivers. If you have downloaded the zipped installer, extract the installer application. The basic installation process is identical for both installers. Follow these steps to complete the installation: 1. Double-click the standalone installer that you extracted, or the MSI file you downloaded. 2. The MySQL Connector/ODBC Setup Wizard starts. Click the `Next' button to begin the installation process. Connector/ODBC Windows Installer - Welcome 3. Choose the installation type. The `Typical' installation provides the standard files needed to connect to a MySQL database using ODBC. The `Complete' option installs all the available files, including debug and utility components. Oracle recommends choosing one of these two options to complete the installation. If you choose one of these methods, click `Next', then proceed to step 5. You can also choose a `Custom' installation, where you select the individual components to install. If you choose this method, click `Next', then proceed to step 4. Connector/ODBC Windows Installer - Choosing a Setup type welcome 4. If you have chosen a custom installation, use the pop-ups to select which components to install, then click `Next' to install the necessary files. Connector/ODBC Windows Installer - Custom Installation welcome 5. Once the files are copied to their final locations, the installation is complete. Click `Finish' to exit the installer. Connector/ODBC Windows Installer - Completion welcome Now that the installation is complete, configure your ODBC connections using *Note connector-odbc-configuration::.  File: manual.info, Node: connector-odbc-installation-binary-windows-dll, Prev: connector-odbc-installation-binary-windows-installer, Up: connector-odbc-installation-binary-windows 21.1.3.3 Installing the Windows Connector/ODBC Driver Using the Zipped DLL Package .................................................................................. If you have downloaded the zipped DLL package: 1. Unzip the installation files. 2. Run the included batch file to perform an installation to the default locations. 3. Alternatively, install the individual files required for Connector/ODBC operation manually. *Note*: The following instructions only work for 32-bit Windows systems. If you have a 64-bit Windows system, use the MSI installer, which installs both the 32-bit and 64-bit drivers to the correct locations. To install using the *batch file*: 1. Unzip the Connector/ODBC zipped DLL package. 2. Open a command prompt. 3. Change to the directory created when you unzipped the Connector/ODBC zipped DLL package. 4. Run `Install.bat': C:\> Install.bat This copies the necessary files into the default location, and then registers the Connector/ODBC driver with the Windows ODBC manager. *Note*: Changing or adding a new DSN (data source name) may be accomplished using either the GUI, or from the command-line using `myodbc-installer.exe'. Although Oracle recommends installing these files in the standard location, you can also copy the files by hand to an alternative location - for example, to run or test different versions of the Connector/ODBC driver on the same machine. To *copy the files* to a location of your choice, use the following steps: 1. Unzip the Connector/ODBC zipped DLL package. 2. Open a command prompt. 3. Change to the directory created when you unzipped the Connector/ODBC zipped DLL package. 4. Copy the library files to a suitable directory. The default location is the default Windows system directory `\Windows\System32': C:\> copy lib\myodbc5S.dll \Windows\System32 C:\> copy lib\myodbc5S.lib \Windows\System32 If installing the Unicode-enabled driver: C:\> copy lib\myodbc5w.dll \Windows\System32 C:\> copy lib\myodbc5w.lib \Windows\System32 If installing the ANSI driver: C:\> copy lib\myodbc5a.dll \Windows\System32 C:\> copy lib\myodbc5a.lib \Windows\System32 5. Copy the Connector/ODBC tools. These must be placed in a directory that is in the system `%PATH%'. The default is to install these into the Windows system directory `\Windows\System32': C:\> copy bin\myodbc-installer.exe \Windows\System32 6. Optionally, copy the help files. For these files to be accessible through the help system, they must be installed in the Windows system directory: C:\> copy doc\*.hlp \Windows\System32 7. Finally, register the Connector/ODBC driver with the ODBC manager: For Unicode-enabled driver: C:\> myodbc-installer -a -d -t"MySQL ODBC 5.2 Driver;\ DRIVER=myodbc5w.dll;SETUP=myodbc5S.dll" For ANSI driver: C:\> myodbc-installer -a -d -t"MySQL ODBC 5.2 Driver;\ DRIVER=myodbc5a.dll;SETUP=myodbc5S.dll" If you installed these files into a non-default location, change the references to the DLL files and command location in the above statement  File: manual.info, Node: connector-odbc-installation-binary-unix, Next: connector-odbc-installation-binary-macosx, Prev: connector-odbc-installation-binary-windows, Up: connector-odbc-installation 21.1.3.4 Installing Connector/ODBC on Unix .......................................... * Menu: * connector-odbc-installation-binary-unix-tarball:: Installing Connector/ODBC from a Binary Tarball Distribution * connector-odbc-installation-binary-unix-rpm:: Installing Connector/ODBC from an RPM Distribution There are two methods available for installing Connector/ODBC on Unix from a binary distribution. For most Unix environments, you will use the *tarball* distribution. For Linux systems, there is also an *RPM* distribution available. *Note*: To install Connector/ODBC 5.x on Unix requires unixODBC 2.2.12 or later to be installed.  File: manual.info, Node: connector-odbc-installation-binary-unix-tarball, Next: connector-odbc-installation-binary-unix-rpm, Prev: connector-odbc-installation-binary-unix, Up: connector-odbc-installation-binary-unix 21.1.3.5 Installing Connector/ODBC from a Binary Tarball Distribution ..................................................................... To install the driver from a tarball distribution (`.tar.gz' file), download the latest version of the driver for your operating system and follow these steps that demonstrate the process using the Linux version of the tarball, substituting the appropriate file and directory names based on the package you download: shell> su root shell> gunzip mysql-connector-odbc-5.2.2-i686-pc-linux.tar.gz shell> tar xvf mysql-connector-odbc-5.2.2-i686-pc-linux.tar shell> cd mysql-connector-odbc-5.2.2-i686-pc-linux Read the installation instructions in the `INSTALL' file and execute these commands. Then see *Note connector-odbc-configuration-dsn-unix:: to configure the DSN for Connector/ODBC. For more information, refer to the `INSTALL' file that comes with your distribution.  File: manual.info, Node: connector-odbc-installation-binary-unix-rpm, Prev: connector-odbc-installation-binary-unix-tarball, Up: connector-odbc-installation-binary-unix 21.1.3.6 Installing Connector/ODBC from an RPM Distribution ........................................................... To install or upgrade Connector/ODBC from an RPM distribution on Linux, simply download the RPM distribution of the latest version of Connector/ODBC and follow the instructions below. Use `su root' to become `root', then install the RPM file. If you are installing for the first time: shell> su root shell> rpm -ivh mysql-connector-odbc-5.2.2.i386.rpm If the driver exists, upgrade it like this: shell> su root shell> rpm -Uvh mysql-connector-odbc-5.2.2.i386.rpm If there is any dependency error for MySQL client library, `libmysqlclient', simply ignore it by supplying the `--nodeps' option, and then make sure the MySQL client shared library is in the path or set through `LD_LIBRARY_PATH'. This installs the driver libraries and related documents to `/usr/local/lib' and `/usr/share/doc/MyODBC', respectively. See *Note connector-odbc-configuration-dsn-unix:: for the post-installation configuration steps. To *uninstall* the driver, become `root' and execute an `rpm' command: shell> su root shell> rpm -e mysql-connector-odbc  File: manual.info, Node: connector-odbc-installation-binary-macosx, Next: connector-odbc-installation-source-windows, Prev: connector-odbc-installation-binary-unix, Up: connector-odbc-installation 21.1.3.7 Installing Connector/ODBC on Mac OS X .............................................. Mac OS X is based on the FreeBSD operating system, and you can normally use the MySQL network port for connecting to MySQL servers on other hosts. Installing the Connector/ODBC driver lets you connect to MySQL databases on any platform through the ODBC interface. If your application requires an ODBC interface, install the Connector/ODBC driver. Applications that require or can use ODBC (and therefore the Connector/ODBC driver) include ColdFusion, Filemaker Pro, 4th Dimension and many other applications. On Mac OS X, the ODBC Administrator, based on the `iODBC' manager, provides easy administration of ODBC drivers and configuration, allowing the updates of the underlying `iODBC' configuration files through a GUI tool. The tool is included in Mac OS X v10.5 and earlier; users of later versions of Mac OS X need to download and install it manually. There are two ways to install Connector/ODBC on Mac OS X. You can use either the package provided in a compressed tar archive that you manually install, or use a compressed disk image (`.dmg') file, which includes an installer. To install using the compressed tar archive: 1. Download the compressed tar archive. 2. Extract the archive: shell> tar xvzf mysql-connector-odbc-5.X.Y-osx10.Z-x86-(32|64)bit.tar.gz 3. The directory created contains two subdirectories, `lib' and `bin'. Copy these to a suitable location such as `/usr/local': shell> cp bin/* /usr/local/bin shell> cp lib/* /usr/local/lib 4. Finally, register the driver with iODBC using the `myodbc-installer' tool that was included in the package: shell> myodbc-installer -a -d -t"MySQL ODBC 5.2 Driver;Driver=/usr/local/lib/libmyodbc5w.so" To verify the installed drivers, either use the ODBC Administrator application or the `myodbc-installer' utility: shell> myodbc-installer -q -d  File: manual.info, Node: connector-odbc-installation-source-windows, Next: connector-odbc-installation-source-unix, Prev: connector-odbc-installation-binary-macosx, Up: connector-odbc-installation 21.1.3.8 Building Connector/ODBC from a Source Distribution on Windows ...................................................................... You only need to build Connector/ODBC from source on Windows to modify the source or installation location. If you are unsure whether to install from source, please use the binary installation detailed in *Note connector-odbc-installation-binary-windows::. Building Connector/ODBC from source on Windows requires a number of different tools and packages: * MDAC, Microsoft Data Access SDK from `http://support.microsoft.com/kb/110093'. * Suitable C compiler, such as Microsoft Visual C++ or the C compiler included with Microsoft Visual Studio. Microsoft Visual Studio 7 and 8 are preferred, and well-tested. * Connector/ODBC 5.2: `cmake'. * MySQL client libraries and include files from MySQL 4.0.0 or higher. (Preferably MySQL 4.0.16 or higher). This is required because Connector/ODBC uses calls and structures that exist only starting from this version of the library. To get the client libraries and include files, visit `http://dev.mysql.com/downloads/'. * Build Steps * Set the environment variables for the Visual Studio toolchain. Visual Studio includes a batch file to set these for you, and installs a `Start' menu shortcut that opens a command prompt with these variables set. Set `MYSQL_DIR' to the MySQL server installation path, while using the short-style file names. For example: C:\> set MYSQL_DIR=C:\PROGRA~1\MySQL\MYSQLS~1.0 Build Connector/ODBC using the `cmake' command-line tool by executing the following from the source root directory (in a command prompt window): C:\> cmake -G "Visual Studio 8 2005" This produces a project file that you can open with Visual Studio, or build from the command line with either of the following commands: C:\> devenv.com MySQL_Connector_ODBC.sln /build Release C:\> devenv.com MySQL_Connector_ODBC.sln /build RelWithDebInfo To compile a debug build, set the `cmake' build type so that the correct versions of the MySQL client libraries are used: C:\> cmake -G "Visual Studio 8 2005" -DWITH_DEBUG=1 C:\> devenv.com MySQL_Connector_ODBC.sln /build Debug Upon completion, the executables are in the `bin/' and `lib/' subdirectories. See *Note connector-odbc-installation-binary-windows-dll:: for the `copy' commands to complete the installation.  File: manual.info, Node: connector-odbc-installation-source-unix, Next: connector-odbc-installation-source-unix-macosx, Prev: connector-odbc-installation-source-windows, Up: connector-odbc-installation 21.1.3.9 Building Connector/ODBC from a Source Distribution on Unix ................................................................... *Note*: Connector/5.2 uses `cmake' for build, rather than `autoconf' and its `configure' command. You need the following tools to build MySQL from source on Unix: * A working ANSI C++ compiler. GCC 4.2.1 or later, Sun Studio 10 or later, Visual Studio 2008 or later, and many current vendor-supplied compilers are known to work. * `cmake'. * MySQL client libraries and include files from MySQL 4.0.0 or higher. (Preferably MySQL 4.0.16 or higher). This is required because Connector/ODBC uses calls and structures that exist only starting from this version of the library. To get the client libraries and include files, visit `http://dev.mysql.com/downloads/'. If you have built your own MySQL server or client libraries from source using the GNU autotools, use the `--enable-thread-safe-client' option to `configure' when the libraries were built. No special option is needed if you configure with `cmake'. Also, ensure that the `libmysqlclient' library was built and installed as a shared library. * A compatible ODBC manager must be installed. Connector/ODBC is known to work with the `iODBC' and `unixODBC' managers. See *Note connector-odbc-driver-manager:: for more information. * If you are using a character set that is not compiled into the MySQL client library, install the MySQL character definitions from the `charsets' directory into SHAREDIR (by default, `/usr/local/mysql/share/mysql/charsets'). These should be in place if you have installed the MySQL server on the same machine. See *Note charset:: for more information on character set support. Once you have all the required files, unpack the source files to a separate directory, then run `configure' and build the library using `make'. * Typical `cmake' Options * `iODBC' is the default ODBC library used by Connector/ODBC. Alternatively, `unixODBC' may be used by passing in the appropriate option to `cmake'. For example: shell> cmake -G "Unix Makefiles" -DWITH_UNIXODBC=1 When you run `cmake', you might add options to the command line. Here are some examples: * `-DODBC_INCLUDES=DIR_NAME' (http://dev.mysql.com/doc/refman/5.5/en/source-configuration-options.html#option_cmake_odbc_includes): Used when the ODBC include directory is not found within the system `$PATH'. * `-DODBC_LIB_DIR=DIR_NAME' (http://dev.mysql.com/doc/refman/5.5/en/source-configuration-options.html#option_cmake_odbc_lib_dir): Used when the ODBC library directory is not found within the system `$PATH'. * `-DWITH_UNIXODBC=1' (http://dev.mysql.com/doc/refman/5.5/en/source-configuration-options.html#option_cmake_with_unixodbc): Enables unixODBC support. * Additional configure Options * There are a number of other options that you need, or want, to set when configuring the Connector/ODBC driver before it is built. * To link the driver with MySQL thread safe client libraries `libmysqlclient_r.so' or `libmysqlclient_r.a', specify the following `configure' option: --enable-thread-safe and can be disabled (default) using --disable-thread-safe This option enables the building of the driver thread-safe library `libmyodbc3_r.so' from by linking with MySQL thread-safe client library `libmysqlclient_r.so'. (The extensions are OS-dependent.) If the compilation with the thread-safe option fails, it may be because the correct thread-libraries on the system could not be located. Set the value of `LIBS' to point to the correct thread library for your system. LIBS="-lpthread" ./configure .. * You can enable or disable the shared and static versions of Connector/ODBC using these options: --enable-shared[=yes|no] --disable-shared --enable-static[=yes|no] --disable-static * By default, all the binary distributions are built as non-debug versions (configured with `--without-debug'). To enable debugging information, build the driver from a source distribution with the proper configuration option to enable debugging support. See *Note source-configuration-options::. * This option is available only for source trees that have been obtained from the Subversion repository. This option does not apply to the packaged source distributions. By default, the driver is built with the `--without-docs' option. If you would like the documentation to be built, then execute `configure' with: --with-docs * Build Steps for Unix * To build the driver libraries, execute `make': shell> make If any errors occur, correct them and continue the build process. If you are not able to build, then send a detailed email to for further assistance. * Building Shared Libraries * On most platforms, MySQL does not build or support `.so' (shared) client libraries by default. This is based on our experience of problems when building shared libraries. In cases like this, you have to download the MySQL distribution and configure it with these options: --without-server --enable-shared To build shared driver libraries, specify the `--enable-shared' option for `configure'. By default, `configure' does not enable this option. If you have configured with the `--disable-shared' option, you can build the `.so' file from the static libraries using the following commands: shell> cd mysql-connector-odbc-3.51.01 shell> make shell> cd driver shell> CC=/usr/bin/gcc \ $CC -bundle -flat_namespace -undefined error \ -o .libs/libmyodbc3-3.51.01.so \ catalog.o connect.o cursor.o dll.o error.o execute.o \ handle.o info.o misc.o myodbc3.o options.o prepare.o \ results.o transact.o utility.o \ -L/usr/local/mysql/lib/mysql/ \ -L/usr/local/iodbc/lib/ \ -lz -lc -lmysqlclient -liodbcinst Make sure to change `-liodbcinst' to `-lodbcinst' if you are using `unixODBC' instead of `iODBC', and configure the library paths accordingly. This builds and places the `libmyodbc3-3.51.01.so' file in the `.libs' directory. Copy this file to the Connector/ODBC library installation directory (`/usr/local/lib', or the `lib' directory under the installation directory that you supplied with the `--prefix' option). shell> cd .libs shell> cp libmyodbc3-3.51.01.so /usr/local/lib shell> cd /usr/local/lib shell> ln -s libmyodbc3-3.51.01.so libmyodbc3.so To build the thread-safe driver library: shell> CC=/usr/bin/gcc \ $CC -bundle -flat_namespace -undefined error -o .libs/libmyodbc3_r-3.51.01.so catalog.o connect.o cursor.o dll.o error.o execute.o handle.o info.o misc.o myodbc3.o options.o prepare.o results.o transact.o utility.o -L/usr/local/mysql/lib/mysql/ -L/usr/local/iodbc/lib/ -lz -lc -lmysqlclient_r -liodbcinst * Installing Driver Libraries * To install the driver libraries, execute the following command: shell> make install That command installs one of the following sets of libraries: For Connector/ODBC 3.51: * `libmyodbc3.so' * `libmyodbc3-3.51.01.so', where 3.51.01 is the version of the driver * `libmyodbc3.a' For thread-safe Connector/ODBC 3.51: * `libmyodbc3_r.so' * `libmyodbc3-3_r.51.01.so' * `libmyodbc3_r.a' For more information on build process, refer to the `INSTALL' file that comes with the source distribution. Note that if you are trying to use the `make' from Sun, you may end up with errors. On the other hand, GNU `gmake' should work fine on all platforms. * Testing Connector/ODBC on Unix * To run the basic samples provided in the distribution with the libraries that you built, use the following command: shell> make test Before running the tests, create the DSN 'myodbc3' in `odbc.ini' and set the environment variable `ODBCINI' to the correct `odbc.ini' file; and MySQL server is running. You can find a sample `odbc.ini' with the driver distribution. You can even modify the `samples/run-samples' script to pass the desired DSN, UID, and PASSWORD values as the command-line arguments to each sample.  File: manual.info, Node: connector-odbc-installation-source-unix-macosx, Next: connector-odbc-installation-source-development, Prev: connector-odbc-installation-source-unix, Up: connector-odbc-installation 21.1.3.10 Building Connector/ODBC from a Source Distribution on Mac OS X ........................................................................ To build the driver on Mac OS X (Darwin), make use of the following `configure' example: shell> ./configure --prefix=/usr/local --with-unixODBC=/usr/local --with-mysql-path=/usr/local/mysql --disable-shared --enable-gui=no --host=powerpc-apple The command assumes that the `unixODBC' and MySQL are installed in the default locations. If not, configure accordingly. On Mac OS X, `--enable-shared' builds `.dylib' files by default. You can build `.so' files like this: shell> make shell> cd driver shell> CC=/usr/bin/gcc \ $CC -bundle -flat_namespace -undefined error -o .libs/libmyodbc3-3.51.01.so *.o -L/usr/local/mysql/lib/ -L/usr/local/iodbc/lib -liodbcinst -lmysqlclient -lz -lc To build the thread-safe driver library: shell> CC=/usr/bin/gcc \ $CC -bundle -flat_namespace -undefined error -o .libs/libmyodbc3-3.51.01.so *.o -L/usr/local/mysql/lib/ -L/usr/local/iodbc/lib -liodbcinst -lmysqlclienti_r -lz -lc -lpthread Make sure to change the `-liodbcinst' to `-lodbcinst' in case of using `unixODBC' instead of `iODBC' and configure the libraries path accordingly. In Apple's version of GCC, both `cc' and `gcc' are actually symbolic links to `gcc3'. Copy this library to the `$prefix/lib' directory and symlink to `libmyodbc3.so'. You can cross-check the output shared-library properties using this command: shell> otool -LD .libs/libmyodbc3-3.51.01.so  File: manual.info, Node: connector-odbc-installation-source-development, Prev: connector-odbc-installation-source-unix-macosx, Up: connector-odbc-installation 21.1.3.11 Installing Connector/ODBC from the Development Source Tree .................................................................... *Caution*: Read this section only if you are interested in helping us test our new code. To just get MySQL Connector/ODBC up and running on your system, use a standard release distribution. To obtain the most recent development source tree, first download and install Bazaar from the Bazaar VCS Web site (http://bazaar-vcs.org). Bazaar is supported by any platform that supports Python, and is therefore compatible with any Linux, Unix, Windows, or Mac OS X host. Instructions for downloading and installing Bazaar on the different platforms are available on the Bazaar Web site. Building from the source trees requires the following tools: * `autoconf' 2.52 (or newer). * `automake' 1.4 (or newer). * `libtool' 1.4 (or newer). * `m4'. The most recent development source tree is available from our public Subversion trees at `http://dev.mysql.com/tech-resources/sources.html'. To check out the Connector/ODBC sources, change to the directory where you want the copy of the Connector/ODBC tree to be stored, then use the following command: shell> bzr branch lp:myodbc You should now have a copy of the entire Connector/ODBC source tree in the directory `connector-odbc3'. To build from this source tree on Unix or Linux, follow these steps: shell> cd myodbc shell> aclocal shell> autoheader shell> libtoolize -c -f shell> autoconf shell> automake; shell> ./configure # Add your favorite options here shell> make When the build is done, run `make install' to install the Connector/ODBC driver on your system. If you have gotten to the `make' stage and the distribution does not compile, please report it to . On Windows, make use of Windows Makefiles `WIN-Makefile' and `WIN-Makefile_debug' in building the driver. For more information, see *Note connector-odbc-installation-source-windows::. After the initial checkout operation to get the source tree, run `bzr pull' periodically to update your source according to the latest version.  File: manual.info, Node: connector-odbc-configuration, Next: connector-odbc-examples, Prev: connector-odbc-installation, Up: connector-odbc 21.1.4 Configuring Connector/ODBC --------------------------------- * Menu: * connector-odbc-configuration-dsn:: Overview of Connector/ODBC Data Source Names * connector-odbc-configuration-connection-parameters:: Connector/ODBC Connection Parameters * connector-odbc-configuration-dsn-windows:: Configuring a Connector/ODBC DSN on Windows * connector-odbc-configuration-dsn-macosx:: Configuring a Connector/ODBC DSN on Mac OS X * connector-odbc-configuration-dsn-unix:: Configuring a Connector/ODBC DSN on Unix * connector-odbc-configuration-connection-without-dsn:: Connecting Without a Predefined DSN * connector-odbc-configuration-connection-pooling:: ODBC Connection Pooling * connector-odbc-configuration-trace:: Getting an ODBC Trace File Before you connect to a MySQL database using the Connector/ODBC driver, you configure an ODBC Data Source Name (DSN). The DSN associates the various configuration parameters required to communicate with a database to a specific name. You use the DSN in an application to communicate with the database, rather than specifying individual parameters within the application itself. DSN information can be user-specific, system-specific, or provided in a special file. ODBC data source names are configured in different ways, depending on your platform and ODBC driver.  File: manual.info, Node: connector-odbc-configuration-dsn, Next: connector-odbc-configuration-connection-parameters, Prev: connector-odbc-configuration, Up: connector-odbc-configuration 21.1.4.1 Overview of Connector/ODBC Data Source Names ..................................................... A Data Source Name associates the configuration parameters for communicating with a specific database. Generally, a DSN consists of the following parameters: * Name * Host Name * Database Name * Login * Password In addition, different ODBC drivers, including Connector/ODBC, may accept additional driver-specific options and parameters. There are three types of DSN: * A _System DSN_ is a global DSN definition that is available to any user and application on a particular system. A System DSN can normally only be configured by a systems administrator, or by a user who has specific permissions that let them create System DSNs. * A _User DSN_ is specific to an individual user, and can be used to store database connectivity information that the user regularly uses. * A _File DSN_ uses a simple file to define the DSN configuration. File DSNs can be shared between users and machines and are therefore more practical when installing or deploying DSN information as part of an application across many machines. DSN information is stored in different locations depending on your platform and environment.  File: manual.info, Node: connector-odbc-configuration-connection-parameters, Next: connector-odbc-configuration-dsn-windows, Prev: connector-odbc-configuration-dsn, Up: connector-odbc-configuration 21.1.4.2 Connector/ODBC Connection Parameters ............................................. You can specify the parameters in the following tables for Connector/ODBC when configuring a DSN: * *Note codbc-dsn-config-options:: * *Note codbc-dsn-option-flags:: Users on Windows can use the Options and Advanced panels when configuring a DSN to set these parameters; see *Note codbc-dsn-config-options:: for information on which options are related to which fields and check boxes. On Unix and Mac OS X, use the parameter name and value as the keyword/value pair in the DSN configuration. Alternatively, you can set these parameters within the `InConnectionString' argument in the `SQLDriverConnect()' call. *Connector/ODBC DSN Configuration Options* Parameter Default Value Comment `user' ODBC The user name used to connect to MySQL. `uid' ODBC Synonymous with `user'. Added in 3.51.16. `server' `localhost' The host name of the MySQL server. `database' The default database. `option' 0 Options that specify how Connector/ODBC works. See *Note codbc-dsn-option-flags:: and *Note codbc-dsn-option-combos::. `port' 3306 The TCP/IP port to use if `server' is not `localhost'. `initstmt' Initial statement. A statement to execute when connecting to MySQL. In version 3.51 the parameter is called `stmt'. Note: the driver supports the initial statement being executed only at the time of the initial connection. `password' The password for the `user' account on `server'. `pwd' Synonymous with `password'. Added in 3.51.16. `socket' The Unix socket file or Windows named pipe to connect to if `server' is `localhost'. `sslca' The path to a file with a list of trust SSL CAs. Added in 3.51.16. `sslcapath' The path to a directory that contains trusted SSL CA certificates in PEM format. Added in 3.51.16. `sslcert' The name of the SSL certificate file to use for establishing a secure connection. Added in 3.51.16. `sslcipher' A list of permissible ciphers to use for SSL encryption. The cipher list has the same format as the `openssl ciphers' command. Added in 3.51.16. `sslkey' The name of the SSL key file to use for establishing a secure connection. Added in 3.51.16. `charset' The character set to use for the connection. Added in 3.51.17. `sslverify' If set to 1, the SSL certificate will be verified when used with the MySQL connection. If not set, then the default behavior is to ignore SSL certificate verification. `readtimeout' The timeout in seconds for attempts to read from the server. Each attempt uses this timeout value and 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. This option works only for TCP/IP connections, and only for Windows prior to MySQL 5.1.12. Corresponds to the `MYSQL_OPT_READ_TIMEOUT' option of the MySQL Client Library. Added in 3.51.27. `writetimeout' The timeout in seconds for attempts to write to the server. Each attempt uses this timeout value and there are `net_retry_count' retries if necessary, so the total effective timeout value is `net_retry_count' times the option value. This option works only for TCP/IP connections, and only for Windows prior to MySQL 5.1.12. Corresponds to the `MYSQL_OPT_WRITE_TIMEOUT' option of the MySQL Client Library. Added in 3.51.27. `interactive' Enables the `CLIENT_INTERACTIVE' connection option of `mysql_real_connect'. `prefetch' 0 When set to a non-zero value N, causes all queries in the connection to return N rows at a time rather than the entire result set. Useful for queries against very large tables where it is not practical to retrieve the whole result set at once. You can scroll through the result set, N records at a time. This option works only with forward-only cursors. It does not work when the option parameter `MULTI_STATEMENTS' is set. It can be used in combination with the option parameter `NO_CACHE'. Its behavior in ADO applications is undefined: the prefetching might or might not occur. `no_ssps' 0 In Connector/ODBC 5.2, by default, server-side prepared statements are used. When this option is set to a non-zero value, prepared statements are emulated on the client side, which is the same behavior as in 5.1 and 3.51. Added in 5.2. `can_handle_exp_pwd'0 Indicates that the application can deal with an expired password, which is signalled by an SQL state of `08004' (`Server rejected the connection') and a native error code `ER_MUST_CHANGE_PASSWORD_LOGIN' (1862). The connection is `sandboxed', and can do nothing other than issue a `SET PASSWORD' statement. To establish a connection in this case, your application must either use the `initstmt' connection option to set a new password at the start, or issue a `SET PASSWORD' statement immediately after connecting. Once the expired password is reset, the restrictions on the connection are lifted. See `ALTER USER' Syntax (http://dev.mysql.com/doc/refman/5.6/en/alter-user.html) for details about password expiration for MySQL server accounts. Added in 5.2.4. *Note*: The SSL configuration parameters can also be automatically loaded from a `my.ini' or `my.cnf' file. See *Note option-files::. The behavior of Connector/ODBC can be modified by using special option parameters listed in *Note codbc-dsn-option-flags::, specified in the connection string or through the GUI dialog box. Most of the connection parameters also have their own numeric constant values, which can be added up as a combined value for the `option' parameter for specifying those options. However, the numerical `option' value in the connection string can only enable, but not disable parameters enabled on the DSN, which can only be overridden by specifying the option parameters using their text names in the connection string. *Note*: While the combined numerical value for the `option' parameter can be easily constructed by addition of the options' constant values, decomposing the value to verify if particular options are enabled can be difficult. We recommend using the options' parameter names instead in the connection string, because they are self-explanatory. Also notice that not every option parameter has a constant value. *Connector/ODBC Option Parameters* Parameter Name GUI Option Constant Description Value `FOUND_ROWS' Return matched 2 The client cannot handle rows instead of when MySQL returns the true affected rows value of affected rows. If this flag is set, MySQL returns `found rows' instead. You must have MySQL 3.21.14 or newer for this to work. `BIG_PACKETS' Allow big result 8 Do not set any packet limit set for results and bind parameters. Without this option, parameter binding will be truncated to 255 characters. `NO_PROMPT' Don't prompt when 16 Do not prompt for questions connecting even if driver would like to prompt. `DYNAMIC_CURSOR' Enable Dynamic 32 Enable or disable the Cursors dynamic cursor support. `NO_SCHEMA' Ignore schema in 64 Ignore use of database name column in DB_NAME.TBL_NAME.COL_NAME. specifications `NO_DEFAULT_CURSOR' Disable 128 Force use of ODBC manager driver-provided cursors (experimental). cursor support `NO_LOCALE' Don't use 256 Disable the use of extended setlocale() fetch (experimental). `PAD_SPACE' Pad CHAR to full 512 Pad *Note `CHAR': char. length with space columns to full column length. `FULL_COLUMN_NAMES' Include table 1024 `SQLDescribeCol()' returns name in fully-qualified column names. SQLDescribeCol() `COMPRESSED_PROTO' Use compression 2048 Use the compressed client/server protocol. `IGNORE_SPACE' Ignore space 4096 Tell server to ignore space after function after function name and names before ``('' (needed by PowerBuilder). This makes all function names keywords. `NAMED_PIPE' Named Pipe 8192 Connect with named pipes to a *Note `mysqld': mysqld. server running on NT. `NO_BIGINT' Treat BIGINT 16384 Change *Note `BIGINT': columns as INT integer-types. columns to columns *Note `INT': integer-types. columns (some applications cannot handle *Note `BIGINT': integer-types.). `NO_CATALOG' Disable catalog 32768 Forces results from the support catalog functions, such as `SQLTables', to always return `NULL' and the driver to report that catalogs are not supported. `USE_MYCNF' Read options from 65536 Read parameters from the `my.cnf' `[client]' and `[odbc]' groups from `my.cnf'. `SAFE' Enable safe 131072 Add some extra safety checks. options `NO_TRANSACTIONS' Disable 262144 Disable transactions. transaction support `LOG_QUERY' Log queries to 524288 Enable query logging to %TEMP%\myodbc.sql `c:\myodbc.sql'(`/tmp/myodbc.sql') file. (Enabled only in debug mode.) `NO_CACHE' Don't cache 1048576 Do not cache the results results of locally in the driver, forward-only instead read from server cursors (*Note `mysql_use_result()': mysql-use-result.). This works only for forward-only cursors. This option is very important in dealing with large tables when you do not want the driver to cache the entire result set. `FORWARD_CURSOR' Force use of 2097152 Force the use of forward-only `Forward-only' cursor type. cursors In cases of applications setting the default static/dynamic cursor type and one wants the driver to use noncache result sets, this option ensures the forward-only cursor behavior. `AUTO_RECONNECT' Enable automatic 4194304 Enables auto-reconnection reconnect functionality. Do not use this option with transactions (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction), since an auto-reconnection during a incomplete transaction may cause corruption. Note that an auto-reconnected connection will not inherit the same settings and environment as the original connection. Added in 3.51.13. `AUTO_IS_NULL' Enable 8388608 When `AUTO_IS_NULL' is set, SQL_AUTO_IS_NULL the driver does not change the default value of `sql_auto_is_null', leaving it at 1, so you get the MySQL default, not the SQL standard behavior. When `AUTO_IS_NULL' is not set, the driver changes the default value of `SQL_AUTO_IS_NULL' to 0 after connecting, so you get the SQL standard, not the MySQL default behavior. Thus, omitting the flag disables the compatibility option and forces SQL standard behavior. See `IS NULL'. Added in 3.51.13. `ZERO_DATE_TO_MIN' Return 16777216 Translates zero dates SQL_NULL_DATA for (`XXXX-00-00') into the zero date minimum date values supported by ODBC, `XXXX-01-01'. This resolves an issue where some statements will not work because the date returned and the minimum ODBC date value are incompatible. Added in 3.51.17. `MIN_DATE_TO_ZERO' Bind minimal date 33554432 Translates the minimum ODBC as zero date date value (`XXXX-01-01') to the zero date format supported by MySQL (`XXXX-00-00'). This resolves an issue where some statements will not work because the date returned and the minimum ODBC date value are incompatible. Added in 3.51.17. `MULTI_STATEMENTS' Allow multiple 67108864 Enables support for batched statements statements. Added in 3.51.18. `COLUMN_SIZE_S32' Limit column size 134217728 Limits the column size to a to signed 32-bit signed 32-bit value to range prevent problems with larger column sizes in applications that do not support them. This option is automatically enabled when working with ADO applications. Added in 3.51.22. `NO_BINARY_RESULT' Always handle 268435456 When set, this option binary function disables charset 63 for results as columns with an empty character data `org_table'. Added in 3.51.26. `DFLT_BIGINT_BIND_STR' [This option is 536870912 Causes `BIGINT' parameters not on the GUI to be bound as strings. dialog box] Microsoft Access treats `BIGINT' as a string on linked tables. The value is read correctly, but bound as a string. This option is used automatically if the driver is used by Microsoft Access. Added in 5.1.3. `NO_INFORMATION_SCHEMA' Don't use 1073741824 Tells catalog functions not INFORMATION_SCHEMA to use `INFORMATION_SCHEMA', for metadata but rather use legacy algorithms. The trade-off here is usually speed for information quality. Using `INFORMATION_SCHEMA' is often slow, but the information obtained is more complete. Added in 5.1.7. `INTERACTIVE' Interactive Client - Makes the client interactive and uses `interactive_timeout' instead of `wait_timeout'. Added in 5.1.7. `CAN_HANDLE_EXP_PWD' Can Handle - Enables handling of expired Expired Password password. Added in 5.2.4. `ENABLE_CLEARTEXT_PLUGIN' Enable Cleartext - Enables cleartext Authentication authentication. Added in 5.1.13 and 5.2.5. `NO_SSPS' Prepare - Prepares statements on the statements on the client instead of the client server. Added in 5.2.0. `PREFETCH' Prefecth from - Specifies the number of rows server by N rows (N) to prefetch from the at a time server for queries without `LIMIT'. It turns, for example, `SELECT * FROM table' into `SELECT * FROM table LIMIT 0, N'. If the client wants to read more rows than specified in the PREFETCH parameter, the driver runs another query `SELECT * FROM table LIMIT N+1, N*2'. Added in 5.1.11. *Note codbc-dsn-option-combos:: shows some recommended parameter settings and their corresponding `option' values for various configurations: *Recommended Connector/ODBC Option Values for Different Configurations* Configuration Parameter Option Settings Value Microsoft FOUND_ROWS=1; 2 Access, Visual Basic Microsoft FOUND_ROWS=1;DYNAMIC_CURSOR=1;34 Access (with improved DELETE queries) Microsoft SQL COLUMN_SIZE_S32=1;134217728 Server Large tables COMPRESSED_PROTO=1;2048 with too many rows Sybase IGNORE_SPACE=1;FLAG_SAFE=1;135168 PowerBuilder Query log LOG_QUERY=1; 524288 generation (Debug mode) Large tables NO_CACHE=1;FORWARD_CURSOR=1;3145728 with no-cache results Applications PREFETCH=N Not that run Applicable full-table "SELECT * FROM ... " query, but read only a small number (N) of rows from the result  File: manual.info, Node: connector-odbc-configuration-dsn-windows, Next: connector-odbc-configuration-dsn-macosx, Prev: connector-odbc-configuration-connection-parameters, Up: connector-odbc-configuration 21.1.4.3 Configuring a Connector/ODBC DSN on Windows .................................................... * Menu: * connector-odbc-configuration-dsn-windows-5-2:: Configuring a Connector/ODBC 5.x DSN on Windows * connector-odbc-configuration-dsn-windows-5-2-command-line:: Configuring a Connector/ODBC 5.x DSN on Windows, Using the Command Line * connector-odbc-configuration-dsn-windows-problems:: Troubleshooting ODBC Connection Problems The `ODBC Data Source Administrator' within Windows lets you create DSNs, check driver installation and configure ODBC systems such as tracing (used for debugging) and connection pooling. Different editions and versions of Windows store the `ODBC Data Source Administrator' in different locations depending on the version of Windows that you are using. To open the `ODBC Data Source Administrator' in Windows Server 2003: *Tip*: To identify whether a DSN was created using the 32-bit or the 64-bit driver, include the driver being used within the DSN identifier. This will help you to identify the right DSN to use with applications such as Excel that are only compatible with the 32-bit driver. For example, you might add `Using32bitCODBC' to the DSN identifier for the 32-bit interface and `Using64bitCODBC' for those using the 64-bit Connector/ODBC driver. 1. On the `Start' menu, choose `Administrative Tools', and then click `Data Sources (ODBC)'. To open the `ODBC Data Source Administrator' in Windows 2000 Server or Windows 2000 Professional: 1. On the `Start' menu, choose `Settings', and then click `Control Panel'. 2. In `Control Panel', click `Administrative Tools'. 3. In `Administrative Tools', click `Data Sources (ODBC)'. To open the `ODBC Data Source Administrator' on Windows XP: 1. On the `Start' menu, click `Control Panel'. 2. In the `Control Panel' when in `Category View' click `Performance and Maintenance' and then click `Administrative Tools.'. If you are viewing the `Control Panel' in `Classic View', click `Administrative Tools'. 3. In `Administrative Tools', click `Data Sources (ODBC)'. Irrespective of your Windows version, you should be presented the `ODBC Data Source Administrator' window: `ODBC Data Source Administrator' Dialog Within Windows XP, you can add the `Administrative Tools' folder to your `Start' menu to make it easier to locate the ODBC Data Source Administrator. To do this: 1. Right-click the `Start' menu. 2. Select `Properties'. 3. Click `Customize...'. 4. Select the `Advanced' tab. 5. Within `Start menu items', within the `System Administrative Tools' section, select `Display on the All Programs menu'. Within both Windows Server 2003 and Windows XP, consider permanently adding the `ODBC Data Source Administrator' to your `Start' menu. To do this, locate the `Data Sources (ODBC)' icon using the methods shown, then right-click on the icon and then choose `Pin to Start Menu'. The interfaces for the 3.51 and 5.x versions of the Connector/ODBC driver are different, although the fields and information that you need to enter remain the same. To configure a DSN using Connector/ODBC 5.2, see *Note connector-odbc-configuration-dsn-windows-5-2::.  File: manual.info, Node: connector-odbc-configuration-dsn-windows-5-2, Next: connector-odbc-configuration-dsn-windows-5-2-command-line, Prev: connector-odbc-configuration-dsn-windows, Up: connector-odbc-configuration-dsn-windows 21.1.4.4 Configuring a Connector/ODBC 5.x DSN on Windows ........................................................ Due to the native Unicode support within Connector/ODBC, you do not need to specify the initial character set to be used with your connection. To add or configure a Connector/ODBC 5.x DSN on Windows, use either the command-line, or the `ODBC Data Source Administrator' GUI. 1. Open the `ODBC Data Source Administrator'. 2. To create a System DSN (which will be available to all users), select the `System DSN' tab. To create a User DSN, which will be unique only to the current user, click the `Add...' button. 3. Select the ODBC driver for this DSN. `MySQL ODBC Driver Selection' Dialog Select `MySQL ODBC 5.X Driver' for the appropriate level of Connector/ODBC, then click `Finish'. 4. You now need to configure the specific fields for the DSN you are creating through the `Connection Parameters' dialog. `Add Data Source Name' Dialog for Connector/ODBC 5.2 In the `Data Source Name' box, enter the name of the data source to access. It can be any valid name that you choose. 5. In the `Description' box, enter some text to help identify the connection. 6. In the `Server' field, enter the name of the MySQL server host to access. By default, it is `localhost'. 7. In the `User' field, enter the user name to use for this connection. 8. In the `Password' field, enter the corresponding password for this connection. 9. The `Database' pop-up should automatically populate with the list of databases that the user has permissions to access. 10. To communicate over a different TCP/IP port than the default (3306), change the value of the `Port'. 11. Click `OK' to save the DSN. To verify the connection using the parameters you have entered, click the `Test' button. If the connection could be made successfully, you will be notified with a `Success; connection was made!' dialog. You can configure a number of options for a specific DSN by using the `Details' button. Connector/ODBC Connect Options Dialog The `Details' button opens a tabbed display where you set additional options: * `Flags 1', `Flags 2', and `Flags 3' enable you to select the additional flags for the DSN connection. For more information on these flags, see *Note connector-odbc-configuration-connection-parameters::. * `Debug' lets you turn on ODBC debugging to record the queries you execute through the DSN to the `myodbc.sql' file. For more information, see *Note connector-odbc-configuration-trace::. * `SSL Settings' configures the additional options required for using the Secure Sockets Layer (SSL) when communicating with MySQL server. Note that you must also enable SSL and configure the MySQL server with suitable certificates to communicate over SSL. Connector/ODBC 5.2 SSL Configuration The `Advanced' tab lets you configure Connector/ODBC connection parameters. Refer to *Note connector-odbc-configuration-connection-parameters::, for information about the meaning of these options.  File: manual.info, Node: connector-odbc-configuration-dsn-windows-5-2-command-line, Next: connector-odbc-configuration-dsn-windows-problems, Prev: connector-odbc-configuration-dsn-windows-5-2, Up: connector-odbc-configuration-dsn-windows 21.1.4.5 Configuring a Connector/ODBC 5.x DSN on Windows, Using the Command Line ................................................................................ Use `myodbc-installer.exe' when configuring Connector/ODBC 5.1 or later from the command-line. Execute `myodbc-installer.exe' without arguments to view a list of available options.  File: manual.info, Node: connector-odbc-configuration-dsn-windows-problems, Prev: connector-odbc-configuration-dsn-windows-5-2-command-line, Up: connector-odbc-configuration-dsn-windows 21.1.4.6 Troubleshooting ODBC Connection Problems ................................................. This section answers Connector/ODBC connection-related questions. * *While configuring a Connector/ODBC DSN, a `Could Not Load Translator or Setup Library' error occurs* For more information, refer to MS KnowledgeBase Article(Q260558) (http://support.microsoft.com/default.aspx?scid=kb;EN-US;q260558). Also, make sure you have the latest valid `ctl3d32.dll' in your system directory. * On Windows, the default `myodbc5w.dll' (Unicode) or `myodbc5a.dll' (ANSI) is compiled for optimal performance. To debug Connector/ODBC (for example, to enable tracing), instead use `myodbc5d.dll'. To install this file, copy `myodbc5d.dll' over the installed `myodbc5w.dll' or `myodbc5a.dll' file. Make sure to revert back to the release version of the driver DLL once you are done with the debugging, because the debug version may cause performance issues.  File: manual.info, Node: connector-odbc-configuration-dsn-macosx, Next: connector-odbc-configuration-dsn-unix, Prev: connector-odbc-configuration-dsn-windows, Up: connector-odbc-configuration 21.1.4.7 Configuring a Connector/ODBC DSN on Mac OS X ..................................................... To configure a DSN on Mac OS X, you can either use the command-line utility (`myodbc-installer'), edit the `odbc.ini' file within the `Library/ODBC' directory of the user, or use the ODBC Administrator GUI. If you have Mac OS X 10.2 or earlier, refer to *Note connector-odbc-configuration-dsn-unix::. Select whether to create a User DSN or a System DSN. When adding a System DSN, you might need to authenticate with the system. Click the padlock and enter a user and password with administrator privileges. For correct operation of ODBC Administrator, ensure that the `/Library/ODBC/odbc.ini' file used to set up ODBC connectivity and DSNs are writable by the `admin' group. If this file is not writable by this group, then the ODBC Administrator may fail, or may appear to work but not generate the correct entry. *Warning*: There are known issues with the Mac OS X ODBC Administrator and Connector/ODBC that may prevent you from creating a DSN using this method. In this case, use the command line or edit the `odbc.ini' file directly. Note that existing DSNs or those that you created using the `myodbc-installer' tool can still be checked and edited using ODBC Administrator. To create a DSN using the `myodbc-installer' utility, you need only specify the DSN type and the DSN connection string. For example: shell> myodbc-installer -a -s -t"DSN=mydb;DRIVER=MySQL ODBC 5.2 Driver;SERVER=mysql;USER=username;PASSWORD=pass" To use ODBC Administrator: 1. Open the ODBC Administrator from the `Utilities' folder in the `Applications' folder. `ODBC Administrator Main Panel' Dialog 2. On the User DSN or System DSN panel, click `Add'. 3. Select the Connector/ODBC driver and click `OK'. 4. You will be presented with the `Data Source Name' dialog. Enter the `Data Source Name' and an optional `Description' for the DSN. `ODBC Administrator Add DSN' Dialog 5. Click `Add' to add a new keyword/value pair to the panel. Configure at least four pairs to specify the `server', `username', `password' and `database' connection parameters. See *Note connector-odbc-configuration-connection-parameters::. 6. Click `OK' to add the DSN to the list of configured data source names. A completed DSN configuration may look like this: `ODBC Administrator Sample DSN' Dialog You can configure other ODBC options in your DSN by adding further keyword/value pairs and setting the corresponding values. See *Note connector-odbc-configuration-connection-parameters::.  File: manual.info, Node: connector-odbc-configuration-dsn-unix, Next: connector-odbc-configuration-connection-without-dsn, Prev: connector-odbc-configuration-dsn-macosx, Up: connector-odbc-configuration 21.1.4.8 Configuring a Connector/ODBC DSN on Unix ................................................. On `Unix', you configure DSN entries directly in the `odbc.ini' file. Here is a typical `odbc.ini' file that configures `myodbc3' as the DSN name for Connector/ODBC 3.51: ; ; odbc.ini configuration for Connector/ODBC and Connector/ODBC 3.51 drivers ; [ODBC Data Sources] myodbc3 = MyODBC 3.51 Driver DSN [myodbc3] Driver = /usr/local/lib/libmyodbc3.so Description = Connector/ODBC 3.51 Driver DSN SERVER = localhost PORT = USER = root Password = Database = test OPTION = 3 SOCKET = [Default] Driver = /usr/local/lib/libmyodbc3.so Description = Connector/ODBC 3.51 Driver DSN SERVER = localhost PORT = USER = root Password = Database = test OPTION = 3 SOCKET = Refer to the *Note connector-odbc-configuration-connection-parameters::, for the list of connection parameters that can be supplied. *Note*: If you are using `unixODBC', you can use the following tools to set up the DSN: * `ODBCConfig' GUI tool (HOWTO: ODBCConfig (http://www.unixodbc.org/config.html)) * `odbcinst' In some cases when using `unixODBC', you might get this error: Data source name not found and no default driver specified If this happens, make sure the `ODBCINI' and `ODBCSYSINI' environment variables are pointing to the right `odbc.ini' file. For example, if your `odbc.ini' file is located in `/usr/local/etc', set the environment variables like this: export ODBCINI=/usr/local/etc/odbc.ini export ODBCSYSINI=/usr/local/etc  File: manual.info, Node: connector-odbc-configuration-connection-without-dsn, Next: connector-odbc-configuration-connection-pooling, Prev: connector-odbc-configuration-dsn-unix, Up: connector-odbc-configuration 21.1.4.9 Connecting Without a Predefined DSN ............................................ You can connect to the MySQL server using `SQLDriverConnect', by specifying the `DRIVER' name field. Here are the connection strings for Connector/ODBC using DSN-Less connections: * For Connector/ODBC 3.51: * ConnectionString = "DRIVER={MySQL ODBC 3.51 Driver};\ SERVER=localhost;\ DATABASE=test;\ USER=venu;\ PASSWORD=venu;\ OPTION=3;" If your programming language converts backslash followed by whitespace to a space, it is preferable to specify the connection string as a single long string, or to use a concatenation of multiple strings that does not add spaces in between. For example: ConnectionString = "DRIVER={MySQL ODBC 3.51 Driver};" "SERVER=localhost;" "DATABASE=test;" "USER=venu;" "PASSWORD=venu;" "OPTION=3;" Note On Mac OS X, you might need to specify the full path to the Connector/ODBC driver library. Refer to *Note connector-odbc-configuration-connection-parameters:: for the list of connection parameters that can be supplied.  File: manual.info, Node: connector-odbc-configuration-connection-pooling, Next: connector-odbc-configuration-trace, Prev: connector-odbc-configuration-connection-without-dsn, Up: connector-odbc-configuration 21.1.4.10 ODBC Connection Pooling ................................. Connection pooling enables the ODBC driver to re-use existing connections to a given database from a pool of connections, instead of opening a new connection each time the database is accessed. By enabling connection pooling you can improve the overall performance of your application by lowering the time taken to open a connection to a database in the connection pool. For more information about connection pooling: `http://support.microsoft.com/default.aspx?scid=kb;EN-US;q169470'.  File: manual.info, Node: connector-odbc-configuration-trace, Prev: connector-odbc-configuration-connection-pooling, Up: connector-odbc-configuration 21.1.4.11 Getting an ODBC Trace File .................................... * Menu: * connector-odbc-configuration-trace-windows:: Enabling ODBC Tracing on Windows * connector-odbc-configuration-trace-macosx:: Enabling ODBC Tracing on Mac OS X * connector-odbc-configuration-trace-unix:: Enabling ODBC Tracing on Unix * connector-odbc-configuration-trace-log:: Enabling a Connector/ODBC Log If you encounter difficulties or problems with Connector/ODBC, start by making a log file from the `ODBC Manager' and Connector/ODBC. This is called _tracing_, and is enabled through the ODBC Manager. The procedure for this differs for Windows, Mac OS X and Unix.  File: manual.info, Node: connector-odbc-configuration-trace-windows, Next: connector-odbc-configuration-trace-macosx, Prev: connector-odbc-configuration-trace, Up: connector-odbc-configuration-trace 21.1.4.12 Enabling ODBC Tracing on Windows .......................................... To enable the trace option on Windows: 1. The `Tracing' tab of the ODBC Data Source Administrator dialog box lets you configure the way ODBC function calls are traced. ODBC Data Source Administrator Tracing Dialog 2. When you activate tracing from the `Tracing' tab, the `Driver Manager' logs all ODBC function calls for all subsequently run applications. 3. ODBC function calls from applications running before tracing is activated are not logged. ODBC function calls are recorded in a log file you specify. 4. Tracing ceases only after you click `Stop Tracing Now'. Remember that while tracing is on, the log file continues to increase in size and that tracing affects the performance of all your ODBC applications.  File: manual.info, Node: connector-odbc-configuration-trace-macosx, Next: connector-odbc-configuration-trace-unix, Prev: connector-odbc-configuration-trace-windows, Up: connector-odbc-configuration-trace 21.1.4.13 Enabling ODBC Tracing on Mac OS X ........................................... To enable the trace option on Mac OS X 10.3 or later, use the `Tracing' tab within ODBC Administrator . 1. Open the ODBC Administrator. 2. Select the `Tracing' tab. ODBC Administrator Tracing Dialog 3. Select the `Enable Tracing' check box. 4. Enter the location to save the Tracing log. To append information to an existing log file, click the `Choose...' button.  File: manual.info, Node: connector-odbc-configuration-trace-unix, Next: connector-odbc-configuration-trace-log, Prev: connector-odbc-configuration-trace-macosx, Up: connector-odbc-configuration-trace 21.1.4.14 Enabling ODBC Tracing on Unix ....................................... To enable the trace option on Mac OS X 10.2 (or earlier) or Unix, add the `trace' option to the ODBC configuration: 1. On Unix, explicitly set the `Trace' option in the `ODBC.INI' file. Set the tracing `ON' or `OFF' by using `TraceFile' and `Trace' parameters in `odbc.ini' as shown below: TraceFile = /tmp/odbc.trace Trace = 1 `TraceFile' specifies the name and full path of the trace file and `Trace' is set to `ON' or `OFF'. You can also use `1' or `YES' for `ON' and `0' or `NO' for `OFF'. If you are using `ODBCConfig' from `unixODBC', then follow the instructions for tracing `unixODBC' calls at HOWTO-ODBCConfig (http://www.unixodbc.org/config.html).  File: manual.info, Node: connector-odbc-configuration-trace-log, Prev: connector-odbc-configuration-trace-unix, Up: connector-odbc-configuration-trace 21.1.4.15 Enabling a Connector/ODBC Log ....................................... To generate a Connector/ODBC log, do the following: 1. Within Windows, enable the `Trace Connector/ODBC' option flag in the Connector/ODBC connect/configure screen. The log is written to file `C:\myodbc.log'. If the trace option is not remembered when you are going back to the above screen, it means that you are not using the `myodbcd.dll' driver, see *Note connector-odbc-configuration-dsn-windows-problems::. On Mac OS X, Unix, or if you are using a DSN-less connection, either supply `OPTION=4' in the connection string, or set the corresponding keyword/value pair in the DSN. 2. Start your application and try to get it to fail. Then check the Connector/ODBC trace file to find out what could be wrong. If you need help determining what is wrong, see *Note connector-odbc-support-community::.  File: manual.info, Node: connector-odbc-examples, Next: connector-odbc-reference, Prev: connector-odbc-configuration, Up: connector-odbc 21.1.5 Connector/ODBC Examples ------------------------------ * Menu: * connector-odbc-examples-overview:: Basic Connector/ODBC Application Steps * connector-odbc-examples-walkthrough:: Step-by-step Guide to Connecting to a MySQL Database through Connector/ODBC * connector-odbc-examples-tools:: Connector/ODBC and Third-Party ODBC Tools * connector-odbc-examples-tools-with-access:: Using Connector/ODBC with Microsoft Access * connector-odbc-examples-tools-with-wordexcel:: Using Connector/ODBC with Microsoft Word or Excel * connector-odbc-examples-tools-with-crystalreports:: Using Connector/ODBC with Crystal Reports * connector-odbc-examples-programming:: Connector/ODBC Programming Once you have configured a DSN to provide access to a database, how you access and use that connection is dependent on the application or programming language. As ODBC is a standardized interface, any application or language that supports ODBC can use the DSN and connect to the configured database.  File: manual.info, Node: connector-odbc-examples-overview, Next: connector-odbc-examples-walkthrough, Prev: connector-odbc-examples, Up: connector-odbc-examples 21.1.5.1 Basic Connector/ODBC Application Steps ............................................... Interacting with a MySQL server from an applications using the Connector/ODBC typically involves the following operations: * Configure the Connector/ODBC DSN. * Connect to MySQL server. * Initialization operations. * Execute SQL statements. * Retrieve results. * Perform transactions (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction). * Disconnect from the server. Most applications use some variation of these steps. The basic application steps are shown in the following diagram: Connector/ODBC Programming Flowchart  File: manual.info, Node: connector-odbc-examples-walkthrough, Next: connector-odbc-examples-tools, Prev: connector-odbc-examples-overview, Up: connector-odbc-examples 21.1.5.2 Step-by-step Guide to Connecting to a MySQL Database through Connector/ODBC .................................................................................... A typical situation where you would install Connector/ODBC is to access a database on a Linux or Unix host from a Windows machine. As an example of the process required to set up access between two machines, the steps below take you through the basic steps. These instructions assume that you connect to system ALPHA from system BETA with a user name and password of `myuser' and `mypassword'. On system ALPHA (the MySQL server) follow these steps: 1. Start the MySQL server. 2. Use *Note `GRANT': grant. to set up an account with a user name of `myuser' that can connect from system BETA using a password of `myuser' to the database `test': GRANT ALL ON test.* to 'myuser'@'BETA' IDENTIFIED BY 'mypassword'; For more information about MySQL privileges, refer to *Note user-account-management::. On system BETA (the Connector/ODBC client), follow these steps: 1. Configure a Connector/ODBC DSN using parameters that match the server, database and authentication information that you have just configured on system ALPHA. Sample configuration settings for connecting to database on server ALPHA from Connector/ODBC running on server BETA. Parameter Value Comment DSN remote_test A name to identify the connection. SERVER ALPHA The address of the remote server. DATABASE test The name of the default database. USER myuser The user name configured for access to this database. PASSWORD mypassword The password for `myuser'. 2. Using an ODBC-capable application, such as Microsoft Office, connect to the MySQL server using the DSN you have just created. If the connection fails, use tracing to examine the connection process. See *Note connector-odbc-configuration-trace::, for more information.  File: manual.info, Node: connector-odbc-examples-tools, Next: connector-odbc-examples-tools-with-access, Prev: connector-odbc-examples-walkthrough, Up: connector-odbc-examples 21.1.5.3 Connector/ODBC and Third-Party ODBC Tools .................................................. Once you have configured your Connector/ODBC DSN, you can access your MySQL database through any application that supports the ODBC interface, including programming languages and third-party applications. This section contains guides and help on using Connector/ODBC with various ODBC-compatible tools and applications, including Microsoft Word, Microsoft Excel and Adobe/Macromedia ColdFusion. Connector/ODBC has been tested with the following applications: List of applications that Connector/ODBC has been tested with. Publisher Application Notes Adobe ColdFusion Formerly Macromedia ColdFusion Borland C++ Builder Builder 4 Delphi Business Objects Crystal Reports Claris Filemaker Pro Corel Paradox Computer Visual Objects Also known as CAVO Associates AllFusion ERwin Data Modeler Gupta Team Developer Previously known as Centura Team Developer; Gupta SQL/Windows Gensym G2-ODBC Bridge Inline iHTML Lotus Notes Versions 4.5 and 4.6 Microsoft Access Excel Visio Enterprise Visual C++ Visual Basic ODBC.NET Using C#, Visual Basic, C++ FoxPro Visual Interdev OpenOffice.org OpenOffice.org Perl DBD::ODBC Pervasive Software DataJunction Sambar Sambar Server Technologies SPSS SPSS SoftVelocity Clarion SQLExpress SQLExpress for Xbase++ Sun StarOffice SunSystems Vision Sybase PowerBuilder PowerDesigner theKompany.com Data Architect If you know of any other applications that work with Connector/ODBC, please send mail to about them.  File: manual.info, Node: connector-odbc-examples-tools-with-access, Next: connector-odbc-examples-tools-with-wordexcel, Prev: connector-odbc-examples-tools, Up: connector-odbc-examples 21.1.5.4 Using Connector/ODBC with Microsoft Access ................................................... * Menu: * connector-odbc-examples-tools-with-access-export:: Exporting Access Data to MySQL * connector-odbc-examples-tools-with-access-import:: Importing MySQL Data to Access * connector-odbc-examples-tools-with-access-linked-tables:: Using Microsoft Access as a Front-end to MySQL You can use MySQL database with Microsoft Access using Connector/ODBC. The MySQL database can be used as an import source, an export source, or as a linked table for direct use within an Access application, so you can use Access as the front-end interface to a MySQL database.  File: manual.info, Node: connector-odbc-examples-tools-with-access-export, Next: connector-odbc-examples-tools-with-access-import, Prev: connector-odbc-examples-tools-with-access, Up: connector-odbc-examples-tools-with-access 21.1.5.5 Exporting Access Data to MySQL ....................................... To export a table of data from an Access database to MySQL, follow these instructions: 1. When you open an Access database or an Access project, a Database window appears. It displays shortcuts for creating new database objects and opening existing objects. Access Database 2. Click the name of the `table' or `query' to export, and then in the `File' menu, select `Export'. 3. In the `Export Object Type OBJECT NAME To' dialog box, in the `Save As Type' box, select `ODBC Databases ()' as shown here: Selecting an ODBC Database 4. In the `Export' dialog box, enter a name for the file (or use the suggested name), and then select `OK'. 5. The Select Data Source dialog box is displayed; it lists the defined data sources for any ODBC drivers installed on your computer. Click either the File Data Source or Machine Data Source tab, and then double-click the Connector/ODBC or Connector/ODBC 3.51 data source to export to. To define a new data source for Connector/ODBC, please *Note connector-odbc-configuration-dsn-windows::. *Note*: Ensure that the information that you are exporting to the MySQL table is valid for the corresponding MySQL data types. Values that are outside of the supported range of the MySQL data type but valid within Access may trigger an `overflow' error during the export. Microsoft Access connects to the MySQL Server through this data source and exports new tables and or data.  File: manual.info, Node: connector-odbc-examples-tools-with-access-import, Next: connector-odbc-examples-tools-with-access-linked-tables, Prev: connector-odbc-examples-tools-with-access-export, Up: connector-odbc-examples-tools-with-access 21.1.5.6 Importing MySQL Data to Access ....................................... To import a table or tables from MySQL to Access, follow these instructions: 1. Open a database, or switch to the Database window for the open database. 2. To import tables, on the `File' menu, point to `Get External Data', and then click `Import'. 3. In the `Import' dialog box, in the Files Of Type box, select `ODBC Databases ()'. The Select Data Source dialog box lists the defined data sources `The Select Data Source' dialog box is displayed; it lists the defined data source names. 4. If the ODBC data source that you selected requires you to log on, enter your login ID and password (additional information might also be required), and then click `OK'. 5. Microsoft Access connects to the MySQL server through `ODBC data source ' and displays the list of tables that you can `import'. 6. Click each table to `import', and then click `OK'.  File: manual.info, Node: connector-odbc-examples-tools-with-access-linked-tables, Prev: connector-odbc-examples-tools-with-access-import, Up: connector-odbc-examples-tools-with-access 21.1.5.7 Using Microsoft Access as a Front-end to MySQL ....................................................... You can use Microsoft Access as a front end to a MySQL database by linking tables within your Microsoft Access database to tables that exist within your MySQL database. When a query is requested on a table within Access, ODBC is used to execute the queries on the MySQL database instead. *To create a linked table*: 1. Open the Access database that you want to link to MySQL. 2. From the `File', choose `Get External Data->Link Tables'. Linking Microsoft Access tables to MySQL tables 3. From the browser, choose `ODBC Databases ()' from the `Files of type' pop-up. 4. In the `Select Data Source' window, choose an existing DSN, either from a `File Data Source' or `Machine Data Source'.You can also create a new DSN using the `New...' button. For more information on creating a DSN see *Note connector-odbc-configuration-dsn-windows::. Linking Microsoft Access tables to MySQL tables, choosing a DSN 5. In the `Link Tables' dialog, select one or more tables from the MySQL database. A link will be created to each table that you select from this list. Linking Microsoft Access tables to MySQL tables, table selection 6. If Microsoft Access is unable to determine the unique record identifier for a table automatically then it may ask you to confirm the column, or combination of columns, to be used to uniquely identify each row from the source table. Select the columns to use and click `OK'. Linking Microsoft Access tables to MySQL tables, choosing unique record identifier Once the process has been completed, you can now build interfaces and queries to the linked tables just as you would for any Access database. Use the following procedure to view or to refresh links when the structure or location of a linked table has changed. The Linked Table Manager lists the paths to all currently linked tables. *To view or refresh links*: 1. Open the database that contains links to MySQL tables. 2. On the `Tools' menu, point to `Add-ins' (`Database Utilities' in Access 2000 or newer), and then click `Linked Table Manager'. 3. Select the check box for the tables whose links you want to refresh. 4. Click OK to refresh the links. Microsoft Access confirms a successful refresh or, if the table wasn't found, displays the `Select New Location of'
City Population
%s%d
dialog box in which you can specify its the table's new location. If several selected tables have moved to the new location that you specify, the Linked Table Manager searches that location for all selected tables, and updates all links in one step. *To change the path for a set of linked tables*: 1. Open the database that contains links to tables. 2. On the `Tools' menu, point to `Add-ins' (`Database Utilities' in Access 2000 or newer), and then click `Linked Table Manager'. 3. Select the `Always Prompt For A New Location' check box. 4. Select the check box for the tables whose links you want to change, and then click `OK'. 5. In the `Select New Location of'
dialog box, specify the new location, click `Open', and then click `OK'.  File: manual.info, Node: connector-odbc-examples-tools-with-wordexcel, Next: connector-odbc-examples-tools-with-crystalreports, Prev: connector-odbc-examples-tools-with-access, Up: connector-odbc-examples 21.1.5.8 Using Connector/ODBC with Microsoft Word or Excel .......................................................... You can use Microsoft Word and Microsoft Excel to access information from a MySQL database using Connector/ODBC. Within Microsoft Word, this facility is most useful when importing data for mailmerge, or for tables and data to be included in reports. Within Microsoft Excel, you can execute queries on your MySQL server and import the data directly into an Excel Worksheet, presenting the data as a series of rows and columns. With both applications, data is accessed and imported into the application using Microsoft Query, which lets you execute a query though an ODBC source. You use Microsoft Query to build the SQL statement to be executed, selecting the tables, fields, selection criteria and sort order. For example, to insert information from a table in the World test database into an Excel spreadsheet, using the DSN samples shown in *Note connector-odbc-configuration::: 1. Create a new Worksheet. 2. From the `Data' menu, choose `Import External Data', and then select `New Database Query'. 3. Microsoft Query will start. First, you need to choose the data source, by selecting an existing Data Source Name. Microsoft Query, Choose Data Source 4. Within the `Query Wizard', choose the columns to import. The list of tables available to the user configured through the DSN is shown on the left, the columns that will be added to your query are shown on the right. The columns you choose are equivalent to those in the first section of a *Note `SELECT': select. query. Click `Next' to continue. Microsoft Query, Choose Columns 5. You can filter rows from the query (the equivalent of a `WHERE' clause) using the `Filter Data' dialog. Click `Next' to continue. Microsoft Query, Filter Data 6. Select an (optional) sort order for the data. This is equivalent to using a `ORDER BY' clause in your SQL query. You can select up to three fields for sorting the information returned by the query. Click `Next' to continue. Microsoft Query, Sort Order 7. Select the destination for your query. You can select to return the data Microsoft Excel, where you can choose a worksheet and cell where the data will be inserted; you can continue to view the query and results within Microsoft Query, where you can edit the SQL query and further filter and sort the information returned; or you can create an OLAP Cube from the query, which can then be used directly within Microsoft Excel. Click `Finish'. Microsoft Query, Selecting a destination The same process can be used to import data into a Word document, where the data will be inserted as a table. This can be used for mail merge purposes (where the field data is read from a Word table), or where you want to include data and reports within a report or other document.  File: manual.info, Node: connector-odbc-examples-tools-with-crystalreports, Next: connector-odbc-examples-programming, Prev: connector-odbc-examples-tools-with-wordexcel, Up: connector-odbc-examples 21.1.5.9 Using Connector/ODBC with Crystal Reports .................................................. Crystal Reports can use an ODBC DSN to connect to a database from which you to extract data and information for reporting purposes. *Note*: There is a known issue with certain versions of Crystal Reports where the application is unable to open and browse tables and fields through an ODBC connection. Before using Crystal Reports with MySQL, please ensure that you have update to the latest version, including any outstanding service packs and hotfixes. For more information on this issue, see the Business) Objects Knowledgebase (http://support.crystaldecisions.com/library/kbase/new_articles/c2013269.asp) for more information. For example, to create a simple crosstab report within Crystal Reports XI, follow these steps: 1. Create a DSN using the `Data Sources (ODBC)' tool. You can either specify a complete database, including user name and password, or you can build a basic DSN and use Crystal Reports to set the user name and password. For the purposes of this example, a DSN that provides a connection to an instance of the MySQL Sakila sample database has been created. 2. Open Crystal Reports and create a new project, or an open an existing reporting project into which you want to insert data from your MySQL data source. 3. Start the Cross-Tab Report Wizard, either by clicking the option on the Start Page. Expand the `Create New Connection' folder, then expand the `ODBC (RDO)' folder to obtain a list of ODBC data sources. You will be asked to select a data source. Selecting an Data Source in Crystal Reports 4. When you first expand the `ODBC (RDO)' folder you will be presented the Data Source Selection screen. From here you can select either a pre-configured DSN, open a file-based DSN or enter and manual connection string. For this example, the `Sakila' DSN will be used. If the DSN contains a user name/password combination, or you want to use different authentication credentials, click `Next' to enter the user name and password that you want to use. Otherwise, click `Finish' to continue the data source selection wizard. Selecting an ODBC Data Source in Crystal Reports 5. You will be returned the Cross-Tab Report Creation Wizard. You now need to select the database and tables that you want to include in your report. For our example, we will expand the selected Sakila database. Click the `city' table and use the `>' button to add the table to the report. Then repeat the action with the `country' table. Alternatively you can select multiple tables and add them to the report. Finally, you can select the parent `Sakila' resource and add of the tables to the report. Once you have selected the tables you want to include, click `Next' to continue. Selecting an tables in Crystal Reports 6. Crystal Reports will now read the table definitions and automatically identify the links between the tables. The identification of links between tables enables Crystal Reports to automatically lookup and summarize information based on all the tables in the database according to your query. If Crystal Reports is unable to perform the linking itself, you can manually create the links between fields in the tables you have selected. Click `Next' to continue the process. Table links/structure in Crystal Reports 7. You can now select the columns and rows that to include within the Cross-Tab report. Drag and drop or use the `>' buttons to add fields to each area of the report. In the example shown, we will report on cities, organized by country, incorporating a count of the number of cities within each country. If you want to browse the data, select a field and click the `Browse Data...' button. Click `Next' to create a graph of the results. Since we are not creating a graph from this data, click `Finish' to generate the report. Cross-tab definition in Crystal Reports 8. The finished report will be shown, a sample of the output from the Sakila sample database is shown below. Cross-tab final report in Crystal Reports Once the ODBC connection has been opened within Crystal Reports, you can browse and add any fields within the available tables into your reports.  File: manual.info, Node: connector-odbc-examples-programming, Prev: connector-odbc-examples-tools-with-crystalreports, Up: connector-odbc-examples 21.1.5.10 Connector/ODBC Programming .................................... * Menu: * connector-odbc-examples-programming-vb:: Using Connector/ODBC with Visual Basic Using ADO, DAO and RDO * connector-odbc-examples-programming-net:: Using Connector/ODBC with .NET With a suitable ODBC Manager and the Connector/ODBC driver installed, any programming language or environment that can support ODBC can connect to a MySQL database through Connector/ODBC. This includes, but is not limited to, Microsoft support languages (including Visual Basic, C# and interfaces such as ODBC.NET), Perl (through the DBI module, and the DBD::ODBC driver).  File: manual.info, Node: connector-odbc-examples-programming-vb, Next: connector-odbc-examples-programming-net, Prev: connector-odbc-examples-programming, Up: connector-odbc-examples-programming 21.1.5.11 Using Connector/ODBC with Visual Basic Using ADO, DAO and RDO ....................................................................... * Menu: * connector-odbc-examples-programming-vb-ado:: ADO: `rs.addNew', `rs.delete', and `rs.update' * connector-odbc-examples-programming-vb-dao:: DAO: `rs.addNew', `rs.update', and Scrolling * connector-odbc-examples-programming-vb-rdo:: RDO: `rs.addNew' and `rs.update' This section contains simple examples of the use of Connector/ODBC with ADO, DAO and RDO.  File: manual.info, Node: connector-odbc-examples-programming-vb-ado, Next: connector-odbc-examples-programming-vb-dao, Prev: connector-odbc-examples-programming-vb, Up: connector-odbc-examples-programming-vb 21.1.5.12 ADO: `rs.addNew', `rs.delete', and `rs.update' ........................................................ The following ADO (ActiveX Data Objects) example creates a table `my_ado' and demonstrates the use of `rs.addNew', `rs.delete', and `rs.update'. Private Sub myodbc_ado_Click() Dim conn As ADODB.Connection Dim rs As ADODB.Recordset Dim fld As ADODB.Field Dim sql As String 'connect to MySQL server using Connector/ODBC Set conn = New ADODB.Connection conn.ConnectionString = "DRIVER={MySQL ODBC 3.51 Driver};"_ & "SERVER=localhost;"_ & " DATABASE=test;"_ & "UID=venu;PWD=venu; OPTION=3" conn.Open 'create table conn.Execute "DROP TABLE IF EXISTS my_ado" conn.Execute "CREATE TABLE my_ado(id int not null primary key, name varchar(20)," _ & "txt text, dt date, tm time, ts timestamp)" 'direct insert conn.Execute "INSERT INTO my_ado(id,name,txt) values(1,100,'venu')" conn.Execute "INSERT INTO my_ado(id,name,txt) values(2,200,'MySQL')" conn.Execute "INSERT INTO my_ado(id,name,txt) values(3,300,'Delete')" Set rs = New ADODB.Recordset rs.CursorLocation = adUseServer 'fetch the initial table .. rs.Open "SELECT * FROM my_ado", conn Debug.Print rs.RecordCount rs.MoveFirst Debug.Print String(50, "-") & "Initial my_ado Result Set " & String(50, "-") For Each fld In rs.Fields Debug.Print fld.Name, Next Debug.Print Do Until rs.EOF For Each fld In rs.Fields Debug.Print fld.Value, Next rs.MoveNext Debug.Print Loop rs.Close 'rs insert rs.Open "select * from my_ado", conn, adOpenDynamic, adLockOptimistic rs.AddNew rs!Name = "Monty" rs!txt = "Insert row" rs.Update rs.Close 'rs update rs.Open "SELECT * FROM my_ado" rs!Name = "update" rs!txt = "updated-row" rs.Update rs.Close 'rs update second time.. rs.Open "SELECT * FROM my_ado" rs!Name = "update" rs!txt = "updated-second-time" rs.Update rs.Close 'rs delete rs.Open "SELECT * FROM my_ado" rs.MoveNext rs.MoveNext rs.Delete rs.Close 'fetch the updated table .. rs.Open "SELECT * FROM my_ado", conn Debug.Print rs.RecordCount rs.MoveFirst Debug.Print String(50, "-") & "Updated my_ado Result Set " & String(50, "-") For Each fld In rs.Fields Debug.Print fld.Name, Next Debug.Print Do Until rs.EOF For Each fld In rs.Fields Debug.Print fld.Value, Next rs.MoveNext Debug.Print Loop rs.Close conn.Close End Sub  File: manual.info, Node: connector-odbc-examples-programming-vb-dao, Next: connector-odbc-examples-programming-vb-rdo, Prev: connector-odbc-examples-programming-vb-ado, Up: connector-odbc-examples-programming-vb 21.1.5.13 DAO: `rs.addNew', `rs.update', and Scrolling ...................................................... The following DAO (Data Access Objects) example creates a table `my_dao' and demonstrates the use of `rs.addNew', `rs.update', and result set scrolling. Private Sub myodbc_dao_Click() Dim ws As Workspace Dim conn As Connection Dim queryDef As queryDef Dim str As String 'connect to MySQL using MySQL ODBC 3.51 Driver Set ws = DBEngine.CreateWorkspace("", "venu", "venu", dbUseODBC) str = "odbc;DRIVER={MySQL ODBC 3.51 Driver};"_ & "SERVER=localhost;"_ & " DATABASE=test;"_ & "UID=venu;PWD=venu; OPTION=3" Set conn = ws.OpenConnection("test", dbDriverNoPrompt, False, str) 'Create table my_dao Set queryDef = conn.CreateQueryDef("", "drop table if exists my_dao") queryDef.Execute Set queryDef = conn.CreateQueryDef("", "create table my_dao(Id INT AUTO_INCREMENT PRIMARY KEY, " _ & "Ts TIMESTAMP(14) NOT NULL, Name varchar(20), Id2 INT)") queryDef.Execute 'Insert new records using rs.addNew Set rs = conn.OpenRecordset("my_dao") Dim i As Integer For i = 10 To 15 rs.AddNew rs!Name = "insert record" & i rs!Id2 = i rs.Update Next i rs.Close 'rs update.. Set rs = conn.OpenRecordset("my_dao") rs.Edit rs!Name = "updated-string" rs.Update rs.Close 'fetch the table back... Set rs = conn.OpenRecordset("my_dao", dbOpenDynamic) str = "Results:" rs.MoveFirst While Not rs.EOF str = " " & rs!Id & " , " & rs!Name & ", " & rs!Ts & ", " & rs!Id2 Debug.Print "DATA:" & str rs.MoveNext Wend 'rs Scrolling rs.MoveFirst str = " FIRST ROW: " & rs!Id & " , " & rs!Name & ", " & rs!Ts & ", " & rs!Id2 Debug.Print str rs.MoveLast str = " LAST ROW: " & rs!Id & " , " & rs!Name & ", " & rs!Ts & ", " & rs!Id2 Debug.Print str rs.MovePrevious str = " LAST-1 ROW: " & rs!Id & " , " & rs!Name & ", " & rs!Ts & ", " & rs!Id2 Debug.Print str 'free all resources rs.Close queryDef.Close conn.Close ws.Close End Sub  File: manual.info, Node: connector-odbc-examples-programming-vb-rdo, Prev: connector-odbc-examples-programming-vb-dao, Up: connector-odbc-examples-programming-vb 21.1.5.14 RDO: `rs.addNew' and `rs.update' .......................................... The following RDO (Remote Data Objects) example creates a table `my_rdo' and demonstrates the use of `rs.addNew' and `rs.update'. Dim rs As rdoResultset Dim cn As New rdoConnection Dim cl As rdoColumn Dim SQL As String 'cn.Connect = "DSN=test;" cn.Connect = "DRIVER={MySQL ODBC 3.51 Driver};"_ & "SERVER=localhost;"_ & " DATABASE=test;"_ & "UID=venu;PWD=venu; OPTION=3" cn.CursorDriver = rdUseOdbc cn.EstablishConnection rdDriverPrompt 'drop table my_rdo SQL = "drop table if exists my_rdo" cn.Execute SQL, rdExecDirect 'create table my_rdo SQL = "create table my_rdo(id int, name varchar(20))" cn.Execute SQL, rdExecDirect 'insert - direct SQL = "insert into my_rdo values (100,'venu')" cn.Execute SQL, rdExecDirect SQL = "insert into my_rdo values (200,'MySQL')" cn.Execute SQL, rdExecDirect 'rs insert SQL = "select * from my_rdo" Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect) rs.AddNew rs!id = 300 rs!Name = "Insert1" rs.Update rs.Close 'rs insert SQL = "select * from my_rdo" Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect) rs.AddNew rs!id = 400 rs!Name = "Insert 2" rs.Update rs.Close 'rs update SQL = "select * from my_rdo" Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect) rs.Edit rs!id = 999 rs!Name = "updated" rs.Update rs.Close 'fetch back... SQL = "select * from my_rdo" Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect) Do Until rs.EOF For Each cl In rs.rdoColumns Debug.Print cl.Value, Next rs.MoveNext Debug.Print Loop Debug.Print "Row count="; rs.RowCount 'close rs.Close cn.Close End Sub  File: manual.info, Node: connector-odbc-examples-programming-net, Prev: connector-odbc-examples-programming-vb, Up: connector-odbc-examples-programming 21.1.5.15 Using Connector/ODBC with .NET ........................................ * Menu: * connector-odbc-examples-programming-net-csharp:: Using Connector/ODBC with ODBC.NET and C# (C sharp) * connector-odbc-examples-programming-net-vb:: Using Connector/ODBC with ODBC.NET and Visual Basic This section contains simple examples that demonstrate the use of Connector/ODBC drivers with ODBC.NET.  File: manual.info, Node: connector-odbc-examples-programming-net-csharp, Next: connector-odbc-examples-programming-net-vb, Prev: connector-odbc-examples-programming-net, Up: connector-odbc-examples-programming-net 21.1.5.16 Using Connector/ODBC with ODBC.NET and C# (C sharp) ............................................................. The following sample creates a table `my_odbc_net' and demonstrates its use in C#. /** * @sample : mycon.cs * @purpose : Demo sample for ODBC.NET using Connector/ODBC * @author : Venu, * * (C) Copyright MySQL AB, 1995-2006 * **/ /* build command * * csc /t:exe * /out:mycon.exe mycon.cs * /r:Microsoft.Data.Odbc.dll */ using Console = System.Console; using Microsoft.Data.Odbc; namespace myodbc3 { class mycon { static void Main(string[] args) { try { //Connection string for Connector/ODBC 3.51 string MyConString = "DRIVER={MySQL ODBC 3.51 Driver};" + "SERVER=localhost;" + "DATABASE=test;" + "UID=venu;" + "PASSWORD=venu;" + "OPTION=3"; //Connect to MySQL using Connector/ODBC OdbcConnection MyConnection = new OdbcConnection(MyConString); MyConnection.Open(); Console.WriteLine("\n !!! success, connected successfully !!!\n"); //Display connection information Console.WriteLine("Connection Information:"); Console.WriteLine("\tConnection String:" + MyConnection.ConnectionString); Console.WriteLine("\tConnection Timeout:" + MyConnection.ConnectionTimeout); Console.WriteLine("\tDatabase:" + MyConnection.Database); Console.WriteLine("\tDataSource:" + MyConnection.DataSource); Console.WriteLine("\tDriver:" + MyConnection.Driver); Console.WriteLine("\tServerVersion:" + MyConnection.ServerVersion); //Create a sample table OdbcCommand MyCommand = new OdbcCommand("DROP TABLE IF EXISTS my_odbc_net", MyConnection); MyCommand.ExecuteNonQuery(); MyCommand.CommandText = "CREATE TABLE my_odbc_net(id int, name varchar(20), idb bigint)"; MyCommand.ExecuteNonQuery(); //Insert MyCommand.CommandText = "INSERT INTO my_odbc_net VALUES(10,'venu', 300)"; Console.WriteLine("INSERT, Total rows affected:" + MyCommand.ExecuteNonQuery());; //Insert MyCommand.CommandText = "INSERT INTO my_odbc_net VALUES(20,'mysql',400)"; Console.WriteLine("INSERT, Total rows affected:" + MyCommand.ExecuteNonQuery()); //Insert MyCommand.CommandText = "INSERT INTO my_odbc_net VALUES(20,'mysql',500)"; Console.WriteLine("INSERT, Total rows affected:" + MyCommand.ExecuteNonQuery()); //Update MyCommand.CommandText = "UPDATE my_odbc_net SET id=999 WHERE id=20"; Console.WriteLine("Update, Total rows affected:" + MyCommand.ExecuteNonQuery()); //COUNT(*) MyCommand.CommandText = "SELECT COUNT(*) as TRows FROM my_odbc_net"; Console.WriteLine("Total Rows:" + MyCommand.ExecuteScalar()); //Fetch MyCommand.CommandText = "SELECT * FROM my_odbc_net"; OdbcDataReader MyDataReader; MyDataReader = MyCommand.ExecuteReader(); while (MyDataReader.Read()) { if(string.Compare(MyConnection.Driver,"myodbc3.dll") == 0) { //Supported only by Connector/ODBC 3.51 Console.WriteLine("Data:" + MyDataReader.GetInt32(0) + " " + MyDataReader.GetString(1) + " " + MyDataReader.GetInt64(2)); } else { //BIGINTs not supported by Connector/ODBC Console.WriteLine("Data:" + MyDataReader.GetInt32(0) + " " + MyDataReader.GetString(1) + " " + MyDataReader.GetInt32(2)); } } //Close all resources MyDataReader.Close(); MyConnection.Close(); } catch (OdbcException MyOdbcException) //Catch any ODBC exception .. { for (int i=0; i < MyOdbcException.Errors.Count; i++) { Console.Write("ERROR #" + i + "\n" + "Message: " + MyOdbcException.Errors[i].Message + "\n" + "Native: " + MyOdbcException.Errors[i].NativeError.ToString() + "\n" + "Source: " + MyOdbcException.Errors[i].Source + "\n" + "SQL: " + MyOdbcException.Errors[i].SQLState + "\n"); } } } } }  File: manual.info, Node: connector-odbc-examples-programming-net-vb, Prev: connector-odbc-examples-programming-net-csharp, Up: connector-odbc-examples-programming-net 21.1.5.17 Using Connector/ODBC with ODBC.NET and Visual Basic ............................................................. The following sample creates a table `my_vb_net' and demonstrates the use in VB. ' @sample : myvb.vb ' @purpose : Demo sample for ODBC.NET using Connector/ODBC ' @author : Venu, ' ' (C) Copyright MySQL AB, 1995-2006 ' ' ' ' build command ' ' vbc /target:exe ' /out:myvb.exe ' /r:Microsoft.Data.Odbc.dll ' /r:System.dll ' /r:System.Data.dll ' Imports Microsoft.Data.Odbc Imports System Module myvb Sub Main() Try 'Connector/ODBC 3.51 connection string Dim MyConString As String = "DRIVER={MySQL ODBC 3.51 Driver};" & _ "SERVER=localhost;" & _ "DATABASE=test;" & _ "UID=venu;" & _ "PASSWORD=venu;" & _ "OPTION=3;" 'Connection Dim MyConnection As New OdbcConnection(MyConString) MyConnection.Open() Console.WriteLine("Connection State::" & MyConnection.State.ToString) 'Drop Console.WriteLine("Dropping table") Dim MyCommand As New OdbcCommand() MyCommand.Connection = MyConnection MyCommand.CommandText = "DROP TABLE IF EXISTS my_vb_net" MyCommand.ExecuteNonQuery() 'Create Console.WriteLine("Creating....") MyCommand.CommandText = "CREATE TABLE my_vb_net(id int, name varchar(30))" MyCommand.ExecuteNonQuery() 'Insert MyCommand.CommandText = "INSERT INTO my_vb_net VALUES(10,'venu')" Console.WriteLine("INSERT, Total rows affected:" & _ MyCommand.ExecuteNonQuery()) 'Insert MyCommand.CommandText = "INSERT INTO my_vb_net VALUES(20,'mysql')" Console.WriteLine("INSERT, Total rows affected:" & _ MyCommand.ExecuteNonQuery()) 'Insert MyCommand.CommandText = "INSERT INTO my_vb_net VALUES(20,'mysql')" Console.WriteLine("INSERT, Total rows affected:" & _ MyCommand.ExecuteNonQuery()) 'Insert MyCommand.CommandText = "INSERT INTO my_vb_net(id) VALUES(30)" Console.WriteLine("INSERT, Total rows affected:" & _ MyCommand.ExecuteNonQuery()) 'Update MyCommand.CommandText = "UPDATE my_vb_net SET id=999 WHERE id=20" Console.WriteLine("Update, Total rows affected:" & _ MyCommand.ExecuteNonQuery()) 'COUNT(*) MyCommand.CommandText = "SELECT COUNT(*) as TRows FROM my_vb_net" Console.WriteLine("Total Rows:" & MyCommand.ExecuteScalar()) 'Select Console.WriteLine("Select * FROM my_vb_net") MyCommand.CommandText = "SELECT * FROM my_vb_net" Dim MyDataReader As OdbcDataReader MyDataReader = MyCommand.ExecuteReader While MyDataReader.Read If MyDataReader("name") Is DBNull.Value Then Console.WriteLine("id = " & _ CStr(MyDataReader("id")) & " name = " & _ "NULL") Else Console.WriteLine("id = " & _ CStr(MyDataReader("id")) & " name = " & _ CStr(MyDataReader("name"))) End If End While 'Catch ODBC Exception Catch MyOdbcException As OdbcException Dim i As Integer Console.WriteLine(MyOdbcException.ToString) 'Catch program exception Catch MyException As Exception Console.WriteLine(MyException.ToString) End Try End Sub  File: manual.info, Node: connector-odbc-reference, Next: connector-odbc-usagenotes, Prev: connector-odbc-examples, Up: connector-odbc 21.1.6 Connector/ODBC Reference ------------------------------- * Menu: * connector-odbc-reference-api:: Connector/ODBC API Reference * connector-odbc-reference-datatypes:: Connector/ODBC Data Types * connector-odbc-reference-errorcodes:: Connector/ODBC Error Codes This section provides reference material for the Connector/ODBC API, showing supported functions and methods, supported MySQL column types and the corresponding native type in Connector/ODBC, and the error codes returned by Connector/ODBC when a fault occurs.  File: manual.info, Node: connector-odbc-reference-api, Next: connector-odbc-reference-datatypes, Prev: connector-odbc-reference, Up: connector-odbc-reference 21.1.6.1 Connector/ODBC API Reference ..................................... This section summarizes ODBC routines, categorized by functionality. For the complete ODBC API reference, please refer to the ODBC Programmer's Reference at `http://msdn.microsoft.com/en-us/library/ms714177.aspx'. An application can call `SQLGetInfo' function to obtain conformance information about Connector/ODBC. To obtain information about support for a specific function in the driver, an application can call `SQLGetFunctions'. *Note*: For backward compatibility, the Connector/ODBC driver supports all deprecated functions. The following tables list Connector/ODBC API calls grouped by task: *ODBC API Calls for Connecting to a Data Source* Function Name Connector/ODBCStandard Purpose Supports? `SQLAllocHandle' Yes ISO 92 Obtains an environment, connection, statement, or descriptor handle. `SQLConnect' Yes ISO 92 Connects to a specific driver by data source name, user ID, and password. `SQLDriverConnect' Yes ODBC Connects to a specific driver by connection string or requests that the Driver Manager and driver display connection dialog boxes for the user. `SQLAllocEnv' Yes DeprecatedObtains an environment handle allocated from driver. `SQLAllocConnect' Yes DeprecatedObtains a connection handle *ODBC API Calls for Obtaining Information about a Driver and Data Source* Function Name Connector/ODBCStandard Purpose Supports? `SQLDataSources' No ISO 92 Returns the list of available data sources, handled by the Driver Manager `SQLDrivers' No ODBC Returns the list of installed drivers and their attributes, handles by Driver Manager `SQLGetInfo' Yes ISO 92 Returns information about a specific driver and data source. `SQLGetFunctions' Yes ISO 92 Returns supported driver functions. `SQLGetTypeInfo' Yes ISO 92 Returns information about supported data types. *ODBC API Calls for Setting and Retrieving Driver Attributes* Function Name Connector/ODBCStandard Purpose Supports? `SQLSetConnectAttr' Yes ISO 92 Sets a connection attribute. `SQLGetConnectAttr' Yes ISO 92 Returns the value of a connection attribute. `SQLSetConnectOption'Yes DeprecatedSets a connection option `SQLGetConnectOption'Yes DeprecatedReturns the value of a connection option `SQLSetEnvAttr' Yes ISO 92 Sets an environment attribute. `SQLGetEnvAttr' Yes ISO 92 Returns the value of an environment attribute. `SQLSetStmtAttr' Yes ISO 92 Sets a statement attribute. `SQLGetStmtAttr' Yes ISO 92 Returns the value of a statement attribute. `SQLSetStmtOption' Yes DeprecatedSets a statement option `SQLGetStmtOption' Yes DeprecatedReturns the value of a statement option *ODBC API Calls for Preparing SQL Requests* Function Name Connector/ODBCStandard Purpose Supports? `SQLAllocStmt' Yes DeprecatedAllocates a statement handle `SQLPrepare' Yes ISO 92 Prepares an SQL statement for later execution. `SQLBindParameter' Yes ODBC Assigns storage for a parameter in an SQL statement. Connector/ODBC 5.2 adds support for `out' and `inout' parameters, through the `SQL_PARAM_OUTPUT' or `SQL_PARAM_INPUT_OUTPUT' type specifiers. (`Out' and `inout' parameters are not supported for `LONGTEXT' and `LONGBLOB' columns.) `SQLGetCursorName' Yes ISO 92 Returns the cursor name associated with a statement handle. `SQLSetCursorName' Yes ISO 92 Specifies a cursor name. `SQLSetScrollOptions'Yes ODBC Sets options that control cursor behavior. *ODBC API Calls for Submitting Requests* Function Name Connector/ODBCStandard Purpose Supports? `SQLExecute' Yes ISO 92 Executes a prepared statement. `SQLExecDirect' Yes ISO 92 Executes a statement `SQLNativeSql' Yes ODBC Returns the text of an SQL statement as translated by the driver. `SQLDescribeParam' Yes ODBC Returns the description for a specific parameter in a statement. `SQLNumParams' Yes ISO 92 Returns the number of parameters in a statement. `SQLParamData' Yes ISO 92 Used in conjunction with `SQLPutData' to supply parameter data at execution time. (Useful for long data values.) `SQLPutData' Yes ISO 92 Sends part or all of a data value for a parameter. (Useful for long data values.) *ODBC API Calls for Retrieving Results and Information about Results* Function Name Connector/ODBCStandard Purpose Supports? `SQLRowCount' Yes ISO 92 Returns the number of rows affected by an insert, update, or delete request. `SQLNumResultCols' Yes ISO 92 Returns the number of columns in the result set. `SQLDescribeCol' Yes ISO 92 Describes a column in the result set. `SQLColAttribute' Yes ISO 92 Describes attributes of a column in the result set. `SQLColAttributes' Yes DeprecatedDescribes attributes of a column in the result set. `SQLFetch' Yes ISO 92 Returns multiple result rows. `SQLFetchScroll' Yes ISO 92 Returns scrollable result rows. `SQLExtendedFetch' Yes DeprecatedReturns scrollable result rows. `SQLSetPos' Yes ODBC Positions a cursor within a fetched block of data and enables an application to refresh data in the rowset or to update or delete data in the result set. `SQLBulkOperations' Yes ODBC Performs bulk insertions and bulk bookmark operations, including update, delete, and fetch by bookmark. *ODBC API Calls for Retrieving Error or Diagnostic Information* Function Name Connector/ODBCStandard Purpose Supports? `SQLError' Yes DeprecatedReturns additional error or status information `SQLGetDiagField' Yes ISO 92 Returns additional diagnostic information (a single field of the diagnostic data structure). `SQLGetDiagRec' Yes ISO 92 Returns additional diagnostic information (multiple fields of the diagnostic data structure). *ODBC API Calls for Obtaining Information about the Data Source's System Tables (Catalog Functions) Item* Function Name Connector/ODBCStandard Purpose Supports? `SQLColumnPrivileges'Yes ODBC Returns a list of columns and associated privileges for one or more tables. `SQLColumns' Yes X/Open Returns the list of column names in specified tables. `SQLForeignKeys' Yes ODBC Returns a list of column names that make up foreign keys, if they exist for a specified table. `SQLPrimaryKeys' Yes ODBC Returns the list of column names that make up the primary key for a table. `SQLSpecialColumns' Yes X/Open Returns information about the optimal set of columns that uniquely identifies a row in a specified table, or the columns that are automatically updated when any value in the row is updated by a transaction. `SQLStatistics' Yes ISO 92 Returns statistics about a single table and the list of indexes associated with the table. `SQLTablePrivileges'Yes ODBC Returns a list of tables and the privileges associated with each table. `SQLTables' Yes X/Open Returns the list of table names stored in a specific data source. *ODBC API Calls for Performing Transactions* Function Name Connector/ODBCStandard Purpose Supports? `SQLTransact' Yes DeprecatedCommits or rolls back a transaction `SQLEndTran' Yes ISO 92 Commits (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_commit) or rolls back (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_rollback) a transaction (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction). *ODBC API Calls for Terminating a Statement* Function Name Connector/ODBCStandard Purpose Supports? `SQLFreeStmt' Yes ISO 92 Ends statement processing, discards pending results, and, optionally, frees all resources associated with the statement handle. `SQLCloseCursor' Yes ISO 92 Closes a cursor that has been opened on a statement handle. `SQLCancel' Yes ISO 92 Cancels an SQL statement. *ODBC API Calls for Terminating a Connection* Function Name Connector/ODBCStandard Purpose Supports? `SQLDisconnect' Yes ISO 92 Closes the connection. `SQLFreeHandle' Yes ISO 92 Releases an environment, connection, statement, or descriptor handle. `SQLFreeConnect' Yes DeprecatedReleases connection handle. `SQLFreeEnv' Yes DeprecatedReleases an environment handle.  File: manual.info, Node: connector-odbc-reference-datatypes, Next: connector-odbc-reference-errorcodes, Prev: connector-odbc-reference-api, Up: connector-odbc-reference 21.1.6.2 Connector/ODBC Data Types .................................. The following table illustrates how Connector/ODBC maps the server data types to default SQL and C data types. *How Connector/ODBC Maps MySQL Data Types to SQL and C Data Types* Native Value SQL Type C Type `bigint unsigned' `SQL_BIGINT' `SQL_C_UBIGINT' `bigint' `SQL_BIGINT' `SQL_C_SBIGINT' `bit' `SQL_BIT' `SQL_C_BIT' `bit' `SQL_CHAR' `SQL_C_CHAR' `blob' `SQL_LONGVARBINARY' `SQL_C_BINARY' `bool' `SQL_CHAR' `SQL_C_CHAR' `char' `SQL_CHAR' `SQL_C_CHAR' `date' `SQL_DATE' `SQL_C_DATE' `datetime' `SQL_TIMESTAMP' `SQL_C_TIMESTAMP' `decimal' `SQL_DECIMAL' `SQL_C_CHAR' `double precision' `SQL_DOUBLE' `SQL_C_DOUBLE' `double' `SQL_FLOAT' `SQL_C_DOUBLE' `enum' `SQL_VARCHAR' `SQL_C_CHAR' `float' `SQL_REAL' `SQL_C_FLOAT' `int unsigned' `SQL_INTEGER' `SQL_C_ULONG' `int' `SQL_INTEGER' `SQL_C_SLONG' `integer unsigned' `SQL_INTEGER' `SQL_C_ULONG' `integer' `SQL_INTEGER' `SQL_C_SLONG' `long varbinary' `SQL_LONGVARBINARY' `SQL_C_BINARY' `long varchar' `SQL_LONGVARCHAR' `SQL_C_CHAR' `longblob' `SQL_LONGVARBINARY' `SQL_C_BINARY' `longtext' `SQL_LONGVARCHAR' `SQL_C_CHAR' `mediumblob' `SQL_LONGVARBINARY' `SQL_C_BINARY' `mediumint unsigned' `SQL_INTEGER' `SQL_C_ULONG' `mediumint' `SQL_INTEGER' `SQL_C_SLONG' `mediumtext' `SQL_LONGVARCHAR' `SQL_C_CHAR' `numeric' `SQL_NUMERIC' `SQL_C_CHAR' `real' `SQL_FLOAT' `SQL_C_DOUBLE' `set' `SQL_VARCHAR' `SQL_C_CHAR' `smallint unsigned' `SQL_SMALLINT' `SQL_C_USHORT' `smallint' `SQL_SMALLINT' `SQL_C_SSHORT' `text' `SQL_LONGVARCHAR' `SQL_C_CHAR' `time' `SQL_TIME' `SQL_C_TIME' `timestamp' `SQL_TIMESTAMP' `SQL_C_TIMESTAMP' `tinyblob' `SQL_LONGVARBINARY' `SQL_C_BINARY' `tinyint unsigned' `SQL_TINYINT' `SQL_C_UTINYINT' `tinyint' `SQL_TINYINT' `SQL_C_STINYINT' `tinytext' `SQL_LONGVARCHAR' `SQL_C_CHAR' `varchar' `SQL_VARCHAR' `SQL_C_CHAR' `year' `SQL_SMALLINT' `SQL_C_SHORT'  File: manual.info, Node: connector-odbc-reference-errorcodes, Prev: connector-odbc-reference-datatypes, Up: connector-odbc-reference 21.1.6.3 Connector/ODBC Error Codes ................................... The following tables lists the error codes returned by Connector/ODBC apart from the server errors. *Special Error Codes Returned by Connector/ODBC* Native SQLSTATE 2 SQLSTATE 3 Error Message Code 500 01000 01000 General warning 501 01004 01004 String data, right truncated 502 01S02 01S02 Option value changed 503 01S03 01S03 No rows updated/deleted 504 01S04 01S04 More than one row updated/deleted 505 01S06 01S06 Attempt to fetch before the result set returned the first row set 506 07001 07002 `SQLBindParameter' not used for all parameters 507 07005 07005 Prepared statement not a cursor-specification 508 07009 07009 Invalid descriptor index 509 08002 08002 Connection name in use 510 08003 08003 Connection does not exist 511 24000 24000 Invalid cursor state 512 25000 25000 Invalid transaction state 513 25S01 25S01 Transaction state unknown 514 34000 34000 Invalid cursor name 515 S1000 HY000 General driver defined error 516 S1001 HY001 Memory allocation error 517 S1002 HY002 Invalid column number 518 S1003 HY003 Invalid application buffer type 519 S1004 HY004 Invalid SQL data type 520 S1009 HY009 Invalid use of null pointer 521 S1010 HY010 Function sequence error 522 S1011 HY011 Attribute can not be set now 523 S1012 HY012 Invalid transaction operation code 524 S1013 HY013 Memory management error 525 S1015 HY015 No cursor name available 526 S1024 HY024 Invalid attribute value 527 S1090 HY090 Invalid string or buffer length 528 S1091 HY091 Invalid descriptor field identifier 529 S1092 HY092 Invalid attribute/option identifier 530 S1093 HY093 Invalid parameter number 531 S1095 HY095 Function type out of range 532 S1106 HY106 Fetch type out of range 533 S1117 HY117 Row value out of range 534 S1109 HY109 Invalid cursor position 535 S1C00 HYC00 Optional feature not implemented 0 21S01 21S01 Column count does not match value count 0 23000 23000 Integrity constraint violation 0 42000 42000 Syntax error or access violation 0 42S02 42S02 Base table or view not found 0 42S12 42S12 Index not found 0 42S21 42S21 Column already exists 0 42S22 42S22 Column not found 0 08S01 08S01 Communication link failure  File: manual.info, Node: connector-odbc-usagenotes, Next: connector-odbc-support, Prev: connector-odbc-reference, Up: connector-odbc 21.1.7 Connector/ODBC Notes and Tips ------------------------------------ * Menu: * connector-odbc-usagenotes-functionality:: Connector/ODBC General Functionality * connector-odbc-usagenotes-apptips:: Connector/ODBC Application-Specific Tips * connector-odbc-errors:: Connector/ODBC Errors and Resolutions (FAQ) Here are some common notes and tips for using Connector/ODBC within different environments, applications and tools. The notes provided here are based on the experiences of Connector/ODBC developers and users.  File: manual.info, Node: connector-odbc-usagenotes-functionality, Next: connector-odbc-usagenotes-apptips, Prev: connector-odbc-usagenotes, Up: connector-odbc-usagenotes 21.1.7.1 Connector/ODBC General Functionality ............................................. * Menu: * connector-odbc-usagenotes-functionality-last-insert-id:: Obtaining Auto-Increment Values * connector-odbc-usagenotes-functionality-dynamic-cursor:: Dynamic Cursor Support * connector-odbc-usagenotes-functionality-performance:: Connector/ODBC Performance * connector-odbc-usagenotes-functionality-query-timeout:: Setting ODBC Query Timeout in Windows This section provides help with common queries and areas of functionality in MySQL and how to use them with Connector/ODBC.  File: manual.info, Node: connector-odbc-usagenotes-functionality-last-insert-id, Next: connector-odbc-usagenotes-functionality-dynamic-cursor, Prev: connector-odbc-usagenotes-functionality, Up: connector-odbc-usagenotes-functionality 21.1.7.2 Obtaining Auto-Increment Values ........................................ Obtaining the value of column that uses `AUTO_INCREMENT' after an *Note `INSERT': insert. statement can be achieved in a number of different ways. To obtain the value immediately after an *Note `INSERT': insert, use a *Note `SELECT': select. query with the `LAST_INSERT_ID()' function. For example, using Connector/ODBC you would execute two separate statements, the *Note `INSERT': insert. statement and the *Note `SELECT': select. query to obtain the auto-increment value. INSERT INTO tbl (auto,text) VALUES(NULL,'text'); SELECT LAST_INSERT_ID(); If you do not require the value within your application, but do require the value as part of another *Note `INSERT': insert, the entire process can be handled by executing the following statements: INSERT INTO tbl (auto,text) VALUES(NULL,'text'); INSERT INTO tbl2 (id,text) VALUES(LAST_INSERT_ID(),'text'); Certain ODBC applications (including Delphi and Access) may have trouble obtaining the auto-increment value using the previous examples. In this case, try the following statement as an alternative: SELECT * FROM tbl WHERE auto IS NULL; This alternative method requires that `sql_auto_is_null' variable is not set to 0. See *Note server-system-variables::. See also *Note getting-unique-id::.  File: manual.info, Node: connector-odbc-usagenotes-functionality-dynamic-cursor, Next: connector-odbc-usagenotes-functionality-performance, Prev: connector-odbc-usagenotes-functionality-last-insert-id, Up: connector-odbc-usagenotes-functionality 21.1.7.3 Dynamic Cursor Support ............................... Support for the `dynamic cursor' is provided in Connector/ODBC 3.51, but dynamic cursors are not enabled by default. You can enable this function within Windows by selecting the `Enable Dynamic Cursor' check box within the ODBC Data Source Administrator. On other platforms, you can enable the dynamic cursor by adding `32' to the `OPTION' value when creating the DSN.  File: manual.info, Node: connector-odbc-usagenotes-functionality-performance, Next: connector-odbc-usagenotes-functionality-query-timeout, Prev: connector-odbc-usagenotes-functionality-dynamic-cursor, Up: connector-odbc-usagenotes-functionality 21.1.7.4 Connector/ODBC Performance ................................... The Connector/ODBC driver has been optimized to provide very fast performance. If you experience problems with the performance of Connector/ODBC, or notice a large amount of disk activity for simple queries, there are a number of aspects to check: * Ensure that `ODBC Tracing' is not enabled. With tracing enabled, a lot of information is recorded in the tracing file by the ODBC Manager. You can check, and disable, tracing within Windows using the `Tracing' panel of the ODBC Data Source Administrator. Within Mac OS X, check the `Tracing' panel of ODBC Administrator. See *Note connector-odbc-configuration-trace::. * Make sure you are using the standard version of the driver, and not the debug version. The debug version includes additional checks and reporting measures. * Disable the Connector/ODBC driver trace and query logs. These options are enabled for each DSN, so make sure to examine only the DSN that you are using in your application. Within Windows, you can disable the Connector/ODBC and query logs by modifying the DSN configuration. Within Mac OS X and Unix, ensure that the driver trace (option value 4) and query logging (option value 524288) are not enabled.  File: manual.info, Node: connector-odbc-usagenotes-functionality-query-timeout, Prev: connector-odbc-usagenotes-functionality-performance, Up: connector-odbc-usagenotes-functionality 21.1.7.5 Setting ODBC Query Timeout in Windows .............................................. For more information on how to set the query timeout on Microsoft Windows when executing queries through an ODBC connection, read the Microsoft knowledgebase document at `http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B153756'.  File: manual.info, Node: connector-odbc-usagenotes-apptips, Next: connector-odbc-errors, Prev: connector-odbc-usagenotes-functionality, Up: connector-odbc-usagenotes 21.1.7.6 Connector/ODBC Application-Specific Tips ................................................. * Menu: * connector-odbc-usagenotes-apptips-microsoft:: Using Connector/ODBC with Microsoft Applications * connector-odbc-usagenotes-apptips-borland:: Using Connector/ODBC with Borland Applications * connector-odbc-usagenotes-apptips-coldfusion:: Using Connector/ODBC with ColdFusion * connector-odbc-usagenotes-apptips-openoffice:: Using Connector/ODBC with OpenOffice.org * connector-odbc-usagenotes-apptips-sambarserver:: Using Connector/ODBC with Sambar Server * connector-odbc-usagenotes-apptips-datajunction:: Using Connector/ODBC with Pervasive Software DataJunction * connector-odbc-usagenotes-apptips-vision:: Using Connector/ODBC with SunSystems Vision Most programs should work with Connector/ODBC, but for each of those listed here, there are specific notes and tips to improve or enhance the way you work with Connector/ODBC and these applications. With all applications, ensure that you are using the latest Connector/ODBC drivers, ODBC Manager and any supporting libraries and interfaces used by your application. For example, on Windows, using the latest version of Microsoft Data Access Components (MDAC) will improve the compatibility with ODBC in general, and with the Connector/ODBC driver.  File: manual.info, Node: connector-odbc-usagenotes-apptips-microsoft, Next: connector-odbc-usagenotes-apptips-borland, Prev: connector-odbc-usagenotes-apptips, Up: connector-odbc-usagenotes-apptips 21.1.7.7 Using Connector/ODBC with Microsoft Applications ......................................................... * Menu: * connector-odbc-usagenotes-apptips-microsoft-access:: Microsoft Access * connector-odbc-usagenotes-apptips-microsoft-excel:: Microsoft Excel and Column Types * connector-odbc-usagenotes-apptips-microsoft-visualbasic:: Microsoft Visual Basic * connector-odbc-usagenotes-apptips-microsoft-visualinterdev:: Microsoft Visual InterDev * connector-odbc-usagenotes-apptips-microsoft-visualobjects:: Visual Objects * connector-odbc-usagenotes-apptips-microsoft-ado:: Microsoft ADO * connector-odbc-usagenotes-apptips-microsoft-asp:: Using Connector/ODBC with Active Server Pages (ASP) * connector-odbc-usagenotes-apptips-microsoft-vb-asp:: Using Connector/ODBC with Visual Basic (ADO, DAO and RDO) and ASP The majority of Microsoft applications have been tested with Connector/ODBC, including Microsoft Office, Microsoft Access and the various programming languages supported within ASP and Microsoft Visual Studio.  File: manual.info, Node: connector-odbc-usagenotes-apptips-microsoft-access, Next: connector-odbc-usagenotes-apptips-microsoft-excel, Prev: connector-odbc-usagenotes-apptips-microsoft, Up: connector-odbc-usagenotes-apptips-microsoft 21.1.7.8 Microsoft Access ......................... To improve the integration between Microsoft Access and MySQL through Connector/ODBC: * For all versions of Access, enable the Connector/ODBC `Return matching rows' option. For Access 2.0, also enable the `Simulate ODBC 1.0' option. * Include a *Note `TIMESTAMP': datetime. column in all tables that you want to be able to update. For maximum portability, do not use a length specification in the column declaration (which is unsupported within MySQL in versions earlier than 4.1). * Include a primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key) in each MySQL table you want to use with Access. If not, new or updated rows may show up as `#DELETED#'. * Use only *Note `DOUBLE': floating-point-types. float fields. Access fails when comparing with single-precision floats. The symptom usually is that new or updated rows may show up as `#DELETED#' or that you cannot find or update rows. * If you are using Connector/ODBC to link to a table that has a *Note `BIGINT': integer-types. column, the results are displayed as `#DELETED#'. The work around solution is: * Have one more dummy column with *Note `TIMESTAMP': datetime. as the data type. * Select the `Change BIGINT columns to INT' option in the connection dialog in ODBC DSN Administrator. * Delete the table link from Access and re-create it. Old records may still display as `#DELETED#', but newly added/updated records are displayed properly. * If you still get the error `Another user has changed your data' after adding a *Note `TIMESTAMP': datetime. column, the following trick may help you: Do not use a `table' data sheet view. Instead, create a form with the fields you want, and use that `form' data sheet view. Set the `DefaultValue' property for the *Note `TIMESTAMP': datetime. column to `NOW()'. Consider hiding the *Note `TIMESTAMP': datetime. column from view so your users are not confused. * In some cases, Access may generate SQL statements that MySQL cannot understand. You can fix this by selecting `"Query|SQLSpecific|Pass-Through"' from the Access menu. * On Windows NT, Access reports *Note `BLOB': blob. columns as `OLE OBJECTS'. If you want to have `MEMO' columns instead, change *Note `BLOB': blob. columns to *Note `TEXT': blob. with *Note `ALTER TABLE': alter-table. * Access cannot always handle the MySQL *Note `DATE': datetime. column properly. If you have a problem with these, change the columns to *Note `DATETIME': datetime. * If you have in Access a column defined as `BYTE', Access tries to export this as *Note `TINYINT': integer-types. instead of `TINYINT UNSIGNED'. This gives you problems if you have values larger than 127 in the column. * If you have very large (long) tables in Access, it might take a very long time to open them. Or you might run low on virtual memory and eventually get an `ODBC Query Failed' error and the table cannot open. To deal with this, select the following options: * Return Matching Rows (2) * Allow BIG Results (8). These add up to a value of 10 (`OPTION=10'). Some external articles and tips that may be useful when using Access, ODBC and Connector/ODBC: * Read How to Trap ODBC Login Error Messages in Access (http://support.microsoft.com/support/kb/articles/Q124/9/01.asp?LN=EN-US&SD=gn&FR=0%3CP%3E) * Optimizing Access ODBC Applications * Optimizing for Client/Server Performance (http://support.microsoft.com/default.aspx?scid=kb;en-us;128808) * Tips for Converting Applications to Using ODBCDirect (http://support.microsoft.com/default.aspx?scid=kb;en-us;164481) * Tips for Optimizing Queries on Attached SQL Tables (http://support.microsoft.com/default.aspx?scid=kb;EN-US;q99321) * For a list of tools that can be used with Access and ODBC data sources, refer to http://www.mysql.com/portal/software/convertors/ section for list of available tools.  File: manual.info, Node: connector-odbc-usagenotes-apptips-microsoft-excel, Next: connector-odbc-usagenotes-apptips-microsoft-visualbasic, Prev: connector-odbc-usagenotes-apptips-microsoft-access, Up: connector-odbc-usagenotes-apptips-microsoft 21.1.7.9 Microsoft Excel and Column Types ......................................... If you have problems importing data into Microsoft Excel, particularly numeric, date, and time values, this is probably because of a bug in Excel, where the column type of the source data is used to determine the data type when that data is inserted into a cell within the worksheet. The result is that Excel incorrectly identifies the content and this affects both the display format and the data when it is used within calculations. To address this issue, use the `CONCAT()' function in your queries. The use of `CONCAT()' forces Excel to treat the value as a string, which Excel will then parse and usually correctly identify the embedded information. However, even with this option, some data may be incorrectly formatted, even though the source data remains unchanged. Use the `Format Cells' option within Excel to change the format of the displayed information.  File: manual.info, Node: connector-odbc-usagenotes-apptips-microsoft-visualbasic, Next: connector-odbc-usagenotes-apptips-microsoft-visualinterdev, Prev: connector-odbc-usagenotes-apptips-microsoft-excel, Up: connector-odbc-usagenotes-apptips-microsoft 21.1.7.10 Microsoft Visual Basic ................................ To be able to update a table, you must define a primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key) for the table. Visual Basic with ADO cannot handle big integers. This means that some queries like *Note `SHOW PROCESSLIST': show-processlist. do not work properly. The fix is to use `OPTION=16384' in the ODBC connect string or to select the `Change BIGINT columns to INT' option in the Connector/ODBC connect screen. You may also want to select the `Return matching rows' option.  File: manual.info, Node: connector-odbc-usagenotes-apptips-microsoft-visualinterdev, Next: connector-odbc-usagenotes-apptips-microsoft-visualobjects, Prev: connector-odbc-usagenotes-apptips-microsoft-visualbasic, Up: connector-odbc-usagenotes-apptips-microsoft 21.1.7.11 Microsoft Visual InterDev ................................... If you have a *Note `BIGINT': integer-types. in your result, you may get the error `[Microsoft][ODBC Driver Manager] Driver does not support this parameter'. Try selecting the `Change BIGINT columns to INT' option in the Connector/ODBC connect screen.  File: manual.info, Node: connector-odbc-usagenotes-apptips-microsoft-visualobjects, Next: connector-odbc-usagenotes-apptips-microsoft-ado, Prev: connector-odbc-usagenotes-apptips-microsoft-visualinterdev, Up: connector-odbc-usagenotes-apptips-microsoft 21.1.7.12 Visual Objects ........................ Select the `Don't optimize column widths' option.  File: manual.info, Node: connector-odbc-usagenotes-apptips-microsoft-ado, Next: connector-odbc-usagenotes-apptips-microsoft-asp, Prev: connector-odbc-usagenotes-apptips-microsoft-visualobjects, Up: connector-odbc-usagenotes-apptips-microsoft 21.1.7.13 Microsoft ADO ....................... When you are coding with the ADO API and Connector/ODBC, you need to pay attention to some default properties that aren't supported by the MySQL server. For example, using the `CursorLocation Property' as `adUseServer' returns a result of -1 for the `RecordCount Property'. To have the right value, you need to set this property to `adUseClient', as shown in the VB code here: Dim myconn As New ADODB.Connection Dim myrs As New Recordset Dim mySQL As String Dim myrows As Long myconn.Open "DSN=MyODBCsample" mySQL = "SELECT * from user" myrs.Source = mySQL Set myrs.ActiveConnection = myconn myrs.CursorLocation = adUseClient myrs.Open myrows = myrs.RecordCount myrs.Close myconn.Close Another workaround is to use a `SELECT COUNT(*)' statement for a similar query to get the correct row count. To find the number of rows affected by a specific SQL statement in ADO, use the `RecordsAffected' property in the ADO execute method. For more information on the usage of execute method, refer to `http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ado270/htm/mdmthcnnexecute.asp'. For information, see ActiveX Data Objects(ADO) Frequently Asked Questions (http://support.microsoft.com/default.aspx?scid=kb;EN-US;q183606).  File: manual.info, Node: connector-odbc-usagenotes-apptips-microsoft-asp, Next: connector-odbc-usagenotes-apptips-microsoft-vb-asp, Prev: connector-odbc-usagenotes-apptips-microsoft-ado, Up: connector-odbc-usagenotes-apptips-microsoft 21.1.7.14 Using Connector/ODBC with Active Server Pages (ASP) ............................................................. Select the `Return matching rows' option in the DSN. For more information about how to access MySQL through ASP using Connector/ODBC, refer to the following articles: * Using MyODBC To Access Your MySQL Database Via ASP (http://www.devarticles.com/c/a/ASP/Using-MyODBC-To-Access-Your-MySQL-Database-Via-ASP/) * ASP and MySQL at DWAM.NT (http://www.dwam.net/mysql/asp_myodbc.asp) A Frequently Asked Questions list for ASP can be found at `http://support.microsoft.com/default.aspx?scid=/Support/ActiveServer/faq/data/adofaq.asp'.  File: manual.info, Node: connector-odbc-usagenotes-apptips-microsoft-vb-asp, Prev: connector-odbc-usagenotes-apptips-microsoft-asp, Up: connector-odbc-usagenotes-apptips-microsoft 21.1.7.15 Using Connector/ODBC with Visual Basic (ADO, DAO and RDO) and ASP ........................................................................... Some articles that may help with Visual Basic and ASP: * MySQL BLOB columns and Visual Basic 6 (http://dev.mysql.com/tech-resources/articles/vb-blob-handling.html) by Mike Hillyer (). * How to map Visual basic data type to MySQL types (http://dev.mysql.com/tech-resources/articles/visual-basic-datatypes.html) by Mike Hillyer ().  File: manual.info, Node: connector-odbc-usagenotes-apptips-borland, Next: connector-odbc-usagenotes-apptips-coldfusion, Prev: connector-odbc-usagenotes-apptips-microsoft, Up: connector-odbc-usagenotes-apptips 21.1.7.16 Using Connector/ODBC with Borland Applications ........................................................ * Menu: * connector-odbc-usagenotes-apptips-borland-builder:: Using Connector/ODBC with Borland Builder 4 * connector-odbc-usagenotes-apptips-borland-delphi:: Using Connector/ODBC with Delphi * connector-odbc-usagenotes-apptips-borland-cppbuilder:: Using Connector/ODBC with C++ Builder With all Borland applications where the Borland Database Engine (BDE) is used, follow these steps to improve compatibility: * Update to BDE 3.2 or newer. * Enable the `Don't optimize column widths' option in the DSN. * Enabled the `Return matching rows' option in the DSN.  File: manual.info, Node: connector-odbc-usagenotes-apptips-borland-builder, Next: connector-odbc-usagenotes-apptips-borland-delphi, Prev: connector-odbc-usagenotes-apptips-borland, Up: connector-odbc-usagenotes-apptips-borland 21.1.7.17 Using Connector/ODBC with Borland Builder 4 ..................................................... When you start a query, you can use the `Active' property or the `Open' method. Note that `Active' starts by automatically issuing a `SELECT * FROM ...' query. That may not be a good thing if your tables are large.  File: manual.info, Node: connector-odbc-usagenotes-apptips-borland-delphi, Next: connector-odbc-usagenotes-apptips-borland-cppbuilder, Prev: connector-odbc-usagenotes-apptips-borland-builder, Up: connector-odbc-usagenotes-apptips-borland 21.1.7.18 Using Connector/ODBC with Delphi .......................................... Also, here is some potentially useful Delphi code that sets up both an ODBC entry and a BDE entry for Connector/ODBC. The BDE entry requires a BDE Alias Editor that is free at a Delphi Super Page near you. (Thanks to Bryan Brunton for this): fReg:= TRegistry.Create; fReg.OpenKey('\Software\ODBC\ODBC.INI\DocumentsFab', True); fReg.WriteString('Database', 'Documents'); fReg.WriteString('Description', ' '); fReg.WriteString('Driver', 'C:\WINNT\System32\myodbc.dll'); fReg.WriteString('Flag', '1'); fReg.WriteString('Password', ''); fReg.WriteString('Port', ' '); fReg.WriteString('Server', 'xmark'); fReg.WriteString('User', 'winuser'); fReg.OpenKey('\Software\ODBC\ODBC.INI\ODBC Data Sources', True); fReg.WriteString('DocumentsFab', 'MySQL'); fReg.CloseKey; fReg.Free; Memo1.Lines.Add('DATABASE NAME='); Memo1.Lines.Add('USER NAME='); Memo1.Lines.Add('ODBC DSN=DocumentsFab'); Memo1.Lines.Add('OPEN MODE=READ/WRITE'); Memo1.Lines.Add('BATCH COUNT=200'); Memo1.Lines.Add('LANGDRIVER='); Memo1.Lines.Add('MAX ROWS=-1'); Memo1.Lines.Add('SCHEMA CACHE DIR='); Memo1.Lines.Add('SCHEMA CACHE SIZE=8'); Memo1.Lines.Add('SCHEMA CACHE TIME=-1'); Memo1.Lines.Add('SQLPASSTHRU MODE=SHARED AUTOCOMMIT'); Memo1.Lines.Add('SQLQRYMODE='); Memo1.Lines.Add('ENABLE SCHEMA CACHE=FALSE'); Memo1.Lines.Add('ENABLE BCD=FALSE'); Memo1.Lines.Add('ROWSET SIZE=20'); Memo1.Lines.Add('BLOBS TO CACHE=64'); Memo1.Lines.Add('BLOB SIZE=32'); AliasEditor.Add('DocumentsFab','MySQL',Memo1.Lines);  File: manual.info, Node: connector-odbc-usagenotes-apptips-borland-cppbuilder, Prev: connector-odbc-usagenotes-apptips-borland-delphi, Up: connector-odbc-usagenotes-apptips-borland 21.1.7.19 Using Connector/ODBC with C++ Builder ............................................... Tested with BDE 3.0. The only known problem is that when the table schema changes, query fields are not updated. BDE, however, does not seem to recognize primary keys, only the index named `PRIMARY', although this has not been a problem.  File: manual.info, Node: connector-odbc-usagenotes-apptips-coldfusion, Next: connector-odbc-usagenotes-apptips-openoffice, Prev: connector-odbc-usagenotes-apptips-borland, Up: connector-odbc-usagenotes-apptips 21.1.7.20 Using Connector/ODBC with ColdFusion .............................................. The following information is taken from the ColdFusion documentation: Use the following information to configure ColdFusion Server for Linux to use the `unixODBC' driver with Connector/ODBC for MySQL data sources. You can download Connector/ODBC at `http://dev.mysql.com/downloads/connector/odbc/'. ColdFusion version 4.5.1 lets you use the ColdFusion Administrator to add the MySQL data source. However, the driver is not included with ColdFusion version 4.5.1. Before the MySQL driver appears in the ODBC data sources drop-down list, build and copy the Connector/ODBC driver to `/opt/coldfusion/lib/libmyodbc.so'. The Contrib directory contains the program `mydsn-XXX.zip' which lets you build and remove the DSN registry file for the Connector/ODBC driver on ColdFusion applications. For more information and guides on using ColdFusion and Connector/ODBC, see the following external sites: * Troubleshooting Data Sources and Database Connectivity for Unix Platforms (http://www.macromedia.com/v1/handlers/index.cfm?ID=11328&Method=Full&PageCall=/support/index.cfm).  File: manual.info, Node: connector-odbc-usagenotes-apptips-openoffice, Next: connector-odbc-usagenotes-apptips-sambarserver, Prev: connector-odbc-usagenotes-apptips-coldfusion, Up: connector-odbc-usagenotes-apptips 21.1.7.21 Using Connector/ODBC with OpenOffice.org .................................................. Open Office (`http://www.openoffice.org') How-to: MySQL + OpenOffice (http://wiki.services.openoffice.org/wiki/Connect_MySQL_and_Base). How-to: OpenOffice + MyODBC + unixODBC (http://www.unixodbc.org/doc/OOoMySQL.pdf).  File: manual.info, Node: connector-odbc-usagenotes-apptips-sambarserver, Next: connector-odbc-usagenotes-apptips-datajunction, Prev: connector-odbc-usagenotes-apptips-openoffice, Up: connector-odbc-usagenotes-apptips 21.1.7.22 Using Connector/ODBC with Sambar Server ................................................. Sambar Server (`http://www.sambarserver.info') How-to: MyODBC + SambarServer + MySQL (http://www.sambarserver.info/article.php?sid=66).  File: manual.info, Node: connector-odbc-usagenotes-apptips-datajunction, Next: connector-odbc-usagenotes-apptips-vision, Prev: connector-odbc-usagenotes-apptips-sambarserver, Up: connector-odbc-usagenotes-apptips 21.1.7.23 Using Connector/ODBC with Pervasive Software DataJunction ................................................................... You have to change it to output *Note `VARCHAR': char. rather than *Note `ENUM': enum, as it exports the latter in a manner that causes MySQL problems.  File: manual.info, Node: connector-odbc-usagenotes-apptips-vision, Prev: connector-odbc-usagenotes-apptips-datajunction, Up: connector-odbc-usagenotes-apptips 21.1.7.24 Using Connector/ODBC with SunSystems Vision ..................................................... Select the `Return matching rows' option.  File: manual.info, Node: connector-odbc-errors, Prev: connector-odbc-usagenotes-apptips, Up: connector-odbc-usagenotes 21.1.7.25 Connector/ODBC Errors and Resolutions (FAQ) ..................................................... The following section details some common errors and their suggested fix or alternative solution. If you are still experiencing problems, use the Connector/ODBC mailing list; see *Note connector-odbc-support-community::. Many problems can be resolved by upgrading your Connector/ODBC drivers to the latest available release. On Windows, make sure that you have the latest versions of the Microsoft Data Access Components (MDAC) installed. * 64-Bit Windows and ODBC Data Source Administrator * I have installed Connector/ODBC on Windows XP x64 Edition or Windows Server 2003 R2 x64. The installation completed successfully, but the Connector/ODBC driver does not appear in `ODBC Data Source Administrator'. This is not a bug, but is related to the way Windows x64 editions operate with the ODBC driver. On Windows x64 editions, the Connector/ODBC driver is installed in the `%SystemRoot%\SysWOW64' folder. However, the default `ODBC Data Source Administrator' that is available through the `Administrative Tools' or `Control Panel' in Windows x64 Editions is located in the `%SystemRoot%\system32' folder, and only searches this folder for ODBC drivers. On Windows x64 editions, use the ODBC administration tool located at `%SystemRoot%\SysWOW64\odbcad32.exe', this will correctly locate the installed Connector/ODBC drivers and enable you to create a Connector/ODBC DSN. This issue was originally reported as Bug #20301. * Error 10061 (Cannot connect to server) * When connecting or using the `Test' button in `ODBC Data Source Administrator' I get error 10061 (Cannot connect to server) This error can be raised by a number of different issues, including server problems, network problems, and firewall and port blocking problems. For more information, see *Note can-not-connect-to-server::. * "Transactions are not enabled" Error * The following error is reported when using transactions: `Transactions are not enabled' This error indicates that you are trying to use transactions (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction) with a MySQL table that does not support transactions. Transactions are supported within MySQL when using the *Note `InnoDB': innodb-storage-engine. database engine, which is the default storage engine in MySQL 5.5 and higher. In versions of MySQL before MySQL 5.1, you may also use the `BDB' engine. Check the following before continuing: * Verify that your MySQL server supports a transactional database engine. Use *Note `SHOW ENGINES': show-engines. to obtain a list of the available engine types. * Verify that the tables you are updating use a transactional database engine. * Ensure that you have not enabled the `disable transactions' option in your DSN. * #DELETED# Records Reported by Access * Access reports records as `#DELETED#' when inserting or updating records in linked tables. If the inserted or updated records are shown as `#DELETED#' in Access, then: * If you are using Access 2000, get and install the newest (version 2.6 or higher) Microsoft MDAC (`Microsoft Data Access Components') from `http://support.microsoft.com/kb/110093'. This fixes a bug in Access that when you export data to MySQL, the table and column names aren't specified. Also, get and apply the Microsoft Jet 4.0 Service Pack 5 (SP5), which can be found at `http://support.microsoft.com/default.aspx?scid=kb;EN-US;q239114'. This fixes some cases where columns are marked as `#DELETED#' in Access. * For all versions of Access, enable the Connector/ODBC `Return matching rows' option. For Access 2.0, also enable the `Simulate ODBC 1.0' option. * Include a `TIMESTAMP' in all tables that you want to be able to update. * Include a primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key) in the table. If not, new or updated rows may show up as `#DELETED#'. * Use only *Note `DOUBLE': floating-point-types. float fields. Access fails when comparing with single-precision floats. The symptom usually is that new or updated rows may show up as `#DELETED#' or that you cannot find or update rows. * If you are using Connector/ODBC to link to a table that has a *Note `BIGINT': integer-types. column, the results are displayed as `#DELETED'. The work around solution is: * Have one more dummy column with *Note `TIMESTAMP': datetime. as the data type. * Select the `Change BIGINT columns to INT' option in the connection dialog in ODBC DSN Administrator. * Delete the table link from Access and re-create it. Old records still display as `#DELETED#', but newly added/updated records are displayed properly. * Write Conflicts or Row Location Errors * How do I handle Write Conflicts or Row Location errors? If you see the following errors, select the `Return Matching Rows' option in the DSN configuration dialog, or specify `OPTION=2', as the connection parameter: Write Conflict. Another user has changed your data. Row cannot be located for updating. Some values may have been changed since it was last read. * Importing from Access 97 * Exporting data from Access 97 to MySQL reports a `Syntax Error'. This error is specific to Access 97 and versions of Connector/ODBC earlier than 3.51.02. Update to the latest version of the Connector/ODBC driver to resolve this problem. * Importing from Microsoft DTS * Exporting data from Microsoft DTS to MySQL reports a `Syntax Error'. This error occurs only with MySQL tables using the *Note `TEXT': blob. or *Note `VARCHAR': char. data types. You can fix this error by upgrading your Connector/ODBC driver to version 3.51.02 or higher. * SQL_NO_DATA Exception from ODBC.NET * Using ODBC.NET with Connector/ODBC, while fetching empty string (0 length), it starts giving the `SQL_NO_DATA' exception. You can get the patch that addresses this problem from `http://support.microsoft.com/default.aspx?scid=kb;EN-US;q319243'. * Error with SELECT COUNT(*) * Using `SELECT COUNT(*) FROM TBL_NAME' within Visual Basic and ASP returns an error. This error occurs because the `COUNT(*)' expression is returning a *Note `BIGINT': integer-types, and ADO cannot make sense of a number this big. Select the `Change BIGINT columns to INT' option (option value 16384). * Multiple-Step Operation Error * Using the `AppendChunk()' or `GetChunk()' ADO methods, the `Multiple-step operation generated errors. Check each status value' error is returned. The `GetChunk()' and `AppendChunk()' methods from ADO do not work as expected when the cursor location is specified as `adUseServer'. On the other hand, you can overcome this error by using `adUseClient'. A simple example can be found from `http://www.dwam.net/iishelp/ado/docs/adomth02_4.htm' * Modified Record Error * Access returns `Another user had modified the record that you have modified' while editing records on a Linked Table. In most cases, this can be solved by doing one of the following things: * Add a primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key) for the table if one doesn't exist. * Add a timestamp column if one doesn't exist. * Only use double-precision float fields. Some programs may fail when they compare single-precision floats. If these strategies do not help, start by making a log file from the ODBC manager (the log you get when requesting logs from ODBCADMIN) and a Connector/ODBC log to help you figure out why things go wrong. For instructions, see *Note connector-odbc-configuration-trace::. * Direct Application Linking Under Unix or Linux * When linking an application directly to the Connector/ODBC library under Unix or Linux, the application crashes. Connector/ODBC under Unix or Linux is not compatible with direct application linking. To connect to an ODBC source, use a driver manager, such as `iODBC' or `unixODBC'. * Microsoft Office and DATE or TIMESTAMP Columns * Applications in the Microsoft Office suite cannot update tables that have *Note `DATE': datetime. or *Note `TIMESTAMP': datetime. columns. This is a known issue with Connector/ODBC. Ensure that the field has a default value (rather than `NULL') and that the default value is nonzero (that is, something other than `0000-00-00 00:00:00'). * INFORMATION_SCHEMA Database * When connecting Connector/ODBC 5.x to a MySQL 4.x server, the error `1044 Access denied for user 'xxx'@'%' to database 'information_schema'' is returned. Connector/ODBC 5.x is designed to work with MySQL 5.0 or later, taking advantage of the `INFORMATION_SCHEMA' database to determine data definition information. Support for MySQL 4.1 is planned for the final release. * S1T00 Error * When calling `SQLTables', the error `S1T00' is returned, but I cannot find this in the list of error numbers for Connector/ODBC. The `S1T00' error indicates that a general timeout has occurred within the ODBC system and is not a MySQL error. Typically it indicates that the connection you are using is stale, the server is too busy to accept your request or that the server has gone away. * "Table does not exist" Error in Access 2000 * When linking to tables in Access 2000 and generating links to tables programmatically, rather than through the table designer interface, you may get errors about tables not existing. There is a known issue with a specific version of the `msjet40.dll' that exhibits this issue. The version affected is 4.0.9025.0. Reverting to an older version will enable you to create the links. If you have recently updated your version, check your `WINDOWS' directory for the older version of the file and copy it to the drivers directory. * Batched Statements * When I try to use batched statements, the execution of the batched statements fails. Batched statement support was added in 3.51.18. Support for batched statements is not enabled by default. Enable option `FLAG_MULTI_STATEMENTS', value 67108864, or select the `Allow multiple statements' flag within a GUI configuration. * Packet Errors with ADODB and Excel * When connecting to a MySQL server using ADODB and Excel, occasionally the application fails to communicate with the server and the error `Got an error reading communication packets' appears in the error log. This error may be related to Keyboard Logger 1.1 from PanteraSoft.com, which is known to interfere with the network communication between MySQL Connector/ODBC and MySQL. * Outer Join Error * When using some applications to access a MySQL server using Connector/ODBC and outer joins, an error is reported regarding the Outer Join Escape Sequence. This is a known issue with MySQL Connector/ODBC which is not correctly parsing the "Outer Join Escape Sequence", as per the specs at Microsoft ODBC Specs (http://msdn2.microsoft.com/en-us/library/ms710299.aspx). Currently, Connector/ODBC will return a value > 0 when asked for `SQL_OJ_CAPABILITIES' even though no parsing takes place in the driver to handle the outer join escape sequence. * Hebrew/CJK Characters * I can correctly store extended characters in the database (Hebrew/CJK) using Connector/ODBC 5.1, but when I retrieve the data, the text is not formatted correctly and I get garbled characters. When using ASP and UTF8 characters, add the following to your ASP files to ensure that the data returned is correctly encoded: Response.CodePage = 65001 Response.CharSet = "utf-8" * Duplicate Entry in Installed Programs List * I have a duplicate MySQL Connector/ODBC entry within my `Installed Programs' list, but I cannot delete one of them. This problem can occur when you upgrade an existing Connector/ODBC installation, rather than removing and then installing the updated version. *Warning*: To fix the problem, use any working uninstallers to remove existing installations; then may have to edit the contents of the registry. Make sure you have a backup of your registry information before attempting any editing of the registry contents. * Values Truncated to 255 Characters * When submitting queries with parameter binding using *Note `UPDATE': update, my field values are being truncated to 255 characters. Ensure that the `FLAG_BIG_PACKETS' option is set for your connection. This removes the 255 character limitation on bound parameters. * Disabling Data-At-Execution * Is it possible to disable data-at-execution using a flag? If you do not want to use data-at-execution, remove the corresponding calls. For example: SQLLEN ylen = SQL_LEN_DATA_AT_EXEC(10); SQLBindCol(hstmt,2,SQL_C_BINARY, buf, 10, &ylen); Would become: SQLBindCol(hstmt,2,SQL_C_BINARY, buf, 10, NULL); Note that in the call to `SQLBindCol()', &ylen has been replaced by NULL. For further information, refer to the MSDN documentation (http://msdn.microsoft.com/en-us/library/ms711010(VS.85).aspx) for `SQLBindCol()'. * NULLABLE Attribute for AUTO_INCREMENT Columns * When you call `SQLColumns()' for a table column that is `AUTO_INCREMENT', the `NULLABLE' column of the result set is always `SQL_NULLABLE (1)'. This is because MySQL reports the `DEFAULT' value for such a column as `NULL'. It means, if you insert a `NULL' value into the column, you will get the next integer value for the table's `auto_increment' counter.  File: manual.info, Node: connector-odbc-support, Prev: connector-odbc-usagenotes, Up: connector-odbc 21.1.8 Connector/ODBC Support ----------------------------- * Menu: * connector-odbc-support-community:: Connector/ODBC Community Support * connector-odbc-support-bug-report:: How to Report Connector/ODBC Problems or Bugs * connector-odbc-support-patch-submission:: How to Submit a Connector/ODBC Patch There are many different places where you can get support for using Connector/ODBC. Always try the Connector/ODBC Mailing List or Connector/ODBC Forum. See *Note connector-odbc-support-community::, for help before reporting a specific bug or issue to MySQL.  File: manual.info, Node: connector-odbc-support-community, Next: connector-odbc-support-bug-report, Prev: connector-odbc-support, Up: connector-odbc-support 21.1.8.1 Connector/ODBC Community Support ......................................... Oracle provides assistance to the user community by means of its mailing lists. For Connector/ODBC-related issues, you can get help from experienced users by using the mailing list. Archives are available online at `http://lists.mysql.com/myodbc'. For information about subscribing to MySQL mailing lists or to browse list archives, visit `http://lists.mysql.com/'. See *Note mailing-lists::. Community support from experienced users is also available through the ODBC Forum (http://forums.mysql.com/list.php?37). You may also find help from other users in the other MySQL Forums, located at `http://forums.mysql.com'. See *Note forums::.  File: manual.info, Node: connector-odbc-support-bug-report, Next: connector-odbc-support-patch-submission, Prev: connector-odbc-support-community, Up: connector-odbc-support 21.1.8.2 How to Report Connector/ODBC Problems or Bugs ...................................................... If you encounter difficulties or problems with Connector/ODBC, start by making a log file from the `ODBC Manager' (the log you get when requesting logs from `ODBC ADMIN') and Connector/ODBC. The procedure for doing this is described in *Note connector-odbc-configuration-trace::. Check the Connector/ODBC trace file to find out what could be wrong. Determine what statements were issued by searching for the string `>mysql_real_query' in the `myodbc.log' file. Also, try issuing the statements from the *Note `mysql': mysql. client program or from `admndemo'. This helps you determine whether the error is in Connector/ODBC or MySQL. If you find out something is wrong, please only send the relevant rows (maximum 40 rows) to the `myodbc' mailing list. See *Note mailing-lists::. Please never send the whole Connector/ODBC or ODBC log file! Ideally, include the following information with the email: * Operating system and version * Connector/ODBC version * ODBC Driver Manager type and version * MySQL server version * ODBC trace from Driver Manager * Connector/ODBC log file from Connector/ODBC driver * Simple reproducible sample Remember that the more information you can supply to us, the more likely it is that we can fix the problem! Also, before posting the bug, check the MyODBC mailing list archive at `http://lists.mysql.com/myodbc'. If you are unable to find out what is wrong, the last option is to create an archive in `tar' or `zip' format that contains a Connector/ODBC trace file, the ODBC log file, and a `README' file that explains the problem. Initiate a bug report for our bugs database at `http://bugs.mysql.com/', then click the Files tab in the bug report for instructions on uploading the archive to the bugs database. Only MySQL engineers have access to the files you upload, and we are very discreet with the data. If you can create a program that also demonstrates the problem, please include it in the archive as well. If the program works with another SQL server, include an ODBC log file where you perform exactly the same SQL statements so that we can compare the results between the two systems. Remember that the more information you can supply to us, the more likely it is that we can fix the problem.  File: manual.info, Node: connector-odbc-support-patch-submission, Prev: connector-odbc-support-bug-report, Up: connector-odbc-support 21.1.8.3 How to Submit a Connector/ODBC Patch ............................................. You can send a patch or suggest a better solution for any existing code or problems by sending a mail message to .  File: manual.info, Node: connector-net, Next: connector-j, Prev: connector-odbc, Up: connectors-apis 21.2 MySQL Connector/Net ======================== * Menu: * connector-net-versions:: Connector/Net Versions * connector-net-installation:: Connector/Net Installation * connector-net-visual-studio:: Connector/Net Visual Studio Integration * connector-net-tutorials:: Connector/Net Tutorials * connector-net-programming:: Connector/Net Programming * connector-net-connection-options:: Connector/Net Connection String Options Reference * connector-net-rt:: Connector/Net Support for Windows Store * connector-net-entityframework50:: EF 5 Support * connector-net-ref:: Connector/Net API Reference * connector-net-support:: Connector/Net Support * connector-net-faq:: Connector/Net FAQ Connector/Net lets you easily develop .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. Connector/Net is a fully managed ADO.NET driver written in 100% pure C#. It does not use the MySQL C client library. For release notes detailing the changes in each release of Connector/Net, see MySQL Connector/Net Release Notes (http://dev.mysql.com/doc/relnotes/connector-net/en/). Connector/Net includes full support for: * Features provided by MySQL Server up to and including MySQL Server 5.7. * Large-packet support for sending and receiving rows and *Note `BLOB': blob. values up to 2 gigabytes in size. * Protocol compression, which enables compressing the data stream between the client and server. * Connections using TCP/IP sockets, named pipes, or shared memory on Windows. * Connections using TCP/IP sockets or Unix sockets on Unix. * The Open Source Mono framework developed by Novell. * Microsoft Entity Framework. * Microsoft Windows RT. This document is intended as a user's guide to Connector/Net and includes a full syntax reference. Syntax information is also included within the `MySql.Data.chm' file included with the Connector/Net distribution. If you are using MySQL 5.0 or later, and Visual Studio as your development environment, you can also use the MySQL Visual Studio Plugin. The plugin acts as a DDEX (Data Designer Extensibility) provider: you can use the data design tools within Visual Studio to manipulate the schema and objects within a MySQL database. For more information, see *Note connector-net-visual-studio::. *Note*: From Connector/Net 5.1 through 6.6, the Visual Studio Plugin is part of the main Connector/Net package. Starting with 6.7, the Visual Studio Plugin has been separated out into it's own product. The MySQL for Visual Studio Plugin release notes can be found at MySQL Connector/Net Release Notes (http://dev.mysql.com/doc/relnotes/connector-net/en/). MySQL Connector/Net supports full versions of Visual Studio 2008, 2010, and 2012, although the extent of support may be limited depending on your versions of MySQL Connector/Net and Visual Studio. For details, see *Note connector-net-visual-studio::. MySQL Connector/Net does not support Express versions of Microsoft products, including Microsoft Visual Web Developer. * Key Topics * * For connection string properties when using the MySqlConnection class, see *Note connector-net-connection-options::.  File: manual.info, Node: connector-net-versions, Next: connector-net-installation, Prev: connector-net, Up: connector-net 21.2.1 Connector/Net Versions ----------------------------- There are several versions of Connector/Net available: * Connector/Net 6.7 includes support for MySQL 5.7, 5.6, 5.5, 5.1, and 5.0. Important new features include Entity Framework 5 support, Built-in Load Balancing (to be used with a backend implementing either MySQL Replication or MySQL Clustering), a Memcached client (compatible with Innodb Memcached plugin) and support for Windows Runtime (WinRT) to write store apps. This version also removes all features related to Visual Studio Integration, which are provided in a separate product, MySQL for Visual Studio. * Connector/Net 6.6 includes support for MySQL Server 5.7, 5.6, 5.5, 5.1, and 5.0. Important new features include stored procedure debugging in Microsoft Visual Studio, support for pluggable authentication including the ability to write your own authentication plugins, Entity Framework 4.3 Code First support, and enhancements to partial trust support to allow hosting services to deploy applications without installing the Connector/Net library in the GAC. * Connector/Net 6.5 includes support for MySQL Server 5.7, 5.6, 5.5, 5.1, and 5.0. Important new features include interceptor classes for exceptions and commands, support for the MySQL 5.6 fractional seconds feature, better partial-trust support, and better IntelliSense, including auto-completion when editing stored procedures or `.mysql' files. * Connector/Net 6.4 includes support for MySQL Server 5.6, 5.5, 5.1, and 5.0. Important new features include support for Windows authentication (when connecting to MySQL Server 5.5+), table caching on the client side, simple connection fail-over support, and improved SQL generation from the Entity Framework provider. This version of Connector/Net is no longer supported. * Connector/Net 6.3 includes support for MySQL Server 5.6, 5.5, 5.1, and 5.0. Important new features include integration with Visual Studio 2010, such as availability of DDL T4 template for Entity Framework, and a custom MySQL SQL Editor. Other features include refactored transaction scope: Connector/Net now supports nested transactions in a scope where they use the same connection string. This version of Connector/Net is no longer supported. * Connector/Net 6.2 includes support for MySQL Server 5.6, 5.5, 5.1, 5.0, and 4.1. Important new features include a new logging system and client SSL certificates. This version of Connector/Net is no longer supported. * Connector/Net 6.1 includes support for MySQL Server 5.6, 5.5, 5.1, 5.0, and 4.1. Important new features include the MySQL Website Configuration Tool and a Session State Provider. This version of Connector/Net is no longer supported. * Connector/Net 6.0 includes support for MySQL Server 5.5, 5.1, 5.0, and 4.1. This version of Connector/Net is no longer supported. * Connector/Net 5.2 includes support for MySQL Server 5.5, 5.1, 5.0, and 4.1 features. Connector/Net 5.2 also includes support for a new membership/role provider, Compact Framework 2.0, a new stored procedure parser and improvements to `GetSchema'. Connector/Net 5.2 also includes the Visual Studio Plugin as a standard installable component. This version of Connector/Net is no longer supported. * Connector/Net 5.1 includes support for MySQL Server 5.5, 5.1, 5.0, 4.1, and 4.0 features. Connector/Net 5.1 also includes support for a new membership/role provider, Compact Framework 2.0, a new stored procedure parser and improvements to `GetSchema'. Connector/Net 5.1 also includes the Visual Studio Plugin as a standard installable component. This version of Connector/Net is no longer supported. * Connector/Net 5.0 includes support for MySQL Server 5.1, 5.0, 4.1, and 4.0 features. Connector/Net 5.0 also includes full support for the ADO.Net 2.0 interfaces and subclasses, includes support for the usage advisor and performance monitor (PerfMon) hooks. This version of Connector/Net is no longer supported. * Connector/Net 1.0 includes support for MySQL Server 5.0, 4.1, and 4.0 features, and full compatibility with the ADO.NET driver interface. This version of Connector/Net is no longer supported. The following table shows the .NET Framework version required, and the MySQL Server version supported by Connector/Net: *Connector/Net Requirements for Related Products* Connector/Net ADO.NET version .NET Framework MySQL Server Currently version supported version required version supported supported 6.7 2.x+ 2.x+ for VS 2008, 5.7, 5.6, 5.5, Yes 4.x+ for VS 2010 5.1, 5.0 / VS 2012, .NET RT for VS 2012 6.6 2.x+ 2.x+ for VS 2008, 5.7, 5.6, 5.5, Yes 4.x+ for VS 2010 5.1, 5.0 / VS 2012 6.5 2.x+ 2.x+ for VS 2008, 5.7, 5.6, 5.5, Yes 4.x+ for VS 2010 5.1, 5.0 6.4 2.x+ 2.x+, 4.x+ for VS 5.6, 5.5, 5.1, 5.0 No 2010 6.3 2.x+ 2.x+, 4.x+ for VS 5.6, 5.5, 5.1, 5.0 No 2010 6.2 2.x+ 2.x+ 5.6, 5.5, 5.1, No 5.0, 4.1 6.1 2.x+ 2.x+ 5.6, 5.5, 5.1, No 5.0, 4.1 6.0 2.x+ 2.x+ 5.5, 5.1, 5.0, 4.1 No 5.2 2.x+ 2.x+ 5.5, 5.1, 5.0, 4.1 No 5.1 2.x+ 2.x+ 5.5, 5.1, 5.0, No 4.1, 4.0 5.0 2.x+ 2.x+ 5.0, 4.1, 4.0 No 1.0 1.x 1.x 5.0, 4.1, 4.0 No *Note*: Version numbers for MySQL products are formatted as X.Y.Z, where Z=0 indicates alpha, Z=1 indicates beta, and Z>=2 indicates GA. However, Windows tools (Control Panel, properties display) may show the version numbers as XX.YY.ZZ. For example, the official MySQL formatted version number 5.0.9 may be displayed by Windows tools as 5.00.09. The two versions are the same; only the number display format is different.  File: manual.info, Node: connector-net-installation, Next: connector-net-visual-studio, Prev: connector-net-versions, Up: connector-net 21.2.2 Connector/Net Installation --------------------------------- * Menu: * connector-net-installation-windows:: Installing Connector/Net on Windows * connector-net-installation-unix:: Installing Connector/Net on Unix with Mono * connector-net-installation-source:: Installing Connector/Net from the Source Code Connector/Net runs on any platform that supports the .NET framework. The .NET framework is primarily supported on recent versions of Microsoft Windows, and is supported on Linux through the Open Source Mono framework (see `http://www.mono-project.com'). Connector/Net is available for download from `http://dev.mysql.com/downloads/connector/net/'.  File: manual.info, Node: connector-net-installation-windows, Next: connector-net-installation-unix, Prev: connector-net-installation, Up: connector-net-installation 21.2.2.1 Installing Connector/Net on Windows ............................................ * Menu: * connector-net-installation-binary-windows-installer:: Installing Connector/Net Using the Installer * connector-net-installation-binary-windows-zip:: Installing Connector/Net Using the Zip Packages On Windows, you can install either through a binary installation process or by downloading a zip file with the Connector/Net components. Before installing, ensure that your system is up to date, including installing the latest version of the .NET Framework.  File: manual.info, Node: connector-net-installation-binary-windows-installer, Next: connector-net-installation-binary-windows-zip, Prev: connector-net-installation-windows, Up: connector-net-installation-windows 21.2.2.2 Installing Connector/Net Using the Installer ..................................................... Using the installer is the most straightforward method of installing Connector/Net on Windows and the installed components include the source code, test code and full reference documentation. You install Connector/Net through a Windows Installer (`.msi') installation package, which can install Connector/Net on all Windows operating systems. The MSI package is contained within a zip archive named `mysql-connector-net-VERSION.zip', where VERSION indicates the Connector/Net version. To install Connector/Net: 1. Double-click the MSI installer file extracted from the zip you downloaded. Click `Next' to start the installation. Connector/Net Windows Installer - Welcome 2. You must choose the type of installation to perform. Connector/Net Windows Installer - Installation type For most situations, the Typical installation is suitable. Click the `Typical' button and proceed to Step 5. A Complete installation installs all the available files. To conduct a Complete installation, click the `Complete' button and proceed to step 5. To customize your installation, including choosing the components to install and some installation options, click the `Custom' button and proceed to Step 3. The Connector/Net installer will register the connector within the Global Assembly Cache (GAC) - this will make the Connector/Net component available to all applications, not just those where you explicitly reference the Connector/Net component. The installer will also create the necessary links in the Start menu to the documentation and release notes. 3. If you have chosen a custom installation, you can select the individual components to install, including the core interface component, supporting documentation (a CHM file) samples and examples, and the source code. Select the items, and their installation level, and then click `Next' to continue the installation. *Note*: For Connector/Net 1.0.8 or lower and Connector 5.0.4 and lower the installer will attempt to install binaries for both 1.x and 2.x of the .NET Framework. If you only have one version of the framework installed, the connector installation may fail. If this happens, you can choose the framework version to be installed through the custom installation step. Connector/Net Windows Installer - Custom setup 4. You will be given a final opportunity to confirm the installation. Click `Install' to copy and install the files onto your machine. Connector/Net Windows Installer - Confirming installation 5. Once the installation has been completed, click `Finish' to exit the installer. Connector/Net Windows Installer - Finish installation Unless you choose otherwise, Connector/Net is installed in `C:\Program Files\MySQL\MySQL Connector Net X.X.X', where X.X.X is replaced with the version of Connector/Net you are installing. New installations do not overwrite existing versions of Connector/Net. Depending on your installation type, the installed components will include some or all of the following components: * `bin': Connector/Net MySQL libraries for different versions of the .NET environment. * `docs': Connector/Net documentation in CHM format. * `samples': Sample code and applications that use the Connector/Net component. * `src': The source code for the Connector/Net component. You may also use the `/quiet' or `/q' command-line option with the `msiexec' tool to install the Connector/Net package automatically (using the default options) with no notification to the user. Using this method the user cannot select options. Additionally, no prompts, messages or dialog boxes will be displayed. C:\> msiexec /package connector-net.msi /quiet To provide a progress bar to the user during automatic installation, use the `/passive' option.  File: manual.info, Node: connector-net-installation-binary-windows-zip, Prev: connector-net-installation-binary-windows-installer, Up: connector-net-installation-windows 21.2.2.3 Installing Connector/Net Using the Zip Packages ........................................................ If you have problems running the installer, you can download a zip file without an installer as an alternative. That file is called `mysql-connector-net-VERSION-noinstall.zip'. After downloading the zip archive, extract the files to a location of your choice. The file contains the following directories: * `bin': Connector/Net MySQL libraries for different versions of the .NET environment. * `Docs': Connector/Net documentation in CHM format. * `Samples': Sample code and applications that use the Connector/Net component. Connector/Net 6.0.x has a different directory structure: * `Assemblies': A collection of DLLs that make up the connector functionality. * `Documentation': Connector/Net documentation in CHM format. * `Samples': sample code and applications that use the Connector/Net component. Another zip file available for download contains the source code distribution. This file is named `mysql-connector-net-VERSION-src.zip'. The file contains the following directories: * `Documentation': Source files to build the documentation into the compiled HTML (CHM) format. * `Installer': Source files to build the Connector/Net installer program. * `MySql.Data': Source files for the core data provider. * `MySql.VisualStudio': Source files for the Microsoft Visual Studio extensions. * `MySql.Web': Source files for the web providers. This includes code for the membership provider, role provider and profile provider. These are used in ASP.NET web sites. * `Samples': Source files for several example applications. * `Tests': A spreadsheet listing test cases. * `VisualStudio': Resources used by the Visual Studio plugin. Finally, ensure that `MySql.Data.dll' is accessible to your program at build time (and runtime). If using Microsoft Visual Studio, add `MySql.Data' as a Reference to your project. *Note*: If using MySQL Connector/Net 6.3.5 and above, the `MySql.Data.dll' file provided will work with both .NET Framework 2.x and 4.x.  File: manual.info, Node: connector-net-installation-unix, Next: connector-net-installation-source, Prev: connector-net-installation-windows, Up: connector-net-installation 21.2.2.4 Installing Connector/Net on Unix with Mono ................................................... There is no installer available for installing the Connector/Net component on your Unix installation. Before installing, ensure that you have a working Mono project installation. To test whether your system has Mono installed, enter: shell> mono --version The version of the Mono JIT compiler is displayed. To compile C# source code, make sure a Mono C# compiler is installed. Note that there are two Mono C# compilers available, `mcs', which accesses the 1.0-profile libraries, and `gmcs', which accesses the 2.0-profile libraries. To install Connector/Net on Unix/Mono: 1. Download the `mysql-connector-net-VERSION-noinstall.zip' and extract the contents to a directory of your choice, for example: `~/connector-net/'. 2. In the directory where you unzipped the connector to, change into the `bin' subdirectory. Ensure the file `MySql.Data.dll' is present. This filename is case-sensitive. 3. You must register the Connector/Net component, `MySql.Data', in the Global Assembly Cache (GAC). In the current directory enter the `gacutil' command: root-shell> gacutil /i MySql.Data.dll This will register `MySql.Data' into the GAC. You can check this by listing the contents of `/usr/lib/mono/gac', where you will find `MySql.Data' if the registration has been successful. You are now ready to compile your application. You must ensure that when you compile your application you include the Connector/Net component using the `-r:' command-line option. For example: shell> gmcs -r:System.dll -r:System.Data.dll -r:MySql.Data.dll HelloWorld.cs Note, the assemblies that are referenced depend on the requirements of the application, but applications using Connector/Net must provide `-r:MySql.Data' as a minimum. You can further check your installation by running the compiled program, for example: shell> mono HelloWorld.exe  File: manual.info, Node: connector-net-installation-source, Prev: connector-net-installation-unix, Up: connector-net-installation 21.2.2.5 Installing Connector/Net from the Source Code ...................................................... Source packages of Connector/Net are available for download from `http://dev.mysql.com/downloads/connector/net/'. * Building the Source Code on Windows * The following procedure can be used to build the connector on Microsoft Windows. * Navigate to the root of the source code tree. * A Microsoft Visual Studio solution file named `MySqlClient.sln' is available to build the connector. Click this file to load the solution into Visual Studio. `MySqlClient.sln' must be compiled with VS 2008, VS 2010, or VS 2012. Also, depending on the version, the dependencies to build it include Visual Studio SDK, NUnit, Entity Framework, and ANTLR Integration for Visual Studio. * Select `Build', `Build Solution' from the main menu to build the solution. * Building the Source Code on Unix * Support for building Connector/Net on Mono/Unix is currently not available.  File: manual.info, Node: connector-net-visual-studio, Next: connector-net-tutorials, Prev: connector-net-installation, Up: connector-net 21.2.3 Connector/Net Visual Studio Integration ---------------------------------------------- * Menu: * connector-net-visual-studio-making-a-connection:: Making a Connection * connector-net-visual-studio-intellisense:: Using IntelliSense in the SQL Editor * connector-net-visual-studio-editing-tables:: Editing Tables * connector-net-visual-studio-editing-views:: Editing Views * connector-net-visual-studio-editing-stored-procedures-and-functions:: Editing Stored Procedures and Functions * connector-net-visual-studio-editing-triggers:: Editing Triggers * connector-net-visual-studio-editing-user-defined-functions-udf:: Editing User Defined Functions (UDF) * connector-net-visual-studio-debugger:: Debugging Stored Procedures and Functions * connector-net-visual-studio-cloning-database-objects:: Cloning Database Objects * connector-net-visual-studio-dropping-database-objects:: Dropping Database Objects * connector-net-visual-studio-entity-framework:: Using the ADO.NET Entity Framework * connector-net-website-config:: MySQL Website Configuration Tool * connector-net-sql-editor:: MySQL SQL Editor * connector-net-ddl-t4-ef:: DDL T4 Template Macro When MySQL Connector/Net is installed on Microsoft Windows, Visual Studio integration components are also installed and initialized. This enables the developer to work seamlessly with MySQL Connector/Net in the familiar Visual Studio environment, as described in the following sections of the manual. MySQL Connector/Net supports full versions of Visual Studio 2008, 2010, and 2012, although the extent of support may be limited depending on your versions of MySQL Connector/Net and Visual Studio: * Visual Studio 2012 is supported by MySQL Connector/Net 6.6 and up. * Full integration with Visual Studio 2010 is available only with MySQL Connector/Net 6.3.2 and up, although applications using earlier versions of the connector can be built with the Visual Studio 2010 environment using .NET 2.x frameworks. * Visual Studio 2005 is supported only through MySQL Connector/Net 6.4. MySQL Connector/Net does not currently support Express versions of Microsoft products, including Microsoft Visual Web Developer. Visual Studio 2010 support was introduced with MySQL Connector/Net 6.3.2. From version 6.3.2 the connector ships with both .NET 2.x and .NET 4.x versions of the entity framework support files, `mysql.data.ef.dll' and `mysql.visualstudio.dll'. The .NET 4.x versions are required to enable new integration features supported in Visual Studio 2010, including: * New DDL T4 template for the Entity Framework (EF) - This enables developers to design an EF model from scratch and use the native Visual Studio 2010 facility to generate MySQL DDL from that model. This is done by creating the model, and with the model open, choosing the SSDLToMySQL template in the properties window. The correct DDL is then generated. The developer can then save this code as a `.mysql' file in their project and execute it against the MySQL server. * New SQL Editor - A new SQL editor lets you connect to a MySQL server to execute SQL. This is activated by creating a new file with a `.mysql' extension. A new template lets you create files with this file type using the Visual Studio 2010 main menu item `File', `New'. Note that the MySQL SQL Editor is also available in Visual Studio 2005 and 2008. As of Connector/Net 5.1.2, the Visual Studio Plugin is part of the main Connector/Net package. The Visual Studio Plugin release notes can be found at MySQL Connector/Net Release Notes (http://dev.mysql.com/doc/relnotes/connector-net/en/).  File: manual.info, Node: connector-net-visual-studio-making-a-connection, Next: connector-net-visual-studio-intellisense, Prev: connector-net-visual-studio, Up: connector-net-visual-studio 21.2.3.1 Making a Connection ............................ Once the connector is installed, you can use it to create, modify, and delete connections to MySQL databases. To create a connection with a MySQL database, perform the following steps: * Start Visual Studio, and open the Server Explorer window (`View', `Server Explorer' option in the main Visual Studio menu, or `Control+W', `L' keyboard shortcuts). * Right-click the Data Connections node, and choose the `Add Connection...' menu item. * Add Connection dialog opens. Press the `Change' button to choose MySQL Database as a data source. FIGURE GOES HERE: Add Connection Context Menu * `Change Data Source' dialog opens. Choose `MySQL Database' in the list of data sources (or the `' option, if MySQL Database is absent), and then choose `.NET Framework Data Provider for MySQL' in the combo box of data providers. FIGURE GOES HERE: Choose Data Source * Input the connection settings: the server host name (for example, localhost if the MySQL server is installed on the local machine), the user name, the password, and the default schema name. Note that you must specify the default schema name to open the connection. FIGURE GOES HERE: Add Connection Dialog * You can also set the port to connect with the MySQL server by pressing the `Advanced' button. To test connection with the MySQL server, set the server host name, the user name, and the password, and press the `Test Connection' button. If the test succeeds, the success confirmation dialog opens. * After you set all settings and test the connection, press `OK'. The newly created connection is displayed in Server Explorer. Now you can work with the MySQL server through standard Server Explorer GUI. FIGURE GOES HERE: New Data Connection After the connection is successfully established, all settings are saved for future use. When you start Visual Studio for the next time, open the connection node in Server Explorer to establish a connection to the MySQL server again. To modify and delete a connection, use the Server Explorer context menu for the corresponding node. You can modify any of the settings by overwriting the existing values with new ones. Note that the connection may be modified or deleted only if no active editor for its objects is opened: otherwise, you may lose your data.  File: manual.info, Node: connector-net-visual-studio-intellisense, Next: connector-net-visual-studio-editing-tables, Prev: connector-net-visual-studio-making-a-connection, Up: connector-net-visual-studio 21.2.3.2 Using IntelliSense in the SQL Editor ............................................. IntelliSense support is available starting in Connector/Net 6.5. Once you have established a connection, for example, using the `Connect to MySql' toolbar button, you can get autocompletion as you type, or by pressing `Control+J'. Depending on the context, the autocompletion dialog can show the list of available tables, table columns, or stored procedures (with the routine's signature as a tooltip). Typing some characters before pressing `Control+J' filters the choices to those items starting with that prefix.  File: manual.info, Node: connector-net-visual-studio-editing-tables, Next: connector-net-visual-studio-editing-views, Prev: connector-net-visual-studio-intellisense, Up: connector-net-visual-studio 21.2.3.3 Editing Tables ....................... * Menu: * connector-net-visual-studio-editing-tables-column-editor:: Column Editor * connector-net-visual-studio-editing-tables-indexes:: Editing Indexes * connector-net-visual-studio-editing-tables-foreign-keys:: Editing Foreign Keys * connector-net-visual-studio-editing-tables-column-details:: Column Properties * connector-net-visual-studio-editing-tables-table-properties:: Table Properties Connector/Net contains a table editor, which enables the visual creation and modification of tables. The Table Designer can be accessed through a mouse action on table-type node of Server Explorer. To create a new table, right-click the `Tables' node (under the connection node) and choose the `Create Table' command from the context menu. To modify an existing table, double-click the node of the table to modify, or right-click this node and choose the `Design' item from the context menu. Either of the commands opens the Table Designer. The table editor is implemented in the manner of the well-known Query Browser Table Editor, but with minor differences. FIGURE GOES HERE: Editing New Table Table Designer consists of the following parts: * Columns Editor - a data grid on top of the Table Designer. Use the Columns grid for column creation, modification, and deletion. * Indexes tab - a tab on bottom of the Table Designer. Use the Indexes tab for indexes management. * Foreign Keys tab - a tab on bottom of the Table Designer. Use the Foreign Keys tab for foreign keys management. * Column Details tab - a tab on bottom of the Table Designer. Use the Column Details tab to set advanced column options. * Properties window - a standard Visual Studio Properties window, where the properties of the edited table are displayed. Use the Properties window to set the table properties. Each of these areas is discussed in more detail in subsequent sections. To save changes you have made in the Table Designer, use either `Save' or `Save All' button of the Visual Studio main toolbar, or press `Control+S'. If you have not already named the table, you will be prompted to do so. FIGURE GOES HERE: Choose Table Name Once the table is created, you can view it in the Server Explorer. FIGURE GOES HERE: Newly Created Table The Table Designer main menu lets you set a primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key) column, edit relationships such as foreign keys (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_foreign_key), and create indexes (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_index). FIGURE GOES HERE: Table Designer Main Menu  File: manual.info, Node: connector-net-visual-studio-editing-tables-column-editor, Next: connector-net-visual-studio-editing-tables-indexes, Prev: connector-net-visual-studio-editing-tables, Up: connector-net-visual-studio-editing-tables 21.2.3.4 Column Editor ...................... You can use the Column Editor to set or change the name, data type, default value, and other properties of a table column. To set the focus to a needed cell of a grid, use the mouse click. Also you can move through the grid using `Tab' and `Shift'+`Tab' keys. To set or change the name, data type, default value and comment of a column, activate the appropriate cell and type the desired value. To set or unset flag-type column properties (`NOT NULL', auto incremented, flags), check or uncheck the corresponding check boxes. Note that the set of column flags depends on its data type. To reorder columns, index columns or foreign key columns in the Column Editor, select the whole column to reorder by clicking the selector column on the left of the column grid. Then move the column by using `Control+Up' (to move the column up) or `Control+Down' (to move the column down) keys. To delete a column, select it by clicking the selector column on the left of the column grid, then press the `Delete' button on a keyboard.  File: manual.info, Node: connector-net-visual-studio-editing-tables-indexes, Next: connector-net-visual-studio-editing-tables-foreign-keys, Prev: connector-net-visual-studio-editing-tables-column-editor, Up: connector-net-visual-studio-editing-tables 21.2.3.5 Editing Indexes ........................ Indexes management is performed using the `Indexes/Keys' dialog. To add an index, select `Table Designer', `Indexes/Keys...' from the main menu, and click `Add' to add a new index. You can then set the index name, index kind, index type, and a set of index columns. FIGURE GOES HERE: Indexes Dialog To remove an index, select it in the list box on the left, and click the `Delete' button. To change index settings, select the needed index in the list box on the left. The detailed information about the index is displayed in the panel on the right hand side. Change the desired values.  File: manual.info, Node: connector-net-visual-studio-editing-tables-foreign-keys, Next: connector-net-visual-studio-editing-tables-column-details, Prev: connector-net-visual-studio-editing-tables-indexes, Up: connector-net-visual-studio-editing-tables 21.2.3.6 Editing Foreign Keys ............................. You manage foreign keys (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_foreign_key) for *Note `InnoDB': innodb-storage-engine. tables using the `Foreign Key Relationships' dialog. To add a foreign key, select `Table Designer', `Relationships...' from the main menu. This displays the `Foreign Key Relationship' dialog. Click `Add'. You can then set the foreign key name, referenced table name, foreign key columns, and actions upon update and delete. To remove a foreign key, select it in the list box on the left, and click the `Delete' button. To change foreign key settings, select the required foreign key in the list box on the left. The detailed information about the foreign key is displayed in the right hand panel. Change the desired values. FIGURE GOES HERE: Foreign Key Relationships Dialog  File: manual.info, Node: connector-net-visual-studio-editing-tables-column-details, Next: connector-net-visual-studio-editing-tables-table-properties, Prev: connector-net-visual-studio-editing-tables-foreign-keys, Up: connector-net-visual-studio-editing-tables 21.2.3.7 Column Properties .......................... The `Column Properties' tab can be used to set column options. In addition to the general column properties presented in the Column Editor, in the `Column Properties' tab you can set additional properties such as Character Set, Collation and Precision.  File: manual.info, Node: connector-net-visual-studio-editing-tables-table-properties, Prev: connector-net-visual-studio-editing-tables-column-details, Up: connector-net-visual-studio-editing-tables 21.2.3.8 Table Properties ......................... To bring up Table Properties select the table and right-click to activate the context menu. Select `Properties'. The `Table Properties' dockable window will be displayed. FIGURE GOES HERE: Table Properties Menu Item The following table properties can be set: * Auto Increment. * Average Row Length. * Character Set. * Collation. * Comment. * Data Directory. * Index Directory. * Maximum Rows. * Minimum Rows. * Name. * Row Format. * Schema. * Storage Engine (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_storage_engine). Note that in MySQL 5.5 and higher, the default storage engine for new tables is `InnoDB'. See `InnoDB' as the Default MySQL Storage Engine (http://dev.mysql.com/doc/refman/5.5/en/innodb-default-se.html) for more information about the choice of storage engine, and considerations if you convert existing tables to `InnoDB'. The property `Schema' is read-only. FIGURE GOES HERE: Table Properties  File: manual.info, Node: connector-net-visual-studio-editing-views, Next: connector-net-visual-studio-editing-stored-procedures-and-functions, Prev: connector-net-visual-studio-editing-tables, Up: connector-net-visual-studio 21.2.3.9 Editing Views ...................... To create a new view, right-click the Views node under the connection node in Server Explorer. From the node's context menu, choose the `Create View' command. This command opens the SQL Editor. FIGURE GOES HERE: Editing View SQL You can then enter the SQL for your view. FIGURE GOES HERE: View SQL Added To modify an existing view, double-click a node of the view to modify, or right-click this node and choose the `Alter View' command from a context menu. Either of the commands opens the SQL Editor. All other view properties can be set in the Properties window. These properties are: * Catalog * Check Option * Definer * Definition * Definer * Is Updatable * Name * Schema * Security Type Some of these properties can have arbitrary text values, others accept values from a predefined set. In the latter case, set the desired value with an embedded combobox. The properties `Is Updatable' and `Schema' are readonly. To save changes you have made, use either `Save' or `Save All' buttons of the Visual Studio main toolbar, or press `Control+S'. FIGURE GOES HERE: View SQL Saved  File: manual.info, Node: connector-net-visual-studio-editing-stored-procedures-and-functions, Next: connector-net-visual-studio-editing-triggers, Prev: connector-net-visual-studio-editing-views, Up: connector-net-visual-studio 21.2.3.10 Editing Stored Procedures and Functions ................................................. To create a new stored procedure, right-click the `Stored Procedures' node under the connection node in Server Explorer. From the node's context menu, choose the `Create Routine' command. This command opens the SQL Editor. FIGURE GOES HERE: Edit Stored Procedure SQL To create a new stored function, right-click the `Functions' node under the connection node in Server Explorer. From the node's context menu, choose the `Create Routine' command. To modify an existing stored routine (procedure or function), double-click the node of the routine to modify, or right-click this node and choose the `Alter Routine' command from the context menu. Either of the commands opens the SQL Editor. To create or alter the routine definition using SQL Editor, type this definition in the SQL Editor using standard SQL. All other routine properties can be set in the Properties window. These properties are: * Body * Catalog * Comment * Creation Time * Data Access * Definer * Definition * External Name * External Language * Is Deterministic * Last Modified * Name * Parameter Style * Returns * Schema * Security Type * Specific Name * SQL Mode * SQL Path * Type Some of these properties can have arbitrary text values, others accept values from a predefined set. In the latter case, set the desired value using the embedded combo box. You can also set all the options directly in the SQL Editor, using the standard *Note `CREATE PROCEDURE': create-procedure. or *Note `CREATE FUNCTION': create-function. statement. However, it is recommended to use the Properties window instead. To save changes you have made, use either `Save' or `Save All' buttons of the Visual Studio main toolbar, or press `Control+S'. FIGURE GOES HERE: Stored Procedure SQL Saved To observe the runtime behavior of a stored routine and debug any problems, use the Stored Procedure Debugger (available in Connector/Net 6.6 and higher). See *Note connector-net-visual-studio-debugger:: for details.  File: manual.info, Node: connector-net-visual-studio-editing-triggers, Next: connector-net-visual-studio-editing-user-defined-functions-udf, Prev: connector-net-visual-studio-editing-stored-procedures-and-functions, Up: connector-net-visual-studio 21.2.3.11 Editing Triggers .......................... To create a new trigger, right-click the node of the table in which to add the trigger. From the node's context menu, choose the `Create Trigger' command. This command opens the SQL Editor. To modify an existing trigger, double-click the node of the trigger to modify, or right-click this node and choose the `Alter Trigger' command from the context menu. Either of the commands opens the SQL Editor. To create or alter the trigger definition using SQL Editor, type the trigger statement in the SQL Editor using standard SQL. *Note*: Enter only the trigger statement, that is, the part of the *Note `CREATE TRIGGER': create-trigger. query that is placed after the `FOR EACH ROW' clause. All other trigger properties are set in the Properties window. These properties are: * Definer * Event Manipulation * Name * Timing Some of these properties can have arbitrary text values, others accept values from a predefined set. In the latter case, set the desired value using the embedded combo box. The properties `Event Table', `Schema', and `Server' in the Properties window are read-only. To save changes you have made, use either `Save' or `Save All' buttons of the Visual Studio main toolbar, or press `Control+S'. Before changes are saved, you will be asked to confirm the execution of the corresponding SQL query in a confirmation dialog. To observe the runtime behavior of a stored routine and debug any problems, use the Stored Procedure Debugger (available in Connector/Net 6.6 and higher). See *Note connector-net-visual-studio-debugger:: for details.  File: manual.info, Node: connector-net-visual-studio-editing-user-defined-functions-udf, Next: connector-net-visual-studio-debugger, Prev: connector-net-visual-studio-editing-triggers, Up: connector-net-visual-studio 21.2.3.12 Editing User Defined Functions (UDF) .............................................. To create a new User Defined Function (UDF), right-click the `UDFs' node under the connection node in Server Explorer. From the node's context menu, choose the `Create UDF' command. This command opens the UDF Editor. To modify an existing UDF, double-click the node of the UDF to modify, or right-click this node and choose the `Alter UDF' command from the context menu. Either of these commands opens the UDF Editor. The UDF editor enables you to set the following properties: * Name * So-name (DLL name) * Return type * Is Aggregate There are text fields for both names, a combo box for the return type, and a check box to indicate if the UDF is aggregate. All these options are also accessible using the Properties window. The property `Server' in the Properties window is read-only. To save changes you have made, use either `Save' or `Save All' buttons of the Visual Studio main toolbar, or press `Control+S'. Before changes are saved, you will be asked to confirm the execution of the corresponding SQL query in a confirmation dialog. To observe the runtime behavior of a stored routine and debug any problems, use the Stored Procedure Debugger (available in Connector/Net 6.6 and higher). See *Note connector-net-visual-studio-debugger:: for details.  File: manual.info, Node: connector-net-visual-studio-debugger, Next: connector-net-visual-studio-cloning-database-objects, Prev: connector-net-visual-studio-editing-user-defined-functions-udf, Up: connector-net-visual-studio 21.2.3.13 Debugging Stored Procedures and Functions ................................................... The stored procedure debugger, new in Connector/Net 6.6, provides facilities for setting breakpoints, stepping into individual statements (Step Into, Step Out, Step Over), evaluating and changing local variable values, evaluating breakpoints, and other typical debugging tasks. * Installing the Debugger * To enable the stored procedure debugger, install Connector/Net 6.6 or higher and choose the `Complete' option. * Privileges * The debugger recreates at the start of each debug session a `serversidedebugger' database in your server. This database helps to track the instrumented code and implement observability logic in the debugged routine. Your current connection needs to have privileges to create that database, and its associated stored routines, functions, and tables. The debugger makes changes behind the scenes to temporarily add instrumentation code to the stored routines that you debug. You must have the `ALTER ROUTINE' privilege for each stored procedure, function, or trigger that you debug. (Including procedures and functions that are called, and triggers that are fired, by a procedure that you are debugging.) * Starting the Debugger * To start the debugger, follow these steps: * Choose a connection in the Visual Studio Server Explorer. FIGURE GOES HERE: Connection Dialog * Expand the `Stored Procedures' folder. Only stored procedures can be debugged directly. To debug a user-defined function, create a stored procedure that calls the function. * Click on a stored procedure node, then right-click and from the context menu choose `Debug Routine'. FIGURE GOES HERE: Choose a Stored Routine to Debug At this point, Visual Studio switches to debug mode, opening the source code of the routine being debugged in step mode, positioned on the first statement. If the initial routine you debug has one or more arguments, a popup will show up with a grid (a row per each argument and three columns: one for the argument, one for the argument value (this is editable) and one for nullifying that argument value (a checkbox)). After setting up all the argument values, you can press `OK' to start the debug session, or `Cancel' to cancel the debug session. FIGURE GOES HERE: Setting Arguments (1 of 2) FIGURE GOES HERE: Setting Arguments (2 of 2) * How the Debugger Works * To have visibility into the internal workings of a stored routine, the debugger prepares a special version of the procedure, function, or trigger being debugged, instrumented with extra code to keep track of the current line being stepped into and the values of all the local variables. Any other stored procedures, functions, or triggers called from the routine being debugged are instrumented the same way. The debug versions of the routines are prepared for you automatically, and when the debug session ends (by either pressing `F5' or `Shift+F5'), the original versions of the routines are automatically restored. A copy of the original version of each instrumented routine (the version without instrumentation) is stored in the `AppData\Roaming\MySqlDebuggerCache' folder for the current Windows user (the path returned by calling `System.Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData)' in .NET, plus appending `MySqlDebuggerCache'. There is one file for each instrumented routine, named `ROUTINE_NAME.mysql'. For example, in Windows 7, for a user named `fergs', the path is `C:\Users\fergs\AppData\Roaming\MySqlDebuggerCache'. Two threads are used, one for the debugger and one for the routine being debugged. The threads run in strict alternation, switching between the debugger and the routine as each statement is executed in the stored routine. * Basic Debugging Operations * The debugger has the same look and feel as the standard Visual Studio debuggers for C#, VB.NET or C++. In particular, the following are true: *Locals and Watches* * To show the Locals tab, choose the menu item `Debug -> Windows -> Locals'. The `Locals' tab lists all the variables available in the current scope: variables defined with `DECLARE' at any point in the routine, argument parameters, and session variables that are referenced. * If the last step operation changes the value of a local, its value will be highlighted in red (until another statement is executed or stepped. * You can change the value of any local. * To show the `Watch' tab, choose the menu item `Debug -> Windows -> Watch'. To define a watch, type any valid MySQL expression, optionally including function calls. If the watch evaluation makes sense in the current context (current stack frame), it will show its value, otherwise it will show an error message in the same row the watch was defined. * When debugging a trigger, in addition to any locals declared or session variables referenced, the new and old object (when applicable) will be listed. For example in a trigger for `INSERT', for a table defined like: create table t1( id int, myname varchar( 50 )); the locals will list the extra variables `new.id' and `new.myname'. For an `UPDATE' trigger, you will also get the extra variables `old.id' and `old.myname'. These variables from the new and old objects can be manipulated the same way as any ordinary local variable. FIGURE GOES HERE: Debugging a Trigger *Call Stack* * To show the `Call Stack' tab, choose the menu item `Debug -> Windows -> Call Stack'. * The stack trace (in the `Call Stack' tab) will list all the stack traces, one for each routine invocation. The one with a yellow mark is the current stepping point. Clicking in another will activate in the editor the tab for that routine source, highlighting in green the last statement stepped. FIGURE GOES HERE: Call Stack *Stepping* * Stepping of a new routine starts in the first executable instruction (excluding declares, handlers, cursor declarations, and so on). FIGURE GOES HERE: Debug Stepping FIGURE GOES HERE: Function Stepping (1 of 2) FIGURE GOES HERE: Function Stepping (2 of 2) * To step into the code of a condition handler, the condition must be triggered in the rest of the MySQL routine. * The next statement to be executed is highlighted in yellow. * To continue stepping, you can choose between `Step Into' (by pressing `F11'), `Step Out' (by pressing `F10') or `Step Over' (by pressing `Shift+F11'). * You can step out of any of functions, triggers or stored procedures. If you step from the main routine, it will run that routine to completion and finish the debug session. * You can step over stored procedure calls, stored functions, and triggers. (To step over a trigger, step over the statement that would cause the trigger to fire.) * When stepping into a single statement, the debugger will step into each individual function invoked by that statement and each trigger fired by that statement. The order in which they are debugged is the same order in which the MySQL server executes them. * You can step into triggers triggered from *Note `INSERT': insert, *Note `DELETE': delete, *Note `UPDATE': update, and *Note `REPLACE': replace. statements. * Also, the number of times you enter into a stored function or trigger depends on how many rows are evaluated by the function or affected by the trigger. For example, if you press `F11' (`Step Into') into an `UPDATE' statement that modifies three rows (calling a function for a column in the `SET' clause, thus invoking the function for each of the three rows), you will step into into that function three times in succession, once for each of the rows. You can accelerate this debug session by disabling any breakpoints defined in the given stored function and pressing `Shift+F11' to step out. In this example, the order in which the different instances of the stored function are debugged is server-specific: the same order used by the current MySQL server instance to evaluate the three function invocations. *Breakpoints* * To show the `Breakpoints' tab, choose the menu item `Debug -> Windows -> Breakpoints'. * The `Breakpoints' tab will show all the breakpoints defined. From here, you can enable and disable breakpoints one by one or all at once (using the toolbar on top of the `Breakpoints' tab). * You can define new breakpoints only in the middle of a debug session. Click in the left gray border of any MySQL editor, or click anywhere in a MySQL editor and press `F9'. In the familiar Visual Studio way, you press `F9' once to create a breakpoint in that line, and press it again to remove that breakpoint. * Once a breakpoint is defined, it will appear enabled (as filled red circle left to the current row if that line is a valid statement to put a breakpoint) or disabled (as a non-filled red circle left to the current row if that row is not valid to put a breakpoint). * To define conditional breakpoints, after creating the breakpoint, right click in the red dot and choose `Condition...'. There you can put any valid MySQL expression and state if the condition is `Is True' or `Has changed'. The former will trigger the breakpoint every time the condition is true, the latter every time the condition value has changed. (If you define a conditional breakpoint, it is not enough to step into the line with the breakpoint defined to trigger such a breakpoint.) FIGURE GOES HERE: Conditional Breakpoints FIGURE GOES HERE: Expressions and Breakpoints * To define pass count breakpoints, after creating the breakpoint, right click in the red dot and choose `Hit Count...'. In the popup dialog, define the specific condition to set. For example, `break when the hit count is equal to' and a value 3 will trigger the breakpoint the third time it is hit. * Other Features * * To abort the debug session (and the execution of the current call stack of routines), press Shift+F5. * To run the routine to completion (or until next breakpoint hit), press F5. * For all functionality you can use (in addition to the shortcuts documented), see the options in the `Debug' menu of Visual Studio. * Limitations * * Code being debugged must not use `get_lock' or `release_lock' MySQL functions, since they are used internally by the debugger infrastructure to synchronize the debugger and the debugged routine. * Code being debugged must avoid using any transaction code (`START TRANSACTION', `COMMIT', `ROLLBACK') due to the possibility of wiping out the contents of the debugger tables. (This limitation may be removed in the future). * You cannot debug the routines in the `serversidedebugger' database. * The MySQL server running the routine being debugged can be any version between 5.0 and 5.6, running on Windows, Linux, or any other supported platform. * We recommend always running debug sessions on test and development servers, rather than against a MySQL production server, because debugging can cause temporary performance issues or even deadlocks. The instrumented versions of the routines being debugged use locks, that the rest of the production code may not be aware of. * Keyboard Shortcuts * The following list summarizes the keyboard shortcuts for debugging: * `F9' Toggles breakpoints * `F11': Step into once * `F10': Step over once * `Shift+F11': Step out once * `F5': Run * `Shift+F5': Abort current debug session  File: manual.info, Node: connector-net-visual-studio-cloning-database-objects, Next: connector-net-visual-studio-dropping-database-objects, Prev: connector-net-visual-studio-debugger, Up: connector-net-visual-studio 21.2.3.14 Cloning Database Objects .................................. Tables, views, stored procedures, and functions can be cloned using the appropriate Clone command from the context menu: `Clone Table', `Clone View', `Clone Routine'. The clone commands open the corresponding editor for a new object: the `Table Editor' for cloning a table, and the `SQL Editor' for cloning a view or a routine. The editor is filled with values of the original object. You can modify these values in the usual manner. To save the cloned object, use either `Save' or `Save All' buttons of the Visual Studio main toolbar, or press `Control+S'. Before changes are saved, you will be asked to confirm the execution of the corresponding SQL query in a confirmation dialog.  File: manual.info, Node: connector-net-visual-studio-dropping-database-objects, Next: connector-net-visual-studio-entity-framework, Prev: connector-net-visual-studio-cloning-database-objects, Up: connector-net-visual-studio 21.2.3.15 Dropping Database Objects ................................... Tables, views, stored routines, triggers, and UDFs can be dropped with the appropriate Drop command selected from its context menu: `Drop Table', `Drop View', `Drop Routine', `Drop Trigger', `Drop UDF'. You will be asked to confirm the execution of the corresponding drop query in a confirmation dialog. You can only drop a single object at a time.  File: manual.info, Node: connector-net-visual-studio-entity-framework, Next: connector-net-website-config, Prev: connector-net-visual-studio-dropping-database-objects, Up: connector-net-visual-studio 21.2.3.16 Using the ADO.NET Entity Framework ............................................ Connector/Net 6.0 introduced support for the ADO.NET Entity Framework. ADO.NET Entity Framework was included with .NET Framework 3.5 Service Pack 1, and Visual Studio 2008 Service Pack 1. ADO.NET Entity Framework was released on 11th August 2008. ADO.NET Entity Framework provides an Object Relational Mapping (ORM) service, mapping the relational database schema to objects. The ADO.NET Entity Framework defines several layers, these can be summarized as: * *Logical* - this layer defines the relational data and is defined by the Store Schema Definition Language (SSDL). * *Conceptual* - this layer defines the .NET classes and is defined by the Conceptual Schema Definition Language (CSDL) * *Mapping* - this layer defines the mapping from .NET classes to relational tables and associations, and is defined by Mapping Specification Language (MSL). Connector/Net integrates with Visual Studio 2008 to provide a range of helpful tools to assist the developer. A full treatment of ADO.NET Entity Framework is beyond the scope of this manual. If you are unfamiliar with ADO.NET, review the Microsoft ADO.NET Entity Framework documentation (http://msdn.microsoft.com/en-us/library/aa697427(VS.80).aspx). Tutorials on getting started with ADO.NET Entity Framework are available. See *Note connector-net-tutorials-entity-framework-winform-data-source:: and *Note connector-net-tutorials-entity-framework-databinding-linq-entities::.  File: manual.info, Node: connector-net-website-config, Next: connector-net-sql-editor, Prev: connector-net-visual-studio-entity-framework, Up: connector-net-visual-studio 21.2.3.17 MySQL Website Configuration Tool .......................................... MySQL Connector/Net 6.1 introduced the MySQL Website Configuration Tool. This is a facility available in Visual Studio that enables you to configure the Membership, Role, Session State and Profile Provider, without editing configuration files. You set your configuration options within the tool, and the tool modifies your `web.config' file accordingly. The MySQL Website Configuration Tool appears as a small icon on the Solution Explorer toolbar in Visual Studio, as show by the following screenshot: FIGURE GOES HERE: MySQL Website Configuration Tool Clicking the Website Configuration Tool icon launches the wizard and displays the first screen: FIGURE GOES HERE: MySQL Website Configuration Tool - Membership This allows you to enable use of the MySQL Membership Provider. Click the check box to enable this. You can now enter the name of the application that you are creating the configuration for. You can also enter a description for the application. You can then click the `Edit...' button to launch the Connection String Editor: FIGURE GOES HERE: MySQL Website Configuration Tool - Connection String Editor Note that if you have already defined a connection string for the providers manually in `web.config', or previously using the tool, this will be automatically loaded and displayed, and can then be modified in this dialog. You can also ensure that the necessary schemas are created automatically for you by selecting the Autogenerate Schema check box. These schemas are used to store membership information. The database used to storage is the one specified in the connection string. You can also ensure that exceptions generated by the application will be written to the Windows event log by selecting the `Write exceptions to event log' check box. Clicking the `Advanced...' button launches a dialog that enables you to set Membership Options. These options dictate such variables as password length required when a user signs up, whether the password is encrypted and whether the user can reset their password or not. FIGURE GOES HERE: MySQL Website Configuration Tool - Advanced Options Once information has been set up as required for configuration of the Membership Provider, the `Next' button can be clicked to display the Roles Provider screen: FIGURE GOES HERE: MySQL Website Configuration Tool - Roles Again the connection string can be edited, a description added and Autogenerate Schema can be enabled before clicking `Next' to go to the Profiles Provider screen: FIGURE GOES HERE: MySQL Website Configuration Tool - Profiles This screen display similar options to the previous screens. Click `Next' to proceed to the Session State configuration page: FIGURE GOES HERE: MySQL Website Configuration Tool - Session State Once you have set up the Session State Provider as required, click `Finish' to exit the wizard. At this point, select the `Authentication Type' to `From Internet'. Launch the ASP.NET Configuration Tool and select the Security tab. Click the `Select authentication type' link and ensure that the `From the internet' radio button is selected. You can now examine the database you created to store membership information. All the necessary tables will have been created for you: FIGURE GOES HERE: MySQL Website Configuration Tool - Tables  File: manual.info, Node: connector-net-sql-editor, Next: connector-net-ddl-t4-ef, Prev: connector-net-website-config, Up: connector-net-visual-studio 21.2.3.18 MySQL SQL Editor .......................... MySQL Connector/Net 6.3.2 introduced a new MySQL SQL Editor. The easiest way to invoke the editor is by selecting the `New', `File' menu item from the Visual Studio main menu. This displays the `New File' dialog: FIGURE GOES HERE: MySQL SQL Editor - New File From the `New File' dialog, select the MySQL template, and then double-click the `MySQL SQL Script' document, or click the `Open' button. The MySQL SQL Editor will be displayed. You can now enter SQL code as required, or connect to a MySQL server. Click the `Connect to MySQL' button in the MySQL SQL Editor toolbar. You can enter the connection details into the `Connect to MySQL' dialog that is displayed. You can enter the server name, user ID, password and database to connect to, or click the `Advanced' button to select other connection string options. Click the `Connect' button to connect to the MySQL server. To execute your SQL code against the server, click the `Run SQL' button on the toolbar. FIGURE GOES HERE: MySQL SQL Editor - Query The results from any queries are displayed on the `Results' tab. Any errors are displayed on the `Messages' tab.  File: manual.info, Node: connector-net-ddl-t4-ef, Prev: connector-net-sql-editor, Up: connector-net-visual-studio 21.2.3.19 DDL T4 Template Macro ............................... MySQL Connector/Net 6.3 introduced the ability to convert an Entity Framework model to MySQL DDL (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_ddl) code. Starting with a blank model, you can develop an entity model in Visual Studio's designer. Once the model is created, you can select the model's properties, and in the Database Script Generation category of the model's properties, the property `DDL Generation' can be found. Select the value `SSDLToMySQL.tt(VS)' from the drop-down listbox. FIGURE GOES HERE: DDL T4 Template Macro - Model Properties Right-clicking the model design area displays a context-sensitive menu. Selecting `Generate Database from Model' from the menu displays the `Generate Database Wizard'. The wizard can then be used to generate MySQL DDL code. FIGURE GOES HERE: DDL T4 Template Macro - Generate Database Wizard  File: manual.info, Node: connector-net-tutorials, Next: connector-net-programming, Prev: connector-net-visual-studio, Up: connector-net 21.2.4 Connector/Net Tutorials ------------------------------ * Menu: * connector-net-tutorials-intro:: Tutorial: An Introduction to Connector/Net Programming * connector-net-tutorials-asp-roles:: Tutorial: MySQL Connector/Net ASP.NET Membership and Role Provider * connector-net-tutorials-asp-provider-session-state:: Tutorial: MySQL Connector/Net ASP.NET Session State Provider * connector-net-tutorials-asp-provider-profile:: Tutorial: MySQL Connector/Net ASP.NET Profile Provider * connector-net-tutorials-entity-framework-winform-data-source:: Tutorial: Using an Entity Framework Entity as a Windows Forms Data Source * connector-net-tutorials-entity-framework-databinding-linq-entities:: Tutorial: Databinding in ASP.NET Using LINQ on Entities * connector-net-tutorials-ssl:: Tutorial: Using SSL with MySQL Connector/Net * connector-net-tutorials-mysqlscript:: Tutorial: Using MySqlScript * connector-net-tutorials-efmodel-ddl:: Tutorial: Generating MySQL DDL from an Entity Framework Model The following tutorials illustrate how to develop MySQL programs using technologies such as Visual Studio, C#, ASP.NET, and the .NET and Mono frameworks. Work through the first tutorial to verify that you have the right software components installed and configured, then choose other tutorials to try depending on the features you intend to use in your applications.  File: manual.info, Node: connector-net-tutorials-intro, Next: connector-net-tutorials-asp-roles, Prev: connector-net-tutorials, Up: connector-net-tutorials 21.2.4.1 Tutorial: An Introduction to Connector/Net Programming ............................................................... * Menu: * connector-net-tutorials-connection:: The MySqlConnection Object * connector-net-tutorials-sql-command:: The MySqlCommand Object * connector-net-tutorials-data-adapter:: Working with Decoupled Data * connector-net-tutorials-parameters:: Working with Parameters * connector-net-tutorials-stored-procedures:: Working with Stored Procedures This section provides a gentle introduction to programming with Connector/Net. The example code is written in C#, and is designed to work on both Microsoft .NET Framework and Mono. This tutorial is designed to get you up and running with Connector/Net as quickly as possible, it does not go into detail on any particular topic. However, the following sections of this manual describe each of the topics introduced in this tutorial in more detail. In this tutorial you are encouraged to type in and run the code, modifying it as required for your setup. This tutorial assumes you have MySQL and Connector/Net already installed. It also assumes that you have installed the World example database, which can be downloaded from the MySQL Documentation page (http://dev.mysql.com/doc/index-other.html). You can also find details on how to install the database on the same page. *Note*: Before compiling the example code, make sure that you have added References to your project as required. The References required are `System', `System.Data' and `MySql.Data'.  File: manual.info, Node: connector-net-tutorials-connection, Next: connector-net-tutorials-sql-command, Prev: connector-net-tutorials-intro, Up: connector-net-tutorials-intro 21.2.4.2 The MySqlConnection Object ................................... For your Connector/Net application to connect to a MySQL database, it must establish a connection by using a `MySqlConnection' object. The `MySqlConnection' constructor takes a connection string as one of its parameters. The connection string provides necessary information to make the connection to the MySQL database. The connection string is discussed more fully in *Note connector-net-programming-connecting::. For a list of supported connection string options, see *Note connector-net-connection-options::. The following code shows how to create a connection object: using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial1 { public static void Main() { string connStr = "server=localhost;user=root;database=world;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); // Perform database operations } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine("Done."); } } When the `MySqlConnection' constructor is invoked, it returns a connection object, which is used for subsequent database operations. Open the connection before any other operations take place. Before the application exits, close the connection to the database by calling `Close' on the connection object. Sometimes an attempt to perform an `Open' on a connection object can fail, generating an exception that can be handled using standard exception handling code. In this section you have learned how to create a connection to a MySQL database, and open and close the corresponding connection object.  File: manual.info, Node: connector-net-tutorials-sql-command, Next: connector-net-tutorials-data-adapter, Prev: connector-net-tutorials-connection, Up: connector-net-tutorials-intro 21.2.4.3 The MySqlCommand Object ................................ Once a connection has been established with the MySQL database, the next step is do carry out the desired database operations. This can be achieved through the use of the `MySqlCommand' object. You will see how to create a `MySqlCommand' object. Once it has been created, there are three main methods of interest that you can call: * *ExecuteReader* - used to query the database. Results are usually returned in a `MySqlDataReader' object, created by `ExecuteReader'. * *ExecuteNonQuery* - used to insert and delete data. * *ExecuteScalar* - used to return a single value. Once a `MySqlCommand' object has been created, you will call one of the above methods on it to carry out a database operation, such as perform a query. The results are usually returned into a `MySqlDataReader' object, and then processed, for example the results might be displayed. The following code demonstrates how this could be done. using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial2 { public static void Main() { string connStr = "server=localhost;user=root;database=world;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); string sql = "SELECT Name, HeadOfState FROM Country WHERE Continent='Oceania'"; MySqlCommand cmd = new MySqlCommand(sql, conn); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr[0]+" -- "+rdr[1]); } rdr.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine("Done."); } } When a connection has been created and opened, the code then creates a `MySqlCommand' object. Note that the SQL query to be executed is passed to the `MySqlCommand' constructor. The `ExecuteReader' method is then used to generate a `MySqlReader' object. The `MySqlReader' object contains the results generated by the SQL executed on the command object. Once the results have been obtained in a `MySqlReader' object, the results can be processed. In this case, the information is printed out by a `while' loop. Finally, the `MySqlReader' object is disposed of by running its `Close' method on it. In the next example, you will see how to use the `ExecuteNonQuery' method. The procedure for performing an `ExecuteNonQuery' method call is simpler, as there is no need to create an object to store results. This is because `ExecuteNonQuery' is only used for inserting, updating and deleting data. The following example illustrates a simple update to the `Country' table: using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial3 { public static void Main() { string connStr = "server=localhost;user=root;database=world;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); string sql = "INSERT INTO Country (Name, HeadOfState, Continent) VALUES ('Disneyland','Mickey Mouse', 'North America')"; MySqlCommand cmd = new MySqlCommand(sql, conn); cmd.ExecuteNonQuery(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine("Done."); } } The query is constructed, the command object created and the `ExecuteNonQuery' method called on the command object. You can access your MySQL database with the *Note `mysql': mysql. command interpreter and verify that the update was carried out correctly. Finally, you will see how the `ExecuteScalar' method can be used to return a single value. Again, this is straightforward, as a `MySqlDataReader' object is not required to store results, a simple variable will do. The following code illustrates how to use `ExecuteScalar': using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial4 { public static void Main() { string connStr = "server=localhost;user=root;database=world;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); string sql = "SELECT COUNT(*) FROM Country"; MySqlCommand cmd = new MySqlCommand(sql, conn); object result = cmd.ExecuteScalar(); if (result != null) { int r = Convert.ToInt32(result); Console.WriteLine("Number of countries in the World database is: " + r); } } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine("Done."); } } This example uses a simple query to count the rows in the `Country' table. The result is obtained by calling `ExecuteScalar' on the command object.  File: manual.info, Node: connector-net-tutorials-data-adapter, Next: connector-net-tutorials-parameters, Prev: connector-net-tutorials-sql-command, Up: connector-net-tutorials-intro 21.2.4.4 Working with Decoupled Data .................................... Previously, when using `MySqlDataReader', the connection to the database was continually maintained, unless explicitly closed. It is also possible to work in a manner where a connection is only established when needed. For example, in this mode, a connection could be established to read a chunk of data, the data could then be modified by the application as required. A connection could then be reestablished only if and when the application writes data back to the database. This decouples the working data set from the database. This decoupled mode of working with data is supported by Connector/Net. There are several parts involved in allowing this method to work: * *Data Set* - The Data Set is the area in which data is loaded to read or modify it. A `DataSet' object is instantiated, which can store multiple tables of data. * *Data Adapter* - The Data Adapter is the interface between the Data Set and the database itself. The Data Adapter is responsible for efficiently managing connections to the database, opening and closing them as required. The Data Adapter is created by instantiating an object of the `MySqlDataAdapter' class. The `MySqlDataAdapter' object has two main methods: `Fill' which reads data into the Data Set, and `Update', which writes data from the Data Set to the database. * *Command Builder* - The Command Builder is a support object. The Command Builder works in conjunction with the Data Adapter. When a `MySqlDataAdapter' object is created, it is typically given an initial SELECT statement. From this *Note `SELECT': select. statement the Command Builder can work out the corresponding *Note `INSERT': insert, *Note `UPDATE': update. and *Note `DELETE': delete. statements that would be required to update the database. To create the Command Builder, an object of the class `MySqlCommandBuilder' is created. Each of these classes will now be discussed in more detail. *Instantiating a DataSet object* A `DataSet' object can be created simply, as shown in the following example code snippet: DataSet dsCountry; ... dsCountry = new DataSet(); Although this creates the `DataSet' object, it has not yet filled it with data. For that, a Data Adapter is required. *Instantiating a MySqlDataAdapter object* The `MySqlDataAdapter' can be created as illustrated by the following example: MySqlDataAdapter daCountry; ... string sql = "SELECT Code, Name, HeadOfState FROM Country WHERE Continent='North America'"; daCountry = new MySqlDataAdapter (sql, conn); Note, the `MySqlDataAdapter' is given the SQL specifying the data to work with. *Instantiating a MySqlCommandBuilder object* Once the `MySqlDataAdapter' has been created, it is necessary to generate the additional statements required for inserting, updating and deleting data. There are several ways to do this, but in this tutorial you will see how this can most easily be done with `MySqlCommandBuilder'. The following code snippet illustrates how this is done: MySqlCommandBuilder cb = new MySqlCommandBuilder(daCountry); Note that the `MySqlDataAdapter' object is passed as a parameter to the command builder. *Filling the Data Set* To do anything useful with the data from your database, you need to load it into a Data Set. This is one of the jobs of the `MySqlDataAdapter' object, and is carried out with its `Fill' method. The following example code illustrates this: DataSet dsCountry; ... dsCountry = new DataSet(); ... daCountry.Fill(dsCountry, "Country"); Note the `Fill' method is a `MySqlDataAdapter' method, the Data Adapter knows how to establish a connection with the database and retrieve the required data, and then populates the Data Set when the `Fill' method is called. The second parameter `Country' is the table in the Data Set to update. *Updating the Data Set* The data in the Data Set can now be manipulated by the application as required. At some point, changes to data will need to be written back to the database. This is achieved through a `MySqlDataAdapter' method, the `Update' method. daCountry.Update(dsCountry, "Country"); Again, the Data Set and the table within the Data Set to update are specified. *Working Example* The interactions between the `DataSet', `MySqlDataAdapter' and `MySqlCommandBuilder' classes can be a little confusing, so their operation can perhaps be best illustrated by working code. In this example, data from the World database is read into a Data Grid View control. Here, the data can be viewed and changed before clicking an update button. The update button then activates code to write changes back to the database. The code uses the principles explained above. The application was built using the Microsoft Visual Studio to place and create the user interface controls, but the main code that uses the key classes described above is shown below, and is portable. using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; using System.Drawing; using System.Linq; using System.Text; using System.Windows.Forms; using MySql.Data; using MySql.Data.MySqlClient; namespace WindowsFormsApplication5 { public partial class Form1 : Form { MySqlDataAdapter daCountry; DataSet dsCountry; public Form1() { InitializeComponent(); } private void Form1_Load(object sender, EventArgs e) { string connStr = "server=localhost;user=root;database=world;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { label2.Text = "Connecting to MySQL..."; string sql = "SELECT Code, Name, HeadOfState FROM Country WHERE Continent='North America'"; daCountry = new MySqlDataAdapter (sql, conn); MySqlCommandBuilder cb = new MySqlCommandBuilder(daCountry); dsCountry = new DataSet(); daCountry.Fill(dsCountry, "Country"); dataGridView1.DataSource = dsCountry; dataGridView1.DataMember = "Country"; } catch (Exception ex) { label2.Text = ex.ToString(); } } private void button1_Click(object sender, EventArgs e) { daCountry.Update(dsCountry, "Country"); label2.Text = "MySQL Database Updated!"; } } } The application running is shown below: FIGURE GOES HERE: World Database Application  File: manual.info, Node: connector-net-tutorials-parameters, Next: connector-net-tutorials-stored-procedures, Prev: connector-net-tutorials-data-adapter, Up: connector-net-tutorials-intro 21.2.4.5 Working with Parameters ................................ This part of the tutorial shows you how to use parameters in your Connector/Net application. Although it is possible to build SQL query strings directly from user input, this is not advisable as it does not prevent erroneous or malicious information being entered. It is safer to use parameters as they will be processed as field data only. For example, imagine the following query was constructed from user input: string sql = "SELECT Name, HeadOfState FROM Country WHERE Continent = "+user_continent; If the string `user_continent' came from a Text Box control, there would potentially be no control over the string entered by the user. The user could enter a string that generates a runtime error, or in the worst case actually harms the system. When using parameters it is not possible to do this because a parameter is only ever treated as a field parameter, rather than an arbitrary piece of SQL code. The same query written user a parameter for user input would be: string sql = "SELECT Name, HeadOfState FROM Country WHERE Continent = @Continent"; Note that the parameter is preceded by an '@' symbol to indicate it is to be treated as a parameter. As well as marking the position of the parameter in the query string, it is necessary to add a parameter to the Command object. This is illustrated by the following code snippet: cmd.Parameters.AddWithValue("@Continent", "North America"); In this example the string "North America" is supplied as the parameter value statically, but in a more practical example it would come from a user input control. A further example illustrates the complete process: using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial5 { public static void Main() { string connStr = "server=localhost;user=root;database=world;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); string sql = "SELECT Name, HeadOfState FROM Country WHERE Continent=@Continent"; MySqlCommand cmd = new MySqlCommand(sql, conn); Console.WriteLine("Enter a continent e.g. 'North America', 'Europe': "); string user_input = Console.ReadLine(); cmd.Parameters.AddWithValue("@Continent", user_input); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr["Name"]+" --- "+rdr["HeadOfState"]); } rdr.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine("Done."); } } In this part of the tutorial you have see how to use parameters to make your code more secure.  File: manual.info, Node: connector-net-tutorials-stored-procedures, Prev: connector-net-tutorials-parameters, Up: connector-net-tutorials-intro 21.2.4.6 Working with Stored Procedures ....................................... This section illustrates how to work with stored procedures. Putting database-intensive operations into stored procedures lets you define an API for your database application. You can reuse this API across multiple applications and multiple programming languages. This technique avoids duplicating database code, saving time and effort when you make updates due to schema changes, tune the performance of queries, or add new database operations for logging, security, and so on. Before working through this tutorial, familiarize yourself with the *Note `CREATE PROCEDURE': create-procedure. and *Note `CREATE FUNCTION': create-function. statements that create different kinds of stored routines. For the purposes of this tutorial, you will create a simple stored procedure to see how it can be called from Connector/Net. In the MySQL Client program, connect to the World database and enter the following stored procedure: DELIMITER // CREATE PROCEDURE country_hos (IN con CHAR(20)) BEGIN SELECT Name, HeadOfState FROM Country WHERE Continent = con; END // DELIMITER ; Test that the stored procedure works as expected by typing the following into the *Note `mysql': mysql. command interpreter: CALL country_hos('Europe'); Note that The stored routine takes a single parameter, which is the continent to restrict your search to. Having confirmed that the stored procedure is present and correct, you can see how to access it from Connector/Net. Calling a stored procedure from your Connector/Net application is similar to techniques you have seen earlier in this tutorial. A `MySqlCommand' object is created, but rather than taking an SQL query as a parameter, it takes the name of the stored procedure to call. Set the `MySqlCommand' object to the type of stored procedure, as shown by the following code snippet: string rtn = "country_hos"; MySqlCommand cmd = new MySqlCommand(rtn, conn); cmd.CommandType = CommandType.StoredProcedure; In this case, the stored procedure requires you to pass a parameter. This can be achieved using the techniques seen in the previous section on parameters, *Note connector-net-tutorials-parameters::, as shown in the following code snippet: cmd.Parameters.AddWithValue("@con", "Europe"); The value of the parameter `@con' could more realistically have come from a user input control, but for simplicity it is set as a static string in this example. At this point, everything is set up and you can call the routine using techniques also learned in earlier sections. In this case, the `ExecuteReader' method of the `MySqlCommand' object is used. Complete working code for the stored procedure example is shown below: using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial6 { public static void Main() { string connStr = "server=localhost;user=root;database=world;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); string rtn = "country_hos"; MySqlCommand cmd = new MySqlCommand(rtn, conn); cmd.CommandType = CommandType.StoredProcedure; cmd.Parameters.AddWithValue("@con", "Europe"); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr[0] + " --- " + rdr[1]); } rdr.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine("Done."); } } In this section, you have seen how to call a stored procedure from Connector/Net. For the moment, this concludes our introductory tutorial on programming with Connector/Net.  File: manual.info, Node: connector-net-tutorials-asp-roles, Next: connector-net-tutorials-asp-provider-session-state, Prev: connector-net-tutorials-intro, Up: connector-net-tutorials 21.2.4.7 Tutorial: MySQL Connector/Net ASP.NET Membership and Role Provider ........................................................................... Many web sites feature the facility for the user to create a user account. They can then log into the web site and enjoy a personalized experience. This requires that the developer creates database tables to store user information, along with code to gather and process this data. This represents a burden on the developer, and there is the possibility for security issues to creep into the developed code. However, ASP.NET 2.0 introduced the Membership system. This system is designed around the concept of Membership, Profile and Role Providers, which together provide all of the functionality to implement a user system, that previously would have to have been created by the developer from scratch. Currently, MySQL Connector/Net provides Membership, Role, Profile and Session State Providers. This tutorial shows you how to set up your ASP.NET web application to use the MySQL Connector/Net Membership and Role Providers. It assumes that you have MySQL Server installed, along with MySQL Connector/Net and Microsoft Visual Studio. This tutorial was tested with MySQL Connector/Net 6.0.4 and Microsoft Visual Studio 2008 Professional Edition. It is recommended you use 6.0.4 or above for this tutorial. 1. Create a new database in the MySQL Server using the MySQL Command-Line Client program (`mysql'), or other suitable tool. It does not matter what name is used for the database, but record it. You specify it in the connection string constructed later in this tutorial. This database contains the tables, automatically created for you later, used to store data about users and roles. 2. Create a new ASP.NET Web Site in Visual Studio. If you are not sure how to do this, refer to *Note connector-net-tutorials-entity-framework-databinding-linq-entities::, which demonstrates how to create a simple ASP.NET web site. 3. Add References to `MySql.Data' and `MySql.Web' to the web site project. 4. Locate the `machine.config' file on your system, which is the configuration file for the .NET Framework. 5. Search the `machine.config' file to find the membership provider `MySQLMembershipProvider'. 6. Add the attribute `autogenerateschema="true"'. The appropriate section should now resemble the following (note: for the sake of brevity some information has been excluded): Note that the name for the connection string to be used to connect to the server that contains the membership database is `LocalMySqlServer'. The `autogenerateschema="true"' attribute will cause MySQL Connector/Net to silently create, or upgrade, the schema on the database server, to contain the required tables for storing membership information. 7. It is now necessary to create the connection string referenced in the previous step. Load the web site's `web.config' file into Visual Studio. 8. Locate the section marked `'. Add the following connection string information: The database specified is the one created in the first step. You could alternatively have used an existing database. 9. At this point build the solution to ensure no errors are present. This can be done by selecting `Build', `Build Solution' from the main menu, or pressing `F6'. 10. ASP.NET supports the concept of locally and remotely authenticated users. With local authentication the user is validated using their Windows credentials when they attempt to access the web site. This can be useful in an Intranet environment. With remote authentication, a user is prompted for their login details when accessing the web site, and these credentials are checked against the membership information stored in a database server such as MySQL Server. You will now see how to choose this form of authentication. Start the ASP.NET Web Site Administration Tool. This can be done quickly by clicking the small hammer/Earth icon in the Solution Explorer. You can also launch this tool by selecting `Website', `ASP.NET Configuration' from the main menu. 11. In the ASP.NET Web Site Administration Tool click the `Security' tab. 12. Now click the `User Authentication Type' link. 13. Select the `From the internet' radio button. The web site will now need to provide a form to allow the user to enter their login details. These will be checked against membership information stored in the MySQL database. FIGURE GOES HERE: Authentication Type 14. You now need to specify the Role and Membership Provider to be used. Click the `Provider' tab. 15. Click the `Select a different provider for each feature (advanced)' link. 16. Now select the `MySQLMembershipProvider' and the `MySQLRoleProvider' radio buttons. FIGURE GOES HERE: Select Membership and Role Provider 17. In Visual Studio, rebuild the solution by selecting `Build', `Rebuild Solution' from the main menu. 18. Check that the necessary schema has been created. This can be achieved using the *Note `mysql': mysql. command interpreter. FIGURE GOES HERE: Membership and Role Provider Tables 19. Assuming all is present and correct, you can now create users and roles for your web application. The easiest way to do this is with the ASP.NET Web Site Administration Tool. However, many web applications contain their own modules for creating roles and users. For simplicity, the ASP.NET Web Site Administration Tool will be used in this tutorial. 20. In the ASP.NET Web Site Administration Tool, click the `Security' tab. Now that both the Membership and Role Provider are enabled, you will see links for creating roles and users. Click the `Create or Manage Roles' link. FIGURE GOES HERE: Security Tab 21. You can now enter the name of a new Role and click `Add Role' to create the new Role. Create new Roles as required. 22. Click the `Back' button. 23. Click the `Create User' link. You can now fill in information about the user to be created, and also allocate that user to one or more Roles. FIGURE GOES HERE: Create User 24. Using the *Note `mysql': mysql. command interpreter, you can check that your database has been correctly populated with the Membership and Role data. FIGURE GOES HERE: Membership and Roles Table Contents In this tutorial, you have seen how to set up the MySQL Connector/Net Membership and Role Providers for use in your ASP.NET web application.  File: manual.info, Node: connector-net-tutorials-asp-provider-session-state, Next: connector-net-tutorials-asp-provider-profile, Prev: connector-net-tutorials-asp-roles, Up: connector-net-tutorials 21.2.4.8 Tutorial: MySQL Connector/Net ASP.NET Session State Provider ..................................................................... MySQL Connector/Net from version 6.1 has included a MySQL Session State Provider. This provider enables you to store session state in a MySQL database. The following tutorial shows you how to prepare to use the MySQL Session State Provider, and then store session data into the MySQL database. This tutorial uses Microsoft Visual Studio 2008 Professional Edition, MySQL Connector/Net 6.1.1 and MySQL Server 5.1. This tutorial also assumes you have created an empty database, for example `test', where you will store session data. You could do this using the *Note `mysql': mysql. command interpreter. 1. In Visual Studio, create a new ASP.NET web site. If you are not sure how to do this, refer to the tutorial *Note connector-net-tutorials-entity-framework-databinding-linq-entities::, which demonstrates how to do this. 2. Launch the MySQL MySQL Website Configuration tool. Due to a bug in 6.1.1, this may not appear unless you are connected to a server in the Server Explorer. If you are unfamiliar with the MySQL Website Configuration tool, consider first working through the tutorial in *Note connector-net-website-config::. 3. Navigate through the wizard to the Session State page. Make sure the check box `Use MySQL to manage my ASP.NET session data' is selected. 4. On the same page, configure the connection string to the database that will contain your session data. If this database is empty, MySQL Connector/Net will create the schema required to store session data. 5. Ensure that the check box `Autogenerate Schema' is selected so that MySQL Connector/Net will create the schema in your database to store the session data correctly. 6. Enter the name of your application. 7. Click `Finish'. The MySQL Website Configuration tool will now update your application's `web.config' file with information about the connection string and default providers to be used. In this case, we have selected the MySQL Session State Provider. At this point, you are ready to use the MySQL database to store session data. To test that the set up has worked, you can write a simple program that uses session variables. 1. Open `Default.aspx.cs'. In the `Page_Load' method, add the following code: Session["SessionVariable1"] = "Test string"; 2. Build your solution. 3. Run the solution (without debugging). When the application runs, the provider will autogenerate tables required in the database you chose when setting up the application. 4. Check that the schema was in fact created. Using the MySQL Command-Line Client use the target database and then type `SHOW TABLES;'. You will see that MySQL Connector/Net has created the required schema automatically, as we selected this to happen in the MySQL Website Configuration tool. 5. Now view the contents of these tables by typing `SELECT * FROM my_aspnet_sessions;' in the *Note `mysql': mysql. command interpreter. This will display the session data our application used. Note that this is stored in binary format so some data may not display as expected. At this point, you have installed the Session State Provider and carried out a preliminary test of the installation. You will now work a bit more with the Session State Provider. In this part of the tutorial, you will set and retrieve a session variable. You can work with your existing project. 1. Select the `Default.aspx' and switch to Design View. Add a text box and three buttons. Change the text property for the buttons to `Store Session Variable', `Clear Textbox', and `Show Session Variable'. These will be `Button1', `Button2' and `Button3' respectively. Build your solution to ensure that no errors have been introduced. 2. Still in the Design View, double-click `Button1'. Now to the `Button1_Click' event handler add code some the handler resembles the following: protected void Button1_Click(object sender, EventArgs e) { Session["SessionString"] = TextBox1.Text; } You have created a new Session variable accessed using the key `SessionString'. This will be set to the text that was entered into the text box when `Button1' is clicked. 3. In Design View, double-click `Button2' to add its click event handler. This button needs to clear text from the text box. The code to do this is as follows: protected void Button2_Click(object sender, EventArgs e) { TextBox1.Text = ""; } The code simply assigns an empty string to the `Text' property of the text box. 4. In the Design View double-click `Button3' and modify the click handler as follows: protected void Button3_Click(object sender, EventArgs e) { TextBox1.Text = (String)Session["SessionString"]; } This will retrieve the session string and display it in the text box. 5. Now modify the `Page_Load' method as follows: protected void Page_Load(object sender, EventArgs e) { if (!IsPostBack) { TextBox1.Text = "Enter some text"; } } This ensures that when the page loads the text box `Text' property is reset. 6. Ensure that the solution is saved and then rebuild the solution. 7. Run the solution without debugging. 8. The form will be displayed. Enter some text into the text box. Now click `Store Session Variable'. At this point you have stored the string in a session variable. 9. Now click `Clear Text' to clear the text box. 10. Now click `Show Session Variable' to retrieve and display the session variable. 11. Refresh the page to destroy the form and display a new form. 12. Click `Show Session Variable' the text box will display the stored session variable, demonstrating that the refreshing the page does not destroy the session variable. This illustrates that the session state data is not destroyed when a page is reloaded.  File: manual.info, Node: connector-net-tutorials-asp-provider-profile, Next: connector-net-tutorials-entity-framework-winform-data-source, Prev: connector-net-tutorials-asp-provider-session-state, Up: connector-net-tutorials 21.2.4.9 Tutorial: MySQL Connector/Net ASP.NET Profile Provider ............................................................... This tutorial shows you how to use the MySQL Profile Provider to store user profile information in a MySQL database. The tutorial uses MySQL Connector/Net 6.1.1, MySQL Server 5.1 and Microsoft Visual Studio 2008 Professional Edition. Many modern web sites allow the user to create a personal profile. This requires a significant amount of code, but ASP.NET reduces this considerable by including the functionality in its Profile classes. The Profile Provider provides an abstraction between these classes and a data source. The MySQL Profile Provider enables profile data to be stored in a MySQL database. This enables the profile properties to be written to a persistent store, and be retrieved when required. The Profile Provider also enables profile data to be managed effectively, for example it enables profiles that have not been accessed since a specific date to be deleted. The following steps show you how you can select the MySQL Profile Provider. 1. Create a new ASP.NET web project. 2. Select the MySQL Website Configuration tool. Due to a bug in 6.1.1 you may have to first connect to a server in Server Explorer before the tool's icon will display in the toolbar of the Solution Explorer. 3. In the MySQL Website Configuration tool navigate through the tool to the Profiles page. 4. Select the `Use MySQL to manage my profiles' check box. 5. Select the `Autogenerate Schema' check box. 6. Click the `Edit...' button and configure a connection string for the database that will be used to store user profile information. 7. Navigate to the last page of the tool and click `Finish' to save your changes and exit the tool. At this point you are now ready to start using the MySQL Profile Provider. With the following steps you can carry out a preliminary test of your installation. 1. Open your `web.config' file. 2. Add a simple profile such as the following: ... ... Note that `anonymousIdentification' has been set to true. This enables users who have not been authenticated to use profiles. They are identified by a GUID in a cookie rather than by user name. Now that the simple profile has been defined in `web.config', the next step is to write some code to test the profile. 1. In Design View design a simple page with the following controls: FIGURE GOES HERE: Simple Profile Application These will allow the user to enter some profile information. The user can also use the buttons to save their profile, clear the page, and restore their profile data. 2. In the Code View add code as follows: ... protected void Page_Load(object sender, EventArgs e) { if (!IsPostBack) { TextBox1.Text = Profile.Name; TextBox2.Text = Profile.Age.ToString(); Label1.Text = Profile.UI.Color; } } // Store Profile protected void Button1_Click(object sender, EventArgs e) { Profile.Name = TextBox1.Text; Profile.Age = UInt16.Parse(TextBox2.Text); } // Clear Form protected void Button2_Click(object sender, EventArgs e) { TextBox1.Text = ""; TextBox2.Text = ""; Label1.Text = ""; } // Retrieve Profile protected void Button3_Click(object sender, EventArgs e) { TextBox1.Text = Profile.Name; TextBox2.Text = Profile.Age.ToString(); Label1.Text = Profile.UI.Color; } protected void DropDownList1_SelectedIndexChanged(object sender, EventArgs e) { Profile.UI.Color = DropDownList1.SelectedValue; } ... 3. Save all files and build the solution to check that no errors have been introduced. 4. Run the application. 5. Enter your name, age and select a color from the listbox. Now store this information in your profile by clicking `Store Profile'. Note that if you do not select a color from the listbox your profile will use the default color `Blue' that was specified in the `web.config' file. 6. Click `Clear Form' to clear text from the textboxes and the label that displays your chosen color. 7. Now click `Retrieve Profile' to restore your profile data from the MySQL database. 8. Now exit the browser to terminate the application. 9. Run the application again. Note that when the page loads your profile information is restored from the MySQL database. In this tutorial you have seen how to using the MySQL Profile Provider with MySQL Connector/Net.  File: manual.info, Node: connector-net-tutorials-entity-framework-winform-data-source, Next: connector-net-tutorials-entity-framework-databinding-linq-entities, Prev: connector-net-tutorials-asp-provider-profile, Up: connector-net-tutorials 21.2.4.10 Tutorial: Using an Entity Framework Entity as a Windows Forms Data Source ................................................................................... In this tutorial you will learn how to create a Windows Forms Data Source from an Entity in an Entity Data Model. This tutorial assumes that you have installed the World example database, which can be downloaded from the MySQL Documentation page (http://dev.mysql.com/doc/index-other.html). You can also find details on how to install the database on the same page. It will also be convenient for you to create a connection to the World database after it is installed. For instructions on how to do this see *Note connector-net-visual-studio-making-a-connection::. *Creating a new Windows Forms application* The first step is to create a new Windows Forms application. 1. In Visual Studio, select `File', `New', `Project' from the main menu. 2. Choose the `Windows Forms Application' installed template. Click `OK'. The solution is created. *Adding an Entity Data Model* You will now add an Entity Data Model to your solution. 1. In the Solution Explorer, right-click your application and select `Add', `New Item...'. From `Visual Studio installed templates' select `ADO.NET Entity Data Model'. Click `Add'. FIGURE GOES HERE: Add Entity Data Model 2. You will now see the Entity Data Model Wizard. You will use the wizard to generate the Entity Data Model from the world example database. Select the icon ` Generate from database'. Click `Next'. FIGURE GOES HERE: Entity Data Model Wizard Screen 1 3. You can now select the connection you made earlier to the World database. If you have not already done so, you can create the new connection at this time by clicking `New Connection...'. For further instructions on creating a connection to a database see *Note connector-net-visual-studio-making-a-connection::. FIGURE GOES HERE: Entity Data Model Wizard Screen 2 4. Make a note of the entity connection settings to be used in App.Config, as these will be used later to write the necessary control code. 5. Click `Next'. 6. The Entity Data Model Wizard connects to the database. You are then presented with a tree structure of the database. From this you can select the object you would like to include in your model. If you had created Views and Stored Routines these will be displayed along with any tables. In this example you just need to select the tables. Click `Finish' to create the model and exit the wizard. FIGURE GOES HERE: Entity Data Model Wizard Screen 3 7. Visual Studio will generate the model and then display it. FIGURE GOES HERE: Entity Data Model Diagram 8. From the Visual Studio main menu select `Build', `Build Solution', to ensure that everything compiles correctly so far. *Adding a new Data Source* You will now add a new Data Source to your project and see how it can be used to read and write to the database. 1. From the Visual Studio main menu select `Data', `Add New Data Source...'. You will be presented with the Data Source Configuration Wizard. FIGURE GOES HERE: Entity Data Source Configuration Wizard Screen 1 2. Select the `Object' icon. Click `Next'. 3. You will now select the Object to bind to. Expand the tree. In this tutorial, you will select the city table. Once the city table has been selected click `Next'. FIGURE GOES HERE: Entity Data Source Configuration Wizard Screen 2 4. The wizard will confirm that the city object is to be added. Click `Finish'. FIGURE GOES HERE: Entity Data Source Configuration Wizard Screen 3 5. The city object will be display in the Data Sources panel. If the Data Sources panel is not displayed, select `Data', `Show Data Sources' from the Visual Studio main menu. The docked panel will then be displayed. FIGURE GOES HERE: Data Sources *Using the Data Source in a Windows Form* You will now learn how to use the Data Source in a Windows Form. 1. In the Data Sources panel select the Data Source you just created and drag and drop it onto the Form Designer. By default the Data Source object will be added as a Data Grid View control. Note that the Data Grid View control is bound to the `cityBindingSource' and the Navigator control is bound to `cityBindingNavigator'. FIGURE GOES HERE: Data Form Designer 2. Save and rebuild the solution before continuing. *Adding Code to Populate the Data Grid View* You are now ready to add code to ensure that the Data Grid View control will be populated with data from the City database table. 1. Double-click the form to access its code. 2. Add code to instantiate the Entity Data Model's EntityContainer object and retrieve data from the database to populate the control. FIGURE GOES HERE: Adding Code to the Form 3. Save and rebuild the solution. 4. Run the solution. Ensure the grid is populated and you can navigate the database. FIGURE GOES HERE: The Populated Grid Control *Adding Code to Save Changes to the Database* You will now add code to enable you to save changes to the database. The Binding source component ensures that changes made in the Data Grid View control are also made to the Entity classes bound to it. However, that data needs to be saved back from the entities to the database itself. This can be achieved by the enabling of the Save button in the Navigator control, and the addition of some code. 1. In the Form Designer, click the Save icon in the Form toolbar and ensure that its Enabled property is set to True. FIGURE GOES HERE: Save Button Enabled 2. Double-click the Save icon in the Form toolbar to display its code. 3. You now need to add code to ensure that data is saved to the database when the save button is clicked in the application. FIGURE GOES HERE: Adding Save Code to the Form 4. Once the code has been added, save the solution and rebuild it. Run the application and verify that changes made in the grid are saved.  File: manual.info, Node: connector-net-tutorials-entity-framework-databinding-linq-entities, Next: connector-net-tutorials-ssl, Prev: connector-net-tutorials-entity-framework-winform-data-source, Up: connector-net-tutorials 21.2.4.11 Tutorial: Databinding in ASP.NET Using LINQ on Entities ................................................................. In this tutorial you create an ASP.NET web page that binds LINQ queries to entities using the Entity Framework mapping. If you have not already done so, install the World example database prior to attempting this tutorial. See the tutorial *Note connector-net-tutorials-entity-framework-winform-data-source:: for instructions on downloading and installing this database. *Creating an ASP.NET web site* In this part of the tutorial, you create an ASP.NET web site. The web site uses the World database. The main web page features a drop down list from which you can select a country. Data about that country's cities is then displayed in a grid view control. 1. From the Visual Studio main menu select `File', `New', `Web Site...'. 2. From the Visual Studio installed templates select `ASP.NET Web Site'. Click `OK'. You will be presented with the Source view of your web page by default. 3. Click the Design view tab situated underneath the Source view panel. FIGURE GOES HERE: The Design Tab 4. In the Design view panel, enter some text to decorate the blank web page. 5. Click Toolbox. From the list of controls select `DropDownList'. Drag and drop the control to a location beneath the text on your web page. FIGURE GOES HERE: Drop Down List 6. From the `DropDownList' control's context menu, ensure that the `Enable AutoPostBack' check box is enabled. This will ensure the control's event handler is called when an item is selected. The user's choice will in turn be used to populate the `GridView' control. FIGURE GOES HERE: Enable AutoPostBack 7. From the Toolbox select the `GridView' control. FIGURE GOES HERE: Grid View Control Drag and drop the Grid Vew control to a location just below the Drop Down List you already placed. FIGURE GOES HERE: Placed Grid Vew Control 8. At this point it is recommended that you save your solution, and build the solution to ensure that there are no errors. 9. If you run the solution you will see that the text and drop down list are displayed, but the list is empty. Also, the grid view does not appear at all. Adding this functionality is described in the following sections. At this stage you have a web site that will build, but further functionality is required. The next step will be to use the Entity Framework to create a mapping from the World database into entities that you can control programmatically. *Creating an ADO.NET Entity Data Model* In this stage of the tutorial you will add an ADO.NET Entity Data Model to your project, using the World database at the storage level. The procedure for doing this is described in the tutorial *Note connector-net-tutorials-entity-framework-winform-data-source::, and so will not be repeated here. *Populating a Drop Data List Box with using the results of a entity LINQ query* In this part of the tutorial you will write code to populate the DropDownList control. When the web page loads the data to populate the list will be achieved by using the results of a LINQ query on the model created previously. 1. In the Design view panel, double-click any blank area. This brings up the Page_Load method. 2. Modify the relevant section of code according to the following listing: ... public partial class _Default : System.Web.UI.Page { worldModel.worldEntities we; protected void Page_Load(object sender, EventArgs e) { we = new worldModel.worldEntities(); if (!IsPostBack) { var countryQuery = from c in we.country orderby c.Name select new { c.Code, c.Name }; DropDownList1.DataValueField = "Code"; DropDownList1.DataTextField = "Name"; DropDownList1.DataSource = countryQuery; DataBind(); } } ... Note that the list control only needs to be populated when the page first loads. The conditional code ensures that if the page is subsequently reloaded, the list control is not repopulated, which would cause the user selection to be lost. 3. Save the solution, build it and run it. You should see the list control has been populated. You can select an item, but as yet the grid view control does not appear. At this point you have a working Drop Down List control, populated by a LINQ query on your entity data model. *Populating a Grid View control using an entity LINQ query* In the last part of this tutorial you will populate the Grid View Control using a LINQ query on your entity data model. 1. In the Design view, double-click the `DropDownList' control. This causes its SelectedIndexChanged code to be displayed. This method is called when a user selects an item in the list control and thus fires an AutoPostBack event. 2. Modify the relevant section of code accordingly to the following listing: ... protected void DropDownList1_SelectedIndexChanged(object sender, EventArgs e) { var cityQuery = from c in we.city where c.CountryCode == DropDownList1.SelectedValue orderby c.Name select new { c.Name, c.Population, c.CountryCode }; GridView1.DataSource = cityQuery; DataBind(); } ... The grid view control is populated from the result of the LINQ query on the entity data model. 3. As a check compare your code to that shown in the following screenshot: FIGURE GOES HERE: Source Code 4. Save, build and run the solution. As you select a country you will see its cities are displayed in the grid view control. FIGURE GOES HERE: The Working Web Site In this tutorial you have seen how to create an ASP.NET web site, you have also seen how you can access a MySQL database using LINQ queries on an entity data model.  File: manual.info, Node: connector-net-tutorials-ssl, Next: connector-net-tutorials-mysqlscript, Prev: connector-net-tutorials-entity-framework-databinding-linq-entities, Up: connector-net-tutorials 21.2.4.12 Tutorial: Using SSL with MySQL Connector/Net ...................................................... In this tutorial you will learn how you can use MySQL Connector/Net to connect to a MySQL server configured to use SSL. Support for SSL client certificates was added with MySQL Connector/Net 6.2. MySQL Server uses the PEM format for certificates and private keys. This tutorial will use the test certificates from the server test suite by way of example. You can obtain the MySQL Server source code from MySQL Downloads (http://dev.mysql.com/downloads/mysql/5.1.html#source). The certificates can be found in the directory `./mysql-test/std_data'. To carry out the steps in this tutorial, you must have Open SSL installed. This can be downloaded for Microsoft Windows at no charge from Shining Light Productions (http://www.slproweb.com/products/Win32OpenSSL.html). Further details on the connection string options used in this tutorial can be found at *Note connector-net-connection-options::. *Configuring the MySQL Server to use SSL* 1. In the MySQL Server configuration file, set the SSL parameters as follows: ssl-ca=path/to/repo/mysql-test/std_data/cacert.pem ssl-cert=path/to/repo/mysql-test/std_data/server-cert.pem ssl-key=path/to/repo/mysql-test/std_data/server-key.pem Adjust the directories according to the location in which you installed the MySQL source code. 2. In this step you create a test user and set the user to require SSL. Using the MySQL Command-Line Client, connect as `root' and create the user `sslclient'. 3. To set privileges and requirements, issue the following command: GRANT ALL PRIVILEGES ON *.* TO sslclient@'%' REQUIRE SSL; * Creating a certificate file to use with the .NET client* 1. The .NET client does not use the PEM file format, as .NET does not support this format natively. You will be using test client certificates from the same server repository, for the purposes of this example. Convert these to PFX format first. This format is also known as PKCS#12. An article describing this procedure can be found at the Citrix website (http://support.citrix.com/article/CTX106630). From the directory `SERVER-REPOSITORY-ROOT/mysql-test/std_data', issue the following command: openssl pkcs12 -export -in client-cert.pem -inkey client-key.pem -certfile cacert.pem -out client.pfx 2. When asked for an export password, enter the password `pass'. The file `client.pfx' will be generated. This file is used in the remainder of the tutorial. *Connecting to the server using a file-based certificate* 1. You will use PFX file, `client.pfx' you created in the previous step to authenticate the client. The following example demonstrates how to connect using the `SSL Mode', `CertificateFile' and `CertificatePassword' connection string options: using (MySqlConnection connection = new MySqlConnection( "database=test;user=sslclient;" + "CertificateFile=H:\\bzr\\mysql-trunk\\mysql-test\\std_data\\client.pfx" + "CertificatePassword=pass;" + "SSL Mode=Required ")) { connection.Open(); } The path to the certificate file will need to be changed to reflect your individual installation. *Connecting to the server using a store-based certificate* 1. The first step is to import the PFX file, `client.pfx', into the Personal Store. Double-click the file in Windows explorer. This launches the Certificate Import Wizard. 2. Follow the steps dictated by the wizard, and when prompted for the password for the PFX file, enter `pass'. 3. Click `Finish' to close the wizard and import the certificate into the personal store. *Examine certificates in the Personal Store* 1. Start the Microsoft Management Console by entering `mmc.exe' at a command prompt. 2. Select `File', `Add/Remove snap-in'. Click `Add'. Select `Certificates' from the list of available snap-ins in the dialog. 3. Click `Add' button in the dialog, and select the `My user account' radio button. This is used for personal certificates. 4. Click the `Finish' button. 5. Click `OK' to close the Add/Remove Snap-in dialog. 6. You will now have `Certificates - Current User' displayed in the left panel of the Microsoft Management Console. Expand the Certificates - Current User tree item and select `Personal', `Certificates'. The right-hand panel will display a certificate issued to MySQL. This is the certificate that was previously imported. Double-click the certificate to display its details. 7. After you have imported the certificate to the Personal Store, you can use a more succint connection string to connect to the database, as illustrated by the following code: using (MySqlConnection connection = new MySqlConnection( "database=test;user=sslclient;" + "Certificate Store Location=CurrentUser;" + "SSL Mode=Required")) { connection.Open(); } *Certificate Thumbprint Parameter* If you have a large number of certificates in your store, and many have the same Issuer, this can be a source of confusion and result in the wrong certificate being used. To alleviate this situation, there is an optional Certificate Thumbprint parameter that can additionally be specified as part of the connection string. As mentioned before, you can double-click a certificate in the Microsoft Management Console to display the certificate's details. When the Certificate dialog is displayed click the `Details' tab and scroll down to see the thumbprint. The thumbprint will typically be a number such as `‎47 94 36 00 9a 40 f3 01 7a 14 5c f8 47 9e 76 94 d7 aa de f0'. This thumbprint can be used in the connection string, as the following code illustrates: using (MySqlConnection connection = new MySqlConnection( "database=test;user=sslclient;" + "Certificate Store Location=CurrentUser;" + "Certificate Thumbprint=479436009a40f3017a145cf8479e7694d7aadef0;"+ "SSL Mode=Required")) { connection.Open(); } Spaces in the thumbprint parameter are optional and the value is case-insensitive.  File: manual.info, Node: connector-net-tutorials-mysqlscript, Next: connector-net-tutorials-efmodel-ddl, Prev: connector-net-tutorials-ssl, Up: connector-net-tutorials 21.2.4.13 Tutorial: Using MySqlScript ..................................... * Menu: * connector-net-tutorials-mysqlscript-delimiter:: Using Delimiters with MySqlScript This tutorial teaches you how to use the MySqlScript class. This class enables you to execute a series of statements. Depending on the circumstances, this can be more convenient than using the MySqlCommand approach. Further details of the MySqlScript class can be found in the reference documentation supplied with MySQL Connector/Net. To run the example programs in this tutorial, set up a simple test database and table using the *Note `mysql': mysql. Command-Line Client or MySQL Workbench. Commands for the *Note `mysql': mysql. Command-Line Client are given here: CREATE DATABASE TestDB; USE TestDB; CREATE TABLE TestTable (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100)); The main method of the MySqlScript class is the Execute method. This method causes the script (sequence of statements) assigned to the Query property of the MySqlScript object to be executed. Note the Query property can be set through the MySqlScript constructor or using the Query property. Execute returns the number of statements executed. The MySqlScript object will execute the specified script on the connection set using the Connection property. Again, this property can be set directly or through the MySqlScript constructor. The following code snippets illustrate this: string sql = "SELECT * FROM TestTable"; ... MySqlScript script = new MySqlScript(conn, sql); ... MySqlScript script = new MySqlScript(); script.Query = sql; script.Connection = conn; ... script.Execute(); The MySqlScript class has several events associated with it. There are: 1. Error - generated if an error occurs. 2. ScriptCompleted - generated when the script successfully completes execution. 3. StatementExecuted - generated after each statement is executed. It is possible to assign event handlers to each of these events. These user-provided routines are called back when the connected event occurs. The following code shows how the event handlers are set up. script.Error += new MySqlScriptErrorEventHandler(script_Error); script.ScriptCompleted += new EventHandler(script_ScriptCompleted); script.StatementExecuted += new MySqlStatementExecutedEventHandler(script_StatementExecuted); In VisualStudio, you can save typing by using tab completion to fill out stub routines. Start by typing, for example, `script.Error +='. Then press `TAB', and then press `TAB' again. The assignment is completed, and a stub event handler created. A complete working example is shown below: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; namespace MySqlScriptTest { class Program { static void Main(string[] args) { string connStr = "server=localhost;user=root;database=TestDB;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); string sql = "INSERT INTO TestTable(name) VALUES ('Superman');" + "INSERT INTO TestTable(name) VALUES ('Batman');" + "INSERT INTO TestTable(name) VALUES ('Wolverine');" + "INSERT INTO TestTable(name) VALUES ('Storm');"; MySqlScript script = new MySqlScript(conn, sql); script.Error += new MySqlScriptErrorEventHandler(script_Error); script.ScriptCompleted += new EventHandler(script_ScriptCompleted); script.StatementExecuted += new MySqlStatementExecutedEventHandler(script_StatementExecuted); int count = script.Execute(); Console.WriteLine("Executed " + count + " statement(s)."); Console.WriteLine("Delimiter: " + script.Delimiter); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine("Done."); } static void script_StatementExecuted(object sender, MySqlScriptEventArgs args) { Console.WriteLine("script_StatementExecuted"); } static void script_ScriptCompleted(object sender, EventArgs e) { /// EventArgs e will be EventArgs.Empty for this method Console.WriteLine("script_ScriptCompleted!"); } static void script_Error(Object sender, MySqlScriptErrorEventArgs args) { Console.WriteLine("script_Error: " + args.Exception.ToString()); } } } Note that in the script_ScriptCompleted event handler, the EventArgs parameter `e' will be `EventArgs.Empty'. In the case of the `ScriptCompleted' event there is no additional data to be obtained, which is why the event object is `EventArgs.Empty'.  File: manual.info, Node: connector-net-tutorials-mysqlscript-delimiter, Prev: connector-net-tutorials-mysqlscript, Up: connector-net-tutorials-mysqlscript 21.2.4.14 Using Delimiters with MySqlScript ........................................... Depending on the nature of the script, you may need control of the delimiter used to separate the statements that will make up a script. The most common example of this is where you have a multi-statement stored routine as part of your script. In this case if the default delimiter of `;' is used you will get an error when you attempt to execute the script. For example, consider the following stored routine: CREATE PROCEDURE test_routine() BEGIN SELECT name FROM TestTable ORDER BY name; SELECT COUNT(name) FROM TestTable; END This routine actually needs to be executed on the MySQL Server as a single statement. However, with the default delimiter of `;', the MySqlScript class would interpret the above as two statements, the first being: CREATE PROCEDURE test_routine() BEGIN SELECT name FROM TestTable ORDER BY name; Executing this as a statement would generate an error. To solve this problem MySqlScript supports the ability to set a different delimiter. This is achieved through the Delimiter property. For example, you could set the delimiter to `??', in which case the above stored routine would no longer generate an error when executed. Multiple statements can be delimited in the script, so for example, you could have a three statement script such as: string sql = "DROP PROCEDURE IF EXISTS test_routine??" + "CREATE PROCEDURE test_routine() " + "BEGIN " + "SELECT name FROM TestTable ORDER BY name;" + "SELECT COUNT(name) FROM TestTable;" + "END??" + "CALL test_routine()"; You can change the delimiter back at any point by setting the Delimiter property. The following code shows a complete working example: using System; using System.Collections.Generic; using System.Linq; using System.Text; using MySql.Data; using MySql.Data.MySqlClient; namespace ConsoleApplication8 { class Program { static void Main(string[] args) { string connStr = "server=localhost;user=root;database=TestDB;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); string sql = "DROP PROCEDURE IF EXISTS test_routine??" + "CREATE PROCEDURE test_routine() " + "BEGIN " + "SELECT name FROM TestTable ORDER BY name;" + "SELECT COUNT(name) FROM TestTable;" + "END??" + "CALL test_routine()"; MySqlScript script = new MySqlScript(conn); script.Query = sql; script.Delimiter = "??"; int count = script.Execute(); Console.WriteLine("Executed " + count + " statement(s)"); script.Delimiter = ";"; Console.WriteLine("Delimiter: " + script.Delimiter); Console.WriteLine("Query: " + script.Query); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine("Done."); } } }  File: manual.info, Node: connector-net-tutorials-efmodel-ddl, Prev: connector-net-tutorials-mysqlscript, Up: connector-net-tutorials 21.2.4.15 Tutorial: Generating MySQL DDL from an Entity Framework Model ....................................................................... In this tutorial, you will learn how to create MySQL DDL (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_ddl) from an Entity Framework model. Use Visual Studio 2010 and MySQL Connector/Net 6.3 to carry out this tutorial. 1. Create a new console application in Visual Studio 2010. 2. Using the `Solution Explorer', add a reference to `MySql.Data.Entity'. 3. From the `Solution Explorer' select `Add', `New Item'. In the `Add New Item' dialog select `Online Templates'. Select `ADO.NET Entity Data Model' and click `Add'. The `Entity Data Model' dialog will be displayed. 4. In the `Entity Data Model' dialog select `Empty Model'. Click `Finish'. A blank model will be created. 5. Create a simple model. A single Entity will do for the purposes of this tutorial. 6. In the `Properties' panel select `ConceptualEntityModel' from the drop-down listbox. 7. In the `Properties' panel, locate the `DDL Generation Template' in the category `Database Script Generation'. 8. For the `DDL Generation' property select `SSDLToMySQL.tt(VS)' from the drop-down listbox. 9. Save the solution. 10. Right-click an empty space in the model design area. The context-sensitive menu will be displayed. 11. From the context-sensitive menu select `Generate Database from Model'. The `Generate Database Wizard' dialog will be displayed. 12. In the `Generate Database Wizard' dialog select an existing connection, or create a new connection to a server. Select an appropriate radio button to show or hide sensitive data. For the purposes of this tutorial you can select `Yes' (although you might skip this for commercial applications). 13. Click `Next'. MySQL compatible DDL code will be generated. Click `Finish' to exit the wizard. You have seen how to create MySQL DDL code from an Entity Framework model.  File: manual.info, Node: connector-net-programming, Next: connector-net-connection-options, Prev: connector-net-tutorials, Up: connector-net 21.2.5 Connector/Net Programming -------------------------------- * Menu: * connector-net-programming-connecting:: Connecting to MySQL Using Connector/Net * connector-net-programming-connecting-connection-string:: Creating a Connector/Net Connection String * connector-net-programming-mysqlcommand:: Using MySqlCommand * connector-net-programming-connection-pooling:: Using Connector/Net with Connection Pooling * connector-net-programming-authentication-windows-native:: Using the Windows Native Authentication Plugin * connector-net-programming-authentication-user-plugin:: Writing a Custom Authentication Plugin * connector-net-programming-tablecaching:: Using Connector/Net with Table Caching * connector-net-programming-prepared:: Using the Connector/Net with Prepared Statements * connector-net-programming-stored:: Accessing Stored Procedures with Connector/Net * connector-net-programming-blob:: Handling BLOB Data With Connector/Net * connector-net-interceptors:: Using the Connector/Net Interceptor Classes * connector-net-programming-datetime:: Handling Date and Time Information in Connector/Net * connector-net-programming-bulk-loader:: Using the `MySqlBulkLoader' Class * connector-net-programming-tracing:: Using the MySQL Connector/Net Trace Source Object * connector-net-programming-binary-issues:: Binary/Nonbinary Issues * connector-net-using-character-sets:: Character Set Considerations for Connector/Net * connector-net-programming-crystal:: Using Connector/Net with Crystal Reports * connector-net-programming-asp-provider:: ASP.NET Provider Model * connector-net-medium-trust:: Working with Partial Trust / Medium Trust Connector/Net comprises several classes that are used to connect to the database, execute queries and statements, and manage query results. The following are the major classes of Connector/Net: * `MySqlCommand': Represents an SQL statement to execute against a MySQL database. * `MySqlCommandBuilder': Automatically generates single-table commands used to reconcile changes made to a DataSet with the associated MySQL database. * `MySqlConnection': Represents an open connection to a MySQL Server database. * `MySqlDataAdapter': Represents a set of data commands and a database connection that are used to fill a data set and update a MySQL database. * `MySqlDataReader': Provides a means of reading a forward-only stream of rows from a MySQL database. * `MySqlException': The exception that is thrown when MySQL returns an error. * `MySqlHelper': Helper class that makes it easier to work with the provider. * `MySqlTransaction': Represents an SQL transaction (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction) to be made in a MySQL database. In the following sections, you will learn about some common use cases for Connector/Net, including BLOB handling, date handling, and using Connector/Net with common tools such as Crystal Reports.  File: manual.info, Node: connector-net-programming-connecting, Next: connector-net-programming-connecting-connection-string, Prev: connector-net-programming, Up: connector-net-programming 21.2.5.1 Connecting to MySQL Using Connector/Net ................................................ All interaction between a .NET application and the MySQL server is routed through a `MySqlConnection' object. Before your application can interact with the server, it must instantiate, configure, and open a `MySqlConnection' object. Even when using the `MySqlHelper' class, a `MySqlConnection' object is created by the helper class. This section describes how to connect to MySQL using the `MySqlConnection' object.  File: manual.info, Node: connector-net-programming-connecting-connection-string, Next: connector-net-programming-mysqlcommand, Prev: connector-net-programming-connecting, Up: connector-net-programming 21.2.5.2 Creating a Connector/Net Connection String ................................................... * Menu: * connector-net-programming-connecting-open:: Opening a Connection * connector-net-programming-connecting-errors:: Handling Connection Errors * connector-net-programming-getschema:: Using GetSchema on a Connection The `MySqlConnection' object is configured using a connection string. A connection string contains several key/value pairs, separated by semicolons. In each key/value pair, the option name and its corresponding value are joined by an equal sign. For the list of option names to use in the connection string, see *Note connector-net-connection-options::. The following is a sample connection string: Server=127.0.0.1;Uid=root;Pwd=12345;Database=test; In this example, the `MySqlConnection' object is configured to connect to a MySQL server at `127.0.0.1', with a user name of `root' and a password of `12345'. The default database for all statements will be the `test' database. *Note*: Using the '@' symbol for parameters is now the preferred approach, although the old pattern of using '?' is still supported. To avoid conflicts when using the '@' symbol in combination with user variables, see the `Allow User Variables' connection string option in *Note connector-net-connection-options::. The `Old Syntax' connection string option has now been deprecated.  File: manual.info, Node: connector-net-programming-connecting-open, Next: connector-net-programming-connecting-errors, Prev: connector-net-programming-connecting-connection-string, Up: connector-net-programming-connecting-connection-string 21.2.5.3 Opening a Connection ............................. Once you have created a connection string it can be used to open a connection to the MySQL server. The following code is used to create a `MySqlConnection' object, assign the connection string, and open the connection. Connector/Net can also connect using the native Windows authentication plugin. See *Note connector-net-programming-authentication-windows-native:: for details. You can further extend the authentication mechanism by writing your own authentication plugin. See *Note connector-net-programming-authentication-user-plugin:: for details. * Visual Basic Example * Dim conn As New MySql.Data.MySqlClient.MySqlConnection Dim myConnectionString as String myConnectionString = "server=127.0.0.1;" _ & "uid=root;" _ & "pwd=12345;" _ & "database=test;" Try conn.ConnectionString = myConnectionString conn.Open() Catch ex As MySql.Data.MySqlClient.MySqlException MessageBox.Show(ex.Message) End Try * C# Example * MySql.Data.MySqlClient.MySqlConnection conn; string myConnectionString; myConnectionString = "server=127.0.0.1;uid=root;" + "pwd=12345;database=test;"; try { conn = new MySql.Data.MySqlClient.MySqlConnection(); conn.ConnectionString = myConnectionString; conn.Open(); } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show(ex.Message); } You can also pass the connection string to the constructor of the `MySqlConnection' class: * Visual Basic Example * Dim myConnectionString as String myConnectionString = "server=127.0.0.1;" _ & "uid=root;" _ & "pwd=12345;" _ & "database=test;" Try Dim conn As New MySql.Data.MySqlClient.MySqlConnection(myConnectionString) conn.Open() Catch ex As MySql.Data.MySqlClient.MySqlException MessageBox.Show(ex.Message) End Try * C# Example * MySql.Data.MySqlClient.MySqlConnection conn; string myConnectionString; myConnectionString = "server=127.0.0.1;uid=root;" + "pwd=12345;database=test;"; try { conn = new MySql.Data.MySqlClient.MySqlConnection(myConnectionString); conn.Open(); } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show(ex.Message); } Once the connection is open it can be used by the other Connector/Net classes to communicate with the MySQL server.  File: manual.info, Node: connector-net-programming-connecting-errors, Next: connector-net-programming-getschema, Prev: connector-net-programming-connecting-open, Up: connector-net-programming-connecting-connection-string 21.2.5.4 Handling Connection Errors ................................... Because connecting to an external server is unpredictable, it is important to add error handling to your .NET application. When there is an error connecting, the `MySqlConnection' class will return a `MySqlException' object. This object has two properties that are of interest when handling errors: * `Message': A message that describes the current exception. * `Number': The MySQL error number. When handling errors, you can your application's response based on the error number. The two most common error numbers when connecting are as follows: * `0': Cannot connect to server. * `1045': Invalid user name and/or password. The following code shows how to adapt the application's response based on the actual error: * Visual Basic Example * Dim myConnectionString as String myConnectionString = "server=127.0.0.1;" _ & "uid=root;" _ & "pwd=12345;" _ & "database=test;" Try Dim conn As New MySql.Data.MySqlClient.MySqlConnection(myConnectionString) conn.Open() Catch ex As MySql.Data.MySqlClient.MySqlException Select Case ex.Number Case 0 MessageBox.Show("Cannot connect to server. Contact administrator") Case 1045 MessageBox.Show("Invalid username/password, please try again") End Select End Try * C# Example * MySql.Data.MySqlClient.MySqlConnection conn; string myConnectionString; myConnectionString = "server=127.0.0.1;uid=root;" + "pwd=12345;database=test;"; try { conn = new MySql.Data.MySqlClient.MySqlConnection(myConnectionString); conn.Open(); } catch (MySql.Data.MySqlClient.MySqlException ex) { switch (ex.Number) { case 0: MessageBox.Show("Cannot connect to server. Contact administrator"); break; case 1045: MessageBox.Show("Invalid username/password, please try again"); break; } } *Important*: Note that if you are using multilanguage databases you must specify the character set in the connection string. If you do not specify the character set, the connection defaults to the `latin1' charset. You can specify the character set as part of the connection string, for example: MySqlConnection myConnection = new MySqlConnection("server=127.0.0.1;uid=root;" + "pwd=12345;database=test;Charset=latin1;");  File: manual.info, Node: connector-net-programming-getschema, Prev: connector-net-programming-connecting-errors, Up: connector-net-programming-connecting-connection-string 21.2.5.5 Using GetSchema on a Connection ........................................ * Menu: * connector-net-programming-getschema-collections:: Collections The `GetSchema()' method of the connection object can be used to retrieve schema information about the database currently connected to. The schema information is returned in the form of a `DataTable'. The schema information is organized into a number of collections. Different forms of the `GetSchema()' method can be used depending on the information required. There are three forms of the `GetSchema()' method: * `GetSchema()' - This call will return a list of available collections. * `GetSchema(String)' - This call returns information about the collection named in the string parameter. If the string `MetaDataCollections' is used then a list of all available collections is returned. This is the same as calling `GetSchema()' without any parameters. * `GetSchema(String, String[])' - In this call the first string parameter represents the collection name, and the second parameter represents a string array of restriction values. Restriction values limit the amount of data that will be returned. Restriction values are explained in more detail in the Microsoft .NET documentation (http://msdn.microsoft.com/en-us/library/ms254934(VS.80).aspx).  File: manual.info, Node: connector-net-programming-getschema-collections, Prev: connector-net-programming-getschema, Up: connector-net-programming-getschema 21.2.5.6 Collections .................... The collections can be broadly grouped into two types: collections that are common to all data providers, and collections specific to a particular provider. *Common* The following collections are common to all data providers: * MetaDataCollections * DataSourceInformation * DataTypes * Restrictions * ReservedWords *Provider-specific* The following are the collections currently provided by MySQL Connector/Net, in addition to the common collections above: * Databases * Tables * Columns * Users * Foreign Keys * IndexColumns * Indexes * Foreign Key Columns * UDF * Views * ViewColumns * Procedure Parameters * Procedures * Triggers *Example Code* A list of available collections can be obtained using the following code: using System; using System.Data; using System.Text; using MySql.Data; using MySql.Data.MySqlClient; namespace ConsoleApplication2 { class Program { private static void DisplayData(System.Data.DataTable table) { foreach (System.Data.DataRow row in table.Rows) { foreach (System.Data.DataColumn col in table.Columns) { Console.WriteLine("{0} = {1}", col.ColumnName, row[col]); } Console.WriteLine("============================"); } } static void Main(string[] args) { string connStr = "server=localhost;user=root;database=world;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); DataTable table = conn.GetSchema("MetaDataCollections"); //DataTable table = conn.GetSchema("UDF"); DisplayData(table); conn.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } Console.WriteLine("Done."); } } } Further information on the `GetSchema()' method and schema collections can be found in the Microsoft .NET documentation (http://msdn.microsoft.com/en-us/library/kcax58fh(VS.80).aspx).  File: manual.info, Node: connector-net-programming-mysqlcommand, Next: connector-net-programming-connection-pooling, Prev: connector-net-programming-connecting-connection-string, Up: connector-net-programming 21.2.5.7 Using MySqlCommand ........................... A `MySqlCommand' has the `CommandText' and `CommandType' properties associated with it. The `CommandText' will be handled differently depending on the setting of `CommandType'. `CommandType' can be one of: 1. Text - A SQL text command (default) 2. StoredProcedure - The name of a Stored Procedure 3. TableDirect - The name of a table (new in Connector/Net 6.2) The default `CommandType', `Text', is used for executing queries and other SQL commands. Some example of this can be found in the following section *Note connector-net-tutorials-sql-command::. If `CommandType' is set to `StoredProcedure', set `CommandText' to the name of the Stored Procedure to access. If `CommandType' is set to `TableDirect', all rows and columns of the named table will be returned when you call one of the Execute methods. In effect, this command performs a `SELECT *' on the table specified. The `CommandText' property is set to the name of the table to query. This is illustrated by the following code snippet: ... MySqlCommand cmd = new MySqlCommand(); cmd.CommandText = "mytable"; cmd.Connection = someConnection; cmd.CommandType = CommandType.TableDirect; MySqlDataReader reader = cmd.ExecuteReader(); while (reader.Read()) { Console.WriteLn(reader[0], reader[1]...); } ... Examples of using the CommandType of StoredProcedure can be found in the section *Note connector-net-programming-stored::. Commands can have a timeout associated with them. This is useful as you may not want a situation were a command takes up an excessive amount of time. A timeout can be set using the `CommandTimeout' property. The following code snippet sets a timeout of one minute: MySqlCommand cmd = new MySqlCommand(); cmd.CommandTimeout = 60; The default value is 30 seconds. Avoid a value of 0, which indicates an indefinite wait. To change the default command timeout, use the connection string option `Default Command Timeout'. Prior to MySQL Connector/Net 6.2, `MySqlCommand.CommandTimeout' included user processing time, that is processing time not related to direct use of the connector. Timeout was implemented through a .NET Timer, that triggered after `CommandTimeout' seconds. This timer consumed a thread. MySQL Connector/Net 6.2 introduced timeouts that are aligned with how Microsoft handles `SqlCommand.CommandTimeout'. This property is the cumulative timeout for all network reads and writes during command execution or processing of the results. A timeout can still occur in the `MySqlReader.Read' method after the first row is returned, and does not include user processing time, only IO operations. The 6.2 implementation uses the underlying stream timeout facility, so is more efficient in that it does not require the additional timer thread as was the case with the previous implementation. Further details on this can be found in the relevant Microsoft documentation (http://msdn.microsoft.com/en-us/library/system.data.sqlclient.sqlcommand.commandtimeout.aspx).  File: manual.info, Node: connector-net-programming-connection-pooling, Next: connector-net-programming-authentication-windows-native, Prev: connector-net-programming-mysqlcommand, Up: connector-net-programming 21.2.5.8 Using Connector/Net with Connection Pooling .................................................... The Connector/Net supports connection pooling for better performance and scalability with database-intensive applications. This is enabled by default. You can turn it off or adjust its performance characteristics using the connection string options `Pooling', `Connection Reset', `Connection Lifetime', `Cache Server Properties', `Max Pool Size' and `Min Pool Size'. See *Note connector-net-programming-connecting-connection-string:: for further information. Connection pooling works by keeping the native connection to the server live when the client disposes of a `MySqlConnection'. Subsequently, if a new `MySqlConnection' object is opened, it will be created from the connection pool, rather than creating a new native connection. This improves performance. * Guidelines * To work as designed, it is best to let the connection pooling system manage all connections. Do not create a globally accessible instance of `MySqlConnection' and then manually open and close it. This interferes with the way the pooling works and can lead to unpredictable results or even exceptions. One approach that simplifies things is to avoid manually creating a `MySqlConnection' object. Instead use the overloaded methods that take a connection string as an argument. Using this approach, Connector/Net will automatically create, open, close and destroy connections, using the connection pooling system for best performance. Typed Datasets and the `MembershipProvider' and `RoleProvider' classes use this approach. Most classes that have methods that take a `MySqlConnection' as an argument, also have methods that take a connection string as an argument. This includes `MySqlDataAdapter'. Instead of manually creating `MySqlCommand' objects, you can use the static methods of the `MySqlHelper' class. These take a connection string as an argument, and they fully support connection pooling. * Resource Usage * Starting with MySQL Connector/Net 6.2, there is a background job that runs every three minutes and removes connections from pool that have been idle (unused) for more than three minutes. The pool cleanup frees resources on both client and server side. This is because on the client side every connection uses a socket, and on the server side every connection uses a socket and a thread. Prior to this change, connections were never removed from the pool, and the pool always contained the peak number of open connections. For example, a web application that peaked at 1000 concurrent database connections would consume 1000 threads and 1000 open sockets at the server, without ever freeing up those resources from the connection pool. Note, connections, no matter how old, will not be closed if the number of connections in the pool is less than or equal to the value set by the `Min Pool Size' connection string parameter.  File: manual.info, Node: connector-net-programming-authentication-windows-native, Next: connector-net-programming-authentication-user-plugin, Prev: connector-net-programming-connection-pooling, Up: connector-net-programming 21.2.5.9 Using the Windows Native Authentication Plugin ....................................................... Connector/Net applications can authenticate to a MySQL server using the Windows Native Authentication Plugin as of Connector/Net 6.4.4 and MySQL 5.5.16/5.6.10. 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 background and usage information about the authentication plugin, see, The Windows Native Authentication Plugin (http://dev.mysql.com/doc/refman/5.5/en/windows-authentication-plugin.html). The interface matches the *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. object. To enable, pass in `Integrated Security' to the connection string with a value of `yes' or `sspi'. Passing in a user ID is optional. When Windows authentication is set up, a MySQL user is created and configured to be used by Windows authentication. By default, this user ID is named `auth_windows', but can be defined using a different name. If the default name is used, then passing the user ID to the connection string from Connector/Net is optional, because it will use the `auth_windows' user. Otherwise, the name must be passed to the *Note connection string: connector-net-programming-connecting-connection-string. using the standard user ID element.  File: manual.info, Node: connector-net-programming-authentication-user-plugin, Next: connector-net-programming-tablecaching, Prev: connector-net-programming-authentication-windows-native, Up: connector-net-programming 21.2.5.10 Writing a Custom Authentication Plugin ................................................ Advanced users with special security requirements can create their own authentication plugins for Connector/Net applications. You can extend the handshake protocol, adding custom logic. This capability requires Connector/Net 6.6.3 or higher, and MySQL 5.5.16 or higher. For background and usage information about MySQL authentication plugins, see, Authentication Plugins (http://dev.mysql.com/doc/refman/5.5/en/authentication-plugins.html) and Writing Authentication Plugins (http://dev.mysql.com/doc/refman/5.5/en/writing-authentication-plugins.html). To write a custom authentication plugin, you will need a reference to the assembly `MySql.Data.dll'. The classes relevant for writing authentication plugins are available at the namespace `MySql.Data.MySqlClient.Authentication'. * How the Custom Authentication Plugin Works * At some point during handshake, the internal method void Authenticate(bool reset) of `MySqlAuthenticationPlugin' is called. This method in turns calls several overridable methods of the current plugin. * Creating the Authentication Plugin Class * You put the authentication plugin logic inside a new class derived from `MySql.Data.MySqlClient.Authentication.MySqlAuthenticationPlugin'. The following methods are available to be overridden: protected virtual void CheckConstraints() protected virtual void AuthenticationFailed(Exception ex) protected virtual void AuthenticationSuccessful() protected virtual byte[] MoreData(byte[] data) protected virtual void AuthenticationChange() public abstract string PluginName { get; } public virtual string GetUsername() public virtual object GetPassword() protected byte[] AuthData; The following is a brief explanation of each one: /// /// This method must check authentication method specific constraints in the environment and throw an Exception /// if the conditions are not met. The default implementation does nothing. /// protected virtual void CheckConstraints() /// /// This method, called when the authentication failed, provides a chance to plugins to manage the error /// the way they consider decide (either showing a message, logging it, etc.). /// The default implementation wraps the original exception in a MySqlException with an standard message and rethrows it. /// /// The exception with extra information on the error. protected virtual void AuthenticationFailed(Exception ex) /// /// This method is invoked when the authentication phase was successful accepted by the server. /// Derived classes must override this if they want to be notified of such condition. /// /// The default implementation does nothing. protected virtual void AuthenticationSuccessful() /// /// This method provides a chance for the plugin to send more data when the server requests so during the /// authentication phase. This method will be called at least once, and more than one depending upon whether the /// server response packets have the 0x01 prefix. /// /// The response data from the server, during the authentication phase the first time is called is null, in subsequent calls contains the server response. /// The data generated by the plugin for server consumption. /// The default implementation always returns null. protected virtual byte[] MoreData(byte[] data) /// /// The plugin name. /// public abstract string PluginName { get; } /// /// Gets the user name to send to the server in the authentication phase. /// /// An string with the user name /// Default implementation returns the UserId passed from the connection string. public virtual string GetUsername() /// /// Gets the password to send to the server in the authentication phase. This can can be an string or a /// /// An object, can be byte[], string or null, with the password. /// Default implementation returns null. public virtual object GetPassword() /// /// The authentication data passed when creating the plugin. /// For example in mysql_native_password this is the seed to encrypt the password. /// protected byte[] AuthData; * Sample Authentication Plugin * Here is an example showing how to create the authentication plugin, then enable it by means of a configuration file. Follow these steps: 1. Create a console app, adding a reference to `MySql.Data.dll'. 2. Design the main program as follows: using System; using System.Collections.Generic; using System.Linq; using System.Text; using MySql.Data.MySqlClient; namespace AuthPluginTest { class Program { static void Main(string[] args) { // Customize the connection string as necessary. MySqlConnection con = new MySqlConnection("server=localhost; database=test; user id=myuser; password=mypass"); con.Open(); con.Close(); } } } 3. Create your plugin class. In this example, we add an `alternative' implementation of the Native password plugin by just using the same code from the original plugin. We name our class `MySqlNativePasswordPlugin2': using System.IO; using System; using System.Text; using System.Security.Cryptography; using MySql.Data.MySqlClient.Authentication; using System.Diagnostics; namespace AuthPluginTest { public class MySqlNativePasswordPlugin2 : MySqlAuthenticationPlugin { public override string PluginName { get { return "mysql_native_password"; } } public override object GetPassword() { Debug.WriteLine("Calling MySqlNativePasswordPlugin2.GetPassword"); return Get411Password(Settings.Password, AuthData); } /// /// Returns a byte array containing the proper encryption of the /// given password/seed according to the new 4.1.1 authentication scheme. /// /// /// /// private byte[] Get411Password(string password, byte[] seedBytes) { // if we have no password, then we just return 1 zero byte if (password.Length == 0) return new byte[1]; SHA1 sha = new SHA1CryptoServiceProvider(); byte[] firstHash = sha.ComputeHash(Encoding.Default.GetBytes(password)); byte[] secondHash = sha.ComputeHash(firstHash); byte[] input = new byte[seedBytes.Length + secondHash.Length]; Array.Copy(seedBytes, 0, input, 0, seedBytes.Length); Array.Copy(secondHash, 0, input, seedBytes.Length, secondHash.Length); byte[] thirdHash = sha.ComputeHash(input); byte[] finalHash = new byte[thirdHash.Length + 1]; finalHash[0] = 0x14; Array.Copy(thirdHash, 0, finalHash, 1, thirdHash.Length); for (int i = 1; i < finalHash.Length; i++) finalHash[i] = (byte)(finalHash[i] ^ firstHash[i - 1]); return finalHash; } } } 4. Notice that the plugin implementation just overrides `GetPassword', and provides an implementation to encrypt the password using the 4.1 protocol. We also put the following line in the `GetPassword' body: Debug.WriteLine("Calling MySqlNativePasswordPlugin2.GetPassword"); to provide confirmation that the plugin was effectively used. (You could also put a breakpoint on that method.) 5. Enable the new plugin in the configuration file:
6. Run the application. In Visual Studio, you will see the message `Calling MySqlNativePasswordPlugin2.GetPassword' in the debug window. 7. Continue enhancing the authentication logic, overriding more methods if you required.  File: manual.info, Node: connector-net-programming-tablecaching, Next: connector-net-programming-prepared, Prev: connector-net-programming-authentication-user-plugin, Up: connector-net-programming 21.2.5.11 Using Connector/Net with Table Caching ................................................ This feature exists with Connector/Net versions 6.4 and above. Table caching is a feature that can be used to cache slow-changing datasets on the client side. This is useful for applications that are designed to use readers, but still want to minimize trips to the server for slow-changing tables. This feature is transparent to the application, and is disabled by default. * Configuration * * To enable table caching, add `*Note 'table cache = true': connector-net-connection-options.' to the connection string. * Optionally, specify the `*Note 'Default Table Cache Age': connector-net-connection-options.' connection string option, which represents the number of seconds a table is cached before the cached data is discarded. The default value is `60'. * You can turn caching on and off and set caching options at runtime, on a per-command basis.  File: manual.info, Node: connector-net-programming-prepared, Next: connector-net-programming-stored, Prev: connector-net-programming-tablecaching, Up: connector-net-programming 21.2.5.12 Using the Connector/Net with Prepared Statements .......................................................... * Menu: * connector-net-programming-prepared-preparing:: Preparing Statements in Connector/Net As of MySQL 4.1, it is possible to use prepared statements with Connector/Net. Use of prepared statements can provide significant performance improvements on queries that are executed more than once. 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. Another advantage of prepared statements is that it uses a binary protocol that makes data transfer between client and server more efficient.  File: manual.info, Node: connector-net-programming-prepared-preparing, Prev: connector-net-programming-prepared, Up: connector-net-programming-prepared 21.2.5.13 Preparing Statements in Connector/Net ............................................... To prepare a statement, create a command object and set the `.CommandText' property to your query. After entering your statement, call the `.Prepare' method of the `MySqlCommand' object. After the statement is prepared, add parameters for each of the dynamic elements in the query. After you enter your query and enter parameters, execute the statement using the `.ExecuteNonQuery()', `.ExecuteScalar()', or `.ExecuteReader' methods. For subsequent executions, you need only modify the values of the parameters and call the execute method again, there is no need to set the `.CommandText' property or redefine the parameters. * Visual Basic Example * Dim conn As New MySqlConnection Dim cmd As New MySqlCommand conn.ConnectionString = strConnection Try conn.Open() cmd.Connection = conn cmd.CommandText = "INSERT INTO myTable VALUES(NULL, @number, @text)" cmd.Prepare() cmd.Parameters.AddWithValue("@number", 1) cmd.Parameters.AddWithValue("@text", "One") For i = 1 To 1000 cmd.Parameters("@number").Value = i cmd.Parameters("@text").Value = "A string value" cmd.ExecuteNonQuery() Next Catch ex As MySqlException MessageBox.Show("Error " & ex.Number & " has occurred: " & ex.Message, "Error", MessageBoxButtons.OK, MessageBoxIcon.Error) End Try * C# Example * MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); conn.ConnectionString = strConnection; try { conn.Open(); cmd.Connection = conn; cmd.CommandText = "INSERT INTO myTable VALUES(NULL, @number, @text)"; cmd.Prepare(); cmd.Parameters.AddWithValue("@number", 1); cmd.Parameters.AddWithValue("@text", "One"); for (int i=1; i <= 1000; i++) { cmd.Parameters["@number"].Value = i; cmd.Parameters["@text"].Value = "A string value"; cmd.ExecuteNonQuery(); } } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show("Error " + ex.Number + " has occurred: " + ex.Message, "Error", MessageBoxButtons.OK, MessageBoxIcon.Error); }  File: manual.info, Node: connector-net-programming-stored, Next: connector-net-programming-blob, Prev: connector-net-programming-prepared, Up: connector-net-programming 21.2.5.14 Accessing Stored Procedures with Connector/Net ........................................................ * Menu: * connector-net-programming-stored-using:: Using Stored Routines from Connector/Net MySQL server version 5 and up supports stored procedures with the SQL 2003 stored procedure syntax. A stored procedure is a set of SQL statements that is stored in the server. Clients make a single call to the stored procedure, passing parameters that can influence the procedure logic and query conditions, rather than issuing individual hardcoded SQL statements. Stored procedures can be particularly useful in situations such as the following: * Stored procedures can act as an API or abstraction layer, allowing multiple client applications to perform the same database operations. The applications can be written in different languages and run on different platforms. The applications do not need to hardcode table and column names, complicated queries, and so on. When you extend and optimize the queries in a stored procedure, all the applications that call the procedure automatically receive the benefits. * When security is paramount, stored procedures keep applications from directly manipulating tables, or even knowing details such as table and column names. Banks, for example, use stored procedures for all common operations. This provides a consistent and secure environment, and procedures can ensure that each operation is properly logged. In such a setup, applications and users would not get any access to the database tables directly, but can only execute specific stored procedures. Connector/Net supports the calling of stored procedures through the `MySqlCommand' object. Data can be passed in and out of a MySQL stored procedure through use of the `MySqlCommand.Parameters' collection. *Note*: When you call a stored procedure, the command object makes an additional *Note `SELECT': select. call to determine the parameters of the stored procedure. You must ensure that the user calling the procedure has the `SELECT' privilege on the `mysql.proc' table to enable them to verify the parameters. Failure to do this will result in an error when calling the procedure. This section will not provide in-depth information on creating Stored Procedures. For such information, please refer to `http://dev.mysql.com/doc/mysql/en/stored-routines.html'. A sample application demonstrating how to use stored procedures with Connector/Net can be found in the `Samples' directory of your Connector/Net installation.  File: manual.info, Node: connector-net-programming-stored-using, Prev: connector-net-programming-stored, Up: connector-net-programming-stored 21.2.5.15 Using Stored Routines from Connector/Net .................................................. Stored procedures in MySQL can be created using a variety of tools. First, stored procedures can be created using the *Note `mysql': mysql. command-line client. Second, stored procedures can be created using MySQL Workbench. Finally, stored procedures can be created using the `.ExecuteNonQuery' method of the `MySqlCommand' object. Unlike the command-line and GUI clients, you are not required to specify a special delimiter when creating stored procedures in Connector/Net. To call a stored procedure using Connector/Net, you create a `MySqlCommand' object and pass the stored procedure name as the `.CommandText' property. You then set the `.CommandType' property to `CommandType.StoredProcedure'. After the stored procedure is named, you create one `MySqlCommand' parameter for every parameter in the stored procedure. `IN' parameters are defined with the parameter name and the object containing the value, `OUT' parameters are defined with the parameter name and the data type that is expected to be returned. All parameters need the parameter direction defined. After defining the parameters, you call the stored procedure by using the `MySqlCommand.ExecuteNonQuery()' method. Once the stored procedure is called, the values of the output parameters can be retrieved by using the `.Value' property of the `MySqlConnector.Parameters' collection. *Note*: When a stored procedure is called using `MySqlCommand.ExecuteReader', and the stored procedure has output parameters, the output parameters are only set after the `MySqlDataReader' returned by `ExecuteReader' is closed. The following C# example code demonstrates the use of stored procedures. It assumes the database 'employees' has already been created: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; namespace UsingStoredRoutines { class Program { static void Main(string[] args) { MySqlConnection conn = new MySqlConnection(); conn.ConnectionString = "server=localhost;user=root;database=employees;port=3306;password=******;"; MySqlCommand cmd = new MySqlCommand(); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); cmd.Connection = conn; cmd.CommandText = "DROP PROCEDURE IF EXISTS add_emp"; cmd.ExecuteNonQuery(); cmd.CommandText = "DROP TABLE IF EXISTS emp"; cmd.ExecuteNonQuery(); cmd.CommandText = "CREATE TABLE emp (empno INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, first_name VARCHAR(20), last_name VARCHAR(20), birthdate DATE)"; cmd.ExecuteNonQuery(); cmd.CommandText = "CREATE PROCEDURE add_emp(" + "IN fname VARCHAR(20), IN lname VARCHAR(20), IN bday DATETIME, OUT empno INT)" + "BEGIN INSERT INTO emp(first_name, last_name, birthdate) " + "VALUES(fname, lname, DATE(bday)); SET empno = LAST_INSERT_ID(); END"; cmd.ExecuteNonQuery(); } catch (MySqlException ex) { Console.WriteLine ("Error " + ex.Number + " has occurred: " + ex.Message); } conn.Close(); Console.WriteLine("Connection closed."); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); cmd.Connection = conn; cmd.CommandText = "add_emp"; cmd.CommandType = CommandType.StoredProcedure; cmd.Parameters.AddWithValue("@lname", "Jones"); cmd.Parameters["@lname"].Direction = ParameterDirection.Input; cmd.Parameters.AddWithValue("@fname", "Tom"); cmd.Parameters["@fname"].Direction = ParameterDirection.Input; cmd.Parameters.AddWithValue("@bday", "1940-06-07"); cmd.Parameters["@bday"].Direction = ParameterDirection.Input; cmd.Parameters.AddWithValue("@empno", MySqlDbType.Int32); cmd.Parameters["@empno"].Direction = ParameterDirection.Output; cmd.ExecuteNonQuery(); Console.WriteLine("Employee number: "+cmd.Parameters["@empno"].Value); Console.WriteLine("Birthday: " + cmd.Parameters["@bday"].Value); } catch (MySql.Data.MySqlClient.MySqlException ex) { Console.WriteLine("Error " + ex.Number + " has occurred: " + ex.Message); } conn.Close(); Console.WriteLine("Done."); } } } The following code shows the same application in Visual Basic: Imports System Imports System.Collections.Generic Imports System.Linq Imports System.Text Imports System.Data Imports MySql.Data Imports MySql.Data.MySqlClient Module Module1 Sub Main() Dim conn As New MySqlConnection() conn.ConnectionString = "server=localhost;user=root;database=world;port=3306;password=******;" Dim cmd As New MySqlCommand() Try Console.WriteLine("Connecting to MySQL...") conn.Open() cmd.Connection = conn cmd.CommandText = "DROP PROCEDURE IF EXISTS add_emp" cmd.ExecuteNonQuery() cmd.CommandText = "DROP TABLE IF EXISTS emp" cmd.ExecuteNonQuery() cmd.CommandText = "CREATE TABLE emp (empno INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, first_name VARCHAR(20), last_name VARCHAR(20), birthdate DATE)" cmd.ExecuteNonQuery() cmd.CommandText = "CREATE PROCEDURE add_emp(" & "IN fname VARCHAR(20), IN lname VARCHAR(20), IN bday DATETIME, OUT empno INT)" & "BEGIN INSERT INTO emp(first_name, last_name, birthdate) " & "VALUES(fname, lname, DATE(bday)); SET empno = LAST_INSERT_ID(); END" cmd.ExecuteNonQuery() Catch ex As MySqlException Console.WriteLine(("Error " & ex.Number & " has occurred: ") + ex.Message) End Try conn.Close() Console.WriteLine("Connection closed.") Try Console.WriteLine("Connecting to MySQL...") conn.Open() cmd.Connection = conn cmd.CommandText = "add_emp" cmd.CommandType = CommandType.StoredProcedure cmd.Parameters.AddWithValue("@lname", "Jones") cmd.Parameters("@lname").Direction = ParameterDirection.Input cmd.Parameters.AddWithValue("@fname", "Tom") cmd.Parameters("@fname").Direction = ParameterDirection.Input cmd.Parameters.AddWithValue("@bday", "1940-06-07") cmd.Parameters("@bday").Direction = ParameterDirection.Input cmd.Parameters.AddWithValue("@empno", MySqlDbType.Int32) cmd.Parameters("@empno").Direction = ParameterDirection.Output cmd.ExecuteNonQuery() Console.WriteLine("Employee number: " & cmd.Parameters("@empno").Value) Console.WriteLine("Birthday: " & cmd.Parameters("@bday").Value) Catch ex As MySql.Data.MySqlClient.MySqlException Console.WriteLine(("Error " & ex.Number & " has occurred: ") + ex.Message) End Try conn.Close() Console.WriteLine("Done.") End Sub End Module  File: manual.info, Node: connector-net-programming-blob, Next: connector-net-interceptors, Prev: connector-net-programming-stored, Up: connector-net-programming 21.2.5.16 Handling BLOB Data With Connector/Net ............................................... * Menu: * connector-net-programming-blob-serverprep:: Preparing the MySQL Server * connector-net-programming-blob-writing:: Writing a File to the Database * connector-net-programming-blob-reading:: Reading a BLOB from the Database to a File on Disk One common use for MySQL is the storage of binary data in *Note `BLOB': blob. columns. MySQL supports four different BLOB data types: `TINYBLOB', `BLOB', `MEDIUMBLOB', and `LONGBLOB', all described in *Note blob:: and *Note storage-requirements::. Data stored in a `BLOB' column can be accessed using Connector/Net and manipulated using client-side code. There are no special requirements for using Connector/Net with `BLOB' data. Simple code examples will be presented within this section, and a full sample application can be found in the `Samples' directory of the Connector/Net installation.  File: manual.info, Node: connector-net-programming-blob-serverprep, Next: connector-net-programming-blob-writing, Prev: connector-net-programming-blob, Up: connector-net-programming-blob 21.2.5.17 Preparing the MySQL Server .................................... The first step is using MySQL with `BLOB' data is to configure the server. Let's start by creating a table to be accessed. In my file tables, I usually have four columns: an `AUTO_INCREMENT' column of appropriate size (`UNSIGNED SMALLINT') to serve as a primary key to identify the file, a `VARCHAR' column that stores the file name, an `UNSIGNED MEDIUMINT' column that stores the size of the file, and a `MEDIUMBLOB' column that stores the file itself. For this example, I will use the following table definition: CREATE TABLE file( file_id SMALLINT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY, file_name VARCHAR(64) NOT NULL, file_size MEDIUMINT UNSIGNED NOT NULL, file MEDIUMBLOB NOT NULL); After creating a table, you might need to modify the `max_allowed_packet' system variable. This variable determines how large of a packet (that is, a single row) can be sent to the MySQL server. By default, the server only accepts a maximum size of 1MB from the client application. If you intend to exceed 1MB in your file transfers, increase this number. The `max_allowed_packet' option can be modified using the MySQL Workbench `Server Administration' screen. Adjust the Maximum permitted option in the `Data / Memory size' section of the Networking tab to an appropriate setting. After adjusting the value, click the `Apply' button and restart the server using the `Startup / Shutdown' screen of MySQL Workbench. You can also adjust this value directly in the `my.cnf' file (add a line that reads `max_allowed_packet=XXM'), or use the `SET max_allowed_packet=XXM;' syntax from within MySQL. Try to be conservative when setting `max_allowed_packet', as transfers of BLOB data can take some time to complete. Try to set a value that will be adequate for your intended use and increase the value if necessary.  File: manual.info, Node: connector-net-programming-blob-writing, Next: connector-net-programming-blob-reading, Prev: connector-net-programming-blob-serverprep, Up: connector-net-programming-blob 21.2.5.18 Writing a File to the Database ........................................ To write a file to a database, we need to convert the file to a byte array, then use the byte array as a parameter to an *Note `INSERT': insert. query. The following code opens a file using a FileStream object, reads it into a byte array, and inserts it into the `file' table: * Visual Basic Example * Dim conn As New MySqlConnection Dim cmd As New MySqlCommand Dim SQL As String Dim FileSize As UInt32 Dim rawData() As Byte Dim fs As FileStream conn.ConnectionString = "server=127.0.0.1;" _ & "uid=root;" _ & "pwd=12345;" _ & "database=test" Try fs = New FileStream("c:\image.png", FileMode.Open, FileAccess.Read) FileSize = fs.Length rawData = New Byte(FileSize) {} fs.Read(rawData, 0, FileSize) fs.Close() conn.Open() SQL = "INSERT INTO file VALUES(NULL, @FileName, @FileSize, @File)" cmd.Connection = conn cmd.CommandText = SQL cmd.Parameters.AddWithValue("@FileName", strFileName) cmd.Parameters.AddWithValue("@FileSize", FileSize) cmd.Parameters.AddWithValue("@File", rawData) cmd.ExecuteNonQuery() MessageBox.Show("File Inserted into database successfully!", _ "Success!", MessageBoxButtons.OK, MessageBoxIcon.Asterisk) conn.Close() Catch ex As Exception MessageBox.Show("There was an error: " & ex.Message, "Error", _ MessageBoxButtons.OK, MessageBoxIcon.Error) End Try * C# Example * MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); string SQL; UInt32 FileSize; byte[] rawData; FileStream fs; conn.ConnectionString = "server=127.0.0.1;uid=root;" + "pwd=12345;database=test;"; try { fs = new FileStream(@"c:\image.png", FileMode.Open, FileAccess.Read); FileSize = fs.Length; rawData = new byte[FileSize]; fs.Read(rawData, 0, FileSize); fs.Close(); conn.Open(); SQL = "INSERT INTO file VALUES(NULL, @FileName, @FileSize, @File)"; cmd.Connection = conn; cmd.CommandText = SQL; cmd.Parameters.AddWithValue("@FileName", strFileName); cmd.Parameters.AddWithValue("@FileSize", FileSize); cmd.Parameters.AddWithValue("@File", rawData); cmd.ExecuteNonQuery(); MessageBox.Show("File Inserted into database successfully!", "Success!", MessageBoxButtons.OK, MessageBoxIcon.Asterisk); conn.Close(); } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show("Error " + ex.Number + " has occurred: " + ex.Message, "Error", MessageBoxButtons.OK, MessageBoxIcon.Error); } The `Read' method of the `FileStream' object is used to load the file into a byte array which is sized according to the `Length' property of the `FileStream' object. After assigning the byte array as a parameter of the `MySqlCommand' object, the `ExecuteNonQuery' method is called and the `BLOB' is inserted into the `file' table.  File: manual.info, Node: connector-net-programming-blob-reading, Prev: connector-net-programming-blob-writing, Up: connector-net-programming-blob 21.2.5.19 Reading a BLOB from the Database to a File on Disk ............................................................ Once a file is loaded into the `file' table, we can use the `MySqlDataReader' class to retrieve it. The following code retrieves a row from the `file' table, then loads the data into a `FileStream' object to be written to disk: * Visual Basic Example * Dim conn As New MySqlConnection Dim cmd As New MySqlCommand Dim myData As MySqlDataReader Dim SQL As String Dim rawData() As Byte Dim FileSize As UInt32 Dim fs As FileStream conn.ConnectionString = "server=127.0.0.1;" _ & "uid=root;" _ & "pwd=12345;" _ & "database=test" SQL = "SELECT file_name, file_size, file FROM file" Try conn.Open() cmd.Connection = conn cmd.CommandText = SQL myData = cmd.ExecuteReader If Not myData.HasRows Then Throw New Exception("There are no BLOBs to save") myData.Read() FileSize = myData.GetUInt32(myData.GetOrdinal("file_size")) rawData = New Byte(FileSize) {} myData.GetBytes(myData.GetOrdinal("file"), 0, rawData, 0, FileSize) fs = New FileStream("C:\newfile.png", FileMode.OpenOrCreate, FileAccess.Write) fs.Write(rawData, 0, FileSize) fs.Close() MessageBox.Show("File successfully written to disk!", "Success!", MessageBoxButtons.OK, MessageBoxIcon.Asterisk) myData.Close() conn.Close() Catch ex As Exception MessageBox.Show("There was an error: " & ex.Message, "Error", MessageBoxButtons.OK, MessageBoxIcon.Error) End Try * C# Example * MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; MySql.Data.MySqlClient.MySqlDataReader myData; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); string SQL; UInt32 FileSize; byte[] rawData; FileStream fs; conn.ConnectionString = "server=127.0.0.1;uid=root;" + "pwd=12345;database=test;"; SQL = "SELECT file_name, file_size, file FROM file"; try { conn.Open(); cmd.Connection = conn; cmd.CommandText = SQL; myData = cmd.ExecuteReader(); if (! myData.HasRows) throw new Exception("There are no BLOBs to save"); myData.Read(); FileSize = myData.GetUInt32(myData.GetOrdinal("file_size")); rawData = new byte[FileSize]; myData.GetBytes(myData.GetOrdinal("file"), 0, rawData, 0, (int)FileSize); fs = new FileStream(@"C:\newfile.png", FileMode.OpenOrCreate, FileAccess.Write); fs.Write(rawData, 0, (int)FileSize); fs.Close(); MessageBox.Show("File successfully written to disk!", "Success!", MessageBoxButtons.OK, MessageBoxIcon.Asterisk); myData.Close(); conn.Close(); } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show("Error " + ex.Number + " has occurred: " + ex.Message, "Error", MessageBoxButtons.OK, MessageBoxIcon.Error); } After connecting, the contents of the `file' table are loaded into a `MySqlDataReader' object. The `GetBytes' method of the `MySqlDataReader' is used to load the `BLOB' into a byte array, which is then written to disk using a `FileStream' object. The `GetOrdinal' method of the MySqlDataReader can be used to determine the integer index of a named column. Use of the GetOrdinal method prevents errors if the column order of the *Note `SELECT': select. query is changed.  File: manual.info, Node: connector-net-interceptors, Next: connector-net-programming-datetime, Prev: connector-net-programming-blob, Up: connector-net-programming 21.2.5.20 Using the Connector/Net Interceptor Classes ..................................................... An interceptor is a software design pattern that provides a transparent way to extend or modify some aspect of a program, similar to a user exit. No recompiling is required. With Connector/Net, the interceptors are enabled and disabled by updating the connection string to refer to different sets of interceptor classes that you instantiate. Connector/Net includes the following interceptor classes: * The *Note `BaseCommandInterceptor': connector-net-ref-mysqlclient-basecommandinterceptor. lets you perform additional operations when a program issues a SQL command. For example, you can examine the SQL statement for logging or debugging purposes, substitute your own result set to implement a caching mechanism, and so on. Depending on the use case, your code can supplement the SQL command or replace it entirely. The `BaseCommandInterceptor' class has these methods that you can override: public virtual bool ExecuteScalar(string sql, ref object returnValue); public virtual bool ExecuteNonQuery(string sql, ref int returnValue); public virtual bool ExecuteReader(string sql, CommandBehavior behavior, ref MySqlDataReader returnValue); public virtual void Init(MySqlConnection connection); If your interceptor overrides one of the `Execute...' methods, set the `returnValue' output parameter and return `true' if you handled the event, or `false' if you did not handle the event. The SQL command is processed normally only when all command interceptors return `false'. The connection passed to the `Init' method is the connection that is attached to this interceptor. * The *Note `BaseExceptionInterceptor': connector-net-ref-mysqlclient-baseexceptioninterceptor. lets you perform additional operations when a program encounters a SQL exception. The exception interception mechanism is modeled after the Connector/J model. You can code an interceptor class and connect it to an existing program without recompiling, and intercept exceptions when they are created. You can then change the exception type and optionally attach information to it. This capability lets you turn on and off logging and debugging code without hardcoding anything in the application. This technique applies to exceptions raised at the SQL level, not to lower-level system or I/O errors. You develop an exception interceptor first by creating a subclass of the `BaseExceptionInterceptor' class. You must override the `InterceptException()' method. You can also override the `Init()' method to do some one-time initialization. Each exception interceptor has 2 methods: public abstract Exception InterceptException(Exception exception, MySqlConnection connection); public virtual void Init(MySqlConnection connection); The connection passed to `Init()' is the connection that is attached to this interceptor. Each interceptor is required to override `InterceptException' and return an exception. It can return the exception it is given, or it can wrap it in a new exception. We currently do not offer the ability to suppress the exception. Here are examples of using the FQN (fully qualified name) on the connection string: MySqlConnection c1 = new MySqlConnection(@"server=localhost;pooling=false; commandinterceptors=CommandApp.MyCommandInterceptor,CommandApp"); MySqlConnection c2 = new MySqlConnection(@"server=localhost;pooling=false; exceptioninterceptors=ExceptionStackTraceTest.MyExceptionInterceptor,ExceptionStackTraceTest"); In this example, the command interceptor is called `CommandApp.MyCommandInterceptor' and exists in the `CommandApp' assembly. The exception interceptor is called `ExceptionStackTraceTest.MyExceptionInterceptor' and exists in the `ExceptionStackTraceTest' assembly. To shorten the connection string, you can register your exception interceptors in your `app.config' or `web.config' file like this:
Once you have done that, your connection strings can look like these: MySqlConnection c1 = new MySqlConnection(@"server=localhost;pooling=false; commandinterceptors=myC"); MySqlConnection c2 = new MySqlConnection(@"server=localhost;pooling=false; exceptioninterceptors=myE");  File: manual.info, Node: connector-net-programming-datetime, Next: connector-net-programming-bulk-loader, Prev: connector-net-interceptors, Up: connector-net-programming 21.2.5.21 Handling Date and Time Information in Connector/Net ............................................................. * Menu: * connector-net-programming-datetime-fractional:: Fractional Seconds * connector-net-programming-datetime-problems:: Problems when Using Invalid Dates * connector-net-programming-datetime-restricting:: Restricting Invalid Dates * connector-net-programming-datetime-invalid:: Handling Invalid Dates * connector-net-programming-datetime-null:: Handling NULL Dates MySQL and the .NET languages handle date and time information differently, with MySQL allowing dates that cannot be represented by a .NET data type, such as '`0000-00-00 00:00:00''. These differences can cause problems if not properly handled. The following sections demonstrate how to properly handle date and time information when using Connector/Net.  File: manual.info, Node: connector-net-programming-datetime-fractional, Next: connector-net-programming-datetime-problems, Prev: connector-net-programming-datetime, Up: connector-net-programming-datetime 21.2.5.22 Fractional Seconds ............................ Connector/Net 6.5 and higher support the fractional seconds feature introduced in MySQL 5.6.4. Fractional seconds could always be specified in a date literal or passed back and forth as parameters and return values, but the fractional part was always stripped off when stored in a table column. In MySQL 5.6.4 and higher, the fractional part is now preserved in data stored and retrieved through SQL. For fractional second handling in MySQL 5.6.4 and higher, see Fractional Seconds in Time Values (http://dev.mysql.com/doc/refman/5.6/en/fractional-seconds.html). For the behavior of fractional seconds prior to MySQL 5.6.4, see Fractional Seconds in Time Values (http://dev.mysql.com/doc/refman/5.5/en/fractional-seconds.html). To use the more precise date and time types, specify a value from 1 to 6 when creating the table column, for example `TIME(3)' or `DATETIME(6)', representing the number of digits of precision after the decimal point. Specifying a precision of 0 leaves the fractional part out entirely. In your C# or Visual Basic code, refer to the `Millisecond' member to retrieve the fractional second value from the `MySqlDateTime' object returned by the `GetMySqlDateTime' function. The `DateTime' object returned by the `GetDateTime' function also contains the fractional value, but only the first 3 digits. For related code examples, see the following blog post: `https://blogs.oracle.com/MySqlOnWindows/entry/milliseconds_value_support_on_datetime'  File: manual.info, Node: connector-net-programming-datetime-problems, Next: connector-net-programming-datetime-restricting, Prev: connector-net-programming-datetime-fractional, Up: connector-net-programming-datetime 21.2.5.23 Problems when Using Invalid Dates ........................................... The differences in date handling can cause problems for developers who use invalid dates. Invalid MySQL dates cannot be loaded into native .NET `DateTime' objects, including `NULL' dates. Because of this issue, .NET `DataSet' objects cannot be populated by the `Fill' method of the `MySqlDataAdapter' class as invalid dates will cause a `System.ArgumentOutOfRangeException' exception to occur.  File: manual.info, Node: connector-net-programming-datetime-restricting, Next: connector-net-programming-datetime-invalid, Prev: connector-net-programming-datetime-problems, Up: connector-net-programming-datetime 21.2.5.24 Restricting Invalid Dates ................................... The best solution to the date problem is to restrict users from entering invalid dates. This can be done on either the client or the server side. Restricting invalid dates on the client side is as simple as always using the .NET `DateTime' class to handle dates. The `DateTime' class will only allow valid dates, ensuring that the values in your database are also valid. The disadvantage of this is that it is not useful in a mixed environment where .NET and non .NET code are used to manipulate the database, as each application must perform its own date validation. Users of MySQL 5.0.2 and higher can use the new `traditional' SQL mode to restrict invalid date values. For information on using the `traditional' SQL mode, see *Note server-sql-mode::.  File: manual.info, Node: connector-net-programming-datetime-invalid, Next: connector-net-programming-datetime-null, Prev: connector-net-programming-datetime-restricting, Up: connector-net-programming-datetime 21.2.5.25 Handling Invalid Dates ................................ Although it is strongly recommended that you avoid the use of invalid dates within your .NET application, it is possible to use invalid dates by means of the `MySqlDateTime' data type. The `MySqlDateTime' data type supports the same date values that are supported by the MySQL server. The default behavior of Connector/Net is to return a .NET DateTime object for valid date values, and return an error for invalid dates. This default can be modified to cause Connector/Net to return `MySqlDateTime' objects for invalid dates. To instruct Connector/Net to return a `MySqlDateTime' object for invalid dates, add the following line to your connection string: Allow Zero Datetime=True Please note that the use of the `MySqlDateTime' class can still be problematic. The following are some known issues: 1. Data binding for invalid dates can still cause errors (zero dates like 0000-00-00 do not seem to have this problem). 2. The `ToString' method return a date formatted in the standard MySQL format (for example, `2005-02-23 08:50:25'). This differs from the `ToString' behavior of the .NET DateTime class. 3. The `MySqlDateTime' class supports NULL dates, while the .NET DateTime class does not. This can cause errors when trying to convert a MySQLDateTime to a DateTime if you do not check for NULL first. Because of the known issues, the best recommendation is still to use only valid dates in your application.  File: manual.info, Node: connector-net-programming-datetime-null, Prev: connector-net-programming-datetime-invalid, Up: connector-net-programming-datetime 21.2.5.26 Handling NULL Dates ............................. The .NET `DateTime' data type cannot handle `NULL' values. As such, when assigning values from a query to a `DateTime' variable, you must first check whether the value is in fact `NULL'. When using a `MySqlDataReader', use the `.IsDBNull' method to check whether a value is `NULL' before making the assignment: * Visual Basic Example * If Not myReader.IsDBNull(myReader.GetOrdinal("mytime")) Then myTime = myReader.GetDateTime(myReader.GetOrdinal("mytime")) Else myTime = DateTime.MinValue End If * C# Example * if (! myReader.IsDBNull(myReader.GetOrdinal("mytime"))) myTime = myReader.GetDateTime(myReader.GetOrdinal("mytime")); else myTime = DateTime.MinValue; `NULL' values will work in a data set and can be bound to form controls without special handling.  File: manual.info, Node: connector-net-programming-bulk-loader, Next: connector-net-programming-tracing, Prev: connector-net-programming-datetime, Up: connector-net-programming 21.2.5.27 Using the `MySqlBulkLoader' Class ........................................... MySQL Connector/Net features a bulk loader class that wraps the MySQL statement *Note `LOAD DATA INFILE': load-data. This gives MySQL Connector/Net the ability to load a data file from a local or remote host to the server. The class concerned is `MySqlBulkLoader'. This class has various methods, the main one being `load' to cause the specified file to be loaded to the server. Various parameters can be set to control how the data file is processed. This is achieved through setting various properties of the class. For example, the field separator used, such as comma or tab, can be specified, along with the record terminator, such as newline. The following code shows a simple example of using the `MySqlBulkLoader' class. First an empty table needs to be created, in this case in the `test' database: CREATE TABLE Career ( Name VARCHAR(100) NOT NULL, Age INTEGER, Profession VARCHAR(200) ); A simple tab-delimited data file is also created (it could use any other field delimiter such as comma): Table Career in Test Database Name Age Profession Tony 47 Technical Writer Ana 43 Nurse Fred 21 IT Specialist Simon 45 Hairy Biker Note that with this test file the first three lines will need to be ignored, as they do not contain table data. This can be achieved using the `NumberOfLinesToSkip' property. This file can then be loaded and used to populate the `Career' table in the `test' database: using System; using System.Text; using MySql.Data; using MySql.Data.MySqlClient; namespace ConsoleApplication1 { class Program { static void Main(string[] args) { string connStr = "server=localhost;user=root;database=test;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); MySqlBulkLoader bl = new MySqlBulkLoader(conn); bl.TableName = "Career"; bl.FieldTerminator = "\t"; bl.LineTerminator = "\n"; bl.FileName = "c:/career_data.txt"; bl.NumberOfLinesToSkip = 3; try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); // Upload data from file int count = bl.Load(); Console.WriteLine(count + " lines uploaded."); string sql = "SELECT Name, Age, Profession FROM Career"; MySqlCommand cmd = new MySqlCommand(sql, conn); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr[0] + " -- " + rdr[1] + " -- " + rdr[2]); } rdr.Close(); conn.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } Console.WriteLine("Done."); } } } Further information on `LOAD DATA INFILE' can be found in *Note load-data::. Further information on `MySqlBulkLoader' can be found in the reference documentation that was included with your connector.  File: manual.info, Node: connector-net-programming-tracing, Next: connector-net-programming-binary-issues, Prev: connector-net-programming-bulk-loader, Up: connector-net-programming 21.2.5.28 Using the MySQL Connector/Net Trace Source Object ........................................................... * Menu: * connector-net-programming-tracing-mysql:: Viewing MySQL Trace Information * connector-net-programming-tracing-mysql-custom-listeners:: Building Custom Listeners MySQL Connector/Net 6.2 introduced support for .NET 2.0 compatible tracing, using `TraceSource' objects. The .NET 2.0 tracing architecture consists of four main parts: * _Source_ - This is the originator of the trace information. The source is used to send trace messages. The name of the source provided by MySQL Connector/Net is `mysql'. * _Switch_ - This defines the level of trace information to emit. Typically, this is specified in the `app.config' file, so that it is not necessary to recompile an application to change the trace level. * _Listener_ - Trace listeners define where the trace information will be written to. Supported listeners include, for example, the Visual Studio Output window, the Windows Event Log, and the console. * _Filter_ - Filters can be attached to listeners. Filters determine the level of trace information that will be written. While a switch defines the level of information that will be written to all listeners, a filter can be applied on a per-listener basis, giving finer grained control of trace information. To use tracing a `TraceSource' object first needs to be created. To create a `TraceSource' object in MySQL Connector/Net you would use code similar to the following: TraceSource ts = new TraceSource("mysql"); To enable trace messages, configure a trace switch. There are three main switch classes, `BooleanSwitch', `SourceSwitch', and `TraceSwitch'. Trace switches also have associated with them a trace level enumeration, these are `Off', `Error', `Warning', `Info', and `Verbose'. The following code snippet illustrates creating a switch: ts.Switch = new SourceSwitch("MySwitch", "Verbose"); This creates a `SourceSwitch', called `MySwitch', and sets the trace level to `Verbose', meaning that all trace messages will be written. It is convenient to be able to change the trace level without having to recompile the code. This is achieved by specifying the trace level in application configuration file, `app.config'. You then simply need to specify the desired trace level in the configuration file and restart the application. The trace source is configured within the `system.diagnostics' section of the file. The following XML snippet illustrates this: ... ... ... ... By default, trace information is written to the Output window of Microsoft Visual Studio. There are a wide range of listeners that can be attached to the trace source, so that trace messages can be written out to various destinations. You can also create custom listeners to allow trace messages to be written to other destinations as mobile devices and web services. A commonly used example of a listener is `ConsoleTraceListener', which writes trace messages to the console. To add a listener at runtime, use code such as the following: ts.Listeners.Add(new ConsoleTraceListener()); Then, call methods on the trace source object to generate trace information. For example, the `TraceInformation()', `TraceEvent()', or `TraceData()' methods can be used. The `TraceInformation()' method simply prints a string passed as a parameter. The `TraceEvent()' method, as well as the optional informational string, requires a `TraceEventType' value to be passed to indicate the trace message type, and also an application specific ID. The `TraceEventType' can have a value of `Verbose', `Information', `Warning', `Error', and `Critical'. Using the `TraceData()' method you can pass any object, for example an exception object, instead of a message. To ensure than these generated trace messages gets flushed from the trace source buffers to listeners, invoke the `Flush()' method. When you are finished using a trace source, call the `Close()' method. The `Close()' method first calls `Flush()', to ensure any remaining data is written out. It then frees up resources, and closes the listeners associated with the trace source. ts.TraceInformation("Informational message"); ts.TraceEvent(TraceEventType.Error, 3, "Optional error message"); ts.TraceData(TraceEventType.Error, 3, ex); // pass exception object ts.Flush(); ... ts.Close();  File: manual.info, Node: connector-net-programming-tracing-mysql, Next: connector-net-programming-tracing-mysql-custom-listeners, Prev: connector-net-programming-tracing, Up: connector-net-programming-tracing 21.2.5.29 Viewing MySQL Trace Information ......................................... This section describes how to set up your application to view MySQL trace information. The first thing you need to do is create a suitable `app.config' file for your application. An example is shown in the following code: This ensures a suitable trace source is created, along with a switch. The switch level in this case is set to `Verbose' to display the maximum amount of information. In the application the only other step required is to add `logging=true' to the connection string. An example application could be: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Diagnostics; using MySql.Data; using MySql.Data.MySqlClient; using MySql.Web; namespace ConsoleApplication1 { class Program { static void Main(string[] args) { string connStr = "server=localhost;user=root;database=world;port=3306;password=******;logging=true;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); string sql = "SELECT Name, HeadOfState FROM Country WHERE Continent='Oceania'"; MySqlCommand cmd = new MySqlCommand(sql, conn); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr[0] + " -- " + rdr[1]); } rdr.Close(); conn.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } Console.WriteLine("Done."); } } } This simple application will then generate the following output: Connecting to MySQL... mysql Information: 1 : 1: Connection Opened: connection string = 'server=localhost;User Id=root;database=world;port=3306 ;password=******;logging=True' mysql Information: 3 : 1: Query Opened: SHOW VARIABLES mysql Information: 4 : 1: Resultset Opened: field(s) = 2, affected rows = -1, inserted id = -1 mysql Information: 5 : 1: Resultset Closed. Total rows=272, skipped rows=0, size (bytes)=7058 mysql Information: 6 : 1: Query Closed mysql Information: 3 : 1: Query Opened: SHOW COLLATION mysql Information: 4 : 1: Resultset Opened: field(s) = 6, affected rows = -1, inserted id = -1 mysql Information: 5 : 1: Resultset Closed. Total rows=127, skipped rows=0, size (bytes)=4102 mysql Information: 6 : 1: Query Closed mysql Information: 3 : 1: Query Opened: SET character_set_results=NULL mysql Information: 4 : 1: Resultset Opened: field(s) = 0, affected rows = 0, inserted id = 0 mysql Information: 5 : 1: Resultset Closed. Total rows=0, skipped rows=0, size (bytes)=0 mysql Information: 6 : 1: Query Closed mysql Information: 10 : 1: Set Database: world mysql Information: 3 : 1: Query Opened: SELECT Name, HeadOfState FROM Country WHERE Continent='Oceania' mysql Information: 4 : 1: Resultset Opened: field(s) = 2, affected rows = -1, inserted id = -1 American Samoa -- George W. Bush Australia -- Elisabeth II ... Wallis and Futuna -- Jacques Chirac Vanuatu -- John Bani United States Minor Outlying Islands -- George W. Bush mysql Information: 5 : 1: Resultset Closed. Total rows=28, skipped rows=0, size (bytes)=788 mysql Information: 6 : 1: Query Closed Done. mysql Information: 2 : 1: Connection Closed The first number displayed in the trace message corresponds to the MySQL event type: Explains the MySQL event types, specified by the first number displayed in each trace message. Event Description 1 ConnectionOpened: connection string 2 ConnectionClosed: 3 QueryOpened: mysql server thread id, query text 4 ResultOpened: field count, affected rows (-1 if select), inserted id (-1 if select) 5 ResultClosed: total rows read, rows skipped, size of resultset in bytes 6 QueryClosed: 7 StatementPrepared: prepared sql, statement id 8 StatementExecuted: statement id, mysql server thread id 9 StatementClosed: statement id 10 NonQuery: [varies] 11 UsageAdvisorWarning: usage advisor flag. NoIndex = 1, BadIndex = 2, SkippedRows = 3, SkippedColumns = 4, FieldConversion = 5. 12 Warning: level, code, message 13 Error: error number, error message The second number displayed in the trace message is the connection count. Although this example uses the `ConsoleTraceListener', any of the other standard listeners could have been used. Another possibility is to create a custom listener that uses the information passed using the `TraceEvent' method. For example, a custom trace listener could be created to perform active monitoring of the MySQL event messages, rather than simply writing these to an output device. It is also possible to add listeners to the MySQL Trace Source at runtime. This can be done with the following code: MySqlTrace.Listeners.Add(new ConsoleTraceListener()); MySQL Connector/Net 6.3.2 introduced the ability to switch tracing on and off at runtime. This can be achieved using the calls `MySqlTrace.EnableQueryAnalyzer(string host, int postInterval)' and `MySqlTrace.DisableQueryAnalyzer()'. The parameter `host' is the URL of the MySQL Enterprise Monitor server to monitor. The parameter `postInterval' is how often to post the data to MySQL Enterprise Monitor, in seconds.  File: manual.info, Node: connector-net-programming-tracing-mysql-custom-listeners, Prev: connector-net-programming-tracing-mysql, Up: connector-net-programming-tracing 21.2.5.30 Building Custom Listeners ................................... To build custom listeners that work with the MySQL Connector/Net Trace Source, it is necessary to understand the key methods used, and the event data formats used. The main method involved in passing trace messages is the `TraceSource.TraceEvent' method. This has the prototype: public void TraceEvent( TraceEventType eventType, int id, string format, params Object[] args ) This trace source method will process the list of attached listeners and call the listener's `TraceListener.TraceEvent' method. The prototype for the `TraceListener.TraceEvent' method is as follows: public virtual void TraceEvent( TraceEventCache eventCache, string source, TraceEventType eventType, int id, string format, params Object[] args ) The first three parameters are used in the standard as defined by Microsoft (http://msdn.microsoft.com/en-us/library/d193webf.aspx). The last three parameters contain MySQL-specific trace information. Each of these parameters is now discussed in more detail. *`int id'* This is a MySQL-specific identifier. It identifies the MySQL event type that has occurred, resulting in a trace message being generated. This value is defined by the `MySqlTraceEventType' public enum contained in the MySQL Connector/Net code: public enum MySqlTraceEventType : int { ConnectionOpened = 1, ConnectionClosed, QueryOpened, ResultOpened, ResultClosed, QueryClosed, StatementPrepared, StatementExecuted, StatementClosed, NonQuery, UsageAdvisorWarning, Warning, Error } The MySQL event type also determines the contents passed using the parameter `params Object[] args'. The nature of the `args' parameters are described in further detail in the following material. *`string format'* This is the format string that contains zero or more format items, which correspond to objects in the args array. This would be used by a listener such as `ConsoleTraceListener' to write a message to the output device. *`params Object[] args'* This is a list of objects that depends on the MySQL event type, `id'. However, the first parameter passed using this list is always the driver id. The driver id is a unique number that is incremented each time the connector is opened. This enables groups of queries on the same connection to be identified. The parameters that follow driver id depend on the MySQL event id, and are as follows: Meanings of second and subsequent elements in the `TraceListener.TraceEvent' `args' parameter array. MySQL-specific event Arguments (params Object[] args) type ConnectionOpened Connection string ConnectionClosed No additional parameters QueryOpened mysql server thread id, query text ResultOpened field count, affected rows (-1 if select), inserted id (-1 if select) ResultClosed total rows read, rows skipped, size of resultset in bytes QueryClosed No additional parameters StatementPrepared prepared sql, statement id StatementExecuted statement id, mysql server thread id StatementClosed statement id NonQuery Varies UsageAdvisorWarning usage advisor flag. NoIndex = 1, BadIndex = 2, SkippedRows = 3, SkippedColumns = 4, FieldConversion = 5. Warning level, code, message Error error number, error message This information will allow you to create custom trace listeners that can actively monitor the MySQL-specific events.  File: manual.info, Node: connector-net-programming-binary-issues, Next: connector-net-using-character-sets, Prev: connector-net-programming-tracing, Up: connector-net-programming 21.2.5.31 Binary/Nonbinary Issues ................................. There are certain situations where MySQL will return incorrect metadata about one or more columns. More specifically, the server will sometimes report that a column is binary when it is not and vice versa. In these situations, it becomes practically impossible for the connector to be able to correctly identify the correct metadata. Some examples of situations that may return incorrect metadata are: * Execution of *Note `SHOW PROCESSLIST': show-processlist. Some of the columns will be returned as binary even though they only hold string data. * When a temporary table is used to process a resultset, some columns may be returned with incorrect binary flags. * Some server functions such `DATE_FORMAT' will incorrectly return the column as binary. With the availability of `BINARY' and `VARBINARY' data types, it is important that we respect the metadata returned by the server. However, we are aware that some existing applications may break with this change, so we are creating a connection string option to enable or disable it. By default, Connector/Net 5.1 respects the binary flags returned by the server. You might need to make small changes to your application to accommodate this change. In the event that the changes required to your application would be too large, adding `'respect binary flags=false'' to your connection string causes the connector to use the prior behavior: any column that is marked as string, regardless of binary flags, will be returned as string. Only columns that are specifically marked as a `BLOB' will be returned as `BLOB'.  File: manual.info, Node: connector-net-using-character-sets, Next: connector-net-programming-crystal, Prev: connector-net-programming-binary-issues, Up: connector-net-programming 21.2.5.32 Character Set Considerations for Connector/Net ........................................................ *Treating Binary Blobs As UTF8* MySQL doesn't currently support 4-byte UTF8 sequences. This makes it difficult to represent some multi-byte languages such as Japanese. To try and alleviate this, Connector/Net now supports a mode where binary blobs can be treated as strings. To do this, you set the `'Treat Blobs As UTF8'' connection string keyword to `yes'. This is all that needs to be done to enable conversion of all binary blobs to UTF8 strings. To convert only some of your BLOB columns, you can make use of the `'BlobAsUTF8IncludePattern'' and`'BlobAsUTF8ExcludePattern'' keywords. Set these to a regular expression pattern that matches the column names to include or exclude respectively. When the regular expression patterns both match a single column, the include pattern is applied before the exclude pattern. The result, in this case, would be that the column would be excluded. Also, be aware that this mode does not apply to columns of type `BINARY' or `VARBINARY' and also do not apply to nonbinary `BLOB' columns. Currently, this mode only applies to reading strings out of MySQL. To insert 4-byte UTF8 strings into blob columns, use the .NET `Encoding.GetBytes' function to convert your string to a series of bytes. You can then set this byte array as a parameter for a `BLOB' column.  File: manual.info, Node: connector-net-programming-crystal, Next: connector-net-programming-asp-provider, Prev: connector-net-using-character-sets, Up: connector-net-programming 21.2.5.33 Using Connector/Net with Crystal Reports .................................................. * Menu: * connector-net-programming-crystal-source:: Creating a Data Source * connector-net-programming-crystal-creating:: Creating the Report * connector-net-programming-crystal-displaying:: Displaying the Report Crystal Reports is a common tool used by Windows application developers to perform reporting and document generation. In this section we will show how to use Crystal Reports XI with MySQL and Connector/Net.  File: manual.info, Node: connector-net-programming-crystal-source, Next: connector-net-programming-crystal-creating, Prev: connector-net-programming-crystal, Up: connector-net-programming-crystal 21.2.5.34 Creating a Data Source ................................ When creating a report in Crystal Reports there are two options for accessing the MySQL data while designing your report. The first option is to use Connector/ODBC as an ADO data source when designing your report. You will be able to browse your database and choose tables and fields using drag and drop to build your report. The disadvantage of this approach is that additional work must be performed within your application to produce a data set that matches the one expected by your report. The second option is to create a data set in VB.NET and save it as XML. This XML file can then be used to design a report. This works quite well when displaying the report in your application, but is less versatile at design time because you must choose all relevant columns when creating the data set. If you forget a column you must re-create the data set before the column can be added to the report. The following code can be used to create a data set from a query and write it to disk: * Visual Basic Example * Dim myData As New DataSet Dim conn As New MySqlConnection Dim cmd As New MySqlCommand Dim myAdapter As New MySqlDataAdapter conn.ConnectionString = "server=127.0.0.1;" _ & "uid=root;" _ & "pwd=12345;" _ & "database=world" Try conn.Open() cmd.CommandText = "SELECT city.name AS cityName, city.population AS CityPopulation, " _ & "country.name, country.population, country.continent " _ & "FROM country, city ORDER BY country.continent, country.name" cmd.Connection = conn myAdapter.SelectCommand = cmd myAdapter.Fill(myData) myData.WriteXml("C:\dataset.xml", XmlWriteMode.WriteSchema) Catch ex As Exception MessageBox.Show(ex.Message, "Report could not be created", MessageBoxButtons.OK, MessageBoxIcon.Error) End Try * C# Example * DataSet myData = new DataSet(); MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; MySql.Data.MySqlClient.MySqlDataAdapter myAdapter; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); myAdapter = new MySql.Data.MySqlClient.MySqlDataAdapter(); conn.ConnectionString = "server=127.0.0.1;uid=root;" + "pwd=12345;database=test;"; try { cmd.CommandText = "SELECT city.name AS cityName, city.population AS CityPopulation, " + "country.name, country.population, country.continent " + "FROM country, city ORDER BY country.continent, country.name"; cmd.Connection = conn; myAdapter.SelectCommand = cmd; myAdapter.Fill(myData); myData.WriteXml(@"C:\dataset.xml", XmlWriteMode.WriteSchema); } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show(ex.Message, "Report could not be created", MessageBoxButtons.OK, MessageBoxIcon.Error); } The resulting XML file can be used as an ADO.NET XML datasource when designing your report. If you choose to design your reports using Connector/ODBC, it can be downloaded from dev.mysql.com (http://dev.mysql.com/downloads/connector/odbc/3.51.html).  File: manual.info, Node: connector-net-programming-crystal-creating, Next: connector-net-programming-crystal-displaying, Prev: connector-net-programming-crystal-source, Up: connector-net-programming-crystal 21.2.5.35 Creating the Report ............................. For most purposes, the Standard Report wizard helps with the initial creation of a report. To start the wizard, open Crystal Reports and choose the `New > Standard Report' option from the File menu. The wizard first prompts you for a data source. If you use Connector/ODBC as your data source, use the OLEDB provider for ODBC option from the OLE DB (ADO) tree instead of the ODBC (RDO) tree when choosing a data source. If using a saved data set, choose the ADO.NET (XML) option and browse to your saved data set. The remainder of the report creation process is done automatically by the wizard. After the report is created, choose the Report Options... entry of the File menu. Un-check the Save Data With Report option. This prevents saved data from interfering with the loading of data within our application.  File: manual.info, Node: connector-net-programming-crystal-displaying, Prev: connector-net-programming-crystal-creating, Up: connector-net-programming-crystal 21.2.5.36 Displaying the Report ............................... To display a report we first populate a data set with the data needed for the report, then load the report and bind it to the data set. Finally we pass the report to the crViewer control for display to the user. The following references are needed in a project that displays a report: * CrystalDecisions.CrystalReports.Engine * CrystalDecisions.ReportSource * CrystalDecisions.Shared * CrystalDecisions.Windows.Forms The following code assumes that you created your report using a data set saved using the code shown in *Note connector-net-programming-crystal-source::, and have a crViewer control on your form named `myViewer'. * Visual Basic Example * Imports CrystalDecisions.CrystalReports.Engine Imports System.Data Imports MySql.Data.MySqlClient Dim myReport As New ReportDocument Dim myData As New DataSet Dim conn As New MySqlConnection Dim cmd As New MySqlCommand Dim myAdapter As New MySqlDataAdapter conn.ConnectionString = _ "server=127.0.0.1;" _ & "uid=root;" _ & "pwd=12345;" _ & "database=test" Try conn.Open() cmd.CommandText = "SELECT city.name AS cityName, city.population AS CityPopulation, " _ & "country.name, country.population, country.continent " _ & "FROM country, city ORDER BY country.continent, country.name" cmd.Connection = conn myAdapter.SelectCommand = cmd myAdapter.Fill(myData) myReport.Load(".\world_report.rpt") myReport.SetDataSource(myData) myViewer.ReportSource = myReport Catch ex As Exception MessageBox.Show(ex.Message, "Report could not be created", MessageBoxButtons.OK, MessageBoxIcon.Error) End Try * C# Example * using CrystalDecisions.CrystalReports.Engine; using System.Data; using MySql.Data.MySqlClient; ReportDocument myReport = new ReportDocument(); DataSet myData = new DataSet(); MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; MySql.Data.MySqlClient.MySqlDataAdapter myAdapter; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); myAdapter = new MySql.Data.MySqlClient.MySqlDataAdapter(); conn.ConnectionString = "server=127.0.0.1;uid=root;" + "pwd=12345;database=test;"; try { cmd.CommandText = "SELECT city.name AS cityName, city.population AS CityPopulation, " + "country.name, country.population, country.continent " + "FROM country, city ORDER BY country.continent, country.name"; cmd.Connection = conn; myAdapter.SelectCommand = cmd; myAdapter.Fill(myData); myReport.Load(@".\world_report.rpt"); myReport.SetDataSource(myData); myViewer.ReportSource = myReport; } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show(ex.Message, "Report could not be created", MessageBoxButtons.OK, MessageBoxIcon.Error); } A new data set it generated using the same query used to generate the previously saved data set. Once the data set is filled, a ReportDocument is used to load the report file and bind it to the data set. The ReportDocument is the passed as the ReportSource of the crViewer. This same approach is taken when a report is created from a single table using Connector/ODBC. The data set replaces the table used in the report and the report is displayed properly. When a report is created from multiple tables using Connector/ODBC, a data set with multiple tables must be created in our application. This enables each table in the report data source to be replaced with a report in the data set. We populate a data set with multiple tables by providing multiple *Note `SELECT': select. statements in our MySqlCommand object. These *Note `SELECT': select. statements are based on the SQL query shown in Crystal Reports in the Database menu's Show SQL Query option. Assume the following query: SELECT `country`.`Name`, `country`.`Continent`, `country`.`Population`, `city`.`Name`, `city`.`Population` FROM `world`.`country` `country` LEFT OUTER JOIN `world`.`city` `city` ON `country`.`Code`=`city`.`CountryCode` ORDER BY `country`.`Continent`, `country`.`Name`, `city`.`Name` This query is converted to two *Note `SELECT': select. queries and displayed with the following code: * Visual Basic Example * Imports CrystalDecisions.CrystalReports.Engine Imports System.Data Imports MySql.Data.MySqlClient Dim myReport As New ReportDocument Dim myData As New DataSet Dim conn As New MySqlConnection Dim cmd As New MySqlCommand Dim myAdapter As New MySqlDataAdapter conn.ConnectionString = "server=127.0.0.1;" _ & "uid=root;" _ & "pwd=12345;" _ & "database=world" Try conn.Open() cmd.CommandText = "SELECT name, population, countrycode FROM city ORDER BY countrycode, name; " _ & "SELECT name, population, code, continent FROM country ORDER BY continent, name" cmd.Connection = conn myAdapter.SelectCommand = cmd myAdapter.Fill(myData) myReport.Load(".\world_report.rpt") myReport.Database.Tables(0).SetDataSource(myData.Tables(0)) myReport.Database.Tables(1).SetDataSource(myData.Tables(1)) myViewer.ReportSource = myReport Catch ex As Exception MessageBox.Show(ex.Message, "Report could not be created", MessageBoxButtons.OK, MessageBoxIcon.Error) End Try * C# Example * using CrystalDecisions.CrystalReports.Engine; using System.Data; using MySql.Data.MySqlClient; ReportDocument myReport = new ReportDocument(); DataSet myData = new DataSet(); MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; MySql.Data.MySqlClient.MySqlDataAdapter myAdapter; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); myAdapter = new MySql.Data.MySqlClient.MySqlDataAdapter(); conn.ConnectionString = "server=127.0.0.1;uid=root;" + "pwd=12345;database=test;"; try { cmd.CommandText = "SELECT name, population, countrycode FROM city ORDER " + "BY countrycode, name; *Note `SELECT': select. name, population, code, continent FROM " + "country ORDER BY continent, name"; cmd.Connection = conn; myAdapter.SelectCommand = cmd; myAdapter.Fill(myData); myReport.Load(@".\world_report.rpt"); myReport.Database.Tables(0).SetDataSource(myData.Tables(0)); myReport.Database.Tables(1).SetDataSource(myData.Tables(1)); myViewer.ReportSource = myReport; } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show(ex.Message, "Report could not be created", MessageBoxButtons.OK, MessageBoxIcon.Error); } It is important to order the *Note `SELECT': select. queries in alphabetic order, as this is the order the report will expect its source tables to be in. One SetDataSource statement is needed for each table in the report. This approach can cause performance problems because Crystal Reports must bind the tables together on the client-side, which will be slower than using a pre-saved data set.  File: manual.info, Node: connector-net-programming-asp-provider, Next: connector-net-medium-trust, Prev: connector-net-programming-crystal, Up: connector-net-programming 21.2.5.37 ASP.NET Provider Model ................................ MySQL Connector/Net provides support for the ASP.NET 2.0 provider model. This model enables application developers to focus on the business logic of their application instead of having to recreate such boilerplate items as membership and roles support. MySQL Connector/Net supplies the following providers: * Membership Provider * Role Provider * Profile Provider * Session State Provider (MySQL Connector/Net 6.1 and later) The following tables show the supported providers, their default provider and the corresponding MySQL provider. *Membership Provider* Default provider and corresponding MySQL provider for the Membership provider. Default Provider MySQL Provider System.Web.Security.SqlMembershipProviderMySql.Web.Security.MySQLMembershipProvider *Role Provider* Default provider and corresponding MySQL provider for the Role provider. Default Provider MySQL Provider System.Web.Security.SqlRoleProvider MySql.Web.Security.MySQLRoleProvider *Profile Provider* Default provider and corresponding MySQL provider for the Profile provider. Default Provider MySQL Provider System.Web.Profile.SqlProfileProviderMySql.Web.Profile.MySQLProfileProvider *SessionState Provider* Default provider and corresponding MySQL provider for the SessionState provider. Default Provider MySQL Provider System.Web.SessionState.InProcSessionStateStoreMySql.Web.SessionState.MySqlSessionStateStore *Note*: The MySQL Session State provider uses slightly different capitalization on the class name compared to the other MySQL providers. *Installing The Providers* The installation of Connector/Net 5.1 or later will install the providers and register them in your machine's .NET configuration file, `machine.config'. The additional entries created will result in the `system.web' section appearing similar to the following code: Each provider type can have multiple provider implementations. The default provider can also be set here using the `defaultProvider' attribute, but usually this is set in the `web.config' file either manually or by using the ASP.NET configuration tool. At time of writing, the `MySqlSessionStateStore' is not added to `machine.config' at install time, and so add the following: The SessionState Provider uses the `customProvider' attribute, rather than `defaultProvider', to set the provider as the default. A typical `web.config' file might contain: ... This sets the MySQL Providers as the defaults to be used in this web application. The providers are implemented in the file `mysql.web.dll' and this file can be found in your MySQL Connector/Net installation folder. There is no need to run any type of SQL script to set up the database schema, as the providers create and maintain the proper schema automatically. * Using The Providers* The easiest way to start using the providers is to use the ASP.NET configuration tool that is available on the Solution Explorer toolbar when you have a website project loaded. In the web pages that open, you can select the MySQL membership and roles providers by picking a custom provider for each area. When the provider is installed, it creates a dummy connection string named `LocalMySqlServer'. Although this has to be done so that the provider will work in the ASP.NET configuration tool, you override this connection string in your `web.config' file. You do this by first removing the dummy connection string and then adding in the proper one, as shown in the following example: Note the database to connect to must be specified. Rather than manually editing configuration files, consider using the MySQL Website Configuration tool to configure your desired provider setup. From MySQL Connector/Net 6.1.1 onwards, all providers can be selected and configured from this wizard. The tool modifies your `website.config' file to the desired configuration. A tutorial on doing this is available in the following section *Note connector-net-website-config::. A tutorial demonstrating how to use the Membership and Role Providers can be found in the following section *Note connector-net-tutorials-asp-roles::. * Deployment* To use the providers on a production server, distribute the `MySql.Data' and the `MySql.Web' assemblies, and either register them in the remote systems Global Assembly Cache or keep them in your application's `bin/' directory.  File: manual.info, Node: connector-net-medium-trust, Prev: connector-net-programming-asp-provider, Up: connector-net-programming 21.2.5.38 Working with Partial Trust / Medium Trust ................................................... * Menu: * connector-net-medium-trust-evolution:: Evolution of Partial Trust Support Across Connector/Net Versions * connector-net-medium-trust-gac:: Configuring Partial Trust with Connector/Net Library Installed in GAC * connector-net-medium-trust-nongac:: Configuring Partial Trust with Connector/Net Library Not Installed in GAC .NET applications operate under a given trust level. Normal desktop applications operate under full trust, while web applications that are hosted in shared environments are normally run under the partial trust level (also known as `medium trust'). Some hosting providers host shared applications in their own app pools and allow the application to run under full trust, but this configuration is relatively rare. The Connector/Net support for partial trust has improved over time to simplify the configuration and deployment process for hosting providers.  File: manual.info, Node: connector-net-medium-trust-evolution, Next: connector-net-medium-trust-gac, Prev: connector-net-medium-trust, Up: connector-net-medium-trust 21.2.5.39 Evolution of Partial Trust Support Across Connector/Net Versions .......................................................................... The partial trust support for Connector/Net has improved rapidly throughout the 6.5.x and 6.6.x versions. The latest enhancements do require some configuration changes in existing deployments. Here is a summary of the changes for each version. * 6.6.4 and Above: Library Can Be Inside or Outside GAC * Now you can install the `MySql.Data.dll' library in the Global Assembly Cache (GAC) as explained in *Note connector-net-medium-trust-gac::, or in a `bin' or `lib' folder inside the project or solution as explained in *Note connector-net-medium-trust-nongac::. If the library is not in the GAC, the only protocol supported is TCP/IP. * 6.5.1 and Above: Partial Trust Requires Library in the GAC * Connector/Net 6.5 fully enables our provider to run in a partial trust environment when the library is installed in the Global Assembly Cache (GAC). The new `MySqlClientPermission' class, derived from the .NET `DBDataPermission' class, helps to simplify the permission setup. * 5.0.8 / 5.1.3 and Above: Partial Trust Requires Socket Permissions * Starting with these versions, Connector/Net can be used under partial trust hosting that has been modified to allow the use of sockets for communication. By default, partial trust does not include `SocketPermission'. Connector/Net uses sockets to talk with the MySQL server, so the hosting provider must create a new trust level that is an exact clone of partial trust but that has the following permissions added: * `System.Net.SocketPermission' * `System.Security.Permissions.ReflectionPermission' * `System.Net.DnsPermission' * `System.Security.Permissions.SecurityPermission' * Prior to 5.0.8 / 5.1.3: Partial Trust Not Supported * Connector/Net versions prior to 5.0.8 and 5.1.3 were not compatible with partial trust hosting.  File: manual.info, Node: connector-net-medium-trust-gac, Next: connector-net-medium-trust-nongac, Prev: connector-net-medium-trust-evolution, Up: connector-net-medium-trust 21.2.5.40 Configuring Partial Trust with Connector/Net Library Installed in GAC ............................................................................... If the library is installed in the GAC, you must include the connection option `includesecurityasserts=true' in your connection string. This is a new requirement as of Connector/Net 6.6.4. The following list shows steps and code fragments needed to run a Connector/Net application in a partial trust environment. For illustration purposes, we use the Pipe Connections protocol in this example. 1. Install Connector/Net: version 6.6.1 or higher, or 6.5.4 or higher. 2. After installing the library, make the following configuration changes: In the `SecurityClasses' section, add a definition for the `MySqlClientPermission' class, including the version to use. .... Scroll down to the `ASP.Net' section: Add a new entry for the detailed configuration of the `MySqlClientPermission' class: Note: This configuration is the most generalized way that includes all keywords. 3. Configure the MySQL server to accept pipe connections, by adding the `--enable-named-pipe' option on the command line. If you need more information about this, see *Note windows-installation::. 4. Confirm that the hosting provider has installed the Connector/Net library (`MySql.Data.dll') in the GAC. 5. Optionally, the hosting provider can avoid granting permissions globally by using the new `MySqlClientPermission' class in the trust policies. (The alternative is to globally enable the permissions `System.Net.SocketPermission', `System.Security.Permissions.ReflectionPermission', `System.Net.DnsPermission', and `System.Security.Permissions.SecurityPermission'.) 6. Create a simple web application using Visual Studio 2010. 7. Add the reference in your application for the `MySql.Data.MySqlClient' library. 8. Edit your `web.config' file so that your application runs using a Medium trust level: 9. Add the `MySql.Data.MySqlClient' namespace to your server-code page. 10. Define the connection string, in slightly different ways depending on the Connector/Net version. *Only for 6.6.4 or later:* To use the connections inside any web application that will run in Medium trust, add the new `includesecurityasserts' option to the connection string. `includesecurityasserts=true' that makes the library request the following permissions when required: `SocketPermissions', `ReflectionPermissions', `DnsPermissions', `SecurityPermissions' among others that are not granted in Medium trust levels. *For Connector/Net 6.6.3 or earlier:* No special setting for security is needed within the connection string. MySqlConnectionStringBuilder myconnString = new MySqlConnectionStringBuilder("server=localhost;User Id=root;database=test;"); myconnString.PipeName = "MySQL55"; myconnString.ConnectionProtocol = MySqlConnectionProtocol.Pipe; // Following attribute is a new requirement when the library is in the GAC. // Could also be done by adding includesecurityasserts=true; to the string literal // in the constructor above. // Not needed with Connector/Net 6.6.3 and earlier.*myconnString.IncludeSecurityAsserts = true;* 11. Define the `MySqlConnection' to use: MySqlConnection myconn = new MySqlConnection(myconnString.ConnectionString); myconn.Open(); 12. Retrieve some data from your tables: MySqlCommand cmd = new MySqlCommand("Select * from products", myconn); MySqlDataAdapter da = new MySqlDataAdapter(cmd); DataSet1 tds = new DataSet1(); da.Fill(tds, tds.Tables[0].TableName); GridView1.DataSource = tds; GridView1.DataBind(); myconn.Close() 13. Run the program. It should execute successfully, without requiring any special code or encountering any security problems.  File: manual.info, Node: connector-net-medium-trust-nongac, Prev: connector-net-medium-trust-gac, Up: connector-net-medium-trust 21.2.5.41 Configuring Partial Trust with Connector/Net Library Not Installed in GAC ................................................................................... When deploying a web application to a Shared Hosted environment, where this environment is configured to run all their .NET applications under a partial or medium trust level, you might not be able to install the Connector/Net library in the GAC. Instead, you put a reference to the library in the `bin' or `lib' folder inside the project or solution. In this case, you configure the security in a different way than when the library is in the GAC. Connector/Net is commonly used by applications that run in Windows environments where the default communication for the protocol is used via sockets or by TCP/IP. For this protocol to operate is necessary have the required socket permissions in the web configuration file as follows: 1. Open the medium trust policy web configuration file, which should be under this folder: %windir%\Microsoft.NET\Framework\{VERSION}\CONFIG\web_mediumtrust.config Use `Framework64' in the path instead of `Framework' if you are using a 64-bit installation of the framework. 2. Locate the `SecurityClasses' tag: 3. Scroll down and look for the following `PermissionSet': 4. Add the following inside this `PermissionSet': This configuration lets you use the driver with the default Windows protocol TCP/IP without having any security issues. This approach only supports the TCP/IP protocol, so you cannot use any other type of connection. Also, since the `MySQLClientPermissions' class is not added to the medium trust policy, you cannot use it. This configuration is the minimum required in order to work with Connector/Net without the GAC.  File: manual.info, Node: connector-net-connection-options, Next: connector-net-rt, Prev: connector-net-programming, Up: connector-net 21.2.6 Connector/Net Connection String Options Reference -------------------------------------------------------- For usage information about connection strings, see *Note connector-net-programming-connecting-connection-string::. The first table list options that apply generally to all server configurations. The options related to systems using a connection pool are split into a separate table. * General Options * *Connector/Net Connection String Options - General* Name Default Description `Allow Batch', true When true, multiple SQL statements can `AllowBatch' be sent with one command execution. Note: starting with MySQL 4.1.1, batch statements should be separated by the server-defined separator character. Statements sent to earlier versions of MySQL should be separated by ';'. `Allow User Variables', false Setting this to `true' indicates that `AllowUserVariables' the provider expects user variables in the SQL. This option was added in Connector/Net version 5.2.2. `Allow Zero Datetime', false If set to `True', `AllowZeroDateTime' `MySqlDataReader.GetValue()' returns a `MySqlDateTime' object for date or datetime columns that have disallowed values, such as zero datetime values, and a `System.DateTime' object for valid values. If set to `False' (the default setting) it causes a `System.DateTime' object to be returned for all valid values and an exception to be thrown for disallowed values, such as zero datetime values. `Auto Enlist', true If `AutoEnlist' is set to `true', which `AutoEnlist' is the default, a connection opened using `TransactionScope' participates in this scope, it commits when the scope commits and rolls back if `TransactionScope' does not commit. However, this feature is considered security sensitive and therefore cannot be used in a medium trust environment. `BlobAsUTF8ExcludePattern'null A POSIX-style regular expression that matches the names of BLOB columns that do not contain UTF-8 character data. See *Note connector-net-using-character-sets:: for usage details. `BlobAsUTF8IncludePattern'null A POSIX-style regular expression that matches the names of BLOB columns containing UTF-8 character data. See *Note connector-net-using-character-sets:: for usage details. `Certificate File', null This option specifies the path to a `CertificateFile' certificate file in PKCS #12 format (`.pfx'). For an example of usage, see *Note connector-net-tutorials-ssl::. Was introduced with 6.2.1. `Certificate Password', null Specifies a password that is used in `CertificatePassword' conjunction with a certificate specified using the option `CertificateFile'. For an example of usage, see *Note connector-net-tutorials-ssl::. Was introduced with 6.2.1. `Certificate Store null Enables you to access a certificate Location', held in a personal store, rather than `CertificateStoreLocation' use a certificate file and password combination. For an example of usage, see *Note connector-net-tutorials-ssl::. Was introduced with 6.2.1. `Certificate Thumbprint', null Specifies a certificate thumbprint to `CertificateThumbprint' ensure correct identification of a certificate contained within a personal store. For an example of usage, see *Note connector-net-tutorials-ssl::. Was introduced with 6.2.1. `CharSet', `Character Specifies the character set that should Set', `CharacterSet' be used to encode all queries sent to the server. Resultsets are still returned in the character set of the result data. `Check Parameters', true Indicates if stored routine parameters `CheckParameters' should be checked against the server. `Command Interceptors', The list of interceptors that can `CommandInterceptors' intercept SQL command operations. `Connect Timeout', 15 The length of time (in seconds) to wait `Connection Timeout', for a connection to the server before `ConnectionTimeout' terminating the attempt and generating an error. `Connect_Attrs' Passes a predefined set of key/value pairs containing connection-specific data items to the server, for application-defined purposes. connector/Net automatically transmits the following attributes: `_pid', `_client_version', `_platform', `_program_name', `_os', `_os_details', and `_thread'. See Performance Schema Connection Attribute Tables (http://dev.mysql.com/doc/refman/5.6/en/performance-schema-connection-attribute-tables.html) for the Performance Schema (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_performance_schema) tables to query on the server side to make use of these attributes. `Convert Zero Datetime', false True to have `ConvertZeroDateTime' `MySqlDataReader.GetValue()' and `MySqlDataReader.GetDateTime()' return `DateTime.MinValue' for date or datetime columns that have disallowed values. `Default Command 30 Sets the default value of the command Timeout', timeout to be used. This does not `DefaultCommandTimeout' supersede the individual command timeout property on an individual command object. If you set the command timeout property, that will be used. This option was added in Connector/Net 5.1.4 `Default Table Cache 60 Specifies how long a `TableDirect' Age', result should be cached, in seconds. `DefaultTableCacheAge' For usage information about table caching, see *Note connector-net-programming-tablecaching::. This option was added in Connector/Net 6.4. `enableSessionExpireCallback'false When set to `true', causes the session-expiry scanner to raise the `session_end' event before deleting the session data stored in the `my_aspnet_sessions' table, when a session times out. Enable this option to write additional application-specific cleanup code to handle the `session_end' event of the `global.asax' class, before the stored data of the session gets deleted. Within the session_end method, any other required cleanup can be done. This option was added in Connector/Net 6.4.5; it is not yet available in Connector/Net 6.5.x releases. `Encrypt', `UseSSL' false For Connector/Net 5.0.3 and later, when `true', SSL encryption is used for all data sent between the client and server if the server has a certificate installed. Recognized values are `true', `false', `yes', and `no'. In versions before 5.0.3, this option had no effect. From version 6.2.1, this option is deprecated and is replaced by `SSL Mode'. The option still works if used. If this option is set to true, it is equivalent to `SSL Mode = Preferred'. `Exception Interceptors', The list of interceptors that can `ExceptionInterceptors' triage thrown `MySqlException' exceptions. `Functions Return false Causes the connector to return String', binary/varbinary values as strings, if `FunctionsReturnString' they do not have a tablename in the metadata. `Host', `Server', `Data localhostThe name or network address of the Source', `DataSource', instance of MySQL to which to connect. `Address', `Addr', Multiple hosts can be specified `Network Address' separated by commas. This can be useful where multiple MySQL servers are configured for replication and you are not concerned about the precise server you are connecting to. No attempt is made by the provider to synchronize writes to the database, so take care when using this option. In Unix environment with Mono, this can be a fully qualified path to a MySQL socket file. With this configuration, the Unix socket is used instead of the TCP/IP socket. Currently, only a single socket name can be given, so accessing MySQL in a replicated environment using Unix sockets is not currently supported. `Ignore Prepare', true When true, instructs the provider to `IgnorePrepare' ignore any calls to `MySqlCommand.Prepare()'. This option is provided to prevent issues with corruption of the statements when used with server-side prepared statements. If you use server-side prepare statements, set this option to false. This option was added in Connector/Net 5.0.3 and Connector/Net 1.0.9. `includesecurityasserts', false Must be set to `true' when using the `include security `MySQLClientPermissions' class in a asserts' partial trust environment, with the library installed in the GAC of the hosting environment. This requirement is new for partial-trust applications in Connector/Net 6.6.4 and higher. See *Note connector-net-medium-trust:: for details. `Initial Catalog', mysql The case-sensitive name of the database `Database' to use initially. `Interactive', false If set to true, the client is `Interactive Session', interactive. An interactive client is `InteractiveSession' one where the server variable `CLIENT_INTERACTIVE' is set. If an interactive client is set, the `wait_timeout' variable is set to the value of `interactive_timeout'. The client will then time out after this period of inactivity. For more details, see *Note server-system-variables:: in the MySQL Reference Manual. `Integrated Security', no Use Windows authentication when `IntegratedSecurity' connecting to server. By default, it is turned off. To enable, specify a value of `yes'. (You can also use the value `sspi' as an alternative to `yes'.) For details, see *Note connector-net-programming-authentication-windows-native::. This option was introduced in Connector/Net 6.4.4. `Keep Alive', `Keepalive' 0 For TCP connections, idle connection time measured in seconds, before the first keepalive packet is sent. A value of 0 indicates that keepalive is not used. `Logging' false When true, various pieces of information is output to any configured TraceListeners. See *Note connector-net-programming-tracing:: for further details. `Old Guids', `OldGuids' false This option was introduced in Connector/Net 6.1.1. The backend representation of a GUID type was changed from `BINARY(16)' to `CHAR(36)'. This was done to allow developers to use the server function `UUID()' to populate a GUID table - `UUID()' generates a 36-character string. Developers of older applications can add `'Old Guids=true'' to the connection string to use a GUID of data type *Note `BINARY(16)': binary-varbinary. `Old Syntax', false This option was deprecated in `OldSyntax', `Use Old Connector/Net 5.2.2. All code should now Syntax', `UseOldSyntax' be written using the '@' symbol as the parameter marker. `Password', `pwd' The password for the MySQL account being used. `Persist Security Info', false When set to `false' or `no' (strongly `PersistSecurityInfo' recommended), security-sensitive information, such as the password, is not returned as part of the connection if the connection is open or has ever been in an open state. Resetting the connection string resets all connection string values, including the password. Recognized values are `true', `false', `yes', and `no'. `Pipe Name', `Pipe', mysql When set to the name of a named pipe, `PipeName' the `MySqlConnection' attempts to connect to MySQL on that named pipe. This setting only applies to the Windows platform. `Port' 3306 The port MySQL is using to listen for connections. This value is ignored if Unix socket is used. `Procedure Cache Size', 25 Sets the size of the stored procedure `ProcedureCacheSize', cache. By default, Connector/Net stores `procedure cache', the metadata (input/output data types) `procedurecache' about the last 25 stored procedures used. To disable the stored procedure cache, set the value to zero (0). This option was added in Connector/Net 5.0.2 and Connector/Net 1.0.9. `Protocol', `Connection socket Specifies the type of connection to Protocol', make to the server. Values can be: `ConnectionProtocol' `socket' or `tcp' for a socket connection, `pipe' for a named pipe connection, `unix' for a Unix socket connection, `memory' to use MySQL shared memory. `Replication' false Indicates if this connection is to use replicated servers. `Respect Binary Flags', true Setting this option to `false' means `RespectBinaryFlags' that Connector/Net ignores a column's binary flags as set by the server. This option was added in Connector/Net version 5.1.3. `Shared Memory Name', MYSQL The name of the shared memory object to `SharedMemoryName' use for communication if the connection protocol is set to `memory'. `Sql Server Mode', false Allow SQL Server syntax. When set to `sqlservermode' `true', enables Connector/Net to support square brackets around symbols instead of backticks. This enables Visual Studio wizards that bracket symbols with [] to work with Connector/Net. This option incurs a performance hit, so should only be used if necessary. This option was added in version 6.3.1. `SSL Mode', `SslMode' None This option has the following values: * *None* - do not use SSL. * *Preferred* - use SSL if the server supports it, but allow connection in all cases. * *Required* - Always use SSL. Deny connection if server does not support SSL. * *VerifyCA* - Always use SSL. Validate the CA but tolerate name mismatch. * *VerifyFull* - Always use SSL. Fail if the host name is not correct. This option was introduced in MySQL Connector/Net 6.2.1. `Table Cache', false Enables or disables caching of `tablecache', `TableDirect' commands. A value of `tablecaching' `true' enables the cache while `false' disables it. For usage information about table caching, see *Note connector-net-programming-tablecaching::. This option was added in Connector/Net 6.4. `Treat BLOBs as UTF8', false `TreatBlobsAsUTF8' `Treat Tiny As Boolean', true Setting this value to `false' causes `TreatTinyAsBoolean' `TINYINT(1)' to be treated as an *Note `INT': integer-types. See *Note numeric-type-overview:: for a further explanation of the *Note `TINYINT': integer-types. and *Note `BOOL': integer-types. data types. `Use Affected Rows', false When `true', the connection reports `UseAffectedRows' changed rows instead of found rows. This option was added in Connector/Net version 5.2.6. `Use Procedure Bodies', true When set to `true', the default value, `UseProcedureBodies', MySQL Connector/Net expects the body of `procedure bodies' the procedure to be viewable. This enables it to determine the parameter types and order. Set the option to `false' when the user connecting to the database does not have the `SELECT' privileges for the `mysql.proc' (stored procedures) table, or cannot view *Note `INFORMATION_SCHEMA.ROUTINES': routines-table. In this case, MySQL Connector/Net cannot determine the types and order of the parameters, and must be alerted to this fact by setting this option to `false'. When set to `false', MySQL Connector/Net does not rely on this information being available when the procedure is called. Because MySQL Connector/Net will not be able to determine this information, explicitly set the types of all the parameters before the call and add the parameters to the command in the same order as they appear in the procedure definition. This option was added in MySQL Connector/Net 5.0.4 and MySQL Connector/Net 1.0.10. `User Id', `UserID', The MySQL login account being used. `Username', `Uid', `User name', `User' `Compress', `Use false Setting this option to `true' enables Compression', compression of packets exchanged `UseCompression' between the client and the server. This exchange is defined by the MySQL client/server protocol. Compression is used if both client and server support ZLIB compression, and the client has requested compression using this option. A compressed packet header is: packet length (3 bytes), packet number (1 byte), and Uncompressed Packet Length (3 bytes). The Uncompressed Packet Length is the number of bytes in the original, uncompressed packet. If this is zero, the data in this packet has not been compressed. When the compression protocol is in use, either the client or the server may compress packets. However, compression will not occur if the compressed length is greater than the original length. Thus, some packets will contain compressed data while other packets will not. `Use Usage Advisor', false Logs inefficient database operations. `Usage Advisor', `UseUsageAdvisor' `Use Performance false Indicates that performance counters Monitor', should be updated during execution. `UsePerformanceMonitor', `userperfmon', `perfmon' * Connection Pooling Options * The following table lists the valid names for options related to connection pooling within the `ConnectionString'. For more information about connection pooling, see *Note connector-net-programming-connection-pooling::. *Connector/Net Connection String Options - Connection Pooling* Name Default Description `Cache Server false Specifies whether server variable Properties', settings are updated by a `SHOW `CacheServerProperties' VARIABLES' command each time a pooled connection is returned. Enabling this setting speeds up connections in a connection pool environment. Your application is not informed of any changes to configuration variables made by other connections. This option was added in Connector/Net 6.3. `Connection Lifetime', 0 When a connection is returned to the `ConnectionLifeTime' pool, its creation time is compared with the current time, and the connection is destroyed if that time span (in seconds) exceeds the value specified by `Connection Lifetime'. This is useful in clustered configurations to force load balancing between a running server and a server just brought online. A value of zero (0) causes pooled connections to have the maximum connection timeout. `Connection Reset', false If true, the connection state is reset `ConnectionReset' when it is retrieved from the pool. The default value of false avoids making an additional server round trip when obtaining a connection, but the connection state is not reset. `Maximum Pool Size', 100 The maximum number of connections `Max Pool Size', allowed in the pool. `maximumpoolsize' `Minimum Pool Size', 0 The minimum number of connections `Min Pool Size', allowed in the pool. `MinimumPoolSize' `Pooling' true When `true', the `MySqlConnection' object is drawn from the appropriate pool, or if necessary, is created and added to the appropriate pool. Recognized values are `true', `false', `yes', and `no'.  File: manual.info, Node: connector-net-rt, Next: connector-net-entityframework50, Prev: connector-net-connection-options, Up: connector-net 21.2.7 Connector/Net Support for Windows Store ---------------------------------------------- Starting with 6.7, Connector/Net fully supports building Windows Store apps. Windows Store are based on .NET but use a very restrictive subset of that functionality. The main difference is the complete lack of the ADO.Net data subsystem. Below is a list of the differences between Connector/Net 6.7 and Connector/Net RT 6.7. Please note that we are looking at ways of bringing these functionalities back in future versions. * No support for MySqlDataAdapter. MySqlCommand and MySqlDataReader are supported. * Connector/Net RT does not support SSL connections or Windows authentication. Also, SHA256 is not currectly supported. * Connector/Net RT only supports TCP connections. Named pipe and shared memory connections are not supported. * Connector/Net RT doesn't support tracing. This version of Connector/Net is no longer supported. * Connector/Net RT doesn't support load balancing. Command and Exception interceptors are supported however. This version of Connector/Net is no longer supported. * MySqlConnection.GetSchema methods do not return DataTable types. Instead they return a new object called MySqlSchemaCollection. You can query this object for the schema information. Normal Connector/Net will include support for returning schema information in both DataTable and MySqlSchemaCollection format. This version of Connector/Net is no longer supported. * Some contructors and other apis on supported classes may have been removed or altered. Any API that used DataTable, DataSet, or DataRow has been altered or removed. This version of Connector/Net is no longer supported. Using Connector/Net RT is easy. Simply create a Windows Store application using Visual Studio and then reference the MySql.Data.RT.dll assembly in your project. The code you write should be exactly the same as for normal Connector/Net (including using same namespace MySql.Data.MySqlClient) except for the differences listed above.  File: manual.info, Node: connector-net-entityframework50, Next: connector-net-ref, Prev: connector-net-rt, Up: connector-net 21.2.8 EF 5 Support ------------------- EF 5 Support is based on the new support for .Net Framework 4.5 which is the default target framework in the latest version of VS (2012). Using this framework version is a requirement in order to use any EF 5 feature. Below is a detailed description on each one of the features. * EF 5 Features * Spatial Data Type (Geometry type support). Spatial data types support is backed up by the server capabilities which are documented at: *Note spatial-extensions:: There are different types for spatial data, and the instantiable types that are supported at MySQL are: Point, LineString, Polygon, GeometryCollection, MultiPoint, MultiLineString, and MultiPolygon. At Connector/Net these different types can be managed with the new Geometry type. Before Connector/Net 6.7 the Geometry types didn't have a MySql Type inside the driver. So most of the users had to use it by using a binary type. This is not longer needed. Now all the specific operations for any Geometry type can be done by using this new class. An example of how to write a point data is shown here using Connector/Net 6.7 and MySQL Server 5.6.7 or further. //Storing a geometry point MySqlConnection conn = new MySqlConnection("server=localhost;userid=root;database=testgeo;"); conn.Open(); MySqlCommand cmd = new MySqlCommand("CREATE TABLE Test (v Geometry NOT NULL)"); cmd.Connection = conn; cmd.ExecuteNonQuery(); cmd = new MySqlCommand("INSERT INTO Test VALUES(GeomFromText(?v))", conn); cmd.Parameters.Add("?v",MySqlDbType.String); cmd.Parameters[0].Value = "POINT(47.37-122.21)"; cmd.ExecuteNonQuery(); cmd.CommandText = "SELECT AsText(v) FROM Test"; using(MySqlDataReader reader = cmd.ExecuteReader()) { reader.Read(); varval = reader.GetValue(0); Console.WriteLine(val); } conn.Close(); Output POINT(47.37, -122.21) To read a set of rows that contains a Geometry column can be achieved by using an appropiate MySqlDataReader. Example: cmd.CommandText = "SELECT v FROM Test"; using(MySqlDataReader reader = cmd.ExecuteReader()) { reader.Read(); var val = reader.GetMySqlGeometry(0); var valWithName = reader.GetMySqlGeometry("v"); Console.WriteLine(val.ToString()); // output : ("POINT(47.37 -122.21)" Console.WriteLine(valWithName.ToString()); // output("POINT(47.37 -122.21)" } A geometry point also can contain an SRID (Spatial Reference System Identifier)value. This value can also be stored using a geometry type: Example: MySqlGeometry v = new MySqlGeometry(47.37, -122.21, 101); var par =new MySqlParameter("?v", MySqlDbType.Geometry); par.Value = v; MySqlCommand cmd = new MySqlCommand("INSERT INTO Test VALUES(?v)", conn); cmd.Parameters.Add(par); cmd.ExecuteNonQuery(); cmd.CommandText = "SELECT SRID(v) FROM Test"; using (MySqlDataReader reader = cmd.ExecuteReader()) { reader.Read(); var val = reader.GetString(0); Console.WriteLine(val); // output "101" } Another types of values besides point can be stored at the Geometry type: * LineString * MultiLineString * Polygon * MultiPolygon * GeometryCollection Spatial data is supported in Model, Database and Code First. Using spatial types with an Entity Framework Model is one of the new features of Connector/Net 6.7. Spatial types can be used with any of the strategies used to create the data layer of any application: Database First, Code First or Model First. Entity Framework support two main types for spatial data: DbGeometry and DBGeography. The second one is not supported at Connector/Net since the MySQL server doesn't have any equivalent type to which map this type in. So all the examples will use the DbGeometry type. Example of usage in Code First. An entity that contains a Geometry column can be defined as follows: public class Distributor { public int DistributorId { get; set; } public string Name { get; set; } public DbGeometry point { get; set; } } public class DistributorsContext : DbContext { public DbSet Distributors { get; set; } } Creating the db: using (DistributorsContext context = new DistributorsContext()) { context.Database.Delete(); context.Database.Create(); context.Distributors.Add(new Distributor() { Name = "Graphic Design Institute", point = DbGeometry.FromText("POINT(-122.336106 47.605049)",101), }); context.SaveChanges(); var result = (from u in context.Distributors select u.point.CoordinateSystemId).ToList(); foreach (var item in result) Console.WriteLine("CoordinateSystemId " + item); Output: CoordinateSystemId 101 * Spatial supported Functions * There are some useful functions that takes Geometry values: * SpatialDimension * SpatialEnvelope * IsSimpleGeometry * SpatialTypeName * CoordinateSystemId * Point * XCoordinate * YCoordinate * GeometryFromText * SpatialContains * AsText * SpatialBuffer * SpatialDifference * SpatialIntersection * Enum types Support * * Enumeration types are used to define a set of named constants that may be assigned to a numeric value. * By default the underlying type of each element in the enum is int. But it can be specified another numeric type by using a colon. Example:enum Months : byte { Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec }; * When a value is not specified in the defined list, the values are automatically incremented by 1. In the previous exampleMonths.Jan has a default value of 0. In order to use enum types inside an Entity Framework defined class it should follow the next steps: In Visual Studio 2012 Using Database First approach * Create a new project (make sure .NET framework is target in the New Project dialog.), * Add a new Entity Model * Select the Existing Database option * Select the tables to be imported in the model * In order to create an Enum Type an integer column should exists inside of a table. * In the Model designer select the table to use. * Right click on the column of integer type and select Create enum type. * At this point all linq to entities query can use the Enum type directly. Example: using (var db = new DistributorsEntities()) { db.Database.CreateIfNotExists(); db.distributors.Add(new distributor { Type = DistributorType.Regional }); db.distributors.Add(new distributor { Type = DistributorType.Reseller }); db.distributors.Add(new distributor { Type = DistributorType.Zone }); db.SaveChanges(); var testQ = (from d in db.distributors select d).FirstOrDefault(); foreach (var item in testQ) Console.WriteLine(item.Type); } Output: Regional Reseller Zone Other important features and improvements included in Entity Framework are: * All LINQ queries are now automatically compiled and cached to improve query performance. * Multiple Diagrams for a model is supported. * Enhancement Table per type in SQL Generation. * Performance Enhancements. * The StoreGeneratedPattern for key columns can now be set on an entity Properties window and this value will propagate from the entity model down to the stored definition. The stored Generated Pattern attribute allows to control how the Entity Framework synchronizes database column values and entity property values;  File: manual.info, Node: connector-net-ref, Next: connector-net-support, Prev: connector-net-entityframework50, Up: connector-net 21.2.9 Connector/Net API Reference ---------------------------------- * Menu: * connector-net-ref-mysqlclient:: `MySql.Data.MySqlClient' Namespace * connector-net-ref-types:: `MySql.Data.Types' Namespace This section of the manual contains a complete reference to the Connector/Net ADO.NET component, automatically generated from the embedded documentation.  File: manual.info, Node: connector-net-ref-mysqlclient, Next: connector-net-ref-types, Prev: connector-net-ref, Up: connector-net-ref 21.2.9.1 `MySql.Data.MySqlClient' Namespace ........................................... * Menu: * connector-net-ref-mysqlclienthierarchy:: `MySql.Data.MySqlClientHierarchy' * connector-net-ref-mysqlclient-basecommandinterceptor:: `BaseCommandInterceptor' * connector-net-ref-mysqlclient-baseexceptioninterceptor:: `BaseExceptionInterceptor' * connector-net-ref-mysqlclient-mysqlcommand:: `MySqlCommand' Class * connector-net-ref-mysqlclient-mysqlcommandbuilder:: `MySqlCommandBuilder' Class * connector-net-ref-mysqlclient-mysqlexception:: `MySqlException' Class * connector-net-ref-mysqlclient-mysqlhelper:: `MySqlHelper' Class * connector-net-ref-mysqlclient-mysqlerrorcode:: `MySqlErrorCode' Enumeration *Note Namespace hierarchy: connector-net-ref-mysqlclienthierarchy. *Classes* Classes in the MySql.Data.MySqlClient namespace. Class Description *Note BaseCommandInterceptor: Provides a means of enhancing or connector-net-ref-mysqlclient-basecommandinterceptor.replacing SQL commands through the connection string rather than recompiling. *Note BaseExceptionInterceptor: Provides a means of enabling and connector-net-ref-mysqlclient-baseexceptioninterceptor.disabling exception handling through the connection string rather than recompiling. MySqlClientPermission Derived from the .NET DBDataPermission (http://msdn.microsoft.com/en-us/library/system.data.common.dbdatapermission.aspx) class. For usage information, see *Note connector-net-medium-trust::. *Note MySqlCommand: connector-net-ref-mysqlclient-mysqlcommand. *Note MySqlCommandBuilder: connector-net-ref-mysqlclient-mysqlcommandbuilder. *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. *Note MySqlDataAdapter: connector-net-ref-mysqlclient-mysqldataadapter. *Note MySqlDataReader: Provides a means of reading a connector-net-ref-mysqlclient-mysqldatareader.forward-only stream of rows from a MySQL database. This class cannot be inherited. *Note MySqlError: Collection of error codes that can connector-net-ref-mysqlclient-mysqlerror.be returned by the server *Note MySqlException: The exception that is thrown when connector-net-ref-mysqlclient-mysqlexception.MySQL returns an error. This class cannot be inherited. *Note MySqlHelper: Helper class that makes it easier connector-net-ref-mysqlclient-mysqlhelper.to work with the provider. *Note MySqlInfoMessageEventArgs: Provides data for the InfoMessage connector-net-ref-mysqlclient-mysqlinfomessageeventargs.event. This class cannot be inherited. *Note MySqlParameter: Represents a parameter to a *Note connector-net-ref-mysqlclient-mysqlparameter.MySqlCommand: connector-net-ref-mysqlclient-mysqlcommand, and optionally, its mapping to DataSetcolumns. This class cannot be inherited. *Note MySqlParameterCollection: Represents a collection of connector-net-ref-mysqlclient-mysqlparametercollection.parameters relevant to a *Note MySqlCommand: connector-net-ref-mysqlclient-mysqlcommand. as well as their respective mappings to columns in a DataSet. This class cannot be inherited. *Note MySqlRowUpdatedEventArgs: Provides data for the RowUpdated connector-net-ref-mysqlclient-mysqlrowupdatedeventargs.event. This class cannot be inherited. *Note MySqlRowUpdatingEventArgs: Provides data for the RowUpdating connector-net-ref-mysqlclient-mysqlrowupdatingeventargs.event. This class cannot be inherited. *Note MySqlTransaction: connector-net-ref-mysqlclient-mysqltransaction. *Delegates* Delegates in the MySql.Data.MySqlClient namespace. Delegate Description *Note MySqlInfoMessageEventHandler: Represents the method that will connector-net-ref-mysqlclient-mysqlinfomessageeventhandler.handle the *Note InfoMessage: connector-net-ref-mysqlclient-mysqlconnection-infomessage. event of a *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. *Note MySqlRowUpdatedEventHandler: Represents the method that will connector-net-ref-mysqlclient-mysqlrowupdatedeventhandler.handle the RowUpdatedevent of a *Note MySqlDataAdapter: connector-net-ref-mysqlclient-mysqldataadapter. *Note MySqlRowUpdatingEventHandler: Represents the method that will connector-net-ref-mysqlclient-mysqlrowupdatingeventhandler.handle the RowUpdatingevent of a *Note MySqlDataAdapter: connector-net-ref-mysqlclient-mysqldataadapter. *Enumerations* Enumerations in the MySql.Data.MySqlClient namespace. Enumeration Description *Note MySqlDbType: Specifies MySQL-specific data type connector-net-ref-mysqlclient-mysqldbtype.of a field, property, for use in a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. *Note MySqlErrorCode: connector-net-ref-mysqlclient-mysqlerrorcode.  File: manual.info, Node: connector-net-ref-mysqlclienthierarchy, Next: connector-net-ref-mysqlclient-basecommandinterceptor, Prev: connector-net-ref-mysqlclient, Up: connector-net-ref-mysqlclient 21.2.9.2 `MySql.Data.MySqlClientHierarchy' .......................................... *See Also* *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-basecommandinterceptor, Next: connector-net-ref-mysqlclient-baseexceptioninterceptor, Prev: connector-net-ref-mysqlclienthierarchy, Up: connector-net-ref-mysqlclient 21.2.9.3 `BaseCommandInterceptor' ................................. The `BaseCommandInterceptor' class has these methods that you can override: public virtual bool ExecuteScalar(string sql, ref object returnValue); public virtual bool ExecuteNonQuery(string sql, ref int returnValue); public virtual bool ExecuteReader(string sql, CommandBehavior behavior, ref MySqlDataReader returnValue); public virtual void Init(MySqlConnection connection); If your interceptor overrides one of the `Execute...' methods, set the `returnValue' output parameter and return `true' if you handled the event, or `false' if you did not handle the event. The SQL command is processed normally only when all command interceptors return `false'. The connection passed to the `Init' method is the connection that is attached to this interceptor. For full usage and examples, see *Note connector-net-interceptors::.  File: manual.info, Node: connector-net-ref-mysqlclient-baseexceptioninterceptor, Next: connector-net-ref-mysqlclient-mysqlcommand, Prev: connector-net-ref-mysqlclient-basecommandinterceptor, Up: connector-net-ref-mysqlclient 21.2.9.4 `BaseExceptionInterceptor' ................................... You develop an exception interceptor first by creating a subclass of the `BaseExceptionInterceptor' class. You must override the `InterceptException()' method. You can also override the `Init()' method to do some one-time initialization. Each exception interceptor has 2 methods: public abstract Exception InterceptException(Exception exception, MySqlConnection connection); public virtual void Init(MySqlConnection connection); The connection passed to `Init()' is the connection that is attached to this interceptor. Each interceptor is required to override `InterceptException' and return an exception. It can return the exception it is given, or it can wrap it in a new exception. We currently do not offer the ability to suppress the exception. For full usage and examples, see *Note connector-net-interceptors::.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand, Next: connector-net-ref-mysqlclient-mysqlcommandbuilder, Prev: connector-net-ref-mysqlclient-baseexceptioninterceptor, Up: connector-net-ref-mysqlclient 21.2.9.5 `MySqlCommand' Class ............................. * Menu: * connector-net-ref-mysqlclient-mysqlcommandmembers:: `MySqlCommand' Members For a list of all members of this type, see *Note MySqlCommand Members: connector-net-ref-mysqlclient-mysqlcommandmembers. *Syntax: Visual Basic* NotInheritable Public Class MySqlCommand_ Inherits Component_ Implements IDbCommand, ICloneable *Syntax: C#* public sealed class MySqlCommand : Component, IDbCommand, ICloneable *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlCommand Members: connector-net-ref-mysqlclient-mysqlcommandmembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandmembers, Prev: connector-net-ref-mysqlclient-mysqlcommand, Up: connector-net-ref-mysqlclient-mysqlcommand 21.2.9.6 `MySqlCommand' Members ............................... * Menu: * connector-net-ref-mysqlclient-mysqlcommandconstructor:: `MySqlCommand' Constructor * connector-net-ref-mysqlclient-mysqlcommand-commandtext:: CommandText Property * connector-net-ref-mysqlclient-mysqlcommand-commandtimeout:: CommandTimeout Property * connector-net-ref-mysqlclient-mysqlcommand-commandtype:: CommandType Property * connector-net-ref-mysqlclient-mysqlcommand-connection:: Connection Property * connector-net-ref-mysqlclient-mysqlcommand-isprepared:: IsPrepared Property * connector-net-ref-mysqlclient-mysqlcommand-parameters:: Parameters Property * connector-net-ref-mysqlclient-mysqlcommand-transaction:: Transaction Property * connector-net-ref-mysqlclient-mysqlcommand-updatedrowsource:: UpdatedRowSource Property * connector-net-ref-mysqlclient-mysqlcommand-cancel:: `MySqlCommand.Cancel' Method * connector-net-ref-mysqlclient-mysqlcommand-createparameter:: `MySqlCommand.CreateParameter' Method * connector-net-ref-mysqlclient-mysqlcommand-executenonquery:: `MySqlCommand.ExecuteNonQuery' Method * connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads:: ExecuteReader Method * connector-net-ref-mysqlclient-mysqlcommand-executescalar:: `MySqlCommand.ExecuteScalar' Method * connector-net-ref-mysqlclient-mysqlcommand-prepare:: `MySqlCommand.Prepare' Method *Note MySqlCommand overview: connector-net-ref-mysqlclient-mysqlcommand. *Public Instance Constructors* Public instance constructors in the MySql.Data.MySqlClient namespace. *Note MySqlCommand: Overloaded. Initializes a new connector-net-ref-mysqlclient-mysqlcommandconstructor.instance of the MySqlCommand class. *Public Instance Properties* Public instance properties in the MySql.Data.MySqlClient namespace. *Note CommandText: connector-net-ref-mysqlclient-mysqlcommand-commandtext. *Note CommandTimeout: connector-net-ref-mysqlclient-mysqlcommand-commandtimeout. *Note CommandType: connector-net-ref-mysqlclient-mysqlcommand-commandtype. *Note Connection: connector-net-ref-mysqlclient-mysqlcommand-connection. Container (inherited from Component) Gets the IContainer that contains the Component. *Note IsPrepared: connector-net-ref-mysqlclient-mysqlcommand-isprepared. *Note Parameters: connector-net-ref-mysqlclient-mysqlcommand-parameters. Site (inherited from Component) Gets or sets the ISite of the Component. *Note Transaction: connector-net-ref-mysqlclient-mysqlcommand-transaction. *Note UpdatedRowSource: connector-net-ref-mysqlclient-mysqlcommand-updatedrowsource. *Public Instance Methods* Public instance methods in the MySql.Data.MySqlClient namespace. *Note Cancel: Attempts to cancel the execution of connector-net-ref-mysqlclient-mysqlcommand-cancel.a MySqlCommand. This operation is not supported. CreateObjRef (inherited from Creates an object that contains all MarshalByRefObject) the relevant information required to generate a proxy used to communicate with a remote object. *Note CreateParameter: Creates a new instance of a *Note connector-net-ref-mysqlclient-mysqlcommand-createparameter.MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object. Dispose (inherited from Component) Releases all resources used by the Component. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. *Note ExecuteNonQuery: connector-net-ref-mysqlclient-mysqlcommand-executenonquery. *Note ExecuteReader: Overloaded. connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads. *Note ExecuteScalar: connector-net-ref-mysqlclient-mysqlcommand-executescalar. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetLifetimeService (inherited from Retrieves the current lifetime MarshalByRefObject) service object that controls the lifetime policy for this instance. GetType (inherited from Object) Gets the Type of the current instance. InitializeLifetimeService Obtains a lifetime service object (inherited from MarshalByRefObject) to control the lifetime policy for this instance. *Note Prepare: connector-net-ref-mysqlclient-mysqlcommand-prepare. ToString (inherited from Component) Returns a String containing the name of the Component, if any. This method should not be overridden. *Public Instance Events* Public instance events in the MySql.Data.MySqlClient namespace. Disposed (inherited from Component) Adds an event handler to listen to the Disposed event on the component. *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandconstructor, Next: connector-net-ref-mysqlclient-mysqlcommand-commandtext, Prev: connector-net-ref-mysqlclient-mysqlcommandmembers, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.7 `MySqlCommand' Constructor ................................... * Menu: * connector-net-ref-mysqlclient-mysqlcommandconstructor1:: `MySqlCommand' Constructor () * connector-net-ref-mysqlclient-mysqlcommandconstructor2:: `MySqlCommand' Constructor (String) * connector-net-ref-mysqlclient-mysqlcommandconstructor3:: `MySqlCommand' Constructor * connector-net-ref-mysqlclient-mysqlcommandconstructor4:: `MySqlCommand' Constructor Initializes a new instance of the *Note MySqlCommand: connector-net-ref-mysqlclient-mysqlcommand. class. *Overload List* Initializes a new instance of the *Note MySqlCommand: connector-net-ref-mysqlclient-mysqlcommand. class. * *Note public MySqlCommand();: connector-net-ref-mysqlclient-mysqlcommandconstructor1. * *Note public MySqlCommand(string);: connector-net-ref-mysqlclient-mysqlcommandconstructor2. * *Note public MySqlCommand(string: (MySqlConnection);)connector-net-ref-mysqlclient-mysqlcommandconstructor3. * *Note public MySqlCommand(string: (MySqlConnection)connector-net-ref-mysqlclient-mysqlcommandconstructor4. *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandconstructor1, Next: connector-net-ref-mysqlclient-mysqlcommandconstructor2, Prev: connector-net-ref-mysqlclient-mysqlcommandconstructor, Up: connector-net-ref-mysqlclient-mysqlcommandconstructor 21.2.9.8 `MySqlCommand' Constructor () ...................................... Initializes a new instance of the *Note MySqlCommand: connector-net-ref-mysqlclient-mysqlcommand. class. *Syntax: Visual Basic* Overloads Public Sub New() *Syntax: C#* public MySqlCommand(); *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommand Constructor Overload List: connector-net-ref-mysqlclient-mysqlcommandconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandconstructor2, Next: connector-net-ref-mysqlclient-mysqlcommandconstructor3, Prev: connector-net-ref-mysqlclient-mysqlcommandconstructor1, Up: connector-net-ref-mysqlclient-mysqlcommandconstructor 21.2.9.9 `MySqlCommand' Constructor (String) ............................................ *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal cmdText As String _ ) *Syntax: C#* public MySqlCommand( stringcmdText ); *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommand Constructor Overload List: connector-net-ref-mysqlclient-mysqlcommandconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandconstructor3, Next: connector-net-ref-mysqlclient-mysqlcommandconstructor4, Prev: connector-net-ref-mysqlclient-mysqlcommandconstructor2, Up: connector-net-ref-mysqlclient-mysqlcommandconstructor 21.2.9.10 `MySqlCommand' Constructor .................................... * Menu: * connector-net-ref-mysqlclient-mysqlconnection:: `MySqlConnection' Class *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal cmdText As String, _ ByVal connection As MySqlConnection _ ) *Syntax: C#* public MySqlCommand( stringcmdText, MySqlConnectionconnection ); *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommand Constructor Overload List: connector-net-ref-mysqlclient-mysqlcommandconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection, Prev: connector-net-ref-mysqlclient-mysqlcommandconstructor3, Up: connector-net-ref-mysqlclient-mysqlcommandconstructor3 21.2.9.11 `MySqlConnection' Class ................................. * Menu: * connector-net-ref-mysqlclient-mysqlconnectionmembers:: `MySqlConnection' Members For a list of all members of this type, see *Note MySqlConnection Members: connector-net-ref-mysqlclient-mysqlconnectionmembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlConnection_ Inherits Component_ Implements IDbConnection, ICloneable *Syntax: C#* public sealed class MySqlConnection : Component, IDbConnection, ICloneable *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlConnection Members: connector-net-ref-mysqlclient-mysqlconnectionmembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnectionmembers, Prev: connector-net-ref-mysqlclient-mysqlconnection, Up: connector-net-ref-mysqlclient-mysqlconnection 21.2.9.12 `MySqlConnection' Members ................................... * Menu: * connector-net-ref-mysqlclient-mysqlconnectionconstructor:: `MySqlConnection' Constructor * connector-net-ref-mysqlclient-mysqlconnection-connectionstring:: ConnectionString Property * connector-net-ref-mysqlclient-mysqlconnection-connectiontimeout:: ConnectionTimeout Property * connector-net-ref-mysqlclient-mysqlconnection-database:: Database Property * connector-net-ref-mysqlclient-mysqlconnection-datasource:: DataSource Property * connector-net-ref-mysqlclient-mysqlconnection-serverthread:: ServerThread Property * connector-net-ref-mysqlclient-mysqlconnection-serverversion:: ServerVersion Property * connector-net-ref-mysqlclient-mysqlconnection-state:: State Property * connector-net-ref-mysqlclient-mysqlconnection-usecompression:: UseCompression Property * connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads:: BeginTransaction Method * connector-net-ref-mysqlclient-mysqlconnection-changedatabase:: `MySqlConnection.ChangeDatabase' Method * connector-net-ref-mysqlclient-mysqlconnection-close:: `MySqlConnection.Close' Method * connector-net-ref-mysqlclient-mysqlconnection-createcommand:: `MySqlConnection.CreateCommand' Method * connector-net-ref-mysqlclient-mysqlconnection-open:: `MySqlConnection.Open' Method * connector-net-ref-mysqlclient-mysqlconnection-ping:: `MySqlConnection.Ping' Method * connector-net-ref-mysqlclient-mysqlconnection-infomessage:: `MySqlConnection.InfoMessage' Event * connector-net-ref-mysqlclient-mysqlconnection-statechange:: `MySqlConnection.StateChange' Event *Note MySqlConnection overview: connector-net-ref-mysqlclient-mysqlconnection. *Public Instance Constructors* Public instance constructors in the MySqlConnection class. *Note MySqlConnection: Overloaded. Initializes a new connector-net-ref-mysqlclient-mysqlconnectionconstructor.instance of the MySqlConnection class. *Public Instance Properties* Public instance properties in the MySqlConnection class. *Note ConnectionString: connector-net-ref-mysqlclient-mysqlconnection-connectionstring. *Note ConnectionTimeout: connector-net-ref-mysqlclient-mysqlconnection-connectiontimeout. Container (inherited from Component) Gets the IContainer that contains the Component. *Note Database: connector-net-ref-mysqlclient-mysqlconnection-database. *Note DataSource: Gets the name of the MySQL server connector-net-ref-mysqlclient-mysqlconnection-datasource.to which to connect. *Note ServerThread: Returns the ID of the server thread connector-net-ref-mysqlclient-mysqlconnection-serverthread.this connection is executing on. *Note ServerVersion: connector-net-ref-mysqlclient-mysqlconnection-serverversion. Site (inherited from Component) Gets or sets the ISite of the Component. *Note State: connector-net-ref-mysqlclient-mysqlconnection-state. *Note UseCompression: Indicates if this connection should connector-net-ref-mysqlclient-mysqlconnection-usecompression.use compression when communicating with the server. *Public Instance Methods* Public instance methods in the MySqlConnection class. *Note BeginTransaction: Overloaded. connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads. *Note ChangeDatabase: connector-net-ref-mysqlclient-mysqlconnection-changedatabase. *Note Close: connector-net-ref-mysqlclient-mysqlconnection-close. *Note CreateCommand: connector-net-ref-mysqlclient-mysqlconnection-createcommand. CreateObjRef (inherited from Creates an object that contains all MarshalByRefObject) the relevant information required to generate a proxy used to communicate with a remote object. Dispose (inherited from Component) Releases all resources used by the Component. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetLifetimeService (inherited from Retrieves the current lifetime MarshalByRefObject) service object that controls the lifetime policy for this instance. GetType (inherited from Object) Gets the Type of the current instance. InitializeLifetimeService Obtains a lifetime service object (inherited from MarshalByRefObject) to control the lifetime policy for this instance. *Note Open: connector-net-ref-mysqlclient-mysqlconnection-open. *Note Ping: Ping connector-net-ref-mysqlclient-mysqlconnection-ping. ToString (inherited from Component) Returns a String containing the name of the Component, if any. This method should not be overridden. *Public Instance Events* Public instance events in the MySqlConnection class. Disposed (inherited from Component) Adds an event handler to listen to the Disposed event on the component. *Note InfoMessage: connector-net-ref-mysqlclient-mysqlconnection-infomessage. *Note StateChange: connector-net-ref-mysqlclient-mysqlconnection-statechange. *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnectionconstructor, Next: connector-net-ref-mysqlclient-mysqlconnection-connectionstring, Prev: connector-net-ref-mysqlclient-mysqlconnectionmembers, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.13 `MySqlConnection' Constructor ....................................... * Menu: * connector-net-ref-mysqlclient-mysqlconnectionconstructor1:: `MySqlConnection' Constructor * connector-net-ref-mysqlclient-mysqlconnectionconstructor2:: `MySqlConnection' Constructor Initializes a new instance of the *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. class. *Overload List* Initializes a new instance of the *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. class. * *Note public MySqlConnection();: connector-net-ref-mysqlclient-mysqlconnectionconstructor1. * *Note public MySqlConnection(string);: connector-net-ref-mysqlclient-mysqlconnectionconstructor2. *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnectionconstructor1, Next: connector-net-ref-mysqlclient-mysqlconnectionconstructor2, Prev: connector-net-ref-mysqlclient-mysqlconnectionconstructor, Up: connector-net-ref-mysqlclient-mysqlconnectionconstructor 21.2.9.14 `MySqlConnection' Constructor ....................................... Initializes a new instance of the *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. class. *Syntax: Visual Basic* Overloads Public Sub New() *Syntax: C#* public MySqlConnection(); *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlConnection Constructor Overload List: connector-net-ref-mysqlclient-mysqlconnectionconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnectionconstructor2, Prev: connector-net-ref-mysqlclient-mysqlconnectionconstructor1, Up: connector-net-ref-mysqlclient-mysqlconnectionconstructor 21.2.9.15 `MySqlConnection' Constructor ....................................... *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal connectionString As String _ ) *Syntax: C#* public MySqlConnection( stringconnectionString ); *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlConnection Constructor Overload List: connector-net-ref-mysqlclient-mysqlconnectionconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-connectionstring, Next: connector-net-ref-mysqlclient-mysqlconnection-connectiontimeout, Prev: connector-net-ref-mysqlclient-mysqlconnectionconstructor, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.16 ConnectionString Property ................................... *Syntax: Visual Basic* NotOverridable Public Property ConnectionString As String _ _ Implements IDbConnection.ConnectionString *Syntax: C#* public string ConnectionString {get; set;} *Implements* IDbConnection.ConnectionString *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-connectiontimeout, Next: connector-net-ref-mysqlclient-mysqlconnection-database, Prev: connector-net-ref-mysqlclient-mysqlconnection-connectionstring, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.17 ConnectionTimeout Property .................................... *Syntax: Visual Basic* NotOverridable Public ReadOnly Property ConnectionTimeout As Integer _ _ Implements IDbConnection.ConnectionTimeout *Syntax: C#* public int ConnectionTimeout {get;} *Implements* IDbConnection.ConnectionTimeout *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-database, Next: connector-net-ref-mysqlclient-mysqlconnection-datasource, Prev: connector-net-ref-mysqlclient-mysqlconnection-connectiontimeout, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.18 Database Property ........................... *Syntax: Visual Basic* NotOverridable Public ReadOnly Property Database As String _ _ Implements IDbConnection.Database *Syntax: C#* public string Database {get;} *Implements* IDbConnection.Database *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-datasource, Next: connector-net-ref-mysqlclient-mysqlconnection-serverthread, Prev: connector-net-ref-mysqlclient-mysqlconnection-database, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.19 DataSource Property ............................. Gets the name of the MySQL server to which to connect. *Syntax: Visual Basic* Public ReadOnly Property DataSource As String *Syntax: C#* public string DataSource {get;} *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-serverthread, Next: connector-net-ref-mysqlclient-mysqlconnection-serverversion, Prev: connector-net-ref-mysqlclient-mysqlconnection-datasource, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.20 ServerThread Property ............................... Returns the ID of the server thread this connection is executing on *Syntax: Visual Basic* Public ReadOnly Property ServerThread As Integer *Syntax: C#* public int ServerThread {get;} *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-serverversion, Next: connector-net-ref-mysqlclient-mysqlconnection-state, Prev: connector-net-ref-mysqlclient-mysqlconnection-serverthread, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.21 ServerVersion Property ................................ *Syntax: Visual Basic* Public ReadOnly Property ServerVersion As String *Syntax: C#* public string ServerVersion {get;} *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-state, Next: connector-net-ref-mysqlclient-mysqlconnection-usecompression, Prev: connector-net-ref-mysqlclient-mysqlconnection-serverversion, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.22 State Property ........................ *Syntax: Visual Basic* NotOverridable Public ReadOnly Property State As ConnectionState _ _ Implements IDbConnection.State *Syntax: C#* public System.Data.ConnectionState State {get;} *Implements* IDbConnection.State *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-usecompression, Next: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads, Prev: connector-net-ref-mysqlclient-mysqlconnection-state, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.23 UseCompression Property ................................. Indicates if this connection should use compression when communicating with the server. *Syntax: Visual Basic* Public ReadOnly Property UseCompression As Boolean *Syntax: C#* public bool UseCompression {get;} *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads, Next: connector-net-ref-mysqlclient-mysqlconnection-changedatabase, Prev: connector-net-ref-mysqlclient-mysqlconnection-usecompression, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.24 BeginTransaction Method ................................. * Menu: * connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-1:: `MySqlConnection.BeginTransaction' Method * connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-2:: `MySqlConnection.BeginTransaction' Method *Overload List* * *Note public MySqlTransaction BeginTransaction();: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-1. * *Note public MySqlTransaction BeginTransaction(IsolationLevel);: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-2. *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-1, Next: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-2, Prev: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads, Up: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads 21.2.9.25 `MySqlConnection.BeginTransaction' Method ................................................... * Menu: * connector-net-ref-mysqlclient-mysqltransaction:: `MySqlTransaction' Class *Syntax: Visual Basic* Overloads Public Function BeginTransaction() As MySqlTransaction *Syntax: C#* public MySqlTransaction BeginTransaction(); *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlConnection.BeginTransaction Overload List: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqltransaction, Prev: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-1, Up: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-1 21.2.9.26 `MySqlTransaction' Class .................................. * Menu: * connector-net-ref-mysqlclient-mysqltransactionmembers:: `MySqlTransaction' Members For a list of all members of this type, see *Note MySqlTransaction Members: connector-net-ref-mysqlclient-mysqltransactionmembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlTransaction_ Implements IDbTransaction, IDisposable *Syntax: C#* public sealed class MySqlTransaction : IDbTransaction, IDisposable *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlTransaction Members: connector-net-ref-mysqlclient-mysqltransactionmembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqltransactionmembers, Prev: connector-net-ref-mysqlclient-mysqltransaction, Up: connector-net-ref-mysqlclient-mysqltransaction 21.2.9.27 `MySqlTransaction' Members .................................... * Menu: * connector-net-ref-mysqlclient-mysqltransaction-connection:: Connection Property * connector-net-ref-mysqlclient-mysqltransaction-isolationlevel:: IsolationLevel Property * connector-net-ref-mysqlclient-mysqltransaction-commit:: `MySqlTransaction.Commit' Method * connector-net-ref-mysqlclient-mysqltransaction-rollback:: `MySqlTransaction.Rollback' Method *Note MySqlTransaction overview: connector-net-ref-mysqlclient-mysqltransaction. *Public Instance Properties* Public instance properties in the MySqlTransaction class. *Note Connection: Gets the *Note MySqlConnection: connector-net-ref-mysqlclient-mysqltransaction-connection.connector-net-ref-mysqlclient-mysqlconnection. object associated with the transaction, or a null reference (Nothing in Visual Basic) if the transaction is no longer valid. *Note IsolationLevel: Specifies the IsolationLevel for connector-net-ref-mysqlclient-mysqltransaction-isolationlevel.this transaction. *Public Instance Methods* Public instance methods in the MySqlTransaction class. *Note Commit: connector-net-ref-mysqlclient-mysqltransaction-commit. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetType (inherited from Object) Gets the Type of the current instance. *Note Rollback: connector-net-ref-mysqlclient-mysqltransaction-rollback. ToString (inherited from Object) Returns a String that represents the current Object. *See Also* *Note MySqlTransaction Class: connector-net-ref-mysqlclient-mysqltransaction, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqltransaction-connection, Next: connector-net-ref-mysqlclient-mysqltransaction-isolationlevel, Prev: connector-net-ref-mysqlclient-mysqltransactionmembers, Up: connector-net-ref-mysqlclient-mysqltransactionmembers 21.2.9.28 Connection Property ............................. Gets the *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object associated with the transaction, or a null reference (Nothing in Visual Basic) if the transaction is no longer valid. *Syntax: Visual Basic* Public ReadOnly Property Connection As MySqlConnection *Syntax: C#* public MySqlConnection Connection {get;} *Property Value* The *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object associated with this transaction. *Remarks* A single application may have multiple database connections, each with zero or more transactions. This property enables you to determine the connection object associated with a particular transaction created by *Note BeginTransaction: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-1. *See Also* *Note MySqlTransaction Class: connector-net-ref-mysqlclient-mysqltransaction, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqltransaction-isolationlevel, Next: connector-net-ref-mysqlclient-mysqltransaction-commit, Prev: connector-net-ref-mysqlclient-mysqltransaction-connection, Up: connector-net-ref-mysqlclient-mysqltransactionmembers 21.2.9.29 IsolationLevel Property ................................. Specifies the IsolationLevel for this transaction. *Syntax: Visual Basic* NotOverridable Public ReadOnly Property IsolationLevel As IsolationLevel _ _ Implements IDbTransaction.IsolationLevel *Syntax: C#* public System.Data.IsolationLevel IsolationLevel {get;} *Property Value* The IsolationLevel for this transaction. The default is ReadCommitted. *Implements* IDbTransaction.IsolationLevel *Remarks* Parallel transactions are not supported. Therefore, the IsolationLevel applies to the entire transaction. *See Also* *Note MySqlTransaction Class: connector-net-ref-mysqlclient-mysqltransaction, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqltransaction-commit, Next: connector-net-ref-mysqlclient-mysqltransaction-rollback, Prev: connector-net-ref-mysqlclient-mysqltransaction-isolationlevel, Up: connector-net-ref-mysqlclient-mysqltransactionmembers 21.2.9.30 `MySqlTransaction.Commit' Method .......................................... *Syntax: Visual Basic* NotOverridable Public Sub Commit() _ _ Implements IDbTransaction.Commit *Syntax: C#* public void Commit(); *Implements* IDbTransaction.Commit *See Also* *Note MySqlTransaction Class: connector-net-ref-mysqlclient-mysqltransaction, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqltransaction-rollback, Prev: connector-net-ref-mysqlclient-mysqltransaction-commit, Up: connector-net-ref-mysqlclient-mysqltransactionmembers 21.2.9.31 `MySqlTransaction.Rollback' Method ............................................ *Syntax: Visual Basic* NotOverridable Public Sub Rollback() _ _ Implements IDbTransaction.Rollback *Syntax: C#* public void Rollback(); *Implements* IDbTransaction.Rollback *See Also* *Note MySqlTransaction Class: connector-net-ref-mysqlclient-mysqltransaction, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-2, Prev: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-1, Up: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads 21.2.9.32 `MySqlConnection.BeginTransaction' Method ................................................... *Syntax: Visual Basic* Overloads Public Function BeginTransaction( _ ByVal iso As IsolationLevel _ ) As MySqlTransaction *Syntax: C#* public MySqlTransaction BeginTransaction( IsolationLeveliso ); *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlConnection.BeginTransaction Overload List: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-changedatabase, Next: connector-net-ref-mysqlclient-mysqlconnection-close, Prev: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.33 `MySqlConnection.ChangeDatabase' Method ................................................. *Syntax: Visual Basic* NotOverridable Public Sub ChangeDatabase( _ ByVal databaseName As String _ ) _ _ Implements IDbConnection.ChangeDatabase *Syntax: C#* public void ChangeDatabase( stringdatabaseName ); *Implements* IDbConnection.ChangeDatabase *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-close, Next: connector-net-ref-mysqlclient-mysqlconnection-createcommand, Prev: connector-net-ref-mysqlclient-mysqlconnection-changedatabase, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.34 `MySqlConnection.Close' Method ........................................ *Syntax: Visual Basic* NotOverridable Public Sub Close() _ _ Implements IDbConnection.Close *Syntax: C#* public void Close(); *Implements* IDbConnection.Close *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-createcommand, Next: connector-net-ref-mysqlclient-mysqlconnection-open, Prev: connector-net-ref-mysqlclient-mysqlconnection-close, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.35 `MySqlConnection.CreateCommand' Method ................................................ *Syntax: Visual Basic* Public Function CreateCommand() As MySqlCommand *Syntax: C#* public MySqlCommand CreateCommand(); *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-open, Next: connector-net-ref-mysqlclient-mysqlconnection-ping, Prev: connector-net-ref-mysqlclient-mysqlconnection-createcommand, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.36 `MySqlConnection.Open' Method ....................................... *Syntax: Visual Basic* NotOverridable Public Sub Open() _ _ Implements IDbConnection.Open *Syntax: C#* public void Open(); *Implements* IDbConnection.Open *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-ping, Next: connector-net-ref-mysqlclient-mysqlconnection-infomessage, Prev: connector-net-ref-mysqlclient-mysqlconnection-open, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.37 `MySqlConnection.Ping' Method ....................................... Ping *Syntax: Visual Basic* Public Function Ping() As Boolean *Syntax: C#* public bool Ping(); *Return Value* *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-infomessage, Next: connector-net-ref-mysqlclient-mysqlconnection-statechange, Prev: connector-net-ref-mysqlclient-mysqlconnection-ping, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.38 `MySqlConnection.InfoMessage' Event ............................................. * Menu: * connector-net-ref-mysqlclient-mysqlinfomessageeventhandler:: `MySqlInfoMessageEventHandler' Delegate *Syntax: Visual Basic* Public Event InfoMessage As MySqlInfoMessageEventHandler *Syntax: C#* public event MySqlInfoMessageEventHandler InfoMessage; *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlinfomessageeventhandler, Prev: connector-net-ref-mysqlclient-mysqlconnection-infomessage, Up: connector-net-ref-mysqlclient-mysqlconnection-infomessage 21.2.9.39 `MySqlInfoMessageEventHandler' Delegate ................................................. * Menu: * connector-net-ref-mysqlclient-mysqlinfomessageeventargs:: `MySqlInfoMessageEventArgs' Class Represents the method that will handle the *Note InfoMessage: connector-net-ref-mysqlclient-mysqlconnection-infomessage. event of a *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. *Syntax: Visual Basic* Public Delegate Sub MySqlInfoMessageEventHandler( _ ByVal sender As Object, _ ByVal args As MySqlInfoMessageEventArgs _ ) *Syntax: C#* public delegate void MySqlInfoMessageEventHandler( objectsender, MySqlInfoMessageEventArgsargs ); *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlinfomessageeventargs, Prev: connector-net-ref-mysqlclient-mysqlinfomessageeventhandler, Up: connector-net-ref-mysqlclient-mysqlinfomessageeventhandler 21.2.9.40 `MySqlInfoMessageEventArgs' Class ........................................... * Menu: * connector-net-ref-mysqlclient-mysqlinfomessageeventargsmembers:: `MySqlInfoMessageEventArgs' Members Provides data for the InfoMessage event. This class cannot be inherited. For a list of all members of this type, see *Note MySqlInfoMessageEventArgs Members: connector-net-ref-mysqlclient-mysqlinfomessageeventargsmembers . *Syntax: Visual Basic* Public Class MySqlInfoMessageEventArgs_ Inherits EventArgs *Syntax: C#* public class MySqlInfoMessageEventArgs : EventArgs *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlInfoMessageEventArgs Members: connector-net-ref-mysqlclient-mysqlinfomessageeventargsmembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlinfomessageeventargsmembers, Prev: connector-net-ref-mysqlclient-mysqlinfomessageeventargs, Up: connector-net-ref-mysqlclient-mysqlinfomessageeventargs 21.2.9.41 `MySqlInfoMessageEventArgs' Members ............................................. * Menu: * connector-net-ref-mysqlclient-mysqlinfomessageeventargsconstructor:: `MySqlInfoMessageEventArgs' Constructor * connector-net-ref-mysqlclient-mysqlinfomessageeventargs-errors:: `MySqlInfoMessageEventArgs.errors' Field *Note MySqlInfoMessageEventArgs overview: connector-net-ref-mysqlclient-mysqlinfomessageeventargs. *Public Instance Constructors* Public instance constructors in the MySqlInfoMessageEventArgs class. *Note MySqlInfoMessageEventArgs Initializes a new instance of the Constructor: *Note MySqlInfoMessageEventArgs: connector-net-ref-mysqlclient-mysqlinfomessageeventargsconstructor.connector-net-ref-mysqlclient-mysqlinfomessageeventargs. class. *Public Instance Fields* Public instance fields in the MySqlInfoMessageEventArgs class. *Note errors: connector-net-ref-mysqlclient-mysqlinfomessageeventargs-errors. *Public Instance Methods* Public instance methods in the MySqlInfoMessageEventArgs class. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetType (inherited from Object) Gets the Type of the current instance. ToString (inherited from Object) Returns a String that represents the current Object. *Protected Instance Methods* Protected instance methods in the MySqlInfoMessageEventArgs class. Finalize (inherited from Object) Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. MemberwiseClone (inherited from Creates a shallow copy of the Object) current Object. *See Also* *Note MySqlInfoMessageEventArgs Class: connector-net-ref-mysqlclient-mysqlinfomessageeventargs, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlinfomessageeventargsconstructor, Next: connector-net-ref-mysqlclient-mysqlinfomessageeventargs-errors, Prev: connector-net-ref-mysqlclient-mysqlinfomessageeventargsmembers, Up: connector-net-ref-mysqlclient-mysqlinfomessageeventargsmembers 21.2.9.42 `MySqlInfoMessageEventArgs' Constructor ................................................. Initializes a new instance of the *Note MySqlInfoMessageEventArgs: connector-net-ref-mysqlclient-mysqlinfomessageeventargs. class. *Syntax: Visual Basic* Public Sub New() *Syntax: C#* public MySqlInfoMessageEventArgs(); *See Also* *Note MySqlInfoMessageEventArgs Class: connector-net-ref-mysqlclient-mysqlinfomessageeventargs, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlinfomessageeventargs-errors, Prev: connector-net-ref-mysqlclient-mysqlinfomessageeventargsconstructor, Up: connector-net-ref-mysqlclient-mysqlinfomessageeventargsmembers 21.2.9.43 `MySqlInfoMessageEventArgs.errors' Field .................................................. * Menu: * connector-net-ref-mysqlclient-mysqlerror:: `MySqlError' Class *Syntax: Visual Basic* Public errors As MySqlError() *Syntax: C#* public MySqlError[] errors; *See Also* *Note MySqlInfoMessageEventArgs Class: connector-net-ref-mysqlclient-mysqlinfomessageeventargs, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlerror, Prev: connector-net-ref-mysqlclient-mysqlinfomessageeventargs-errors, Up: connector-net-ref-mysqlclient-mysqlinfomessageeventargs-errors 21.2.9.44 `MySqlError' Class ............................ * Menu: * connector-net-ref-mysqlclient-mysqlerrormembers:: `MySqlError' Members Collection of error codes that can be returned by the server For a list of all members of this type, see *Note MySqlError Members: connector-net-ref-mysqlclient-mysqlerrormembers . *Syntax: Visual Basic* Public Class MySqlError *Syntax: C#* public class MySqlError *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlError Members: connector-net-ref-mysqlclient-mysqlerrormembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlerrormembers, Prev: connector-net-ref-mysqlclient-mysqlerror, Up: connector-net-ref-mysqlclient-mysqlerror 21.2.9.45 `MySqlError' Members .............................. * Menu: * connector-net-ref-mysqlclient-mysqlerrorconstructor:: `MySqlError' Constructor * connector-net-ref-mysqlclient-mysqlerror-code:: Code Property * connector-net-ref-mysqlclient-mysqlerror-level:: Level Property * connector-net-ref-mysqlclient-mysqlerror-message:: Message Property *Note MySqlError overview: connector-net-ref-mysqlclient-mysqlerror. *Public Instance Constructors* Public instance constructors in the MySqlError class. *Note MySqlError Constructor: connector-net-ref-mysqlclient-mysqlerrorconstructor. *Public Instance Properties* Public instance properties in the MySqlError class. *Note Code: Error code connector-net-ref-mysqlclient-mysqlerror-code. *Note Level: Error level connector-net-ref-mysqlclient-mysqlerror-level. *Note Message: Error message connector-net-ref-mysqlclient-mysqlerror-message. *Public Instance Methods* Public instance methods in the MySqlError class. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetType (inherited from Object) Gets the Type of the current instance. ToString (inherited from Object) Returns a String that represents the current Object. *Protected Instance Methods* Protected instance methods in the MySqlError class. Finalize (inherited from Object) Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. MemberwiseClone (inherited from Creates a shallow copy of the Object) current Object. *See Also* *Note MySqlError Class: connector-net-ref-mysqlclient-mysqlerror, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlerrorconstructor, Next: connector-net-ref-mysqlclient-mysqlerror-code, Prev: connector-net-ref-mysqlclient-mysqlerrormembers, Up: connector-net-ref-mysqlclient-mysqlerrormembers 21.2.9.46 `MySqlError' Constructor .................................. *Syntax: Visual Basic* Public Sub New( _ ByVal level As String, _ ByVal code As Integer, _ ByVal message As String _ ) *Syntax: C#* public MySqlError( stringlevel, intcode, stringmessage ); *Parameters* * `level': * `code': * `message': *See Also* *Note MySqlError Class: connector-net-ref-mysqlclient-mysqlerror, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlerror-code, Next: connector-net-ref-mysqlclient-mysqlerror-level, Prev: connector-net-ref-mysqlclient-mysqlerrorconstructor, Up: connector-net-ref-mysqlclient-mysqlerrormembers 21.2.9.47 Code Property ....................... Error code *Syntax: Visual Basic* Public ReadOnly Property Code As Integer *Syntax: C#* public int Code {get;} *See Also* *Note MySqlError Class: connector-net-ref-mysqlclient-mysqlerror, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlerror-level, Next: connector-net-ref-mysqlclient-mysqlerror-message, Prev: connector-net-ref-mysqlclient-mysqlerror-code, Up: connector-net-ref-mysqlclient-mysqlerrormembers 21.2.9.48 Level Property ........................ Error level *Syntax: Visual Basic* Public ReadOnly Property Level As String *Syntax: C#* public string Level {get;} *See Also* *Note MySqlError Class: connector-net-ref-mysqlclient-mysqlerror, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlerror-message, Prev: connector-net-ref-mysqlclient-mysqlerror-level, Up: connector-net-ref-mysqlclient-mysqlerrormembers 21.2.9.49 Message Property .......................... Error message *Syntax: Visual Basic* Public ReadOnly Property Message As String *Syntax: C#* public string Message {get;} *See Also* *Note MySqlError Class: connector-net-ref-mysqlclient-mysqlerror, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlconnection-statechange, Prev: connector-net-ref-mysqlclient-mysqlconnection-infomessage, Up: connector-net-ref-mysqlclient-mysqlconnectionmembers 21.2.9.50 `MySqlConnection.StateChange' Event ............................................. *Syntax: Visual Basic* Public Event StateChange As StateChangeEventHandler *Syntax: C#* public event StateChangeEventHandler StateChange; *See Also* *Note MySqlConnection Class: connector-net-ref-mysqlclient-mysqlconnection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandconstructor4, Prev: connector-net-ref-mysqlclient-mysqlcommandconstructor3, Up: connector-net-ref-mysqlclient-mysqlcommandconstructor 21.2.9.51 `MySqlCommand' Constructor .................................... *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal cmdText As String, _ ByVal connection As MySqlConnection, _ ByVal transaction As MySqlTransaction _ ) *Syntax: C#* public MySqlCommand( stringcmdText, MySqlConnectionconnection, MySqlTransactiontransaction ); *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommand Constructor Overload List: connector-net-ref-mysqlclient-mysqlcommandconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-commandtext, Next: connector-net-ref-mysqlclient-mysqlcommand-commandtimeout, Prev: connector-net-ref-mysqlclient-mysqlcommandconstructor, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.52 CommandText Property .............................. *Syntax: Visual Basic* NotOverridable Public Property CommandText As String _ _ Implements IDbCommand.CommandText *Syntax: C#* public string CommandText {get; set;} *Implements* IDbCommand.CommandText *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-commandtimeout, Next: connector-net-ref-mysqlclient-mysqlcommand-commandtype, Prev: connector-net-ref-mysqlclient-mysqlcommand-commandtext, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.53 CommandTimeout Property ................................. *Syntax: Visual Basic* NotOverridable Public Property CommandTimeout As Integer _ _ Implements IDbCommand.CommandTimeout *Syntax: C#* public int CommandTimeout {get; set;} *Implements* IDbCommand.CommandTimeout *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-commandtype, Next: connector-net-ref-mysqlclient-mysqlcommand-connection, Prev: connector-net-ref-mysqlclient-mysqlcommand-commandtimeout, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.54 CommandType Property .............................. *Syntax: Visual Basic* NotOverridable Public Property CommandType As CommandType _ _ Implements IDbCommand.CommandType *Syntax: C#* public System.Data.CommandType CommandType {get; set;} *Implements* IDbCommand.CommandType *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-connection, Next: connector-net-ref-mysqlclient-mysqlcommand-isprepared, Prev: connector-net-ref-mysqlclient-mysqlcommand-commandtype, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.55 Connection Property ............................. *Syntax: Visual Basic* Public Property Connection As MySqlConnection *Syntax: C#* public MySqlConnection Connection {get; set;} *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-isprepared, Next: connector-net-ref-mysqlclient-mysqlcommand-parameters, Prev: connector-net-ref-mysqlclient-mysqlcommand-connection, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.56 IsPrepared Property ............................. *Syntax: Visual Basic* Public ReadOnly Property IsPrepared As Boolean *Syntax: C#* public bool IsPrepared {get;} *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-parameters, Next: connector-net-ref-mysqlclient-mysqlcommand-transaction, Prev: connector-net-ref-mysqlclient-mysqlcommand-isprepared, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.57 Parameters Property ............................. * Menu: * connector-net-ref-mysqlclient-mysqlparametercollection:: `MySqlParameterCollection' Class *Syntax: Visual Basic* Public ReadOnly Property Parameters As MySqlParameterCollection *Syntax: C#* public MySqlParameterCollection Parameters {get;} *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection, Prev: connector-net-ref-mysqlclient-mysqlcommand-parameters, Up: connector-net-ref-mysqlclient-mysqlcommand-parameters 21.2.9.58 `MySqlParameterCollection' Class .......................................... * Menu: * connector-net-ref-mysqlclient-mysqlparametercollectionmembers:: `MySqlParameterCollection' Members Represents a collection of parameters relevant to a *Note MySqlCommand: connector-net-ref-mysqlclient-mysqlcommand. as well as their respective mappings to columns in a DataSet. This class cannot be inherited. For a list of all members of this type, see *Note MySqlParameterCollection Members: connector-net-ref-mysqlclient-mysqlparametercollectionmembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlParameterCollection_ Inherits MarshalByRefObject_ Implements IDataParameterCollection, IList, ICollection, IEnumerable *Syntax: C#* public sealed class MySqlParameterCollection : MarshalByRefObject, IDataParameterCollection, IList, ICollection, IEnumerable *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlParameterCollection Members: connector-net-ref-mysqlclient-mysqlparametercollectionmembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollectionmembers, Prev: connector-net-ref-mysqlclient-mysqlparametercollection, Up: connector-net-ref-mysqlclient-mysqlparametercollection 21.2.9.59 `MySqlParameterCollection' Members ............................................ * Menu: * connector-net-ref-mysqlclient-mysqlparametercollectionconstructor:: `MySqlParameterCollection' Constructor * connector-net-ref-mysqlclient-mysqlparametercollection-count:: Count Property * connector-net-ref-mysqlclient-mysqlparametercollectionitem:: Item Property * connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads:: Add Method * connector-net-ref-mysqlclient-mysqlparametercollection-clear:: `MySqlParameterCollection.Clear' Method * connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads:: Contains Method * connector-net-ref-mysqlclient-mysqlparametercollection-copyto:: `MySqlParameterCollection.CopyTo' Method * connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads:: IndexOf Method * connector-net-ref-mysqlclient-mysqlparametercollection-insert:: `MySqlParameterCollection.Insert' Method * connector-net-ref-mysqlclient-mysqlparametercollection-remove:: `MySqlParameterCollection.Remove' Method * connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overloads:: RemoveAt Method *Note MySqlParameterCollection overview: connector-net-ref-mysqlclient-mysqlparametercollection. *Public Instance Constructors* Public instance constructors in the MySqlParameterCollection class. *Note MySqlParameterCollection Initializes a new instance of the Constructor: *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollectionconstructor.connector-net-ref-mysqlclient-mysqlparametercollection. class. *Public Instance Properties* Public instance properties in the MySqlParameterCollection class. *Note Count: Gets the number of MySqlParameter connector-net-ref-mysqlclient-mysqlparametercollection-count.objects in the collection. *Note Item: Overloaded. Gets the *Note connector-net-ref-mysqlclient-mysqlparametercollectionitem.MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. with a specified attribute. In C#, this property is the indexer for the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. class. *Public Instance Methods* Public instance methods in the MySqlParameterCollection class. *Note Add: Overloaded. Adds the specified connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads.*Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. *Note Clear: Removes all items from the connector-net-ref-mysqlclient-mysqlparametercollection-clear.collection. *Note Contains: Overloaded. Gets a value indicating connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads.whether a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. exists in the collection. *Note CopyTo: Copies MySqlParameter objects from connector-net-ref-mysqlclient-mysqlparametercollection-copyto.the MySqlParameterCollection to the specified array. CreateObjRef (inherited from Creates an object that contains all MarshalByRefObject) the relevant information required to generate a proxy used to communicate with a remote object. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetLifetimeService (inherited from Retrieves the current lifetime MarshalByRefObject) service object that controls the lifetime policy for this instance. GetType (inherited from Object) Gets the Type of the current instance. *Note IndexOf: Overloaded. Gets the location of a connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads.*Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. in the collection. InitializeLifetimeService Obtains a lifetime service object (inherited from MarshalByRefObject) to control the lifetime policy for this instance. *Note Insert: Inserts a MySqlParameter into the connector-net-ref-mysqlclient-mysqlparametercollection-insert.collection at the specified index. *Note Remove: Removes the specified connector-net-ref-mysqlclient-mysqlparametercollection-remove.MySqlParameter from the collection. *Note RemoveAt: Overloaded. Removes the specified connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overloads.*Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. from the collection. ToString (inherited from Object) Returns a String that represents the current Object. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollectionconstructor, Next: connector-net-ref-mysqlclient-mysqlparametercollection-count, Prev: connector-net-ref-mysqlclient-mysqlparametercollectionmembers, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.60 `MySqlParameterCollection' Constructor ................................................ Initializes a new instance of the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. class. *Syntax: Visual Basic* Public Sub New() *Syntax: C#* public MySqlParameterCollection(); *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-count, Next: connector-net-ref-mysqlclient-mysqlparametercollectionitem, Prev: connector-net-ref-mysqlclient-mysqlparametercollectionconstructor, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.61 Count Property ........................ Gets the number of MySqlParameter objects in the collection. *Syntax: Visual Basic* NotOverridable Public ReadOnly Property Count As Integer _ _ Implements ICollection.Count *Syntax: C#* public int Count {get;} *Implements* ICollection.Count *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollectionitem, Next: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-count, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.62 Item Property ....................... * Menu: * connector-net-ref-mysqlclient-mysqlparameter:: `MySqlParameter' Class * connector-net-ref-mysqlclient-mysqlparametercollection-item1:: Item Property (Int32) * connector-net-ref-mysqlclient-mysqlparametercollection-item2:: Item Property (String) Gets the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. with a specified attribute. In C#, this property is the indexer for the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. class. *Overload List* Gets the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. at the specified index. * *Note public MySqlParameter this[int] {get; set;}: connector-net-ref-mysqlclient-mysqlparametercollection-item1. Gets the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. with the specified name. * *Note public MySqlParameter this[string] {get; set;}: connector-net-ref-mysqlclient-mysqlparametercollection-item2. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter, Next: connector-net-ref-mysqlclient-mysqlparametercollection-item1, Prev: connector-net-ref-mysqlclient-mysqlparametercollectionitem, Up: connector-net-ref-mysqlclient-mysqlparametercollectionitem 21.2.9.63 `MySqlParameter' Class ................................ * Menu: * connector-net-ref-mysqlclient-mysqlparametermembers:: `MySqlParameter' Members Represents a parameter to a *Note MySqlCommand: connector-net-ref-mysqlclient-mysqlcommand, and optionally, its mapping to DataSetcolumns. This class cannot be inherited. For a list of all members of this type, see *Note MySqlParameter Members: connector-net-ref-mysqlclient-mysqlparametermembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlParameter_ Inherits MarshalByRefObject_ Implements IDataParameter, IDbDataParameter, ICloneable *Syntax: C#* public sealed class MySqlParameter : MarshalByRefObject, IDataParameter, IDbDataParameter, ICloneable *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlParameter Members: connector-net-ref-mysqlclient-mysqlparametermembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametermembers, Prev: connector-net-ref-mysqlclient-mysqlparameter, Up: connector-net-ref-mysqlclient-mysqlparameter 21.2.9.64 `MySqlParameter' Members .................................. * Menu: * connector-net-ref-mysqlclient-mysqlparameterconstructor:: `MySqlParameter' Constructor * connector-net-ref-mysqlclient-mysqlparameter-dbtype:: DbType Property * connector-net-ref-mysqlclient-mysqlparameter-direction:: Direction Property * connector-net-ref-mysqlclient-mysqlparameter-isnullable:: IsNullable Property * connector-net-ref-mysqlclient-mysqlparameter-isunsigned:: IsUnsigned Property * connector-net-ref-mysqlclient-mysqlparameter-mysqldbtype:: `MySqlDbType' Property * connector-net-ref-mysqlclient-mysqlparameter-parametername:: ParameterName Property * connector-net-ref-mysqlclient-mysqlparameter-precision:: Precision Property * connector-net-ref-mysqlclient-mysqlparameter-scale:: Scale Property * connector-net-ref-mysqlclient-mysqlparameter-size:: Size Property * connector-net-ref-mysqlclient-mysqlparameter-sourcecolumn:: SourceColumn Property * connector-net-ref-mysqlclient-mysqlparameter-sourceversion:: SourceVersion Property * connector-net-ref-mysqlclient-mysqlparameter-tostring:: `MySqlParameter.ToString' Method *Note MySqlParameter overview: connector-net-ref-mysqlclient-mysqlparameter. *Public Instance Constructors* Public instance constructors in the MySqlParameter class. *Note MySqlParameter: Overloaded. Initializes a new connector-net-ref-mysqlclient-mysqlparameterconstructor.instance of the MySqlParameter class. *Public Instance Properties* Public instance properties in the MySqlParameter class. *Note DbType: Gets or sets the DbType of the connector-net-ref-mysqlclient-mysqlparameter-dbtype.parameter. *Note Direction: Gets or sets a value indicating connector-net-ref-mysqlclient-mysqlparameter-direction.whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter. As of MySQL version 4.1 and earlier, input-only is the only valid choice. *Note IsNullable: Gets or sets a value indicating connector-net-ref-mysqlclient-mysqlparameter-isnullable.whether the parameter accepts null values. *Note IsUnsigned: connector-net-ref-mysqlclient-mysqlparameter-isunsigned. *Note MySqlDbType: Gets or sets the MySqlDbType of the connector-net-ref-mysqlclient-mysqlparameter-mysqldbtype.parameter. *Note ParameterName: Gets or sets the name of the connector-net-ref-mysqlclient-mysqlparameter-parametername.MySqlParameter. *Note Precision: Gets or sets the maximum number of connector-net-ref-mysqlclient-mysqlparameter-precision.digits used to represent the *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. property. *Note Scale: Gets or sets the number of decimal connector-net-ref-mysqlclient-mysqlparameter-scale.places to which *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. is resolved. *Note Size: Gets or sets the maximum size, in connector-net-ref-mysqlclient-mysqlparameter-size.bytes, of the data within the column. *Note SourceColumn: Gets or sets the name of the source connector-net-ref-mysqlclient-mysqlparameter-sourcecolumn.column that is mapped to the DataSetand used for loading or returning the *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. *Note SourceVersion: Gets or sets the DataRowVersion to connector-net-ref-mysqlclient-mysqlparameter-sourceversion.use when loading *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. *Note Value: Gets or sets the value of the connector-net-ref-mysqlclient-mysqlparameter-value.parameter. *Public Instance Methods* Public instance methods in the MySqlParameter class. CreateObjRef (inherited from Creates an object that contains all MarshalByRefObject) the relevant information required to generate a proxy used to communicate with a remote object. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetLifetimeService (inherited from Retrieves the current lifetime MarshalByRefObject) service object that controls the lifetime policy for this instance. GetType (inherited from Object) Gets the Type of the current instance. InitializeLifetimeService Obtains a lifetime service object (inherited from MarshalByRefObject) to control the lifetime policy for this instance. *Note ToString: Overridden. Gets a string connector-net-ref-mysqlclient-mysqlparameter-tostring.containing the *Note ParameterName: connector-net-ref-mysqlclient-mysqlparameter-parametername. *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameterconstructor, Next: connector-net-ref-mysqlclient-mysqlparameter-dbtype, Prev: connector-net-ref-mysqlclient-mysqlparametermembers, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.65 `MySqlParameter' Constructor ...................................... * Menu: * connector-net-ref-mysqlclient-mysqlparameterconstructor1:: `MySqlParameter' Constructor () * connector-net-ref-mysqlclient-mysqlparameterconstructor3:: `MySqlParameter' Constructor * connector-net-ref-mysqlclient-mysqlparameterconstructor4:: `MySqlParameter' Constructor (String, MySqlDbType, Int32) * connector-net-ref-mysqlclient-mysqlparameterconstructor6:: `MySqlParameter' Constructor * connector-net-ref-mysqlclient-mysqlparameterconstructor5:: `MySqlParameter' Constructor * connector-net-ref-mysqlclient-mysqlparameterconstructor2:: `MySqlParameter' Constructor Initializes a new instance of the MySqlParameter class. *Overload List* Initializes a new instance of the MySqlParameter class. * *Note public MySqlParameter();: connector-net-ref-mysqlclient-mysqlparameterconstructor1. Initializes a new instance of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. class with the parameter name and the data type. * *Note public MySqlParameter(string: (MySqlDbType);)connector-net-ref-mysqlclient-mysqlparameterconstructor3. Initializes a new instance of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. class with the parameter name, the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype, and the size. * *Note public MySqlParameter(string: (MySqlDbType)connector-net-ref-mysqlclient-mysqlparameterconstructor4. Initializes a new instance of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. class with the parameter name, the type of the parameter, the size of the parameter, a ParameterDirection, the precision of the parameter, the scale of the parameter, the source column, a DataRowVersion to use, and the value of the parameter. * *Note public MySqlParameter(string: (MySqlDbType)connector-net-ref-mysqlclient-mysqlparameterconstructor6.ParameterDirection,bool,byte,byte,string,DataRowVersion,object); Initializes a new instance of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. class with the parameter name, the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype, the size, and the source column name. * *Note public MySqlParameter(string: (MySqlDbType)connector-net-ref-mysqlclient-mysqlparameterconstructor5.string); Initializes a new instance of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. class with the parameter name and a value of the new MySqlParameter. * *Note public MySqlParameter(string: (object);)connector-net-ref-mysqlclient-mysqlparameterconstructor2. *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameterconstructor1, Next: connector-net-ref-mysqlclient-mysqlparameterconstructor3, Prev: connector-net-ref-mysqlclient-mysqlparameterconstructor, Up: connector-net-ref-mysqlclient-mysqlparameterconstructor 21.2.9.66 `MySqlParameter' Constructor () ......................................... Initializes a new instance of the MySqlParameter class. *Syntax: Visual Basic* Overloads Public Sub New() *Syntax: C#* public MySqlParameter(); *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameter Constructor Overload List: connector-net-ref-mysqlclient-mysqlparameterconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameterconstructor3, Next: connector-net-ref-mysqlclient-mysqlparameterconstructor4, Prev: connector-net-ref-mysqlclient-mysqlparameterconstructor1, Up: connector-net-ref-mysqlclient-mysqlparameterconstructor 21.2.9.67 `MySqlParameter' Constructor ...................................... * Menu: * connector-net-ref-mysqlclient-mysqldbtype:: `MySqlDbType' Enumeration Initializes a new instance of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. class with the parameter name and the data type. *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType _ ) *Syntax: C#* public MySqlParameter( stringparameterName, MySqlDbTypedbType ); *Parameters* * `parameterName': The name of the parameter to map. * `dbType': One of the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype. values. *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameter Constructor Overload List: connector-net-ref-mysqlclient-mysqlparameterconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldbtype, Prev: connector-net-ref-mysqlclient-mysqlparameterconstructor3, Up: connector-net-ref-mysqlclient-mysqlparameterconstructor3 21.2.9.68 `MySqlDbType' Enumeration ................................... Specifies MySQL-specific data type of a field, property, for use in a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. *Syntax: Visual Basic* Public Enum MySqlDbType *Syntax: C#* public enum MySqlDbType *Members* Members in the MySqlDbType enumeration. *Member Name* *Description* Newdate Obsolete. Use Datetime or Date type. Timestamp A timestamp. The range is '1970-01-01 00:00:01.000000' to '2038-01-19 03:14:07.999999'. (Fractional seconds can only be stored with a MySQL 5.6.4 or higher database server.) Time The range is '-838:59:59.000000' to '838:59:59.000000'. (Fractional seconds can only be stored with a MySQL 5.6.4 or higher database server.) Date The supported range is '1000-01-01' to '9999-12-31'. Datetime The supported range is '1000-01-01 00:00:00.000000' to '9999-12-31 23:59:59.999999'. (Fractional seconds can only be stored with a MySQL 5.6.4 or higher database server.) Year A year in 2- or 4-digit format (default is 4-digit). The allowable values are 1901 to 2155, 0000 in the 4-digit year format, and 1970-2069 if you use the 2-digit format (70-69). TinyBlob A BLOB column with a maximum length of 255 (2^8 - 1) characters. Blob A BLOB column with a maximum length of 65535 (2^16 - 1) characters. MediumBlob A BLOB column with a maximum length of 16777215 (2^24 - 1) characters. LongBlob A BLOB column with a maximum length of 4294967295 or 4G (2^32 - 1) characters. Int16 A 16-bit signed integer. The signed range is -32768 to 32767. The unsigned range is 0 to 65535. Int24 Specifies a 24 (3 byte) signed or unsigned value. Int32 A 32-bit signed integer. Int64 A 64-bit signed integer. Byte The signed range is -128 to 127. The unsigned range is 0 to 255. Float A small (single-precision) floating-point number. Allowable values are -3.402823466E+38 to -1.175494351E-38, 0, and 1.175494351E-38 to 3.402823466E+38. Double A normal-size (double-precision) floating-point number. Allowable values are -1.7976931348623157E+308 to -2.2250738585072014E-308, 0, and 2.2250738585072014E-308 to 1.7976931348623157E+308. UByte An 8-bit unsigned value. UInt16 A 16-bit unsigned value. UInt24 A 24-bit unsigned value. UInt32 A 32-bit unsigned value. UInt64 A 64-bit unsigned value. Decimal A fixed precision and scale numeric value between -10^38-1 and 10^38-1. NewDecimal New Decimal Set 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', ... A SET can have a maximum of 64 members. String Obsolete. Use VarChar type. VarChar A variable-length string containing 0 to 255 characters. VarString A variable-length string containing 0 to 65535 characters. Enum 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. An ENUM can have a maximum of 65535 distinct values. Geometry Bit Bit-field data type. TinyText A nonbinary string column supporting a maximum length of 255 (2^8 - 1) characters. Text A nonbinary string column supporting a maximum length of 65535 (2^16 - 1) characters. MediumText A nonbinary string column supporting a maximum length of 16777215 (2^24 - 1) characters. LongText A nonbinary string column supporting a maximum length of 4294967295 (2^32 - 1) characters. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameterconstructor4, Next: connector-net-ref-mysqlclient-mysqlparameterconstructor6, Prev: connector-net-ref-mysqlclient-mysqlparameterconstructor3, Up: connector-net-ref-mysqlclient-mysqlparameterconstructor 21.2.9.69 `MySqlParameter' Constructor (String, MySqlDbType, Int32) ................................................................... Initializes a new instance of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. class with the parameter name, the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype, and the size. *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType, _ ByVal size As Integer _ ) *Syntax: C#* public MySqlParameter( stringparameterName, MySqlDbTypedbType, intsize ); *Parameters* * `parameterName': The name of the parameter to map. * `dbType': One of the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype. values. * `size': The length of the parameter. *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameter Constructor Overload List: connector-net-ref-mysqlclient-mysqlparameterconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameterconstructor6, Next: connector-net-ref-mysqlclient-mysqlparameterconstructor5, Prev: connector-net-ref-mysqlclient-mysqlparameterconstructor4, Up: connector-net-ref-mysqlclient-mysqlparameterconstructor 21.2.9.70 `MySqlParameter' Constructor ...................................... * Menu: * connector-net-ref-mysqlclient-mysqlparameter-value:: Value Property Initializes a new instance of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. class with the parameter name, the type of the parameter, the size of the parameter, a ParameterDirection, the precision of the parameter, the scale of the parameter, the source column, a DataRowVersion to use, and the value of the parameter. *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType, _ ByVal size As Integer, _ ByVal direction As ParameterDirection, _ ByVal isNullable As Boolean, _ ByVal precision As Byte, _ ByVal scale As Byte, _ ByVal sourceColumn As String, _ ByVal sourceVersion As DataRowVersion, _ ByVal value As Object _ ) *Syntax: C#* public MySqlParameter( stringparameterName, MySqlDbTypedbType, intsize, ParameterDirectiondirection, boolisNullable, byteprecision, bytescale, stringsourceColumn, DataRowVersionsourceVersion, objectvalue ); *Parameters* * `parameterName': The name of the parameter to map. * `dbType': One of the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype. values. * `size': The length of the parameter. * `direction': One of the ParameterDirectionvalues. * `isNullable': true if the value of the field can be null, otherwise false. * `precision': The total number of digits to the left and right of the decimal point to which *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. is resolved. * `scale': The total number of decimal places to which *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. is resolved. * `sourceColumn': The name of the source column. * `sourceVersion': One of the DataRowVersionvalues. * `value': An Object that is the value of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. *Exceptions* Exceptions in the MySqlParameter constructor. *Exception Type* *Condition* ArgumentException *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameter Constructor Overload List: connector-net-ref-mysqlclient-mysqlparameterconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-value, Prev: connector-net-ref-mysqlclient-mysqlparameterconstructor6, Up: connector-net-ref-mysqlclient-mysqlparameterconstructor6 21.2.9.71 Value Property ........................ Gets or sets the value of the parameter. *Syntax: Visual Basic* NotOverridable Public Property Value As Object _ _ Implements IDataParameter.Value *Syntax: C#* public object Value {get; set;} *Implements* IDataParameter.Value *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameterconstructor5, Next: connector-net-ref-mysqlclient-mysqlparameterconstructor2, Prev: connector-net-ref-mysqlclient-mysqlparameterconstructor6, Up: connector-net-ref-mysqlclient-mysqlparameterconstructor 21.2.9.72 `MySqlParameter' Constructor ...................................... Initializes a new instance of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. class with the parameter name, the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype, the size, and the source column name. *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType, _ ByVal size As Integer, _ ByVal sourceColumn As String _ ) *Syntax: C#* public MySqlParameter( stringparameterName, MySqlDbTypedbType, intsize, stringsourceColumn ); *Parameters* * `parameterName': The name of the parameter to map. * `dbType': One of the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype. values. * `size': The length of the parameter. * `sourceColumn': The name of the source column. *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameter Constructor Overload List: connector-net-ref-mysqlclient-mysqlparameterconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameterconstructor2, Prev: connector-net-ref-mysqlclient-mysqlparameterconstructor5, Up: connector-net-ref-mysqlclient-mysqlparameterconstructor 21.2.9.73 `MySqlParameter' Constructor ...................................... Initializes a new instance of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. class with the parameter name and a value of the new MySqlParameter. *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal parameterName As String, _ ByVal value As Object _ ) *Syntax: C#* public MySqlParameter( stringparameterName, objectvalue ); *Parameters* * `parameterName': The name of the parameter to map. * `value': An Object that is the value of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameter Constructor Overload List: connector-net-ref-mysqlclient-mysqlparameterconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-dbtype, Next: connector-net-ref-mysqlclient-mysqlparameter-direction, Prev: connector-net-ref-mysqlclient-mysqlparameterconstructor, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.74 DbType Property ......................... Gets or sets the DbType of the parameter. *Syntax: Visual Basic* NotOverridable Public Property DbType As DbType _ _ Implements IDataParameter.DbType *Syntax: C#* public System.Data.DbType DbType {get; set;} *Implements* IDataParameter.DbType *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-direction, Next: connector-net-ref-mysqlclient-mysqlparameter-isnullable, Prev: connector-net-ref-mysqlclient-mysqlparameter-dbtype, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.75 Direction Property ............................ Gets or sets a value indicating whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter. As of MySQL version 4.1 and earlier, input-only is the only valid choice. *Syntax: Visual Basic* NotOverridable Public Property Direction As ParameterDirection _ _ Implements IDataParameter.Direction *Syntax: C#* public System.Data.ParameterDirection Direction {get; set;} *Implements* IDataParameter.Direction *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-isnullable, Next: connector-net-ref-mysqlclient-mysqlparameter-isunsigned, Prev: connector-net-ref-mysqlclient-mysqlparameter-direction, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.76 IsNullable Property ............................. Gets or sets a value indicating whether the parameter accepts null values. *Syntax: Visual Basic* NotOverridable Public Property IsNullable As Boolean _ _ Implements IDataParameter.IsNullable *Syntax: C#* public bool IsNullable {get; set;} *Implements* IDataParameter.IsNullable *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-isunsigned, Next: connector-net-ref-mysqlclient-mysqlparameter-mysqldbtype, Prev: connector-net-ref-mysqlclient-mysqlparameter-isnullable, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.77 IsUnsigned Property ............................. *Syntax: Visual Basic* Public Property IsUnsigned As Boolean *Syntax: C#* public bool IsUnsigned {get; set;} *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-mysqldbtype, Next: connector-net-ref-mysqlclient-mysqlparameter-parametername, Prev: connector-net-ref-mysqlclient-mysqlparameter-isunsigned, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.78 `MySqlDbType' Property ................................ Gets or sets the MySqlDbType of the parameter. *Syntax: Visual Basic* Public Property MySqlDbType As MySqlDbType *Syntax: C#* public MySqlDbType MySqlDbType {get; set;} *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-parametername, Next: connector-net-ref-mysqlclient-mysqlparameter-precision, Prev: connector-net-ref-mysqlclient-mysqlparameter-mysqldbtype, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.79 ParameterName Property ................................ Gets or sets the name of the MySqlParameter. *Syntax: Visual Basic* NotOverridable Public Property ParameterName As String _ _ Implements IDataParameter.ParameterName *Syntax: C#* public string ParameterName {get; set;} *Implements* IDataParameter.ParameterName *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-precision, Next: connector-net-ref-mysqlclient-mysqlparameter-scale, Prev: connector-net-ref-mysqlclient-mysqlparameter-parametername, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.80 Precision Property ............................ Gets or sets the maximum number of digits used to represent the *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. property. *Syntax: Visual Basic* NotOverridable Public Property Precision As Byte _ _ Implements IDbDataParameter.Precision *Syntax: C#* public byte Precision {get; set;} *Implements* IDbDataParameter.Precision *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-scale, Next: connector-net-ref-mysqlclient-mysqlparameter-size, Prev: connector-net-ref-mysqlclient-mysqlparameter-precision, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.81 Scale Property ........................ Gets or sets the number of decimal places to which *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. is resolved. *Syntax: Visual Basic* NotOverridable Public Property Scale As Byte _ _ Implements IDbDataParameter.Scale *Syntax: C#* public byte Scale {get; set;} *Implements* IDbDataParameter.Scale *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-size, Next: connector-net-ref-mysqlclient-mysqlparameter-sourcecolumn, Prev: connector-net-ref-mysqlclient-mysqlparameter-scale, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.82 Size Property ....................... Gets or sets the maximum size, in bytes, of the data within the column. *Syntax: Visual Basic* NotOverridable Public Property Size As Integer _ _ Implements IDbDataParameter.Size *Syntax: C#* public int Size {get; set;} *Implements* IDbDataParameter.Size *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-sourcecolumn, Next: connector-net-ref-mysqlclient-mysqlparameter-sourceversion, Prev: connector-net-ref-mysqlclient-mysqlparameter-size, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.83 SourceColumn Property ............................... Gets or sets the name of the source column that is mapped to the DataSetand used for loading or returning the *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. *Syntax: Visual Basic* NotOverridable Public Property SourceColumn As String _ _ Implements IDataParameter.SourceColumn *Syntax: C#* public string SourceColumn {get; set;} *Implements* IDataParameter.SourceColumn *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-sourceversion, Next: connector-net-ref-mysqlclient-mysqlparameter-tostring, Prev: connector-net-ref-mysqlclient-mysqlparameter-sourcecolumn, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.84 SourceVersion Property ................................ Gets or sets the DataRowVersion to use when loading *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. *Syntax: Visual Basic* NotOverridable Public Property SourceVersion As DataRowVersion _ _ Implements IDataParameter.SourceVersion *Syntax: C#* public System.Data.DataRowVersion SourceVersion {get; set;} *Implements* IDataParameter.SourceVersion *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparameter-tostring, Prev: connector-net-ref-mysqlclient-mysqlparameter-sourceversion, Up: connector-net-ref-mysqlclient-mysqlparametermembers 21.2.9.85 `MySqlParameter.ToString' Method .......................................... Overridden. Gets a string containing the *Note ParameterName: connector-net-ref-mysqlclient-mysqlparameter-parametername. *Syntax: Visual Basic* Overrides Public Function ToString() As String *Syntax: C#* public override string ToString(); *Return Value* *See Also* *Note MySqlParameter Class: connector-net-ref-mysqlclient-mysqlparameter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-item1, Next: connector-net-ref-mysqlclient-mysqlparametercollection-item2, Prev: connector-net-ref-mysqlclient-mysqlparameter, Up: connector-net-ref-mysqlclient-mysqlparametercollectionitem 21.2.9.86 Item Property (Int32) ............................... Gets the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. at the specified index. *Syntax: Visual Basic* Overloads Public Default Property Item( _ ByVal index As Integer _ ) As MySqlParameter *Syntax: C#* public MySqlParameter this[ intindex ] {get; set;} *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.Item Overload List: connector-net-ref-mysqlclient-mysqlparametercollectionitem.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-item2, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-item1, Up: connector-net-ref-mysqlclient-mysqlparametercollectionitem 21.2.9.87 Item Property (String) ................................ Gets the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. with the specified name. *Syntax: Visual Basic* Overloads Public Default Property Item( _ ByVal name As String _ ) As MySqlParameter *Syntax: C#* public MySqlParameter this[ stringname ] {get; set;} *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.Item Overload List: connector-net-ref-mysqlclient-mysqlparametercollectionitem.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads, Next: connector-net-ref-mysqlclient-mysqlparametercollection-clear, Prev: connector-net-ref-mysqlclient-mysqlparametercollectionitem, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.88 Add Method .................... * Menu: * connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-2:: `MySqlParameterCollection.Add' Method * connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-1:: `MySqlParameterCollection.Add' Method * connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-4:: `MySqlParameterCollection.Add' Method * connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-5:: `MySqlParameterCollection.Add' Method * connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-6:: `MySqlParameterCollection.Add' Method * connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-3:: `MySqlParameterCollection.Add' Method Adds the specified *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. *Overload List* Adds the specified *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. * *Note public MySqlParameter Add(MySqlParameter);: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-2. Adds the specified *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. * *Note public int Add(object);: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-1. Adds a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. given the parameter name and the data type. * *Note public MySqlParameter Add(string: (MySqlDbType);)connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-4. Adds a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. with the parameter name, the data type, and the column length. * *Note public MySqlParameter Add(string: (MySqlDbType)connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-5. Adds a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. with the parameter name, the data type, the column length, and the source column name. * *Note public MySqlParameter Add(string: (MySqlDbType)connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-6.string); Adds a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. given the specified parameter name and value. * *Note public MySqlParameter Add(string: (object);)connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-3. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-2, Next: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-1, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads, Up: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads 21.2.9.89 `MySqlParameterCollection.Add' Method ............................................... Adds the specified *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. *Syntax: Visual Basic* Overloads Public Function Add( _ ByVal value As MySqlParameter _ ) As MySqlParameter *Syntax: C#* public MySqlParameter Add( MySqlParametervalue ); *Parameters* * `value': The *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to add to the collection. *Return Value* The newly added *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.Add Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-1, Next: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-4, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-2, Up: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads 21.2.9.90 `MySqlParameterCollection.Add' Method ............................................... Adds the specified *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. *Syntax: Visual Basic* NotOverridable Overloads Public Function Add( _ ByVal value As Object _ ) As Integer _ _ Implements IList.Add *Syntax: C#* public int Add( objectvalue ); *Parameters* * `value': The *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to add to the collection. *Return Value* The index of the new *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object. *Implements* IList.Add *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.Add Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-4, Next: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-5, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-1, Up: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads 21.2.9.91 `MySqlParameterCollection.Add' Method ............................................... Adds a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. given the parameter name and the data type. *Syntax: Visual Basic* Overloads Public Function Add( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType _ ) As MySqlParameter *Syntax: C#* public MySqlParameter Add( stringparameterName, MySqlDbTypedbType ); *Parameters* * `parameterName': The name of the parameter. * `dbType': One of the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype. values. *Return Value* The newly added *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.Add Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-5, Next: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-6, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-4, Up: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads 21.2.9.92 `MySqlParameterCollection.Add' Method ............................................... Adds a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. with the parameter name, the data type, and the column length. *Syntax: Visual Basic* Overloads Public Function Add( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType, _ ByVal size As Integer _ ) As MySqlParameter *Syntax: C#* public MySqlParameter Add( stringparameterName, MySqlDbTypedbType, intsize ); *Parameters* * `parameterName': The name of the parameter. * `dbType': One of the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype. values. * `size': The length of the column. *Return Value* The newly added *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.Add Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-6, Next: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-3, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-5, Up: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads 21.2.9.93 `MySqlParameterCollection.Add' Method ............................................... Adds a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. with the parameter name, the data type, the column length, and the source column name. *Syntax: Visual Basic* Overloads Public Function Add( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType, _ ByVal size As Integer, _ ByVal sourceColumn As String _ ) As MySqlParameter *Syntax: C#* public MySqlParameter Add( stringparameterName, MySqlDbTypedbType, intsize, stringsourceColumn ); *Parameters* * `parameterName': The name of the parameter. * `dbType': One of the *Note MySqlDbType: connector-net-ref-mysqlclient-mysqldbtype. values. * `size': The length of the column. * `sourceColumn': The name of the source column. *Return Value* The newly added *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.Add Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-3, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-6, Up: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads 21.2.9.94 `MySqlParameterCollection.Add' Method ............................................... Adds a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to the *Note MySqlParameterCollection: connector-net-ref-mysqlclient-mysqlparametercollection. given the specified parameter name and value. *Syntax: Visual Basic* Overloads Public Function Add( _ ByVal parameterName As String, _ ByVal value As Object _ ) As MySqlParameter *Syntax: C#* public MySqlParameter Add( stringparameterName, objectvalue ); *Parameters* * `parameterName': The name of the parameter. * `value': The *Note Value: connector-net-ref-mysqlclient-mysqlparameter-value. of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. to add to the collection. *Return Value* The newly added *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.Add Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-clear, Next: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.95 `MySqlParameterCollection.Clear' Method ................................................. Removes all items from the collection. *Syntax: Visual Basic* NotOverridable Public Sub Clear() _ _ Implements IList.Clear *Syntax: C#* public void Clear(); *Implements* IList.Clear *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads, Next: connector-net-ref-mysqlclient-mysqlparametercollection-copyto, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-clear, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.96 Contains Method ......................... * Menu: * connector-net-ref-mysqlclient-mysqlparametercollection-contains-overload-1:: `MySqlParameterCollection.Contains' Method * connector-net-ref-mysqlclient-mysqlparametercollection-contains-overload-2:: `MySqlParameterCollection.Contains' Method Gets a value indicating whether a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. exists in the collection. *Overload List* Gets a value indicating whether a MySqlParameter exists in the collection. * *Note public bool Contains(object);: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overload-1. Gets a value indicating whether a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. with the specified parameter name exists in the collection. * *Note public bool Contains(string);: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overload-2. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overload-1, Next: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overload-2, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads, Up: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads 21.2.9.97 `MySqlParameterCollection.Contains' Method .................................................... Gets a value indicating whether a MySqlParameter exists in the collection. *Syntax: Visual Basic* NotOverridable Overloads Public Function Contains( _ ByVal value As Object _ ) As Boolean _ _ Implements IList.Contains *Syntax: C#* public bool Contains( objectvalue ); *Parameters* * `value': The value of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to find. *Return Value* true if the collection contains the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object; otherwise, false. *Implements* IList.Contains *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.Contains Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overload-2, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overload-1, Up: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads 21.2.9.98 `MySqlParameterCollection.Contains' Method .................................................... Gets a value indicating whether a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. with the specified parameter name exists in the collection. *Syntax: Visual Basic* NotOverridable Overloads Public Function Contains( _ ByVal name As String _ ) As Boolean _ _ Implements IDataParameterCollection.Contains *Syntax: C#* public bool Contains( stringname ); *Parameters* * `name': The name of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to find. *Return Value* true if the collection contains the parameter; otherwise, false. *Implements* IDataParameterCollection.Contains *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.Contains Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-copyto, Next: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.99 `MySqlParameterCollection.CopyTo' Method .................................................. Copies MySqlParameter objects from the MySqlParameterCollection to the specified array. *Syntax: Visual Basic* NotOverridable Public Sub CopyTo( _ ByVal array As Array, _ ByVal index As Integer _ ) _ _ Implements ICollection.CopyTo *Syntax: C#* public void CopyTo( Arrayarray, intindex ); *Parameters* * `array': * `index': *Implements* ICollection.CopyTo *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads, Next: connector-net-ref-mysqlclient-mysqlparametercollection-insert, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-copyto, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.100 IndexOf Method ......................... * Menu: * connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overload-1:: `MySqlParameterCollection.IndexOf' Method * connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overload-2:: `MySqlParameterCollection.IndexOf' Method Gets the location of a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. in the collection. *Overload List* Gets the location of a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. in the collection. * *Note public int IndexOf(object);: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overload-1. Gets the location of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. in the collection with a specific parameter name. * *Note public int IndexOf(string);: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overload-2. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overload-1, Next: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overload-2, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads, Up: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads 21.2.9.101 `MySqlParameterCollection.IndexOf' Method .................................................... Gets the location of a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. in the collection. *Syntax: Visual Basic* NotOverridable Overloads Public Function IndexOf( _ ByVal value As Object _ ) As Integer _ _ Implements IList.IndexOf *Syntax: C#* public int IndexOf( objectvalue ); *Parameters* * `value': The *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to locate. *Return Value* The zero-based location of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. in the collection. *Implements* IList.IndexOf *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.IndexOf Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overload-2, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overload-1, Up: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads 21.2.9.102 `MySqlParameterCollection.IndexOf' Method .................................................... Gets the location of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. in the collection with a specific parameter name. *Syntax: Visual Basic* NotOverridable Overloads Public Function IndexOf( _ ByVal parameterName As String _ ) As Integer _ _ Implements IDataParameterCollection.IndexOf *Syntax: C#* public int IndexOf( stringparameterName ); *Parameters* * `parameterName': The name of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to retrieve. *Return Value* The zero-based location of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. in the collection. *Implements* IDataParameterCollection.IndexOf *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.IndexOf Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-insert, Next: connector-net-ref-mysqlclient-mysqlparametercollection-remove, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.103 `MySqlParameterCollection.Insert' Method ................................................... Inserts a MySqlParameter into the collection at the specified index. *Syntax: Visual Basic* NotOverridable Public Sub Insert( _ ByVal index As Integer, _ ByVal value As Object _ ) _ _ Implements IList.Insert *Syntax: C#* public void Insert( intindex, objectvalue ); *Parameters* * `index': * `value': *Implements* IList.Insert *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-remove, Next: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overloads, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-insert, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.104 `MySqlParameterCollection.Remove' Method ................................................... Removes the specified MySqlParameter from the collection. *Syntax: Visual Basic* NotOverridable Public Sub Remove( _ ByVal value As Object _ ) _ _ Implements IList.Remove *Syntax: C#* public void Remove( objectvalue ); *Parameters* * `value': *Implements* IList.Remove *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overloads, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-remove, Up: connector-net-ref-mysqlclient-mysqlparametercollectionmembers 21.2.9.105 RemoveAt Method .......................... * Menu: * connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overload-1:: `MySqlParameterCollection.RemoveAt' Method * connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overload-2:: `MySqlParameterCollection.RemoveAt' Method Removes the specified *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. from the collection. *Overload List* Removes the specified *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. from the collection using a specific index. * *Note public void RemoveAt(int);: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overload-1. Removes the specified *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. from the collection using the parameter name. * *Note public void RemoveAt(string);: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overload-2. *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overload-1, Next: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overload-2, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overloads, Up: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overloads 21.2.9.106 `MySqlParameterCollection.RemoveAt' Method ..................................................... Removes the specified *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. from the collection using a specific index. *Syntax: Visual Basic* NotOverridable Overloads Public Sub RemoveAt( _ ByVal index As Integer _ ) _ _ Implements IList.RemoveAt *Syntax: C#* public void RemoveAt( intindex ); *Parameters* * `index': The zero-based index of the parameter. *Implements* IList.RemoveAt *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.RemoveAt Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overload-2, Prev: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overload-1, Up: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overloads 21.2.9.107 `MySqlParameterCollection.RemoveAt' Method ..................................................... Removes the specified *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. from the collection using the parameter name. *Syntax: Visual Basic* NotOverridable Overloads Public Sub RemoveAt( _ ByVal name As String _ ) _ _ Implements IDataParameterCollection.RemoveAt *Syntax: C#* public void RemoveAt( stringname ); *Parameters* * `name': The name of the *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object to retrieve. *Implements* IDataParameterCollection.RemoveAt *See Also* *Note MySqlParameterCollection Class: connector-net-ref-mysqlclient-mysqlparametercollection, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlParameterCollection.RemoveAt Overload List: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-transaction, Next: connector-net-ref-mysqlclient-mysqlcommand-updatedrowsource, Prev: connector-net-ref-mysqlclient-mysqlcommand-parameters, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.108 Transaction Property ............................... *Syntax: Visual Basic* Public Property Transaction As MySqlTransaction *Syntax: C#* public MySqlTransaction Transaction {get; set;} *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-updatedrowsource, Next: connector-net-ref-mysqlclient-mysqlcommand-cancel, Prev: connector-net-ref-mysqlclient-mysqlcommand-transaction, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.109 UpdatedRowSource Property .................................... *Syntax: Visual Basic* NotOverridable Public Property UpdatedRowSource As UpdateRowSource _ _ Implements IDbCommand.UpdatedRowSource *Syntax: C#* public System.Data.UpdateRowSource UpdatedRowSource {get; set;} *Implements* IDbCommand.UpdatedRowSource *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-cancel, Next: connector-net-ref-mysqlclient-mysqlcommand-createparameter, Prev: connector-net-ref-mysqlclient-mysqlcommand-updatedrowsource, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.110 `MySqlCommand.Cancel' Method ....................................... Attempts to cancel the execution of a MySqlCommand. This operation is not supported. *Syntax: Visual Basic* NotOverridable Public Sub Cancel() _ _ Implements IDbCommand.Cancel *Syntax: C#* public void Cancel(); *Implements* IDbCommand.Cancel *Remarks* Cancelling an executing command is currently not supported on any version of MySQL. *Exceptions* Exceptions in the MySqlCommand.Cancel method. *Exception Type* *Condition* NotSupportedException This operation is not supported. *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-createparameter, Next: connector-net-ref-mysqlclient-mysqlcommand-executenonquery, Prev: connector-net-ref-mysqlclient-mysqlcommand-cancel, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.111 `MySqlCommand.CreateParameter' Method ................................................ Creates a new instance of a *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object. *Syntax: Visual Basic* Public Function CreateParameter() As MySqlParameter *Syntax: C#* public MySqlParameter CreateParameter(); *Return Value* A *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. object. *Remarks* This method is a strongly-typed version of CreateParameter. *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-executenonquery, Next: connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads, Prev: connector-net-ref-mysqlclient-mysqlcommand-createparameter, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.112 `MySqlCommand.ExecuteNonQuery' Method ................................................ *Syntax: Visual Basic* NotOverridable Public Function ExecuteNonQuery() As Integer _ _ Implements IDbCommand.ExecuteNonQuery *Syntax: C#* public int ExecuteNonQuery(); *Implements* IDbCommand.ExecuteNonQuery *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads, Next: connector-net-ref-mysqlclient-mysqlcommand-executescalar, Prev: connector-net-ref-mysqlclient-mysqlcommand-executenonquery, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.113 ExecuteReader Method ............................... * Menu: * connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-1:: `MySqlCommand.ExecuteReader' Method * connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-2:: `MySqlCommand.ExecuteReader' Method *Overload List* * *Note public MySqlDataReader ExecuteReader();: connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-1. * *Note public MySqlDataReader ExecuteReader(CommandBehavior);: connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-2. *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-1, Next: connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-2, Prev: connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads, Up: connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads 21.2.9.114 `MySqlCommand.ExecuteReader' Method .............................................. * Menu: * connector-net-ref-mysqlclient-mysqldatareader:: `MySqlDataReader' Class *Syntax: Visual Basic* Overloads Public Function ExecuteReader() As MySqlDataReader *Syntax: C#* public MySqlDataReader ExecuteReader(); *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommand.ExecuteReader Overload List: connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader, Prev: connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-1, Up: connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-1 21.2.9.115 `MySqlDataReader' Class .................................. * Menu: * connector-net-ref-mysqlclient-mysqldatareadermembers:: `MySqlDataReader' Members Provides a means of reading a forward-only stream of rows from a MySQL database. This class cannot be inherited. For a list of all members of this type, see *Note MySqlDataReader Members: connector-net-ref-mysqlclient-mysqldatareadermembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlDataReader_ Inherits MarshalByRefObject_ Implements IEnumerable, IDataReader, IDisposable, IDataRecord *Syntax: C#* public sealed class MySqlDataReader : MarshalByRefObject, IEnumerable, IDataReader, IDisposable, IDataRecord *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlDataReader Members: connector-net-ref-mysqlclient-mysqldatareadermembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareadermembers, Prev: connector-net-ref-mysqlclient-mysqldatareader, Up: connector-net-ref-mysqlclient-mysqldatareader 21.2.9.116 `MySqlDataReader' Members .................................... * Menu: * connector-net-ref-mysqlclient-mysqldatareader-depth:: Depth Property * connector-net-ref-mysqlclient-mysqldatareader-fieldcount:: FieldCount Property * connector-net-ref-mysqlclient-mysqldatareader-hasrows:: HasRows Property * connector-net-ref-mysqlclient-mysqldatareader-isclosed:: IsClosed Property * connector-net-ref-mysqlclient-mysqldatareaderitem:: Item Property * connector-net-ref-mysqlclient-mysqldatareader-recordsaffected:: RecordsAffected Property * connector-net-ref-mysqlclient-mysqldatareader-close:: `MySqlDataReader.Close' Method * connector-net-ref-mysqlclient-mysqldatareader-getboolean:: `MySqlDataReader.GetBoolean' Method * connector-net-ref-mysqlclient-mysqldatareader-getbyte:: `MySqlDataReader.GetByte' Method * connector-net-ref-mysqlclient-mysqldatareader-getbytes:: `MySqlDataReader.GetBytes' Method * connector-net-ref-mysqlclient-mysqldatareader-getchar:: `MySqlDataReader.GetChar' Method * connector-net-ref-mysqlclient-mysqldatareader-getchars:: `MySqlDataReader.GetChars' Method * connector-net-ref-mysqlclient-mysqldatareader-getdatatypename:: `MySqlDataReader.GetDataTypeName' Method * connector-net-ref-mysqlclient-mysqldatareader-getdatetime:: `MySqlDataReader.GetDateTime' Method * connector-net-ref-mysqlclient-mysqldatareader-getdecimal:: `MySqlDataReader.GetDecimal' Method * connector-net-ref-mysqlclient-mysqldatareader-getdouble:: `MySqlDataReader.GetDouble' Method * connector-net-ref-mysqlclient-mysqldatareader-getfieldtype:: `MySqlDataReader.GetFieldType' Method * connector-net-ref-mysqlclient-mysqldatareader-getfloat:: `MySqlDataReader.GetFloat' Method * connector-net-ref-mysqlclient-mysqldatareader-getguid:: `MySqlDataReader.GetGuid' Method * connector-net-ref-mysqlclient-mysqldatareader-getint16:: `MySqlDataReader.GetInt16' Method * connector-net-ref-mysqlclient-mysqldatareader-getint32:: `MySqlDataReader.GetInt32' Method * connector-net-ref-mysqlclient-mysqldatareader-getint64:: `MySqlDataReader.GetInt64' Method * connector-net-ref-mysqlclient-mysqldatareader-getmysqldatetime:: `MySqlDataReader.GetMySqlDateTime' Method * connector-net-ref-mysqlclient-mysqldatareader-getname:: `MySqlDataReader.GetName' Method * connector-net-ref-mysqlclient-mysqldatareader-getordinal:: `MySqlDataReader.GetOrdinal' Method * connector-net-ref-mysqlclient-mysqldatareader-getschematable:: `MySqlDataReader.GetSchemaTable' Method * connector-net-ref-mysqlclient-mysqldatareader-getstring:: `MySqlDataReader.GetString' Method * connector-net-ref-mysqlclient-mysqldatareader-gettimespan:: `MySqlDataReader.GetTimeSpan' Method * connector-net-ref-mysqlclient-mysqldatareader-getuint16:: `MySqlDataReader.GetUInt16' Method * connector-net-ref-mysqlclient-mysqldatareader-getuint32:: `MySqlDataReader.GetUInt32' Method * connector-net-ref-mysqlclient-mysqldatareader-getuint64:: `MySqlDataReader.GetUInt64' Method * connector-net-ref-mysqlclient-mysqldatareader-getvalue:: `MySqlDataReader.GetValue' Method * connector-net-ref-mysqlclient-mysqldatareader-getvalues:: `MySqlDataReader.GetValues' Method * connector-net-ref-mysqlclient-mysqldatareader-isdbnull:: `MySqlDataReader.IsDBNull' Method * connector-net-ref-mysqlclient-mysqldatareader-nextresult:: `MySqlDataReader.NextResult' Method * connector-net-ref-mysqlclient-mysqldatareader-read:: `MySqlDataReader.Read' Method *Note MySqlDataReader overview: connector-net-ref-mysqlclient-mysqldatareader. *Public Instance Properties* Public instance properties in the MySqlDataReader class. *Note Depth: Gets a value indicating the depth connector-net-ref-mysqlclient-mysqldatareader-depth.of nesting for the current row. This method is not supported currently and always returns 0. *Note FieldCount: Gets the number of columns in the connector-net-ref-mysqlclient-mysqldatareader-fieldcount.current row. *Note HasRows: Gets a value indicating whether the connector-net-ref-mysqlclient-mysqldatareader-hasrows.MySqlDataReader contains one or more rows. *Note IsClosed: Gets a value indicating whether the connector-net-ref-mysqlclient-mysqldatareader-isclosed.data reader is closed. *Note Item: Overloaded. Overloaded. Gets the connector-net-ref-mysqlclient-mysqldatareaderitem.value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class. *Note RecordsAffected: Gets the number of rows changed, connector-net-ref-mysqlclient-mysqldatareader-recordsaffected.inserted, or deleted by execution of the SQL statement. *Public Instance Methods* Public instance methods in the MySqlDataReader class. *Note Close: Closes the MySqlDataReader object. connector-net-ref-mysqlclient-mysqldatareader-close. CreateObjRef (inherited from Creates an object that contains all MarshalByRefObject) the relevant information required to generate a proxy used to communicate with a remote object. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. *Note GetBoolean: Gets the value of the specified connector-net-ref-mysqlclient-mysqldatareader-getboolean.column as a Boolean. *Note GetByte: Gets the value of the specified connector-net-ref-mysqlclient-mysqldatareader-getbyte.column as a byte. *Note GetBytes: Reads a stream of bytes from the connector-net-ref-mysqlclient-mysqldatareader-getbytes.specified column offset into the buffer an array starting at the given buffer offset. *Note GetChar: Gets the value of the specified connector-net-ref-mysqlclient-mysqldatareader-getchar.column as a single character. *Note GetChars: Reads a stream of characters from connector-net-ref-mysqlclient-mysqldatareader-getchars.the specified column offset into the buffer as an array starting at the given buffer offset. *Note GetDataTypeName: Gets the name of the source data connector-net-ref-mysqlclient-mysqldatareader-getdatatypename.type. *Note GetDateTime: connector-net-ref-mysqlclient-mysqldatareader-getdatetime. *Note GetDecimal: connector-net-ref-mysqlclient-mysqldatareader-getdecimal. *Note GetDouble: connector-net-ref-mysqlclient-mysqldatareader-getdouble. *Note GetFieldType: Gets the Type that is the data type connector-net-ref-mysqlclient-mysqldatareader-getfieldtype.of the object. *Note GetFloat: connector-net-ref-mysqlclient-mysqldatareader-getfloat. *Note GetGuid: connector-net-ref-mysqlclient-mysqldatareader-getguid. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. *Note GetInt16: connector-net-ref-mysqlclient-mysqldatareader-getint16. *Note GetInt32: connector-net-ref-mysqlclient-mysqldatareader-getint32. *Note GetInt64: connector-net-ref-mysqlclient-mysqldatareader-getint64. GetLifetimeService (inherited from Retrieves the current lifetime MarshalByRefObject) service object that controls the lifetime policy for this instance. *Note GetMySqlDateTime: connector-net-ref-mysqlclient-mysqldatareader-getmysqldatetime. *Note GetName: Gets the name of the specified connector-net-ref-mysqlclient-mysqldatareader-getname.column. *Note GetOrdinal: Gets the column ordinal, given the connector-net-ref-mysqlclient-mysqldatareader-getordinal.name of the column. *Note GetSchemaTable: Returns a DataTable that describes connector-net-ref-mysqlclient-mysqldatareader-getschematable.the column metadata of the MySqlDataReader. *Note GetString: connector-net-ref-mysqlclient-mysqldatareader-getstring. *Note GetTimeSpan: connector-net-ref-mysqlclient-mysqldatareader-gettimespan. GetType (inherited from Object) Gets the Type of the current instance. *Note GetUInt16: connector-net-ref-mysqlclient-mysqldatareader-getuint16. *Note GetUInt32: connector-net-ref-mysqlclient-mysqldatareader-getuint32. *Note GetUInt64: connector-net-ref-mysqlclient-mysqldatareader-getuint64. *Note GetValue: Gets the value of the specified connector-net-ref-mysqlclient-mysqldatareader-getvalue.column in its native format. *Note GetValues: Gets all attribute columns in the connector-net-ref-mysqlclient-mysqldatareader-getvalues.collection for the current row. InitializeLifetimeService Obtains a lifetime service object (inherited from MarshalByRefObject) to control the lifetime policy for this instance. *Note IsDBNull: Gets a value indicating whether the connector-net-ref-mysqlclient-mysqldatareader-isdbnull.column contains non-existent or missing values. *Note NextResult: Advances the data reader to the connector-net-ref-mysqlclient-mysqldatareader-nextresult.next result, when reading the results of batch SQL statements. *Note Read: Advances the MySqlDataReader to the connector-net-ref-mysqlclient-mysqldatareader-read.next record. ToString (inherited from Object) Returns a String that represents the current Object. *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-depth, Next: connector-net-ref-mysqlclient-mysqldatareader-fieldcount, Prev: connector-net-ref-mysqlclient-mysqldatareadermembers, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.117 Depth Property ......................... Gets a value indicating the depth of nesting for the current row. This method is not supported currently and always returns 0. *Syntax: Visual Basic* NotOverridable Public ReadOnly Property Depth As Integer _ _ Implements IDataReader.Depth *Syntax: C#* public int Depth {get;} *Implements* IDataReader.Depth *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-fieldcount, Next: connector-net-ref-mysqlclient-mysqldatareader-hasrows, Prev: connector-net-ref-mysqlclient-mysqldatareader-depth, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.118 FieldCount Property .............................. Gets the number of columns in the current row. *Syntax: Visual Basic* NotOverridable Public ReadOnly Property FieldCount As Integer _ _ Implements IDataRecord.FieldCount *Syntax: C#* public int FieldCount {get;} *Implements* IDataRecord.FieldCount *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-hasrows, Next: connector-net-ref-mysqlclient-mysqldatareader-isclosed, Prev: connector-net-ref-mysqlclient-mysqldatareader-fieldcount, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.119 HasRows Property ........................... Gets a value indicating whether the MySqlDataReader contains one or more rows. *Syntax: Visual Basic* Public ReadOnly Property HasRows As Boolean *Syntax: C#* public bool HasRows {get;} *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-isclosed, Next: connector-net-ref-mysqlclient-mysqldatareaderitem, Prev: connector-net-ref-mysqlclient-mysqldatareader-hasrows, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.120 IsClosed Property ............................ Gets a value indicating whether the data reader is closed. *Syntax: Visual Basic* NotOverridable Public ReadOnly Property IsClosed As Boolean _ _ Implements IDataReader.IsClosed *Syntax: C#* public bool IsClosed {get;} *Implements* IDataReader.IsClosed *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareaderitem, Next: connector-net-ref-mysqlclient-mysqldatareader-recordsaffected, Prev: connector-net-ref-mysqlclient-mysqldatareader-isclosed, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.121 Item Property ........................ * Menu: * connector-net-ref-mysqlclient-mysqldatareader-item1:: Item Property (Int32) * connector-net-ref-mysqlclient-mysqldatareader-item2:: Item Property (String) Overloaded. Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class. *Overload List* Overloaded. Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class. * *Note public object this[int] {get;}: connector-net-ref-mysqlclient-mysqldatareader-item1. Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class. * *Note public object this[string] {get;}: connector-net-ref-mysqlclient-mysqldatareader-item2. *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-item1, Next: connector-net-ref-mysqlclient-mysqldatareader-item2, Prev: connector-net-ref-mysqlclient-mysqldatareaderitem, Up: connector-net-ref-mysqlclient-mysqldatareaderitem 21.2.9.122 Item Property (Int32) ................................ Overloaded. Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class. *Syntax: Visual Basic* NotOverridable Overloads Public Default ReadOnly Property Item( _ ByVal i As Integer _ ) _ _ Implements IDataRecord.Item As Object _ _ Implements IDataRecord.Item *Syntax: C#* public object this[ inti ] {get;} *Implements* IDataRecord.Item *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlDataReader.Item Overload List: connector-net-ref-mysqlclient-mysqldatareaderitem.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-item2, Prev: connector-net-ref-mysqlclient-mysqldatareader-item1, Up: connector-net-ref-mysqlclient-mysqldatareaderitem 21.2.9.123 Item Property (String) ................................. Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class. *Syntax: Visual Basic* NotOverridable Overloads Public Default ReadOnly Property Item( _ ByVal name As String _ ) _ _ Implements IDataRecord.Item As Object _ _ Implements IDataRecord.Item *Syntax: C#* public object this[ stringname ] {get;} *Implements* IDataRecord.Item *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlDataReader.Item Overload List: connector-net-ref-mysqlclient-mysqldatareaderitem.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-recordsaffected, Next: connector-net-ref-mysqlclient-mysqldatareader-close, Prev: connector-net-ref-mysqlclient-mysqldatareaderitem, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.124 RecordsAffected Property ................................... Gets the number of rows changed, inserted, or deleted by execution of the SQL statement. *Syntax: Visual Basic* NotOverridable Public ReadOnly Property RecordsAffected As Integer _ _ Implements IDataReader.RecordsAffected *Syntax: C#* public int RecordsAffected {get;} *Implements* IDataReader.RecordsAffected *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-close, Next: connector-net-ref-mysqlclient-mysqldatareader-getboolean, Prev: connector-net-ref-mysqlclient-mysqldatareader-recordsaffected, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.125 `MySqlDataReader.Close' Method ......................................... Closes the MySqlDataReader object. *Syntax: Visual Basic* NotOverridable Public Sub Close() _ _ Implements IDataReader.Close *Syntax: C#* public void Close(); *Implements* IDataReader.Close *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getboolean, Next: connector-net-ref-mysqlclient-mysqldatareader-getbyte, Prev: connector-net-ref-mysqlclient-mysqldatareader-close, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.126 `MySqlDataReader.GetBoolean' Method .............................................. Gets the value of the specified column as a Boolean. *Syntax: Visual Basic* NotOverridable Public Function GetBoolean( _ ByVal i As Integer _ ) As Boolean _ _ Implements IDataRecord.GetBoolean *Syntax: C#* public bool GetBoolean( inti ); *Parameters* * `i': *Return Value* *Implements* IDataRecord.GetBoolean *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getbyte, Next: connector-net-ref-mysqlclient-mysqldatareader-getbytes, Prev: connector-net-ref-mysqlclient-mysqldatareader-getboolean, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.127 `MySqlDataReader.GetByte' Method ........................................... Gets the value of the specified column as a byte. *Syntax: Visual Basic* NotOverridable Public Function GetByte( _ ByVal i As Integer _ ) As Byte _ _ Implements IDataRecord.GetByte *Syntax: C#* public byte GetByte( inti ); *Parameters* * `i': *Return Value* *Implements* IDataRecord.GetByte *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getbytes, Next: connector-net-ref-mysqlclient-mysqldatareader-getchar, Prev: connector-net-ref-mysqlclient-mysqldatareader-getbyte, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.128 `MySqlDataReader.GetBytes' Method ............................................ Reads a stream of bytes from the specified column offset into the buffer an array starting at the given buffer offset. *Syntax: Visual Basic* NotOverridable Public Function GetBytes( _ ByVal i As Integer, _ ByVal dataIndex As Long, _ ByVal buffer As Byte(), _ ByVal bufferIndex As Integer, _ ByVal length As Integer _ ) As Long _ _ Implements IDataRecord.GetBytes *Syntax: C#* public long GetBytes( inti, longdataIndex, byte[]buffer, intbufferIndex, intlength ); *Parameters* * `i': The zero-based column ordinal. * `dataIndex': The index within the field from which to begin the read operation. * `buffer': The buffer into which to read the stream of bytes. * `bufferIndex': The index for buffer to begin the read operation. * `length': The maximum length to copy into the buffer. *Return Value* The actual number of bytes read. *Implements* IDataRecord.GetBytes *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getchar, Next: connector-net-ref-mysqlclient-mysqldatareader-getchars, Prev: connector-net-ref-mysqlclient-mysqldatareader-getbytes, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.129 `MySqlDataReader.GetChar' Method ........................................... Gets the value of the specified column as a single character. *Syntax: Visual Basic* NotOverridable Public Function GetChar( _ ByVal i As Integer _ ) As Char _ _ Implements IDataRecord.GetChar *Syntax: C#* public char GetChar( inti ); *Parameters* * `i': *Return Value* *Implements* IDataRecord.GetChar *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getchars, Next: connector-net-ref-mysqlclient-mysqldatareader-getdatatypename, Prev: connector-net-ref-mysqlclient-mysqldatareader-getchar, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.130 `MySqlDataReader.GetChars' Method ............................................ Reads a stream of characters from the specified column offset into the buffer as an array starting at the given buffer offset. *Syntax: Visual Basic* NotOverridable Public Function GetChars( _ ByVal i As Integer, _ ByVal fieldOffset As Long, _ ByVal buffer As Char(), _ ByVal bufferoffset As Integer, _ ByVal length As Integer _ ) As Long _ _ Implements IDataRecord.GetChars *Syntax: C#* public long GetChars( inti, longfieldOffset, char[]buffer, intbufferoffset, intlength ); *Parameters* * `i': * `fieldOffset': * `buffer': * `bufferoffset': * `length': *Return Value* *Implements* IDataRecord.GetChars *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getdatatypename, Next: connector-net-ref-mysqlclient-mysqldatareader-getdatetime, Prev: connector-net-ref-mysqlclient-mysqldatareader-getchars, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.131 `MySqlDataReader.GetDataTypeName' Method ................................................... Gets the name of the source data type. *Syntax: Visual Basic* NotOverridable Public Function GetDataTypeName( _ ByVal i As Integer _ ) As String _ _ Implements IDataRecord.GetDataTypeName *Syntax: C#* public string GetDataTypeName( inti ); *Parameters* * `i': *Return Value* *Implements* IDataRecord.GetDataTypeName *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getdatetime, Next: connector-net-ref-mysqlclient-mysqldatareader-getdecimal, Prev: connector-net-ref-mysqlclient-mysqldatareader-getdatatypename, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.132 `MySqlDataReader.GetDateTime' Method ............................................... *Syntax: Visual Basic* NotOverridable Public Function GetDateTime( _ ByVal index As Integer _ ) As Date _ _ Implements IDataRecord.GetDateTime *Syntax: C#* public DateTime GetDateTime( intindex ); *Implements* IDataRecord.GetDateTime *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getdecimal, Next: connector-net-ref-mysqlclient-mysqldatareader-getdouble, Prev: connector-net-ref-mysqlclient-mysqldatareader-getdatetime, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.133 `MySqlDataReader.GetDecimal' Method .............................................. *Syntax: Visual Basic* NotOverridable Public Function GetDecimal( _ ByVal index As Integer _ ) As Decimal _ _ Implements IDataRecord.GetDecimal *Syntax: C#* public decimal GetDecimal( intindex ); *Implements* IDataRecord.GetDecimal *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getdouble, Next: connector-net-ref-mysqlclient-mysqldatareader-getfieldtype, Prev: connector-net-ref-mysqlclient-mysqldatareader-getdecimal, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.134 `MySqlDataReader.GetDouble' Method ............................................. *Syntax: Visual Basic* NotOverridable Public Function GetDouble( _ ByVal index As Integer _ ) As Double _ _ Implements IDataRecord.GetDouble *Syntax: C#* public double GetDouble( intindex ); *Implements* IDataRecord.GetDouble *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getfieldtype, Next: connector-net-ref-mysqlclient-mysqldatareader-getfloat, Prev: connector-net-ref-mysqlclient-mysqldatareader-getdouble, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.135 `MySqlDataReader.GetFieldType' Method ................................................ Gets the Type that is the data type of the object. *Syntax: Visual Basic* NotOverridable Public Function GetFieldType( _ ByVal i As Integer _ ) As Type _ _ Implements IDataRecord.GetFieldType *Syntax: C#* public Type GetFieldType( inti ); *Parameters* * `i': *Return Value* *Implements* IDataRecord.GetFieldType *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getfloat, Next: connector-net-ref-mysqlclient-mysqldatareader-getguid, Prev: connector-net-ref-mysqlclient-mysqldatareader-getfieldtype, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.136 `MySqlDataReader.GetFloat' Method ............................................ *Syntax: Visual Basic* NotOverridable Public Function GetFloat( _ ByVal index As Integer _ ) As Single _ _ Implements IDataRecord.GetFloat *Syntax: C#* public float GetFloat( intindex ); *Implements* IDataRecord.GetFloat *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getguid, Next: connector-net-ref-mysqlclient-mysqldatareader-getint16, Prev: connector-net-ref-mysqlclient-mysqldatareader-getfloat, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.137 `MySqlDataReader.GetGuid' Method ........................................... *Syntax: Visual Basic* NotOverridable Public Function GetGuid( _ ByVal index As Integer _ ) As Guid _ _ Implements IDataRecord.GetGuid *Syntax: C#* public Guid GetGuid( intindex ); *Implements* IDataRecord.GetGuid *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getint16, Next: connector-net-ref-mysqlclient-mysqldatareader-getint32, Prev: connector-net-ref-mysqlclient-mysqldatareader-getguid, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.138 `MySqlDataReader.GetInt16' Method ............................................ *Syntax: Visual Basic* NotOverridable Public Function GetInt16( _ ByVal index As Integer _ ) As Short _ _ Implements IDataRecord.GetInt16 *Syntax: C#* public short GetInt16( intindex ); *Implements* IDataRecord.GetInt16 *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getint32, Next: connector-net-ref-mysqlclient-mysqldatareader-getint64, Prev: connector-net-ref-mysqlclient-mysqldatareader-getint16, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.139 `MySqlDataReader.GetInt32' Method ............................................ *Syntax: Visual Basic* NotOverridable Public Function GetInt32( _ ByVal index As Integer _ ) As Integer _ _ Implements IDataRecord.GetInt32 *Syntax: C#* public int GetInt32( intindex ); *Implements* IDataRecord.GetInt32 *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getint64, Next: connector-net-ref-mysqlclient-mysqldatareader-getmysqldatetime, Prev: connector-net-ref-mysqlclient-mysqldatareader-getint32, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.140 `MySqlDataReader.GetInt64' Method ............................................ *Syntax: Visual Basic* NotOverridable Public Function GetInt64( _ ByVal index As Integer _ ) As Long _ _ Implements IDataRecord.GetInt64 *Syntax: C#* public long GetInt64( intindex ); *Implements* IDataRecord.GetInt64 *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getmysqldatetime, Next: connector-net-ref-mysqlclient-mysqldatareader-getname, Prev: connector-net-ref-mysqlclient-mysqldatareader-getint64, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.141 `MySqlDataReader.GetMySqlDateTime' Method .................................................... *Syntax: Visual Basic* Public Function GetMySqlDateTime( _ ByVal index As Integer _ ) As MySqlDateTime *Syntax: C#* public MySqlDateTime GetMySqlDateTime( intindex ); *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getname, Next: connector-net-ref-mysqlclient-mysqldatareader-getordinal, Prev: connector-net-ref-mysqlclient-mysqldatareader-getmysqldatetime, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.142 `MySqlDataReader.GetName' Method ........................................... Gets the name of the specified column. *Syntax: Visual Basic* NotOverridable Public Function GetName( _ ByVal i As Integer _ ) As String _ _ Implements IDataRecord.GetName *Syntax: C#* public string GetName( inti ); *Parameters* * `i': *Return Value* *Implements* IDataRecord.GetName *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getordinal, Next: connector-net-ref-mysqlclient-mysqldatareader-getschematable, Prev: connector-net-ref-mysqlclient-mysqldatareader-getname, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.143 `MySqlDataReader.GetOrdinal' Method .............................................. Gets the column ordinal, given the name of the column. *Syntax: Visual Basic* NotOverridable Public Function GetOrdinal( _ ByVal name As String _ ) As Integer _ _ Implements IDataRecord.GetOrdinal *Syntax: C#* public int GetOrdinal( stringname ); *Parameters* * `name': *Return Value* *Implements* IDataRecord.GetOrdinal *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getschematable, Next: connector-net-ref-mysqlclient-mysqldatareader-getstring, Prev: connector-net-ref-mysqlclient-mysqldatareader-getordinal, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.144 `MySqlDataReader.GetSchemaTable' Method .................................................. Returns a DataTable that describes the column metadata of the MySqlDataReader. *Syntax: Visual Basic* NotOverridable Public Function GetSchemaTable() As DataTable _ _ Implements IDataReader.GetSchemaTable *Syntax: C#* public DataTable GetSchemaTable(); *Return Value* *Implements* IDataReader.GetSchemaTable *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getstring, Next: connector-net-ref-mysqlclient-mysqldatareader-gettimespan, Prev: connector-net-ref-mysqlclient-mysqldatareader-getschematable, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.145 `MySqlDataReader.GetString' Method ............................................. *Syntax: Visual Basic* NotOverridable Public Function GetString( _ ByVal index As Integer _ ) As String _ _ Implements IDataRecord.GetString *Syntax: C#* public string GetString( intindex ); *Implements* IDataRecord.GetString *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-gettimespan, Next: connector-net-ref-mysqlclient-mysqldatareader-getuint16, Prev: connector-net-ref-mysqlclient-mysqldatareader-getstring, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.146 `MySqlDataReader.GetTimeSpan' Method ............................................... *Syntax: Visual Basic* Public Function GetTimeSpan( _ ByVal index As Integer _ ) As TimeSpan *Syntax: C#* public TimeSpan GetTimeSpan( intindex ); *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getuint16, Next: connector-net-ref-mysqlclient-mysqldatareader-getuint32, Prev: connector-net-ref-mysqlclient-mysqldatareader-gettimespan, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.147 `MySqlDataReader.GetUInt16' Method ............................................. *Syntax: Visual Basic* Public Function GetUInt16( _ ByVal index As Integer _ ) As UInt16 *Syntax: C#* public ushort GetUInt16( intindex ); *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getuint32, Next: connector-net-ref-mysqlclient-mysqldatareader-getuint64, Prev: connector-net-ref-mysqlclient-mysqldatareader-getuint16, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.148 `MySqlDataReader.GetUInt32' Method ............................................. *Syntax: Visual Basic* Public Function GetUInt32( _ ByVal index As Integer _ ) As UInt32 *Syntax: C#* public uint GetUInt32( intindex ); *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getuint64, Next: connector-net-ref-mysqlclient-mysqldatareader-getvalue, Prev: connector-net-ref-mysqlclient-mysqldatareader-getuint32, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.149 `MySqlDataReader.GetUInt64' Method ............................................. *Syntax: Visual Basic* Public Function GetUInt64( _ ByVal index As Integer _ ) As UInt64 *Syntax: C#* public ulong GetUInt64( intindex ); *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getvalue, Next: connector-net-ref-mysqlclient-mysqldatareader-getvalues, Prev: connector-net-ref-mysqlclient-mysqldatareader-getuint64, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.150 `MySqlDataReader.GetValue' Method ............................................ Gets the value of the specified column in its native format. *Syntax: Visual Basic* NotOverridable Public Function GetValue( _ ByVal i As Integer _ ) As Object _ _ Implements IDataRecord.GetValue *Syntax: C#* public object GetValue( inti ); *Parameters* * `i': *Return Value* *Implements* IDataRecord.GetValue *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-getvalues, Next: connector-net-ref-mysqlclient-mysqldatareader-isdbnull, Prev: connector-net-ref-mysqlclient-mysqldatareader-getvalue, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.151 `MySqlDataReader.GetValues' Method ............................................. Gets all attribute columns in the collection for the current row. *Syntax: Visual Basic* NotOverridable Public Function GetValues( _ ByVal values As Object() _ ) As Integer _ _ Implements IDataRecord.GetValues *Syntax: C#* public int GetValues( object[]values ); *Parameters* * `values': *Return Value* *Implements* IDataRecord.GetValues *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-isdbnull, Next: connector-net-ref-mysqlclient-mysqldatareader-nextresult, Prev: connector-net-ref-mysqlclient-mysqldatareader-getvalues, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.152 `MySqlDataReader.IsDBNull' Method ............................................ Gets a value indicating whether the column contains non-existent or missing values. *Syntax: Visual Basic* NotOverridable Public Function IsDBNull( _ ByVal i As Integer _ ) As Boolean _ _ Implements IDataRecord.IsDBNull *Syntax: C#* public bool IsDBNull( inti ); *Parameters* * `i': *Return Value* *Implements* IDataRecord.IsDBNull *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-nextresult, Next: connector-net-ref-mysqlclient-mysqldatareader-read, Prev: connector-net-ref-mysqlclient-mysqldatareader-isdbnull, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.153 `MySqlDataReader.NextResult' Method .............................................. Advances the data reader to the next result, when reading the results of batch SQL statements. *Syntax: Visual Basic* NotOverridable Public Function NextResult() As Boolean _ _ Implements IDataReader.NextResult *Syntax: C#* public bool NextResult(); *Return Value* *Implements* IDataReader.NextResult *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldatareader-read, Prev: connector-net-ref-mysqlclient-mysqldatareader-nextresult, Up: connector-net-ref-mysqlclient-mysqldatareadermembers 21.2.9.154 `MySqlDataReader.Read' Method ........................................ Advances the MySqlDataReader to the next record. *Syntax: Visual Basic* NotOverridable Public Function Read() As Boolean _ _ Implements IDataReader.Read *Syntax: C#* public bool Read(); *Return Value* *Implements* IDataReader.Read *See Also* *Note MySqlDataReader Class: connector-net-ref-mysqlclient-mysqldatareader, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-2, Prev: connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-1, Up: connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads 21.2.9.155 `MySqlCommand.ExecuteReader' Method .............................................. *Syntax: Visual Basic* Overloads Public Function ExecuteReader( _ ByVal behavior As CommandBehavior _ ) As MySqlDataReader *Syntax: C#* public MySqlDataReader ExecuteReader( CommandBehaviorbehavior ); *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommand.ExecuteReader Overload List: connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-executescalar, Next: connector-net-ref-mysqlclient-mysqlcommand-prepare, Prev: connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.156 `MySqlCommand.ExecuteScalar' Method .............................................. *Syntax: Visual Basic* NotOverridable Public Function ExecuteScalar() As Object _ _ Implements IDbCommand.ExecuteScalar *Syntax: C#* public object ExecuteScalar(); *Implements* IDbCommand.ExecuteScalar *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommand-prepare, Prev: connector-net-ref-mysqlclient-mysqlcommand-executescalar, Up: connector-net-ref-mysqlclient-mysqlcommandmembers 21.2.9.157 `MySqlCommand.Prepare' Method ........................................ *Syntax: Visual Basic* NotOverridable Public Sub Prepare() _ _ Implements IDbCommand.Prepare *Syntax: C#* public void Prepare(); *Implements* IDbCommand.Prepare *See Also* *Note MySqlCommand Class: connector-net-ref-mysqlclient-mysqlcommand, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder, Next: connector-net-ref-mysqlclient-mysqlexception, Prev: connector-net-ref-mysqlclient-mysqlcommand, Up: connector-net-ref-mysqlclient 21.2.9.158 `MySqlCommandBuilder' Class ...................................... * Menu: * connector-net-ref-mysqlclient-mysqlcommandbuildermembers:: `MySqlCommandBuilder' Members For a list of all members of this type, see *Note MySqlCommandBuilder Members: connector-net-ref-mysqlclient-mysqlcommandbuildermembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlCommandBuilder_ Inherits Component *Syntax: C#* public sealed class MySqlCommandBuilder : Component *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlCommandBuilder Members: connector-net-ref-mysqlclient-mysqlcommandbuildermembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuildermembers, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder, Up: connector-net-ref-mysqlclient-mysqlcommandbuilder 21.2.9.159 `MySqlCommandBuilder' Members ........................................ * Menu: * connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overloads:: DeriveParameters Method * connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor:: `MySqlCommandBuilder' Constructor * connector-net-ref-mysqlclient-mysqlcommandbuilder-dataadapter:: DataAdapter Property * connector-net-ref-mysqlclient-mysqlcommandbuilder-quoteprefix:: QuotePrefix Property * connector-net-ref-mysqlclient-mysqlcommandbuilder-quotesuffix:: QuoteSuffix Property * connector-net-ref-mysqlclient-mysqlcommandbuilder-getdeletecommand:: `MySqlCommandBuilder.GetDeleteCommand' Method * connector-net-ref-mysqlclient-mysqlcommandbuilder-getinsertcommand:: `MySqlCommandBuilder.GetInsertCommand' Method * connector-net-ref-mysqlclient-mysqlcommandbuilder-getupdatecommand:: `MySqlCommandBuilder.GetUpdateCommand' Method * connector-net-ref-mysqlclient-mysqlcommandbuilder-refreshschema:: `MySqlCommandBuilder.RefreshSchema' Method *Note MySqlCommandBuilder overview: connector-net-ref-mysqlclient-mysqlcommandbuilder. *Public Static (Shared) Methods* Public static (shared) methods in the MySqlCommandBuilder class. *Note DeriveParameters: Overloaded. Retrieves parameter connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overloads.information from the stored procedure specified in the MySqlCommand and populates the Parameters collection of the specified MySqlCommand object. This method is not currently supported since stored procedures are not available in MySql. *Public Instance Constructors* Public instance constructors in the MySqlCommandBuilder class. *Note MySqlCommandBuilder: Overloaded. Initializes a new connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor.instance of the MySqlCommandBuilder class. *Public Instance Properties* Public instance properties in the MySqlCommandBuilder class. Container (inherited from Component) Gets the IContainer that contains the Component. *Note DataAdapter: connector-net-ref-mysqlclient-mysqlcommandbuilder-dataadapter. *Note QuotePrefix: connector-net-ref-mysqlclient-mysqlcommandbuilder-quoteprefix. *Note QuoteSuffix: connector-net-ref-mysqlclient-mysqlcommandbuilder-quotesuffix. Site (inherited from Component) Gets or sets the ISite of the Component. *Public Instance Methods* Public instance methods in the MySqlCommandBuilder class. CreateObjRef (inherited from Creates an object that contains all MarshalByRefObject) the relevant information required to generate a proxy used to communicate with a remote object. Dispose (inherited from Component) Releases all resources used by the Component. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. *Note GetDeleteCommand: connector-net-ref-mysqlclient-mysqlcommandbuilder-getdeletecommand. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. *Note GetInsertCommand: connector-net-ref-mysqlclient-mysqlcommandbuilder-getinsertcommand. GetLifetimeService (inherited from Retrieves the current lifetime MarshalByRefObject) service object that controls the lifetime policy for this instance. GetType (inherited from Object) Gets the Type of the current instance. *Note GetUpdateCommand: connector-net-ref-mysqlclient-mysqlcommandbuilder-getupdatecommand. InitializeLifetimeService Obtains a lifetime service object (inherited from MarshalByRefObject) to control the lifetime policy for this instance. *Note RefreshSchema: connector-net-ref-mysqlclient-mysqlcommandbuilder-refreshschema. ToString (inherited from Component) Returns a String containing the name of the Component, if any. This method should not be overridden. *Public Instance Events* Public instance events in the MySqlCommandBuilder class. Disposed (inherited from Component) Adds an event handler to listen to the Disposed event on the component. *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overloads, Next: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor, Prev: connector-net-ref-mysqlclient-mysqlcommandbuildermembers, Up: connector-net-ref-mysqlclient-mysqlcommandbuildermembers 21.2.9.160 DeriveParameters Method .................................. * Menu: * connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overload-1:: `MySqlCommandBuilder.DeriveParameters' Method * connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overload-2:: `MySqlCommandBuilder.DeriveParameters' Method Retrieves parameter information from the stored procedure specified in the MySqlCommand and populates the Parameters collection of the specified MySqlCommand object. This method is not currently supported since stored procedures are not available in MySql. *Overload List* Retrieves parameter information from the stored procedure specified in the MySqlCommand and populates the Parameters collection of the specified MySqlCommand object. This method is not currently supported since stored procedures are not available in MySql. * *Note public static void DeriveParameters(MySqlCommand);: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overload-1. * *Note public static void DeriveParameters(MySqlCommand: (bool);)connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overload-2. *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overload-1, Next: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overload-2, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overloads, Up: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overloads 21.2.9.161 `MySqlCommandBuilder.DeriveParameters' Method ........................................................ Retrieves parameter information from the stored procedure specified in the MySqlCommand and populates the Parameters collection of the specified MySqlCommand object. This method is not currently supported since stored procedures are not available in MySql. *Syntax: Visual Basic* Overloads Public Shared Sub DeriveParameters( _ ByVal command As MySqlCommand _ ) *Syntax: C#* public static void DeriveParameters( MySqlCommandcommand ); *Parameters* * `command': The MySqlCommand referencing the stored procedure from which the parameter information is to be derived. The derived parameters are added to the Parameters collection of the MySqlCommand. *Exceptions* Exceptions in the MySqlCommandBuilder.DeriveParameters method. *Exception Type* *Condition* InvalidOperationException The command text is not a valid stored procedure name. *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommandBuilder.DeriveParameters Overload List: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overload-2, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overload-1, Up: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overloads 21.2.9.162 `MySqlCommandBuilder.DeriveParameters' Method ........................................................ *Syntax: Visual Basic* Overloads Public Shared Sub DeriveParameters( _ ByVal command As MySqlCommand, _ ByVal useProc As Boolean _ ) *Syntax: C#* public static void DeriveParameters( MySqlCommandcommand, booluseProc ); *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommandBuilder.DeriveParameters Overload List: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor, Next: connector-net-ref-mysqlclient-mysqlcommandbuilder-dataadapter, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overloads, Up: connector-net-ref-mysqlclient-mysqlcommandbuildermembers 21.2.9.163 `MySqlCommandBuilder' Constructor ............................................ * Menu: * connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor1:: `MySqlCommandBuilder' Constructor * connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor3:: `MySqlCommandBuilder' Constructor * connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor4:: `MySqlCommandBuilder' Constructor * connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor2:: `MySqlCommandBuilder' Constructor Initializes a new instance of the *Note MySqlCommandBuilder: connector-net-ref-mysqlclient-mysqlcommandbuilder. class. *Overload List* Initializes a new instance of the *Note MySqlCommandBuilder: connector-net-ref-mysqlclient-mysqlcommandbuilder. class. * *Note public MySqlCommandBuilder();: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor1. * *Note public MySqlCommandBuilder(MySqlDataAdapter);: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor3. * *Note public MySqlCommandBuilder(MySqlDataAdapter: (bool);)connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor4. * *Note public MySqlCommandBuilder(bool);: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor2. *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor1, Next: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor3, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor, Up: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor 21.2.9.164 `MySqlCommandBuilder' Constructor ............................................ Initializes a new instance of the *Note MySqlCommandBuilder: connector-net-ref-mysqlclient-mysqlcommandbuilder. class. *Syntax: Visual Basic* Overloads Public Sub New() *Syntax: C#* public MySqlCommandBuilder(); *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommandBuilder Constructor Overload List: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor3, Next: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor4, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor1, Up: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor 21.2.9.165 `MySqlCommandBuilder' Constructor ............................................ * Menu: * connector-net-ref-mysqlclient-mysqldataadapter:: `MySqlDataAdapter' Class *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal adapter As MySqlDataAdapter _ ) *Syntax: C#* public MySqlCommandBuilder( MySqlDataAdapteradapter ); *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommandBuilder Constructor Overload List: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapter, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor3, Up: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor3 21.2.9.166 `MySqlDataAdapter' Class ................................... * Menu: * connector-net-ref-mysqlclient-mysqldataadaptermembers:: `MySqlDataAdapter' Members For a list of all members of this type, see *Note MySqlDataAdapter Members: connector-net-ref-mysqlclient-mysqldataadaptermembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlDataAdapter_ Inherits DbDataAdapter *Syntax: C#* public sealed class MySqlDataAdapter : DbDataAdapter *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlDataAdapter Members: connector-net-ref-mysqlclient-mysqldataadaptermembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadaptermembers, Prev: connector-net-ref-mysqlclient-mysqldataadapter, Up: connector-net-ref-mysqlclient-mysqldataadapter 21.2.9.167 `MySqlDataAdapter' Members ..................................... * Menu: * connector-net-ref-mysqlclient-mysqldataadapterconstructor:: `MySqlDataAdapter' Constructor * connector-net-ref-mysqlclient-mysqldataadapter-deletecommand1:: DeleteCommand Property * connector-net-ref-mysqlclient-mysqldataadapter-insertcommand1:: InsertCommand Property * connector-net-ref-mysqlclient-mysqldataadapter-selectcommand1:: SelectCommand Property * connector-net-ref-mysqlclient-mysqldataadapter-updatecommand1:: UpdateCommand Property * connector-net-ref-mysqlclient-mysqldataadapter-rowupdated:: `MySqlDataAdapter.RowUpdated' Event * connector-net-ref-mysqlclient-mysqldataadapter-rowupdating:: `MySqlDataAdapter.RowUpdating' Event *Note MySqlDataAdapter overview: connector-net-ref-mysqlclient-mysqldataadapter. *Public Instance Constructors* Public instance constructors in the MySqlDataAdapter class. *Note MySqlDataAdapter: Overloaded. Initializes a new connector-net-ref-mysqlclient-mysqldataadapterconstructor.instance of the MySqlDataAdapter class. *Public Instance Properties* Public instance properties in the MySqlDataAdapter class. AcceptChangesDuringFill (inherited Gets or sets a value indicating from DataAdapter) whether AcceptChangesis called on a DataRowafter it is added to the DataTableduring any of the Fill operations. AcceptChangesDuringUpdate Gets or sets whether (inherited from DataAdapter) AcceptChangesis called during a Update. Container (inherited from Component) Gets the IContainer that contains the Component. ContinueUpdateOnError (inherited Gets or sets a value that specifies from DataAdapter) whether to generate an exception when an error is encountered during a row update. *Note DeleteCommand: Overloaded. connector-net-ref-mysqlclient-mysqldataadapter-deletecommand1. FillLoadOption (inherited from Gets or sets the LoadOption that DataAdapter) determines how the adapter fills the DataTablefrom the DbDataReader. *Note InsertCommand: Overloaded. connector-net-ref-mysqlclient-mysqldataadapter-insertcommand1. MissingMappingAction (inherited Determines the action to take when from DataAdapter) incoming data does not have a matching table or column. MissingSchemaAction (inherited from Determines the action to take when DataAdapter) existing DataSetschema does not match incoming data. ReturnProviderSpecificTypes Gets or sets whether the Fillmethod (inherited from DataAdapter) should return provider-specific values or common CLS-compliant values. *Note SelectCommand: Overloaded. connector-net-ref-mysqlclient-mysqldataadapter-selectcommand1. Site (inherited from Component) Gets or sets the ISite of the Component. TableMappings (inherited from Gets a collection that provides the DataAdapter) master mapping between a source table and a DataTable. UpdateBatchSize (inherited from Gets or sets a value that enables DbDataAdapter) or disables batch processing support, and specifies the number of commands that can be executed in a batch. *Note UpdateCommand: Overloaded. connector-net-ref-mysqlclient-mysqldataadapter-updatecommand1. *Public Instance Methods* Public instance methods in the MySqlDataAdapter class. CreateObjRef (inherited from Creates an object that contains all MarshalByRefObject) the relevant information required to generate a proxy used to communicate with a remote object. Dispose (inherited from Component) Releases all resources used by the Component. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. Fill (inherited from DbDataAdapter) Overloaded. Adds or refreshes rows in the DataSetto match those in the data source using the DataSetname, and creates a DataTablenamed "Table." FillSchema (inherited from Overloaded. Configures the schema DbDataAdapter) of the specified DataTablebased on the specified SchemaType. GetFillParameters (inherited from Gets the parameters set by the user DbDataAdapter) when executing an SQL *Note `SELECT': select. statement. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetLifetimeService (inherited from Retrieves the current lifetime MarshalByRefObject) service object that controls the lifetime policy for this instance. GetType (inherited from Object) Gets the Type of the current instance. InitializeLifetimeService Obtains a lifetime service object (inherited from MarshalByRefObject) to control the lifetime policy for this instance. ResetFillLoadOption (inherited from Resets FillLoadOptionto its default DataAdapter) state and causes Fillto honor AcceptChangesDuringFill. ShouldSerializeAcceptChangesDuringFillDetermines whether the (inherited from DataAdapter) AcceptChangesDuringFillproperty should be persisted. ShouldSerializeFillLoadOption Determines whether the (inherited from DataAdapter) FillLoadOptionproperty should be persisted. ToString (inherited from Component) Returns a String containing the name of the Component, if any. This method should not be overridden. Update (inherited from Overloaded. Calls the respective DbDataAdapter) INSERT, UPDATE, or DELETE statements for each inserted, updated, or deleted row in the specified DataSet. *Public Instance Events* Public instance methods in the MySqlDataAdapter class. Disposed (inherited from Component) Adds an event handler to listen to the Disposed event on the component. FillError (inherited from Returned when an error occurs DataAdapter) during a fill operation. *Note RowUpdated: Occurs during Update after a connector-net-ref-mysqlclient-mysqldataadapter-rowupdated.command is executed against the data source. The attempt to update is made, so the event fires. *Note RowUpdating: Occurs during Update before a connector-net-ref-mysqlclient-mysqldataadapter-rowupdating.command is executed against the data source. The attempt to update is made, so the event fires. *Protected Internal Instance Properties* Protected internal instance properties in the MySqlDataAdapter class. FillCommandBehavior (inherited from Gets or sets the behavior of the DbDataAdapter) command used to fill the data adapter. *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapterconstructor, Next: connector-net-ref-mysqlclient-mysqldataadapter-deletecommand1, Prev: connector-net-ref-mysqlclient-mysqldataadaptermembers, Up: connector-net-ref-mysqlclient-mysqldataadaptermembers 21.2.9.168 `MySqlDataAdapter' Constructor ......................................... * Menu: * connector-net-ref-mysqlclient-mysqldataadapterconstructor1:: `MySqlDataAdapter' Constructor * connector-net-ref-mysqlclient-mysqldataadapterconstructor2:: `MySqlDataAdapter' Constructor * connector-net-ref-mysqlclient-mysqldataadapterconstructor3:: `MySqlDataAdapter' Constructor * connector-net-ref-mysqlclient-mysqldataadapterconstructor4:: `MySqlDataAdapter' Constructor Initializes a new instance of the *Note MySqlDataAdapter: connector-net-ref-mysqlclient-mysqldataadapter. class. *Overload List* Initializes a new instance of the *Note MySqlDataAdapter: connector-net-ref-mysqlclient-mysqldataadapter. class. * *Note public MySqlDataAdapter();: connector-net-ref-mysqlclient-mysqldataadapterconstructor1. * *Note public MySqlDataAdapter(MySqlCommand);: connector-net-ref-mysqlclient-mysqldataadapterconstructor2. * *Note public MySqlDataAdapter(string: (MySqlConnection);)connector-net-ref-mysqlclient-mysqldataadapterconstructor3. * *Note public MySqlDataAdapter(string: (string);)connector-net-ref-mysqlclient-mysqldataadapterconstructor4. *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapterconstructor1, Next: connector-net-ref-mysqlclient-mysqldataadapterconstructor2, Prev: connector-net-ref-mysqlclient-mysqldataadapterconstructor, Up: connector-net-ref-mysqlclient-mysqldataadapterconstructor 21.2.9.169 `MySqlDataAdapter' Constructor ......................................... Initializes a new instance of the *Note MySqlDataAdapter: connector-net-ref-mysqlclient-mysqldataadapter. class. *Syntax: Visual Basic* Overloads Public Sub New() *Syntax: C#* public MySqlDataAdapter(); *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlDataAdapter Constructor Overload List: connector-net-ref-mysqlclient-mysqldataadapterconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapterconstructor2, Next: connector-net-ref-mysqlclient-mysqldataadapterconstructor3, Prev: connector-net-ref-mysqlclient-mysqldataadapterconstructor1, Up: connector-net-ref-mysqlclient-mysqldataadapterconstructor 21.2.9.170 `MySqlDataAdapter' Constructor ......................................... *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal selectCommand As MySqlCommand _ ) *Syntax: C#* public MySqlDataAdapter( MySqlCommandselectCommand ); *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlDataAdapter Constructor Overload List: connector-net-ref-mysqlclient-mysqldataadapterconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapterconstructor3, Next: connector-net-ref-mysqlclient-mysqldataadapterconstructor4, Prev: connector-net-ref-mysqlclient-mysqldataadapterconstructor2, Up: connector-net-ref-mysqlclient-mysqldataadapterconstructor 21.2.9.171 `MySqlDataAdapter' Constructor ......................................... *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal selectCommandText As String, _ ByVal connection As MySqlConnection _ ) *Syntax: C#* public MySqlDataAdapter( stringselectCommandText, MySqlConnectionconnection ); *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlDataAdapter Constructor Overload List: connector-net-ref-mysqlclient-mysqldataadapterconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapterconstructor4, Prev: connector-net-ref-mysqlclient-mysqldataadapterconstructor3, Up: connector-net-ref-mysqlclient-mysqldataadapterconstructor 21.2.9.172 `MySqlDataAdapter' Constructor ......................................... *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal selectCommandText As String, _ ByVal selectConnString As String _ ) *Syntax: C#* public MySqlDataAdapter( stringselectCommandText, stringselectConnString ); *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlDataAdapter Constructor Overload List: connector-net-ref-mysqlclient-mysqldataadapterconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapter-deletecommand1, Next: connector-net-ref-mysqlclient-mysqldataadapter-insertcommand1, Prev: connector-net-ref-mysqlclient-mysqldataadapterconstructor, Up: connector-net-ref-mysqlclient-mysqldataadaptermembers 21.2.9.173 DeleteCommand Property ................................. *Syntax: Visual Basic* Overloads Public Property DeleteCommand As MySqlCommand *Syntax: C#* new public MySqlCommand DeleteCommand {get; set;} *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapter-insertcommand1, Next: connector-net-ref-mysqlclient-mysqldataadapter-selectcommand1, Prev: connector-net-ref-mysqlclient-mysqldataadapter-deletecommand1, Up: connector-net-ref-mysqlclient-mysqldataadaptermembers 21.2.9.174 InsertCommand Property ................................. *Syntax: Visual Basic* Overloads Public Property InsertCommand As MySqlCommand *Syntax: C#* new public MySqlCommand InsertCommand {get; set;} *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapter-selectcommand1, Next: connector-net-ref-mysqlclient-mysqldataadapter-updatecommand1, Prev: connector-net-ref-mysqlclient-mysqldataadapter-insertcommand1, Up: connector-net-ref-mysqlclient-mysqldataadaptermembers 21.2.9.175 SelectCommand Property ................................. *Syntax: Visual Basic* Overloads Public Property SelectCommand As MySqlCommand *Syntax: C#* new public MySqlCommand SelectCommand {get; set;} *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapter-updatecommand1, Next: connector-net-ref-mysqlclient-mysqldataadapter-rowupdated, Prev: connector-net-ref-mysqlclient-mysqldataadapter-selectcommand1, Up: connector-net-ref-mysqlclient-mysqldataadaptermembers 21.2.9.176 UpdateCommand Property ................................. *Syntax: Visual Basic* Overloads Public Property UpdateCommand As MySqlCommand *Syntax: C#* new public MySqlCommand UpdateCommand {get; set;} *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapter-rowupdated, Next: connector-net-ref-mysqlclient-mysqldataadapter-rowupdating, Prev: connector-net-ref-mysqlclient-mysqldataadapter-updatecommand1, Up: connector-net-ref-mysqlclient-mysqldataadaptermembers 21.2.9.177 `MySqlDataAdapter.RowUpdated' Event .............................................. * Menu: * connector-net-ref-mysqlclient-mysqlrowupdatedeventhandler:: `MySqlRowUpdatedEventHandler' Delegate Occurs during Update after a command is executed against the data source. The attempt to update is made, so the event fires. *Syntax: Visual Basic* Public Event RowUpdated As MySqlRowUpdatedEventHandler *Syntax: C#* public event MySqlRowUpdatedEventHandler RowUpdated; *Event Data* The event handler receives an argument of type *Note MySqlRowUpdatedEventArgs: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs. containing data related to this event. The following `MySqlRowUpdatedEventArgsproperties' provide information specific to this event. Members of the MySqlRowUpdatedEventArgsproperties enumeration. *Property* *Description* *Note Command: Gets or sets the MySqlCommand connector-net-ref-mysqlclient-mysqlrowupdatedeventargs-command1.executed when Update is called. Errors Gets any errors generated by the .NET Framework data provider when the Commandwas executed. RecordsAffected Gets the number of rows changed, inserted, or deleted by execution of the SQL statement. Row Gets the DataRowsent through an Update. RowCount Gets the number of rows processed in a batch of updated records. StatementType Gets the type of SQL statement executed. Status Gets the UpdateStatus of the Commandproperty. TableMapping Gets the DataTableMappingsent through an Update. *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlrowupdatedeventhandler, Prev: connector-net-ref-mysqlclient-mysqldataadapter-rowupdated, Up: connector-net-ref-mysqlclient-mysqldataadapter-rowupdated 21.2.9.178 `MySqlRowUpdatedEventHandler' Delegate ................................................. * Menu: * connector-net-ref-mysqlclient-mysqlrowupdatedeventargs:: `MySqlRowUpdatedEventArgs' Class Represents the method that will handle the RowUpdatedevent of a *Note MySqlDataAdapter: connector-net-ref-mysqlclient-mysqldataadapter. *Syntax: Visual Basic* Public Delegate Sub MySqlRowUpdatedEventHandler( _ ByVal sender As Object, _ ByVal e As MySqlRowUpdatedEventArgs _ ) *Syntax: C#* public delegate void MySqlRowUpdatedEventHandler( objectsender, MySqlRowUpdatedEventArgs ); *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs, Prev: connector-net-ref-mysqlclient-mysqlrowupdatedeventhandler, Up: connector-net-ref-mysqlclient-mysqlrowupdatedeventhandler 21.2.9.179 `MySqlRowUpdatedEventArgs' Class ........................................... * Menu: * connector-net-ref-mysqlclient-mysqlrowupdatedeventargsmembers:: `MySqlRowUpdatedEventArgs' Members Provides data for the RowUpdated event. This class cannot be inherited. For a list of all members of this type, see *Note MySqlRowUpdatedEventArgs Members: connector-net-ref-mysqlclient-mysqlrowupdatedeventargsmembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlRowUpdatedEventArgs_ Inherits RowUpdatedEventArgs *Syntax: C#* public sealed class MySqlRowUpdatedEventArgs : RowUpdatedEventArgs *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlRowUpdatedEventArgs Members: connector-net-ref-mysqlclient-mysqlrowupdatedeventargsmembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlrowupdatedeventargsmembers, Prev: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs, Up: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs 21.2.9.180 `MySqlRowUpdatedEventArgs' Members ............................................. * Menu: * connector-net-ref-mysqlclient-mysqlrowupdatedeventargsconstructor:: `MySqlRowUpdatedEventArgs' Constructor * connector-net-ref-mysqlclient-mysqlrowupdatedeventargs-command1:: Command Property *Note MySqlRowUpdatedEventArgs overview: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs. *Public Instance Constructors* Public instance constructors in the MySqlRowUpdatedEventArgs class. *Note MySqlRowUpdatedEventArgs Initializes a new instance of the Constructor: MySqlRowUpdatedEventArgs class. connector-net-ref-mysqlclient-mysqlrowupdatedeventargsconstructor. *Public Instance Properties* Public instance properties in the MySqlRowUpdatedEventArgs class. *Note Command: Overloaded. Gets or sets the connector-net-ref-mysqlclient-mysqlrowupdatedeventargs-command1.MySqlCommand executed when Update is called. Errors (inherited from Gets any errors generated by the RowUpdatedEventArgs) .NET Framework data provider when the Commandwas executed. RecordsAffected (inherited from Gets the number of rows changed, RowUpdatedEventArgs) inserted, or deleted by execution of the SQL statement. Row (inherited from Gets the DataRowsent through an RowUpdatedEventArgs) Update. RowCount (inherited from Gets the number of rows processed RowUpdatedEventArgs) in a batch of updated records. StatementType (inherited from Gets the type of SQL statement RowUpdatedEventArgs) executed. Status (inherited from Gets the UpdateStatus of the RowUpdatedEventArgs) Commandproperty. TableMapping (inherited from Gets the DataTableMappingsent RowUpdatedEventArgs) through an Update. *Public Instance Methods* Public instance methods in the MySqlRowUpdatedEventArgs class. CopyToRows (inherited from Overloaded. Copies references to RowUpdatedEventArgs) the modified rows into the provided array. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetType (inherited from Object) Gets the Type of the current instance. ToString (inherited from Object) Returns a String that represents the current Object. *See Also* *Note MySqlRowUpdatedEventArgs Class: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlrowupdatedeventargsconstructor, Next: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs-command1, Prev: connector-net-ref-mysqlclient-mysqlrowupdatedeventargsmembers, Up: connector-net-ref-mysqlclient-mysqlrowupdatedeventargsmembers 21.2.9.181 `MySqlRowUpdatedEventArgs' Constructor ................................................. Initializes a new instance of the MySqlRowUpdatedEventArgs class. *Syntax: Visual Basic* Public Sub New( _ ByVal row As DataRow, _ ByVal command As IDbCommand, _ ByVal statementType As StatementType, _ ByVal tableMapping As DataTableMapping _ ) *Syntax: C#* public MySqlRowUpdatedEventArgs( DataRowrow, IDbCommandcommand, StatementTypestatementType, DataTableMappingtableMapping ); *Parameters* * `row': The DataRowsent through an Update. * `command': The IDbCommand executed when Update is called. * `statementType': One of the StatementTypevalues that specifies the type of query executed. * `tableMapping': The DataTableMapping sent through an Update. *See Also* *Note MySqlRowUpdatedEventArgs Class: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs-command1, Prev: connector-net-ref-mysqlclient-mysqlrowupdatedeventargsconstructor, Up: connector-net-ref-mysqlclient-mysqlrowupdatedeventargsmembers 21.2.9.182 Command Property ........................... Gets or sets the MySqlCommand executed when Update is called. *Syntax: Visual Basic* Overloads Public ReadOnly Property Command As MySqlCommand *Syntax: C#* new public MySqlCommand Command {get;} *See Also* *Note MySqlRowUpdatedEventArgs Class: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqldataadapter-rowupdating, Prev: connector-net-ref-mysqlclient-mysqldataadapter-rowupdated, Up: connector-net-ref-mysqlclient-mysqldataadaptermembers 21.2.9.183 `MySqlDataAdapter.RowUpdating' Event ............................................... * Menu: * connector-net-ref-mysqlclient-mysqlrowupdatingeventhandler:: `MySqlRowUpdatingEventHandler' Delegate Occurs during Update before a command is executed against the data source. The attempt to update is made, so the event fires. *Syntax: Visual Basic* Public Event RowUpdating As MySqlRowUpdatingEventHandler *Syntax: C#* public event MySqlRowUpdatingEventHandler RowUpdating; *Event Data* The event handler receives an argument of type *Note MySqlRowUpdatingEventArgs: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs. containing data related to this event. The following `MySqlRowUpdatingEventArgsproperties' provide information specific to this event. Members of the MySqlRowUpdatingEventArgsproperties enumeration. *Property* *Description* *Note Command: Gets or sets the MySqlCommand to connector-net-ref-mysqlclient-mysqlrowupdatingeventargs-command1.execute when performing the Update. Errors Gets any errors generated by the .NET Framework data provider when the Command executes. Row Gets the DataRow that will be sent to the server as part of an insert, update, or delete operation. StatementType Gets the type of SQL statement to execute. Status Gets or sets the UpdateStatus of the Commandproperty. TableMapping Gets the DataTableMapping to send through the Update. *See Also* *Note MySqlDataAdapter Class: connector-net-ref-mysqlclient-mysqldataadapter, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlrowupdatingeventhandler, Prev: connector-net-ref-mysqlclient-mysqldataadapter-rowupdating, Up: connector-net-ref-mysqlclient-mysqldataadapter-rowupdating 21.2.9.184 `MySqlRowUpdatingEventHandler' Delegate .................................................. * Menu: * connector-net-ref-mysqlclient-mysqlrowupdatingeventargs:: `MySqlRowUpdatingEventArgs' Class Represents the method that will handle the RowUpdatingevent of a *Note MySqlDataAdapter: connector-net-ref-mysqlclient-mysqldataadapter. *Syntax: Visual Basic* Public Delegate Sub MySqlRowUpdatingEventHandler( _ ByVal sender As Object, _ ByVal e As MySqlRowUpdatingEventArgs _ ) *Syntax: C#* public delegate void MySqlRowUpdatingEventHandler( objectsender, MySqlRowUpdatingEventArgs ); *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs, Prev: connector-net-ref-mysqlclient-mysqlrowupdatingeventhandler, Up: connector-net-ref-mysqlclient-mysqlrowupdatingeventhandler 21.2.9.185 `MySqlRowUpdatingEventArgs' Class ............................................ * Menu: * connector-net-ref-mysqlclient-mysqlrowupdatingeventargsmembers:: `MySqlRowUpdatingEventArgs' Members Provides data for the RowUpdating event. This class cannot be inherited. For a list of all members of this type, see *Note MySqlRowUpdatingEventArgs Members: connector-net-ref-mysqlclient-mysqlrowupdatingeventargsmembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlRowUpdatingEventArgs_ Inherits RowUpdatingEventArgs *Syntax: C#* public sealed class MySqlRowUpdatingEventArgs : RowUpdatingEventArgs *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlRowUpdatingEventArgs Members: connector-net-ref-mysqlclient-mysqlrowupdatingeventargsmembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlrowupdatingeventargsmembers, Prev: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs, Up: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs 21.2.9.186 `MySqlRowUpdatingEventArgs' Members .............................................. * Menu: * connector-net-ref-mysqlclient-mysqlrowupdatingeventargsconstructor:: `MySqlRowUpdatingEventArgs' Constructor * connector-net-ref-mysqlclient-mysqlrowupdatingeventargs-command1:: Command Property *Note MySqlRowUpdatingEventArgs overview: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs. *Public Instance Constructors* Public instance constructors in the MySqlRowUpdatingEventArgs class. *Note MySqlRowUpdatingEventArgs Initializes a new instance of the Constructor: MySqlRowUpdatingEventArgs class. connector-net-ref-mysqlclient-mysqlrowupdatingeventargsconstructor. *Public Instance Properties* Public instance properties in the MySqlRowUpdatingEventArgs class. *Note Command: Overloaded. Gets or sets the connector-net-ref-mysqlclient-mysqlrowupdatingeventargs-command1.MySqlCommand to execute when performing the Update. Errors (inherited from Gets any errors generated by the RowUpdatingEventArgs) .NET Framework data provider when the Command executes. Row (inherited from Gets the DataRow that will be sent RowUpdatingEventArgs) to the server as part of an insert, update, or delete operation. StatementType (inherited from Gets the type of SQL statement to RowUpdatingEventArgs) execute. Status (inherited from Gets or sets the UpdateStatus of RowUpdatingEventArgs) the Commandproperty. TableMapping (inherited from Gets the DataTableMapping to send RowUpdatingEventArgs) through the Update. *Public Instance Methods* Public instance methods in the MySqlRowUpdatingEventArgs class. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetType (inherited from Object) Gets the Type of the current instance. ToString (inherited from Object) Returns a String that represents the current Object. *See Also* *Note MySqlRowUpdatingEventArgs Class: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlrowupdatingeventargsconstructor, Next: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs-command1, Prev: connector-net-ref-mysqlclient-mysqlrowupdatingeventargsmembers, Up: connector-net-ref-mysqlclient-mysqlrowupdatingeventargsmembers 21.2.9.187 `MySqlRowUpdatingEventArgs' Constructor .................................................. Initializes a new instance of the MySqlRowUpdatingEventArgs class. *Syntax: Visual Basic* Public Sub New( _ ByVal row As DataRow, _ ByVal command As IDbCommand, _ ByVal statementType As StatementType, _ ByVal tableMapping As DataTableMapping _ ) *Syntax: C#* public MySqlRowUpdatingEventArgs( DataRowrow, IDbCommandcommand, StatementTypestatementType, DataTableMappingtableMapping ); *Parameters* * `row': The DataRowto Update. * `command': The IDbCommandto execute during Update. * `statementType': One of the StatementTypevalues that specifies the type of query executed. * `tableMapping': The DataTableMappingsent through an Update. *See Also* *Note MySqlRowUpdatingEventArgs Class: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs-command1, Prev: connector-net-ref-mysqlclient-mysqlrowupdatingeventargsconstructor, Up: connector-net-ref-mysqlclient-mysqlrowupdatingeventargsmembers 21.2.9.188 Command Property ........................... Gets or sets the MySqlCommand to execute when performing the Update. *Syntax: Visual Basic* Overloads Public Property Command As MySqlCommand *Syntax: C#* new public MySqlCommand Command {get; set;} *See Also* *Note MySqlRowUpdatingEventArgs Class: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor4, Next: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor2, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor3, Up: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor 21.2.9.189 `MySqlCommandBuilder' Constructor ............................................ *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal adapter As MySqlDataAdapter, _ ByVal lastOneWins As Boolean _ ) *Syntax: C#* public MySqlCommandBuilder( MySqlDataAdapteradapter, boollastOneWins ); *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommandBuilder Constructor Overload List: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor2, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor4, Up: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor 21.2.9.190 `MySqlCommandBuilder' Constructor ............................................ *Syntax: Visual Basic* Overloads Public Sub New( _ ByVal lastOneWins As Boolean _ ) *Syntax: C#* public MySqlCommandBuilder( boollastOneWins ); *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlCommandBuilder Constructor Overload List: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-dataadapter, Next: connector-net-ref-mysqlclient-mysqlcommandbuilder-quoteprefix, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor, Up: connector-net-ref-mysqlclient-mysqlcommandbuildermembers 21.2.9.191 DataAdapter Property ............................... *Syntax: Visual Basic* Public Property DataAdapter As MySqlDataAdapter *Syntax: C#* public MySqlDataAdapter DataAdapter {get; set;} *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-quoteprefix, Next: connector-net-ref-mysqlclient-mysqlcommandbuilder-quotesuffix, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder-dataadapter, Up: connector-net-ref-mysqlclient-mysqlcommandbuildermembers 21.2.9.192 QuotePrefix Property ............................... *Syntax: Visual Basic* Public Property QuotePrefix As String *Syntax: C#* public string QuotePrefix {get; set;} *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-quotesuffix, Next: connector-net-ref-mysqlclient-mysqlcommandbuilder-getdeletecommand, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder-quoteprefix, Up: connector-net-ref-mysqlclient-mysqlcommandbuildermembers 21.2.9.193 QuoteSuffix Property ............................... *Syntax: Visual Basic* Public Property QuoteSuffix As String *Syntax: C#* public string QuoteSuffix {get; set;} *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-getdeletecommand, Next: connector-net-ref-mysqlclient-mysqlcommandbuilder-getinsertcommand, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder-quotesuffix, Up: connector-net-ref-mysqlclient-mysqlcommandbuildermembers 21.2.9.194 `MySqlCommandBuilder.GetDeleteCommand' Method ........................................................ *Syntax: Visual Basic* Public Function GetDeleteCommand() As MySqlCommand *Syntax: C#* public MySqlCommand GetDeleteCommand(); *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-getinsertcommand, Next: connector-net-ref-mysqlclient-mysqlcommandbuilder-getupdatecommand, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder-getdeletecommand, Up: connector-net-ref-mysqlclient-mysqlcommandbuildermembers 21.2.9.195 `MySqlCommandBuilder.GetInsertCommand' Method ........................................................ *Syntax: Visual Basic* Public Function GetInsertCommand() As MySqlCommand *Syntax: C#* public MySqlCommand GetInsertCommand(); *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-getupdatecommand, Next: connector-net-ref-mysqlclient-mysqlcommandbuilder-refreshschema, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder-getinsertcommand, Up: connector-net-ref-mysqlclient-mysqlcommandbuildermembers 21.2.9.196 `MySqlCommandBuilder.GetUpdateCommand' Method ........................................................ *Syntax: Visual Basic* Public Function GetUpdateCommand() As MySqlCommand *Syntax: C#* public MySqlCommand GetUpdateCommand(); *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-refreshschema, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder-getupdatecommand, Up: connector-net-ref-mysqlclient-mysqlcommandbuildermembers 21.2.9.197 `MySqlCommandBuilder.RefreshSchema' Method ..................................................... *Syntax: Visual Basic* Public Sub RefreshSchema() *Syntax: C#* public void RefreshSchema(); *See Also* *Note MySqlCommandBuilder Class: connector-net-ref-mysqlclient-mysqlcommandbuilder, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlexception, Next: connector-net-ref-mysqlclient-mysqlhelper, Prev: connector-net-ref-mysqlclient-mysqlcommandbuilder, Up: connector-net-ref-mysqlclient 21.2.9.198 `MySqlException' Class ................................. * Menu: * connector-net-ref-mysqlclient-mysqlexceptionmembers:: `MySqlException' Members The exception that is thrown when MySQL returns an error. This class cannot be inherited. For a list of all members of this type, see *Note MySqlException Members: connector-net-ref-mysqlclient-mysqlexceptionmembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlException_ Inherits SystemException *Syntax: C#* public sealed class MySqlException : SystemException *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlException Members: connector-net-ref-mysqlclient-mysqlexceptionmembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlexceptionmembers, Prev: connector-net-ref-mysqlclient-mysqlexception, Up: connector-net-ref-mysqlclient-mysqlexception 21.2.9.199 `MySqlException' Members ................................... * Menu: * connector-net-ref-mysqlclient-mysqlexception-number:: Number Property *Note MySqlException overview: connector-net-ref-mysqlclient-mysqlexception. *Public Instance Properties* Public instance properties in the MySqlException class. Data (inherited from Exception) Gets a collection of key/value pairs that provide additional, user-defined information about the exception. HelpLink (inherited from Exception) Gets or sets a link to the help file associated with this exception. InnerException (inherited from Gets the `Exceptioninstance' that Exception) caused the current exception. Message (inherited from Exception) Gets a message that describes the current exception. *Note Number: Gets a number that identifies the connector-net-ref-mysqlclient-mysqlexception-number.type of error. This number corresponds to the error numbers given in *Note error-messages-server::. Source (inherited from Exception) Gets or sets the name of the application or the object that causes the error. StackTrace (inherited from Gets a string representation of the Exception) frames on the call stack at the time the current exception was thrown. TargetSite (inherited from Gets the method that throws the Exception) current exception. *Public Instance Methods* Public instance methods in the MySqlException class. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetBaseException (inherited from When overridden in a derived class, Exception) returns the Exception that is the root cause of one or more subsequent exceptions. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetObjectData (inherited from When overridden in a derived class, Exception) sets the SerializationInfo with information about the exception. GetType (inherited from Exception) Gets the runtime type of the current instance. ToString (inherited from Exception) Creates and returns a string representation of the current exception. *See Also* *Note MySqlException Class: connector-net-ref-mysqlclient-mysqlexception, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlexception-number, Prev: connector-net-ref-mysqlclient-mysqlexceptionmembers, Up: connector-net-ref-mysqlclient-mysqlexceptionmembers 21.2.9.200 Number Property .......................... Gets a number that identifies the type of error. *Syntax: Visual Basic* Public ReadOnly Property Number As Integer *Syntax: C#* public int Number {get;} *See Also* *Note MySqlException Class: connector-net-ref-mysqlclient-mysqlexception, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper, Next: connector-net-ref-mysqlclient-mysqlerrorcode, Prev: connector-net-ref-mysqlclient-mysqlexception, Up: connector-net-ref-mysqlclient 21.2.9.201 `MySqlHelper' Class .............................. * Menu: * connector-net-ref-mysqlclient-mysqlhelpermembers:: `MySqlHelper' Members Helper class that makes it easier to work with the provider. For a list of all members of this type, see *Note MySqlHelper Members: connector-net-ref-mysqlclient-mysqlhelpermembers . *Syntax: Visual Basic* NotInheritable Public Class MySqlHelper *Syntax: C#* public sealed class MySqlHelper *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlHelper Members: connector-net-ref-mysqlclient-mysqlhelpermembers, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelpermembers, Prev: connector-net-ref-mysqlclient-mysqlhelper, Up: connector-net-ref-mysqlclient-mysqlhelper 21.2.9.202 `MySqlHelper' Members ................................ * Menu: * connector-net-ref-mysqlclient-mysqlhelper-executedatarow:: `MySqlHelper.ExecuteDataRow' Method * connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads:: ExecuteDataset Method * connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads:: ExecuteNonQuery Method * connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads:: ExecuteReader Method * connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads:: ExecuteScalar Method * connector-net-ref-mysqlclient-mysqlhelper-updatedataset:: `MySqlHelper.UpdateDataSet' Method *Note MySqlHelper overview: connector-net-ref-mysqlclient-mysqlhelper. *Public Static (Shared) Methods* Public static (shared) methods in the MySqlHelper class. *Note ExecuteDataRow: Executes a single SQL statement and connector-net-ref-mysqlclient-mysqlhelper-executedatarow.returns the first row of the resultset. A new MySqlConnection object is created, opened, and closed during this method. *Note ExecuteDataset: Overloaded. Executes a single SQL connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads.statement and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method. *Note ExecuteNonQuery: Overloaded. Executes a single connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads.command against a MySQL database. The *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. is assumed to be open when the method is called and remains open after the method completes. *Note ExecuteReader: Overloaded. Executes a single connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads.command against a MySQL database. *Note ExecuteScalar: Overloaded. Execute a single connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads.command against a MySQL database. *Note UpdateDataSet: Updates the given table with data connector-net-ref-mysqlclient-mysqlhelper-updatedataset.from the given DataSet *Public Instance Methods* Public instance methods in the MySqlHelper class. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetType (inherited from Object) Gets the Type of the current instance. ToString (inherited from Object) Returns a String that represents the current Object. *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executedatarow, Next: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads, Prev: connector-net-ref-mysqlclient-mysqlhelpermembers, Up: connector-net-ref-mysqlclient-mysqlhelpermembers 21.2.9.203 `MySqlHelper.ExecuteDataRow' Method .............................................. Executes a single SQL statement and returns the first row of the resultset. A new MySqlConnection object is created, opened, and closed during this method. *Syntax: Visual Basic* Public Shared Function ExecuteDataRow( _ ByVal connectionString As String, _ ByVal commandText As String, _ ParamArray parms As MySqlParameter() _ ) As DataRow *Syntax: C#* public static DataRow ExecuteDataRow( stringconnectionString, stringcommandText, params MySqlParameter[]parms ); *Parameters* * `connectionString': Settings to be used for the connection * `commandText': Command to execute * `parms': Parameters to use for the command *Return Value* DataRow containing the first row of the resultset *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads, Next: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads, Prev: connector-net-ref-mysqlclient-mysqlhelper-executedatarow, Up: connector-net-ref-mysqlclient-mysqlhelpermembers 21.2.9.204 ExecuteDataset Method ................................ * Menu: * connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-3:: `MySqlHelper.ExecuteDataset' Method * connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-4:: `MySqlHelper.ExecuteDataset' Method * connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-1:: `MySqlHelper.ExecuteDataset' Method * connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-2:: `MySqlHelper.ExecuteDataset' Method Executes a single SQL statement and returns the resultset in a DataSet. The state of the *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object remains unchanged after execution of this method. *Overload List* Executes a single SQL statement and returns the resultset in a DataSet. The state of the *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object remains unchanged after execution of this method. * *Note public static DataSet ExecuteDataset(MySqlConnection: (string);)connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-3. Executes a single SQL statement and returns the resultset in a DataSet. The state of the *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object remains unchanged after execution of this method. * *Note public static DataSet ExecuteDataset(MySqlConnection: (string)connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-4. Executes a single SQL statement and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method. * *Note public static DataSet ExecuteDataset(string: (string);)connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-1. Executes a single SQL statement and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method. * *Note public static DataSet ExecuteDataset(string: (string)connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-2. *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-3, Next: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-4, Prev: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads, Up: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads 21.2.9.205 `MySqlHelper.ExecuteDataset' Method .............................................. Executes a single SQL statement and returns the resultset in a DataSet. The state of the *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object remains unchanged after execution of this method. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteDataset( _ ByVal connection As MySqlConnection, _ ByVal commandText As String _ ) As DataSet *Syntax: C#* public static DataSet ExecuteDataset( MySqlConnectionconnection, stringcommandText ); *Parameters* * `connection': *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object to use * `commandText': Command to execute *Return Value* DataSetcontaining the resultset *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteDataset Overload List: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-4, Next: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-1, Prev: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-3, Up: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads 21.2.9.206 `MySqlHelper.ExecuteDataset' Method .............................................. Executes a single SQL statement and returns the resultset in a DataSet. The state of the *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object remains unchanged after execution of this method. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteDataset( _ ByVal connection As MySqlConnection, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As DataSet *Syntax: C#* public static DataSet ExecuteDataset( MySqlConnectionconnection, stringcommandText, params MySqlParameter[]commandParameters ); *Parameters* * `connection': *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object to use * `commandText': Command to execute * `commandParameters': Parameters to use for the command *Return Value* DataSetcontaining the resultset *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteDataset Overload List: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-1, Next: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-2, Prev: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-4, Up: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads 21.2.9.207 `MySqlHelper.ExecuteDataset' Method .............................................. Executes a single SQL statement and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteDataset( _ ByVal connectionString As String, _ ByVal commandText As String _ ) As DataSet *Syntax: C#* public static DataSet ExecuteDataset( stringconnectionString, stringcommandText ); *Parameters* * `connectionString': Settings to be used for the connection * `commandText': Command to execute *Return Value* DataSetcontaining the resultset *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteDataset Overload List: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-2, Prev: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-1, Up: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads 21.2.9.208 `MySqlHelper.ExecuteDataset' Method .............................................. Executes a single SQL statement and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteDataset( _ ByVal connectionString As String, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As DataSet *Syntax: C#* public static DataSet ExecuteDataset( stringconnectionString, stringcommandText, params MySqlParameter[]commandParameters ); *Parameters* * `connectionString': Settings to be used for the connection * `commandText': Command to execute * `commandParameters': Parameters to use for the command *Return Value* DataSetcontaining the resultset *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteDataset Overload List: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads, Next: connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads, Prev: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads, Up: connector-net-ref-mysqlclient-mysqlhelpermembers 21.2.9.209 ExecuteNonQuery Method ................................. * Menu: * connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overload-1:: `MySqlHelper.ExecuteNonQuery' Method * connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overload-2:: `MySqlHelper.ExecuteNonQuery' Method Executes a single command against a MySQL database. The *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. is assumed to be open when the method is called and remains open after the method completes. *Overload List* Executes a single command against a MySQL database. The *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. is assumed to be open when the method is called and remains open after the method completes. * *Note public static int ExecuteNonQuery(MySqlConnection: (string)connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overload-1. Executes a single command against a MySQL database. A new *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. is created using the *Note ConnectionString: connector-net-ref-mysqlclient-mysqlconnection-connectionstring. given. * *Note public static int ExecuteNonQuery(string: (string)connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overload-2. *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overload-1, Next: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overload-2, Prev: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads, Up: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads 21.2.9.210 `MySqlHelper.ExecuteNonQuery' Method ............................................... Executes a single command against a MySQL database. The *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. is assumed to be open when the method is called and remains open after the method completes. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteNonQuery( _ ByVal connection As MySqlConnection, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As Integer *Syntax: C#* public static int ExecuteNonQuery( MySqlConnectionconnection, stringcommandText, params MySqlParameter[]commandParameters ); *Parameters* * `connection': *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object to use * `commandText': SQL statement to be executed * `commandParameters': Array of *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. objects to use with the command. *Return Value* *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteNonQuery Overload List: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overload-2, Prev: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overload-1, Up: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads 21.2.9.211 `MySqlHelper.ExecuteNonQuery' Method ............................................... Executes a single command against a MySQL database. A new *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. is created using the *Note ConnectionString: connector-net-ref-mysqlclient-mysqlconnection-connectionstring. given. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteNonQuery( _ ByVal connectionString As String, _ ByVal commandText As String, _ ParamArray parms As MySqlParameter() _ ) As Integer *Syntax: C#* public static int ExecuteNonQuery( stringconnectionString, stringcommandText, params MySqlParameter[]parms ); *Parameters* * `connectionString': *Note ConnectionString: connector-net-ref-mysqlclient-mysqlconnection-connectionstring. to use * `commandText': SQL statement to be executed * `parms': Array of *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. objects to use with the command. *Return Value* *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteNonQuery Overload List: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads, Next: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads, Prev: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads, Up: connector-net-ref-mysqlclient-mysqlhelpermembers 21.2.9.212 ExecuteReader Method ............................... * Menu: * connector-net-ref-mysqlclient-mysqlhelper-executereader-overload-1:: `MySqlHelper.ExecuteReader' Method * connector-net-ref-mysqlclient-mysqlhelper-executereader-overload-2:: `MySqlHelper.ExecuteReader' Method Executes a single command against a MySQL database. *Overload List* Executes a single command against a MySQL database. * *Note public static MySqlDataReader ExecuteReader(string: (string);)connector-net-ref-mysqlclient-mysqlhelper-executereader-overload-1. Executes a single command against a MySQL database. * *Note public static MySqlDataReader ExecuteReader(string: (string)connector-net-ref-mysqlclient-mysqlhelper-executereader-overload-2. *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executereader-overload-1, Next: connector-net-ref-mysqlclient-mysqlhelper-executereader-overload-2, Prev: connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads, Up: connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads 21.2.9.213 `MySqlHelper.ExecuteReader' Method ............................................. Executes a single command against a MySQL database. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteReader( _ ByVal connectionString As String, _ ByVal commandText As String _ ) As MySqlDataReader *Syntax: C#* public static MySqlDataReader ExecuteReader( stringconnectionString, stringcommandText ); *Parameters* * `connectionString': Settings to use for this command * `commandText': Command text to use *Return Value* *Note MySqlDataReader: connector-net-ref-mysqlclient-mysqldatareader. object ready to read the results of the command *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteReader Overload List: connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executereader-overload-2, Prev: connector-net-ref-mysqlclient-mysqlhelper-executereader-overload-1, Up: connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads 21.2.9.214 `MySqlHelper.ExecuteReader' Method ............................................. Executes a single command against a MySQL database. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteReader( _ ByVal connectionString As String, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As MySqlDataReader *Syntax: C#* public static MySqlDataReader ExecuteReader( stringconnectionString, stringcommandText, params MySqlParameter[]commandParameters ); *Parameters* * `connectionString': Settings to use for this command * `commandText': Command text to use * `commandParameters': Array of *Note MySqlParameter: connector-net-ref-mysqlclient-mysqlparameter. objects to use with the command *Return Value* *Note MySqlDataReader: connector-net-ref-mysqlclient-mysqldatareader. object ready to read the results of the command *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteReader Overload List: connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads, Next: connector-net-ref-mysqlclient-mysqlhelper-updatedataset, Prev: connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads, Up: connector-net-ref-mysqlclient-mysqlhelpermembers 21.2.9.215 ExecuteScalar Method ............................... * Menu: * connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-3:: `MySqlHelper.ExecuteScalar' Method * connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-4:: `MySqlHelper.ExecuteScalar' Method * connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-1:: `MySqlHelper.ExecuteScalar' Method * connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-2:: `MySqlHelper.ExecuteScalar' Method Execute a single command against a MySQL database. *Overload List* Execute a single command against a MySQL database. * *Note public static object ExecuteScalar(MySqlConnection: (string);)connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-3. Execute a single command against a MySQL database. * *Note public static object ExecuteScalar(MySqlConnection: (string)connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-4. Execute a single command against a MySQL database. * *Note public static object ExecuteScalar(string: (string);)connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-1. Execute a single command against a MySQL database. * *Note public static object ExecuteScalar(string: (string)connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-2. *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-3, Next: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-4, Prev: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads, Up: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads 21.2.9.216 `MySqlHelper.ExecuteScalar' Method ............................................. Execute a single command against a MySQL database. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteScalar( _ ByVal connection As MySqlConnection, _ ByVal commandText As String _ ) As Object *Syntax: C#* public static object ExecuteScalar( MySqlConnectionconnection, stringcommandText ); *Parameters* * `connection': *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object to use * `commandText': Command text to use for the command *Return Value* The first column of the first row in the result set, or a null reference if the result set is empty. *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteScalar Overload List: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-4, Next: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-1, Prev: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-3, Up: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads 21.2.9.217 `MySqlHelper.ExecuteScalar' Method ............................................. Execute a single command against a MySQL database. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteScalar( _ ByVal connection As MySqlConnection, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As Object *Syntax: C#* public static object ExecuteScalar( MySqlConnectionconnection, stringcommandText, params MySqlParameter[]commandParameters ); *Parameters* * `connection': *Note MySqlConnection: connector-net-ref-mysqlclient-mysqlconnection. object to use * `commandText': Command text to use for the command * `commandParameters': Parameters to use for the command *Return Value* The first column of the first row in the result set, or a null reference if the result set is empty. *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteScalar Overload List: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-1, Next: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-2, Prev: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-4, Up: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads 21.2.9.218 `MySqlHelper.ExecuteScalar' Method ............................................. Execute a single command against a MySQL database. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteScalar( _ ByVal connectionString As String, _ ByVal commandText As String _ ) As Object *Syntax: C#* public static object ExecuteScalar( stringconnectionString, stringcommandText ); *Parameters* * `connectionString': Settings to use for the update * `commandText': Command text to use for the update *Return Value* The first column of the first row in the result set, or a null reference if the result set is empty. *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteScalar Overload List: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-2, Prev: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-1, Up: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads 21.2.9.219 `MySqlHelper.ExecuteScalar' Method ............................................. Execute a single command against a MySQL database. *Syntax: Visual Basic* Overloads Public Shared Function ExecuteScalar( _ ByVal connectionString As String, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As Object *Syntax: C#* public static object ExecuteScalar( stringconnectionString, stringcommandText, params MySqlParameter[]commandParameters ); *Parameters* * `connectionString': Settings to use for the command * `commandText': Command text to use for the command * `commandParameters': Parameters to use for the command *Return Value* The first column of the first row in the result set, or a null reference if the result set is empty. *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient, *Note MySqlHelper.ExecuteScalar Overload List: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlhelper-updatedataset, Prev: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads, Up: connector-net-ref-mysqlclient-mysqlhelpermembers 21.2.9.220 `MySqlHelper.UpdateDataSet' Method ............................................. Updates the given table with data from the given DataSet *Syntax: Visual Basic* Public Shared Sub UpdateDataSet( _ ByVal connectionString As String, _ ByVal commandText As String, _ ByVal ds As DataSet, _ ByVal tablename As String _ ) *Syntax: C#* public static void UpdateDataSet( stringconnectionString, stringcommandText, DataSetds, stringtablename ); *Parameters* * `connectionString': Settings to use for the update * `commandText': Command text to use for the update * `ds': DataSetcontaining the new data to use in the update * `tablename': Tablename in the data set to update *See Also* *Note MySqlHelper Class: connector-net-ref-mysqlclient-mysqlhelper, *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-mysqlerrorcode, Prev: connector-net-ref-mysqlclient-mysqlhelper, Up: connector-net-ref-mysqlclient 21.2.9.221 `MySqlErrorCode' Enumeration ....................................... *Syntax: Visual Basic* Public Enum MySqlErrorCode *Syntax: C#* public enum MySqlErrorCode *Members* Members in the MySqlErrorCode enumeration. *Member Name* *Description* PacketTooLarge PasswordNotAllowed DuplicateKeyEntry HostNotPrivileged PasswordNoMatch AnonymousUser DuplicateKey KeyNotFound DuplicateKeyName *Requirements* Namespace: *Note MySql.Data.MySqlClient: connector-net-ref-mysqlclient. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySql.Data.MySqlClient Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-types, Prev: connector-net-ref-mysqlclient, Up: connector-net-ref 21.2.9.222 `MySql.Data.Types' Namespace ....................................... * Menu: * connector-net-ref-typeshierarchy:: `MySql.Data.TypesHierarchy' * connector-net-ref-types-mysqlconversionexception:: `MySqlConversionException' Class * connector-net-ref-types-mysqldatetime:: `MySqlDateTime' Class *Note Namespace hierarchy: connector-net-ref-typeshierarchy. *Classes* Classes in the MySql.Data.Types namespace. *Class* *Description* *Note MySqlConversionException: Summary description for connector-net-ref-types-mysqlconversionexception.MySqlConversionException. *Note MySqlDateTime: Summary description for connector-net-ref-types-mysqldatetime.MySqlDateTime. *Note MySqlValue: connector-net-ref-types-mysqlvalue.  File: manual.info, Node: connector-net-ref-typeshierarchy, Next: connector-net-ref-types-mysqlconversionexception, Prev: connector-net-ref-types, Up: connector-net-ref-types 21.2.9.223 `MySql.Data.TypesHierarchy' ...................................... *See Also* *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlconversionexception, Next: connector-net-ref-types-mysqldatetime, Prev: connector-net-ref-typeshierarchy, Up: connector-net-ref-types 21.2.9.224 `MySqlConversionException' Class ........................................... * Menu: * connector-net-ref-types-mysqlconversionexceptionmembers:: `MySqlConversionException' Members Summary description for MySqlConversionException. For a list of all members of this type, see *Note MySqlConversionException Members: connector-net-ref-types-mysqlconversionexceptionmembers . *Syntax: Visual Basic* Public Class MySqlConversionException_ Inherits ApplicationException *Syntax: C#* public class MySqlConversionException : ApplicationException *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.Types: connector-net-ref-types. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlConversionException Members: connector-net-ref-types-mysqlconversionexceptionmembers, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlconversionexceptionmembers, Prev: connector-net-ref-types-mysqlconversionexception, Up: connector-net-ref-types-mysqlconversionexception 21.2.9.225 `MySqlConversionException' Members ............................................. * Menu: * connector-net-ref-types-mysqlconversionexceptionconstructor:: `MySqlConversionException' Constructor *Note MySqlConversionException overview: connector-net-ref-types-mysqlconversionexception. *Public Instance Constructors* Public instance constructors in the MySqlConversionException class. *Note MySqlConversionException Ctor Constructor: connector-net-ref-types-mysqlconversionexceptionconstructor. *Public Instance Properties* Public instance properties in the MySqlConversionException class. Data (inherited from Exception) Gets a collection of key/value pairs that provide additional, user-defined information about the exception. HelpLink (inherited from Exception) Gets or sets a link to the help file associated with this exception. InnerException (inherited from Gets the `Exceptioninstance' that Exception) caused the current exception. Message (inherited from Exception) Gets a message that describes the current exception. Source (inherited from Exception) Gets or sets the name of the application or the object that causes the error. StackTrace (inherited from Gets a string representation of the Exception) frames on the call stack at the time the current exception was thrown. TargetSite (inherited from Gets the method that throws the Exception) current exception. *Public Instance Methods* Public instance methods in the MySqlConversionException class. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetBaseException (inherited from When overridden in a derived class, Exception) returns the Exception that is the root cause of one or more subsequent exceptions. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetObjectData (inherited from When overridden in a derived class, Exception) sets the SerializationInfo with information about the exception. GetType (inherited from Exception) Gets the runtime type of the current instance. ToString (inherited from Exception) Creates and returns a string representation of the current exception. *Protected Instance Properties* Protected instance properties in the MySqlConversionException class. HResult (inherited from Exception) Gets or sets `HRESULT', a coded numeric value that is assigned to a specific exception. *Protected Instance Methods* Protected instance methods in the MySqlConversionException class. Finalize (inherited from Object) Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. MemberwiseClone (inherited from Creates a shallow copy of the Object) current Object. *See Also* *Note MySqlConversionException Class: connector-net-ref-types-mysqlconversionexception, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlconversionexceptionconstructor, Prev: connector-net-ref-types-mysqlconversionexceptionmembers, Up: connector-net-ref-types-mysqlconversionexceptionmembers 21.2.9.226 `MySqlConversionException' Constructor ................................................. *Syntax: Visual Basic* Public Sub New( _ ByVal msg As String _ ) *Syntax: C#* public MySqlConversionException( stringmsg ); *See Also* *Note MySqlConversionException Class: connector-net-ref-types-mysqlconversionexception, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime, Prev: connector-net-ref-types-mysqlconversionexception, Up: connector-net-ref-types 21.2.9.227 `MySqlDateTime' Class ................................ * Menu: * connector-net-ref-types-mysqldatetimemembers:: `MySqlDateTime' Members * connector-net-ref-mysqlclient-memcached-client:: `Client' Class * connector-net-ref-mysqlclient-memcached-binaryclient:: `BinaryClient' Class * connector-net-ref-mysqlclient-memcached-textclient:: `TextClient' Class * connector-net-ref-replication:: `MySql.Data.MySqlClient.Replication' Namespace Summary description for MySqlDateTime. For a list of all members of this type, see *Note MySqlDateTime Members: connector-net-ref-types-mysqldatetimemembers . *Syntax: Visual Basic* Public Class MySqlDateTime_ Inherits MySqlValue_ Implements IConvertible, IComparable *Syntax: C#* public class MySqlDateTime : MySqlValue, IConvertible, IComparable *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.Types: connector-net-ref-types. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlDateTime Members: connector-net-ref-types-mysqldatetimemembers, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetimemembers, Next: connector-net-ref-mysqlclient-memcached-client, Prev: connector-net-ref-types-mysqldatetime, Up: connector-net-ref-types-mysqldatetime 21.2.9.228 `MySqlDateTime' Members .................................. * Menu: * connector-net-ref-types-mysqldatetime-op-explicit:: `MySqlDateTime' Explicit `MySqlDateTime' to `DateTime' Conversion * connector-net-ref-types-mysqldatetime-day:: Day Property * connector-net-ref-types-mysqldatetime-hour:: Hour Property * connector-net-ref-types-mysqlvalue-isnull:: IsNull Property * connector-net-ref-types-mysqldatetime-isvaliddatetime:: IsValidDateTime Property * connector-net-ref-types-mysqldatetime-millisecond:: Millisecond Property * connector-net-ref-types-mysqldatetime-minute:: Minute Property * connector-net-ref-types-mysqldatetime-month:: Month Property * connector-net-ref-types-mysqldatetime-second:: Second Property * connector-net-ref-types-mysqldatetime-year:: Year Property * connector-net-ref-types-mysqldatetime-getdatetime:: `MySqlDateTime.GetDateTime' Method * connector-net-ref-types-mysqldatetime-tostring:: `MySqlDateTime.ToString' Method *Note MySqlDateTime overview: connector-net-ref-types-mysqldatetime. *Public Static (Shared) Type Conversions* Public static (shared) type conversions in the MySqlDateTime class. *Note Explicit MySqlDateTime to DateTime Conversion: connector-net-ref-types-mysqldatetime-op-explicit. *Public Instance Properties* Public instance properties in the MySqlDateTime class. *Note Day: Returns the day portion of this connector-net-ref-types-mysqldatetime-day.datetime *Note Hour: Returns the hour portion of this connector-net-ref-types-mysqldatetime-hour.datetime *Note IsNull: connector-net-ref-types-mysqlvalue-isnull. (inherited from MySqlValue) *Note IsValidDateTime: Indicates if this object contains a connector-net-ref-types-mysqldatetime-isvaliddatetime.value that can be represented as a DateTime *Note Minute: Returns the minute portion of this connector-net-ref-types-mysqldatetime-minute.datetime *Note Month: Returns the month portion of this connector-net-ref-types-mysqldatetime-month.datetime *Note Second: Returns the second portion of this connector-net-ref-types-mysqldatetime-second.datetime *Note Millisecond: Returns the millisecond portion of connector-net-ref-types-mysqldatetime-millisecond.this datetime *Note ValueAsObject: Returns the value of this field as connector-net-ref-types-mysqlvalue-valueasobject.an object (inherited from MySqlValue) *Note Year: Returns the year portion of this connector-net-ref-types-mysqldatetime-year.datetime *Public Instance Methods* Public instance methods in the MySqlDateTime class. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. *Note GetDateTime: Returns this value as a DateTime connector-net-ref-types-mysqldatetime-getdatetime. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetType (inherited from Object) Gets the Type of the current instance. *Note ToString: Returns a MySQL-specific string connector-net-ref-types-mysqldatetime-tostring.representation of this value *Protected Instance Fields* Protected instance fields in the MySqlDateTime class. *Note classType: The system type represented by this connector-net-ref-types-mysqlvalue-classtype.value (inherited from MySqlValue) *Note dbType: The generic dbtype of this value connector-net-ref-types-mysqlvalue-dbtype. (inherited from MySqlValue) *Note isNull: Is this value null connector-net-ref-types-mysqlvalue-isnull. (inherited from MySqlValue) *Note mySqlDbType: The specific MySQL db type connector-net-ref-types-mysqlvalue-mysqldbtype. (inherited from MySqlValue) *Note mySqlTypeName: The MySQL-specific typename of this connector-net-ref-types-mysqlvalue-mysqltypename.value (inherited from MySqlValue) *Note objectValue: connector-net-ref-types-mysqlvalue-objectvalue. (inherited from MySqlValue) *Protected Instance Methods* Protected instance methods in the MySqlDateTime class. Finalize (inherited from Object) Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. MemberwiseClone (inherited from Creates a shallow copy of the Object) current Object. *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-op-explicit, Next: connector-net-ref-types-mysqldatetime-day, Prev: connector-net-ref-types-mysqldatetimemembers, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.229 `MySqlDateTime' Explicit `MySqlDateTime' to `DateTime' Conversion ............................................................................ *Syntax: Visual Basic* MySqlDateTime.op_Explicit(val) *Syntax: C#* public static explicit operator DateTime( MySqlDateTimeval ); *Parameters* * `val': *Return Value* *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-day, Next: connector-net-ref-types-mysqldatetime-hour, Prev: connector-net-ref-types-mysqldatetime-op-explicit, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.230 Day Property ....................... Returns the day portion of this datetime *Syntax: Visual Basic* Public Property Day As Integer *Syntax: C#* public int Day {get; set;} *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-hour, Next: connector-net-ref-types-mysqlvalue-isnull, Prev: connector-net-ref-types-mysqldatetime-day, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.231 Hour Property ........................ Returns the hour portion of this datetime *Syntax: Visual Basic* Public Property Hour As Integer *Syntax: C#* public int Hour {get; set;} *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalue-isnull, Next: connector-net-ref-types-mysqldatetime-isvaliddatetime, Prev: connector-net-ref-types-mysqldatetime-hour, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.232 IsNull Property .......................... * Menu: * connector-net-ref-types-mysqlvalue:: `MySqlValue' Class *Syntax: Visual Basic* Public Property IsNull As Boolean *Syntax: C#* public bool IsNull {get; set;} *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalue, Prev: connector-net-ref-types-mysqlvalue-isnull, Up: connector-net-ref-types-mysqlvalue-isnull 21.2.9.233 `MySqlValue' Class ............................. * Menu: * connector-net-ref-types-mysqlvaluemembers:: `MySqlValue' Members For a list of all members of this type, see *Note MySqlValue Members: connector-net-ref-types-mysqlvaluemembers . *Syntax: Visual Basic* MustInherit Public Class MySqlValue *Syntax: C#* public abstract class MySqlValue *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.Types: connector-net-ref-types. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note MySqlValue Members: connector-net-ref-types-mysqlvaluemembers, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvaluemembers, Prev: connector-net-ref-types-mysqlvalue, Up: connector-net-ref-types-mysqlvalue 21.2.9.234 `MySqlValue' Members ............................... * Menu: * connector-net-ref-types-mysqlvalue-numberformat:: `MySqlValue.numberFormat' Field * connector-net-ref-types-mysqlvalueconstructor:: `MySqlValue' Constructor * connector-net-ref-types-mysqlvalue-valueasobject:: ValueAsObject Property * connector-net-ref-types-mysqlvalue-tostring:: `MySqlValue.ToString' Method * connector-net-ref-types-mysqlvalue-classtype:: `MySqlValue.classType' Field * connector-net-ref-types-mysqlvalue-dbtype:: `MySqlValue.dbType' Field * connector-net-ref-types-mysqlvalue-mysqldbtype:: `MySqlValue.mySqlDbType' Field * connector-net-ref-types-mysqlvalue-mysqltypename:: `MySqlValue.mySqlTypeName' Field * connector-net-ref-types-mysqlvalue-objectvalue:: `MySqlValue.objectValue' Field *Note MySqlValue overview: connector-net-ref-types-mysqlvalue. *Protected Static (Shared) Fields* Protected static (shared) fields in the MySqlValue class. *Note numberFormat: connector-net-ref-types-mysqlvalue-numberformat. *Public Instance Constructors* Public instance constructors in the MySqlValue class. *Note MySqlValue Constructor: Initializes a new instance of the connector-net-ref-types-mysqlvalueconstructor.*Note MySqlValue: connector-net-ref-types-mysqlvalue. class. *Public Instance Properties* Public instance properties in the MySqlValue class. *Note IsNull: connector-net-ref-types-mysqlvalue-isnull. *Note ValueAsObject: Returns the value of this field as connector-net-ref-types-mysqlvalue-valueasobject.an object *Public Instance Methods* Public instance methods in the MySqlValue class. Equals (inherited from Object) Determines whether the specified Object is equal to the current Object. GetHashCode (inherited from Object) Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. GetType (inherited from Object) Gets the Type of the current instance. *Note ToString: Returns a string representation of connector-net-ref-types-mysqlvalue-tostring.this value *Protected Instance Fields* Protected instance fields in the MySqlValue class. *Note classType: The system type represented by this connector-net-ref-types-mysqlvalue-classtype.value *Note dbType: The generic dbtype of this value connector-net-ref-types-mysqlvalue-dbtype. *Note isNull: Is this value null connector-net-ref-types-mysqlvalue-isnull. *Note mySqlDbType: The specific MySQL db type connector-net-ref-types-mysqlvalue-mysqldbtype. *Note mySqlTypeName: The MySQL-specific typename of this connector-net-ref-types-mysqlvalue-mysqltypename.value *Note objectValue: connector-net-ref-types-mysqlvalue-objectvalue. *Protected Instance Methods* Protected instance methods in the MySqlValue class. Finalize (inherited from Object) Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. MemberwiseClone (inherited from Creates a shallow copy of the Object) current Object. *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalue-numberformat, Next: connector-net-ref-types-mysqlvalueconstructor, Prev: connector-net-ref-types-mysqlvaluemembers, Up: connector-net-ref-types-mysqlvaluemembers 21.2.9.235 `MySqlValue.numberFormat' Field .......................................... *Syntax: Visual Basic* Protected Shared numberFormat As NumberFormatInfo *Syntax: C#* protected static NumberFormatInfo numberFormat; *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalueconstructor, Next: connector-net-ref-types-mysqlvalue-valueasobject, Prev: connector-net-ref-types-mysqlvalue-numberformat, Up: connector-net-ref-types-mysqlvaluemembers 21.2.9.236 `MySqlValue' Constructor ................................... Initializes a new instance of the *Note MySqlValue: connector-net-ref-types-mysqlvalue. class. *Syntax: Visual Basic* Public Sub New() *Syntax: C#* public MySqlValue(); *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalue-valueasobject, Next: connector-net-ref-types-mysqlvalue-tostring, Prev: connector-net-ref-types-mysqlvalueconstructor, Up: connector-net-ref-types-mysqlvaluemembers 21.2.9.237 ValueAsObject Property ................................. Returns the value of this field as an object *Syntax: Visual Basic* Public ReadOnly Property ValueAsObject As Object *Syntax: C#* public object ValueAsObject {get;} *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalue-tostring, Next: connector-net-ref-types-mysqlvalue-classtype, Prev: connector-net-ref-types-mysqlvalue-valueasobject, Up: connector-net-ref-types-mysqlvaluemembers 21.2.9.238 `MySqlValue.ToString' Method ....................................... Returns a string representation of this value *Syntax: Visual Basic* Overrides Public Function ToString() As String *Syntax: C#* public override string ToString(); *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalue-classtype, Next: connector-net-ref-types-mysqlvalue-dbtype, Prev: connector-net-ref-types-mysqlvalue-tostring, Up: connector-net-ref-types-mysqlvaluemembers 21.2.9.239 `MySqlValue.classType' Field ....................................... The system type represented by this value *Syntax: Visual Basic* Protected classType As Type *Syntax: C#* protected Type classType; *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalue-dbtype, Next: connector-net-ref-types-mysqlvalue-mysqldbtype, Prev: connector-net-ref-types-mysqlvalue-classtype, Up: connector-net-ref-types-mysqlvaluemembers 21.2.9.240 `MySqlValue.dbType' Field .................................... The generic dbtype of this value *Syntax: Visual Basic* Protected dbType As DbType *Syntax: C#* protected DbType dbType; *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalue-mysqldbtype, Next: connector-net-ref-types-mysqlvalue-mysqltypename, Prev: connector-net-ref-types-mysqlvalue-dbtype, Up: connector-net-ref-types-mysqlvaluemembers 21.2.9.241 `MySqlValue.mySqlDbType' Field ......................................... The specific MySQL db type *Syntax: Visual Basic* Protected mySqlDbType As MySqlDbType *Syntax: C#* protected MySqlDbType mySqlDbType; *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalue-mysqltypename, Next: connector-net-ref-types-mysqlvalue-objectvalue, Prev: connector-net-ref-types-mysqlvalue-mysqldbtype, Up: connector-net-ref-types-mysqlvaluemembers 21.2.9.242 `MySqlValue.mySqlTypeName' Field ........................................... The MySQL-specific typename of this value *Syntax: Visual Basic* Protected mySqlTypeName As String *Syntax: C#* protected string mySqlTypeName; *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqlvalue-objectvalue, Prev: connector-net-ref-types-mysqlvalue-mysqltypename, Up: connector-net-ref-types-mysqlvaluemembers 21.2.9.243 `MySqlValue.objectValue' Field ......................................... *Syntax: Visual Basic* Protected objectValue As Object *Syntax: C#* protected object objectValue; *See Also* *Note MySqlValue Class: connector-net-ref-types-mysqlvalue, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-isvaliddatetime, Next: connector-net-ref-types-mysqldatetime-millisecond, Prev: connector-net-ref-types-mysqlvalue-isnull, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.244 IsValidDateTime Property ................................... Indicates if this object contains a value that can be represented as a DateTime *Syntax: Visual Basic* Public ReadOnly Property IsValidDateTime As Boolean *Syntax: C#* public bool IsValidDateTime {get;} *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-millisecond, Next: connector-net-ref-types-mysqldatetime-minute, Prev: connector-net-ref-types-mysqldatetime-isvaliddatetime, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.245 Millisecond Property ............................... Returns the millisecond portion of this datetime *Syntax: Visual Basic* Public Property Millisecond As Integer *Syntax: C#* public int Millisecond {get; set;} *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-minute, Next: connector-net-ref-types-mysqldatetime-month, Prev: connector-net-ref-types-mysqldatetime-millisecond, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.246 Minute Property .......................... Returns the minute portion of this datetime *Syntax: Visual Basic* Public Property Minute As Integer *Syntax: C#* public int Minute {get; set;} *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-month, Next: connector-net-ref-types-mysqldatetime-second, Prev: connector-net-ref-types-mysqldatetime-minute, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.247 Month Property ......................... Returns the month portion of this datetime *Syntax: Visual Basic* Public Property Month As Integer *Syntax: C#* public int Month {get; set;} *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-second, Next: connector-net-ref-types-mysqldatetime-year, Prev: connector-net-ref-types-mysqldatetime-month, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.248 Second Property .......................... Returns the second portion of this datetime *Syntax: Visual Basic* Public Property Second As Integer *Syntax: C#* public int Second {get; set;} *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-year, Next: connector-net-ref-types-mysqldatetime-getdatetime, Prev: connector-net-ref-types-mysqldatetime-second, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.249 Year Property ........................ Returns the year portion of this datetime *Syntax: Visual Basic* Public Property Year As Integer *Syntax: C#* public int Year {get; set;} *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-getdatetime, Next: connector-net-ref-types-mysqldatetime-tostring, Prev: connector-net-ref-types-mysqldatetime-year, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.250 `MySqlDateTime.GetDateTime' Method ............................................. Returns this value as a DateTime *Syntax: Visual Basic* Public Function GetDateTime() As Date *Syntax: C#* public DateTime GetDateTime(); *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-types-mysqldatetime-tostring, Prev: connector-net-ref-types-mysqldatetime-getdatetime, Up: connector-net-ref-types-mysqldatetimemembers 21.2.9.251 `MySqlDateTime.ToString' Method .......................................... Returns a MySQL-specific string representation of this value *Syntax: Visual Basic* Overrides Public Function ToString() As String *Syntax: C#* public override string ToString(); *See Also* *Note MySqlDateTime Class: connector-net-ref-types-mysqldatetime, *Note MySql.Data.Types Namespace: connector-net-ref-types.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client, Next: connector-net-ref-mysqlclient-memcached-binaryclient, Prev: connector-net-ref-types-mysqldatetimemembers, Up: connector-net-ref-types-mysqldatetime 21.2.9.252 `Client' Class ......................... * Menu: * connector-net-ref-mysqlclient-memcached-clientmembers:: `Client' Members For a list of all members of this type, see *Note Client Members: connector-net-ref-mysqlclient-memcached-clientmembers . *Syntax: Visual Basic* Public MustInherit Class Client *Syntax: C#* public abstract class Client *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient.Memcached: connector-net-ref-mysqlclient-memcached-client. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note Client Members: connector-net-ref-mysqlclient-memcached-clientmembers, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient-memcached-client.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-clientmembers, Prev: connector-net-ref-mysqlclient-memcached-client, Up: connector-net-ref-mysqlclient-memcached-client 21.2.9.253 `Client' Members ........................... * Menu: * connector-net-ref-mysqlclient-memcached-client-server:: server Property * connector-net-ref-mysqlclient-memcached-client-port:: Port Property * connector-net-ref-mysqlclient-memcached-client-stream:: `stream' * connector-net-ref-mysqlclient-memcached-client-open:: `Client.Open' Method * connector-net-ref-mysqlclient-memcached-client-close:: `Client.Close' Method * connector-net-ref-mysqlclient-memcached-client-add:: `Client.Add' Method * connector-net-ref-mysqlclient-memcached-client-append:: `Client.Append' Method * connector-net-ref-mysqlclient-memcached-client-cas:: `Client.Cas' Method * connector-net-ref-mysqlclient-memcached-client-decrement:: `Client.Decrement' Method * connector-net-ref-mysqlclient-memcached-client-delete:: `Client.Delete' Method * connector-net-ref-mysqlclient-memcached-client-flushall:: `Client.FlushAll' Method * connector-net-ref-mysqlclient-memcached-client-get:: `Client.Get' Method * connector-net-ref-mysqlclient-memcached-client-increment:: `Client.Increment' Method * connector-net-ref-mysqlclient-memcached-client-prepend:: `Client.Prepend' Method * connector-net-ref-mysqlclient-memcached-client-close-replace:: `Client.Replace' Method * connector-net-ref-mysqlclient-memcached-client-set:: `Client.Set' Method * connector-net-ref-mysqlclient-memcached-client-getinstance:: `Client.GetInstance' Method *Note Client overview: connector-net-ref-mysqlclient-memcached-client. *Public Static Methods* Public static methods constructors in the MySql.Data.MySqlClient.Memcached.Client namespace. *Note GetInstance: Factory method for creating connector-net-ref-mysqlclient-memcached-client.instances of Client that implement a connection with the requested features. The connection object returned must be explicitely opened see method Client.Open *Protected Instance Properties* Protected instance properties in the Client class. *Note server: The server DNS or IP address used connector-net-ref-mysqlclient-memcached-client-server.by the connection. *Note port: The port used by the connection. connector-net-ref-mysqlclient-memcached-client-port. *Note stream: The network stream used by the connector-net-ref-mysqlclient-memcached-client-stream.connecition. *Public Instance Methods* Public instance methods in the Client class. *Note Open: Opens the client connection. connector-net-ref-mysqlclient-memcached-client-open. *Note Close: Closes the client connection. connector-net-ref-mysqlclient-memcached-client-close. *Note Add: Adds a new key/value pair with the connector-net-ref-mysqlclient-memcached-client-add.given TimeSpan expiration. *Note Append: Appends the data to the existing connector-net-ref-mysqlclient-memcached-client-append.data for the associated key.. *Note Cas: Executes the Check-and-set connector-net-ref-mysqlclient-memcached-client-cas.Memcached operation. *Note Decrement>: Decrements the value associated connector-net-ref-mysqlclient-memcached-client-decrement.with a key by the given amount. *Note Delete: Removes they pair key/value given connector-net-ref-mysqlclient-memcached-client-delete.the specified key. *Note FlushAll: Removes all entries from the connector-net-ref-mysqlclient-memcached-client-flushall.storage, effectively invalidating the whole cache. *Note Get: Get the key/value pair associated connector-net-ref-mysqlclient-memcached-client-get.with a given key. *Note Increment: Increments the value associated connector-net-ref-mysqlclient-memcached-client-increment.with a key by the given amount. *Note Prepend: Prepends the data to the existing connector-net-ref-mysqlclient-memcached-client-prepend.data for the associated key. *Note Replace: Replaces the value associated with connector-net-ref-mysqlclient-memcached-client-close-replace.the given key with another value. *Note Set: Set the value of a given key. connector-net-ref-mysqlclient-memcached-client-set. *Public Static Methods* Static instance methods in the Client class. *Note GetInstance: Factory method for creating connector-net-ref-mysqlclient-memcached-client-getinstance.instances of Client that implement a connection with the requested features. The connection object returned must be explicitely opened see method Open. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-server, Next: connector-net-ref-mysqlclient-memcached-client-port, Prev: connector-net-ref-mysqlclient-memcached-clientmembers, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.254 server Property .......................... The server DNS or IP address used by the connection. *Syntax: Visual Basic* Protected server As String *Syntax: C#* protected string server *Property Value* The server DNS or IP address used by the connection. *Remarks* None *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-port, Next: connector-net-ref-mysqlclient-memcached-client-stream, Prev: connector-net-ref-mysqlclient-memcached-client-server, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.255 Port Property ........................ The port used by the connection. *Syntax: Visual Basic* Protected port As UInteger *Syntax: C#* protected uint port *Property Value* The TCP port where the Innodb Memcached plugin will be listening for connections. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-stream, Next: connector-net-ref-mysqlclient-memcached-client-open, Prev: connector-net-ref-mysqlclient-memcached-client-port, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.256 `stream' ................... The network stream used by the connection. *Syntax: Visual Basic* Protected stream As Stream *Syntax: C#* protected Stream stream; *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-open, Next: connector-net-ref-mysqlclient-memcached-client-close, Prev: connector-net-ref-mysqlclient-memcached-client-stream, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.257 `Client.Open' Method ............................... *Syntax: Visual Basic* Public Overridable Sub Open *Syntax: C#* public virtual void Open(); Opens the client connection. *Remarks* A client object can be opened and closed many times during its life cycle. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-close, Next: connector-net-ref-mysqlclient-memcached-client-add, Prev: connector-net-ref-mysqlclient-memcached-client-open, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.258 `Client.Close' Method ................................ *Syntax: Visual Basic* Public Overridable Sub Close *Syntax: C#* public virtual void Close(); Closes the client connection. *Remarks* A client object can be opened and closed many times during its life cycle. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-add, Next: connector-net-ref-mysqlclient-memcached-client-append, Prev: connector-net-ref-mysqlclient-memcached-client-close, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.259 `Client.Add' Method .............................. *Syntax: Visual Basic* Public MustOverride Sub Add ( key As String, data As Object, expiration As TimeSpan ) *Syntax: C#* public abstract void Add( string key, Object data, TimeSpan expiration ); Adds a new key/value pair with the given TimeSpan expiration. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `key', The key for identifying the entry. * `data', The data to associate with the key. * `expiration', The interval of timespan, use `TimeSpan.Zero' for no expiration.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-append, Next: connector-net-ref-mysqlclient-memcached-client-cas, Prev: connector-net-ref-mysqlclient-memcached-client-add, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.260 `Client.Append' Method ................................. *Syntax: Visual Basic* Public MustOverride Sub Append ( key As String, data As Object ) *Syntax: C#* public abstract void Append( string key, Object data ); Appends the data to the existing data for the associated key. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `key', The key for identifying the entry. * `data', The data to append with the data associated with the key.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-cas, Next: connector-net-ref-mysqlclient-memcached-client-decrement, Prev: connector-net-ref-mysqlclient-memcached-client-append, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.261 `Client.Cas' Method .............................. *Syntax: Visual Basic* Public MustOverride Sub Cas ( key As String, data As Object, expiration As TimeSpan, casUnique As ULong ) *Syntax: C#* public abstract void Cas( string key, Object data, TimeSpan expiration, ulong casUnique ); Executes the Check-and-set Memcached operation. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `key', The key for identifying the entry. * `data', The data to use in the CAS. * `expiration', The interval of timespan, use `TimeSpan.Zero' for no expiration. * `casUnique', The CAS unique value to use.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-decrement, Next: connector-net-ref-mysqlclient-memcached-client-delete, Prev: connector-net-ref-mysqlclient-memcached-client-cas, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.262 `Client.Decrement' Method .................................... *Syntax: Visual Basic* Public MustOverride Sub Decrement ( key As String, amount As Integer ) *Syntax: C#* public abstract void Decrement( string key, int amount ); Decrements the value associated with a key by the given amount. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `key', The key associated with the value to decrement. * `amount', The amount to decrement the value.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-delete, Next: connector-net-ref-mysqlclient-memcached-client-flushall, Prev: connector-net-ref-mysqlclient-memcached-client-decrement, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.263 `Client.Delete' Method ................................. *Syntax: Visual Basic* Public MustOverride Sub Delete ( key As String ) *Syntax: C#* public abstract void Delete( string key ); Removes they pair key/value given the specified key. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `key', The key associated with the value to delete.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-flushall, Next: connector-net-ref-mysqlclient-memcached-client-get, Prev: connector-net-ref-mysqlclient-memcached-client-delete, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.264 `Client.FlushAll' Method ................................... *Syntax: Visual Basic* Public MustOverride Sub FlushAll ( delay As TimeSpan ) *Syntax: C#* public abstract void FlushAll( TimeSpan delay ); Removes all entries from the storage, effectively invalidating the whole cache. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `TimeSpan', The interval after which the cache will be cleaned. Can be TimeSpan.Zero for immediately.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-get, Next: connector-net-ref-mysqlclient-memcached-client-increment, Prev: connector-net-ref-mysqlclient-memcached-client-flushall, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.265 `Client.Get' Method .............................. *Syntax: Visual Basic* Public MustOverride Function Get ( key As String ) As KeyValuePair(Of String, Object) *Syntax: C#* public abstract KeyValuePair string, Object> Get( string key ); Get the key/value pair associated with a given key. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `key', The key for which to returm the key/value. Return Value The key/value associated with the key or a MemcachedException if it does not exists.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-increment, Next: connector-net-ref-mysqlclient-memcached-client-prepend, Prev: connector-net-ref-mysqlclient-memcached-client-get, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.266 `Client.Increment' Method .................................... *Syntax: Visual Basic* Public MustOverride Sub Increment ( key As String, amount As Integer ) *Syntax: C#* public abstract void Increment( string key, int amount ); Increments the value associated with a key by the given amount. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `key', The key associated with the value to increment. * `amount', The amount to increment the value.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-prepend, Next: connector-net-ref-mysqlclient-memcached-client-close-replace, Prev: connector-net-ref-mysqlclient-memcached-client-increment, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.267 `Client.Prepend' Method .................................. *Syntax: Visual Basic* Public MustOverride Sub Prepend ( key As String, data As Object ) *Syntax: C#* public abstract void Prepend( string key, Object data ); Prepends the data to the existing data for the associated key. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `key', The key for identifying the entry. * `data', The data to append with the data associated with the key.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-close-replace, Next: connector-net-ref-mysqlclient-memcached-client-set, Prev: connector-net-ref-mysqlclient-memcached-client-prepend, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.268 `Client.Replace' Method .................................. *Syntax: Visual Basic* Public MustOverride Sub Replace ( key As String, data As Object, expiration As TimeSpan ) *Syntax: C#* public abstract void Replace( string key, Object data, TimeSpan expiration ); Replaces the value associated with the given key with another value. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `key', The key for identifying the entry. * `data', The data to replace the value associated with the key. * `expiration', The interval of timespan, use `TimeSpan.Zero' for no expiration.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-set, Next: connector-net-ref-mysqlclient-memcached-client-getinstance, Prev: connector-net-ref-mysqlclient-memcached-client-close-replace, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.269 `Client.Set' Method .............................. *Syntax: Visual Basic* Public MustOverride Sub Set ( key As String, data As Object, expiration As TimeSpan ) *Syntax: C#* public abstract void Set( string key, Object data, TimeSpan expiration ); Set the value of a given key. *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `key', The key for identifying the entry. * `data', The data to associate with the given key. * `expiration', The interval of timespan, use `TimeSpan.Zero' for no expiration.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-client-getinstance, Prev: connector-net-ref-mysqlclient-memcached-client-set, Up: connector-net-ref-mysqlclient-memcached-clientmembers 21.2.9.270 `Client.GetInstance' Method ...................................... *Syntax: Visual Basic* Public Shared Function GetInstance ( server As String, port As UInteger, flags As MemcachedFlags ) As Client *Syntax: C#* public static Client GetInstance( string server, uint port, MemcachedFlags flags ); Factory method for creating instances of Client that implement a connection with the requested features. The connection object returned must be explicitely opened see method Open(). *Remarks* None. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient. Parameters * `server', The Memcached server DNS or IP address. * `port', The port for the Memcached server. * `flags', A set of flags indicating characterestics requested. Return Value An instance of a client connection ready to be used.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-binaryclient, Next: connector-net-ref-mysqlclient-memcached-textclient, Prev: connector-net-ref-mysqlclient-memcached-client, Up: connector-net-ref-types-mysqldatetime 21.2.9.271 `BinaryClient' Class ............................... * Menu: * connector-net-ref-mysqlclient-memcached-binaryclientmembers:: `BinaryClient' Members For a list of all members of this type, see *Note BinaryClient Members: connector-net-ref-mysqlclient-memcached-clientmembers . *Syntax: Visual Basic* Public Class BinaryClient Inherits Client *Syntax: C#* public class BinaryClient : Client *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient.Memcached: connector-net-ref-mysqlclient-memcached-client. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note BinaryClient Members: connector-net-ref-mysqlclient-memcached-clientmembers, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient-memcached-client.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-binaryclientmembers, Prev: connector-net-ref-mysqlclient-memcached-binaryclient, Up: connector-net-ref-mysqlclient-memcached-binaryclient 21.2.9.272 `BinaryClient' Members ................................. *Note BinaryClient overview: connector-net-ref-mysqlclient-memcached-client. *Public Static Methods* Public static methods constructors in the MySql.Data.MySqlClient.Memcached.BinaryClient namespace. *Note GetInstance: Inherited from Client connector-net-ref-mysqlclient-memcached-client-getinstance. *Protected Instance Properties* Protected instance properties in the BinaryClient class. *Note server: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-server. *Note port: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-port. *Note stream: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-stream. *Public Instance Methods* Public instance methods in the BinaryClient class. *Note Open: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-open. *Note Close: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-close. *Note Add: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-add. *Note Append: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-append. *Note Cas: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-cas. *Note Decrement>: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-decrement. *Note Delete: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-delete. *Note FlushAll: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-flushall. *Note Get: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-get. *Note Increment: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-increment. *Note Prepend: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-prepend. *Note Replace: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-close-replace. *Note Set: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-set. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-textclient, Next: connector-net-ref-replication, Prev: connector-net-ref-mysqlclient-memcached-binaryclient, Up: connector-net-ref-types-mysqldatetime 21.2.9.273 `TextClient' Class ............................. * Menu: * connector-net-ref-mysqlclient-memcached-textclientmembers:: `TextClient' Members For a list of all members of this type, see *Note TextClient Members: connector-net-ref-mysqlclient-memcached-clientmembers . *Syntax: Visual Basic* Public Class TextClient Inherits Client *Syntax: C#* public class TextClient : Client *Thread Safety* Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe. *Requirements* Namespace: *Note MySql.Data.MySqlClient.Memcached: connector-net-ref-mysqlclient-memcached-client. Assembly: MySql.Data (in MySql.Data.dll) *See Also* *Note TextClient Members: connector-net-ref-mysqlclient-memcached-clientmembers, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient-memcached-client.  File: manual.info, Node: connector-net-ref-mysqlclient-memcached-textclientmembers, Prev: connector-net-ref-mysqlclient-memcached-textclient, Up: connector-net-ref-mysqlclient-memcached-textclient 21.2.9.274 `TextClient' Members ............................... *Note TextClient overview: connector-net-ref-mysqlclient-memcached-client. *Public Static Methods* Public static methods constructors in the MySql.Data.MySqlClient.Memcached.textclient namespace. *Note GetInstance: Inherited from Client connector-net-ref-mysqlclient-memcached-client-getinstance. *Protected Instance Properties* Protected instance properties in the TextClient class. *Note server: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-server. *Note port: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-port. *Note stream: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-stream. *Public Instance Methods* Public instance methods in the TextClient class. *Note Open: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-open. *Note Close: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-close. *Note Add: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-add. *Note Append: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-append. *Note Cas: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-cas. *Note Decrement>: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-decrement. *Note Delete: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-delete. *Note FlushAll: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-flushall. *Note Get: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-get. *Note Increment: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-increment. *Note Prepend: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-prepend. *Note Replace: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-close-replace. *Note Set: Inherited from Client. connector-net-ref-mysqlclient-memcached-client-set. *See Also* *Note Client Class: connector-net-ref-mysqlclient-memcached-client, *Note MySql.Data.MySqlClient.Memcached Namespace: connector-net-ref-mysqlclient.  File: manual.info, Node: connector-net-ref-replication, Prev: connector-net-ref-mysqlclient-memcached-textclient, Up: connector-net-ref-types-mysqldatetime 21.2.9.275 `MySql.Data.MySqlClient.Replication' Namespace ......................................................... * Menu: * connector-net-ref-replication-replicationmanager:: `ReplicationManager' Class * connector-net-ref-replication-replicationroundrobinservergroup:: `ReplicationRoundRobinServerGroup' Class * connector-net-ref-replication-replicationserver:: `ReplicationServer' Class * connector-net-ref-replication-replicationservergroup:: `ReplicationServerGroup' Class This section of the manual contains the API reference for Replication and Load balancing components. *Classes* Classes in the MySql.Data.MySqlClient.Replication namespace. Class Description *Note ReplicationManager: Manager for Replication and Load connector-net-ref-replication-replicationmanager.Balancing features. *Note Class that implements Round Robing ReplicationRoundRobinServerGroup: Load Balancing technique. connector-net-ref-replication-replicationroundrobinservergroup. *Note ReplicationServer: Represents a server in Replication connector-net-ref-replication-replicationserver.environment that contains information about *Note ReplicationServerGroup: Abstract class used to implement a connector-net-ref-replication-replicationservergroup.custom load balancing plugin  File: manual.info, Node: connector-net-ref-replication-replicationmanager, Next: connector-net-ref-replication-replicationroundrobinservergroup, Prev: connector-net-ref-replication, Up: connector-net-ref-replication 21.2.9.276 `ReplicationManager' Class ..................................... * Menu: * connector-net-ref-replication-replicationmanagermembers:: `ReplicationManager' Members *Note Members: connector-net-ref-replication-replicationmanagermembers. Namespace: *Note MySql.Data.MySqlClient.Replication: connector-net-ref-replication. Assembly: MySql.Data (in `MySql.Data.dll') *Syntax C#* public static class ReplicationManager *Syntax Visual Basic* Public NotInheritable Class ReplicationManager *Syntax Visual C++* public ref class ReplicationManager abstract sealed *See Also* *Note ReplicationManager Members: connector-net-ref-replication-replicationmanagermembers. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationmanagermembers, Prev: connector-net-ref-replication-replicationmanager, Up: connector-net-ref-replication-replicationmanager 21.2.9.277 `ReplicationManager' Members ....................................... * Menu: * connector-net-ref-replication-replicationmanager-addgroup:: AddGroup Method * connector-net-ref-replication-replicationmanager-getgroup:: `ReplicationManager.GetGroup' Method * connector-net-ref-replication-replicationmanager-getnewconnection:: `ReplicationManager.GetNewConnection' Method * connector-net-ref-replication-replicationmanager-getserver:: `ReplicationManager.GetServer' Method * connector-net-ref-replication-replicationmanager-isreplicationgroup:: `ReplicationManager.IsReplicationGroup' Method * connector-net-ref-replication-replicationmanager-groups:: `ReplicationManager.Groups' Property The *Note ReplicationManager: connector-net-ref-replication-replicationmanager. type exposes the following members. *Public Static Methods* Public Static Methods Name Description *Note AddGroup(String: Adds a Default Server Group to the (Int32))connector-net-ref-replication-replicationmanager-addgroup.list *Note AddGroup(String: Adds a Server Group to the list (String)connector-net-ref-replication-replicationmanager-addgroup2. *Note GetGroup: Gets a Server Group by name connector-net-ref-replication-replicationmanager-getgroup. *Note GetNewConnection: Assigns a new server driver to the connector-net-ref-replication-replicationmanager-getnewconnection.connection object *Note GetServer: Gets the next server from a connector-net-ref-replication-replicationmanager-getserver.replication group *Note IsReplicationGroup: Validates if the replication group connector-net-ref-replication-replicationmanager-isreplicationgroup.name exists *Public Static Properties* Public Static Properties Name Description *Note Groups: Returns Replication Server Group connector-net-ref-replication-replicationmanager-groups.List *See Also* *Note ReplicationManager Class: connector-net-ref-replication-replicationmanager. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationmanager-addgroup, Next: connector-net-ref-replication-replicationmanager-getgroup, Prev: connector-net-ref-replication-replicationmanagermembers, Up: connector-net-ref-replication-replicationmanagermembers 21.2.9.278 AddGroup Method .......................... * Menu: * connector-net-ref-replication-replicationmanager-addgroup1:: `ReplicationManager.AddGroup' Method (String, Int32) * connector-net-ref-replication-replicationmanager-addgroup2:: `ReplicationManager.AddGroup' Method (String, String, Int32) *Overload List* * *Note AddGroup(String: (Int32))connector-net-ref-replication-replicationmanager-addgroup1. * *Note AddGroup(String: (String)connector-net-ref-replication-replicationmanager-addgroup2. *See Also* *Note ReplicationManager Class: connector-net-ref-replication-replicationmanager. *Note ReplicationManager Members: connector-net-ref-replication-replicationmanagermembers. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationmanager-addgroup1, Next: connector-net-ref-replication-replicationmanager-addgroup2, Prev: connector-net-ref-replication-replicationmanager-addgroup, Up: connector-net-ref-replication-replicationmanager-addgroup 21.2.9.279 `ReplicationManager.AddGroup' Method (String, Int32) ............................................................... Adds a Default Server Group to the list *Syntax C#* public static ReplicationServerGroup AddGroup( string name, int retryTime ) *Syntax Visual Basic* Public Shared Function AddGroup ( _ name As String, _ retryTime As Integer _ ) As ReplicationServerGroup *Syntax Visual C++* public: static ReplicationServerGroup^ AddGroup( String^ name, int retryTime ) *Parameters* name Type: System.String Group name retryTime Type: System.Int32 Time between reconnections for failed servers *Return Value* A *Note ReplicationServerGroup: connector-net-ref-replication-replicationservergroup. object *See Also* *Note ReplicationManager Class: connector-net-ref-replication-replicationmanager. *Note AddGroup Overload: connector-net-ref-replication-replicationmanager-addgroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationmanager-addgroup2, Prev: connector-net-ref-replication-replicationmanager-addgroup1, Up: connector-net-ref-replication-replicationmanager-addgroup 21.2.9.280 `ReplicationManager.AddGroup' Method (String, String, Int32) ....................................................................... Adds a Server Group to the list *Syntax C#* public static ReplicationServerGroup AddGroup( string name, string groupType, int retryTime ) *Syntax Visual Basic* Public Shared Function AddGroup ( _ name As String, _ groupType As String, _ retryTime As Integer _ ) As ReplicationServerGroup *Syntax Visual C++* public: static ReplicationServerGroup^ AddGroup( String^ name, String^ groupType, int retryTime ) *Parameters* name Type: System.String Group name groupType Type: System.String ServerGroup type reference retryTime Type: System.Int32 Time between reconnections for failed servers *Return Value* A *Note ReplicationServerGroup: connector-net-ref-replication-replicationservergroup. object *See Also* *Note ReplicationManager Class: connector-net-ref-replication-replicationmanager. *Note AddGroup Overload: connector-net-ref-replication-replicationmanager-addgroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationmanager-getgroup, Next: connector-net-ref-replication-replicationmanager-getnewconnection, Prev: connector-net-ref-replication-replicationmanager-addgroup, Up: connector-net-ref-replication-replicationmanagermembers 21.2.9.281 `ReplicationManager.GetGroup' Method ............................................... Gets a Server Group by name *Syntax C#* public static ReplicationServerGroup GetGroup( string groupName ) *Syntax Visual Basic* Public Shared Function GetGroup ( _ groupName As String _ ) As ReplicationServerGroup *Syntax Visual C++* public: static ReplicationServerGroup^ GetGroup( String^ groupName ) *Parameters* groupName Type: System.String Group name *Return Value* A *Note ReplicationServerGroup: connector-net-ref-replication-replicationservergroup. object *See Also* *Note ReplicationManager Class: connector-net-ref-replication-replicationmanager. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationmanager-getnewconnection, Next: connector-net-ref-replication-replicationmanager-getserver, Prev: connector-net-ref-replication-replicationmanager-getgroup, Up: connector-net-ref-replication-replicationmanagermembers 21.2.9.282 `ReplicationManager.GetNewConnection' Method ....................................................... Assigns a new server driver to the connection object *Syntax C#* public static void GetNewConnection( string groupName, bool master, MySqlConnection connection ) *Syntax Visual Basic* Public Shared Sub GetNewConnection ( _ groupName As String, _ master As Boolean, _ connection As MySqlConnection _ ) *Syntax Visual C++* public: static void GetNewConnection( String^ groupName, bool master, MySqlConnection^ connection ) *Parameters* groupName Type: System.String Group name master Type: System.Boolean True if the server connection to assign must be a master connection Type: MySql.Data.MySqlClient.MySqlConnection MySqlConnection object where the new driver will be assigned *See Also* *Note ReplicationManager Class: connector-net-ref-replication-replicationmanager. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationmanager-getserver, Next: connector-net-ref-replication-replicationmanager-isreplicationgroup, Prev: connector-net-ref-replication-replicationmanager-getnewconnection, Up: connector-net-ref-replication-replicationmanagermembers 21.2.9.283 `ReplicationManager.GetServer' Method ................................................ Gets the next server from a replication group *Syntax C#* public static ReplicationServer GetServer( string groupName, bool isMaster ) *Syntax Visual Basic* Public Shared Function GetServer ( _ groupName As String, _ isMaster As Boolean _ ) As ReplicationServer *Syntax Visual C++* public: static ReplicationServer^ GetServer( String^ groupName, bool isMaster ) *Parameters* groupName Type: System.String Group name isMaster Type: System.Boolean True if the server to return must be a master *Return Value* A *Note ReplicationServer: connector-net-ref-replication-replicationserver. object *See Also* *Note ReplicationManager Class: connector-net-ref-replication-replicationmanager. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationmanager-isreplicationgroup, Next: connector-net-ref-replication-replicationmanager-groups, Prev: connector-net-ref-replication-replicationmanager-getserver, Up: connector-net-ref-replication-replicationmanagermembers 21.2.9.284 `ReplicationManager.IsReplicationGroup' Method ......................................................... Validates if the replication group name exists. *Syntax C#* public static bool IsReplicationGroup( string groupName ) *Syntax Visual Basic* Public Shared Function IsReplicationGroup ( _ groupName As String _ ) As Boolean *Syntax Visual C++* public: static bool IsReplicationGroup( String^ groupName ) *Parameters* groupName Type: System.String Group name *Return Value* True if replication group name is found, otherwise false *See Also* *Note ReplicationManager Class: connector-net-ref-replication-replicationmanager. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationmanager-groups, Prev: connector-net-ref-replication-replicationmanager-isreplicationgroup, Up: connector-net-ref-replication-replicationmanagermembers 21.2.9.285 `ReplicationManager.Groups' Property ............................................... Returns Replication Server Group List *Syntax C#* public static IList Groups { get; private set; } *Syntax Visual Basic* Public Shared Property Groups As IList(Of ReplicationServerGroup) Get Private Set *Syntax Visual C++* public: static property IList^ Groups { IList^ get (); private: void set (IList^ value); } *See Also* *Note ReplicationManager Class: connector-net-ref-replication-replicationmanager. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationroundrobinservergroup, Next: connector-net-ref-replication-replicationserver, Prev: connector-net-ref-replication-replicationmanager, Up: connector-net-ref-replication 21.2.9.286 `ReplicationRoundRobinServerGroup' Class ................................................... * Menu: * connector-net-ref-replication-replicationroundrobinservergroupmembers:: `ReplicationRoundRobinServerGroup' Members *Note Members: connector-net-ref-replication-replicationroundrobinservergroupmembers. Namespace: *Note MySql.Data.MySqlClient.Replication: connector-net-ref-replication. Assembly: MySql.Data (in MySql.Data.dll) *Syntax C#* public class ReplicationRoundRobinServerGroup : ReplicationServerGroup *Syntax Visual Basic* Public Class ReplicationRoundRobinServerGroup _ Inherits ReplicationServerGroup *Syntax Visual C++* public ref class ReplicationRoundRobinServerGroup : public ReplicationServerGroup *See Also* *Note ReplicationRoundRobinServerGroup Members: connector-net-ref-replication-replicationroundrobinservergroupmembers. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationroundrobinservergroupmembers, Prev: connector-net-ref-replication-replicationroundrobinservergroup, Up: connector-net-ref-replication-replicationroundrobinservergroup 21.2.9.287 `ReplicationRoundRobinServerGroup' Members ..................................................... * Menu: * connector-net-ref-replication-replicationroundrobinservergroup-constructor:: `ReplicationRoundRobinServerGroup' Constructor * connector-net-ref-replication-replicationroundrobinservergroup-getserver:: GetServer Method The *Note ReplicationRoundRobinServerGroup: connector-net-ref-replication-replicationroundrobinservergroup. type exposes the following members. *Public Instance Constructors* Public Instance Constructors Name Description *Note Initializes a new instance of the ReplicationRoundRobinServerGroup: *Note connector-net-ref-replication-replicationroundrobinservergroup-constructor.ReplicationRoundRobinServerGroup: connector-net-ref-replication-replicationroundrobinservergroup. class *Public Instance Methods* Public Instance Methods Name Description *Note AddServer: Adds a server into the group connector-net-ref-replication-replicationservergroup-addserver.(Inherited from *Note ReplicationServerGroup: connector-net-ref-replication-replicationservergroup.) Equals Determines whether the specified Object is equal to the current Object. (Inherited from Object.) GetHashCode Serves as a hash function for a particular type. (Inherited from Object.) *Note GetServer(Boolean): Gets an available server based on connector-net-ref-replication-replicationroundrobinservergroup-getserver1.Round Robin load balancing (Overrides *Note ReplicationServerGroup.GetServer(Boolean): connector-net-ref-replication-replicationservergroup-getserver1.) *Note GetServer(String): Gets a server by name (Inherited connector-net-ref-replication-replicationservergroup-getserver2.from *Note ReplicationServerGroup: connector-net-ref-replication-replicationservergroup.) GetType Gets the Type of the current instance. (Inherited from Object.) *Note RemoveServer: Removes a server from group connector-net-ref-replication-replicationservergroup-removeserver.(Inherited from *Note ReplicationServerGroup: connector-net-ref-replication-replicationservergroup.) ToString Returns a string that represents the current object. (Inherited from Object.) *Public Instance Properties* Public Instance Properties Name Description *Note Name: (Inherited from *Note connector-net-ref-replication-replicationroundrobinservergroup.ReplicationServerGroup: connector-net-ref-replication-replicationservergroup.) *Note RetryTime: (Inherited from *Note connector-net-ref-replication-replicationroundrobinservergroup.ReplicationServerGroup: connector-net-ref-replication-replicationservergroup.) *Note Servers: (Inherited from *Note connector-net-ref-replication-replicationroundrobinservergroup.ReplicationServerGroup: connector-net-ref-replication-replicationservergroup.) *See Also* *Note ReplicationRoundRobinServerGroup Class: connector-net-ref-replication-replicationroundrobinservergroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationroundrobinservergroup-constructor, Next: connector-net-ref-replication-replicationroundrobinservergroup-getserver, Prev: connector-net-ref-replication-replicationroundrobinservergroupmembers, Up: connector-net-ref-replication-replicationroundrobinservergroupmembers 21.2.9.288 `ReplicationRoundRobinServerGroup' Constructor ......................................................... Initializes a new instance of the *Note ReplicationRoundRobinServerGroup: connector-net-ref-replication-replicationroundrobinservergroup. class *Syntax C#* public ReplicationRoundRobinServerGroup( string name, int retryTime ) *Syntax Visual Basic* Public Sub New ( _ name As String, _ retryTime As Integer _ ) *Syntax Visual C++* public: ReplicationRoundRobinServerGroup( String^ name, int retryTime ) *Parameters* name Type: System.String Server name retryTime Type: System.Int32 Retry time between connections to failed connections *See Also* *Note ReplicationRoundRobinServerGroup Class: connector-net-ref-replication-replicationroundrobinservergroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationroundrobinservergroup-getserver, Prev: connector-net-ref-replication-replicationroundrobinservergroup-constructor, Up: connector-net-ref-replication-replicationroundrobinservergroupmembers 21.2.9.289 GetServer Method ........................... * Menu: * connector-net-ref-replication-replicationroundrobinservergroup-getserver1:: `ReplicationRoundRobinServerGroup.GetServer' Method (Boolean) *Overload List* * *Note GetServer(Boolean): connector-net-ref-replication-replicationroundrobinservergroup-getserver1. * *Note GetServer(String): connector-net-ref-replication-replicationservergroup-getserver2. *See Also* *Note ReplicationRoundRobinServerGroup Class: connector-net-ref-replication-replicationroundrobinservergroup. *Note ReplicationRoundRobinServerGroup Members: connector-net-ref-replication-replicationroundrobinservergroupmembers. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationroundrobinservergroup-getserver1, Prev: connector-net-ref-replication-replicationroundrobinservergroup-getserver, Up: connector-net-ref-replication-replicationroundrobinservergroup-getserver 21.2.9.290 `ReplicationRoundRobinServerGroup.GetServer' Method (Boolean) ........................................................................ Gets an available server based on Round Robin load balancing (Overrides *Note ReplicationServerGroup.GetServer(Boolean): connector-net-ref-replication-replicationservergroup-getserver1.) *Syntax C#* public override ReplicationServer GetServer( bool isMaster ) *Syntax Visual Basic* Public Overrides Function GetServer ( _ isMaster As Boolean _ ) As ReplicationServer *Syntax Visual C++* public: virtual ReplicationServer^ GetServer( bool isMaster ) override *Parameters* isMaster Type: System.Boolean True if the server to return must be a master *Return Value* A *Note ReplicationServer: connector-net-ref-replication-replicationserver. object *See Also* *Note ReplicationRoundRobinServerGroup Class: connector-net-ref-replication-replicationroundrobinservergroup. *Note GetServer Overload: connector-net-ref-replication-replicationroundrobinservergroup-getserver. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationserver, Next: connector-net-ref-replication-replicationservergroup, Prev: connector-net-ref-replication-replicationroundrobinservergroup, Up: connector-net-ref-replication 21.2.9.291 `ReplicationServer' Class .................................... * Menu: * connector-net-ref-replication-replicationservermembers:: `ReplicationServer' Members *Note Members: connector-net-ref-replication-replicationservermembers. Namespace: *Note MySql.Data.MySqlClient.Replication: connector-net-ref-replication. Assembly: MySql.Data (in `MySql.Data.dll') *Syntax C#* public class ReplicationServer *Syntax Visual Basic* Public Class ReplicationServer *Syntax Visual C++* public ref class ReplicationServer *See Also* *Note ReplicationServer Members: connector-net-ref-replication-replicationservermembers. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservermembers, Prev: connector-net-ref-replication-replicationserver, Up: connector-net-ref-replication-replicationserver 21.2.9.292 `ReplicationServer' Members ...................................... * Menu: * connector-net-ref-replication-replicationserver-constructor:: `ReplicationServer' Constructor * connector-net-ref-replication-replicationserver-connectionstring:: `ReplicationServer.ConnectionString' Property * connector-net-ref-replication-replicationserver-isavailable:: `ReplicationServer.IsAvailable' Property * connector-net-ref-replication-replicationserver-ismaster:: `ReplicationServer.IsMaster' Property * connector-net-ref-replication-replicationserver-name:: `ReplicationServer.Name' Property The *Note ReplicationServer: connector-net-ref-replication-replicationserver. type exposes the following members. *Public Instance Constructors* Public Instance Constructors Name Description *Note ReplicationServer: Initializes a new instance of the connector-net-ref-replication-replicationserver-constructor.*Note ReplicationServer: connector-net-ref-replication-replicationserver. class *Public Instance Methods* Public Instance Methods Name Description Equals Determines whether the specified Object is equal to the current Object. (Inherited from Object.) GetHashCode Serves as a hash function for a particular type. (Inherited from Object.) GetType Gets the Type of the current instance. (Inherited from Object.) ToString Returns a string that represents the current object. (Inherited from Object.) *Public Instance Properties* Public Instance Properties Name Description *Note ConnectionString: Connection string used to connect connector-net-ref-replication-replicationserver-connectionstring.to the server *Note IsAvailable: Defines if the server is available connector-net-ref-replication-replicationserver-isavailable.to be considered in load balancing *Note IsMaster: Defines if the server is master connector-net-ref-replication-replicationserver-ismaster.(True) or slave *Note Name: Server name connector-net-ref-replication-replicationserver-name. *See Also* *Note ReplicationServer Class: connector-net-ref-replication-replicationserver. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationserver-constructor, Next: connector-net-ref-replication-replicationserver-connectionstring, Prev: connector-net-ref-replication-replicationservermembers, Up: connector-net-ref-replication-replicationservermembers 21.2.9.293 `ReplicationServer' Constructor .......................................... Initializes a new instance of the *Note ReplicationServer: connector-net-ref-replication-replicationserver. class *Syntax C#* public ReplicationServer( string name, bool isMaster, string connectionString ) *Syntax Visual Basic* Public Sub New ( _ name As String, _ isMaster As Boolean, _ connectionString As String _ ) *Syntax Visual C++* public: ReplicationServer( String^ name, bool isMaster, String^ connectionString ) *Parameters* name Type: System.String Server name isMaster Type: System.Boolean Defines if the server is master (True) or slave connectionString Type: System.String Connection string used to connect to the server *See Also* *Note ReplicationServer Class: connector-net-ref-replication-replicationserver. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationserver-connectionstring, Next: connector-net-ref-replication-replicationserver-isavailable, Prev: connector-net-ref-replication-replicationserver-constructor, Up: connector-net-ref-replication-replicationservermembers 21.2.9.294 `ReplicationServer.ConnectionString' Property ........................................................ Connection string used to connect to the server *Syntax C#* public string ConnectionString { get; private set; } *Syntax Visual Basic* Public Property ConnectionString As String Get Private Set *Syntax Visual C++* public: property String^ ConnectionString { String^ get (); private: void set (String^ value); } *See Also* *Note ReplicationServer Class: connector-net-ref-replication-replicationserver. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationserver-isavailable, Next: connector-net-ref-replication-replicationserver-ismaster, Prev: connector-net-ref-replication-replicationserver-connectionstring, Up: connector-net-ref-replication-replicationservermembers 21.2.9.295 `ReplicationServer.IsAvailable' Property ................................................... Defines if the server is available to be considered in load balancing *Syntax C#* public bool IsAvailable { get; set; } *Syntax Visual Basic* Public Property IsAvailable As Boolean Get Set *Syntax Visual C++* public: property bool IsAvailable { bool get (); void set (bool value); } *See Also* *Note ReplicationServer Class: connector-net-ref-replication-replicationserver. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationserver-ismaster, Next: connector-net-ref-replication-replicationserver-name, Prev: connector-net-ref-replication-replicationserver-isavailable, Up: connector-net-ref-replication-replicationservermembers 21.2.9.296 `ReplicationServer.IsMaster' Property ................................................ Defines if the server is master (True) or slave *Syntax C#* public bool IsMaster { get; private set; } *Syntax Visual Basic* Public Property IsMaster As Boolean Get Private Set *Syntax Visual C++* public: property bool IsMaster { bool get (); private: void set (bool value); } *See Also* *Note ReplicationServer Class: connector-net-ref-replication-replicationserver. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationserver-name, Prev: connector-net-ref-replication-replicationserver-ismaster, Up: connector-net-ref-replication-replicationservermembers 21.2.9.297 `ReplicationServer.Name' Property ............................................ Server name *Syntax C#* public string Name { get; private set; } *Syntax Visual Basic* Public Property Name As String Get Private Set *Syntax Visual C++* public: property String^ Name { String^ get (); private: void set (String^ value); } *See Also* *Note ReplicationServer Class: connector-net-ref-replication-replicationserver. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroup, Prev: connector-net-ref-replication-replicationserver, Up: connector-net-ref-replication 21.2.9.298 `ReplicationServerGroup' Class ......................................... * Menu: * connector-net-ref-replication-replicationservergroupmembers:: `ReplicationServerGroup' Members *Note Members: connector-net-ref-replication-replicationservergroupmembers. Base class used to implement load balancing features Namespace: *Note MySql.Data.MySqlClient.Replication: connector-net-ref-replication. Assembly: MySql.Data (in MySql.Data.dll) *Syntax C#* public abstract class ReplicationServerGroup *Syntax Visual Basic* Public MustInherit Class ReplicationServerGroup *Syntax Visual C++* public ref class ReplicationServerGroup abstract *See Also* *Note ReplicationServerGroup Members: connector-net-ref-replication-replicationservergroupmembers. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroupmembers, Prev: connector-net-ref-replication-replicationservergroup, Up: connector-net-ref-replication-replicationservergroup 21.2.9.299 `ReplicationServerGroup' Members ........................................... * Menu: * connector-net-ref-replication-replicationservergroup-constructor:: `ReplicationServerGroup' Constructor * connector-net-ref-replication-replicationservergroup-addserver:: `ReplicationServerGroup.AddServer' Method * connector-net-ref-replication-replicationservergroup-getserver:: GetServer Method * connector-net-ref-replication-replicationservergroup-removeserver:: `ReplicationServerGroup.RemoveServer' Method * connector-net-ref-replication-replicationservergroup-name:: `ReplicationServerGroup.Name' Property * connector-net-ref-replication-replicationservergroup-retrytime:: `ReplicationServerGroup.RetryTime' Property * connector-net-ref-replication-replicationservergroup-servers:: `ReplicationServerGroup.Servers' Property The *Note ReplicationServerGroup: connector-net-ref-replication-replicationservergroup. type exposes the following members. *Public Instance Constructors* Public Instance Constructors Name Description *Note ReplicationServerGroup: Initializes a new instance of the connector-net-ref-replication-replicationservergroup-constructor.*Note ReplicationServerGroup: connector-net-ref-replication-replicationservergroup. class *Public Instance Methods* Public Instance Methods Name Description *Note AddServer: Adds a server into the group connector-net-ref-replication-replicationservergroup-addserver. Equals Determines whether the specified Object is equal to the current Object. (Inherited from Object.) GetHashCode Serves as a hash function for a particular type. (Inherited from Object.) *Note GetServer(Boolean): Must be implemented. Defines the connector-net-ref-replication-replicationservergroup-getserver1.next server for a custom load balancing implementation. *Note GetServer(String): Gets a server by name. connector-net-ref-replication-replicationservergroup-getserver2. GetType Gets the Type of the current instance. (Inherited from Object.) *Note RemoveServer: Removes a server from group. connector-net-ref-replication-replicationservergroup-removeserver. ToString Returns a string that represents the current object. (Inherited from Object.) *Public Instance Properties* Public Instance Properties Name Description *Note Name: Group name connector-net-ref-replication-replicationservergroup-name. *Note RetryTime: Retry time between connections to connector-net-ref-replication-replicationservergroup-retrytime.failed servers *Note Servers: Servers list in the group connector-net-ref-replication-replicationservergroup-servers. *See Also* *Note ReplicationServerGroup Class: connector-net-ref-replication-replicationservergroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroup-constructor, Next: connector-net-ref-replication-replicationservergroup-addserver, Prev: connector-net-ref-replication-replicationservergroupmembers, Up: connector-net-ref-replication-replicationservergroupmembers 21.2.9.300 `ReplicationServerGroup' Constructor ............................................... Initializes a new instance of the *Note ReplicationServerGroup: connector-net-ref-replication-replicationservergroup. class *Syntax C#* public ReplicationServerGroup( string name, int retryTime ) *Syntax Visual Basic* Public Sub New ( _ name As String, _ retryTime As Integer _ ) *Syntax Visual C++* public: ReplicationServerGroup( String^ name, int retryTime ) *Parameters* name Type: System.String Group name retryTime Type: System.Int32 Retry time between connections to failed servers *See Also* *Note ReplicationServerGroup Class: connector-net-ref-replication-replicationservergroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroup-addserver, Next: connector-net-ref-replication-replicationservergroup-getserver, Prev: connector-net-ref-replication-replicationservergroup-constructor, Up: connector-net-ref-replication-replicationservergroupmembers 21.2.9.301 `ReplicationServerGroup.AddServer' Method .................................................... Adds a server into the group. *Syntax C#* public ReplicationServer AddServer( string name, bool isMaster, string connectionString ) *Syntax Visual Basic* Public Function AddServer ( _ name As String, _ isMaster As Boolean, _ connectionString As String _ ) As ReplicationServer *Syntax Visual C++* public: ReplicationServer^ AddServer( String^ name, bool isMaster, String^ connectionString ) *Parameters* name Type: System.String Server name isMaster Type: System.Boolean True if the server to add is master, False for slave server connectionString Type: System.String Connection string used by this server *See Also* *Note ReplicationServerGroup Class: connector-net-ref-replication-replicationservergroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroup-getserver, Next: connector-net-ref-replication-replicationservergroup-removeserver, Prev: connector-net-ref-replication-replicationservergroup-addserver, Up: connector-net-ref-replication-replicationservergroupmembers 21.2.9.302 GetServer Method ........................... * Menu: * connector-net-ref-replication-replicationservergroup-getserver1:: `ReplicationServerGroup.GetServer' Method (Boolean) * connector-net-ref-replication-replicationservergroup-getserver2:: `ReplicationServerGroup.GetServer' Method (String) *Overload List* * *Note GetServer(Boolean): connector-net-ref-replication-replicationservergroup-getserver1. * *Note GetServer(String): connector-net-ref-replication-replicationservergroup-getserver2. *See Also* *Note ReplicationServerGroup Class: connector-net-ref-replication-replicationservergroup. *Note ReplicationServerGroup Members: connector-net-ref-replication-replicationservergroupmembers. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroup-getserver1, Next: connector-net-ref-replication-replicationservergroup-getserver2, Prev: connector-net-ref-replication-replicationservergroup-getserver, Up: connector-net-ref-replication-replicationservergroup-getserver 21.2.9.303 `ReplicationServerGroup.GetServer' Method (Boolean) .............................................................. Must be implemented. Defines the next server for a custom load balancing implementation. *Syntax C#* public abstract ReplicationServer GetServer( bool isMaster ) *Syntax Visual Basic* Public MustOverride Function GetServer ( _ isMaster As Boolean _ ) As ReplicationServer *Syntax Visual C++* public: virtual ReplicationServer^ GetServer( bool isMaster ) abstract *Parameters* isMaster Type: System.Boolean Defines if the server to return is a master or any *Return Value* A *Note ReplicationServer: connector-net-ref-replication-replicationserver. object *See Also* *Note ReplicationServerGroup Class: connector-net-ref-replication-replicationservergroup. *Note GetServer Overload: connector-net-ref-replication-replicationservergroup-getserver. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroup-getserver2, Prev: connector-net-ref-replication-replicationservergroup-getserver1, Up: connector-net-ref-replication-replicationservergroup-getserver 21.2.9.304 `ReplicationServerGroup.GetServer' Method (String) ............................................................. Gets a server by name. *Syntax C#* public ReplicationServer GetServer( string name ) *Syntax Visual Basic* Public Function GetServer ( _ name As String _ ) As ReplicationServer *Syntax Visual C++* public: ReplicationServer^ GetServer( String^ name ) *Parameters* name Type: System.String Server name *Return Value* A *Note ReplicationServer: connector-net-ref-replication-replicationserver. object *See Also* *Note ReplicationServerGroup Class: connector-net-ref-replication-replicationservergroup. *Note GetServer Overload: connector-net-ref-replication-replicationservergroup-getserver. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroup-removeserver, Next: connector-net-ref-replication-replicationservergroup-name, Prev: connector-net-ref-replication-replicationservergroup-getserver, Up: connector-net-ref-replication-replicationservergroupmembers 21.2.9.305 `ReplicationServerGroup.RemoveServer' Method ....................................................... Removes a server from group. *Syntax C#* public void RemoveServer( string name ) *Syntax Visual Basic* Public Sub RemoveServer ( _ name As String _ ) *Syntax Visual C++* public: void RemoveServer( String^ name ) *Parameters* name Type: System.String Server name *See Also* *Note ReplicationServerGroup Class: connector-net-ref-replication-replicationservergroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroup-name, Next: connector-net-ref-replication-replicationservergroup-retrytime, Prev: connector-net-ref-replication-replicationservergroup-removeserver, Up: connector-net-ref-replication-replicationservergroupmembers 21.2.9.306 `ReplicationServerGroup.Name' Property ................................................. Group name. *Syntax C#* public string Name { get; private set; } *Syntax Visual Basic* Public Property Name As String Get Private Set *Syntax Visual C++* public: property String^ Name { String^ get (); private: void set (String^ value); } *See Also* *Note ReplicationServerGroup Class: connector-net-ref-replication-replicationservergroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroup-retrytime, Next: connector-net-ref-replication-replicationservergroup-servers, Prev: connector-net-ref-replication-replicationservergroup-name, Up: connector-net-ref-replication-replicationservergroupmembers 21.2.9.307 `ReplicationServerGroup.RetryTime' Property ...................................................... Retry time between connections to failed servers. *Syntax C#* public int RetryTime { get; private set; } *Syntax Visual Basic* Public Property RetryTime As Integer Get Private Set *Syntax Visual C++* public: property int RetryTime { int get (); private: void set (int value); } *See Also* *Note ReplicationServerGroup Class: connector-net-ref-replication-replicationservergroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-ref-replication-replicationservergroup-servers, Prev: connector-net-ref-replication-replicationservergroup-retrytime, Up: connector-net-ref-replication-replicationservergroupmembers 21.2.9.308 `ReplicationServerGroup.Servers' Property .................................................... Servers list in the group. *Syntax C#* public IList Servers { get; private set; } *Syntax Visual Basic* Public Property Servers As IList(Of ReplicationServer) Get Private Set *Syntax Visual C++* public: property IList^ Servers { IList^ get (); private: void set (IList^ value); } *See Also* *Note ReplicationServerGroup Class: connector-net-ref-replication-replicationservergroup. *Note MySql.Data.MySqlClient.Replication Namespace: connector-net-ref-replication.  File: manual.info, Node: connector-net-support, Next: connector-net-faq, Prev: connector-net-ref, Up: connector-net 21.2.10 Connector/Net Support ----------------------------- * Menu: * connector-net-support-community:: Connector/Net Community Support * connector-net-support-bug-report:: How to Report Connector/Net Problems or Bugs The developers of Connector/Net greatly value the input of our users in the software development process. If you find Connector/Net lacking some feature important to you, or if you discover a bug and need to file a bug report, please use the instructions in *Note bug-reports::.  File: manual.info, Node: connector-net-support-community, Next: connector-net-support-bug-report, Prev: connector-net-support, Up: connector-net-support 21.2.10.1 Connector/Net Community Support ......................................... * Community support for Connector/Net can be found through the forums at `http://forums.mysql.com'. * Community support for Connector/Net can also be found through the mailing lists at `http://lists.mysql.com'. * Paid support is available from Oracle. Additional information is available at `http://dev.mysql.com/support/'.  File: manual.info, Node: connector-net-support-bug-report, Prev: connector-net-support-community, Up: connector-net-support 21.2.10.2 How to Report Connector/Net Problems or Bugs ...................................................... If you encounter difficulties or problems with Connector/Net, contact the Connector/Net community, as explained in *Note connector-net-support-community::. First try to execute the same SQL statements and commands from the *Note `mysql': mysql. client program or from `admndemo'. This helps you determine whether the error is in Connector/Net or MySQL. If reporting a problem, ideally include the following information with the email: * Operating system and version. * Connector/Net version. * MySQL server version. * Copies of error messages or other unexpected output. * Simple reproducible sample. Remember that the more information you can supply to us, the more likely it is that we can fix the problem. If you believe the problem to be a bug, then you must report the bug through `http://bugs.mysql.com/'.  File: manual.info, Node: connector-net-faq, Prev: connector-net-support, Up: connector-net 21.2.11 Connector/Net FAQ ------------------------- *Questions* * 22.2.11.1: How do I obtain the value of an auto-incremented column? *Questions and Answers* *22.2.11.1: ** How do I obtain the value of an auto-incremented column? * When using CommandBuilder, setting `ReturnGeneratedIdentifiers' property to `true' no longer works, as CommandBuilder does not add `last_insert_id()' by default. CommandBuilder hooks up to the DataAdapter.RowUpdating event handler, which means it will get called for every row. It examines the command object and, if it is the same referenced object, it essentially rebuilds the object, thereby destroying your command text changes. One approach to solving this problem is to clone the command object so you have a different actual reference: dataAdapter.InsertCommand = cb.GetInsertCommand().Clone() This will work, but since the CommandBuilder is still connected to the DataAdapter, the RowUpdating event will still fire and performance will be hit. To stop that, once all your commands have been added you need to disconnect the CommandBuilder from the DataAdapter: cb.DataAdapter = null; The last requirement is to make sure the `id' that is returned by `last_insert_id()' has the correct name. For example: SELECT last_insert_id() AS id A complete working example is shown here: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; namespace GetAutoIncId { class Program { static void Main(string[] args) { string connStr = "server=localhost;user=root;database=TestDB;port=3306;password=******;"; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine("Connecting to MySQL..."); conn.Open(); string sql = "SELECT * FROM TestTable"; MySqlDataAdapter da = new MySqlDataAdapter(sql, conn); MySqlCommandBuilder cb = new MySqlCommandBuilder(da); MySqlCommand cmd = new MySqlCommand(); cmd.Connection = conn; cmd.CommandText = sql; // use Cloned object to avoid .NET rebuilding the object, and // thereby throwing away our command text additions. MySqlCommand insertCmd = cb.GetInsertCommand().Clone(); insertCmd.CommandText = insertCmd.CommandText + ";SELECT last_insert_id() AS id"; insertCmd.UpdatedRowSource = UpdateRowSource.FirstReturnedRecord; da.InsertCommand = insertCmd; cb.DataAdapter = null; // Unhook RowUpdating event handler DataTable dt = new DataTable(); da.Fill(dt); DataRow row = dt.NewRow(); row["name"] = "Joe Smith"; dt.Rows.Add(row); da.Update(dt); System.Console.WriteLine("ID after update: " + row["id"]); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine("Done."); } } }  File: manual.info, Node: connector-j, Next: connector-cpp, Prev: connector-net, Up: connectors-apis 21.3 MySQL Connector/J ====================== * Menu: * connector-j-overview:: Overview of MySQL Connector/J * connector-j-versions:: Connector/J Versions * connector-j-installing:: Connector/J Installation * connector-j-examples:: Connector/J Examples * connector-j-reference:: Connector/J (JDBC) Reference * connector-j-usagenotes-basic:: JDBC Concepts * connector-j-usagenotes-j2ee-concepts-connection-pooling:: Connection Pooling with Connector/J * connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections:: Load Balancing with Connector/J * connector-j-usagenotes-j2ee-concepts-load-balancing-failover:: Failover with Connector/J * connector-j-interceptors:: Using the Connector/J Interceptor Classes * connector-j-usagenotes-tomcat:: Using Connector/J with Tomcat * connector-j-usagenotes-jboss:: Using Connector/J with JBoss * connector-j-usagenotes-spring-config:: Using Connector/J with Spring * connector-j-usagenotes-glassfish-config:: Using Connector/J with GlassFish * connector-j-usagenotes-troubleshooting:: Troubleshooting Connector/J Applications * connector-j-usagenotes-known-issues-limitations:: Known Issues and Limitations * connector-j-support:: Connector/J Support This section explains how to configure and develop Java applications with MySQL Connector/J, the JDBC driver that is integrated with MySQL. For release notes detailing the changes in each release of Connector/J, see MySQL Connector/J Release Notes (http://dev.mysql.com/doc/relnotes/connector-j/en/).  File: manual.info, Node: connector-j-overview, Next: connector-j-versions, Prev: connector-j, Up: connector-j 21.3.1 Overview of MySQL Connector/J ------------------------------------ MySQL provides connectivity for client applications developed in the Java programming language through a JDBC driver, which is called MySQL Connector/J. MySQL Connector/J is a JDBC Type 4 driver. Different versions are available that are compatible with the JDBC 3.0 and JDBC 4.0 specifications. The Type 4 designation means that the driver is a pure Java implementation of the MySQL protocol and does not rely on the MySQL client libraries. For large-scale programs that use common design patterns of data access, consider using one of the popular persistence frameworks such as Hibernate (http://www.hibernate.org/), Spring's JDBC templates (http://www.springframework.org/) or Ibatis SQL Maps (http://ibatis.apache.org/) to reduce the amount of JDBC code for you to debug, tune, secure, and maintain. * Key Topics * * For help with connection strings, connection options, and setting up your connection through JDBC, see *Note connector-j-reference-configuration-properties::.  File: manual.info, Node: connector-j-versions, Next: connector-j-installing, Prev: connector-j-overview, Up: connector-j 21.3.2 Connector/J Versions --------------------------- * Menu: * connector-j-change-history:: Connector/J Release Notes and Change History * connector-j-versions-java:: Java Versions Supported There are currently four versions of MySQL Connector/J available: * Connector/J 5.1 is the Type 4 pure Java JDBC driver, which conforms to the JDBC 3.0 and JDBC 4.0 specifications. It provides compatibility with all the functionality of MySQL, including 4.1, 5.0, 5.1, 5.5, 5.6, and 5.7. Connector/J 5.1 provides ease of development features, including auto-registration with the Driver Manager, standardized validity checks, categorized SQLExceptions, support for the JDBC-4.0 XML processing, per connection client information, *Note `NCHAR': char, *Note `NVARCHAR': char. and `NCLOB' types. This release also includes all bug fixes up to and including Connector/J 5.0.6. * Connector/J 5.0 provides support for all the functionality offered by Connector/J 3.1 and includes distributed transaction (XA) support. * Connector/J 3.1 was designed for connectivity to MySQL 4.1 and MySQL 5.0 servers and provides support for all the functionality in MySQL 5.0 except distributed transaction (XA) support. * Connector/J 3.0 provides core functionality and was designed for connectivity to MySQL 3.x or MySQL 4.1 servers, although it provides basic compatibility with later versions of MySQL. Connector/J 3.0 does not support server-side prepared statements, and does not support any of the features in versions of MySQL later than 4.1. The following table summarizes the Connector/J versions available, along with the details of JDBC driver type, what version of the JDBC API it supports, what versions of MySQL Server it works with, and whether it is currently supported or not: *Summary of Connector/J Versions* Connector/J Driver Type JDBC version MySQL Server Status version version 5.1 4 3.0, 4.0 4.1, 5.0, Recommended 5.1, 5.5, version 5.6, 5.7 5.0 4 3.0 4.1, 5.0 Released version 3.1 4 3.0 4.1, 5.0 Obsolete 3.0 4 3.0 3.x, 4.1 Obsolete The current recommended version for Connector/J is 5.1. This guide covers all four connector versions, with specific notes given where a setting applies to a specific option.  File: manual.info, Node: connector-j-change-history, Next: connector-j-versions-java, Prev: connector-j-versions, Up: connector-j-versions 21.3.2.1 Connector/J Release Notes and Change History ..................................................... For details of new features and bug fixes in each Connector/J release, see the MySQL Connector/J Release Notes (http://dev.mysql.com/doc/relnotes/connector-j/en/).  File: manual.info, Node: connector-j-versions-java, Prev: connector-j-change-history, Up: connector-j-versions 21.3.2.2 Java Versions Supported ................................ The following table summarizes what version of Java RTE is required to use Connector/J with Java applications, and what version of JDK is required to build Connector/J source code: *Summary of Java Versions Required by Connector/J* Connector/J version Java RTE required JDK required (to build source code) 5.1 1.5.x, 1.6.x, 1.7.x 1.6.x and 1.5.x 5.0 1.3.x, 1.4.x, 1.5.x, 1.4.2, 1.5.x, 1.6.x 1.6.x 3.1 1.2.x, 1.3.x, 1.4.x, 1.4.2, 1.5.x, 1.6.x 1.5.x, 1.6.x 3.0 1.2.x, 1.3.x, 1.4.x, 1.4.2, 1.5.x, 1.6.x 1.5.x, 1.6.x If you are building Connector/J from source code using the source distribution (see *Note connector-j-installing-source::), you must use JDK 1.4.2 or newer to compile the Connector package. For Connector/J 5.1, you must have both JDK-1.6.x and JDK-1.5.x installed to be able to build the source code. Java 1.7 support requires Connector/J 5.1.21 and higher. Several JDBC 4.1 methods were implemented for the first time in Connector/J 5.1.21. Because of the implementation of java.sql.Savepoint, Connector/J 3.1.0 and newer will not run on a Java runtime older than 1.4 unless the class verifier is turned off (by setting the `-Xverify:none' option to the Java runtime). This is because the class verifier will try to load the class definition for java.sql.Savepoint even though it is not accessed by the driver unless you actually use savepoint functionality. Caching functionality provided by Connector/J 3.1.0 or newer is also not available on JVMs older than 1.4.x, as it relies on java.util.LinkedHashMap which was first available in JDK-1.4.0. MySQL Connector/J does not support JDK-1.1.x or JDK-1.0.x.  File: manual.info, Node: connector-j-installing, Next: connector-j-examples, Prev: connector-j-versions, Up: connector-j 21.3.3 Connector/J Installation ------------------------------- * Menu: * connector-j-binary-installation:: Installing Connector/J from a Binary Distribution * connector-j-installing-classpath:: Installing the Driver and Configuring the `CLASSPATH' * connector-j-installing-upgrading:: Upgrading from an Older Version * connector-j-installing-source:: Installing from the Development Source Tree You can install the Connector/J package using either the binary or source distribution. The binary distribution provides the easiest method for installation; the source distribution lets you customize your installation further. With either solution, you manually add the Connector/J location to your Java `CLASSPATH'. If you are upgrading from a previous version, read the upgrade information in *Note connector-j-installing-upgrading:: before continuing. Connector/J is also available as part of the Maven project. For more information, and to download the Connector/J JAR files, see the Maven repository (http://www.ibiblio.org/maven/).  File: manual.info, Node: connector-j-binary-installation, Next: connector-j-installing-classpath, Prev: connector-j-installing, Up: connector-j-installing 21.3.3.1 Installing Connector/J from a Binary Distribution .......................................................... For the easiest method of installation, use the binary distribution of the Connector/J package. The binary distribution is available either as a tar/gzip or zip file. Extract it to a suitable location, then optionally make the information about the package available by changing your `CLASSPATH' (see *Note connector-j-installing-classpath::). MySQL Connector/J is distributed as a `.zip' or `.tar.gz' archive containing the sources, the class files, and the JAR archive named `mysql-connector-java-VERSION-bin.jar'. Starting with Connector/J 3.1.9, the `.class' files that constitute the JAR files are only included as part of the driver JAR file. Starting with Connector/J 3.1.8, the archive also includes a debug build of the driver in a file named `mysql-connector-java-VERSION-bin-g.jar'. Do not use the debug build of the driver unless instructed to do so when reporting a problem or a bug, as it is not designed to be run in production environments, and will have adverse performance impact when used. The debug binary also depends on the Aspect/J runtime library, which is located in the `src/lib/aspectjrt.jar' file that comes with the Connector/J distribution. Use the appropriate graphical or command-line utility to extract the distribution (for example, WinZip for the .zip archive, and `tar' for the .tar.gz archive). Because there are potentially long file names in the distribution, we use the GNU tar archive format. Use GNU tar (or an application that understands the GNU tar archive format) to unpack the .tar.gz variant of the distribution.  File: manual.info, Node: connector-j-installing-classpath, Next: connector-j-installing-upgrading, Prev: connector-j-binary-installation, Up: connector-j-installing 21.3.3.2 Installing the Driver and Configuring the `CLASSPATH' .............................................................. Once you have extracted the distribution archive, you can install the driver by placing `mysql-connector-java-VERSION-bin.jar 'in your classpath, either by adding the full path to it to your `CLASSPATH' environment variable, or by directly specifying it with the command line switch `-cp' when starting the JVM. To use the driver with the JDBC `DriverManager', use `com.mysql.jdbc.Driver' as the class that implements java.sql.Driver. You can set the `CLASSPATH' environment variable under Unix, Linux or Mac OS X either locally for a user within their `.profile', `.login' or other login file. You can also set it globally by editing the global `/etc/profile' file. For example, add the Connector/J driver to your `CLASSPATH' using one of the following forms, depending on your command shell: # Bourne-compatible shell (sh, ksh, bash, zsh): shell> export CLASSPATH=/path/mysql-connector-java-VER-bin.jar:$CLASSPATH # C shell (csh, tcsh): shell> setenv CLASSPATH /path/mysql-connector-java-VER-bin.jar:$CLASSPATH Within Windows 2000, Windows XP, Windows Server 2003 and Windows Vista, you set the environment variable through the System Control Panel. To use MySQL Connector/J with an application server such as GlassFish, Tomcat or JBoss, read your vendor's documentation for more information on how to configure third-party class libraries, as most application servers ignore the `CLASSPATH' environment variable. For configuration examples for some J2EE application servers, see *Note connector-j-usagenotes-j2ee-concepts-connection-pooling:: *Note connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections::, and *Note connector-j-usagenotes-j2ee-concepts-load-balancing-failover::. However, the authoritative source for JDBC connection pool configuration information for your particular application server is the documentation for that application server. If you are developing servlets or JSPs, and your application server is J2EE-compliant, you can put the driver's `.jar' file in the `WEB-INF/lib' subdirectory of your webapp, as this is a standard location for third party class libraries in J2EE web applications. You can also use the MysqlDataSource or MysqlConnectionPoolDataSource classes in the `com.mysql.jdbc.jdbc2.optional' package, if your J2EE application server supports or requires them. Starting with Connector/J 5.0.0, the `javax.sql.XADataSource' interface is implemented using the `com.mysql.jdbc.jdbc2.optional.MysqlXADataSource' class, which supports XA distributed transactions when used in combination with MySQL server version 5.0. The various MysqlDataSource classes support the following parameters (through standard set mutators): * `user' * `password' * `serverName' (see the previous section about fail-over hosts) * `databaseName' * `port'  File: manual.info, Node: connector-j-installing-upgrading, Next: connector-j-installing-source, Prev: connector-j-installing-classpath, Up: connector-j-installing 21.3.3.3 Upgrading from an Older Version ........................................ * Menu: * connector-j-installing-upgrading-5-1:: Upgrading to MySQL Connector/J 5.1.x * connector-j-installing-upgrading-issues:: JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer * connector-j-installing-upgrading-3-0-to-3-1:: Upgrading from MySQL Connector/J 3.0 to 3.1 This section has information for users who are upgrading from one version of Connector/J to another, or to a new version of the MySQL server that supports a more recent level of JDBC. A newer version of Connector/J might include changes to support new features, improve existing functionality, or comply with new standards.  File: manual.info, Node: connector-j-installing-upgrading-5-1, Next: connector-j-installing-upgrading-issues, Prev: connector-j-installing-upgrading, Up: connector-j-installing-upgrading 21.3.3.4 Upgrading to MySQL Connector/J 5.1.x ............................................. * In Connector/J 5.0.x and earlier, the alias for a table in a *Note `SELECT': select. statement is returned when accessing the result set metadata using `ResultSetMetaData.getColumnName()'. This behavior however is not JDBC compliant, and in Connector/J 5.1 this behavior was changed so that the original table name, rather than the alias, is returned. The JDBC-compliant behavior is designed to let API users reconstruct the DML statement based on the metadata within `ResultSet' and `ResultSetMetaData'. You can get the alias for a column in a result set by calling `ResultSetMetaData.getColumnLabel()'. To use the old noncompliant behavior with `ResultSetMetaData.getColumnName()', use the `useOldAliasMetadataBehavior' option and set the value to `true'. In Connector/J 5.0.x, the default value of `useOldAliasMetadataBehavior' was `true', but in Connector/J 5.1 this was changed to a default value of `false'.  File: manual.info, Node: connector-j-installing-upgrading-issues, Next: connector-j-installing-upgrading-3-0-to-3-1, Prev: connector-j-installing-upgrading-5-1, Up: connector-j-installing-upgrading 21.3.3.5 JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer ......................................................................... * _Using the UTF-8 Character Encoding_ - Prior to MySQL server version 4.1, the UTF-8 character encoding was not supported by the server, however the JDBC driver could use it, allowing storage of multiple character sets in `latin1' tables on the server. Starting with MySQL-4.1, this functionality is deprecated. If you have applications that rely on this functionality, and can not upgrade them to use the official Unicode character support in MySQL server version 4.1 or newer, add the following property to your connection URL: useOldUTF8Behavior=true * _Server-side Prepared Statements_ - Connector/J 3.1 will automatically detect and use server-side prepared statements when they are available (MySQL server version 4.1.0 and newer). If your application encounters issues with server-side prepared statements, you can revert to the older client-side emulated prepared statement code that is still presently used for MySQL servers older than 4.1.0 with the following connection property: useServerPrepStmts=false  File: manual.info, Node: connector-j-installing-upgrading-3-0-to-3-1, Prev: connector-j-installing-upgrading-issues, Up: connector-j-installing-upgrading 21.3.3.6 Upgrading from MySQL Connector/J 3.0 to 3.1 .................................................... Connector/J 3.1 is designed to be backward-compatible with Connector/J 3.0 as much as possible. Major changes are isolated to new functionality exposed in MySQL-4.1 and newer, which includes Unicode character sets, server-side prepared statements, `SQLState' codes returned in error messages by the server and various performance enhancements that can be enabled or disabled using configuration properties. * *Unicode Character Sets*: See the next section, as well as *Note charset::, for information on this MySQL feature. If you have something misconfigured, it will usually show up as an error with a message similar to `Illegal mix of collations'. * *Server-side Prepared Statements*: Connector/J 3.1 will automatically detect and use server-side prepared statements when they are available (MySQL server version 4.1.0 and newer). Starting with version 3.1.7, the driver scans SQL you are preparing using all variants of `Connection.prepareStatement()' to determine if it is a supported type of statement to prepare on the server side, and if it is not supported by the server, it instead prepares it as a client-side emulated prepared statement. You can disable this feature by passing `emulateUnsupportedPstmts=false' in your JDBC URL. If your application encounters issues with server-side prepared statements, you can revert to the older client-side emulated prepared statement code that is still presently used for MySQL servers older than 4.1.0 with the connection property `useServerPrepStmts=false'. * *Datetimes* with all-zero components (`0000-00-00 ...'): These values cannot be represented reliably in Java. Connector/J 3.0.x always converted them to `NULL' when being read from a ResultSet. Connector/J 3.1 throws an exception by default when these values are encountered, as this is the most correct behavior according to the JDBC and SQL standards. This behavior can be modified using the `zeroDateTimeBehavior' configuration property. The permissible values are: * `exception' (the default), which throws an SQLException with an SQLState of `S1009'. * `convertToNull', which returns `NULL' instead of the date. * `round', which rounds the date to the nearest closest value which is `0001-01-01'. Starting with Connector/J 3.1.7, `ResultSet.getString()' can be decoupled from this behavior using `noDatetimeStringSync=true' (the default value is `false') so that you can retrieve the unaltered all-zero value as a String. Note that this also precludes using any time zone conversions, therefore the driver will not allow you to enable `noDatetimeStringSync' and `useTimezone' at the same time. * *New SQLState Codes*: Connector/J 3.1 uses SQL:1999 SQLState codes returned by the MySQL server (if supported), which are different from the legacy X/Open state codes that Connector/J 3.0 uses. If connected to a MySQL server older than MySQL-4.1.0 (the oldest version to return SQLStates as part of the error code), the driver will use a built-in mapping. You can revert to the old mapping by using the configuration property `useSqlStateCodes=false'. * *`ResultSet.getString()'*: Calling `ResultSet.getString()' on a *Note `BLOB': blob. column will now return the address of the `byte[]' array that represents it, instead of a `String' representation of the *Note `BLOB': blob. *Note `BLOB': blob. values have no character set, so they cannot be converted to `java.lang.String's without data loss or corruption. To store strings in MySQL with LOB behavior, use one of the *Note `TEXT': blob. types, which the driver will treat as a `java.sql.Clob'. * *Debug builds*: Starting with Connector/J 3.1.8 a debug build of the driver in a file named `mysql-connector-java-VERSION-bin-g.jar' is shipped alongside the normal binary jar file that is named `mysql-connector-java-VERSION-bin.jar'. Starting with Connector/J 3.1.9, we do not ship the `.class' files unbundled, they are only available in the JAR archives that ship with the driver. Do not use the debug build of the driver unless instructed to do so when reporting a problem or bug, as it is not designed to be run in production environments, and will have adverse performance impact when used. The debug binary also depends on the Aspect/J runtime library, which is located in the `src/lib/aspectjrt.jar' file that comes with the Connector/J distribution.  File: manual.info, Node: connector-j-installing-source, Prev: connector-j-installing-upgrading, Up: connector-j-installing 21.3.3.7 Installing from the Development Source Tree .................................................... *Caution*: Read this section only if you are interested in helping us test our new code. To just get MySQL Connector/J up and running on your system, use a standard binary release distribution. To install MySQL Connector/J from the development source tree, make sure that you have the following prerequisites: * A Bazaar client, to check out the sources from our Launchpad repository (available from `http://bazaar-vcs.org/'). * Apache Ant version 1.7 or newer (available from `http://ant.apache.org/'). * JDK 1.4.2 or later. Although MySQL Connector/J can be be used with older JDKs, compiling it from source requires at least JDK 1.4.2. To build Connector/J 5.1 requires JDK 1.6.x _and_ an older JDK such as JDK 1.5.x; point your `JAVA_HOME' environment variable at the older installation. To check out and compile a specific branch of MySQL Connector/J, follow these steps: 1. Check out the latest code from the branch that you want with one of the following commands. The source code repository for MySQL Connector/J is located on Launchpad at `https://code.launchpad.net/connectorj'. To check out the latest development branch, use: shell> bzr branch lp:connectorji This creates a `connectorj' subdirectory in the current directory that contains the latest sources for the requested branch. To check out the latest 5.1 code, use: shell> bzr branch lp:connectorj/5.1 This creates a `5.1' subdirectory in the current directory containing the latest 5.1 code. 2. To build Connector/J 5.1, make sure that you have both JDK 1.6.x installed and an older JDK such as JDK 1.5.x. This is because Connector/J supports both JDBC 3.0 (which was prior to JDK 1.6.x) and JDBC 4.0. Set your `JAVA_HOME' environment variable to the path of the older JDK installation. 3. Change your current working directory to either the `connectorj' or `5.1' directory, depending on which branch you intend to build. 4. To build Connector/J 5.1, edit the `build.xml' to reflect the location of your JDK 1.6.x installation. The lines to change are: Alternatively, you can set the value of these property names through the Ant `-D' option. 5. Issue the following command to compile the driver and create a `.jar' file suitable for installation: shell> ant dist This creates a `build' directory in the current directory, where all build output will go. A directory is created in the `build' directory that includes the version number of the sources you are building from. This directory contains the sources, compiled `.class' files, and a `.jar' file suitable for deployment. For other possible targets, including ones that will create a fully packaged distribution, issue the following command: shell> ant -projecthelp 6. A newly created `.jar' file containing the JDBC driver will be placed in the directory `build/mysql-connector-java-VERSION'. Install the newly created JDBC driver as you would a binary `.jar' file that you download from MySQL, by following the instructions in *Note connector-j-installing-classpath::. A package containing both the binary and source code for Connector/J 5.1 can also be found at the following location: Connector/J 5.1 Download (http://dev.mysql.com/downloads/connector/j/5.1.html)  File: manual.info, Node: connector-j-examples, Next: connector-j-reference, Prev: connector-j-installing, Up: connector-j 21.3.4 Connector/J Examples --------------------------- Examples of using Connector/J are located throughout this document. This section provides a summary and links to these examples. * *Note connector-j-examples-connection-drivermanager:: * *Note connector-j-examples-execute-select:: * *Note connector-j-examples-stored-procedure:: * *Note connector-j-examples-preparecall:: * *Note connector-j-examples-output-param:: * *Note connector-j-examples-callablestatement:: * *Note connector-j-examples-retrieving-results-params:: * *Note connector-j-examples-autoincrement-getgeneratedkeys:: * *Note connector-j-examples-autoincrement-select:: * *Note connector-j-examples-autoincrement-updateable-resultsets:: * *Note connector-j-examples-connectionpool-j2ee:: * *Note connector-j-examples-transaction-retry::  File: manual.info, Node: connector-j-reference, Next: connector-j-usagenotes-basic, Prev: connector-j-examples, Up: connector-j 21.3.5 Connector/J (JDBC) Reference ----------------------------------- * Menu: * connector-j-reference-configuration-properties:: Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J * connector-j-reference-implementation-notes:: JDBC API Implementation Notes * connector-j-reference-type-conversions:: Java, JDBC and MySQL Types * connector-j-reference-charsets:: Using Character Sets and Unicode * connector-j-reference-using-ssl:: Connecting Securely Using SSL * connector-j-using-pam:: Connecting Using PAM Authentication * connector-j-reference-replication-connection:: Using Master/Slave Replication with ReplicationConnection * connector-j-reference-error-sqlstates:: Mapping MySQL Error Numbers to JDBC SQLState Codes This section of the manual contains reference material for MySQL Connector/J.  File: manual.info, Node: connector-j-reference-configuration-properties, Next: connector-j-reference-implementation-notes, Prev: connector-j-reference, Up: connector-j-reference 21.3.5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J ............................................................................................... * Menu: * connector-j-useconfigs:: Properties Files for the `useConfigs' Option The name of the class that implements `java.sql.Driver' in MySQL Connector/J is `com.mysql.jdbc.Driver'. The `org.gjt.mm.mysql.Driver' class name is also usable for backward compatibility with MM.MySQL, the predecessor of Connector/J. Use this class name when registering the driver, or when otherwise configuring software to use MySQL Connector/J. * JDBC URL Format * The JDBC URL format for MySQL Connector/J is as follows, with items in square brackets ([, ]) being optional: jdbc:mysql://[HOST][,FAILOVERHOST...][:PORT]/[DATABASE] » [?PROPERTYNAME1][=PROPERTYVALUE1][&PROPERTYNAME2][=PROPERTYVALUE2]... If the host name is not specified, it defaults to `127.0.0.1'. If the port is not specified, it defaults to `3306', the default port number for MySQL servers. jdbc:mysql://[HOST:PORT],[HOST:PORT].../[DATABASE] » [?PROPERTYNAME1][=PROPERTYVALUE1][&PROPERTYNAME2][=PROPERTYVALUE2]... Here is a sample connection URL: jdbc:mysql://localhost:3306/sakila?profileSQL=true * IPv6 Connections * For IPv6 connections, use this alternative syntax to specify hosts in the URL, `address=(KEY=VALUE)'. Supported keys are: * `(protocol=tcp)', or `(protocol=pipe)' for named pipes on Windows. * `(path=PATH_TO_PIPE)' for named pipes. * `(host=HOSTNAME)' for TCP connections. * `(port=PORT_NUMBER)' for TCP connections. For example: jdbc:mysql://address=(protocol=tcp)(host=localhost)(port=3306)(user=test)/db Any other parameters are treated as host-specific properties that follow the conventions of the JDBC URL properties. This now allows per-host overrides of any configuration property for multi-host connections (that is, when using failover, load balancing, or replication). Limit the overrides to user, password, network timeouts and statement and metadata cache sizes; the results of other per-host overrides are not defined. * Initial Database for Connection * If the database is not specified, the connection is made with no default database. In this case, either call the `setCatalog()' method on the Connection instance, or fully specify table names using the database name (that is, `SELECT DBNAME.TABLENAME.COLNAME FROM dbname.tablename...') in your SQL. Opening a connection without specifying the database to use is generally only useful when building tools that work with multiple databases, such as GUI database managers. *Note*: Always use the `Connection.setCatalog()' method to specify the desired database in JDBC applications, rather than the `USE DATABASE' statement. * Failover Support * MySQL Connector/J has failover support. This enables the driver to fail over to any number of slave hosts and still perform read-only queries. Failover only happens when the connection is in an `autoCommit(true)' state, because failover cannot happen reliably when a transaction (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction) is in progress. Most application servers and connection pools set `autoCommit' to `true' at the end of every transaction/connection use. The failover functionality has the following behavior: * If the URL property `autoReconnect' is `false': Failover only happens at connection initialization, and failback occurs when the driver determines that the first host has become available again. * If the URL property `autoReconnect' is `true': Failover happens when the driver determines that the connection has failed (checked before _every_ query), and falls back to the first host when it determines that the host has become available again (after `queriesBeforeRetryMaster' queries have been issued). In either case, whenever you are connected to a `failed-over' server, the connection is set to read-only state, so queries that attempt to modify data will throw exceptions (the query will *never* be processed by the MySQL server). * Setting Configuration Properties * Configuration properties define how Connector/J will make a connection to a MySQL server. Unless otherwise noted, properties can be set for a `DataSource' object or for a `Connection' object. Configuration properties can be set in one of the following ways: * Using the `set*()' methods on MySQL implementations of `java.sql.DataSource' (which is the preferred method when using implementations of `java.sql.DataSource'): * `com.mysql.jdbc.jdbc2.optional.MysqlDataSource' * `com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource' * As a key/value pair in the `java.util.Properties' instance passed to `DriverManager.getConnection()' or `Driver.connect()' * As a JDBC URL parameter in the URL given to `java.sql.DriverManager.getConnection()', `java.sql.Driver.connect()' or the MySQL implementations of the `javax.sql.DataSource' `setURL()' method. *Note*: If the mechanism you use to configure a JDBC URL is XML-based, use the XML character literal & to separate configuration parameters, as the ampersand is a reserved character for XML. The properties are listed in the following tables. Connection/Authentication This table lists Connector/J Connection/Authentication connection properties. * Property Name * * Definition * * * Default Since Value * Version * user The user to connect as all versions password The password to use when connecting all versions socketFactory The name of the class that the com.mysql.jdbc.StandardSocketFactory3.0.3 driver should use for creating socket connections to the server. This class must implement the interface 'com.mysql.jdbc.SocketFactory' and have public no-args constructor. connectTimeout Timeout for socket connect (in 0 3.0.1 milliseconds), with 0 being no timeout. Only works on JDK-1.4 or newer. Defaults to '0'. socketTimeout Timeout on network socket 0 3.0.1 operations (0, the default means no timeout). connectionLifecycleInterceptorsA comma-delimited list of classes 5.1.4 that implement "com.mysql.jdbc.ConnectionLifecycleInterceptor" that should notified of connection lifecycle events (creation, destruction, commit, rollback, setCatalog and setAutoCommit) and potentially alter the execution of these commands. ConnectionLifecycleInterceptors are "stackable", more than one interceptor may be specified via the configuration property as a comma-delimited list, with the interceptors executed in order from left to right. useConfigs Load the comma-delimited list of 3.1.5 configuration properties before parsing the URL or applying user-specified properties. These configurations are explained in the 'Configurations' of the documentation. authenticationPlugins Comma-delimited list of classes 5.1.19 that implement com.mysql.jdbc.AuthenticationPlugin and which will be used for authentication unless disabled by "disabledAuthenticationPlugins" property. defaultAuthenticationPluginName of a class implementing com.mysql.jdbc.authentication.MysqlNativePasswordPlugin5.1.19 com.mysql.jdbc.AuthenticationPlugin which will be used as the default authentication plugin (see below). It is an error to use a class which is not listed in "authenticationPlugins" nor it is one of the built-in plugins. It is an error to set as default a plugin which was disabled with "disabledAuthenticationPlugins" property. It is an error to set this value to null or the empty string (i.e. there must be at least a valid default authentication plugin specified for the connection, meeting all constraints listed above). disabledAuthenticationPluginsComma-delimited list of classes 5.1.19 implementing com.mysql.jdbc.AuthenticationPlugin or mechanisms, i.e. "mysql_native_password". The authentication plugins or mechanisms listed will not be used for authentication which will fail if it requires one of them. It is an error to disable the default authentication plugin (either the one named by "defaultAuthenticationPlugin" property or the hard-coded one if "defaultAuthenticationPlugin" property is not set). disconnectOnExpiredPasswordsIf "disconnectOnExpiredPasswords" true 5.1.23 is set to "false" and password is expired then server enters "sandbox" mode and sends ERR(08001, ER_MUST_CHANGE_PASSWORD) for all commands that are not needed to set a new password until a new password is set. interactiveClient Set the CLIENT_INTERACTIVE flag, false 3.1.0 which tells MySQL to timeout connections based on INTERACTIVE_TIMEOUT instead of WAIT_TIMEOUT localSocketAddress Hostname or IP address given to 5.0.5 explicitly configure the interface that the driver will bind the client side of the TCP/IP connection to when connecting. propertiesTransform An implementation of 3.1.4 com.mysql.jdbc.ConnectionPropertiesTransform that the driver will use to modify URL properties passed to the driver before attempting a connection useCompression Use zlib compression when false 3.0.17 communicating with the server (true/false)? Defaults to 'false'. Networking This table lists Connector/J Networking connection properties. * Property Name * * Definition * * * Default Since Value * Version * maxAllowedPacket Maximum allowed packet size to send -1 5.1.8 to server. If not set, the value of system variable 'max_allowed_packet' will be used to initialize this upon connecting. This value will not take effect if set larger than the value of 'max_allowed_packet'. tcpKeepAlive If connecting using TCP/IP, should true 5.0.7 the driver set SO_KEEPALIVE? tcpNoDelay If connecting using TCP/IP, should true 5.0.7 the driver set SO_TCP_NODELAY (disabling the Nagle Algorithm)? tcpRcvBuf If connecting using TCP/IP, should 0 5.0.7 the driver set SO_RCV_BUF to the given value? The default value of '0', means use the platform default value for this property) tcpSndBuf If connecting using TCP/IP, should 0 5.0.7 the driver set SO_SND_BUF to the given value? The default value of '0', means use the platform default value for this property) tcpTrafficClass If connecting using TCP/IP, should 0 5.0.7 the driver set traffic class or type-of-service fields ?See the documentation for java.net.Socket.setTrafficClass() for more information. High Availability and Clustering This table lists Connector/J High Availability and Clustering connection properties. * Property Name * * Definition * * * Default Since Value * Version * autoReconnect Should the driver try to false 1.1 re-establish stale and/or dead connections? If enabled the driver will throw an exception for a queries issued on a stale or dead connection, which belong to the current transaction, but will attempt reconnect before the next query issued on the connection in a new transaction. The use of this feature is not recommended, because it has side effects related to session state and data consistency when applications don't handle SQLExceptions properly, and is only designed to be used when you are unable to configure your application to handle SQLExceptions resulting from dead and stale connections properly. Alternatively, as a last option, investigate setting the MySQL server variable "wait_timeout" to a high value, rather than the default of 8 hours. autoReconnectForPools Use a reconnection strategy false 3.1.3 appropriate for connection pools (defaults to 'false') failOverReadOnly When failing over in autoReconnect true 3.0.12 mode, should the connection be set to 'read-only'? maxReconnects Maximum number of reconnects to 3 1.1 attempt if autoReconnect is true, default is '3'. reconnectAtTxEnd If autoReconnect is set to true, false 3.0.10 should the driver attempt reconnections at the end of every transaction? retriesAllDown When using loadbalancing, the 120 5.1.6 number of times the driver should cycle through available hosts, attempting to connect. Between cycles, the driver will pause for 250ms if no servers are available. initialTimeout If autoReconnect is enabled, the 2 1.1 initial time to wait between re-connect attempts (in seconds, defaults to '2'). roundRobinLoadBalance When autoReconnect is enabled, and false 3.1.2 failoverReadonly is false, should we pick hosts to connect to on a round-robin basis? queriesBeforeRetryMasterNumber of queries to issue before 50 3.0.2 falling back to master when failed over (when using multi-host failover). Whichever condition is met first, 'queriesBeforeRetryMaster' or 'secondsBeforeRetryMaster' will cause an attempt to be made to reconnect to the master. Defaults to 50. secondsBeforeRetryMasterHow long should the driver wait, 30 3.0.2 when failed over, before attempting selfDestructOnPingMaxOperations=If set to a non-zero value, the 0 5.1.6 driver will report close the connection and report failure when Connection.ping() or Connection.isValid(int) is called if the connection's count of commands sent to the server exceeds this value. selfDestructOnPingSecondsLifetimeIf set to a non-zero value, the 0 5.1.6 driver will report close the connection and report failure when Connection.ping() or Connection.isValid(int) is called if the connection's lifetime exceeds this value. resourceId A globally unique name that 5.0.1 identifies the resource that this datasource or connection is connected to, used for XAResource.isSameRM() when the driver can't determine this value based on hostnames used in the URL Security This table lists Connector/J Security connection properties. * Property Name * * Definition * * * Default Since Value * Version * allowMultiQueries Allow the use of ';' to delimit false 3.1.1 multiple queries during one statement (true/false), defaults to 'false', and does not affect the addBatch() and executeBatch() methods, which instead rely on rewriteBatchStatements. useSSL Use SSL when communicating with the false 3.0.2 server (true/false), defaults to 'false' requireSSL Require SSL connection if false 3.1.0 useSSL=true? (defaults to 'false'). verifyServerCertificateIf "useSSL" is set to "true", true 5.1.6 should the driver verify the server's certificate? When using this feature, the keystore parameters should be specified by the "clientCertificateKeyStore*" properties, rather than system properties. clientCertificateKeyStoreUrlURL to the client certificate 5.1.0 KeyStore (if not specified, use defaults) clientCertificateKeyStoreTypeKeyStore type for client JKS 5.1.0 certificates (NULL or empty means use the default, which is "JKS". Standard keystore types supported by the JVM are "JKS" and "PKCS12", your environment may have more available depending on what security products are installed and available to the JVM. clientCertificateKeyStorePasswordPassword for the client 5.1.0 certificates KeyStore trustCertificateKeyStoreUrlURL to the trusted root certificate 5.1.0 KeyStore (if not specified, use defaults) trustCertificateKeyStoreTypeKeyStore type for trusted root JKS 5.1.0 certificates (NULL or empty means use the default, which is "JKS". Standard keystore types supported by the JVM are "JKS" and "PKCS12", your environment may have more available depending on what security products are installed and available to the JVM. trustCertificateKeyStorePasswordPassword for the trusted root 5.1.0 certificates KeyStore allowLoadLocalInfile Should the driver allow use of true 3.0.3 'LOAD DATA LOCAL INFILE...' (defaults to 'true'). allowUrlInLocalInfile Should the driver allow URLs in false 3.1.4 'LOAD DATA LOCAL INFILE' statements? paranoid Take measures to prevent exposure false 3.0.1 sensitive information in error messages and clear data structures holding sensitive data when possible? (defaults to 'false') passwordCharacterEncodingWhat character encoding is used for 5.1.7 passwords? Leaving this set to the default value (null), uses the platform character set, which works for ISO8859_1 (i.e. "latin1") passwords. For passwords in other character encodings, the encoding will have to be specified with this property, as it's not possible for the driver to auto-detect this. Performance Extensions This table lists Connector/J Performance Extensions connection properties. * Property Name * * Definition * * * Default Since Value * Version * callableStmtCacheSize If 'cacheCallableStmts' is enabled, 100 3.1.2 how many callable statements should be cached? metadataCacheSize The number of queries to cache 50 3.1.1 ResultSetMetadata for if cacheResultSetMetaData is set to 'true' (default 50) useLocalSessionState Should the driver refer to the false 3.1.7 internal values of autocommit and transaction isolation that are set by Connection.setAutoCommit() and Connection.setTransactionIsolation() and transaction state as maintained by the protocol, rather than querying the database or blindly sending commands to the database for commit() or rollback() method calls? useLocalTransactionStateShould the driver use the false 5.1.7 in-transaction state provided by the MySQL protocol to determine if a commit() or rollback() should actually be sent to the database? prepStmtCacheSize If prepared statement caching is 25 3.0.10 enabled, how many prepared statements should be cached? prepStmtCacheSqlLimit If prepared statement caching is 256 3.0.10 enabled, what's the largest SQL the driver will cache the parsing for? parseInfoCacheFactory Name of a class implementing com.mysql.jdbc.PerConnectionLRUFactory5.1.1 com.mysql.jdbc.CacheAdapterFactory, which will be used to create caches for the parsed representation of client-side prepared statements. serverConfigCacheFactoryName of a class implementing com.mysql.jdbc.PerVmServerConfigCacheFactory5.1.1 com.mysql.jdbc.CacheAdapterFactory>, which will be used to create caches for MySQL server configuration values alwaysSendSetIsolation Should the driver always true 3.1.7 communicate with the database when Connection.setTransactionIsolation() is called? If set to false, the driver will only communicate with the database when the requested transaction isolation is different than the whichever is newer, the last value that was set via Connection.setTransactionIsolation(), or the value that was read from the server when the connection was established. Note that useLocalSessionState=true will force the same behavior as alwaysSendSetIsolation=false, regardless of how alwaysSendSetIsolation is set. maintainTimeStats Should the driver maintain various true 3.1.9 internal timers to enable idle time calculations as well as more verbose error messages when the connection to the server fails? Setting this property to false removes at least two calls to System.getCurrentTimeMillis() per query. useCursorFetch If connected to MySQL > 5.0.2, and false 5.0.0 setFetchSize() > 0 on a statement, should that statement use cursor-based fetching to retrieve rows? blobSendChunkSize Chunk to use when sending 1048576 3.1.9 BLOB/CLOBs via ServerPreparedStatements cacheCallableStmts Should the driver cache the parsing false 3.1.2 stage of CallableStatements cachePrepStmts Should the driver cache the parsing false 3.0.10 stage of PreparedStatements of client-side prepared statements, the "check" for suitability of server-side prepared and server-side prepared statements themselves? cacheResultSetMetadata Should the driver cache false 3.1.1 ResultSetMetaData for Statements and PreparedStatements? (Req. JDK-1.4+, true/false, default 'false') cacheServerConfigurationShould the driver cache the results false 3.1.5 of 'SHOW VARIABLES' and 'SHOW COLLATION' on a per-URL basis? defaultFetchSize The driver will call 0 3.1.9 setFetchSize(n) with this value on all newly-created Statements dontTrackOpenResources The JDBC specification requires the false 3.1.7 driver to automatically track and close resources, however if your application doesn't do a good job of explicitly calling close() on statements or result sets, this can cause memory leakage. Setting this property to true relaxes this constraint, and can be more memory efficient for some applications. dynamicCalendars Should the driver retrieve the false 3.1.5 default calendar when required, or cache it per connection/session? elideSetAutoCommits If using MySQL-4.1 or newer, should false 3.1.3 the driver only issue 'set autocommit=n' queries when the server's state doesn't match the requested state by Connection.setAutoCommit(boolean)? enableQueryTimeouts When enabled, query timeouts set true 5.0.6 via Statement.setQueryTimeout() use a shared java.util.Timer instance for scheduling. Even if the timeout doesn't expire before the query is processed, there will be memory used by the TimerTask for the given timeout which won't be reclaimed until the time the timeout would have expired if it hadn't been cancelled by the driver. High-load environments might want to consider disabling this functionality. holdResultsOpenOverStatementCloseShould the driver close result sets false 3.1.7 on Statement.close() as required by the JDBC specification? largeRowSizeThreshold What size result set row should the 2048 5.1.1 JDBC driver consider "large", and thus use a more memory-efficient way of representing the row internally? loadBalanceStrategy If using a load-balanced connection random 5.0.6 to connect to SQL nodes in a MySQL Cluster/NDB configuration (by using the URL prefix "jdbc:mysql:loadbalance://"), which load balancing algorithm should the driver use: (1) "random" - the driver will pick a random host for each request. This tends to work better than round-robin, as the randomness will somewhat account for spreading loads where requests vary in response time, while round-robin can sometimes lead to overloaded nodes if there are variations in response times across the workload. (2) "bestResponseTime" - the driver will route the request to the host that had the best response time for the previous transaction. locatorFetchBufferSize If 'emulateLocators' is configured 1048576 3.2.1 to 'true', what size buffer should be used when fetching BLOB data for getBinaryInputStream? rewriteBatchedStatementsShould the driver use multiqueries false 3.1.13 (irregardless of the setting of "allowMultiQueries") as well as rewriting of prepared statements for INSERT into multi-value inserts when executeBatch() is called? Notice that this has the potential for SQL injection if using plain java.sql.Statements and your code doesn't sanitize input correctly. Notice that for prepared statements, server-side prepared statements can not currently take advantage of this rewrite option, and that if you don't specify stream lengths when using PreparedStatement.set*Stream(), the driver won't be able to determine the optimum number of parameters per batch and you might receive an error from the driver that the resultant packet is too large. Statement.getGeneratedKeys() for these rewritten statements only works when the entire batch includes INSERT statements. useDirectRowUnpack Use newer result set row unpacking true 5.1.1 code that skips a copy from network buffers to a MySQL packet instance and instead reads directly into the result set row data buffers. useDynamicCharsetInfo Should the driver use a true 5.0.6 per-connection cache of character set information queried from the server when necessary, or use a built-in static mapping that is more efficient, but isn't aware of custom character sets or character sets implemented after the release of the JDBC driver? useFastDateParsing Use internal true 5.0.5 String->Date/Time/Timestamp conversion routines to avoid excessive object creation? useFastIntParsing Use internal String->Integer true 3.1.4 conversion routines to avoid excessive object creation? useJvmCharsetConvertersAlways use the character encoding false 5.0.1 routines built into the JVM, rather than using lookup tables for single-byte character sets? useReadAheadInput Use newer, optimized non-blocking, true 3.1.5 buffered input stream when reading from the server? Debugging/Profiling This table lists Connector/J Debugging/Profiling connection properties. * Property Name * * Definition * * * Default Since Value * Version * logger The name of a class that implements com.mysql.jdbc.log.StandardLogger3.1.1 "com.mysql.jdbc.log.Log" that will be used to log messages to. (default is "com.mysql.jdbc.log.StandardLogger", which logs to STDERR) gatherPerfMetrics Should the driver gather false 3.1.2 performance metrics, and report them via the configured logger every 'reportMetricsIntervalMillis' milliseconds? profileSQL Trace queries and their false 3.1.0 execution/fetch times to the configured logger (true/false) defaults to 'false' profileSql Deprecated, use 'profileSQL' 2.0.14 instead. Trace queries and their execution/fetch times on STDERR (true/false) defaults to 'false' reportMetricsIntervalMillisIf 'gatherPerfMetrics' is enabled, 30000 3.1.2 how often should they be logged (in ms)? maxQuerySizeToLog Controls the maximum length/size of 2048 3.1.3 a query that will get logged when profiling or tracing packetDebugBufferSize The maximum number of packets to 20 3.1.3 retain when 'enablePacketDebug' is true slowQueryThresholdMillisIf 'logSlowQueries' is enabled, how 2000 3.1.2 long should a query (in ms) before it is logged as 'slow'? slowQueryThresholdNanosIf 'useNanosForElapsedTime' is set 0 5.0.7 to true, and this property is set to a non-zero value, the driver will use this threshold (in nanosecond units) to determine if a query was slow. useUsageAdvisor Should the driver issue 'usage' false 3.1.1 warnings advising proper and efficient usage of JDBC and MySQL Connector/J to the log (true/false, defaults to 'false')? autoGenerateTestcaseScriptShould the driver dump the SQL it false 3.1.9 is executing, including server-side prepared statements to STDERR? autoSlowLog Instead of using true 5.1.4 slowQueryThreshold* to determine if a query is slow enough to be logged, maintain statistics that allow the driver to determine queries that are outside the 99th percentile? clientInfoProvider The name of a class that implements com.mysql.jdbc.JDBC4CommentClientInfoProvider5.1.0 the com.mysql.jdbc.JDBC4ClientInfoProvider interface in order to support JDBC-4.0's Connection.get/setClientInfo() methods dumpMetadataOnColumnNotFoundShould the driver dump the false 3.1.13 field-level metadata of a result set into the exception message when ResultSet.findColumn() fails? dumpQueriesOnException Should the driver dump the contents false 3.1.3 of the query sent to the server in the message for SQLExceptions? enablePacketDebug When enabled, a ring-buffer of false 3.1.3 'packetDebugBufferSize' packets will be kept, and dumped when exceptions are thrown in key areas in the driver's code explainSlowQueries If 'logSlowQueries' is enabled, false 3.1.2 should the driver automatically issue an 'EXPLAIN' on the server and send the results to the configured log at a WARN level? includeInnodbStatusInDeadlockExceptionsInclude the output of "SHOW ENGINE false 5.0.7 INNODB STATUS" in exception messages when deadlock exceptions are detected? includeThreadDumpInDeadlockExceptionsInclude a current Java thread dump false 5.1.15 in exception messages when deadlock exceptions are detected? includeThreadNamesAsStatementCommentInclude the name of the current false 5.1.15 thread as a comment visible in "SHOW PROCESSLIST", or in Innodb deadlock dumps, useful in correlation with "includeInnodbStatusInDeadlockExceptions=true" and "includeThreadDumpInDeadlockExceptions=true". logSlowQueries Should queries that take longer false 3.1.2 than 'slowQueryThresholdMillis' be logged? logXaCommands Should the driver log XA commands false 5.0.5 sent by MysqlXaConnection to the server, at the DEBUG level of logging? profilerEventHandler Name of a class that implements the com.mysql.jdbc.profiler.LoggingProfilerEventHandler5.1.6 interface com.mysql.jdbc.profiler.ProfilerEventHandler that will be used to handle profiling/tracing events. resultSetSizeThreshold If the usage advisor is enabled, 100 5.0.5 how many rows should a result set contain before the driver warns that it is suspiciously large? traceProtocol Should trace-level network protocol false 3.1.2 be logged? useNanosForElapsedTime For profiling/debugging false 5.0.7 functionality that measures elapsed time, should the driver try to use nanoseconds resolution if available (JDK >= 1.5)? Miscellaneous This table lists Connector/J Miscellaneous connection properties. * Property Name * * Definition * * * Default Since Value * Version * useUnicode Should the driver use Unicode true 1.1g character encodings when handling strings? Should only be used when the driver can't determine the character set mapping, or you are trying to 'force' the driver to use a character set that MySQL either doesn't natively support (such as UTF-8), true/false, defaults to 'true' characterEncoding If 'useUnicode' is set to true, 1.1g what character encoding should the driver use when dealing with strings? (defaults is to 'autodetect') characterSetResults Character set to tell the server to 3.0.13 return results as. connectionAttributes A comma-delimited list of 5.1.25 user-defined key:value pairs (in addition to standard MySQL-defined key:value pairs) to be passed to MySQL Server for display as connection attributes in the PERFORMANCE_SCHEMA.SESSION_CONNECT_ATTRS table. Example usage: connectionAttributes=key1:value1,key2:value2 This functionality is available for use with MySQL Server version 5.6 or later only. Earlier versions of MySQL Server do not support connection attributes, causing this configuration option will be ignored. Setting connectionAttributes=none will cause connection attribute processing to be bypassed, for situations where Connection creation/initialization speed is critical. connectionCollation If set, tells the server to use 3.0.13 this collation via 'set collation_connection' useBlobToStoreUTF8OutsideBMPTells the driver to treat false 5.1.3 [MEDIUM/LONG]BLOB columns as [LONG]VARCHAR columns holding text encoded in UTF-8 that has characters outside the BMP (4-byte encodings), which MySQL server can't handle natively. utf8OutsideBmpExcludedColumnNamePatternWhen "useBlobToStoreUTF8OutsideBMP" 5.1.3 is set to "true", column names matching the given regex will still be treated as BLOBs unless they match the regex specified for "utf8OutsideBmpIncludedColumnNamePattern". The regex must follow the patterns used for the java.util.regex package. utf8OutsideBmpIncludedColumnNamePatternUsed to specify exclusion rules to 5.1.3 "utf8OutsideBmpExcludedColumnNamePattern". The regex must follow the patterns used for the java.util.regex package. loadBalanceEnableJMX Enables JMX-based management of false 5.1.13 load-balanced connection groups, including live addition/removal of hosts from load-balancing pool. sessionVariables A comma-separated list of 3.1.8 name/value pairs to be sent as SET SESSION ... to the server when the driver connects. useColumnNamesInFindColumnPrior to JDBC-4.0, the JDBC false 5.1.7 specification had a bug related to what could be given as a "column name" to ResultSet methods like findColumn(), or getters that took a String property. JDBC-4.0 clarified "column name" to mean the label, as given in an "AS" clause and returned by ResultSetMetaData.getColumnLabel(), and if no AS clause, the column name. Setting this property to "true" will give behavior that is congruent to JDBC-3.0 and earlier versions of the JDBC specification, but which because of the specification bug could give unexpected results. This property is preferred over "useOldAliasMetadataBehavior" unless you need the specific behavior that it provides with respect to ResultSetMetadata. allowNanAndInf Should the driver allow NaN or +/- false 3.1.5 INF values in PreparedStatement.setDouble()? autoClosePStmtStreams Should the driver automatically false 3.1.12 call .close() on streams/readers passed as arguments via set*() methods? autoDeserialize Should the driver automatically false 3.1.5 detect and de-serialize objects stored in BLOB fields? blobsAreStrings Should the driver always treat false 5.0.8 BLOBs as Strings - specifically to work around dubious metadata returned by the server for GROUP BY clauses? capitalizeTypeNames Capitalize type names in true 2.0.7 DatabaseMetaData? (usually only useful when using WebObjects, true/false, defaults to 'false') clobCharacterEncoding The character encoding to use for 5.0.0 sending and retrieving TEXT, MEDIUMTEXT and LONGTEXT values instead of the configured connection characterEncoding clobberStreamingResultsThis will cause a 'streaming' false 3.0.9 ResultSet to be automatically closed, and any outstanding data still streaming from the server to be discarded if another query is executed before all the data has been read from the server. compensateOnDuplicateKeyUpdateCountsShould the driver compensate for false 5.1.7 the update counts of "ON DUPLICATE KEY" INSERT statements (2 = 1, 0 = 1) when using prepared statements? continueBatchOnError Should the driver continue true 3.0.3 processing batch commands if one statement fails. The JDBC spec allows either way (defaults to 'true'). createDatabaseIfNotExistCreates the database given in the false 3.1.9 URL if it doesn't yet exist. Assumes the configured user has permissions to create databases. emptyStringsConvertToZeroShould the driver allow conversions true 3.1.8 from empty string fields to numeric values of '0'? emulateLocators Should the driver emulate false 3.1.0 java.sql.Blobs with locators? With this feature enabled, the driver will delay loading the actual Blob data until the one of the retrieval methods (getInputStream(), getBytes(), and so forth) on the blob data stream has been accessed. For this to work, you must use a column alias with the value of the column to the actual name of the Blob. The feature also has the following restrictions: The SELECT that created the result set must reference only one table, the table must have a primary key; the SELECT must alias the original blob column name, specified as a string, to an alternate name; the SELECT must cover all columns that make up the primary key. emulateUnsupportedPstmtsShould the driver detect prepared true 3.1.7 statements that are not supported by the server, and replace them with client-side emulated versions? exceptionInterceptors Comma-delimited list of classes 5.1.8 that implement com.mysql.jdbc.ExceptionInterceptor. These classes will be instantiated one per Connection instance, and all SQLExceptions thrown by the driver will be allowed to be intercepted by these interceptors, in a chained fashion, with the first class listed as the head of the chain. functionsNeverReturnBlobsShould the driver always treat data false 5.0.8 from functions returning BLOBs as Strings - specifically to work around dubious metadata returned by the server for GROUP BY clauses? generateSimpleParameterMetadataShould the driver generate false 5.0.5 simplified parameter metadata for PreparedStatements when no metadata is available either because the server couldn't support preparing the statement, or server-side prepared statements are disabled? getProceduresReturnsFunctionsPre-JDBC4 DatabaseMetaData API has true 5.1.26 only getProcedures() and getProcedureColumns() methods, so they return metadata info for both stored procedures and functions. JDBC4 was extended with getFunctions() and getFunctionColumns() methods and the expected behaviour of previous methods is not well defined. For JDBC4 and higher, default 'true' value means that calls of DatabaseMetaData.getProcedures() and DatabaseMetaData.getProcedureColumns() return metadata for both procedures and function, as before, keeping back compatibility. Setting this property to false allows to decouple from pre-JDBC4 behaviour of DatabaseMetaData.getProcedures() and DatabaseMetaData.getProcedureColumns(), forcing these to return metadata for procedures only. ignoreNonTxTables Ignore non-transactional table false 3.0.9 warning for rollback? (defaults to 'false'). jdbcCompliantTruncationShould the driver throw true 3.1.2 java.sql.DataTruncation exceptions when data is truncated as is required by the JDBC specification when connected to a server that supports warnings (MySQL 4.1.0 and newer)? This property has no effect if the server sql-mode includes STRICT_TRANS_TABLES. loadBalanceAutoCommitStatementRegexWhen load-balancing is enabled for 5.1.15 auto-commit statements (via loadBalanceAutoCommitStatementThreshold), the statement counter will only increment when the SQL matches the regular expression. By default, every statement issued matches. loadBalanceAutoCommitStatementThresholdWhen auto-commit is enabled, the 0 5.1.15 number of statements which should be executed before triggering load-balancing to rebalance. Default value of 0 causes load-balanced connections to only rebalance when exceptions are encountered, or auto-commit is disabled and transactions are explicitly committed or rolled back. loadBalanceBlacklistTimeoutTime in milliseconds between checks 0 5.1.0 of servers which are unavailable, by controlling how long a server lives in the global blacklist. loadBalanceConnectionGroupLogical group of load-balanced 5.1.13 connections within a classloader, used to manage different groups independently. If not specified, live management of load-balanced connections is disabled. loadBalanceExceptionCheckerFully-qualified class name of com.mysql.jdbc.StandardLoadBalanceExceptionChecker5.1.13 custom exception checker. The class must implement com.mysql.jdbc.LoadBalanceExceptionChecker interface, and is used to inspect SQLExceptions and determine whether they should trigger fail-over to another host in a load-balanced deployment. loadBalancePingTimeout Time in milliseconds to wait for 0 5.1.13 ping response from each of load-balanced physical connections when using load-balanced Connection. loadBalanceSQLExceptionSubclassFailoverComma-delimited list of 5.1.13 classes/interfaces used by default load-balanced exception checker to determine whether a given SQLException should trigger failover. The comparison is done using Class.isInstance(SQLException) using the thrown SQLException. loadBalanceSQLStateFailoverComma-delimited list of SQLState 5.1.13 codes used by default load-balanced exception checker to determine whether a given SQLException should trigger failover. The SQLState of a given SQLException is evaluated to determine whether it begins with any value in the comma-delimited list. loadBalanceValidateConnectionOnSwapServerShould the load-balanced Connection false 5.1.13 explicitly check whether the connection is live when swapping to a new physical connection at commit/rollback? maxRows The maximum number of rows to -1 all return (0, the default means return versions all rows). netTimeoutForStreamingResultsWhat value should the driver 600 5.1.0 automatically set the server setting 'net_write_timeout' to when the streaming result sets feature is in use? (value has unit of seconds, the value '0' means the driver will not try and adjust this value) noAccessToProcedureBodiesWhen determining procedure false 5.0.3 parameter types for CallableStatements, and the connected user can't access procedure bodies through "SHOW CREATE PROCEDURE" or select on mysql.proc should the driver instead create basic metadata (all parameters reported as IN VARCHARs, but allowing registerOutParameter() to be called on them anyway) instead of throwing an exception? noDatetimeStringSync Don't ensure that false 3.1.7 ResultSet.getDatetimeType().toString().equals(ResultSet.getString()) noTimezoneConversionForTimeTypeDon't convert TIME values using the false 5.0.0 server timezone if 'useTimezone'='true' nullCatalogMeansCurrentWhen DatabaseMetadataMethods ask true 3.1.8 for a 'catalog' parameter, does the value null mean use the current catalog? (this is not JDBC-compliant, but follows legacy behavior from earlier versions of the driver) nullNamePatternMatchesAllShould DatabaseMetaData methods true 3.1.8 that accept *pattern parameters treat null the same as '%' (this is not JDBC-compliant, however older versions of the driver accepted this departure from the specification) overrideSupportsIntegrityEnhancementFacilityShould the driver return "true" for false 3.1.12 DatabaseMetaData.supportsIntegrityEnhancementFacility() even if the database doesn't support it to workaround applications that require this method to return "true" to signal support of foreign keys, even though the SQL specification states that this facility contains much more than just foreign key support (one such application being OpenOffice)? padCharsWithSpace If a result set column has the CHAR false 5.0.6 type and the value does not fill the amount of characters specified in the DDL for the column, should the driver pad the remaining characters with space (for ANSI compliance)? pedantic Follow the JDBC spec to the letter. false 3.0.0 pinGlobalTxToPhysicalConnectionWhen using XAConnections, should false 5.0.1 the driver ensure that operations on a given XID are always routed to the same physical connection? This allows the XAConnection to support "XA START ... JOIN" after "XA END" has been called populateInsertRowWithDefaultValuesWhen using ResultSets that are false 5.0.5 CONCUR_UPDATABLE, should the driver pre-populate the "insert" row with default values from the DDL for the table used in the query so those values are immediately available for ResultSet accessors? This functionality requires a call to the database for metadata each time a result set of this type is created. If disabled (the default), the default values will be populated by the an internal call to refreshRow() which pulls back default values and/or values changed by triggers. processEscapeCodesForPrepStmtsShould the driver process escape true 3.1.12 codes in queries that are prepared? queryTimeoutKillsConnectionIf the timeout given in false 5.1.9 Statement.setQueryTimeout() expires, should the driver forcibly abort the Connection instead of attempting to abort the query? relaxAutoCommit If the version of MySQL the driver false 2.0.13 connects to does not support transactions, still allow calls to commit(), rollback() and setAutoCommit() (true/false, defaults to 'false')? retainStatementAfterResultSetCloseShould the driver retain the false 3.1.11 Statement reference in a ResultSet after ResultSet.close() has been called. This is not JDBC-compliant after JDBC-4.0. rollbackOnPooledClose Should the driver issue a true 3.0.15 rollback() when the logical connection in a pool is closed? runningCTS13 Enables workarounds for bugs in false 3.1.7 Sun's JDBC compliance testsuite version 1.3 serverTimezone Override detection/mapping of 3.0.2 timezone. Used when timezone from server doesn't map to Java timezone statementInterceptors A comma-delimited list of classes 5.1.1 that implement "com.mysql.jdbc.StatementInterceptor" that should be placed "in between" query execution to influence the results. StatementInterceptors are "chainable", the results returned by the "current" interceptor will be passed on to the next in in the chain, from left-to-right order, as specified in this property. strictFloatingPoint Used only in older versions of false 3.0.0 compliance test strictUpdates Should the driver do strict true 3.0.4 checking (all primary keys selected) of updatable result sets (true, false, defaults to 'true')? tinyInt1isBit Should the driver treat the true 3.0.16 datatype TINYINT(1) as the BIT type (because the server silently converts BIT -> TINYINT(1) when creating tables)? transformedBitIsBooleanIf the driver converts TINYINT(1) false 3.1.9 to a different type, should it use BOOLEAN instead of BIT for future compatibility with MySQL-5.0, as MySQL-5.0 has a BIT type? treatUtilDateAsTimestampShould the driver treat true 5.0.5 java.util.Date as a TIMESTAMP for the purposes of PreparedStatement.setObject()? ultraDevHack Create PreparedStatements for false 2.0.3 prepareCall() when required, because UltraDev is broken and issues a prepareCall() for _all_ statements? (true/false, defaults to 'false') useAffectedRows Don't set the CLIENT_FOUND_ROWS false 5.1.7 flag when connecting to the server (not JDBC-compliant, will break most applications that rely on "found" rows vs. "affected rows" for DML statements), but does cause "correct" update counts from "INSERT ... ON DUPLICATE KEY UPDATE" statements to be returned by the server. useGmtMillisForDatetimesConvert between session timezone false 3.1.12 and GMT before creating Date and Timestamp instances (value of "false" is legacy behavior, "true" leads to more JDBC-compliant behavior. useHostsInPrivileges Add '@hostname' to users in true 3.0.2 DatabaseMetaData.getColumn/TablePrivileges() (true/false), defaults to 'true'. useInformationSchema When connected to MySQL-5.0.7 or false 5.0.0 newer, should the driver use the INFORMATION_SCHEMA to derive information used by DatabaseMetaData? useJDBCCompliantTimezoneShiftShould the driver use false 5.0.0 JDBC-compliant rules when converting TIME/TIMESTAMP/DATETIME values' timezone information for those JDBC arguments which take a java.util.Calendar argument? (Notice that this option is exclusive of the "useTimezone=true" configuration option.) useLegacyDatetimeCode Use code for true 5.1.6 DATE/TIME/DATETIME/TIMESTAMP handling in result sets and statements that consistently handles timezone conversions from client to server and back again, or use the legacy code for these datatypes that has been in the driver for backwards-compatibility? useOldAliasMetadataBehaviorShould the driver use the legacy false 5.0.4 behavior for "AS" clauses on columns and tables, and only return aliases (if any) for ResultSetMetaData.getColumnName() or ResultSetMetaData.getTableName() rather than the original column/table name? In 5.0.x, the default value was true. useOldUTF8Behavior Use the UTF-8 behavior the driver false 3.1.6 did when communicating with 4.0 and older servers useOnlyServerErrorMessagesDon't prepend 'standard' SQLState true 3.0.15 error messages to error messages returned by the server. useSSPSCompatibleTimezoneShiftIf migrating from an environment false 5.0.5 that was using server-side prepared statements, and the configuration property "useJDBCCompliantTimeZoneShift" set to "true", use compatible behavior when not using server-side prepared statements when sending TIMESTAMP values to the MySQL server. useServerPrepStmts Use server-side prepared statements false 3.1.0 if the server supports them? useSqlStateCodes Use SQL Standard state codes true 3.1.3 instead of 'legacy' X/Open/SQL state codes (true/false), default is 'true' useStreamLengthsInPrepStmtsHonor stream length parameter in true 3.0.2 PreparedStatement/ResultSet.setXXXStream() method calls (true/false, defaults to 'true')? useTimezone Convert time/date types between false 3.0.2 client and server timezones (true/false, defaults to 'false')? useUnbufferedInput Don't use BufferedInputStream for true 3.0.11 reading data from the server yearIsDateType Should the JDBC driver treat the true 3.1.9 MySQL type "YEAR" as a java.sql.Date, or as a SHORT? zeroDateTimeBehavior What should happen when the driver exception3.1.4 encounters DATETIME values that are composed entirely of zeros (used by MySQL to represent invalid dates)? Valid values are "exception", "round" and "convertToNull". Connector/J also supports access to MySQL using named pipes on Windows NT, Windows 2000, or Windows XP using the `NamedPipeSocketFactory' as a plugin-socket factory using the `socketFactory' property. If you do not use a `namedPipePath' property, the default of `'\\.\pipe\MySQL'' is used. If you use the `NamedPipeSocketFactory', the host name and port number values in the JDBC url are ignored. To enable this feature, use: socketFactory=com.mysql.jdbc.NamedPipeSocketFactory Named pipes only work when connecting to a MySQL server on the same physical machine where the JDBC driver is running. In simple performance tests, named pipe access is between 30%-50% faster than the standard TCP/IP access. However, this varies per system, and named pipes are slower than TCP/IP in many Windows configurations. To create your own socket factories, follow the example code in com.mysql.jdbc.NamedPipeSocketFactory, or com.mysql.jdbc.StandardSocketFactory.  File: manual.info, Node: connector-j-useconfigs, Prev: connector-j-reference-configuration-properties, Up: connector-j-reference-configuration-properties 21.3.5.2 Properties Files for the `useConfigs' Option ..................................................... The `useConfigs' connection option is convenient shorthand for specifying combinations of options for particular scenarios. The argument values you can use with this option correspond to the names of `.properties' files within the Connector/J `mysql-connector-java-VERSION-bin.jar' JAR file. For example, the Connector/J 5.1.9 driver includes the following configuration properties files: $ unzip mysql-connector-java-5.1.19-bin.jar '*/configs/*' Archive: mysql-connector-java-5.1.19-bin.jar creating: com/mysql/jdbc/configs/ inflating: com/mysql/jdbc/configs/3-0-Compat.properties inflating: com/mysql/jdbc/configs/5-0-Compat.properties inflating: com/mysql/jdbc/configs/clusterBase.properties inflating: com/mysql/jdbc/configs/coldFusion.properties inflating: com/mysql/jdbc/configs/fullDebug.properties inflating: com/mysql/jdbc/configs/maxPerformance.properties inflating: com/mysql/jdbc/configs/solarisMaxPerformance.properties To specify one of these combinations of options, specify `useConfigs=3-0-Compat', `useConfigs=maxPerformance', and so on. The following sections show the options that are part of each `useConfigs' setting. For the details of why each one is included, see the comments in the `.properties' files. * 3-0-Compat * emptyStringsConvertToZero=true jdbcCompliantTruncation=false noDatetimeStringSync=true nullCatalogMeansCurrent=true nullNamePatternMatchesAll=true transformedBitIsBoolean=false dontTrackOpenResources=true zeroDateTimeBehavior=convertToNull useServerPrepStmts=false autoClosePStmtStreams=true processEscapeCodesForPrepStmts=false useFastDateParsing=false populateInsertRowWithDefaultValues=false useDirectRowUnpack=false * 5-0-Compat * useDirectRowUnpack=false * clusterBase * autoReconnect=true failOverReadOnly=false roundRobinLoadBalance=true * coldFusion * useDynamicCharsetInfo=false alwaysSendSetIsolation=false useLocalSessionState=true autoReconnect=true * fullDebug * profileSQL=true gatherPerMetrics=true useUsageAdvisor=true logSlowQueries=true explainSlowQueries=true * maxPerformance * cachePrepStmts=true cacheCallableStmts=true cacheServerConfiguration=true useLocalSessionState=true elideSetAutoCommits=true alwaysSendSetIsolation=false enableQueryTimeouts=false * solarisMaxPerformance * useUnbufferedInput=false useReadAheadInput=false maintainTimeStats=false  File: manual.info, Node: connector-j-reference-implementation-notes, Next: connector-j-reference-type-conversions, Prev: connector-j-reference-configuration-properties, Up: connector-j-reference 21.3.5.3 JDBC API Implementation Notes ...................................... MySQL Connector/J passes all of the tests in the publicly available version of Sun's JDBC compliance test suite. This section gives details on a interface-by-interface level about implementation decisions that might affect how you code applications with MySQL Connector/J. The JDBC specification is vague about how certain functionality should be implemented, or the specification enables leeway in implementation. * *BLOB* Starting with Connector/J version 3.1.0, you can emulate BLOBs with locators by adding the property `emulateLocators=true' to your JDBC URL. Using this method, the driver will delay loading the actual BLOB data until you retrieve the other data and then use retrieval methods (`getInputStream()', `getBytes()', and so forth) on the BLOB data stream. You must use a column alias with the value of the column to the actual name of the BLOB, for example: SELECT id, 'data' as blob_data from blobtable You must also follow these rules: * The *Note `SELECT': select. must reference only one table. The table must have a primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key). * The *Note `SELECT': select. must alias the original BLOB column name, specified as a string, to an alternate name. * The *Note `SELECT': select. must cover all columns that make up the primary key. The BLOB implementation does not allow in-place modification (they are copies, as reported by the `DatabaseMetaData.locatorsUpdateCopies()' method). Because of this, use the corresponding `PreparedStatement.setBlob()' or `ResultSet.updateBlob()' (in the case of updatable result sets) methods to save changes back to the database. * *CallableStatement* Starting with Connector/J 3.1.1, stored procedures are supported when connecting to MySQL version 5.0 or newer using the CallableStatement interface. Currently, the `getParameterMetaData()' method of CallableStatement is not supported. * *CLOB* The CLOB implementation does not allow in-place modification (they are copies, as reported by the `DatabaseMetaData.locatorsUpdateCopies()' method). Because of this, use the `PreparedStatement.setClob()' method to save changes back to the database. The JDBC API does not have a `ResultSet.updateClob()' method. * *Connection* Unlike the pre-Connector/J JDBC driver (`MM.MySQL'), the `isClosed()' method does not ping the server to determine if it is available. In accordance with the JDBC specification, it only returns true if `closed()' has been called on the connection. If you need to determine if the connection is still valid, issue a simple query, such as `SELECT 1'. The driver will throw an exception if the connection is no longer valid. * *DatabaseMetaData* Foreign key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_foreign_key) information (`getImportedKeys()'/`getExportedKeys()' and `getCrossReference()') is only available from *Note `InnoDB': innodb-storage-engine. tables. The driver uses *Note `SHOW CREATE TABLE': show-create-table. to retrieve this information, so if any other storage engines add support for foreign keys, the driver would transparently support them as well. * *PreparedStatement* PreparedStatements are implemented by the driver, as MySQL does not have a prepared statement feature. Because of this, the driver does not implement `getParameterMetaData()' or `getMetaData()' as it would require the driver to have a complete SQL parser in the client. Starting with version 3.1.0 MySQL Connector/J, server-side prepared statements and binary-encoded result sets are used when the server supports them. Take care when using a server-side prepared statement with *large* parameters that are set using `setBinaryStream()', `setAsciiStream()', `setUnicodeStream()', `setBlob()', or `setClob()'. To re-execute the statement with any large parameter changed to a nonlarge parameter, call `clearParameters()' and set all parameters again. The reason for this is as follows: * During both server-side prepared statements and client-side emulation, large data is exchanged only when `PreparedStatement.execute()' is called. * Once that has been done, the stream used to read the data on the client side is closed (as per the JDBC spec), and cannot be read from again. * If a parameter changes from large to nonlarge, the driver must reset the server-side state of the prepared statement to allow the parameter that is being changed to take the place of the prior large value. This removes all of the large data that has already been sent to the server, thus requiring the data to be re-sent, using the `setBinaryStream()', `setAsciiStream()', `setUnicodeStream()', `setBlob()' or `setClob()' method. Consequently, to change the type of a parameter to a nonlarge one, you must call `clearParameters()' and set all parameters of the prepared statement again before it can be re-executed. * *ResultSet* By default, ResultSets are completely retrieved and stored in memory. In most cases this is the most efficient way to operate, and due to the design of the MySQL network protocol is easier to implement. If you are working with ResultSets that have a large number of rows or large values, and cannot allocate heap space in your JVM for the memory required, you can tell the driver to stream the results back one row at a time. To enable this functionality, create a `Statement' instance in the following manner: stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY, java.sql.ResultSet.CONCUR_READ_ONLY); stmt.setFetchSize(Integer.MIN_VALUE); The combination of a forward-only, read-only result set, with a fetch size of `Integer.MIN_VALUE' serves as a signal to the driver to stream result sets row-by-row. After this, any result sets created with the statement will be retrieved row-by-row. There are some caveats with this approach. You must read all of the rows in the result set (or close it) before you can issue any other queries on the connection, or an exception will be thrown. The earliest the locks these statements hold can be released (whether they be `MyISAM' table-level locks or row-level locks in some other storage engine such as `InnoDB') is when the statement completes. If the statement is within scope of a transaction, then locks are released when the transaction completes (which implies that the statement needs to complete first). As with most other databases, statements are not complete until all the results pending on the statement are read or the active result set for the statement is closed. Therefore, if using streaming results, process them as quickly as possible if you want to maintain concurrent access to the tables referenced by the statement producing the result set. * *ResultSetMetaData* The `isAutoIncrement()' method only works when using MySQL servers 4.0 and newer. * *Statement* When using versions of the JDBC driver earlier than 3.2.1, and connected to server versions earlier than 5.0.3, the `setFetchSize()' method has no effect, other than to toggle result set streaming as described above. Connector/J 5.0.0 and later include support for both `Statement.cancel()' and `Statement.setQueryTimeout()'. Both require MySQL 5.0.0 or newer server, and require a separate connection to issue the *Note `KILL QUERY': kill. statement. In the case of `setQueryTimeout()', the implementation creates an additional thread to handle the timeout functionality. *Note*: Failures to cancel the statement for `setQueryTimeout()' may manifest themselves as `RuntimeException' rather than failing silently, as there is currently no way to unblock the thread that is executing the query being cancelled due to timeout expiration and have it throw the exception instead. *Note*: The MySQL statement *Note `KILL QUERY': kill. (which is what the driver uses to implement `Statement.cancel()') is non-deterministic; thus, avoid the use of `Statement.cancel()' if possible. If no query is in process, the next query issued will be killed by the server. This race condition is guarded against as of Connector/J 5.1.18. MySQL does not support SQL cursors, and the JDBC driver doesn't emulate them, so `setCursorName()' has no effect. Connector/J 5.1.3 and later include two additional methods: * `setLocalInfileInputStream()' sets an `InputStream' instance that will be used to send data to the MySQL server for a *Note `LOAD DATA LOCAL INFILE': load-data. statement rather than a `FileInputStream' or `URLInputStream' that represents the path given as an argument to the statement. This stream will be read to completion upon execution of a *Note `LOAD DATA LOCAL INFILE': load-data. statement, and will automatically be closed by the driver, so it needs to be reset before each call to `execute*()' that would cause the MySQL server to request data to fulfill the request for *Note `LOAD DATA LOCAL INFILE': load-data. If this value is set to `NULL', the driver will revert to using a `FileInputStream' or `URLInputStream' as required. * `getLocalInfileInputStream()' returns the `InputStream' instance that will be used to send data in response to a *Note `LOAD DATA LOCAL INFILE': load-data. statement. This method returns `NULL' if no such stream has been set using `setLocalInfileInputStream()'.  File: manual.info, Node: connector-j-reference-type-conversions, Next: connector-j-reference-charsets, Prev: connector-j-reference-implementation-notes, Up: connector-j-reference 21.3.5.4 Java, JDBC and MySQL Types ................................... MySQL Connector/J is flexible in the way it handles conversions between MySQL data types and Java data types. In general, any MySQL data type can be converted to a `java.lang.String', and any numeric type can be converted to any of the Java numeric types, although round-off, overflow, or loss of precision may occur. *Note*: All `TEXT' types return `Types.LONGVARCHAR' with different `getPrecision()' values (65535, 255, 16777215, and 2147483647 respectively) with `getColumnType()' returning `-1'. This behavior is intentional even though `TINYTEXT' does not fall, regarding to its size, within the `LONGVARCHAR' category. This is to avoid different handling inside the same base type. And `getColumnType()' returns `-1' because the internal server handling is of type `TEXT', which is similar to `BLOB'. Also note that `getColumnTypeName()' will return `VARCHAR' even though `getColumnType()' returns `Types.LONGVARCHAR', because `VARCHAR' is the designated column database-specific name for this type. Starting with Connector/J 3.1.0, the JDBC driver issues warnings or throws `DataTruncation' exceptions as is required by the JDBC specification unless the connection was configured not to do so by using the property `jdbcCompliantTruncation' and setting it to `false'. The conversions that are always guaranteed to work are listed in the following table. The first column lists one or more MySQL data types, and the second column lists one or more Java types to which the MySQL types can be converted. *Connection Properties - Miscellaneous* These MySQL Data Types Can always be converted to these Java types `CHAR, VARCHAR, BLOB, TEXT, ENUM, `java.lang.String, and SET' java.io.InputStream, java.io.Reader, java.sql.Blob, java.sql.Clob' `FLOAT, REAL, DOUBLE PRECISION, `java.lang.String, java.lang.Short, NUMERIC, DECIMAL, TINYINT, java.lang.Integer, java.lang.Long, SMALLINT, MEDIUMINT, INTEGER, java.lang.Double, BIGINT' java.math.BigDecimal' `DATE, TIME, DATETIME, TIMESTAMP' `java.lang.String, java.sql.Date, java.sql.Timestamp' *Note*: Round-off, overflow or loss of precision may occur if you choose a Java numeric data type that has less precision or capacity than the MySQL data type you are converting to/from. The ResultSet.getObject() method uses the type conversions between MySQL and Java types, following the JDBC specification where appropriate. The value returned by ResultSetMetaData.GetColumnClassName() is also shown below. For more information on the `java.sql.Types' classes see Java 2 Platform Types (http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Types.html). *MySQL Types to Java Types for ResultSet.getObject()* MySQL Type Name Return value of Returned as Java Class `GetColumnClassName' `BIT(1)' (new in `BIT' java.lang.Boolean MySQL-5.0) `BIT( > 1)' (new `BIT' byte[] in MySQL-5.0) `TINYINT' `TINYINT' java.lang.Boolean if the configuration property `tinyInt1isBit' is set to `true' (the default) and the storage size is 1, or java.lang.Integer if not. `BOOL', `BOOLEAN' `TINYINT' See `TINYINT', above as these are aliases for `TINYINT(1)', currently. `SMALLINT[(M)] `SMALLINT java.lang.Integer (regardless if [UNSIGNED]' [UNSIGNED]' `UNSIGNED' or not) `MEDIUMINT[(M)] `MEDIUMINT java.lang.Integer, if `UNSIGNED' [UNSIGNED]' [UNSIGNED]' java.lang.Long (C/J 3.1 and earlier), or java.lang.Integer for C/J 5.0 and later `INT,INTEGER[(M)] `INTEGER java.lang.Integer, if `UNSIGNED' [UNSIGNED]' [UNSIGNED]' java.lang.Long `BIGINT[(M)] `BIGINT java.lang.Long, if UNSIGNED [UNSIGNED]' [UNSIGNED]' java.math.BigInteger `FLOAT[(M,D)]' `FLOAT' java.lang.Float `DOUBLE[(M,B)]' `DOUBLE' java.lang.Double `DECIMAL[(M[,D])]' `DECIMAL' java.math.BigDecimal `DATE' `DATE' java.sql.Date `DATETIME' `DATETIME' java.sql.Timestamp `TIMESTAMP[(M)]' `TIMESTAMP' java.sql.Timestamp `TIME' `TIME' java.sql.Time `YEAR[(2|4)]' `YEAR' If `yearIsDateType' configuration property is set to `false', then the returned object type is java.sql.Short. If set to `true' (the default), then the returned object is of type java.sql.Date with the date set to January 1st, at midnight. `CHAR(M)' `CHAR' java.lang.String (unless the character set for the column is `BINARY', then byte[] is returned. `VARCHAR(M) `VARCHAR' java.lang.String (unless the [BINARY]' character set for the column is `BINARY', then byte[] is returned. `BINARY(M)' `BINARY' byte[] `VARBINARY(M)' `VARBINARY' byte[] `TINYBLOB' `TINYBLOB' byte[] `TINYTEXT' `VARCHAR' java.lang.String `BLOB' `BLOB' byte[] `TEXT' `VARCHAR' java.lang.String `MEDIUMBLOB' `MEDIUMBLOB' byte[] `MEDIUMTEXT' `VARCHAR' java.lang.String `LONGBLOB' `LONGBLOB' byte[] `LONGTEXT' `VARCHAR' java.lang.String `ENUM('value1','value2',...)'`CHAR' java.lang.String `SET('value1','value2',...)'`CHAR' java.lang.String  File: manual.info, Node: connector-j-reference-charsets, Next: connector-j-reference-using-ssl, Prev: connector-j-reference-type-conversions, Up: connector-j-reference 21.3.5.5 Using Character Sets and Unicode ......................................... All strings sent from the JDBC driver to the server are converted automatically from native Java Unicode form to the client character encoding, including all queries sent using `Statement.execute()', `Statement.executeUpdate()', `Statement.executeQuery()' as well as all PreparedStatement and CallableStatement parameters with the exclusion of parameters set using `setBytes()', `setBinaryStream()', `setAsciiStream()', `setUnicodeStream()' and `setBlob()'. * Number of Encodings Per Connection * In MySQL Server 4.1 and higher, Connector/J supports a single character encoding between client and server, and any number of character encodings for data returned by the server to the client in ResultSets. Prior to MySQL Server 4.1, Connector/J supported a single character encoding per connection, which could either be automatically detected from the server configuration, or could be configured by the user through the useUnicode and characterEncoding properties. * Setting the Character Encoding * The character encoding between client and server is automatically detected upon connection. You specify the encoding on the server using the `character_set_server' for server versions 4.1.0 and newer, and `character_set' system variable for server versions older than 4.1.0. The driver automatically uses the encoding specified by the server. For more information, see *Note charset-server::. For example, to use 4-byte UTF-8 character sets with Connector/J, configure the MySQL server with `character_set_server=utf8mb4', and leave `characterEncoding' out of the Connector/J connection string. Connector/J will then autodetect the UTF-8 setting. To override the automatically detected encoding on the client side, use the characterEncoding property in the URL used to connect to the server. To allow multiple character sets to be sent from the client, use the UTF-8 encoding, either by configuring `utf8' as the default server character set, or by configuring the JDBC driver to use UTF-8 through the `characterEncoding' property. When specifying character encodings on the client side, use Java-style names. The following table lists MySQL character set names and the corresponding Java-style names: *MySQL to Java Encoding Name Translations* MySQL Character Set Name Java-Style Character Encoding Name `ascii' `US-ASCII' `big5' `Big5' `gbk' `GBK' `sjis' `SJIS (or Cp932 or MS932 for MySQL Server < 4.1.11)' `cp932' `Cp932 or MS932 (MySQL Server > 4.1.11)' `gb2312' `EUC_CN' `ujis' `EUC_JP' `euckr' `EUC_KR' `latin1' `Cp1252' `latin2' `ISO8859_2' `greek' `ISO8859_7' `hebrew' `ISO8859_8' `cp866' `Cp866' `tis620' `TIS620' `cp1250' `Cp1250' `cp1251' `Cp1251' `cp1257' `Cp1257' `macroman' `MacRoman' `macce' `MacCentralEurope' `utf8' `UTF-8' `ucs2' `UnicodeBig' *Warning*: Do not issue the query `set names' with Connector/J, as the driver will not detect that the character set has changed, and will continue to use the character set detected during the initial connection setup.  File: manual.info, Node: connector-j-reference-using-ssl, Next: connector-j-using-pam, Prev: connector-j-reference-charsets, Up: connector-j-reference 21.3.5.6 Connecting Securely Using SSL ...................................... SSL in MySQL Connector/J encrypts all data (other than the initial handshake) between the JDBC driver and the server. The performance penalty for enabling SSL is an increase in query processing time between 35% and 50%, depending on the size of the query, and the amount of data it returns. For SSL support to work, you must have the following: * A JDK that includes JSSE (Java Secure Sockets Extension), like JDK-1.4.1 or newer. SSL does not currently work with a JDK that you can add JSSE to, like JDK-1.2.x or JDK-1.3.x due to the following JSSE bug: `http://developer.java.sun.com/developer/bugParade/bugs/4273544.html' * A MySQL server that supports SSL and has been compiled and configured to do so, which is MySQL 4.0.4 or later. For more information, see *Note configuring-for-ssl::. * A client certificate (covered later in this section) The system works through two Java truststore files, one file contains the certificate information for the server (`truststore' in the examples below). The other file contains the certificate for the client (`keystore' in the examples below). All Java truststore files are password protected by supplying a suitable password to the `keytool' when you create the files. You need the file names and associated passwords to create an SSL connection. You will first need to import the MySQL server CA Certificate into a Java truststore. A sample MySQL server CA Certificate is located in the `SSL' subdirectory of the MySQL source distribution. This is what SSL will use to determine if you are communicating with a secure MySQL server. Alternatively, use the CA Certificate that you have generated or been provided with by your SSL provider. To use Java's `keytool' to create a truststore in the current directory , and import the server's CA certificate (`cacert.pem'), you can do the following (assuming that `keytool' is in your path. The `keytool' is typically located in the `bin' subdirectory of your JDK or JRE): shell> keytool -import -alias mysqlServerCACert \ -file cacert.pem -keystore truststore Enter the password when prompted for the keystore file. Interaction with `keytool' looks like this: Enter keystore password: ********* Owner: EMAILADDRESS=walrus@example.com, CN=Walrus, O=MySQL AB, L=Orenburg, ST=Some-State, C=RU Issuer: EMAILADDRESS=walrus@example.com, CN=Walrus, O=MySQL AB, L=Orenburg, ST=Some-State, C=RU Serial number: 0 Valid from: Fri Aug 02 16:55:53 CDT 2002 until: Sat Aug 02 16:55:53 CDT 2003 Certificate fingerprints: MD5: 61:91:A0:F2:03:07:61:7A:81:38:66:DA:19:C4:8D:AB SHA1: 25:77:41:05:D5:AD:99:8C:14:8C:CA:68:9C:2F:B8:89:C3:34:4D:6C Trust this certificate? [no]: yes Certificate was added to keystore You then have two options: either import the client certificate that matches the CA certificate you just imported, or create a new client certificate. Importing an existing certificate requires the certificate to be in DER format. You can use `openssl' to convert an existing certificate into the new format. For example: shell> openssl x509 -outform DER -in client-cert.pem -out client.cert Now import the converted certificate into your keystore using `keytool': shell> keytool -import -file client.cert -keystore keystore -alias mysqlClientCertificate To generate your own client certificate, use `keytool' to create a suitable certificate and add it to the `keystore' file: shell> keytool -genkey -keyalg rsa \ -alias mysqlClientCertificate -keystore keystore Keytool will prompt you for the following information, and create a keystore named `keystore' in the current directory. Respond with information that is appropriate for your situation: Enter keystore password: ********* What is your first and last name? [Unknown]: Matthews What is the name of your organizational unit? [Unknown]: Software Development What is the name of your organization? [Unknown]: MySQL AB What is the name of your City or Locality? [Unknown]: Flossmoor What is the name of your State or Province? [Unknown]: IL What is the two-letter country code for this unit? [Unknown]: US Is correct? [no]: y Enter key password for (RETURN if same as keystore password): Finally, to get JSSE to use the keystore and truststore that you have generated, you need to set the following system properties when you start your JVM, replacing PATH_TO_KEYSTORE_FILE with the full path to the keystore file you created, PATH_TO_TRUSTSTORE_FILE with the path to the truststore file you created, and using the appropriate password values for each property. You can do this either on the command line: -Djavax.net.ssl.keyStore=PATH_TO_KEYSTORE_FILE -Djavax.net.ssl.keyStorePassword=PASSWORD -Djavax.net.ssl.trustStore=PATH_TO_TRUSTSTORE_FILE -Djavax.net.ssl.trustStorePassword=PASSWORD Or you can set the values directly within the application: System.setProperty("javax.net.ssl.keyStore","PATH_TO_KEYSTORE_FILE"); System.setProperty("javax.net.ssl.keyStorePassword","PASSWORD"); System.setProperty("javax.net.ssl.trustStore","PATH_TO_TRUSTSTORE_FILE"); System.setProperty("javax.net.ssl.trustStorePassword","PASSWORD"); You will also need to set `useSSL' to `true' in your connection parameters for MySQL Connector/J, either by adding `useSSL=true' to your URL, or by setting the property `useSSL' to `true' in the java.util.Properties instance you pass to `DriverManager.getConnection()'. You can test that SSL is working by turning on JSSE debugging (as detailed below), and look for the following key events: ... *** ClientHello, v3.1 RandomCookie: GMT: 1018531834 bytes = { 199, 148, 180, 215, 74, 12, » 54, 244, 0, 168, 55, 103, 215, 64, 16, 138, 225, 190, 132, 153, 2, » 217, 219, 239, 202, 19, 121, 78 } Session ID: {} Cipher Suites: { 0, 5, 0, 4, 0, 9, 0, 10, 0, 18, 0, 19, 0, 3, 0, 17 } Compression Methods: { 0 } *** [write] MD5 and SHA1 hashes: len = 59 0000: 01 00 00 37 03 01 3D B6 90 FA C7 94 B4 D7 4A 0C ...7..=.......J. 0010: 36 F4 00 A8 37 67 D7 40 10 8A E1 BE 84 99 02 D9 6...7g.@........ 0020: DB EF CA 13 79 4E 00 00 10 00 05 00 04 00 09 00 ....yN.......... 0030: 0A 00 12 00 13 00 03 00 11 01 00 ........... main, WRITE: SSL v3.1 Handshake, length = 59 main, READ: SSL v3.1 Handshake, length = 74 *** ServerHello, v3.1 RandomCookie: GMT: 1018577560 bytes = { 116, 50, 4, 103, 25, 100, 58, » 202, 79, 185, 178, 100, 215, 66, 254, 21, 83, 187, 190, 42, 170, 3, » 132, 110, 82, 148, 160, 92 } Session ID: {163, 227, 84, 53, 81, 127, 252, 254, 178, 179, 68, 63, » 182, 158, 30, 11, 150, 79, 170, 76, 255, 92, 15, 226, 24, 17, 177, » 219, 158, 177, 187, 143} Cipher Suite: { 0, 5 } Compression Method: 0 *** %% Created: [Session-1, SSL_RSA_WITH_RC4_128_SHA] ** SSL_RSA_WITH_RC4_128_SHA [read] MD5 and SHA1 hashes: len = 74 0000: 02 00 00 46 03 01 3D B6 43 98 74 32 04 67 19 64 ...F..=.C.t2.g.d 0010: 3A CA 4F B9 B2 64 D7 42 FE 15 53 BB BE 2A AA 03 :.O..d.B..S..*.. 0020: 84 6E 52 94 A0 5C 20 A3 E3 54 35 51 7F FC FE B2 .nR..\ ..T5Q.... 0030: B3 44 3F B6 9E 1E 0B 96 4F AA 4C FF 5C 0F E2 18 .D?.....O.L.\... 0040: 11 B1 DB 9E B1 BB 8F 00 05 00 .......... main, READ: SSL v3.1 Handshake, length = 1712 ... JSSE provides debugging (to `stdout') when you set the following system property: `-Djavax.net.debug=all' This will tell you what keystores and truststores are being used, as well as what is going on during the SSL handshake and certificate exchange. It will be helpful when trying to determine what is not working when trying to get an SSL connection to happen.  File: manual.info, Node: connector-j-using-pam, Next: connector-j-reference-replication-connection, Prev: connector-j-reference-using-ssl, Up: connector-j-reference 21.3.5.7 Connecting Using PAM Authentication ............................................ Java applications using Connector/J 5.1.21 and higher can can connect to MySQL servers that use the pluggable authentication module (PAM) authentication scheme. For PAM authentication to work, you must have the following: * A MySQL server that supports PAM authentication: a commercial distribution of MySQL 5.5.16 or higher. See The PAM Authentication Plugin (http://dev.mysql.com/doc/refman/5.5/en/pam-authentication-plugin.html) for more information. Connector/J implements the same cleartext authentication method as in The Cleartext Client-Side Authentication Plugin (http://dev.mysql.com/doc/refman/5.5/en/cleartext-authentication-plugin.html). * SSL capability, as explained in *Note connector-j-reference-using-ssl::. Because the PAM authentication scheme sends the original password to the server, the connection to the server must be encrypted. PAM authentication support is enabled by default in Connector/J 5.1.21 and up, so no extra configuration is needed. To disable the PAM authentication feature, specify `mysql_clear_password' (the method) or `com.mysql.jdbc.authentication.MysqlClearPasswordPlugin' (the class name) in the comma-separated list of arguments for the `disabledAuthenticationPlugins' connection option. See *Note connector-j-reference-configuration-properties:: for details about that connection option.  File: manual.info, Node: connector-j-reference-replication-connection, Next: connector-j-reference-error-sqlstates, Prev: connector-j-using-pam, Up: connector-j-reference 21.3.5.8 Using Master/Slave Replication with ReplicationConnection .................................................................. Connector/J 3.1.7 and higher includes a variant of the driver that will automatically send queries to a read/write master, or a failover or round-robin loadbalanced set of slaves based on the state of `Connection.getReadOnly()'. An application signals that it wants a transaction to be read-only by calling `Connection.setReadOnly(true)', this replication-aware connection will use one of the slave connections, which are load-balanced per-vm using a round-robin scheme (a given connection is sticky to a slave unless that slave is removed from service). If you have a write transaction, or if you have a read that is time-sensitive (remember, replication in MySQL is asynchronous), set the connection to be not read-only, by calling `Connection.setReadOnly(false)' and the driver will ensure that further calls are sent to the master MySQL server. The driver takes care of propagating the current state of autocommit, isolation level, and catalog between all of the connections that it uses to accomplish this load balancing functionality. To enable this functionality, use the `com.mysql.jdbc.ReplicationDriver' class when configuring your application server's connection pool or when creating an instance of a JDBC driver for your standalone application. Because it accepts the same URL format as the standard MySQL JDBC driver, `ReplicationDriver' does not currently work with `java.sql.DriverManager'-based connection creation unless it is the only MySQL JDBC driver registered with the `DriverManager' . Here is a short example of how `ReplicationDriver' might be used in a standalone application: import java.sql.Connection; import java.sql.ResultSet; import java.util.Properties; import com.mysql.jdbc.ReplicationDriver; public class ReplicationDriverDemo { public static void main(String[] args) throws Exception { ReplicationDriver driver = new ReplicationDriver(); Properties props = new Properties(); // We want this for failover on the slaves props.put("autoReconnect", "true"); // We want to load balance between the slaves props.put("roundRobinLoadBalance", "true"); props.put("user", "foo"); props.put("password", "bar"); // // Looks like a normal MySQL JDBC url, with a // comma-separated list of hosts, the first // being the 'master', the rest being any number // of slaves that the driver will load balance against // Connection conn = driver.connect("jdbc:mysql:replication://master,slave1,slave2,slave3/test", props); // // Perform read/write work on the master // by setting the read-only flag to "false" // conn.setReadOnly(false); conn.setAutoCommit(false); conn.createStatement().executeUpdate("UPDATE some_table ...."); conn.commit(); // // Now, do a query from a slave, the driver automatically picks one // from the list // conn.setReadOnly(true); ResultSet rs = conn.createStatement().executeQuery("SELECT a,b FROM alt_table"); ....... } } Consider investigating the Load Balancing JDBC Pool (`lbpool') tool, which provides a wrapper around the standard JDBC driver and enables you to use DB connection pools that includes checks for system failures and uneven load distribution. For more information, see Load Balancing JDBC Pool (lbpool) (http://code.tailrank.com/lbpool).  File: manual.info, Node: connector-j-reference-error-sqlstates, Prev: connector-j-reference-replication-connection, Up: connector-j-reference 21.3.5.9 Mapping MySQL Error Numbers to JDBC SQLState Codes ........................................................... The table below provides a mapping of the MySQL error numbers to JDBC `SQLState' values. *Mapping of MySQL Error Numbers to SQLStates* MySQL Error MySQL Error Name Legacy SQL Standard Number (X/Open) SQLState SQLState 1022 ER_DUP_KEY S1000 23000 1037 ER_OUTOFMEMORY S1001 HY001 1038 ER_OUT_OF_SORTMEMORY S1001 HY001 1040 ER_CON_COUNT_ERROR 08004 08004 1042 ER_BAD_HOST_ERROR 08004 08S01 1043 ER_HANDSHAKE_ERROR 08004 08S01 1044 ER_DBACCESS_DENIED_ERROR S1000 42000 1045 ER_ACCESS_DENIED_ERROR 28000 28000 1047 ER_UNKNOWN_COM_ERROR 08S01 HY000 1050 ER_TABLE_EXISTS_ERROR S1000 42S01 1051 ER_BAD_TABLE_ERROR 42S02 42S02 1052 ER_NON_UNIQ_ERROR S1000 23000 1053 ER_SERVER_SHUTDOWN S1000 08S01 1054 ER_BAD_FIELD_ERROR S0022 42S22 1055 ER_WRONG_FIELD_WITH_GROUP S1009 42000 1056 ER_WRONG_GROUP_FIELD S1009 42000 1057 ER_WRONG_SUM_SELECT S1009 42000 1058 ER_WRONG_VALUE_COUNT 21S01 21S01 1059 ER_TOO_LONG_IDENT S1009 42000 1060 ER_DUP_FIELDNAME S1009 42S21 1061 ER_DUP_KEYNAME S1009 42000 1062 ER_DUP_ENTRY S1009 23000 1063 ER_WRONG_FIELD_SPEC S1009 42000 1064 ER_PARSE_ERROR 42000 42000 1065 ER_EMPTY_QUERY 42000 42000 1066 ER_NONUNIQ_TABLE S1009 42000 1067 ER_INVALID_DEFAULT S1009 42000 1068 ER_MULTIPLE_PRI_KEY S1009 42000 1069 ER_TOO_MANY_KEYS S1009 42000 1070 ER_TOO_MANY_KEY_PARTS S1009 42000 1071 ER_TOO_LONG_KEY S1009 42000 1072 ER_KEY_COLUMN_DOES_NOT_EXITS S1009 42000 1073 ER_BLOB_USED_AS_KEY S1009 42000 1074 ER_TOO_BIG_FIELDLENGTH S1009 42000 1075 ER_WRONG_AUTO_KEY S1009 42000 1080 ER_FORCING_CLOSE S1000 08S01 1081 ER_IPSOCK_ERROR 08S01 08S01 1082 ER_NO_SUCH_INDEX S1009 42S12 1083 ER_WRONG_FIELD_TERMINATORS S1009 42000 1084 ER_BLOBS_AND_NO_TERMINATED S1009 42000 1090 ER_CANT_REMOVE_ALL_FIELDS S1000 42000 1091 ER_CANT_DROP_FIELD_OR_KEY S1000 42000 1101 ER_BLOB_CANT_HAVE_DEFAULT S1000 42000 1102 ER_WRONG_DB_NAME S1000 42000 1103 ER_WRONG_TABLE_NAME S1000 42000 1104 ER_TOO_BIG_SELECT S1000 42000 1106 ER_UNKNOWN_PROCEDURE S1000 42000 1107 ER_WRONG_PARAMCOUNT_TO_PROCEDURES1000 42000 1109 ER_UNKNOWN_TABLE S1000 42S02 1110 ER_FIELD_SPECIFIED_TWICE S1000 42000 1112 ER_UNSUPPORTED_EXTENSION S1000 42000 1113 ER_TABLE_MUST_HAVE_COLUMNS S1000 42000 1115 ER_UNKNOWN_CHARACTER_SET S1000 42000 1118 ER_TOO_BIG_ROWSIZE S1000 42000 1120 ER_WRONG_OUTER_JOIN S1000 42000 1121 ER_NULL_COLUMN_IN_INDEX S1000 42000 1129 ER_HOST_IS_BLOCKED 08004 HY000 1130 ER_HOST_NOT_PRIVILEGED 08004 HY000 1131 ER_PASSWORD_ANONYMOUS_USER S1000 42000 1132 ER_PASSWORD_NOT_ALLOWED S1000 42000 1133 ER_PASSWORD_NO_MATCH S1000 42000 1136 ER_WRONG_VALUE_COUNT_ON_ROW S1000 21S01 1138 ER_INVALID_USE_OF_NULL S1000 42000 1139 ER_REGEXP_ERROR S1000 42000 1140 ER_MIX_OF_GROUP_FUNC_AND_FIELDSS1000 42000 1141 ER_NONEXISTING_GRANT S1000 42000 1142 ER_TABLEACCESS_DENIED_ERROR S1000 42000 1143 ER_COLUMNACCESS_DENIED_ERROR S1000 42000 1144 ER_ILLEGAL_GRANT_FOR_TABLE S1000 42000 1145 ER_GRANT_WRONG_HOST_OR_USER S1000 42000 1146 ER_NO_SUCH_TABLE S1000 42S02 1147 ER_NONEXISTING_TABLE_GRANT S1000 42000 1148 ER_NOT_ALLOWED_COMMAND S1000 42000 1149 ER_SYNTAX_ERROR S1000 42000 1152 ER_ABORTING_CONNECTION S1000 08S01 1153 ER_NET_PACKET_TOO_LARGE S1000 08S01 1154 ER_NET_READ_ERROR_FROM_PIPE S1000 08S01 1155 ER_NET_FCNTL_ERROR S1000 08S01 1156 ER_NET_PACKETS_OUT_OF_ORDER S1000 08S01 1157 ER_NET_UNCOMPRESS_ERROR S1000 08S01 1158 ER_NET_READ_ERROR S1000 08S01 1159 ER_NET_READ_INTERRUPTED S1000 08S01 1160 ER_NET_ERROR_ON_WRITE S1000 08S01 1161 ER_NET_WRITE_INTERRUPTED S1000 08S01 1162 ER_TOO_LONG_STRING S1000 42000 1163 ER_TABLE_CANT_HANDLE_BLOB S1000 42000 1164 ER_TABLE_CANT_HANDLE_AUTO_INCREMENTS1000 42000 1166 ER_WRONG_COLUMN_NAME S1000 42000 1167 ER_WRONG_KEY_COLUMN S1000 42000 1169 ER_DUP_UNIQUE S1000 23000 1170 ER_BLOB_KEY_WITHOUT_LENGTH S1000 42000 1171 ER_PRIMARY_CANT_HAVE_NULL S1000 42000 1172 ER_TOO_MANY_ROWS S1000 42000 1173 ER_REQUIRES_PRIMARY_KEY S1000 42000 1177 ER_CHECK_NO_SUCH_TABLE S1000 42000 1178 ER_CHECK_NOT_IMPLEMENTED S1000 42000 1179 ER_CANT_DO_THIS_DURING_AN_TRANSACTIONS1000 25000 1184 ER_NEW_ABORTING_CONNECTION S1000 08S01 1189 ER_MASTER_NET_READ S1000 08S01 1190 ER_MASTER_NET_WRITE S1000 08S01 1203 ER_TOO_MANY_USER_CONNECTIONS S1000 42000 1205 ER_LOCK_WAIT_TIMEOUT 41000 41000 1207 ER_READ_ONLY_TRANSACTION S1000 25000 1211 ER_NO_PERMISSION_TO_CREATE_USERS1000 42000 1213 ER_LOCK_DEADLOCK 41000 40001 1216 ER_NO_REFERENCED_ROW S1000 23000 1217 ER_ROW_IS_REFERENCED S1000 23000 1218 ER_CONNECT_TO_MASTER S1000 08S01 1222 ER_WRONG_NUMBER_OF_COLUMNS_IN_SELECTS1000 21000 1226 ER_USER_LIMIT_REACHED S1000 42000 1230 ER_NO_DEFAULT S1000 42000 1231 ER_WRONG_VALUE_FOR_VAR S1000 42000 1232 ER_WRONG_TYPE_FOR_VAR S1000 42000 1234 ER_CANT_USE_OPTION_HERE S1000 42000 1235 ER_NOT_SUPPORTED_YET S1000 42000 1239 ER_WRONG_FK_DEF S1000 42000 1241 ER_OPERAND_COLUMNS S1000 21000 1242 ER_SUBQUERY_NO_1_ROW S1000 21000 1247 ER_ILLEGAL_REFERENCE S1000 42S22 1248 ER_DERIVED_MUST_HAVE_ALIAS S1000 42000 1249 ER_SELECT_REDUCED S1000 01000 1250 ER_TABLENAME_NOT_ALLOWED_HERE S1000 42000 1251 ER_NOT_SUPPORTED_AUTH_MODE S1000 08004 1252 ER_SPATIAL_CANT_HAVE_NULL S1000 42000 1253 ER_COLLATION_CHARSET_MISMATCH S1000 42000 1261 ER_WARN_TOO_FEW_RECORDS S1000 01000 1262 ER_WARN_TOO_MANY_RECORDS S1000 01000 1263 ER_WARN_NULL_TO_NOTNULL S1000 01000 1264 ER_WARN_DATA_OUT_OF_RANGE S1000 01000 1265 ER_WARN_DATA_TRUNCATED S1000 01000 1280 ER_WRONG_NAME_FOR_INDEX S1000 42000 1281 ER_WRONG_NAME_FOR_CATALOG S1000 42000 1286 ER_UNKNOWN_STORAGE_ENGINE S1000 42000  File: manual.info, Node: connector-j-usagenotes-basic, Next: connector-j-usagenotes-j2ee-concepts-connection-pooling, Prev: connector-j-reference, Up: connector-j 21.3.6 JDBC Concepts -------------------- * Menu: * connector-j-usagenotes-connect-drivermanager:: Connecting to MySQL Using the JDBC `DriverManager' Interface * connector-j-usagenotes-statements:: Using JDBC `Statement' Objects to Execute SQL * connector-j-usagenotes-statements-callable:: Using JDBC `CallableStatements' to Execute Stored Procedures * connector-j-usagenotes-last-insert-id:: Retrieving `AUTO_INCREMENT' Column Values through JDBC This section provides some general JDBC background.  File: manual.info, Node: connector-j-usagenotes-connect-drivermanager, Next: connector-j-usagenotes-statements, Prev: connector-j-usagenotes-basic, Up: connector-j-usagenotes-basic 21.3.6.1 Connecting to MySQL Using the JDBC `DriverManager' Interface ..................................................................... When you are using JDBC outside of an application server, the `DriverManager' class manages the establishment of Connections. Specify to the `DriverManager' which JDBC drivers to try to make Connections with. The easiest way to do this is to use `Class.forName()' on the class that implements the `java.sql.Driver' interface. With MySQL Connector/J, the name of this class is `com.mysql.jdbc.Driver'. With this method, you could use an external configuration file to supply the driver class name and driver parameters to use when connecting to a database. The following section of Java code shows how you might register MySQL Connector/J from the `main()' method of your application. If testing this code, first read the installation section at *Note connector-j-installing::, to make sure you have connector installed correctly and the `CLASSPATH' set up. Also, ensure that MySQL is configured to accept external TCP/IP connections. import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; // Notice, do not import com.mysql.jdbc.* // or you will have problems! public class LoadDriver { public static void main(String[] args) { try { // The newInstance() call is a work around for some // broken Java implementations Class.forName("com.mysql.jdbc.Driver").newInstance(); } catch (Exception ex) { // handle the error } } } After the driver has been registered with the `DriverManager', you can obtain a `Connection' instance that is connected to a particular database by calling `DriverManager.getConnection()': If you have not already done so, please review the section *Note connector-j-usagenotes-connect-drivermanager:: before working with these examples. This example shows how you can obtain a `Connection' instance from the `DriverManager'. There are a few different signatures for the `getConnection()' method. Consult the API documentation that comes with your JDK for more specific information on how to use them. import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; Connection conn = null; ... try { conn = DriverManager.getConnection("jdbc:mysql://localhost/test?" + "user=monty&password=greatsqldb"); // Do something with the Connection ... } catch (SQLException ex) { // handle any errors System.out.println("SQLException: " + ex.getMessage()); System.out.println("SQLState: " + ex.getSQLState()); System.out.println("VendorError: " + ex.getErrorCode()); } Once a Connection is established, it can be used to create Statement and PreparedStatement objects, as well as retrieve metadata about the database. This is explained in the following sections.  File: manual.info, Node: connector-j-usagenotes-statements, Next: connector-j-usagenotes-statements-callable, Prev: connector-j-usagenotes-connect-drivermanager, Up: connector-j-usagenotes-basic 21.3.6.2 Using JDBC `Statement' Objects to Execute SQL ...................................................... Statement objects allow you to execute basic SQL queries and retrieve the results through the `ResultSet' class, which is described later. To create a Statement instance, you call the `createStatement()' method on the `Connection' object you have retrieved using one of the `DriverManager.getConnection()' or `DataSource.getConnection()' methods described earlier. Once you have a Statement instance, you can execute a *Note `SELECT': select. query by calling the `executeQuery(String)' method with the SQL you want to use. To update data in the database, use the `executeUpdate(String SQL)' method. This method returns the number of rows matched by the update statement, not the number of rows that were modified. If you do not know ahead of time whether the SQL statement will be a *Note `SELECT': select. or an *Note `UPDATE': update./*Note `INSERT': insert, then you can use the `execute(String SQL)' method. This method will return true if the SQL query was a *Note `SELECT': select, or false if it was an *Note `UPDATE': update, *Note `INSERT': insert, or *Note `DELETE': delete. statement. If the statement was a *Note `SELECT': select. query, you can retrieve the results by calling the `getResultSet()' method. If the statement was an *Note `UPDATE': update, *Note `INSERT': insert, or *Note `DELETE': delete. statement, you can retrieve the affected rows count by calling `getUpdateCount()' on the Statement instance. import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; import java.sql.Statement; import java.sql.ResultSet; // assume that conn is an already created JDBC connection (see previous examples) Statement stmt = null; ResultSet rs = null; try { stmt = conn.createStatement(); rs = stmt.executeQuery("SELECT foo FROM bar"); // or alternatively, if you don't know ahead of time that // the query will be a SELECT... if (stmt.execute("SELECT foo FROM bar")) { rs = stmt.getResultSet(); } // Now do something with the ResultSet .... } catch (SQLException ex){ // handle any errors System.out.println("SQLException: " + ex.getMessage()); System.out.println("SQLState: " + ex.getSQLState()); System.out.println("VendorError: " + ex.getErrorCode()); } finally { // it is a good idea to release // resources in a finally{} block // in reverse-order of their creation // if they are no-longer needed if (rs != null) { try { rs.close(); } catch (SQLException sqlEx) { } // ignore rs = null; } if (stmt != null) { try { stmt.close(); } catch (SQLException sqlEx) { } // ignore stmt = null; } }  File: manual.info, Node: connector-j-usagenotes-statements-callable, Next: connector-j-usagenotes-last-insert-id, Prev: connector-j-usagenotes-statements, Up: connector-j-usagenotes-basic 21.3.6.3 Using JDBC `CallableStatements' to Execute Stored Procedures ..................................................................... Starting with MySQL server version 5.0 when used with Connector/J 3.1.1 or newer, the java.sql.CallableStatement interface is fully implemented with the exception of the `getParameterMetaData()' method. For more information on MySQL stored procedures, please refer to `http://dev.mysql.com/doc/mysql/en/stored-routines.html'. Connector/J exposes stored procedure functionality through JDBC's CallableStatement interface. *Note*: Current versions of MySQL server do not return enough information for the JDBC driver to provide result set metadata for callable statements. This means that when using `CallableStatement', `ResultSetMetaData' may return `NULL'. The following example shows a stored procedure that returns the value of inOutParam incremented by 1, and the string passed in using inputParam as a ResultSet: CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), \ INOUT inOutParam INT) BEGIN DECLARE z INT; SET z = inOutParam + 1; SET inOutParam = z; SELECT inputParam; SELECT CONCAT('zyxw', inputParam); END To use the `demoSp' procedure with Connector/J, follow these steps: 1. Prepare the callable statement by using `Connection.prepareCall()'. Notice that you have to use JDBC escape syntax, and that the parentheses surrounding the parameter placeholders are not optional: import java.sql.CallableStatement; ... // // Prepare a call to the stored procedure 'demoSp' // with two parameters // // Notice the use of JDBC-escape syntax ({call ...}) // CallableStatement cStmt = conn.prepareCall("{call demoSp(?, ?)}"); cStmt.setString(1, "abcdefg"); *Note*: `Connection.prepareCall()' is an expensive method, due to the metadata retrieval that the driver performs to support output parameters. For performance reasons, minimize unnecessary calls to `Connection.prepareCall()' by reusing CallableStatement instances in your code. 2. Register the output parameters (if any exist) To retrieve the values of output parameters (parameters specified as `OUT' or `INOUT' when you created the stored procedure), JDBC requires that they be specified before statement execution using the various `registerOutputParameter()' methods in the CallableStatement interface: import java.sql.Types; ... // // Connector/J supports both named and indexed // output parameters. You can register output // parameters using either method, as well // as retrieve output parameters using either // method, regardless of what method was // used to register them. // // The following examples show how to use // the various methods of registering // output parameters (you should of course // use only one registration per parameter). // // // Registers the second parameter as output, and // uses the type 'INTEGER' for values returned from // getObject() // cStmt.registerOutParameter(2, Types.INTEGER); // // Registers the named parameter 'inOutParam', and // uses the type 'INTEGER' for values returned from // getObject() // cStmt.registerOutParameter("inOutParam", Types.INTEGER); ... 3. Set the input parameters (if any exist) Input and in/out parameters are set as for PreparedStatement objects. However, CallableStatement also supports setting parameters by name: ... // // Set a parameter by index // cStmt.setString(1, "abcdefg"); // // Alternatively, set a parameter using // the parameter name // cStmt.setString("inputParameter", "abcdefg"); // // Set the 'in/out' parameter using an index // cStmt.setInt(2, 1); // // Alternatively, set the 'in/out' parameter // by name // cStmt.setInt("inOutParam", 1); ... 4. Execute the CallableStatement, and retrieve any result sets or output parameters. Although CallableStatement supports calling any of the Statement execute methods (`executeUpdate()', `executeQuery()' or `execute()'), the most flexible method to call is `execute()', as you do not need to know ahead of time if the stored procedure returns result sets: ... boolean hadResults = cStmt.execute(); // // Process all returned result sets // while (hadResults) { ResultSet rs = cStmt.getResultSet(); // process result set ... hadResults = cStmt.getMoreResults(); } // // Retrieve output parameters // // Connector/J supports both index-based and // name-based retrieval // int outputValue = cStmt.getInt(2); // index-based outputValue = cStmt.getInt("inOutParam"); // name-based ...  File: manual.info, Node: connector-j-usagenotes-last-insert-id, Prev: connector-j-usagenotes-statements-callable, Up: connector-j-usagenotes-basic 21.3.6.4 Retrieving `AUTO_INCREMENT' Column Values through JDBC ............................................................... Before version 3.0 of the JDBC API, there was no standard way of retrieving key values from databases that supported auto increment or identity columns. With older JDBC drivers for MySQL, you could always use a MySQL-specific method on the Statement interface, or issue the query `SELECT LAST_INSERT_ID()' after issuing an *Note `INSERT': insert. to a table that had an `AUTO_INCREMENT' key. Using the MySQL-specific method call isn't portable, and issuing a *Note `SELECT': select. to get the `AUTO_INCREMENT' key's value requires another round-trip to the database, which isn't as efficient as possible. The following code snippets demonstrate the three different ways to retrieve `AUTO_INCREMENT' values. First, we demonstrate the use of the new JDBC 3.0 method `getGeneratedKeys()' which is now the preferred method to use if you need to retrieve `AUTO_INCREMENT' keys and have access to JDBC 3.0. The second example shows how you can retrieve the same value using a standard `SELECT LAST_INSERT_ID()' query. The final example shows how updatable result sets can retrieve the `AUTO_INCREMENT' value when using the `insertRow()' method. Statement stmt = null; ResultSet rs = null; try { // // Create a Statement instance that we can use for // 'normal' result sets assuming you have a // Connection 'conn' to a MySQL database already // available stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY, java.sql.ResultSet.CONCUR_UPDATABLE); // // Issue the DDL queries for the table for this example // stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial"); stmt.executeUpdate( "CREATE TABLE autoIncTutorial (" + "priKey INT NOT NULL AUTO_INCREMENT, " + "dataField VARCHAR(64), PRIMARY KEY (priKey))"); // // Insert one row that will generate an AUTO INCREMENT // key in the 'priKey' field // stmt.executeUpdate( "INSERT INTO autoIncTutorial (dataField) " + "values ('Can I Get the Auto Increment Field?')", Statement.RETURN_GENERATED_KEYS); // // Example of using Statement.getGeneratedKeys() // to retrieve the value of an auto-increment // value // int autoIncKeyFromApi = -1; rs = stmt.getGeneratedKeys(); if (rs.next()) { autoIncKeyFromApi = rs.getInt(1); } else { // throw an exception from here } rs.close(); rs = null; System.out.println("Key returned from getGeneratedKeys():" + autoIncKeyFromApi); } finally { if (rs != null) { try { rs.close(); } catch (SQLException ex) { // ignore } } if (stmt != null) { try { stmt.close(); } catch (SQLException ex) { // ignore } } } Statement stmt = null; ResultSet rs = null; try { // // Create a Statement instance that we can use for // 'normal' result sets. stmt = conn.createStatement(); // // Issue the DDL queries for the table for this example // stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial"); stmt.executeUpdate( "CREATE TABLE autoIncTutorial (" + "priKey INT NOT NULL AUTO_INCREMENT, " + "dataField VARCHAR(64), PRIMARY KEY (priKey))"); // // Insert one row that will generate an AUTO INCREMENT // key in the 'priKey' field // stmt.executeUpdate( "INSERT INTO autoIncTutorial (dataField) " + "values ('Can I Get the Auto Increment Field?')"); // // Use the MySQL LAST_INSERT_ID() // function to do the same thing as getGeneratedKeys() // int autoIncKeyFromFunc = -1; rs = stmt.executeQuery("SELECT LAST_INSERT_ID()"); if (rs.next()) { autoIncKeyFromFunc = rs.getInt(1); } else { // throw an exception from here } rs.close(); System.out.println("Key returned from " + "'SELECT LAST_INSERT_ID()': " + autoIncKeyFromFunc); } finally { if (rs != null) { try { rs.close(); } catch (SQLException ex) { // ignore } } if (stmt != null) { try { stmt.close(); } catch (SQLException ex) { // ignore } } } Statement stmt = null; ResultSet rs = null; try { // // Create a Statement instance that we can use for // 'normal' result sets as well as an 'updatable' // one, assuming you have a Connection 'conn' to // a MySQL database already available // stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY, java.sql.ResultSet.CONCUR_UPDATABLE); // // Issue the DDL queries for the table for this example // stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial"); stmt.executeUpdate( "CREATE TABLE autoIncTutorial (" + "priKey INT NOT NULL AUTO_INCREMENT, " + "dataField VARCHAR(64), PRIMARY KEY (priKey))"); // // Example of retrieving an AUTO INCREMENT key // from an updatable result set // rs = stmt.executeQuery("SELECT priKey, dataField " + "FROM autoIncTutorial"); rs.moveToInsertRow(); rs.updateString("dataField", "AUTO INCREMENT here?"); rs.insertRow(); // // the driver adds rows at the end // rs.last(); // // We should now be on the row we just inserted // int autoIncKeyFromRS = rs.getInt("priKey"); rs.close(); rs = null; System.out.println("Key returned for inserted row: " + autoIncKeyFromRS); } finally { if (rs != null) { try { rs.close(); } catch (SQLException ex) { // ignore } } if (stmt != null) { try { stmt.close(); } catch (SQLException ex) { // ignore } } } Running the preceding example code should produce the following output: Key returned from getGeneratedKeys(): 1 Key returned from SELECT LAST_INSERT_ID(): 1 Key returned for inserted row: 2 At times, it can be tricky to use the `SELECT LAST_INSERT_ID()' query, as that function's value is scoped to a connection. So, if some other query happens on the same connection, the value is overwritten. On the other hand, the `getGeneratedKeys()' method is scoped by the Statement instance, so it can be used even if other queries happen on the same connection, but not on the same Statement instance.  File: manual.info, Node: connector-j-usagenotes-j2ee-concepts-connection-pooling, Next: connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections, Prev: connector-j-usagenotes-basic, Up: connector-j 21.3.7 Connection Pooling with Connector/J ------------------------------------------ Connection pooling is a technique of creating and managing a pool of connections that are ready for use by any thread (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_thread) that needs them. Connection pooling can greatly increase the performance of your Java application, while reducing overall resource usage. * How Connection Pooling Works * Most applications only need a thread to have access to a JDBC connection when they are actively processing a transaction (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction), which often takes only milliseconds to complete. When not processing a transaction, the connection sits idle. Connection pooling enables the idle connection to be used by some other thread to do useful work. In practice, when a thread needs to do work against a MySQL or other database with JDBC, it requests a connection from the pool. When the thread is finished using the connection, it returns it to the pool, so that it can be used by any other threads. When the connection is loaned out from the pool, it is used exclusively by the thread that requested it. From a programming point of view, it is the same as if your thread called `DriverManager.getConnection()' every time it needed a JDBC connection. With connection pooling, your thread may end up using either a new connection or an already-existing connection. * Benefits of Connection Pooling * The main benefits to connection pooling are: * Reduced connection creation time. Although this is not usually an issue with the quick connection setup that MySQL offers compared to other databases, creating new JDBC connections still incurs networking and JDBC driver overhead that will be avoided if connections are recycled. * Simplified programming model. When using connection pooling, each individual thread can act as though it has created its own JDBC connection, allowing you to use straightforward JDBC programming techniques. * Controlled resource usage. If you create a new connection every time a thread needs one, rather than using connection pooling, your application's resource usage can be wasteful and lead to unpredictable behavior under load. * Using Connection Pooling with Connector/J * Sun has standardized the concept of connection pooling in JDBC through the JDBC 2.0 Optional interfaces, and all major application servers have implementations of these APIs that work with MySQL Connector/J. Generally, you configure a connection pool in your application server configuration files, and access it through the Java Naming and Directory Interface (JNDI). The following code shows how you might use a connection pool from an application deployed in a J2EE application server: import java.sql.Connection; import java.sql.SQLException; import java.sql.Statement; import javax.naming.InitialContext; import javax.sql.DataSource; public class MyServletJspOrEjb { public void doSomething() throws Exception { /* * Create a JNDI Initial context to be able to * lookup the DataSource * * In production-level code, this should be cached as * an instance or static variable, as it can * be quite expensive to create a JNDI context. * * Note: This code only works when you are using servlets * or EJBs in a J2EE application server. If you are * using connection pooling in standalone Java code, you * will have to create/configure datasources using whatever * mechanisms your particular connection pooling library * provides. */ InitialContext ctx = new InitialContext(); /* * Lookup the DataSource, which will be backed by a pool * that the application server provides. DataSource instances * are also a good candidate for caching as an instance * variable, as JNDI lookups can be expensive as well. */ DataSource ds = (DataSource)ctx.lookup("java:comp/env/jdbc/MySQLDB"); /* * The following code is what would actually be in your * Servlet, JSP or EJB 'service' method...where you need * to work with a JDBC connection. */ Connection conn = null; Statement stmt = null; try { conn = ds.getConnection(); /* * Now, use normal JDBC programming to work with * MySQL, making sure to close each resource when you're * finished with it, which permits the connection pool * resources to be recovered as quickly as possible */ stmt = conn.createStatement(); stmt.execute("SOME SQL QUERY"); stmt.close(); stmt = null; conn.close(); conn = null; } finally { /* * close any jdbc instances here that weren't * explicitly closed during normal code path, so * that we don't 'leak' resources... */ if (stmt != null) { try { stmt.close(); } catch (sqlexception sqlex) { // ignore, as we can't do anything about it here } stmt = null; } if (conn != null) { try { conn.close(); } catch (sqlexception sqlex) { // ignore, as we can't do anything about it here } conn = null; } } } } As shown in the example above, after obtaining the JNDI `InitialContext', and looking up the `DataSource', the rest of the code follows familiar JDBC conventions. When using connection pooling, always make sure that connections, and anything created by them (such as statements or result sets) are closed. This rule applies no matter what happens in your code (exceptions, flow-of-control, and so forth). When these objects are closed, they can be re-used; otherwise, they will be stranded, which means that the MySQL server resources they represent (such as buffers, locks, or sockets) are tied up for some time, or in the worst case can be tied up forever. * Sizing the Connection Pool * Each connection to MySQL has overhead (memory, CPU, context switches, and so forth) on both the client and server side. Every connection limits how many resources there are available to your application as well as the MySQL server. Many of these resources will be used whether or not the connection is actually doing any useful work! Connection pools can be tuned to maximize performance, while keeping resource utilization below the point where your application will start to fail rather than just run slower. The optimal size for the connection pool depends on anticipated load and average database transaction time. In practice, the optimal connection pool size can be smaller than you might expect. If you take Sun's Java Petstore blueprint application for example, a connection pool of 15-20 connections can serve a relatively moderate load (600 concurrent users) using MySQL and Tomcat with acceptable response times. To correctly size a connection pool for your application, create load test scripts with tools such as Apache JMeter or The Grinder, and load test your application. An easy way to determine a starting point is to configure your connection pool's maximum number of connections to be unbounded, run a load test, and measure the largest amount of concurrently used connections. You can then work backward from there to determine what values of minimum and maximum pooled connections give the best performance for your particular application. * Validating Connections * MySQL Connector/J can validate the connection by executing a lightweight ping against a server. In the case of load-balanced connections, this is performed against all active pooled internal connections that are retained. This is beneficial to Java applications using connection pools, as the pool can use this feature to validate connections. Depending on your connection pool and configuration, this validation can be carried out at different times: 1. Before the pool returns a connection to the application. 2. When the application returns a connection to the pool. 3. During periodic checks of idle connections. To use this feature, specify a validation query in your connection pool that starts with `/* ping */'. Note that the syntax must be exactly as specified. This will cause the driver send a ping to the server and return a dummy lightweight result set. When using a `ReplicationConnection' or `LoadBalancedConnection', the ping will be sent across all active connections. It is critical that the syntax be specified correctly. The syntax needs to be exact for reasons of efficiency, as this test is done for every statement that is executed: protected static final String PING_MARKER = "/* ping */"; ... if (sql.charAt(0) == '/') { if (sql.startsWith(PING_MARKER)) { doPingInstead(); ... None of the following snippets will work, because the ping syntax is sensitive to whitespace, capitalization, and placement: sql = "/* PING */ SELECT 1"; sql = "SELECT 1 /* ping*/"; sql = "/*ping*/ SELECT 1"; sql = " /* ping */ SELECT 1"; sql = "/*to ping or not to ping*/ SELECT 1"; All of the previous statements will issue a normal `SELECT' statement and will *not* be transformed into the lightweight ping. Further, for load-balanced connections, the statement will be executed against one connection in the internal pool, rather than validating each underlying physical connection. This results in the non-active physical connections assuming a stale state, and they may die. If Connector/J then re-balances, it might select a dead connection, resulting in an exception being passed to the application. To help prevent this, you can use `loadBalanceValidateConnectionOnSwapServer' to validate the connection before use. If your Connector/J deployment uses a connection pool that allows you to specify a validation query, take advantage of it, but ensure that the query starts _exactly_ with `/* ping */'. This is particularly important if you are using the load-balancing or replication-aware features of Connector/J, as it will help keep alive connections which otherwise will go stale and die, causing problems later.  File: manual.info, Node: connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections, Next: connector-j-usagenotes-j2ee-concepts-load-balancing-failover, Prev: connector-j-usagenotes-j2ee-concepts-connection-pooling, Up: connector-j 21.3.8 Load Balancing with Connector/J -------------------------------------- Connector/J has long provided an effective means to distribute read/write load across multiple MySQL server instances for Cluster or master-master replication deployments. Starting with Connector/J 5.1.3, you can now dynamically configure load-balanced connections, with no service outage. In-process transactions are not lost, and no application exceptions are generated if any application is trying to use that particular server instance. There are two connection string options associated with this functionality: * `loadBalanceConnectionGroup' - This provides the ability to group connections from different sources. This allows you to manage these JDBC sources within a single class loader in any combination you choose. If they use the same configuration, and you want to manage them as a logical single group, give them the same name. This is the key property for management: if you do not define a name (string) for `loadBalanceConnectionGroup', you cannot manage the connections. All load-balanced connections sharing the same `loadBalanceConnectionGroup' value, regardless of how the application creates them, will be managed together. * `loadBalanceEnableJMX' - The ability to manage the connections is exposed when you define a `loadBalanceConnectionGroup', but if you want to manage this externally, enable JMX by setting this property to `true'. This enables a JMX implementation, which exposes the management and monitoring operations of a connection group. Further, start your application with the `-Dcom.sun.management.jmxremote' JVM flag. You can then perform connect and perform operations using a JMX client such as `jconsole'. Once a connection has been made using the correct connection string options, a number of monitoring properties are available: * Current active host count. * Current active physical connection count. * Current active logical connection count. * Total logical connections created. * Total transaction count. The following management operations can also be performed: * Add host. * Remove host. The JMX interface, `com.mysql.jdbc.jmx.LoadBalanceConnectionGroupManagerMBean', has the following methods: * `int getActiveHostCount(String group);' * `int getTotalHostCount(String group);' * `long getTotalLogicalConnectionCount(String group);' * `long getActiveLogicalConnectionCount(String group);' * `long getActivePhysicalConnectionCount(String group);' * `long getTotalPhysicalConnectionCount(String group);' * `long getTotalTransactionCount(String group);' * `void removeHost(String group, String host) throws SQLException;' * `void stopNewConnectionsToHost(String group, String host) throws SQLException;' * `void addHost(String group, String host, boolean forExisting);' * `String getActiveHostsList(String group);' * `String getRegisteredConnectionGroups();' The `getRegisteredConnectionGroups()' method returns the names of all connection groups defined in that class loader. You can test this setup with the following code: public class Test { private static String URL = "jdbc:mysql:loadbalance://" + "localhost:3306,localhost:3310/test?" + "loadBalanceConnectionGroup=first&loadBalanceEnableJMX=true"; public static void main(String[] args) throws Exception { new Thread(new Repeater()).start(); new Thread(new Repeater()).start(); new Thread(new Repeater()).start(); } static Connection getNewConnection() throws SQLException, ClassNotFoundException { Class.forName("com.mysql.jdbc.Driver"); return DriverManager.getConnection(URL, "root", ""); } static void executeSimpleTransaction(Connection c, int conn, int trans){ try { c.setAutoCommit(false); Statement s = c.createStatement(); s.executeQuery("SELECT SLEEP(1) /* Connection: " + conn + ", transaction: " + trans + " */"); c.commit(); } catch (SQLException e) { e.printStackTrace(); } } public static class Repeater implements Runnable { public void run() { for(int i=0; i < 100; i++){ try { Connection c = getNewConnection(); for(int j=0; j < 10; j++){ executeSimpleTransaction(c, i, j); Thread.sleep(Math.round(100 * Math.random())); } c.close(); Thread.sleep(100); } catch (Exception e) { e.printStackTrace(); } } } } } After compiling, the application can be started with the `-Dcom.sun.management.jmxremote' flag, to enable remote management. `jconsole' can then be started. The `Test' main class will be listed by `jconsole'. Select this and click `Connect'. You can then navigate to the `com.mysql.jdbc.jmx.LoadBalanceConnectionGroupManager' bean. At this point, you can click on various operations and examine the returned result. If you now had an additional instance of MySQL running on port 3309, you could ensure that Connector/J starts using it by using the `addHost()', which is exposed in `jconsole'. Note that these operations can be performed dynamically without having to stop the application running. For further information on the combination of load balancing and failover, see *Note connector-j-usagenotes-j2ee-concepts-load-balancing-failover::.  File: manual.info, Node: connector-j-usagenotes-j2ee-concepts-load-balancing-failover, Next: connector-j-interceptors, Prev: connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections, Up: connector-j 21.3.9 Failover with Connector/J -------------------------------- Connector/J provides a useful load-balancing implementation for Cluster or multi-master deployments, as explained in *Note connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections::. As of Connector/J 5.1.12, this same implementation is used for balancing load between read-only slaves with `ReplicationDriver'. When trying to balance workload between multiple servers, the driver has to determine when it is safe to swap servers, doing so in the middle of a transaction, for example, could cause problems. It is important not to lose state information. For this reason, Connector/J will only try to pick a new server when one of the following happens: 1. At transaction boundaries (transactions are explicitly committed or rolled back). 2. A communication exception (SQL State starting with "08") is encountered. 3. When a `SQLException' matches conditions defined by user, using the extension points defined by the `loadBalanceSQLStateFailover', `loadBalanceSQLExceptionSubclassFailover' or `loadBalanceExceptionChecker' properties. The third condition revolves around three new properties introduced with Connector/J 5.1.13. It allows you to control which `SQLException's trigger failover. * `loadBalanceExceptionChecker' - The `loadBalanceExceptionChecker' property is really the key. This takes a fully-qualified class name which implements the new `com.mysql.jdbc.LoadBalanceExceptionChecker' interface. This interface is very simple, and you only need to implement the following method: public boolean shouldExceptionTriggerFailover(SQLException ex) A `SQLException' is passed in, and a boolean returned. A value of `true' triggers a failover, `false' does not. You can use this to implement your own custom logic. An example where this might be useful is when dealing with transient errors when using MySQL Cluster, where certain buffers may become overloaded. The following code snippet illustrates this: public class NdbLoadBalanceExceptionChecker extends StandardLoadBalanceExceptionChecker { public boolean shouldExceptionTriggerFailover(SQLException ex) { return super.shouldExceptionTriggerFailover(ex) || checkNdbException(ex); } private boolean checkNdbException(SQLException ex){ // Have to parse the message since most NDB errors // are mapped to the same DEMC. return (ex.getMessage().startsWith("Lock wait timeout exceeded") || (ex.getMessage().startsWith("Got temporary error") && ex.getMessage().endsWith("from NDB"))); } } The code above extends `com.mysql.jdbc.StandardLoadBalanceExceptionChecker', which is the default implementation. There are a few convenient shortcuts built into this, for those who want to have some level of control using properties, without writing Java code. This default implementation uses the two remaining properties: `loadBalanceSQLStateFailover' and `loadBalanceSQLExceptionSubclassFailover'. * `loadBalanceSQLStateFailover' - allows you to define a comma-delimited list of `SQLState' code prefixes, against which a `SQLException' is compared. If the prefix matches, failover is triggered. So, for example, the following would trigger a failover if a given `SQLException' starts with "00", or is "12345": loadBalanceSQLStateFailover=00,12345 * `loadBalanceSQLExceptionSubclassFailover' - can be used in conjunction with `loadBalanceSQLStateFailover' or on its own. If you want certain subclasses of `SQLException' to trigger failover, simply provide a comma-delimited list of fully-qualified class or interface names to check against. For example, if you want all `SQLTransientConnectionExceptions' to trigger failover, you would specify: loadBalanceSQLExceptionSubclassFailover=java.sql.SQLTransientConnectionException While the three fail-over conditions enumerated earlier suit most situations, if `autocommit' is enabled, Connector/J never re-balances, and continues using the same physical connection. This can be problematic, particularly when load-balancing is being used to distribute read-only load across multiple slaves. However, Connector/J can be configured to re-balance after a certain number of statements are executed, when `autocommit' is enabled. This functionality is dependent upon the following properties: * `loadBalanceAutoCommitStatementThreshold' - defines the number of matching statements which will trigger the driver to potentially swap physical server connections. The default value, 0, retains the behavior that connections with `autocommit' enabled are never balanced. * `loadBalanceAutoCommitStatementRegex' - the regular expression against which statements must match. The default value, blank, matches all statements. So, for example, using the following properties will cause Connector/J to re-balance after every third statement that contains the string `test': loadBalanceAutoCommitStatementThreshold=3 loadBalanceAutoCommitStatementRegex=.*test.* `loadBalanceAutoCommitStatementRegex' can prove useful in a number of situations. Your application may use temporary tables, server-side session state variables, or connection state, where letting the driver arbitrarily swap physical connections before processing is complete could cause data loss or other problems. This allows you to identify a trigger statement that is only executed when it is safe to swap physical connections.  File: manual.info, Node: connector-j-interceptors, Next: connector-j-usagenotes-tomcat, Prev: connector-j-usagenotes-j2ee-concepts-load-balancing-failover, Up: connector-j 21.3.10 Using the Connector/J Interceptor Classes ------------------------------------------------- An interceptor is a software design pattern that provides a transparent way to extend or modify some aspect of a program, similar to a user exit. No recompiling is required. With Connector/J, the interceptors are enabled and disabled by updating the connection string to refer to different sets of interceptor classes that you instantiate. The connection properties that control the interceptors are explained in *Note connector-j-reference-configuration-properties::: * `connectionLifecycleInterceptors', where you specify the fully qualified names of classes that implement the `com.mysql.jdbc.ConnectionLifecycleInterceptor' interface. In these kinds of interceptor classes, you might log events such as rollbacks, measure the time between transaction start and end, or count events such as calls to `setAutoCommit()'. * `exceptionInterceptors', where you specify the fully qualified names of classes that implement the `com.mysql.jdbc.ExceptionInterceptor' interface. In these kinds of interceptor classes, you might add extra diagnostic information to exceptions that can have multiple causes or indicate a problem with server settings. Because `exceptionInterceptors' classes are only called when handling a `SQLException' thrown from Connector/J code, they can be used even in production deployments without substantial performance overhead. * `statementInterceptors', where you specify the fully qualified names of classes that implement the `com.mysql.jdbc.StatementInterceptorV2' interface. In these kinds of interceptor classes, you might change or augment the processing done by certain kinds of statements, such as automatically checking for queried data in a `memcached' server, rewriting slow queries, logging information about statement execution, or route requests to remote servers.  File: manual.info, Node: connector-j-usagenotes-tomcat, Next: connector-j-usagenotes-jboss, Prev: connector-j-interceptors, Up: connector-j 21.3.11 Using Connector/J with Tomcat ------------------------------------- The following instructions are based on the instructions for Tomcat-5.x, available at `http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html' which is current at the time this document was written. First, install the `.jar' file that comes with Connector/J in `$CATALINA_HOME/common/lib' so that it is available to all applications installed in the container. Next, configure the JNDI DataSource by adding a declaration resource to `$CATALINA_HOME/conf/server.xml' in the context that defines your web application: ... factory org.apache.commons.dbcp.BasicDataSourceFactory maxActive 10 maxIdle 5 validationQuery SELECT 1 testOnBorrow true testWhileIdle true timeBetweenEvictionRunsMillis 10000 minEvictableIdleTimeMillis 60000 username someuser password somepass driverClassName com.mysql.jdbc.Driver url jdbc:mysql://localhost:3306/test Note that Connector/J 5.1.3 introduced a facility whereby, rather than use a `validationQuery' value of `SELECT 1', it is possible to use `validationQuery' with a value set to `/* ping */'. This sends a ping to the server which then returns a fake result set. This is a lighter weight solution. It also has the advantage that if using `ReplicationConnection' or `LoadBalancedConnection' type connections, the ping will be sent across all active connections. The following XML snippet illustrates how to select this option: validationQuery /* ping */ Note that `/* ping */' has to be specified exactly. In general, follow the installation instructions that come with your version of Tomcat, as the way you configure datasources in Tomcat changes from time to time, and if you use the wrong syntax in your XML file, you will most likely end up with an exception similar to the following: Error: java.sql.SQLException: Cannot load JDBC driver class 'null ' SQL state: null Note that the auto-loading of drivers having the `META-INF/service/java.sql.Driver' class in JDBC 4.0 causes an improper undeployment of the Connector/J driver in Tomcat on Windows. Namely, the Connector/J jar remains locked. This is an initialization problem that is not related to the driver. The possible workarounds, if viable, are as follows: use "`antiResourceLocking=true'" as a Tomcat Context attribute, or remove the `META-INF/' directory.  File: manual.info, Node: connector-j-usagenotes-jboss, Next: connector-j-usagenotes-spring-config, Prev: connector-j-usagenotes-tomcat, Up: connector-j 21.3.12 Using Connector/J with JBoss ------------------------------------ These instructions cover JBoss-4.x. To make the JDBC driver classes available to the application server, copy the `.jar' file that comes with Connector/J to the `lib' directory for your server configuration (which is usually called `default'). Then, in the same configuration directory, in the subdirectory named deploy, create a datasource configuration file that ends with `-ds.xml', which tells JBoss to deploy this file as a JDBC Datasource. The file should have the following contents: MySQLDB jdbc:mysql://localhost:3306/dbname com.mysql.jdbc.Driver user pass 5 20 5 com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker  File: manual.info, Node: connector-j-usagenotes-spring-config, Next: connector-j-usagenotes-glassfish-config, Prev: connector-j-usagenotes-jboss, Up: connector-j 21.3.13 Using Connector/J with Spring ------------------------------------- * Menu: * connector-j-usagenotes-spring-config-jdbctemplate:: Using JdbcTemplate * connector-j-usagenotes-spring-config-transactional:: Transactional JDBC Access * connector-j-usagenotes-spring-config-connpooling:: Connection Pooling with Spring The Spring Framework is a Java-based application framework designed for assisting in application design by providing a way to configure components. The technique used by Spring is a well known design pattern called Dependency Injection (see Inversion of Control Containers and the Dependency Injection pattern (http://www.martinfowler.com/articles/injection.html)). This article will focus on Java-oriented access to MySQL databases with Spring 2.0. For those wondering, there is a .NET port of Spring appropriately named Spring.NET. Spring is not only a system for configuring components, but also includes support for aspect oriented programming (AOP). This is one of the main benefits and the foundation for Spring's resource and transaction management. Spring also provides utilities for integrating resource management with JDBC and Hibernate. For the examples in this section the MySQL world sample database will be used. The first task is to set up a MySQL data source through Spring. Components within Spring use the `bean' terminology. For example, to configure a connection to a MySQL server supporting the world sample database, you might use: In the above example, we are assigning values to properties that will be used in the configuration. For the datasource configuration: The placeholders are used to provide values for properties of this bean. This means that you can specify all the properties of the configuration in one place instead of entering the values for each property on each bean. We do, however, need one more bean to pull this all together. The last bean is responsible for actually replacing the placeholders with the property values. Now that we have our MySQL data source configured and ready to go, we write some Java code to access it. The example below will retrieve three random cities and their corresponding country using the data source we configured with Spring. // Create a new application context. this processes the Spring config ApplicationContext ctx = new ClassPathXmlApplicationContext("ex1appContext.xml"); // Retrieve the data source from the application context DataSource ds = (DataSource) ctx.getBean("dataSource"); // Open a database connection using Spring's DataSourceUtils Connection c = DataSourceUtils.getConnection(ds); try { // retrieve a list of three random cities PreparedStatement ps = c.prepareStatement( "select City.Name as 'City', Country.Name as 'Country' " + "from City inner join Country on City.CountryCode = Country.Code " + "order by rand() limit 3"); ResultSet rs = ps.executeQuery(); while(rs.next()) { String city = rs.getString("City"); String country = rs.getString("Country"); System.out.printf("The city %s is in %s%n", city, country); } } catch (SQLException ex) { // something has failed and we print a stack trace to analyse the error ex.printStackTrace(); // ignore failure closing connection try { c.close(); } catch (SQLException e) { } } finally { // properly release our connection DataSourceUtils.releaseConnection(c, ds); } This is very similar to normal JDBC access to MySQL with the main difference being that we are using DataSourceUtils instead of the DriverManager to create the connection. While it may seem like a small difference, the implications are somewhat far reaching. Spring manages this resource in a way similar to a container managed data source in a J2EE application server. When a connection is opened, it can be subsequently accessed in other parts of the code if it is synchronized with a transaction. This makes it possible to treat different parts of your application as transactional instead of passing around a database connection.  File: manual.info, Node: connector-j-usagenotes-spring-config-jdbctemplate, Next: connector-j-usagenotes-spring-config-transactional, Prev: connector-j-usagenotes-spring-config, Up: connector-j-usagenotes-spring-config 21.3.13.1 Using JdbcTemplate ............................ Spring makes extensive use of the Template method design pattern (see Template Method Pattern (http://en.wikipedia.org/wiki/Template_method_pattern)). Our immediate focus will be on the `JdbcTemplate' and related classes, specifically `NamedParameterJdbcTemplate'. The template classes handle obtaining and releasing a connection for data access when one is needed. The next example shows how to use `NamedParameterJdbcTemplate' inside of a DAO (Data Access Object) class to retrieve a random city given a country code. public class Ex2JdbcDao { /** * Data source reference which will be provided by Spring. */ private DataSource dataSource; /** * Our query to find a random city given a country code. Notice * the ":country" parameter toward the end. This is called a * named parameter. */ private String queryString = "select Name from City " + "where CountryCode = :country order by rand() limit 1"; /** * Retrieve a random city using Spring JDBC access classes. */ public String getRandomCityByCountryCode(String cntryCode) { // A template that permits using queries with named parameters NamedParameterJdbcTemplate template = new NamedParameterJdbcTemplate(dataSource); // A java.util.Map is used to provide values for the parameters Map params = new HashMap(); params.put("country", cntryCode); // We query for an Object and specify what class we are expecting return (String)template.queryForObject(queryString, params, String.class); } /** * A JavaBean setter-style method to allow Spring to inject the data source. * @param dataSource */ public void setDataSource(DataSource dataSource) { this.dataSource = dataSource; } } The focus in the above code is on the `getRandomCityByCountryCode()' method. We pass a country code and use the `NamedParameterJdbcTemplate' to query for a city. The country code is placed in a Map with the key "country", which is the parameter is named in the SQL query. To access this code, you need to configure it with Spring by providing a reference to the data source. At this point, we can just grab a reference to the DAO from Spring and call `getRandomCityByCountryCode()'. // Create the application context ApplicationContext ctx = new ClassPathXmlApplicationContext("ex2appContext.xml"); // Obtain a reference to our DAO Ex2JdbcDao dao = (Ex2JdbcDao) ctx.getBean("dao"); String countryCode = "USA"; // Find a few random cities in the US for(int i = 0; i < 4; ++i) System.out.printf("A random city in %s is %s%n", countryCode, dao.getRandomCityByCountryCode(countryCode)); This example shows how to use Spring's JDBC classes to completely abstract away the use of traditional JDBC classes including `Connection' and `PreparedStatement'.  File: manual.info, Node: connector-j-usagenotes-spring-config-transactional, Next: connector-j-usagenotes-spring-config-connpooling, Prev: connector-j-usagenotes-spring-config-jdbctemplate, Up: connector-j-usagenotes-spring-config 21.3.13.2 Transactional JDBC Access ................................... You might be wondering how we can add transactions into our code if we do not deal directly with the JDBC classes. Spring provides a transaction management package that not only replaces JDBC transaction management, but also enables declarative transaction management (configuration instead of code). To use transactional database access, we will need to change the storage engine of the tables in the world database. The downloaded script explicitly creates MyISAM tables which do not support transactional semantics. The InnoDB storage engine does support transactions and this is what we will be using. We can change the storage engine with the following statements. ALTER TABLE City ENGINE=InnoDB; ALTER TABLE Country ENGINE=InnoDB; ALTER TABLE CountryLanguage ENGINE=InnoDB; A good programming practice emphasized by Spring is separating interfaces and implementations. What this means is that we can create a Java interface and only use the operations on this interface without any internal knowledge of what the actual implementation is. We will let Spring manage the implementation and with this it will manage the transactions for our implementation. First you create a simple interface: public interface Ex3Dao { Integer createCity(String name, String countryCode, String district, Integer population); } This interface contains one method that will create a new city record in the database and return the id of the new record. Next you need to create an implementation of this interface. public class Ex3DaoImpl implements Ex3Dao { protected DataSource dataSource; protected SqlUpdate updateQuery; protected SqlFunction idQuery; public Integer createCity(String name, String countryCode, String district, Integer population) { updateQuery.update(new Object[] { name, countryCode, district, population }); return getLastId(); } protected Integer getLastId() { return idQuery.run(); } } You can see that we only operate on abstract query objects here and do not deal directly with the JDBC API. Also, this is the complete implementation. All of our transaction management will be dealt with in the configuration. To get the configuration started, we need to create the DAO. ... ... Now you need to set up the transaction configuration. The first thing you must do is create transaction manager to manage the data source and a specification of what transaction properties are required for the `dao' methods. The preceding code creates a transaction manager that handles transactions for the data source provided to it. The `txAdvice' uses this transaction manager and the attributes specify to create a transaction for all methods. Finally you need to apply this advice with an AOP pointcut. This basically says that all methods called on the `Ex3Dao' interface will be wrapped in a transaction. To make use of this, you only have to retrieve the `dao' from the application context and call a method on the `dao' instance. Ex3Dao dao = (Ex3Dao) ctx.getBean("dao"); Integer id = dao.createCity(name, countryCode, district, pop); We can verify from this that there is no transaction management happening in our Java code and it is all configured with Spring. This is a very powerful notion and regarded as one of the most beneficial features of Spring.  File: manual.info, Node: connector-j-usagenotes-spring-config-connpooling, Prev: connector-j-usagenotes-spring-config-transactional, Up: connector-j-usagenotes-spring-config 21.3.13.3 Connection Pooling with Spring ........................................ In many situations, such as web applications, there will be a large number of small database transactions. When this is the case, it usually makes sense to create a pool of database connections available for web requests as needed. Although MySQL does not spawn an extra process when a connection is made, there is still a small amount of overhead to create and set up the connection. Pooling of connections also alleviates problems such as collecting large amounts of sockets in the `TIME_WAIT' state. Setting up pooling of MySQL connections with Spring is as simple as changing the data source configuration in the application context. There are a number of configurations that we can use. The first example is based on the Jakarta Commons DBCP library (http://jakarta.apache.org/commons/dbcp/). The example below replaces the source configuration that was based on `DriverManagerDataSource' with DBCP's BasicDataSource. The configuration of the two solutions is very similar. The difference is that DBCP will pool connections to the database instead of creating a new connection every time one is requested. We have also set a parameter here called `initialSize'. This tells DBCP that we want three connections in the pool when it is created. Another way to configure connection pooling is to configure a data source in our J2EE application server. Using JBoss as an example, you can set up the MySQL connection pool by creating a file called `mysql-local-ds.xml' and placing it in the server/default/deploy directory in JBoss. Once we have this setup, we can use JNDI to look it up. With Spring, this lookup is very simple. The data source configuration looks like this.  File: manual.info, Node: connector-j-usagenotes-glassfish-config, Next: connector-j-usagenotes-troubleshooting, Prev: connector-j-usagenotes-spring-config, Up: connector-j 21.3.14 Using Connector/J with GlassFish ---------------------------------------- * Menu: * connector-j-usagenotes-glassfish-config-jsp:: A Simple JSP Application with Glassfish, Connector/J and MySQL * connector-j-usagenotes-glassfish-config-servlet:: A Simple Servlet with Glassfish, Connector/J and MySQL This section explains how to use MySQL Connector/J with Glassfish (tm) Server Open Source Edition 3.0.1. Glassfish can be downloaded from the Glassfish website (https://glassfish.dev.java.net/public/downloadsindex.html#top). Once Glassfish is installed you will need to make sure it can access MySQL Connector/J. To do this copy the MySQL Connector/J JAR file to the directory `GLASSFISH_INSTALL/glassfish/lib'. For example, copy `mysql-connector-java-5.1.12-bin.jar' to `C:\glassfishv3\glassfish\lib'. Restart the Glassfish Application Server. You are now ready to create JDBC Connection Pools and JDBC Resources. *Creating a Connection Pool* 1. In the Glassfish Administration Console, using the navigation tree navigate to `Resources', `JDBC', `Connection Pools'. 2. In the `JDBC Connection Pools' frame click `New'. You will enter a two step wizard. 3. In the `Name' field under `General Settings' enter the name for the connection pool, for example enter MySQLConnPool. 4. In the `Resource Type' field, select `javax.sql.DataSource' from the drop-down listbox. 5. In the `Database Vendor' field, select `MySQL' from the drop-down listbox. Click `Next' to go to the next page of the wizard. 6. You can accept the default settings for General Settings, Pool Settings and Transactions for this example. Scroll down to Additional Properties. 7. In Additional Properties you will need to ensure the following properties are set: * *ServerName* - The server to connect to. For local testing this will be `localhost'. * *User* - The user name with which to connect to MySQL. * *Password* - The corresponding password for the user. * *DatabaseName* - The database to connect to, for example the sample MySQL database `World'. 8. Click `Finish' to exit the wizard. You will be taken to the `JDBC Connection Pools' page where all current connection pools, including the one you just created, will be displayed. 9. In the `JDBC Connection Pools' frame click on the connection pool you just created. Here, you can review and edit information about the connection pool. Because Connector/J does not support optimized validation queries, go to the `Advanced' tab, and under Connection Validation, configure the following settings: * *Connection Validation* - select `Required'. * *Validation Method* - select `table' from the drop-down menu. * *Table Name* - enter `DUAL'. 10. To test your connection pool click the `Ping' button at the top of the frame. A message will be displayed confirming correct operation or otherwise. If an error message is received recheck the previous steps, and ensure that MySQL Connector/J has been correctly copied into the previously specified location. Now that you have created a connection pool you will also need to create a JDBC Resource (data source) for use by your application. *Creating a JDBC Resource* Your Java application will usually reference a data source object to establish a connection with the database. This needs to be created first using the following procedure. * Using the navigation tree in the Glassfish Administration Console, navigate to `Resources', `JDBC', `JDBC Resources'. A list of resources will be displayed in the `JDBC Resources' frame. * Click `New'. The `New JDBC Resource' frame will be displayed. * In the `JNDI Name' field, enter the JNDI name that will be used to access this resource, for example enter jdbc/MySQLDataSource. * In the `Pool Name' field, select a connection pool you want this resource to use from the drop-down listbox. * Optionally, you can enter a description into the `Description' field. * Additional properties can be added if required. * Click `OK' to create the new JDBC resource. The `JDBC Resources' frame will list all available JDBC Resources.  File: manual.info, Node: connector-j-usagenotes-glassfish-config-jsp, Next: connector-j-usagenotes-glassfish-config-servlet, Prev: connector-j-usagenotes-glassfish-config, Up: connector-j-usagenotes-glassfish-config 21.3.14.1 A Simple JSP Application with Glassfish, Connector/J and MySQL ........................................................................ This section shows how to deploy a simple JSP application on Glassfish, that connects to a MySQL database. This example assumes you have already set up a suitable Connection Pool and JDBC Resource, as explained in the preceding sections. It is also assumed you have a sample database installed, such as `world'. The main application code, `index.jsp' is presented here: <%@ page import="java.sql.*, javax.sql.*, java.io.*, javax.naming.*" %> Hello world from JSP <% InitialContext ctx; DataSource ds; Connection conn; Statement stmt; ResultSet rs; try { ctx = new InitialContext(); ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource"); //ds = (DataSource) ctx.lookup("jdbc/MySQLDataSource"); conn = ds.getConnection(); stmt = conn.createStatement(); rs = stmt.executeQuery("SELECT * FROM Country"); while(rs.next()) { %>

Name: <%= rs.getString("Name") %>

Population: <%= rs.getString("Population") %>

<% } } catch (SQLException se) { %> <%= se.getMessage() %> <% } catch (NamingException ne) { %> <%= ne.getMessage() %> <% } %> In addition two XML files are required: `web.xml', and `sun-web.xml'. There may be other files present, such as classes and images. These files are organized into the directory structure as follows: index.jsp WEB-INF | - web.xml - sun-web.xml The code for `web.xml' is: HelloWebApp jdbc/MySQLDataSource javax.sql.DataSource Container Shareable The code for `sun-web.xml' is: HelloWebApp jdbc/MySQLDataSource jdbc/MySQLDataSource These XML files illustrate a very important aspect of running JDBC applications on Glassfish. On Glassfish it is important to map the string specified for a JDBC resource to its JNDI name, as set up in the Glassfish administration console. In this example, the JNDI name for the JDBC resource, as specified in the Glassfish Administration console when creating the JDBC Resource, was `jdbc/MySQLDataSource'. This must be mapped to the name given in the application. In this example the name specified in the application, `jdbc/MySQLDataSource', and the JNDI name, happen to be the same, but this does not necessarily have to be the case. Note that the XML element is used to specify the name as used in the application source code, and this is mapped to the JNDI name specified using the element, in the file `sun-web.xml'. The resource also has to be created in the `web.xml' file, although the mapping of the resource to a JNDI name takes place in the `sun-web.xml' file. If you do not have this mapping set up correctly in the XML files you will not be able to lookup the data source using a JNDI lookup string such as: ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource"); You will still be able to access the data source directly using: ds = (DataSource) ctx.lookup("jdbc/MySQLDataSource"); With the source files in place, in the correct directory structure, you are ready to deploy the application: 1. In the navigation tree, navigate to `Applications' - the `Applications' frame will be displayed. Click `Deploy'. 2. You can now deploy an application packaged into a single WAR file from a remote client, or you can choose a packaged file or directory that is locally accessible to the server. If you are simply testing an application locally you can simply point Glassfish at the directory that contains your application, without needing to package the application into a WAR file. 3. Now select the application type from the `Type' drop-down listbox, which in this example is `Web application'. 4. Click OK. Now, when you navigate to the `Applications' frame, you will have the option to `Launch', `Redeploy', or `Restart' your application. You can test your application by clicking `Launch'. The application will connection to the MySQL database and display the Name and Population of countries in the `Country' table.  File: manual.info, Node: connector-j-usagenotes-glassfish-config-servlet, Prev: connector-j-usagenotes-glassfish-config-jsp, Up: connector-j-usagenotes-glassfish-config 21.3.14.2 A Simple Servlet with Glassfish, Connector/J and MySQL ................................................................ This section describes a simple servlet that can be used in the Glassfish environment to access a MySQL database. As with the previous section, this example assumes the sample database `world' is installed. The project is set up with the following directory structure: index.html WEB-INF | - web.xml - sun-web.xml - classes | - HelloWebServlet.java - HelloWebServlet.class The code for the servlet, located in `HelloWebServlet.java', is as follows: import javax.servlet.http.*; import javax.servlet.*; import java.io.*; import java.sql.*; import javax.sql.*; import javax.naming.*; public class HelloWebServlet extends HttpServlet { InitialContext ctx = null; DataSource ds = null; Connection conn = null; PreparedStatement ps = null; ResultSet rs = null; String sql = "SELECT Name, Population FROM Country WHERE Name=?"; public void init () throws ServletException { try { ctx = new InitialContext(); ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource"); conn = ds.getConnection(); ps = conn.prepareStatement(sql); } catch (SQLException se) { System.out.println("SQLException: "+se.getMessage()); } catch (NamingException ne) { System.out.println("NamingException: "+ne.getMessage()); } } public void destroy () { try { if (rs != null) rs.close(); if (ps != null) ps.close(); if (conn != null) conn.close(); if (ctx != null) ctx.close(); } catch (SQLException se) { System.out.println("SQLException: "+se.getMessage()); } catch (NamingException ne) { System.out.println("NamingException: "+ne.getMessage()); } } public void doPost(HttpServletRequest req, HttpServletResponse resp){ try { String country_name = req.getParameter("country_name"); resp.setContentType("text/html"); PrintWriter writer = resp.getWriter(); writer.println(""); writer.println("

Country: "+country_name+"

"); ps.setString(1, country_name); rs = ps.executeQuery(); if (!rs.next()){ writer.println("

Country does not exist!

"); } else { rs.beforeFirst(); while(rs.next()) { writer.println("

Name: "+rs.getString("Name")+"

"); writer.println("

Population: "+rs.getString("Population")+"

"); } } writer.println(""); writer.close(); } catch (Exception e) { e.printStackTrace(); } } public void doGet(HttpServletRequest req, HttpServletResponse resp){ try { resp.setContentType("text/html"); PrintWriter writer = resp.getWriter(); writer.println(""); writer.println("

Hello from servlet doGet()

"); writer.println(""); writer.close(); } catch (Exception e) { e.printStackTrace(); } } } In the preceding code a basic `doGet()' method is implemented, but is not used in the example. The code to establish the connection with the database is as shown in the previous example, *Note connector-j-usagenotes-glassfish-config-jsp::, and is most conveniently located in the servlet `init()' method. The corresponding freeing of resources is located in the destroy method. The main functionality of the servlet is located in the `doPost()' method. If the user enters nto the input form a country name that can be located in the database, the population of the country is returned. The code is invoked using a POST action associated with the input form. The form is defined in the file `index.html': HelloWebServlet

HelloWebServlet

Please enter country name:

The XML files `web.xml' and `sun-web.xml' are as for the example in the preceding section, *Note connector-j-usagenotes-glassfish-config-jsp::, no additional changes are required. Whe compiling the Java source code, you will need to specify the path to the file `javaee.jar'. On Windows, this can be done as follows: shell> javac -classpath c:\glassfishv3\glassfish\lib\javaee.jar HelloWebServlet.java Once the code is correctly located within its directory structure, and compiled, the application can be deployed in Glassfish. This is done in exactly the same way as described in the preceding section, *Note connector-j-usagenotes-glassfish-config-jsp::. Once deployed the application can be launched from within the Glassfish Administration Console. Enter a country name such as `England', and the application will return `Country does not exist!'. Enter `France', and the application will return a population of 59225700.  File: manual.info, Node: connector-j-usagenotes-troubleshooting, Next: connector-j-usagenotes-known-issues-limitations, Prev: connector-j-usagenotes-glassfish-config, Up: connector-j 21.3.15 Troubleshooting Connector/J Applications ------------------------------------------------ This section explains the symptoms and resolutions for the most commonly encountered issues with applications using MySQL Connector/J. *Questions* * 22.3.15.1: When I try to connect to the database with MySQL Connector/J, I get the following exception: SQLException: Server configuration denies access to data source SQLState: 08001 VendorError: 0 What is going on? I can connect just fine with the MySQL command-line client. * 22.3.15.2: My application throws an SQLException 'No Suitable Driver'. Why is this happening? * 22.3.15.3: I'm trying to use MySQL Connector/J in an applet or application and I get an exception similar to: SQLException: Cannot connect to MySQL server on host:3306. Is there a MySQL server running on the machine/port you are trying to connect to? (java.security.AccessControlException) SQLState: 08S01 VendorError: 0 * 22.3.15.4: I have a servlet/application that works fine for a day, and then stops working overnight * 22.3.15.5: I'm trying to use JDBC 2.0 updatable result sets, and I get an exception saying my result set is not updatable. * 22.3.15.6: I cannot connect to the MySQL server using Connector/J, and I'm sure the connection parameters are correct. * 22.3.15.7: I am trying to connect to my MySQL server within my application, but I get the following error and stack trace: java.net.SocketException MESSAGE: Software caused connection abort: recv failed STACKTRACE: java.net.SocketException: Software caused connection abort: recv failed at java.net.SocketInputStream.socketRead0(Native Method) at java.net.SocketInputStream.read(Unknown Source) at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1392) at com.mysql.jdbc.MysqlIO.readPacket(MysqlIO.java:1414) at com.mysql.jdbc.MysqlIO.doHandshake(MysqlIO.java:625) at com.mysql.jdbc.Connection.createNewIO(Connection.java:1926) at com.mysql.jdbc.Connection.(Connection.java:452) at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:411) * 22.3.15.8: My application is deployed through JBoss and I am using transactions to handle the statements on the MySQL database. Under heavy loads, I am getting an error and stack trace, but these only occur after a fixed period of heavy activity. * 22.3.15.9: When using `gcj', a `java.io.CharConversionException' exception is raised when working with certain character sequences. * 22.3.15.10: Updating a table that contains a primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key) that is either *Note `FLOAT': floating-point-types. or compound primary key that uses *Note `FLOAT': floating-point-types. fails to update the table and raises an exception. * 22.3.15.11: You get an `ER_NET_PACKET_TOO_LARGE' exception, even though the binary blob size you want to insert using JDBC is safely below the `max_allowed_packet' size. * 22.3.15.12: What should you do if you receive error messages similar to the following: `Communications link failure - Last packet sent to the server was X ms ago'? * 22.3.15.13: Why does Connector/J not reconnect to MySQL and re-issue the statement after a communication failure, instead of throwing an Exception, even though I use the `autoReconnect' connection string option? * 22.3.15.14: How can I use 3-byte UTF8 with Connector/J? * 22.3.15.15: How can I use 4-byte UTF8, `utf8mb4' with Connector/J? * 22.3.15.16: Using `useServerPrepStmts=false' and certain character encodings can lead to corruption when inserting BLOBs. How can this be avoided? *Questions and Answers* *22.3.15.1: ** When I try to connect to the database with MySQL Connector/J, I get the following exception: * SQLException: Server configuration denies access to data source SQLState: 08001 VendorError: 0 * What is going on? I can connect just fine with the MySQL command-line client. * MySQL Connector/J must use TCP/IP sockets to connect to MySQL, as Java does not support Unix Domain Sockets. Therefore, when MySQL Connector/J connects to MySQL, the security manager in MySQL server will use its grant tables to determine whether the connection is permitted. You must add the necessary security credentials to the MySQL server for this to happen, using the *Note `GRANT': grant. statement to your MySQL Server. See *Note grant::, for more information. *Note*: Testing your connectivity with the *Note `mysql': mysql. command-line client will not work unless you add the "host" flag, and use something other than `localhost' for the host. The *Note `mysql': mysql. command-line client will use Unix domain sockets if you use the special host name `localhost'. If you are testing connectivity to `localhost', use `127.0.0.1' as the host name instead. *Warning*: Changing privileges and permissions improperly in MySQL can potentially cause your server installation to not have optimal security properties. *22.3.15.2: ** My application throws an SQLException 'No Suitable Driver'. Why is this happening? * There are three possible causes for this error: * The Connector/J driver is not in your `CLASSPATH', see *Note connector-j-installing::. * The format of your connection URL is incorrect, or you are referencing the wrong JDBC driver. * When using DriverManager, the `jdbc.drivers' system property has not been populated with the location of the Connector/J driver. *22.3.15.3: ** I'm trying to use MySQL Connector/J in an applet or application and I get an exception similar to: * SQLException: Cannot connect to MySQL server on host:3306. Is there a MySQL server running on the machine/port you are trying to connect to? (java.security.AccessControlException) SQLState: 08S01 VendorError: 0 Either you're running an Applet, your MySQL server has been installed with the "skip-networking" option set, or your MySQL server has a firewall sitting in front of it. Applets can only make network connections back to the machine that runs the web server that served the .class files for the applet. This means that MySQL must run on the same machine (or you must have some sort of port re-direction) for this to work. This also means that you will not be able to test applets from your local file system, you must always deploy them to a web server. MySQL Connector/J can only communicate with MySQL using TCP/IP, as Java does not support Unix domain sockets. TCP/IP communication with MySQL might be affected if MySQL was started with the "skip-networking" flag, or if it is firewalled. If MySQL has been started with the "skip-networking" option set (the Debian Linux package of MySQL server does this for example), you need to comment it out in the file `/etc/mysql/my.cnf' or `/etc/my.cnf'. Of course your `my.cnf' file might also exist in the `data' directory of your MySQL server, or anywhere else (depending on how MySQL was compiled for your system). Binaries created by us always look in `/etc/my.cnf' and `DATADIR/my.cnf'. If your MySQL server has been firewalled, you will need to have the firewall configured to allow TCP/IP connections from the host where your Java code is running to the MySQL server on the port that MySQL is listening to (by default, 3306). *22.3.15.4: ** I have a servlet/application that works fine for a day, and then stops working overnight * MySQL closes connections after 8 hours of inactivity. You either need to use a connection pool that handles stale connections or use the `autoReconnect' parameter (see *Note connector-j-reference-configuration-properties::). Also, catch `SQLExceptions' in your application and deal with them, rather than propagating them all the way until your application exits. This is just good programming practice. MySQL Connector/J will set the `SQLState' (see `java.sql.SQLException.getSQLState()' in your API docs) to `08S01' when it encounters network-connectivity issues during the processing of a query. Attempt to reconnect to MySQL at this point. The following (simplistic) example shows what code that can handle these exceptions might look like: public void doBusinessOp() throws SQLException { Connection conn = null; Statement stmt = null; ResultSet rs = null; // // How many times do you want to retry the transaction // (or at least _getting_ a connection)? // int retryCount = 5; boolean transactionCompleted = false; do { try { conn = getConnection(); // assume getting this from a // javax.sql.DataSource, or the // java.sql.DriverManager conn.setAutoCommit(false); // // Okay, at this point, the 'retry-ability' of the // transaction really depends on your application logic, // whether or not you're using autocommit (in this case // not), and whether you're using transactional storage // engines // // For this example, we'll assume that it's _not_ safe // to retry the entire transaction, so we set retry // count to 0 at this point // // If you were using exclusively transaction-safe tables, // or your application could recover from a connection going // bad in the middle of an operation, then you would not // touch 'retryCount' here, and just let the loop repeat // until retryCount == 0. // retryCount = 0; stmt = conn.createStatement(); String query = "SELECT foo FROM bar ORDER BY baz"; rs = stmt.executeQuery(query); while (rs.next()) { } rs.close(); rs = null; stmt.close(); stmt = null; conn.commit(); conn.close(); conn = null; transactionCompleted = true; } catch (SQLException sqlEx) { // // The two SQL states that are 'retry-able' are 08S01 // for a communications error, and 40001 for deadlock. // // Only retry if the error was due to a stale connection, // communications problem or deadlock // String sqlState = sqlEx.getSQLState(); if ("08S01".equals(sqlState) || "40001".equals(sqlState)) { retryCount -= 1; } else { retryCount = 0; } } finally { if (rs != null) { try { rs.close(); } catch (SQLException sqlEx) { // You'd probably want to log this... } } if (stmt != null) { try { stmt.close(); } catch (SQLException sqlEx) { // You'd probably want to log this as well... } } if (conn != null) { try { // // If we got here, and conn is not null, the // transaction should be rolled back, as not // all work has been done try { conn.rollback(); } finally { conn.close(); } } catch (SQLException sqlEx) { // // If we got an exception here, something // pretty serious is going on, so we better // pass it up the stack, rather than just // logging it... throw sqlEx; } } } } while (!transactionCompleted && (retryCount > 0)); } *Note*: Use of the `autoReconnect' option is not recommended because there is no safe method of reconnecting to the MySQL server without risking some corruption of the connection state or database state information. Instead, use a connection pool, which will enable your application to connect to the MySQL server using an available connection from the pool. The `autoReconnect' facility is deprecated, and may be removed in a future release. *22.3.15.5: ** I'm trying to use JDBC 2.0 updatable result sets, and I get an exception saying my result set is not updatable. * Because MySQL does not have row identifiers, MySQL Connector/J can only update result sets that have come from queries on tables that have at least one primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key), the query must select every primary key column, and the query can only span one table (that is, no joins). This is outlined in the JDBC specification. Note that this issue only occurs when using updatable result sets, and is caused because Connector/J is unable to guarantee that it can identify the correct rows within the result set to be updated without having a unique reference to each row. There is no requirement to have a unique field on a table if you are using *Note `UPDATE': update. or *Note `DELETE': delete. statements on a table where you can individually specify the criteria to be matched using a `WHERE' clause. *22.3.15.6: ** I cannot connect to the MySQL server using Connector/J, and I'm sure the connection parameters are correct. * Make sure that the `skip-networking' option has not been enabled on your server. Connector/J must be able to communicate with your server over TCP/IP; named sockets are not supported. Also ensure that you are not filtering connections through a firewall or other network security system. For more information, see *Note can-not-connect-to-server::. *22.3.15.7: ** I am trying to connect to my MySQL server within my application, but I get the following error and stack trace: * java.net.SocketException MESSAGE: Software caused connection abort: recv failed STACKTRACE: java.net.SocketException: Software caused connection abort: recv failed at java.net.SocketInputStream.socketRead0(Native Method) at java.net.SocketInputStream.read(Unknown Source) at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1392) at com.mysql.jdbc.MysqlIO.readPacket(MysqlIO.java:1414) at com.mysql.jdbc.MysqlIO.doHandshake(MysqlIO.java:625) at com.mysql.jdbc.Connection.createNewIO(Connection.java:1926) at com.mysql.jdbc.Connection.(Connection.java:452) at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:411) The error probably indicates that you are using a older version of the Connector/J JDBC driver (2.0.14 or 3.0.x) and you are trying to connect to a MySQL server with version 4.1x or newer. The older drivers are not compatible with 4.1 or newer of MySQL as they do not support the newer authentication mechanisms. It is likely that the older version of the Connector/J driver exists within your application directory or your `CLASSPATH' includes the older Connector/J package. *22.3.15.8: ** My application is deployed through JBoss and I am using transactions to handle the statements on the MySQL database. Under heavy loads, I am getting an error and stack trace, but these only occur after a fixed period of heavy activity. * This is a JBoss, not Connector/J, issue and is connected to the use of transactions. Under heavy loads the time taken for transactions to complete can increase, and the error is caused because you have exceeded the predefined timeout. You can increase the timeout value by setting the `TransactionTimeout' attribute to the `TransactionManagerService' within the `/conf/jboss-service.xml' file (pre-4.0.3) or `/deploy/jta-service.xml' for JBoss 4.0.3 or later. See TransactionTimeout (http://wiki.jboss.org/wiki/Wiki.jsp?page=TransactionTimeout) within the JBoss wiki for more information. *22.3.15.9: ** When using `gcj', a `java.io.CharConversionException' exception is raised when working with certain character sequences. * This is a known issue with `gcj' which raises an exception when it reaches an unknown character or one it cannot convert. Add `useJvmCharsetConverters=true' to your connection string to force character conversion outside of the `gcj' libraries, or try a different JDK. *22.3.15.10: ** Updating a table that contains a primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key) that is either *Note `FLOAT': floating-point-types. or compound primary key that uses *Note `FLOAT': floating-point-types. fails to update the table and raises an exception. * Connector/J adds conditions to the `WHERE' clause during an *Note `UPDATE': update. to check the old values of the primary key. If there is no match, then Connector/J considers this a failure condition and raises an exception. The problem is that rounding differences between supplied values and the values stored in the database may mean that the values never match, and hence the update fails. The issue will affect all queries, not just those from Connector/J. To prevent this issue, use a primary key that does not use *Note `FLOAT': floating-point-types. If you have to use a floating point column in your primary key, use *Note `DOUBLE': floating-point-types. or *Note `DECIMAL': fixed-point-types. types in place of *Note `FLOAT': floating-point-types. *22.3.15.11: ** You get an `ER_NET_PACKET_TOO_LARGE' exception, even though the binary blob size you want to insert using JDBC is safely below the `max_allowed_packet' size. * This is because the `hexEscapeBlock()' method in `com.mysql.jdbc.PreparedStatement.streamToBytes()' may almost double the size of your data. *22.3.15.12: ** What should you do if you receive error messages similar to the following: `Communications link failure - Last packet sent to the server was X ms ago'? * Generally speaking, this error suggests that the network connection has been closed. There can be several root causes: * Firewalls or routers may clamp down on idle connections (the MySQL client/server protocol does not ping). * The MySQL Server may be closing idle connections that exceed the `wait_timeout' or `interactive_timeout' threshold. To help troubleshoot these issues, the following tips can be used. If a recent (5.1.13+) version of Connector/J is used, you will see an improved level of information compared to earlier versions. Older versions simply display the last time a packet was sent to the server, which is frequently 0 ms ago. This is of limited use, as it may be that a packet was just sent, while a packet from the server has not been received for several hours. Knowing the period of time since Connector/J last received a packet from the server is useful information, so if this is not displayed in your exception message, it is recommended that you update Connector/J. Further, if the time a packet was last sent/received exceeds the `wait_timeout' or `interactive_timeout' threshold, this is noted in the exception message. Although network connections can be volatile, the following can be helpful in avoiding problems: * Ensure connections are valid when used from the connection pool. Use a query that starts with `/* ping */' to execute a lightweight ping instead of full query. Note, the syntax of the ping needs to be exactly as specified here. * Minimize the duration a connection object is left idle while other application logic is executed. * Explicitly validate the connection before using it if the connection has been left idle for an extended period of time. * Ensure that `wait_timeout' and `interactive_timeout' are set sufficiently high. * Ensure that `tcpKeepalive' is enabled. * Ensure that any configurable firewall or router timeout settings allow for the maximum expected connection idle time. *Note*: Do not expect to be able to reuse a connection without problems, if it has being lying idle for a period. If a connection is to be reused after being idle for any length of time, ensure that you explicitly test it before reusing it. *22.3.15.13: ** Why does Connector/J not reconnect to MySQL and re-issue the statement after a communication failure, instead of throwing an Exception, even though I use the `autoReconnect' connection string option? * There are several reasons for this. The first is transactional integrity. The MySQL Reference Manual states that `there is no safe method of reconnecting to the MySQL server without risking some corruption of the connection state or database state information'. Consider the following series of statements for example: conn.createStatement().execute( "UPDATE checking_account SET balance = balance - 1000.00 WHERE customer='Smith'"); conn.createStatement().execute( "UPDATE savings_account SET balance = balance + 1000.00 WHERE customer='Smith'"); conn.commit(); Consider the case where the connection to the server fails after the `UPDATE' to `checking_account'. If no exception is thrown, and the application never learns about the problem, it will continue executing. However, the server did not commit the first transaction in this case, so that will get rolled back. But execution continues with the next transaction, and increases the `savings_account' balance by 1000. The application did not receive an exception, so it continued regardless, eventually committing the second transaction, as the commit only applies to the changes made in the new connection. Rather than a transfer taking place, a deposit was made in this example. Note that running with `autocommit' enabled does not solve this problem. When Connector/J encounters a communication problem, there is no means to determine whether the server processed the currently executing statement or not. The following theoretical states are equally possible: * The server never received the statement, and therefore no related processing occurred on the server. * The server received the statement, executed it in full, but the response was not received by the client. If you are running with `autocommit' enabled, it is not possible to guarantee the state of data on the server when a communication exception is encountered. The statement may have reached the server, or it may not. All you know is that communication failed at some point, before the client received confirmation (or data) from the server. This does not only affect `autocommit' statements though. If the communication problem occurred during `Connection.commit()', the question arises of whether the transaction was committed on the server before the communication failed, or whether the server received the commit request at all. The second reason for the generation of exceptions is that transaction-scoped contextual data may be vulnerable, for example: * Temporary tables. * User-defined variables. * Server-side prepared statements. These items are lost when a connection fails, and if the connection silently reconnects without generating an exception, this could be detrimental to the correct execution of your application. In summary, communication errors generate conditions that may well be unsafe for Connector/J to simply ignore by silently reconnecting. It is necessary for the application to be notified. It is then for the application developer to decide how to proceed in the event of connection errors and failures. *22.3.15.14: ** How can I use 3-byte UTF8 with Connector/J? * To use 3-byte UTF8 with Connector/J set `characterEncoding=utf8' and set `useUnicode=true' in the connection string. *22.3.15.15: ** How can I use 4-byte UTF8, `utf8mb4' with Connector/J? * To use 4-byte UTF8 with Connector/J configure the MySQL server with `character_set_server=utf8mb4'. Connector/J will then use that setting as long as `characterEncoding' has not been set in the connection string. This is equivalent to autodetection of the character set. *22.3.15.16: ** Using `useServerPrepStmts=false' and certain character encodings can lead to corruption when inserting BLOBs. How can this be avoided? * When using certain character encodings, such as SJIS, CP932, and BIG5, it is possible that BLOB data contains characters that can be interpreted as control characters, for example, backslash, '\'. This can lead to corrupted data when inserting BLOBs into the database. There are two things that need to be done to avoid this: 1. Set the connection string option `useServerPrepStmts' to `true'. 2. Set `SQL_MODE' to `NO_BACKSLASH_ESCAPES'.  File: manual.info, Node: connector-j-usagenotes-known-issues-limitations, Next: connector-j-support, Prev: connector-j-usagenotes-troubleshooting, Up: connector-j 21.3.16 Known Issues and Limitations ------------------------------------ The following are some known issues and limitations for MySQL Connector/J: * When Connector/J retrieves timestamps for a daylight saving time (DST) switch day using the `getTimeStamp()' method on the result set, some of the returned values might be wrong. The errors can be avoided by using the following connection options when connecting to a database: useTimezone=true useLegacyDatetimeCode=false serverTimezone=UTC  File: manual.info, Node: connector-j-support, Prev: connector-j-usagenotes-known-issues-limitations, Up: connector-j 21.3.17 Connector/J Support --------------------------- * Menu: * connector-j-support-community:: Connector/J Community Support * connector-j-support-bug-report:: How to Report Connector/J Bugs or Problems  File: manual.info, Node: connector-j-support-community, Next: connector-j-support-bug-report, Prev: connector-j-support, Up: connector-j-support 21.3.17.1 Connector/J Community Support ....................................... Oracle provides assistance to the user community by means of its mailing lists. For Connector/J related issues, you can get help from experienced users by using the MySQL and Java mailing list. Archives and subscription information is available online at `http://lists.mysql.com/java'. For information about subscribing to MySQL mailing lists or to browse list archives, visit `http://lists.mysql.com/'. See *Note mailing-lists::. Community support from experienced users is also available through the JDBC Forum (http://forums.mysql.com/list.php?39). You may also find help from other users in the other MySQL Forums, located at `http://forums.mysql.com'. See *Note forums::.  File: manual.info, Node: connector-j-support-bug-report, Prev: connector-j-support-community, Up: connector-j-support 21.3.17.2 How to Report Connector/J Bugs or Problems .................................................... The normal place to report bugs is `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 will also be able to enter new reports. If you find a sensitive security bug in MySQL Server, please let us know immediately by sending an email message to . Exception: Support customers should report all problems, including security bugs, to Oracle Support at `http://support.oracle.com/'. 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 will help you write your report correctly so that you do not waste your time doing things that may not help us much or at all. If you have a repeatable bug report, please report it to the bugs database at `http://bugs.mysql.com/'. Any bug that we are able to repeat has a high chance of being fixed in the next MySQL release. To report other problems, you can use one of the MySQL mailing lists. Remember that it is possible for us to respond to a message 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 is this: 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 Connector/J or MySQL used, and (b) not fully describing the platform on which Connector/J is installed (including the JVM version, and the platform type and version number that MySQL itself is installed on). This is highly relevant information, and in 99 cases out of 100, the bug report is useless without it. 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 already been fixed in newer MySQL versions. Sometimes the error is 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 at all possible, create a repeatable, standalone testcase that doesn't involve any third-party classes. To streamline this process, we ship a base class for testcases with Connector/J, named 'com.mysql.jdbc.util.BaseBugReport'. To create a testcase for Connector/J using this class, create your own class that inherits from com.mysql.jdbc.util.BaseBugReport and override the methods `setUp()', `tearDown()' and `runTest()'. In the `setUp()' method, create code that creates your tables, and populates them with any data needed to demonstrate the bug. In the `runTest()' method, create code that demonstrates the bug using the tables and data you created in the `setUp' method. In the `tearDown()' method, drop any tables you created in the `setUp()' method. In any of the above three methods, use one of the variants of the `getConnection()' method to create a JDBC connection to MySQL: * `getConnection()' - Provides a connection to the JDBC URL specified in `getUrl()'. If a connection already exists, that connection is returned, otherwise a new connection is created. * `getNewConnection()' - Use this if you need to get a new connection for your bug report (that is, there is more than one connection involved). * `getConnection(String url)' - Returns a connection using the given URL. * `getConnection(String url, Properties props)' - Returns a connection using the given URL and properties. If you need to use a JDBC URL that is different from 'jdbc:mysql:///test', override the method `getUrl()' as well. Use the `assertTrue(boolean expression)' and `assertTrue(String failureMessage, boolean expression)' methods to create conditions that must be met in your testcase demonstrating the behavior you are expecting (vs. the behavior you are observing, which is why you are most likely filing a bug report). Finally, create a `main()' method that creates a new instance of your testcase, and calls the `run' method: public static void main(String[] args) throws Exception { new MyBugReport().run(); } Once you have finished your testcase, and have verified that it demonstrates the bug you are reporting, upload it with your bug report to `http://bugs.mysql.com/'.  File: manual.info, Node: connector-cpp, Next: connector-c, Prev: connector-j, Up: connectors-apis 21.4 MySQL Connector/C++ ======================== * Menu: * connector-cpp-downloading:: How to Get MySQL Connector/C++ * connector-cpp-installation-binary:: Installing MySQL Connector/C++ from a Binary Distribution * connector-cpp-installation-source:: Installing MySQL Connector/C++ from Source * connector-cpp-apps-windows-visual-studio:: Building MySQL Connector/C++ Windows Applications with Microsoft Visual Studio * connector-cpp-apps-linux-netbeans:: Building MySQL Connector/C++ Linux Applications with NetBeans * connector-cpp-getting-started-examples:: MySQL Connector/C++ Getting Started: Usage Examples * connector-cpp-tutorials:: MySQL Connector/C++ Tutorials * connector-cpp-debug-tracing:: MySQL Connector/C++ Debug Tracing * connector-cpp-usage-notes:: MySQL Connector/C++ Usage Notes * connector-cpp-bugs:: MySQL Connector/C++ Known Bugs and Issues * connector-cpp-support:: MySQL Connector/C++ Support MySQL Connector/C++ is a MySQL database connector for C++. It lets you develop C++ applications that connect to the MySQL Server. For release notes detailing the changes in each release of MySQL Connector/C++, see MySQL Connector/C++ Release Notes (http://dev.mysql.com/doc/relnotes/connector-cpp/en/). * MySQL Connector/C++ Benefits * MySQL Connector/C++ offers the following benefits for C++ users compared to the MySQL C API (MySQL client library): * Convenience of pure C++; no C function calls required * Supports JDBC 4.0, an industry standard API * Supports the object-oriented programming paradigm * Reduces development time * Licensed under the GPL with the FLOSS License Exception * Available under a commercial license upon request * JDBC Compatibility * MySQL Connector/C++ is compatible with the JDBC 4.0 API. MySQL Connector/C++ does not implement the entire JDBC 4.0 API, but does feature the following classes: * Connection * DatabaseMetaData * Driver * PreparedStatement * ResultSet * ResultSetMetaData * Savepoint * Statement The JDBC 4.0 API defines approximately 450 methods for the classes just mentioned. MySQL Connector/C++ implements approximately 80% of these. * Platform Support and Prerequisites * MySQL Connector/C++ requires: * MySQL 5.1 or later * Microsoft Visual Studio 2003 or later on Windows The release has been successfully compiled and tested on the following platforms: *AIX* * 5.2 (PPC32, PPC64) * 5.3 (PPC32, PPC64) *FreeBSD* * 6.0 (x86, x86_64) *HPUX* * 11.11 (PA-RISC 32bit, PA-RISC 64bit) *Linux* * Debian 3.1 (PPC32, x86) * FC4 (x86) * RHEL 3 (x86, x86_64) * RHEL 4 (x86, x86_64) * RHEL 5 (x86, x86_64) * RHEL 6 (x86, x86_64) * SLES 9 (x86, x86_64) * SLES 10 (x86_64) * SuSE 10.3, (x86_64) * Ubuntu 8.04 (x86) * Ubuntu 8.10 (x86_64) *Mac OS X* * Mac OS X 10.3 (PPC32, PPC64) * Mac OS X 10.4 (PPC32, PPC64, x86) * Mac OS X 10.5 (PPC32, PPC64, x86, x86_64) *Solaris* * Solaris 8 (SPARC32, SPARC64, x86) * Solaris 9 (SPARC32, SPARC64, x86) * Solaris 10 (SPARC32, SPARC64, x86, x86_64) *Windows* * XP Professional (32bit) * 2003 (64bit) * Release Status * MySQL Connector/C++ is available as a Generally Available (GA) version. We ask users and developers to try it out and provide feedback. Note that MySQL Workbench is successfully using MySQL Connector/C++. If you have any queries, please *Note contact us: connector-cpp-support. * Licensing * MySQL Connector/C++ is licensed under the terms of the GPL, like most MySQL Connectors. There are special exceptions to the terms and conditions of the GPL as applied to this software; see FLOSS License Exception. If you need a non-GPL license for commercial distribution, please contact us.  File: manual.info, Node: connector-cpp-downloading, Next: connector-cpp-installation-binary, Prev: connector-cpp, Up: connector-cpp 21.4.1 How to Get MySQL Connector/C++ ------------------------------------- Binary and source packages can be obtained from MySQL Connector/C++ downloads (http://dev.mysql.com/downloads/connector/cpp/). * MySQL Connector/C++ Binary Distributions * Binary distributions are available for these platforms: Microsoft Windows: * MSI installer package * Without installer (a Zip file) Other platforms: * Compressed GNU TAR archive (`tar.gz') * MySQL Connector/C++ Source Distributions * Source packages use compressed GNU TAR file (`tar.gz') format and can be used on any supported platform. * MySQL Connector/C++ Source Repository * The latest development sources are available through Launchpad (https://launchpad.net/mysql-connector-cpp). The MySQL Connector/C++ code repository uses Bazaar. To check out the latest source code, use the `bzr' command-line tool: shell> bzr branch lp:~mysql/mysql-connector-cpp/trunk .  File: manual.info, Node: connector-cpp-installation-binary, Next: connector-cpp-installation-source, Prev: connector-cpp-downloading, Up: connector-cpp 21.4.2 Installing MySQL Connector/C++ from a Binary Distribution ---------------------------------------------------------------- *Caution*: One problem that can occur is when the tools you use to build your application are not compatible with the tools used to build the binary versions of MySQL Connector/C++. Ideally, build your application with the same tools that were used to build the MySQL Connector/C++ binaries. To help with this, the following resources are provided. All distributions include a `README' file that contains platform-specific notes. At the end of the `README' file contained in the binary distribution, you will find the settings used to build the binaries. If you experience build-related issues on a platform, it may help to check the settings used on the platform to build the binary. Developers using Microsoft Windows must satisfy the following requirements: 1. Use a supported version of Visual Studio, either Visual Studio 2005 or Visual Studio 2008. 2. Ensure that your application uses the same runtime library as that used to build MySQL Connector/C++. Visual Studio 2005 builds use Microsoft.VC80.CRT (8.0.50727.762), and Visual Studio 2008 builds use Microsoft.VC90.CRT (9.0.21022.8). 3. Your application should use the same linker configuration as MySQL Connector/C++. For example, use one of `/MD', `/MDd', `/MT', or `/MTd'. To use a variation of the requirements previously listed, such as a different compiler version, release configuration, or runtime library, compile MySQL Connector/C++ from source using your desired settings and ensure that your application is built using these same settings. To avoid issues, ensure that the three variables of compiler version, runtime library, and runtime linker configuration settings are the same for both application and MySQL Connector/C++ itself. A better solution that ensures compatibility is to build your MySQL Connector/C++ libraries from the source code using the same tools that you use to build your application. *Downloading MySQL Connector/C++* Binary packages can be obtained from MySQL Connector/C++ downloads (http://dev.mysql.com/downloads/connector/cpp/). *Archive Package* Unpack the distribution archive into an appropriate directory. If you plan to use a dynamically linked version of MySQL Connector/C++, make sure that your system can reference the MySQL client library (MySQL Connector/C++ is linked against and thus requires the MySQL client library). Consult your operating system documentation on how to modify and expand the search path for libraries. If you cannot modify the library search path, it may help to copy your application, the MySQL Connector/C++ library and the MySQL client library into the same directory. Most systems search for libraries in the current directory. Windows users can choose between two binary packaging formats: * Windows MSI Installer (`.msi' file): To use the MSI Installer, launch it and follow the prompts in the screens it presents to install MySQL Connector/C in the location of your choosing. * Zip archive without installer (`.zip' file): To use a Zip archive, unpack it in the directory where you intend to install it using `WinZip' or another tool that can read `.zip' files. *Windows MSI Installer* Using the MSI Installer may be the easiest solution. The MSI Installer does not require any administrative permissions as it simply copies files. The MSI Installer begins by presenting a welcome screen. FIGURE GOES HERE: MSI Installer Welcome Screen The MSI Installer overview screen enables you to select the type of installation you want to perform. The `Typical' installation consists of all required header files and the Release libraries. The `Custom' installation enables you to install additional Debug versions of the connector libraries. FIGURE GOES HERE: MSI Installer Overview Screen If you select a `Custom' installation, the MSI Installer presents a Custom Setup screen that enables you to select which features to install and where to install them. FIGURE GOES HERE: MSI Installer Custom Setup Screen  File: manual.info, Node: connector-cpp-installation-source, Next: connector-cpp-apps-windows-visual-studio, Prev: connector-cpp-installation-binary, Up: connector-cpp 21.4.3 Installing MySQL Connector/C++ from Source ------------------------------------------------- * Menu: * connector-cpp-installation-source-unix:: Building MySQL Connector/C++ from Source on Unix, Solaris, and Mac OS X * connector-cpp-installation-source-windows:: Building MySQL Connector/C++ from Source on Windows * connector-cpp-dynamic-linking-client-library:: Dynamically Linking MySQL Connector/C++ Against the MySQL Client Library MySQL Connector/C++ is based on the MySQL client library (MySQL C API) and is linked against it. Thus, to compile MySQL Connector/C++, the MySQL Client Library must be installed. You also need the cross-platform build tool `CMake' 2.4, or newer, and GLib 2.2.3 or newer. Check the `README' file included with the distribution for platform-specific notes. Typically, the MySQL client library is installed when the MySQL Server is installed. However, check your operating system documentation for other installation options. As of MySQL Connector/C++ 1.1.0, the Boost C++ libraries 1.34.0 or newer must be installed. Boost is required only to build the connector, required to use the connector. You can obtain Boost and its installation instructions from the official site (http://www.boost.org). Once Boost is installed, tell the build system where the Boost files are by defining the `BOOST_ROOT:STRING' option. This can be done when you invoke `CMake'. For example: shell> cmake . -DBOOST_ROOT:STRING=/usr/local/boost_1_40_0 Change `/usr/local/boost_1_40_0/' as necessary to match your installation. For further details, see *Note connector-cpp-installation-source-unix:: and *Note connector-cpp-installation-source-windows::.  File: manual.info, Node: connector-cpp-installation-source-unix, Next: connector-cpp-installation-source-windows, Prev: connector-cpp-installation-source, Up: connector-cpp-installation-source 21.4.3.1 Building MySQL Connector/C++ from Source on Unix, Solaris, and Mac OS X ................................................................................ 1. Change location to the top-level directory of the source distribution: shell> cd /PATH/TO/MYSQL-CONNECTOR-CPP 2. Run `CMake' to build a `Makefile': shell> cmake . -- Check for working C compiler: /usr/local/bin/gcc -- Check for working C compiler: /usr/local/bin/gcc -- works [...] -- Generating done -- Build files have been written to: /PATH/TO/MYSQL-CONNECTOR-CPP/ On non-Windows systems, `CMake' first checks to see if the `CMake' variable `MYSQL_CONFIG_EXECUTABLE' is set. If it is not found, `CMake' tries to locate `mysql_config' in the default locations. If you have any problems with the configuration process, check the troubleshooting instructions given later. 3. Use `make' to build the libraries. First make sure you have a clean build: shell> make clean Then build the connector: shell> make [ 1%] Building CXX object » driver/CMakeFiles/mysqlcppconn.dir/mysql_connection.o [ 3%] Building CXX object » driver/CMakeFiles/mysqlcppconn.dir/mysql_constructed_resultset.o [...] [100%] Building CXX object examples/CMakeFiles/statement.dir/statement.o Linking CXX executable statement If all goes well, you will find the MySQL Connector/C++ library in the `driver' directory. 4. Install the header and library files: shell> make install Unless you have changed the location in the configuration step, `make install' copies the header files to the directory `/usr/local/include'. The header files copied are `mysql_connection.h' and `mysql_driver.h'. Again, unless you have specified otherwise, `make install' copies the library files to `/usr/local/lib'. The files copied are the dynamic library `libmysqlcppconn.so', and the static library `libmysqlcppconn-static.a'. The extension of the dynamic library might be different on your system (for example, `.dylib' on Mac OS X). If you encounter any errors, please first carry out these checks: 1. `CMake' options: MySQL installation path, debug version and more In case of configuration or compilation problems, check the list of `CMake' options: shell> cmake -L [...] CMAKE_BACKWARDS_COMPATIBILITY:STRING=2.4 CMAKE_BUILD_TYPE:STRING= CMAKE_INSTALL_PREFIX:PATH=/usr/local EXECUTABLE_OUTPUT_PATH:PATH= LIBRARY_OUTPUT_PATH:PATH= MYSQLCPPCONN_GCOV_ENABLE:BOOL=0 MYSQLCPPCONN_TRACE_ENABLE:BOOL=0 MYSQL_CONFIG_EXECUTABLE:FILEPATH=/usr/bin/mysql_config For example, if your MySQL Server installation path is not `/usr/local/mysql' and you want to build a debug version of the MySQL Connector/C++, use this command: shell> cmake \ -D CMAKE_BUILD_TYPE:STRING=Debug \ -D MYSQL_CONFIG_EXECUTABLE=/PATH/TO/MY/MYSQL/SERVER/bin/mysql_config . 2. Verify your settings with `cmake `-L'': shell> cmake -L [...] CMAKE_BACKWARDS_COMPATIBILITY:STRING=2.4 CMAKE_BUILD_TYPE:STRING= CMAKE_INSTALL_PREFIX:PATH=/usr/local EXECUTABLE_OUTPUT_PATH:PATH= LIBRARY_OUTPUT_PATH:PATH= MYSQLCPPCONN_GCOV_ENABLE:BOOL=0 MYSQLCPPCONN_TRACE_ENABLE:BOOL=0 MYSQL_CONFIG_EXECUTABLE=/PATH/TO/MY/MYSQL/SERVER/bin/mysql_config Proceed by executing a `make clean' command followed by a `make' command, as described previously. Once you have installed MySQL Connector/C++, you can carry out a quick test to check the installation. To do this, compile and run one of the example programs, such as `examples/standalone_example.cpp'. This example is discussed in more detail later, but for now, you can use it to test whether the connector has been correctly installed. This procedure assumes that you have a working MySQL Server to which you can connect. It also assumes header and library locations of `/usrlocal/include' and `/usr/local/lib', respectively; adjust these as necessary for your system. 1. Compile the example program. To do this, change location to the `examples' directory and enter this command: shell> g++ -o test_install \ -I/usr/local/include -I/usr/local/include/cppconn \ -Wl,-Bdynamic -lmysqlcppconn standalone_example.cpp 2. Make sure the dynamic library which is used in this case can be found at runtime: shell> export LD_LIBRARY_PATH=/usr/local/lib 3. Now run the program to test your installation, substituting the appropriate host, user, password, and database names for your system: shell> ./test_install localhost root password database You should see output similar to the following: Connector/C++ standalone program example... ... running 'SELECT 'Welcome to Connector/C++' AS _message' ... MySQL replies: Welcome to Connector/C++ ... say it again, MySQL ....MySQL replies: Welcome to Connector/C++ ... find more at http://www.mysql.com If you see any errors, take note of them and go through the troubleshooting procedures discussed earlier.  File: manual.info, Node: connector-cpp-installation-source-windows, Next: connector-cpp-dynamic-linking-client-library, Prev: connector-cpp-installation-source-unix, Up: connector-cpp-installation-source 21.4.3.2 Building MySQL Connector/C++ from Source on Windows ............................................................ *Note*: The only compiler formally supported for Windows is Microsoft Visual Studio 2003 and above. The basic steps for building the connector on Windows are the same as for Unix. It is important to use `CMake' 2.6.2 or newer to generate build files for your compiler and to invoke the compiler. *Note*: On Windows, `mysql_config' is not present, so `CMake' attempts to retrieve the location of MySQL from the environment variable `$ENV{MYSQL_DIR}'. If `MYSQL_DIR' is not set, `CMake' then proceeds to check for MySQL in the following locations: `$ENV{ProgramFiles}/MySQL/*/include', and `$ENV{SystemDrive}/MySQL/*/include'. `CMake' makes it easy for you to try other compilers. However, you may experience compile warnings, compile errors or linking issues not detected by Visual Studio. Patches are gratefully accepted to fix issues with other compilers. Consult the `CMake' manual or check `cmake --help' to find out which build systems are supported by your `CMake' version: C:\>cmake --help cmake version 2.6-patch 2 Usage [...] Generators The following generators are available on this platform: Borland Makefiles = Generates Borland makefiles. MSYS Makefiles = Generates MSYS makefiles. MinGW Makefiles = Generates a make file for use with mingw32-make. NMake Makefiles = Generates NMake makefiles. Unix Makefiles = Generates standard UNIX makefiles. Visual Studio 6 = Generates Visual Studio 6 project files. Visual Studio 7 = Generates Visual Studio .NET 2002 project files. Visual Studio 7 .NET 2003 = Generates Visual Studio .NET 2003 project files. Visual Studio 8 2005 = Generates Visual Studio .NET 2005 project files. Visual Studio 8 2005 Win64 = Generates Visual Studio .NET 2005 Win64 project files. Visual Studio 9 2008 = Generates Visual Studio 9 2008 project fil Visual Studio 9 2008 Win64 = Generates Visual Studio 9 2008 Win64 proje files. [...] It is likely that your `CMake' binary supports more compilers, known by `CMake' as _generators_, than can actually be used to build MySQL Connector/C++. We have built the connector using the following generators: * Microsoft Visual Studio 8 (Visual Studio 2005) * Microsoft Visual Studio 9 (Visual Studio 2008, Visual Studio 2008 Express) * NMake Please see the building instructions for Unix, Solaris and Mac OS X for troubleshooting and configuration hints. Use these steps to build the connector: 1. Change location to the top-level directory of the source distribution: shell> cd C:\PATH_TO_MYSQL_CPP 2. Run `CMake' to generate build files for your generator: *Visual Studio* C:\>cmake -G "Visual Studio 9 2008" -- Check for working C compiler: cl -- Check for working C compiler: cl -- works -- Detecting C compiler ABI info -- Detecting C compiler ABI info - done -- Check for working CXX compiler: cl -- Check for working CXX compiler: cl -- works -- Detecting CXX compiler ABI info -- Detecting CXX compiler ABI info - done -- ENV{MYSQL_DIR} = -- MySQL Include dir: C:/Programme/MySQL/MySQL Server 5.5/include -- MySQL Library : C:/Programs/MySQL/MySQL Server 5.5/lib/opt/mysqlclient.lib -- MySQL Library dir: C:/Programs/MySQL/MySQL Server 5.5/lib/opt -- MySQL CFLAGS: -- MySQL Link flags: -- MySQL Include dir: C:/Programs/MySQL/MySQL Server 5.5/include -- MySQL Library dir: C:/Programs/MySQL/MySQL Server 5.5/lib/opt -- MySQL CFLAGS: -- MySQL Link flags: -- Configuring cppconn -- Configuring test cases -- Looking for isinf -- Looking for isinf - not found -- Looking for isinf -- Looking for isinf - not found. -- Looking for finite -- Looking for finite - not found. -- Configuring C/J junit tests port -- Configuring examples -- Configuring done -- Generating done -- Build files have been written to: C:\PATH_TO_MYSQL_CPP C:\>dir *.sln *.vcproj [...] 19.11.2008 12:16 23.332 MYSQLCPPCONN.sln [...] 19.11.2008 12:16 27.564 ALL_BUILD.vcproj 19.11.2008 12:16 27.869 INSTALL.vcproj 19.11.2008 12:16 28.073 PACKAGE.vcproj 19.11.2008 12:16 27.495 ZERO_CHECK.vcproj *NMake* C:\>cmake -G "NMake Makefiles" -- The C compiler identification is MSVC -- The CXX compiler identification is MSVC [...] -- Build files have been written to: C:\PATH_TO_MYSQL_CPP 3. Use your compiler to build MySQL Connector/C++. *Visual Studio - GUI* Open the newly generated project files in the Visual Studio GUI or use a Visual Studio command line to build the driver. The project files contain a variety of different configurations, debug and nondebug versions among them. *Visual Studio - NMake* C:\>nmake Microsoft (R) Program Maintenance Utility Version 9.00.30729.01 Copyright (C) Microsoft Corporation. All rights reserved. Scanning dependencies of target mysqlcppconn [ 2%] Building CXX object driver/CMakeFiles/mysqlcppconn.dir/mysql_connection.obj mysql_connection.cpp [...] Linking CXX executable statement.exe [100%] Built target statement  File: manual.info, Node: connector-cpp-dynamic-linking-client-library, Prev: connector-cpp-installation-source-windows, Up: connector-cpp-installation-source 21.4.3.3 Dynamically Linking MySQL Connector/C++ Against the MySQL Client Library ................................................................................. *Note*: This section refers to dynamic linking of MySQL Connector/C++ with the client library, not dynamic linking of the application to MySQL Connector/C++. Precompiled binaries of MySQL Connector/C++ use static binding with the client library by default. An application that uses MySQL Connector/C++ can be either statically or dynamically linked to the MySQL Connector/C++ libraries. MySQL Connector/C++ is usually statically linked to the underlying MySQL client library (or Connector/C). Note that, unless otherwise stated, reference to the MySQL client library is also taken to include Connector/C, which is a separately packaged, standalone version of the MySQL client library. From MySQL Connector/C++ 1.1.0 on, it is possible to also dynamically link to the underlying MySQL client library. The ability of MySQL Connector/C++ to dynamically link to MySQL client library is not enabled by default. Enabling this feature is done through a compile-time option when compiling the MySQL Connector/C++ source code. To use the ability to dynamically link the client library to MySQL Connector/C++, define the `MYSQLCLIENT_STATIC_BINDING:BOOL' when building the MySQL Connector/C++ source code: shell> rm CMakeCache.txt shell> cmake -DMYSQLCLIENT_STATIC_BINDING:BOOL=1 . shell> make clean shell> make shell> make install Now, in your application, when creating a connection, MySQL Connector/C++ will select and load a client library at runtime. It will choose the client library by searching defined locations and environment variables depending on the host operating system. It is also possible when creating a connection in an application to define an absolute path to the client library to be loaded at runtime. This can be convenient if you have defined a standard location from which you want the client library to be loaded. This is sometimes done to circumvent possible conflicts with other versions of the client library that may be located on the system.  File: manual.info, Node: connector-cpp-apps-windows-visual-studio, Next: connector-cpp-apps-linux-netbeans, Prev: connector-cpp-installation-source, Up: connector-cpp 21.4.4 Building MySQL Connector/C++ Windows Applications with Microsoft Visual Studio ------------------------------------------------------------------------------------- MySQL Connector/C++ is available as a static or dynamic library to use with your application. This section describes how to link the library to your application. *Note*: To avoid potential crashes, the build configuration of MySQL Connector/C++ should match the build configuration of the application using it. For example, do not use the release build of MySQL Connector/C++ with a debug build of the client application. *Static Library* The MySQL Connector/C++ static library file is `mysqlcppconn-static.lib'. You link this library statically with your application. Also link against the files `libmysql.dll' and `libmysql.lib'. At runtime, the application will require access to `libmysql.dll'. *Dynamic Library* The MySQL Connector/C++ dynamic library file is `mysqlcppconn.dll'. To build your client application, link it with the file `mysqlcppconn.lib'. At runtime, the application will require access to the files `mysqlcppconn.dll' and `libmysql.dll'. *Building a MySQL Connector/C++ Application with Microsoft Visual Studio* The initial steps for building an application to use either the static or dynamic library are the same. Some additional steps vary, depend on whether you are building your application to use the static or dynamic library. 1. Select `File', `New', `Project' from the main menu. FIGURE GOES HERE: Creating a New Project 2. In the wizard, select `Visual C++', `Win32'. From `Visual Studio Installed Templates', select the application type `Win32 Console Application'. Enter a name for the application, then click `OK', to move to the Win32 Application Wizard. FIGURE GOES HERE: The New Project Dialog Box 3. In the Win32 Application Wizard, click `Application Settings' and ensure the defaults are selected. The radio button `Console application' and the check box `Precompiled headers' are selected. Click `Finish' to close the wizard. FIGURE GOES HERE: The Win32 Application Wizard 4. From the drop down list box on the toolbar, change from the default `Debug' build to the `Release' build. FIGURE GOES HERE: Selecting the Release Build 5. From the main menu select `Project', `Properties'. This can also be accessed using the hot key `ALT' + `F7'. FIGURE GOES HERE: Selecting Project Properties from the Main Menu 6. Under `Configuration Properties', open the tree view. 7. Select `C++', `General' in the tree view. FIGURE GOES HERE: Setting Properties 8. Ensure that Visual Studio can find the MySQL include directory. This directory includes header files that can optionally be installed when installing MySQL Server. FIGURE GOES HERE: MySQL Include Directory 9. In the `Additional Include Directories' text field, add the MySQL `include/' directory. FIGURE GOES HERE: Select Directory Dialog 10. Also set the location of additional libraries that Visual Studio needs to build the application. These are located in the MySQL `lib/opt' directory, a subdirectory of the MySQL Server installation directory. FIGURE GOES HERE: Typical Contents of MySQL lib/opt Directory 11. In the tree view, open `Linker', `General', `Additional Library Directories'. FIGURE GOES HERE: Additional Library Directories 12. Add the `lib/opt' directory into the `Additional Library Directories' text field. This enables the library file `libmysql.lib' to be found. FIGURE GOES HERE: Additional Library Directories Dialog The remaining steps depend on whether you are building an application to use the MySQL Connector/C++ static or dynamic library. If you are building your application to use the dynamic library, see *Note connector-cpp-application-build-dynamic::. If you are building your application to use the static library, carry out the following steps: 1. Open `Linker', `Input', `Additional Dependencies'. FIGURE GOES HERE: Additional Dependencies 2. Enter `mysqlcppconn-static.lib' and `libmysql.lib'. FIGURE GOES HERE: Adding Additional Dependencies 3. By default `CPPCONN_PUBLIC_FUNC' is defined to declare functions to be compatible with an application that calls a DLL. If you are building an application to call the static library, ensure that function prototypes are compatible with this. In this case, define `CPPCONN_PUBLIC_FUNC' to be an empty string, so that functions are declared with the correct prototype. In the `Project', `Properties' tree view, under `C++', `Preprocessor', enter `CPPCONN_PUBLIC_FUNC=' into the `Preprocessor Definitions' text field. FIGURE GOES HERE: Setting the CPPCONN_PUBLIC_FUNC Define *Note*: Make sure you enter `CPPCONN_PUBLIC_FUNC=' and not `CPPCONN_PUBLIC_FUNC', so that it is defined as an empty string. If you are building an application to use the MySQL Connector/C++ dynamically linked library, carry out these steps: 1. Under `Linker', `Input', add `mysqlcppconn.lib' into the `Additional Dependencies' text field. 2. `mysqlcppconn.dll' must be in the same directory as the application executable, or somewhere on the system's path, so that the application can access the MySQL Connector/C++ Dynamic Linked Library at runtime. Copy `mysqlcppconn.dll' to the same directory as the application. Alternatively, extend the `PATH' environment variable using `SET PATH=%PATH%;C:\path\to\cpp'. Alternatively, you can copy `mysqlcppconn.dll' to the Windows installation Directory, typically `c:\windows'.  File: manual.info, Node: connector-cpp-apps-linux-netbeans, Next: connector-cpp-getting-started-examples, Prev: connector-cpp-apps-windows-visual-studio, Up: connector-cpp 21.4.5 Building MySQL Connector/C++ Linux Applications with NetBeans -------------------------------------------------------------------- This section describes how to build MySQL Connector/C++ applications for Linux using the NetBeans IDE. FIGURE GOES HERE: The NetBeans IDE *Note*: To avoid potential crashes, the build configuration of MySQL Connector/C++ should match the build configuration of the application using it. For example, do not use the release build of MySQL Connector/C++ with a debug build of the client application. 1. Create a new project. Select `File', `New Project'. Choose a `C/C++ Application' and click `Next'. 2. Give the project a name and click `Finish'. A new project is created. 3. In the `Projects' tab, right-click `Source Files' and select `New', then `Main C++ File...'. 4. Change the filename, or simply select the defaults and click `Finish' to add the new file to the project. 5. Now add some working code to your main source file. Explore your MySQL Connector/C++ installation and navigate to the `examples' directory. 6. Select a suitable example, such as `standalone_example_docs1.cpp'. Copy all the code in this file, and use it to replace the code in your existing main source file. Amend the code to reflect the connection properties required for your test database. You now have a working example that will access a MySQL database using MySQL Connector/C++. 7. At this point, NetBeans shows some errors in the source code. Direct NetBeans to the necessary header files to include. Select `File', `Project Properties' from the main menu. 8. In the `Categories:' tree view panel, navigate to `Build', `C++ Compiler'. 9. In the `General' panel, select `Include Directories'. 10. Click the `...' button. 11. Click `Add', then navigate to the directory where the MySQL Connector/C++ header files are located. This is `/usr/local/include' unless you have installed the files to a different location. Click `Select'. Click `OK'. FIGURE GOES HERE: Setting the Header Include Directory 12. Click `OK' again to close the `Project Properties' dialog. At this point, you have created a NetBeans project containing a single C++ source file. You have also ensured that the necessary include files are accessible. Before continuing, decide whether your project is to use the MySQL Connector/C++ static or dynamic library. The project settings are slightly different in each case, because you link against a different library. *Using the Static Library* To use the static MySQL Connector/C++ library, link against two library files, `libmysqlcppconn-static.a' and `libmysqlclient.a'. The locations of the files depend on your setup, but typically the former are in `/usr/local/lib' and the latter in `/usr/lib'. The file `libmysqlclient.a' is not part of MySQL Connector/C++, but is the MySQL client library file distributed with MySQL Server. (Remember, the MySQL client library is an optional component as part of the MySQL Server installation process.) The MySQL Client Library is also available as part of the MySQL Connector/C distribution. 1. Set the project to link the necessary library files. Select `File', `Project Properties' from the main menu. 2. In the `Categories:' tree view, navigate to `Linker'. 3. In the `General' panel, select `Additional Library Directories'. Click the `...' button. 4. Select and add the `/usr/lib' and `/usr/local/lib' directories. 5. In the same panel, add the two library files required for static linking as discussed earlier. The properties panel should then look similar to the following screenshot. FIGURE GOES HERE: Setting the Static Library Directories and File Names 6. Click `OK' to close the `Project Properties' dialog. *Using the Dynamic Library* To use the MySQL Connector/C++ dynamic library, link your project with a single library file, `libmysqlcppconn.so'. The location of this file depends on how you configured your installation of MySQL Connector/C++, but typically is `/usr/local/lib'. 1. Set the project to link the necessary library file. Select `File', `Project Properties' from the main menu. 2. In the `Categories:' tree view, navigate to `Linker'. 3. In the `General' panel, select `Additional Library Directories'. Click the `...' button. 4. Select and add the `/usr/local/lib' directories. 5. In the same panel, add the library file required for static linking as discussed earlier. The properties panel should look similar to the following screenshot. FIGURE GOES HERE: Setting the Dynamic Library Directory and File Name 6. Click OK to close the Project Properties dialog. After configuring your project, build it by selecting `Run', `Build Main Project' from the main menu. You then run the project using `Run', `Run Main Project'. On running the application, you should see a screen similar to the following (this is actually the static version of the application shown): FIGURE GOES HERE: The Example Application Running *Note*: The preceding settings and procedures were carried out for the default `Debug' configuration. To create a `Release' configuration, select that configuration before setting the Project Properties.  File: manual.info, Node: connector-cpp-getting-started-examples, Next: connector-cpp-tutorials, Prev: connector-cpp-apps-linux-netbeans, Up: connector-cpp 21.4.6 MySQL Connector/C++ Getting Started: Usage Examples ---------------------------------------------------------- * Menu: * connector-cpp-examples-connecting:: MySQL Connector/C++ Connecting to MySQL * connector-cpp-examples-query:: MySQL Connector/C++ Running a Simple Query * connector-cpp-examples-results:: MySQL Connector/C++ Fetching Results * connector-cpp-examples-prepared-statements:: MySQL Connector/C++ Using Prepared Statements * connector-cpp-examples-complete-example-1:: MySQL Connector/C++ Complete Example 1 * connector-cpp-examples-complete-example-2:: MySQL Connector/C++ Complete Example 2 The download package contains usage examples in the directory `examples/'. These examples explain how to use the following classes: * Connection * Driver * PreparedStatement * ResultSet * ResultSetMetaData * Statement The examples cover: * Using the Driver class to connect to MySQL * Creating tables, inserting rows, fetching rows using (simple) statements * Creating tables, inserting rows, fetching rows using prepared statements * Hints for working around prepared statement limitations * Accessing result set metadata The examples in this document are only code snippets, not complete programs. The code snippets provide a brief overview on the API. For complete programs, check the `examples/' directory of your MySQL Connector/C++ installation Please also read the `README' file in that directory. To test the example code, edit the `examples.h' file in the `examples/' directory to add your connection information, then rebuild the code by issuing a `make' command. The examples in the `examples/' directory include: * `examples/connect.cpp': How to create a connection, insert data into MySQL and handle exceptions. * `examples/connection_meta_schemaobj.cpp': How to obtain metadata associated with a connection object, for example, a list of tables, databases, MySQL version, connector version. * `examples/debug_output.cpp': How to activate and deactivate the MySQL Connector/C++ debug protocol. * `examples/exceptions.cpp': A closer look at the exceptions thrown by the connector and how to fetch error information. * `examples/prepared_statements.cpp': How to run Prepared Statements including an example how to handle SQL statements that cannot be prepared by the MySQL Server. * `examples/resultset.cpp': How to use a cursor to fetch data and iterate over a result set. * `examples/resultset_meta.cpp': How to obtain metadata associated with a result set, for example, number of columns and column types. * `examples/resultset_types.cpp': Result sets returned from metadata methods. (This is more a test than an example.) * `examples/standalone_example.cpp': Simple standalone program not integrated into regular `CMake' builds. * `examples/statements.cpp': How to execute SQL statements without using Prepared Statements. * `examples/cpp_trace_analyzer.cpp': This example shows how to filter the output of the *Note debug trace: connector-cpp-debug-tracing. Please see the inline comments for further documentation. This script is unsupported.  File: manual.info, Node: connector-cpp-examples-connecting, Next: connector-cpp-examples-query, Prev: connector-cpp-getting-started-examples, Up: connector-cpp-getting-started-examples 21.4.6.1 MySQL Connector/C++ Connecting to MySQL ................................................ To establish a connection to MySQL Server, retrieve an instance of sql::Connection from a sql::mysql::MySQL_Driver object. A sql::mysql::MySQL_Driver object is returned by sql::mysql::MySQL_Driver::get_mysql_driver_instance(). sql::mysql::MySQL_Driver *driver; sql::Connection *con; driver = sql::mysql::MySQL_Driver::get_mysql_driver_instance(); con = driver->connect("tcp://127.0.0.1:3306", "user", "password"); delete con; Make sure that you free, `con', the sql::Connection object as soon as you do not need it any more. But do not explicitly free `driver', the connector object! The connector will take care of freeing that.  File: manual.info, Node: connector-cpp-examples-query, Next: connector-cpp-examples-results, Prev: connector-cpp-examples-connecting, Up: connector-cpp-getting-started-examples 21.4.6.2 MySQL Connector/C++ Running a Simple Query ................................................... For running simple queries, you can use the methods sql::Statement::execute(), sql::Statement::executeQuery() and sql::Statement::executeUpdate(). Use the method sql::Statement::execute() if your query does not return a result set or if your query returns more than one result set. See the `examples/' directory for more information. sql::mysql::MySQL_Driver *driver; sql::Connection *con; sql::Statement *stmt; driver = sql::mysql::get_mysql_driver_instance(); con = driver->connect("tcp://127.0.0.1:3306", "user", "password"); stmt = con->createStatement(); stmt->execute("USE " EXAMPLE_DB); stmt->execute("DROP TABLE IF EXISTS test"); stmt->execute("CREATE TABLE test(id INT, label CHAR(1))"); stmt->execute("INSERT INTO test(id, label) VALUES (1, 'a')"); delete stmt; delete con; Note that you must free sql::Statement and sql::Connection objects explicitly using `delete'.  File: manual.info, Node: connector-cpp-examples-results, Next: connector-cpp-examples-prepared-statements, Prev: connector-cpp-examples-query, Up: connector-cpp-getting-started-examples 21.4.6.3 MySQL Connector/C++ Fetching Results ............................................. The API for fetching result sets is identical for (simple) statements and prepared statements. If your query returns one result set, use sql::Statement::executeQuery() or sql::PreparedStatement::executeQuery() to run your query. Both methods return sql::ResultSet objects. The preview version does buffer all result sets on the client to support cursors. // ... sql::Connection *con; sql::Statement *stmt; sql::ResultSet *res; // ... stmt = con->createStatement(); // ... res = stmt->executeQuery("SELECT id, label FROM test ORDER BY id ASC"); while (res->next()) { // You can use either numeric offsets... cout << "id = " << res->getInt(1); // getInt(1) returns the first column // ... or column names for accessing results. // The latter is recommended. cout << ", label = '" << res->getString("label") << "'" << endl; } delete res; delete stmt; delete con; *Note*: In the preceding code snippet, column indexing starts from 1. Note that you must free sql::Statement, sql::Connection and sql::ResultSet objects explicitly using delete. Cursor usage is demonstrated in the examples contained in the download package.  File: manual.info, Node: connector-cpp-examples-prepared-statements, Next: connector-cpp-examples-complete-example-1, Prev: connector-cpp-examples-results, Up: connector-cpp-getting-started-examples 21.4.6.4 MySQL Connector/C++ Using Prepared Statements ...................................................... If you are not familiar with Prepared Statements on MySQL, take a look at the source code comments and explanations in the file `examples/prepared_statement.cpp'. sql::PreparedStatement is created by passing an SQL query to sql::Connection::prepareStatement(). As sql::PreparedStatement is derived from sql::Statement, you will feel familiar with the API once you have learned how to use (simple) statements (sql::Statement). For example, the syntax for fetching results is identical. // ... sql::Connection *con; sql::PreparedStatement *prep_stmt // ... prep_stmt = con->prepareStatement("INSERT INTO test(id, label) VALUES (?, ?)"); prep_stmt->setInt(1, 1); prep_stmt->setString(2, "a"); prep_stmt->execute(); prep_stmt->setInt(1, 2); prep_stmt->setString(2, "b"); prep_stmt->execute(); delete prep_stmt; delete con; As usual, you must free sql::PreparedStatement and sql::Connection objects explicitly.  File: manual.info, Node: connector-cpp-examples-complete-example-1, Next: connector-cpp-examples-complete-example-2, Prev: connector-cpp-examples-prepared-statements, Up: connector-cpp-getting-started-examples 21.4.6.5 MySQL Connector/C++ Complete Example 1 ............................................... The following code shows a complete example of how to use MySQL Connector/C++: /* Copyright 2008, 2010, Oracle and/or its affiliates. All rights reserved. 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; version 2 of the License. There are special exceptions to the terms and conditions of the GPL as it is applied to this software. View the full text of the exception in file EXCEPTIONS-CONNECTOR-C++ in the directory of this software distribution. 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 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ /* Standard C++ includes */ #include #include /* Include directly the different headers from cppconn/ and mysql_driver.h + mysql_util.h (and mysql_connection.h). This will reduce your build time! */ #include "mysql_connection.h" #include #include #include #include using namespace std; int main(void) { cout << endl; cout << "Running 'SELECT 'Hello World!' » AS _message'..." << endl; try { sql::Driver *driver; sql::Connection *con; sql::Statement *stmt; sql::ResultSet *res; /* Create a connection */ driver = get_driver_instance(); con = driver->connect("tcp://127.0.0.1:3306", "root", "root"); /* Connect to the MySQL test database */ con->setSchema("test"); stmt = con->createStatement(); res = stmt->executeQuery("SELECT 'Hello World!' AS _message"); while (res->next()) { cout << "\t... MySQL replies: "; /* Access column data by alias or column name */ cout << res->getString("_message") << endl; cout << "\t... MySQL says it again: "; /* Access column fata by numeric offset, 1 is the first column */ cout << res->getString(1) << endl; } delete res; delete stmt; delete con; } catch (sql::SQLException &e) { cout << "# ERR: SQLException in " << __FILE__; cout << "(" << __FUNCTION__ << ") on line " » << __LINE__ << endl; cout << "# ERR: " << e.what(); cout << " (MySQL error code: " << e.getErrorCode(); cout << ", SQLState: " << e.getSQLState() << " )" << endl; } cout << endl; return EXIT_SUCCESS; }  File: manual.info, Node: connector-cpp-examples-complete-example-2, Prev: connector-cpp-examples-complete-example-1, Up: connector-cpp-getting-started-examples 21.4.6.6 MySQL Connector/C++ Complete Example 2 ............................................... The following code shows a complete example of how to use MySQL Connector/C++: /* Copyright 2008, 2010, Oracle and/or its affiliates. All rights reserved. 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; version 2 of the License. There are special exceptions to the terms and conditions of the GPL as it is applied to this software. View the full text of the exception in file EXCEPTIONS-CONNECTOR-C++ in the directory of this software distribution. 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 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ /* Standard C++ includes */ #include #include /* Include directly the different headers from cppconn/ and mysql_driver.h + mysql_util.h (and mysql_connection.h). This will reduce your build time! */ #include "mysql_connection.h" #include #include #include #include #include using namespace std; int main(void) { cout << endl; cout << "Let's have MySQL count from 10 to 1..." << endl; try { sql::Driver *driver; sql::Connection *con; sql::Statement *stmt; sql::ResultSet *res; sql::PreparedStatement *pstmt; /* Create a connection */ driver = get_driver_instance(); con = driver->connect("tcp://127.0.0.1:3306", "root", "root"); /* Connect to the MySQL test database */ con->setSchema("test"); stmt = con->createStatement(); stmt->execute("DROP TABLE IF EXISTS test"); stmt->execute("CREATE TABLE test(id INT)"); delete stmt; /* '?' is the supported placeholder syntax */ pstmt = con->prepareStatement("INSERT INTO test(id) VALUES (?)"); for (int i = 1; i <= 10; i++) { pstmt->setInt(1, i); pstmt->executeUpdate(); } delete pstmt; /* Select in ascending order */ pstmt = con->prepareStatement("SELECT id FROM test ORDER BY id ASC"); res = pstmt->executeQuery(); /* Fetch in reverse = descending order! */ res->afterLast(); while (res->previous()) cout << "\t... MySQL counts: " << res->getInt("id") << endl; delete res; delete pstmt; delete con; } catch (sql::SQLException &e) { cout << "# ERR: SQLException in " << __FILE__; cout << "(" << __FUNCTION__ << ") on line " » << __LINE__ << endl; cout << "# ERR: " << e.what(); cout << " (MySQL error code: " << e.getErrorCode(); cout << ", SQLState: " << e.getSQLState() << » " )" << endl; } cout << endl; return EXIT_SUCCESS; }  File: manual.info, Node: connector-cpp-tutorials, Next: connector-cpp-debug-tracing, Prev: connector-cpp-getting-started-examples, Up: connector-cpp 21.4.7 MySQL Connector/C++ Tutorials ------------------------------------ * Menu: * connector-cpp-tutorials-background:: Prerequisites and Background Information * connector-cpp-tutorials-stored-routines-statements:: Calling Stored Procedures with `Statement' Objects * connector-cpp-tutorials-stored-routines-prepared-statements:: Calling Stored Procedures with `PreparedStatement' Objects The following tutorials illustrate various aspects of using MySQL Connector/C++. Also consult the examples in *Note connector-cpp-getting-started-examples::.  File: manual.info, Node: connector-cpp-tutorials-background, Next: connector-cpp-tutorials-stored-routines-statements, Prev: connector-cpp-tutorials, Up: connector-cpp-tutorials 21.4.7.1 Prerequisites and Background Information ................................................. This section describes the prerequisites that must be satisifed before you work through the remaining tutorial sections, and shows how to set up the framework code that serves as the basis for the tutorial applications. These tutorials refer to tables and sample data from the `world' database, which you can download from the `Example Databases' section of the MySQL Documentation (http://dev.mysql.com/doc/index-other.html) page. Each tutorial application uses a framework consisting of the following code. The examples vary at the line that says `/* INSERT TUTORIAL CODE HERE! */' within the `try' block, which is replaced for each application with the application-specific code. #include #include #include #include /* uncomment for applications that use vectors */ /*#include */ #include "mysql_connection.h" #include #include #include #include #include #define EXAMPLE_HOST "localhost" #define EXAMPLE_USER "worlduser" #define EXAMPLE_PASS "worldpass" #define EXAMPLE_DB "world" using namespace std; int main(int argc, const char **argv) { string url(argc >= 2 ? argv[1] : EXAMPLE_HOST); const string user(argc >= 3 ? argv[2] : EXAMPLE_USER); const string pass(argc >= 4 ? argv[3] : EXAMPLE_PASS); const string database(argc >= 5 ? argv[4] : EXAMPLE_DB); cout << "Connector/C++ tutorial framework..." << endl; cout << endl; try { /* INSERT TUTORIAL CODE HERE! */ } catch (sql::SQLException &e) { /* MySQL Connector/C++ throws three different exceptions: - sql::MethodNotImplementedException (derived from sql::SQLException) - sql::InvalidArgumentException (derived from sql::SQLException) - sql::SQLException (derived from std::runtime_error) */ cout << "# ERR: SQLException in " << __FILE__; cout << "(" << __FUNCTION__ << ") on line " << __LINE__ << endl; /* what() (derived from std::runtime_error) fetches error message */ cout << "# ERR: " << e.what(); cout << " (MySQL error code: " << e.getErrorCode(); cout << ", SQLState: " << e.getSQLState() << " )" << endl; return EXIT_FAILURE; } cout << "Done." << endl; return EXIT_SUCCESS; } Try the framework code as a standalone program using this procedure: 1. Copy and paste the framework code to a file such as `framework.cpp'. Edit the `#define' statements to reflect your connection parameters (server, user, password, database). Also, because the file contains those parameters, set its access mode to be readable only to yourself. 2. Compile the framework. For example, on Mac OS X, the command might look like this (enter the command on one line): shell> g++ -o framework -I/usr/local/include -I/usr/local/include/cppconn -lmysqlcppconn framework.cpp Adapt the command as necessary for your system. A similar command is needed for the tutorial applications that follow. 3. To run the framework, enter the following: shell> ./framework You will see a simple message: Connector/C++ tutorial framework... Done. You are now ready to continue to the tutorials.  File: manual.info, Node: connector-cpp-tutorials-stored-routines-statements, Next: connector-cpp-tutorials-stored-routines-prepared-statements, Prev: connector-cpp-tutorials-background, Up: connector-cpp-tutorials 21.4.7.2 Calling Stored Procedures with `Statement' Objects ........................................................... A stored procedure can be called using a `Statement' or `PreparedStatement' object. This section shows how to call stored procedures using `Statement' objects. To see how to use `PreparedStatement' objects, see *Note connector-cpp-tutorials-stored-routines-prepared-statements::. You can construct and call different types of stored procedures: 1. A stored procedure that returns no result. For example, such a stored procedure can log non-critical information, or change database data in a straightforward way. 2. A stored procedure that returns one or more values using output parameters. For example, such a procedure can indicate success or failure, or retrieve and return data items. 3. A stored procedure that returns one or more result sets. The procedure can execute one or more queries, each of which returns an arbitrary number of rows. Your application loops through each result set to display, transform, or otherwise process each row in it. The following stored procedures illustrate each of these scenarios. The following procedure adds a country to the `world' database, but does not return a result. This corresponds to Scenario 1 described earlier. CREATE PROCEDURE add_country (IN country_code CHAR(3), IN country_name CHAR(52), IN continent_name CHAR(30)) BEGIN INSERT INTO Country(Code, Name, Continent) VALUES (country_code, country_name, continent_name); END; The next procedures use an output parameter to return the population of a specified country or continent, or the entire world. These correspond to Scenario 2 described earlier. CREATE PROCEDURE get_pop (IN country_name CHAR(52), OUT country_pop BIGINT) BEGIN SELECT Population INTO country_pop FROM Country WHERE Name = country_name; END; CREATE PROCEDURE get_pop_continent (IN continent_name CHAR(30), OUT continent_pop BIGINT) BEGIN SELECT SUM(Population) INTO continent_pop FROM Country WHERE Continent = continent_name; END; CREATE PROCEDURE get_pop_world (OUT world_pop BIGINT) BEGIN SELECT SUM(Population) INTO world_pop FROM Country; END; The next procedure returns several result sets. This corresponds to Scenario 3 described earlier. CREATE PROCEDURE get_data () BEGIN SELECT Code, Name, Population, Continent FROM Country WHERE Continent = 'Oceania' AND Population < 10000; SELECT Code, Name, Population, Continent FROM Country WHERE Continent = 'Europe' AND Population < 10000; SELECT Code, Name, Population, Continent FROM Country WHERE Continent = 'North America' AND Population < 10000; END; Enter and test the stored procedures manually to ensure that they will be available to your C++ applications. (Select `world' as the default database before you create them.) You are now ready to start writing applications using Connector/C++ that call stored procedures. * Scenario 1: Using a `Statement' for a Stored Procedure That Returns No Result * This example shows how to call a stored procedure that returns no result set. 1. Make a copy of the tutorial framework code: shell> cp framework.cpp sp_scenario1.cpp 2. Add the following code to the `try' block of the tutorial framework: sql::Driver* driver = get_driver_instance(); std::auto_ptr con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr stmt(con->createStatement()); // We need not check the return value explicitly. If it indicates // an error, Connector/C++ generates an exception. stmt->execute("CALL add_country('ATL', 'Atlantis', 'North America')"); 3. Compile the program as described in *Note connector-cpp-tutorials-background::. 4. Run the program: shell> ./sp_scenario1 5. Using the *Note `mysql': mysql. command-line client or other suitable program, check the `world' database to determine that it has been updated correctly. You can use this query: mysql> SELECT Code, Name, Continent FROM Country WHERE Code='ATL'; +------+----------+---------------+ | Code | Name | Continent | +------+----------+---------------+ | ATL | Atlantis | North America | +------+----------+---------------+ The code in this application simply invokes the `execute' method, passing to it a statement that calls the stored procedure. The procedure itself returns no value, although it is important to note there is always a return value from the *Note `CALL': call. statement; this is the `execute' status. MySQL Connector/C++ handles this status for you, so you need not handle it explicitly. If the `execute' call fails for some reason, it raises an exception that the `catch' block handles. * Scenario 2: Using a `Statement' for a Stored Procedure That Returns an Output Parameter * This example shows how to handle a stored procedure that returns an output parameter. 1. Make a copy of the tutorial framework code: shell> cp framework.cpp sp_scenario2.cpp 2. Add the following code to the `try' block of the tutorial framework: sql::Driver* driver = get_driver_instance(); std::auto_ptr con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr stmt(con->createStatement()); stmt->execute("CALL get_pop('Uganda', @pop)"); std::auto_ptr res(stmt->executeQuery("SELECT @pop AS _reply")); while (res->next()) cout << "Population of Uganda: " << res->getString("_reply") << endl; stmt->execute("CALL get_pop_continent('Asia', @pop)"); res.reset(stmt->executeQuery("SELECT @pop AS _reply")); while (res->next()) cout << "Population of Asia: " << res->getString("_reply") << endl; stmt->execute("CALL get_pop_world(@pop)"); res.reset(stmt->executeQuery("SELECT @pop AS _reply")); while (res->next()) cout << "Population of World: " << res->getString("_reply") << endl; 3. Compile the program as described in *Note connector-cpp-tutorials-background::. 4. Run the program: shell> ./sp_scenario2 Connector/C++ tutorial framework... Population of Uganda: 21778000 Population of Asia: 3705025700 Population of World: 6078749450 Done. In this scenario, each stored procedure sets the value of an output parameter. This is not returned directly to the `execute' method, but needs to be obtained using a subsequent query. If you were executing the SQL statements directly, you might use statements similar to these: CALL get_pop('Uganda', @pop); SELECT @pop; CALL get_pop_continent('Asia', @pop); SELECT @pop; CALL get_pop_world(@pop); SELECT @pop; In the C++ code, a similar sequence is carried out for each procedure call: * Execute the *Note `CALL': call. statement. * Obtain the output parameter by executing an additional query. The query produces a `ResultSet' object. * Retrieve the data using a `while' loop. The simplest way to do this is to use a `getString' method on the `ResultSet', passing the name of the variable to access. In this example `_reply' is used as a placeholder for the variable and therefore is used as the key to access the correct element of the result dictionary. Although the query used to obtain the output parameter returns only a single row, it is important to use the `while' loop to catch more than one row, to avoid the possibility of the connection becoming unstable. * Scenario 3: Using a `Statement' for a Stored Procedure That Returns a Result Set * This example shows how to handle result sets produced by a stored procedure. *Note*: This scenario requires MySQL 5.5.3 or higher. The client/server protocol does not support fetching multiple result sets from stored procedures prior to 5.5.3. 1. Make a copy of the tutorial framework code: shell> cp framework.cpp sp_scenario3.cpp 2. Add the following code to the `try' block of the tutorial framework: sql::Driver* driver = get_driver_instance(); std::auto_ptr con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr stmt(con->createStatement()); stmt->execute("CALL get_data()"); std::auto_ptr< sql::ResultSet > res; do { res.reset(stmt->getResultSet()); while (res->next()) { cout << "Name: " << res->getString("Name") << " Population: " << res->getInt("Population") << endl; } } while (stmt->getMoreResults()); 3. Compile the program as described in *Note connector-cpp-tutorials-background::. 4. Run the program: shell> ./sp_scenario3 Connector/C++ tutorial framework... Name: Cocos (Keeling) Islands Population: 600 Name: Christmas Island Population: 2500 Name: Norfolk Island Population: 2000 Name: Niue Population: 2000 Name: Pitcairn Population: 50 Name: Tokelau Population: 2000 Name: United States Minor Outlying Islands Population: 0 Name: Svalbard and Jan Mayen Population: 3200 Name: Holy See (Vatican City State) Population: 1000 Name: Anguilla Population: 8000 Name: Atlantis Population: 0 Name: Saint Pierre and Miquelon Population: 7000 Done. The code is similar to the examples shown previously. The code of particular interest here is: do { res.reset(stmt->getResultSet()); while (res->next()) { cout << "Name: " << res->getString("Name") << " Population: " << res->getInt("Population") << endl; } } while (stmt->getMoreResults()); The *Note `CALL': call. is executed as before, but this time the results are returned into multiple `ResultSet' objects because the stored procedure executes multiple `SELECT' statements. In this example, the output shows that three result sets are processed, because there are three `SELECT' statements in the stored procedure. Each result set returns more than one row. The results are processed using this code pattern: do { Get Result Set while (Get Result) { Process Result } } while (Get More Result Sets); *Note*: Use this pattern even if the stored procedure executes only a single `SELECT' and produces only one result set. This is a requirement of the underlying protocol.  File: manual.info, Node: connector-cpp-tutorials-stored-routines-prepared-statements, Prev: connector-cpp-tutorials-stored-routines-statements, Up: connector-cpp-tutorials 21.4.7.3 Calling Stored Procedures with `PreparedStatement' Objects ................................................................... This section shows how to call stored procedures using prepared statements. It is recommended that, before working through it, you first work through the previous tutorial *Note connector-cpp-tutorials-stored-routines-statements::. That section shows the stored procedures required by the applications in this section. * Scenario 1: Using a `PreparedStatement' for a Stored Procedure That Returns No Result * This example shows how to call a stored procedure that returns no result set. 1. Make a copy of the tutorial framework code: shell> cp framework.cpp ps_scenario1.cpp 2. Add the following code to the `try' block of the tutorial framework: vector code_vector; code_vector.push_back("SLD"); code_vector.push_back("DSN"); code_vector.push_back("ATL"); vector name_vector; name_vector.push_back("Sealand"); name_vector.push_back("Disneyland"); name_vector.push_back("Atlantis"); vector cont_vector; cont_vector.push_back("Europe"); cont_vector.push_back("North America"); cont_vector.push_back("Oceania"); sql::Driver * driver = get_driver_instance(); std::auto_ptr< sql::Connection > con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr< sql::PreparedStatement > pstmt; pstmt.reset(con->prepareStatement("CALL add_country(?,?,?)")); for (int i=0; i<3; i++) { pstmt->setString(1,code_vector[i]); pstmt->setString(2,name_vector[i]); pstmt->setString(3,cont_vector[i]); pstmt->execute(); } Also, uncomment `#include ' near the top of the code, because vectors are used to store sample data. 3. Compile the program as described in *Note connector-cpp-tutorials-background::. 4. Run the program: shell> ./ps_scenario1 5. You can check whether the database has been updated correctly by using this query: mysql> SELECT Code, Name, Continent FROM Country -> WHERE Code IN('DSN','ATL','SLD'); +------+------------+---------------+ | Code | Name | Continent | +------+------------+---------------+ | ATL | Atlantis | Oceania | | DSN | Disneyland | North America | | SLD | Sealand | Europe | +------+------------+---------------+ The code is relatively simple, as no processing is required to handle result sets. The procedure call, `CALL add_country(?,?,?)', is made using placeholders for input parameters denoted by `'?''. These placeholders are replaced by the appropriate data values using the `PreparedStatement' object's `setString' method. The `for' loop is set up to iterate 3 times, as there are three data sets in this example. The same `PreparedStatement' is executed three times, each time with different input parameters. * Scenario 2: Using a `PreparedStatement' for a Stored Procedure That Returns an Output Parameter * This example shows how to handle a stored procedure that returns an output parameter. 1. Make a copy of the tutorial framework code: shell> cp framework.cpp ps_scenario2.cpp 2. Add the following code to the `try' block of the tutorial framework: vector cont_vector; cont_vector.push_back("Europe"); cont_vector.push_back("North America"); cont_vector.push_back("Oceania"); sql::Driver * driver = get_driver_instance(); std::auto_ptr< sql::Connection > con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr< sql::Statement > stmt(con->createStatement()); std::auto_ptr< sql::PreparedStatement > pstmt; std::auto_ptr< sql::ResultSet > res; pstmt.reset(con->prepareStatement("CALL get_pop_continent(?,@pop)")); for (int i=0; i<3; i++) { pstmt->setString(1,cont_vector[i]); pstmt->execute(); res.reset(stmt->executeQuery("SELECT @pop AS _population")); while (res->next()) cout << "Population of " << cont_vector[i] << " is " << res->getString("_population") << endl; } Also, uncomment `#include ' near the top of the code, because vectors are used to store sample data. 3. Compile the program as described in *Note connector-cpp-tutorials-background::. 4. Run the program: shell> ./ps_scenario2 Connector/C++ tutorial framework... Population of Europe is 730074600 Population of North America is 482993000 Population of Oceania is 30401150 Done. In this scenario a `PreparedStatement' object is created that calls the `get_pop_continent' stored procedure. This procedure takes an input parameter, and also returns an output parameter. The approach used is to create another statement that can be used to fetch the output parameter using a `SELECT' query. Note that when the `PreparedStatement' is created, the input parameter to the stored procedure is denoted by '?'. Prior to execution of the prepared statement, it is necessary to replace this placeholder by an actual value. This is done using the `setString' method: pstmt->setString(1,cont_vector[i]); Although the query used to obtain the output parameter returns only a single row, it is important to use the `while' loop to catch more than one row, to avoid the possibility of the connection becoming unstable. * Scenario 3: Using a `PreparedStatement' for a Stored Procedure That Returns a Result Set * This example shows how to handle result sets produced by a stored procedure. *Note*: This scenario requires MySQL 5.5.3 or higher. The client/server protocol does not support fetching multiple result sets from stored procedures prior to 5.5.3. 1. Make a copy of the tutorial framework code: shell> cp framework.cpp ps_scenario3.cpp 2. Add the following code to the `try' block of the tutorial framework: sql::Driver * driver = get_driver_instance(); std::auto_ptr< sql::Connection > con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr< sql::PreparedStatement > pstmt; std::auto_ptr< sql::ResultSet > res; pstmt.reset(con->prepareStatement("CALL get_data()")); res.reset(pstmt->executeQuery()); do { res.reset(pstmt->getResultSet()); while (res->next()) { cout << "Name: " << res->getString("Name") << " Population: " << res->getInt("Population") << endl; } } while (pstmt->getMoreResults()); 3. Compile the program as described in *Note connector-cpp-tutorials-background::. 4. Run the program: shell> ./ps_scenario3 5. Make a note of the output generated. The code executes the stored procedure using a `PreparedStatement' object. The standard `do'/`while' construct is used to ensure that all result sets are fetched. The returned values are fetched from the result sets using the `getInt' and `getString' methods.  File: manual.info, Node: connector-cpp-debug-tracing, Next: connector-cpp-usage-notes, Prev: connector-cpp-tutorials, Up: connector-cpp 21.4.8 MySQL Connector/C++ Debug Tracing ---------------------------------------- Although a debugger can be used to debug your application, you may find it beneficial to turn on the debug traces of the connector. Some problems happen randomly which makes them difficult to debug using a debugger. In such cases, debug traces and protocol files are more useful because they allow you to trace the activities of all instances of your program. DTrace is a very powerful technology to trace any application without having to develop an extra trace module for your application. Unfortunately, DTrace is currently only available on Solaris, Mac OS X 10.5, and FreeBSD. MySQL Connector/C++ can write two trace files: 1. Trace file generated by the MySQL client library 2. Trace file generated internally by MySQL Connector/C++ The first trace file can be generated by the underlying MySQL client library (`libmysqlclient'). To enable this trace, the connector will call the *Note `mysql_debug()': mysql-debug. C API function internally. Because only debug versions of the MySQL client library are capable of writing a trace file, compile MySQL Connector/C++ against a debug version of the library to use this trace. The trace shows the internal function calls and the addresses of internal objects as shown here: >mysql_stmt_init | >_mymalloc | | enter: Size: 816 | | exit: ptr: 0x68e7b8 | <_mymalloc | >init_alloc_root | | enter: root: 0x68e7b8 | | >_mymalloc | | | enter: Size: 2064 | | | exit: ptr: 0x68eb28 [...] The second trace is the MySQL Connector/C++ internal trace. It is available with debug and nondebug builds of the connector as long as you have enabled the tracing module at compile time using `cmake -DMYSQLCPPCONN_TRACE_ENABLE:BOOL=1'. By default, tracing functionality is not available and calls to trace functions are removed by the preprocessor. Compiling the connector with tracing functionality enabled causes two additional tracing function calls per each connector function call. For example: | INF: Tracing enabled MySQL_Prepared_Statement::setInt | INF: this=0x69a2e0 | >MySQL_Prepared_Statement::checkClosed | con(driver->connect(host, user, pass)); /* Activate debug trace of the MySQL client library (C API) Only available with a debug build of the MySQL client library! */ con->setClientOption("libmysql_debug", "d:t:O,client.trace"); /* Connector/C++ tracing is available if you have compiled the driver using cmake -DMYSQLCPPCONN_TRACE_ENABLE:BOOL=1 */ con->setClientOption("client_trace", &on_off);  File: manual.info, Node: connector-cpp-usage-notes, Next: connector-cpp-bugs, Prev: connector-cpp-debug-tracing, Up: connector-cpp 21.4.9 MySQL Connector/C++ Usage Notes -------------------------------------- MySQL Connector/C++ is compatible with the JDBC 4.0 API. See the JDBC overview (http://www.oracle.com/technetwork/java/overview-141217.html) for information on JDBC 4.0. Please also check the `examples/' directory of the download package. * The MySQL Connector/C++ sql::DataType class defines the following JDBC standard data types: `UNKNOWN', `BIT', `TINYINT', `SMALLINT', `MEDIUMINT', `INTEGER', `BIGINT', `REAL', `DOUBLE', `DECIMAL', `NUMERIC', `CHAR', `BINARY', `VARCHAR', `VARBINARY', `LONGVARCHAR', `LONGVARBINARY', `TIMESTAMP', `DATE', `TIME', `GEOMETRY', `ENUM', `SET', `SQLNULL'. MySQL Connector/C++ does not support the following JDBC standard data types: `ARRAY', `BLOB', `CLOB', `DISTINCT', `FLOAT', `OTHER', `REF', `STRUCT'. * `DatabaseMetaData::supportsBatchUpdates()' returns `true' because MySQL supports batch updates in general. However, the MySQL Connector/C++ API provides no API calls for batch updates. * Two non-JDBC methods let you fetch and set unsigned integers: `getUInt64()' and `getUInt()'. These are available for ResultSet and Prepared_Statement: * `ResultSet::getUInt64()' * `ResultSet::getUInt()' * `Prepared_Statement::setUInt64()' * `Prepared_Statement::setUInt()' The corresponding `getLong()' and `setLong()' methods have been removed. * The `DatabaseMetaData::getColumns()' method has 23 columns in its result set, rather than the 22 columns defined by JDBC. The first 22 columns are as described in the JDBC documentation, but column 23 is new: 23. `IS_AUTOINCREMENT': A string which is `YES' if the column is an auto-increment column, `NO' otherwise. * MySQL Connector/C++ may return different metadata for the same column, depending on the method you call. Suppose that you have a column that accepts a character set and a collation in its specification and you specify a binary collation, such as: VARCHAR(20) CHARACTER SET utf8 COLLATE utf8_bin The server sets the `BINARY' flag in the result set metadata of this column. The `ResultSetMetadata::getColumnTypeName()' method uses the metadata and will report, due to the `BINARY' flag, that the column type name is `BINARY'. This is illustrated here: mysql> CREATE TABLE varbin (a VARCHAR(20) CHARACTER SET utf8 COLLATE utf8_bin); Query OK, 0 rows affected (0.00 sec) mysql> select * from varbin; Field 1: `a` Catalog: `def` Database: `test` Table: `varbin` Org_table: `varbin` Type: VAR_STRING Collation: latin1_swedish_ci (8) Length: 20 Max_length: 0 Decimals: 0 Flags: BINARY 0 rows in set (0.00 sec) mysql> SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME='varbin'\G *************************** 1. row *************************** TABLE_CATALOG: NULL TABLE_SCHEMA: test TABLE_NAME: varbin COLUMN_NAME: a ORDINAL_POSITION: 1 COLUMN_DEFAULT: NULL IS_NULLABLE: YES DATA_TYPE: varchar CHARACTER_MAXIMUM_LENGTH: 20 CHARACTER_OCTET_LENGTH: 60 NUMERIC_PRECISION: NULL NUMERIC_SCALE: NULL CHARACTER_SET_NAME: utf8 COLLATION_NAME: utf8_bin COLUMN_TYPE: varchar(20) COLUMN_KEY: EXTRA: PRIVILEGES: select,insert,update,references COLUMN_COMMENT: 1 row in set (0.01 sec) However, `INFORMATION_SCHEMA' gives no hint in its `COLUMNS' table that metadata will contain the `BINARY' flag. `DatabaseMetaData::getColumns()' uses `INFORMATION_SCHEMA' and will report the type name `VARCHAR' for the same column. It also returns a different type code. * When inserting or updating `BLOB' or `TEXT' columns, MySQL Connector/C++ developers are advised not to use `setString()'. Instead, use the dedicated `setBlob()' API function. The use of `setString()' can cause a *Note Packet too large: packet-too-large. error message. The error occurs if the length of the string passed to the connector using `setString()' exceeds `max_allowed_packet' (minus a few bytes reserved in the protocol for control purposes). This situation is not handled in MySQL Connector/C++, because it could lead to security issues, such as extremely large memory allocation requests due to malevolently long strings. If `setBlob()' is used, this problem does not arise because `setBlob()' takes a streaming approach based on `std::istream'. When sending the data from the stream to MySQL Server, MySQL Connector/C++ splits the stream into chunks appropriate for MySQL Server using the current `max_allowed_packet' setting. *Caution*: When using `setString()', it is not possible to set `max_allowed_packet' to a value large enough for the string prior to passing it to MySQL Connector/C++. That configuration option cannot be changed within a session. This difference from the JDBC specification ensures that MySQL Connector/C++ is not vulnerable to memory flooding attacks. * In general, MySQL Connector/C++ works with MySQL 5.0, but it is not completely supported. Some methods may not be available when connecting to MySQL 5.0. This is because the Information Schema is used to obtain the requested information. There are no plans to improve the support for 5.0 because the current GA version of MySQL Server is 5.6. MySQL Connector/C++ is primarily targeted at the MySQL Server GA version that is available on its release. The following methods throw a `sql::MethodNotImplemented' exception when you connect to a MySQL server earlier than 5.1: * `DatabaseMetadata::getCrossReference()' * `DatabaseMetadata::getExportedKeys()' * MySQL Connector/C++ includes a `Connection::getClientOption()' method that is not included in the JDBC API specification. The prototype is: void getClientOption(const std::string & optionName, void * optionValue) The method can be used to check the value of connection properties set when establishing a database connection. The values are returned through the `optionValue' argument passed to the method with the type `void *'. Currently, `getClientOption()' supports fetching the `optionValue' of the following options: * `metadataUseInfoSchema' * `defaultStatementResultType' * `defaultPreparedStatementResultType' The `metadataUseInfoSchema' connection option controls whether to use the `Information_Schemata' for returning the metadata of `SHOW' statements: * For `metadataUseInfoSchema', interpret the `optionValue' argument as a boolean upon return. * For `defaultStatementResultType' and `defaultPreparedStatementResultType', interpret the `optionValue' argument as an integer upon return. The connection property can be set either when establishing the connection through the connection property map, or using `void Connection::setClientOption(const std::string & optionName, const void * optionValue)' where `optionName' is assigned the value `metadataUseInfoSchema'. Some examples: bool isInfoSchemaUsed; conn->getClientOption("metadataUseInfoSchema", (void *) &isInfoSchemaUsed); int defaultStmtResType; int defaultPStmtResType; conn->getClientOption("defaultStatementResultType", (void *) &defaultStmtResType); conn->getClientOption("defaultPreparedStatementResultType", (void *) &defaultPStmtResType); * MySQL Connector/C++ supports the following methods not found in the JDBC API standard: std::string MySQL_Connection::getSessionVariable(const std::string & varname) void MySQL_Connection::setSessionVariable(const std::string & varname, const std::string & value) These methods get and set MySQL session variables. Both are members of the `MySQL_Connection' class. `getSessionVariable()' is equivalent to executing the following and fetching the first return value: SHOW SESSION VARIABLES LIKE "" You can use the `%' and `_' SQL pattern characters in . `setSessionVariable()' is equivalent to executing: SET SESSION = * Fetching the value of a column can sometimes return different values depending on whether the call is made from a Statement or Prepared Statement. This is because the protocol used to communicate with the server differs depending on whether a Statement or Prepared Statement is used. To illustrate this, consider the case where a column has been defined as type `BIGINT'. The most negative `BIGINT' value is then inserted into the column. If a Statement and Prepared Statement are created that perform a `GetUInt64()' call, then the results will be different in each case. The Statement returns the maximum positive value for `BIGINT'. The Prepared Statement returns 0. The difference results from the fact that Statements use a text protocol, and Prepared Statements use a binary protocol. With the binary protocol in this case, a binary value is returned from the server that can be interpreted as an `int64'. In the preceding scenario, a very large negative value is fetched with `GetUInt64()', which fetches unsigned integers. Because the large negative value cannot be sensibly converted to an unsigned value, 0 is returned. In the case of the Statement, which uses the text protocol, values are returned from the server as strings, and then converted as required. When a string value is returned from the server in the preceding scenario, the large negative value must be converted by the runtime library function `strtoul()', which `GetUInt64()' calls. The behavior of `strtoul()' is dependent upon the specific runtime and host operating system, so the results can be platform dependent. In the case, given a large positive value was actually returned. Although it is very rare, there are some cases where Statements and Prepared Statements can return different values unexpectedly, but this usually only happens in extreme cases such as the one mentioned. * The JDBC documentation lists many fields (http://docs.oracle.com/javase/7/docs/api/java/sql/DatabaseMetaData.html) for the `DatabaseMetaData' class. JDBC also appears to define certain values (http://docs.oracle.com/javase/7/docs/api/java/sql/DatabaseMetaData.html#attributeNoNulls) for those fields. However, MySQL Connector/C++ does not define certain values for those fields. Internally enumerations are used and the compiler determines the values to assign to a field. To compare a value with the field, use code such as the following, rather than making assumptions about specific values for the attribute: // dbmeta is an instance of DatabaseMetaData if (myvalue == dbmeta->attributeNoNulls) { ... } Usually MYVALUE will be a column from a result set holding metadata information. MySQL Connector/C++ does not guarantee that `attributeNoNulls' is 0. It can be any value. * When programming stored procedures, JDBC has available an extra class, an extra abstraction layer for callable statements, the `CallableStatement' class. As this class is not present in MySQL Connector/C++, use the methods from the `Statement' and `PreparedStatement' classes to execute a stored procedure using *Note `CALL': call.  File: manual.info, Node: connector-cpp-bugs, Next: connector-cpp-support, Prev: connector-cpp-usage-notes, Up: connector-cpp 21.4.10 MySQL Connector/C++ Known Bugs and Issues ------------------------------------------------- Please report bugs through the MySQL Bug System. See *Note bug-reports::. For release notes detailing the changes in each release of Connector/C++, see MySQL Connector/C++ Release Notes (http://dev.mysql.com/doc/relnotes/connector-cpp/en/). * When linking against a static library for 1.0.3 on Windows, define `CPPDBC_PUBLIC_FUNC' either in the compiler options (preferable) or with `/D "CPPCONN_PUBLIC_FUNC="'. You can also explicitly define it in your code by placing `#define CPPCONN_PUBLIC_FUNC' before the header inclusions. * Generally speaking, C++ library binaries are less portable than C library binaries. Issues can be caused by name mangling, different Standard Template Library (STL) versions, and using different compilers and linkers for linking against the libraries than were used for building the library itself. Even a small change in the compiler version can cause problems. If you obtain error messages that you suspect are related to binary incompatibilities, build MySQL Connector/C++ from source, using the same compiler and linker that you will use to build and link your application. Due to the variations between Linux distributions, compiler and linker versions and STL versions, it is not possible to provide binaries for each and every possible configuration. However, the MySQL Connector/C++ binary distributions contain a `README' file that describes the environment and settings used to build the binary versions of the libraries. * To avoid potential crashes, the build configuration of MySQL Connector/C++ should match the build configuration of the application using it. For example, do not use the release build of MySQL Connector/C++ with a debug build of the client application.  File: manual.info, Node: connector-cpp-support, Prev: connector-cpp-bugs, Up: connector-cpp 21.4.11 MySQL Connector/C++ Support ----------------------------------- For general discussion of the MySQL Connector/C++ please use the C/C++ community forum (http://forums.mysql.com/list.php?167) or join the MySQL Connector/C++ mailing list (http://lists.mysql.com). Bugs can be reported at the MySQL bug Web site (http://bugs.mysql.com). For release notes detailing the changes in each release of MySQL Connector/C++, see MySQL Connector/C++ Release Notes (http://dev.mysql.com/doc/relnotes/connector-cpp/en/). For Licensing questions, and to purchase MySQL Products and Services, please see http://www.mysql.com/buy-mysql/  File: manual.info, Node: connector-c, Next: connector-python, Prev: connector-cpp, Up: connectors-apis 21.5 MySQL Connector/C ====================== * Menu: * connector-c-versions:: MySQL Connector/C Versions * connector-c-platforms:: MySQL Connector/C Supported Platforms * connector-c-contents:: MySQL Connector/C Distribution Contents * connector-c-installation:: Installing MySQL Connector/C * connector-c-applications:: Building MySQL Connector/C Applications MySQL Connector/C is a client library that implements the C API for client/server communication. It is a standalone replacement for the MySQL client library shipped with MySQL Server distributions. See *Note c-api-implementations::. Reasons to use MySQL Connector/C: * If you need only the client library, MySQL Connector/C provides everything required. There is no need to compile or install the MySQL Server package, which is much larger. * MySQL Connector/C does not rely on the MySQL Server release cycle. Bug fixes and new features can be distributed independently of MySQL Server releases. For documentation of the C API implemented by MySQL Connector/C, see *Note c-api::. For release notes detailing the changes in each release of MySQL Connector/C, see MySQL Connector/C Release Notes (http://dev.mysql.com/doc/relnotes/connector-c/en/). The following discussion covers these topics: * MySQL Connector/C versions and supported platforms * MySQL Connector/C distribution contents * Obtaining and installing MySQL Connector/C * Building client programs that use MySQL Connector/C  File: manual.info, Node: connector-c-versions, Next: connector-c-platforms, Prev: connector-c, Up: connector-c 21.5.1 MySQL Connector/C Versions --------------------------------- These versions of MySQL Connector/C are available: * MySQL Connector/C 6.1: Based on the C API parts of current MySQL sources and kept up to date with those sources. * MySQL Connector/C 6.0: Created originally from a branch of the MySQL source tree, but now out of date with respect to C API changes in that tree. Consequently, MySQL Connector/C 6.1 is preferred over 6.0. MySQL Connector/C 6.1 provides these features not present in 6.0: * Support for the pluggable authentication framework that enables implementation of authentication methods as plugins. This framework can be used for MySQL native authentication as well as external authentication methods. See Pluggable Authentication (http://dev.mysql.com/doc/refman/5.5/en/pluggable-authentication.html). * Client-side support for the SHA-256, PAM, and Windows native authentication plugins. See The SHA-256 Authentication Plugin (http://dev.mysql.com/doc/refman/5.6/en/sha256-authentication-plugin.html), The PAM Authentication Plugin (http://dev.mysql.com/doc/refman/5.5/en/pam-authentication-plugin.html), and The Windows Native Authentication Plugin (http://dev.mysql.com/doc/refman/5.5/en/windows-authentication-plugin.html). The older MySQL Connector/C 6.0 can connect only to accounts that use native MySQL passwords. If a client program attempts to connect to an account that requires a different authentication method, an `Access denied for user' error occurs. * Support for connecting to accounts that have expired passwords. See Password Expiration and Sandbox Mode (http://dev.mysql.com/doc/refman/5.6/en/password-expiration.html). * Support for prepared *Note `CALL': call. statements. This enables client programs to handle stored procedures that produce multiple result sets and to obtain the final value of `OUT' and `INOUT' procedure parameters. See *Note c-api-prepared-call-statements::. * Support for connecting over IPv6. See IPv6 Support (http://dev.mysql.com/doc/refman/5.5/en/ipv6-support.html). * Support for binding client programs to a specific IP address at connect time. See *Note mysql-options::. * Support for specifying connection attributes to pass to the server at connect time. See *Note mysql-options::, and `mysql_options4()' (http://dev.mysql.com/doc/refman/5.6/en/mysql-options4.html).  File: manual.info, Node: connector-c-platforms, Next: connector-c-contents, Prev: connector-c-versions, Up: connector-c 21.5.2 MySQL Connector/C Supported Platforms -------------------------------------------- The following tables indicate the platforms on which MySQL Connector/C has been tested. *Supported Platforms for MySQL Connector/C 6.1* Platform Versions Windows Windows Vista, Server 2008, Server 2012, 7, 8 Linux Oracle and RHEL 5, 6; SuSE LES 11; CentOS 5, 6; Fedora 15, 16; OpenSuSE 12.1; Debian 6; Ubuntu 12.04; generic `glibc 2.5'-based Linux systems Solaris 10, 11 Mac OS X 10.6, 10.7 FreeBSD 9 *Supported Platforms for MySQL Connector/C 6.0.2* Platform Versions Windows Windows 2000, XP, Vista, Server 2003, Server 2008 Linux RHEL 4, 5; SuSE LES 9, 10; generic `glibc 2'-based Linux systems Solaris 8, 9, 10 Mac OS X 10.4, 10.5 FreeBSD 6, 7 HP-UX 11.11, 11.23, 11.31 IBM AIX 5.3  File: manual.info, Node: connector-c-contents, Next: connector-c-installation, Prev: connector-c-platforms, Up: connector-c 21.5.3 MySQL Connector/C Distribution Contents ---------------------------------------------- MySQL Connector/C 6.1 distributions contain the header, library, and utility files necessary to build MySQL client applications that communicate with MySQL Server using the C API. Distributions are available in binary and source formats. A binary distribution contains the header, library, and utility components discussed following, compiled and ready for use in writing client programs. A source distribution contains the source files required to produce the same headers, libraries, and utilities included in a binary distribution, but you compile them yourself. MySQL Connector/C distributions include these components: * A set of `.h' header files that C applications include at compile time. These files are located in the `include' directory. * Static and dynamic libraries that C applications link to at link time. These libraries are located in the `lib' directory. The library names 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 Mac OS X. * 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. 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. * Utilities. MySQL Connector/C 6.1 includes the following utilities, located in the `bin' directory. They are the same as in MySQL Server distributions: * *Note `mysql_config': mysql-config. displays flags needed to compile C applications to use MySQL Connector/C. This utility is a shell script and is included only for Unix systems. See *Note mysql-config::. * *Note `my_print_defaults': my-print-defaults. displays the options that are present in option groups within option files. See *Note my-print-defaults::. * *Note `perror': perror. displays error messages corresponding to error codes. See *Note perror::. MySQL Connector/C 6.0 distributions are similar to 6.1 distributions, with these exceptions: * Debug libraries, *Note `my_print_defaults': my-print-defaults, and *Note `perror': perror. are not included. * *Note `mysql_config': mysql-config. is an executable program that is available on all platforms. However, this version of *Note `mysql_config': mysql-config. is more limited than the shell script version in the types of information it can display.  File: manual.info, Node: connector-c-installation, Next: connector-c-applications, Prev: connector-c-contents, Up: connector-c 21.5.4 Installing MySQL Connector/C ----------------------------------- * Menu: * connector-c-installation-binary:: Installing MySQL Connector/C from a Binary Distribution * connector-c-installation-source:: Installing MySQL Connector/C from Source * connector-c-postinstallation:: Postinstallation Steps * connector-c-testing:: Testing MySQL Connector/C MySQL Connector/C Distributions are available in binary and source formats. Binary distributions are available in native format for many platforms, such as RPM packages for Linux, DMG packages for Mac OS X, and PKG packages for Solaris. Distributions are also available in more generic formats such as Zip archives or compressed `tar' files. To obtain a distribution, visit MySQL Connector/C downloads (http://dev.mysql.com/downloads/connector/c/). For a list of supported platforms, see *Note connector-c-platforms::. After installing MySQL Connector/C, you may need to take additional steps to enable your compiler or linker to find the C API header files and libraries. See *Note connector-c-postinstallation::.  File: manual.info, Node: connector-c-installation-binary, Next: connector-c-installation-source, Prev: connector-c-installation, Up: connector-c-installation 21.5.4.1 Installing MySQL Connector/C from a Binary Distribution ................................................................ Installers in native package formats are available for many Unix and Unix-like systems, and for Windows. Alternatively, you can install using a distribution in a more generic format such as a Zip archive or compressed `tar' file. You may need to have `root' or administrator privileges to perform the installation operation. * Installing MySQL Connector/C on Unix Using Compressed `tar' Files * On Unix and Unix-like systems, a generic MySQL Connector/C binary distribution is packaged as a compressed `tar' file, denoted here as `PACKAGE.tar.gz'. To install a distribution file, unpack it in the intended installation directory using this command: shell> tar zxvf PACKAGE.tar.gz * Installing MySQL Connector/C on Microsoft Windows * Windows users can choose between two binary packaging formats: * Windows MSI Installer (`.msi' file): To use the MSI Installer, launch it and follow the prompts in the screens it presents to install MySQL Connector/C in the location of your choosing. * Zip archive without installer (`.zip' file): To use a Zip archive, unpack it in the intended installation directory using `WinZip' or another tool that can read `.zip' files. * Installing MySQL Connector/C on Mac OS X Using DMG Packages * A Mac OS X native package installer is provided as a DMG (disk image) file. To install a DMG package, double-click the image file, then follow the prompts. By default, the DMG package installs MySQL Connector/C under `/usr/local', into a dedicated directory that does not conflict with the one used by MySQL Server DMG packages. * Installing MySQL Connector/C on Linux Using RPM Packages * There are two Linux RPM packages for MySQL Connector/C. Install one or both, depending on the capabilities you require: * The `shared' RPM contains the shared client library. Install this RPM if you intend to compile or run C API applications that depend on the shared client library. * The `devel' RPM contains the header files and the static client library. Install this RPM if you intend to compile C API applications. RPM packages for MySQL Connector/C do not include the *Note `perror': perror. or *Note `my_print_defaults': my-print-defaults. utilities. A Linux RPM package is provided as a file with an `.rpm' suffix, denoted here as `PACKAGE.rpm'. To install a given RPM package, use this command: shell> rpm -i PACKAGE.rpm RPM provides a feature to verify the integrity and authenticity of packages before installing them. To learn more about this feature, see *Note verifying-package-integrity::. * Installing MySQL Connector/C on Solaris Using PKG Packages * A Solaris PKG package is provided as a file with a `.pkg.gz' suffix, denoted here as `PACKAGE.pkg.gz'. To install a PKG package, uncompress it: shell> gunzip PACKAGE.pkg.gz Uncompressing `PACKAGE.pkg.gz' produces `PACKAGE.pkg'. Then use `pkgadd' and follow the onscreen prompts: shell> pkgadd -d PACKAGE.pkg By default, the PKG package installs MySQL Connector/C under the root path `/opt/mysql', into a dedicated directory that does not conflict with the one used by MySQL Server PKG packages. You can change only the installation root path 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.  File: manual.info, Node: connector-c-installation-source, Next: connector-c-postinstallation, Prev: connector-c-installation-binary, Up: connector-c-installation 21.5.4.2 Installing MySQL Connector/C from Source ................................................. A MySQL Connector/C source distribution is packaged as a compressed `tar' file, Zip archive, or RPM package, denoted here as `PACKAGE.tar.gz', `PACKAGE.zip', or. `PACKAGE.src.rpm'. A source distribution in `tar' file or Zip archive format can be used on any supported platform listed in *Note connector-c-platforms::. An RPM package source distribution is intended for RPM-based systems such as Linux. To install a compressed `tar' file, use this command in the intended installation directory: shell> tar zxvf PACKAGE.tar.gz After unpacking the distribution, build it using the appropriate instructions for your platform later in this section. To unpack a Zip archive, use `WinZip' or another tool that can read `.zip' files. After unpacking the distribution, build it using the appropriate instructions for your platform later in this section. To install an RPM package, use this command to create binary RPM packages that you can install. If you do not have `rpmbuild', use `rpm' instead. shell> rpmbuild --rebuild --clean PACKAGE.src.rpm The command should produce binary `shared' and `devel' RPM packages and indicate where it placed them. You can install these packages using the instructions in *Note connector-c-installation-binary::. * Building MySQL Connector/C on Unix from Source * If the native compiler toolset for the target platform is available (for example, SunStudio for Solaris), you can use that for compilation. Alternatively, the GNU toolset can be used on all platforms. You also need `CMake' 2.6 or newer, which is available from cmake.org (http://www.cmake.org). To build and install the source distribution, use the following procedure: 1. Change location to the top-level directory of the source distribution. 2. Generate the `Makefile': shell> cmake -G "Unix Makefiles" Or, for a Debug build: shell> cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug By default, the installation location for MySQL Connector/C is `/usr/local/mysql'. To change this location, use the `CMAKE_INSTALL_PREFIX' option to specify a different directory when generating the `Makefile'. For example: shell> cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/opt/local/mysql For other `CMake' options that you might find useful, see Other MySQL Connector/C Build Options. 3. Build the project: shell> make 4. As `root', install the MySQL Connector/C headers, libraries, and utilities: root-shell> make install * Building MySQL Connector/C on Microsoft Windows from Source * MySQL Connector/C can be built on several versions of Microsoft Windows, listed in *Note connector-c-platforms::. Microsoft Visual Studio 8 or 9 is recommended. The Express Edition of Visual Studio and other compilers might work, but are untested. You also need `CMake' 2.6 or newer, which is available from cmake.org (http://www.cmake.org). To build and install the source distribution, use the following procedure: 1. Set the environment variables for the Visual Studio toolchain. Visual Studio includes a batch file to set these for you, and installs a shortcut in the `Start' menu to open a command prompt with these variables set. 2. Change location to the top-level directory of the source distribution. 3. Generate the `Makefile' by entering the following command in a command-prompt window: shell> cmake -G "Visual Studio 9 2008" For other `CMake' options that you might find useful, see Other MySQL Connector/C Build Options. The result of the `cmake' command is a project (solution) file, `libmysql.sln', that you can open with Visual Studio. Alternatively, build from the command line with either of these commands: shell> devenv.com libmysql.sln /build Release shell> devenv.com libmysql.sln /build RelWithDebInfo For other versions of Visual Studio or for an `nmake'-based build, use the following command to check which generators can be specified with the `-G' option: shell> cmake --help To compile a Debug build, you must set the `CMake' build type so the correct external library versions are used, then compile using the `Debug' solution configuration: shell> cmake -G "Visual Studio 9 2008" -DCMAKE_BUILD_TYPE=Debug shell> devenv.com libmysql.sln /build Debug A normal build builds the C API libraries for the `lib' directory. A Debug build additionally builds debug libraries for the `lib/debug' directory. You must use the debug libraries to compile clients built using the debug C runtime. 4. Use the install operation provided by your development environment to install the MySQL Connector/C headers, libraries, and utilities. You can also use this `CMake' command: shell> cmake --build . --target INSTALL --config RelWithDebInfo * Other MySQL Connector/C Build Options * The following tables show other options that can be used when building MySQL Connector/C from source. *Build Options for MySQL Connector/C 6.1* Build Option Description -DWITH_SSL=system Enable dynamic linking to the system OpenSSL library. -DWITH_ZLIB=system Enable dynamic linking to the system Zlib library. *Build Options for MySQL Connector/C 6.0* Build Option Description -DWITH_OPENSSL=1 Enable dynamic linking to the system OpenSSL library. -DWITH_EXTERNAL_ZLIB=1 Enable dynamic linking to the system Zlib library.  File: manual.info, Node: connector-c-postinstallation, Next: connector-c-testing, Prev: connector-c-installation-source, Up: connector-c-installation 21.5.4.3 Postinstallation Steps ............................... MySQL Connector/C binary `.tar.gz' and `.zip' packages unpack into a directory with a name such as `mysql-connector-c-6.1.0-linux-rhel5-x86-64bit'. If you want to work with a simpler name, rename the directory. On Unix, an alternative is to create a symbolic link with a simpler name: shell> ln -s mysql-connector-c-6.1.0-linux-rhel5-x86-64bit connector-c When you build C applications that use MySQL Connector/C, if the compiler or linker have trouble finding the MySQL Connector/C header files or libraries, you may need to adjust your development tools or runtime environment. See *Note c-api-building-clients::, and *Note c-api-running-clients::.  File: manual.info, Node: connector-c-testing, Prev: connector-c-postinstallation, Up: connector-c-installation 21.5.4.4 Testing MySQL Connector/C .................................. If you build MySQL Connector/C from source, you can use the instructions in this section to test it. The details of the test procedure depend on your MySQL Connector/C version, except that a running MySQL server instance must be available regardless of version. To test MySQL Connector/C 6.1: Use the `mysql_client_test' utility in the `tests' directory. For information about the MySQL Test Framework, see the manual available at `http://dev.mysql.com/doc/mysqltest/2.0/en/'. To test MySQL Connector/C 6.0: Use the `ctest' command. Before you run the test suite, specify the following environment variables: * `MYSQL_TEST_HOST': The host where the MySQL server is running (default `localhost') * `MYSQL_TEST_USER': The user name of the MySQL account to use * `MYSQL_TEST_PASSWD': The password of the MySQL account to use * `MYSQL_TEST_PORT': The TCP/IP port to connect to * `MYSQL_TEST_SOCKET': The socket file to connect to * `MYSQL_TEST_DB': The default database to use (default `test') To run the test suite, execute `ctest' from the command line: shell> ctest  File: manual.info, Node: connector-c-applications, Prev: connector-c-installation, Up: connector-c 21.5.5 Building MySQL Connector/C Applications ---------------------------------------------- To build C applications that use MySQL Connector/C, the connector must be installed. If you need to do that first, see *Note connector-c-installation::. For instructions on building MySQL Connector/C applications, see *Note c-api-building-clients::. To enable your compiler to find the header and library files under the directory where you installed MySQL Connector/C, specify the appropriate compile-time options, as indicated in that section. For binary distributions, the `docs/INFO_BIN' file contains information about the build environment used to compile MySQL Connector/C. This may help you select compatible tools for compiling client applications.  File: manual.info, Node: connector-python, Next: libmysqld, Prev: connector-c, Up: connectors-apis 21.6 MySQL Connector/Python =========================== * Menu: * connector-python-coding:: Guidelines for Python Developers * connector-python-versions:: Connector/Python Versions * connector-python-installation:: Connector/Python Installation * connector-python-examples:: Connector/Python Coding Examples * connector-python-tutorials:: Connector/Python Tutorials * connector-python-connectargs:: Connector/Python Connection Arguments * connector-python-other:: Connector/Python Other Topics * connector-python-reference:: Connector/Python API Reference MySQL Connector/Python enables Python programs to access MySQL databases, using an API that is compliant with the Python DB API version 2.0 (http://www.python.org/dev/peps/pep-0249/). It is written in pure Python and does not have any dependencies except for the Python Standard Library (http://docs.python.org/library/). For release notes detailing the changes in each release of Connector/Python, see MySQL Connector/Python Release Notes (http://dev.mysql.com/doc/relnotes/connector-python/en/). MySQL Connector/Python includes support for: * Almost all features provided by MySQL Server up to and including MySQL Server version 5.5. * Converting parameter values back and forth between Python and MySQL data types, for example Python `datetime' and MySQL `DATETIME'. You can turn automatic conversion on for convenience, or off for optimal performance. * All MySQL extensions to standard SQL syntax. * Protocol compression, which enables compressing the data stream between the client and server. * Connections using TCP/IP sockets and on Unix using Unix sockets. * Secure TCP/IP connections using SSL. * Self-contained driver. Connector/Python does not require the MySQL client library or any Python modules outside the standard library. MySQL Connector/Python 1.1 supports Python from version 2.6 through 2.7, and Python 3.1 and later. MySQL Connector/Python 1.0 supports Python from version 2.4 through 2.7, and Python 3.1 and later. Note that Connector/Python does not support the old MySQL Server authentication methods, which means that MySQL versions prior to 4.1 will not work.  File: manual.info, Node: connector-python-coding, Next: connector-python-versions, Prev: connector-python, Up: connector-python 21.6.1 Guidelines for Python Developers --------------------------------------- The following guidelines cover aspects of developing MySQL applications that might not be immediately obvious to developers coming from a Python background: * For security, do not hardcode the values needed to connect and log into the database in your main script. Python has the convention of a `config.py' module, where you can keep such values separate from the rest of your code. * Python scripts often build up and tear down large data structures in memory, up to the limits of available RAM. Because MySQL often deals with data sets that are many times larger than available memory, techniques that optimize storage space and disk I/O are especially important. For example, in MySQL tables, you typically use numeric IDs rather than string-based dictionary keys, so that the key values are compact and have a predictable length. This is especially important for columns that make up the primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key) for an `InnoDB' table, because those column values are duplicated within each secondary index (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_secondary_index). * Any application that accepts input must expect to handle bad data. The bad data might be accidental, such as out-of-range values or misformatted strings. The application can use server-side checks such as unique constraints (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_unique_constraint) and NOT NULL constraints (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_not_null_constraint), to keep the bad data from ever reaching the database. On the client side, use techniques such as exception handlers to report any problems and take corrective action. The bad data might also be deliberate, representing an `SQL injection' attack. For example, input values might contain quotation marks, semicolons, `%' and `_' wildcard characters and other characters significant in SQL statements. Validate input values to make sure they have only the expected characters. Escape any special characters that could change the intended behavior when substituted into a SQL statement. Never concatenate a user input value into a SQL statement without doing validation and escaping first. Even when accepting input generated by some other program, expect that the other program could also have been compromised and be sending you incorrect or malicious data. * Because the result sets from SQL queries can be very large, use the appropriate method to retrieve items from the result set as you loop through them. *Note fetchone(): connector-python-api-mysqlcursor-fetchone. retrieves a single item, when you know the result set contains a single row. *Note fetchall(): connector-python-api-mysqlcursor-fetchall. retrieves all the items, when you know the result set contains a limited number of rows that can fit comfortably into memory. *Note fetchmany(): connector-python-api-mysqlcursor-fetchmany. is the general-purpose method when you cannot predict the size of the result set: you keep calling it and looping through the returned items, until there are no more results to process. * Since Python already has convenient modules such as `pickle' and `cPickle' to read and write data structures on disk, data that you choose to store in MySQL instead is likely to have special characteristics: * *Too large to all fit in memory at one time.* You use *Note `SELECT': select. statements to query only the precise items you need, and *Note aggregate functions: group-by-functions. to perform calculations across multiple items. You configure the `innodb_buffer_pool_size' option within the MySQL server to dedicate a certain amount of RAM for caching query results. * *Too complex to be represented by a single data structure.* You divide the data between different SQL tables. You can recombine data from multiple tables by using a join (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_join) query. You make sure that related data is kept in sync between different tables by setting up foreign key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_foreign_key) relationships. * *Updated frequently, perhaps by multiple users simultaneously.* The updates might only affect a small portion of the data, making it wasteful to write the whole structure each time. You use the SQL *Note `INSERT': insert, *Note `UPDATE': update, and *Note `DELETE': delete. statements to update different items concurrently, writing only the changed values to disk. You use *Note `InnoDB': innodb-storage-engine. tables and transactions (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_transaction) to keep write operations from conflicting with each other, and to return consistent query results even as the underlying data is being updated. * Using MySQL best practices for performance can help your application to scale without requiring major rewrites and architectural changes. See *Note optimization:: for best practices for MySQL performance. It offers guidelines and tips for SQL tuning, database design, and server configuration. * You can avoid reinventing the wheel by learning the MySQL SQL statements for common operations: operators to use in queries, techniques for bulk loading data, and so on. Some statements and clauses are extensions to the basic ones defined by the SQL standard. See *Note sql-syntax-data-manipulation::, *Note sql-syntax-data-definition::, and *Note select:: for the main classes of statements. * Issuing SQL statements from Python typically involves declaring very long, possibly multi-line string literals. Because string literals within the SQL statements could be enclosed by single quotation, double quotation marks, or contain either of those characters, for simplicity you can use Python's triple-quoting mechanism to enclose the entire statement. For example: '''It doesn't matter if this string contains 'single' or "double" quotes, as long as there aren't 3 in a row.''' You can use either of the `'' or `"' characters for triple-quoting multi-line string literals. * Many of the secrets to a fast, scalable MySQL application involve using the right syntax at the very start of your setup procedure, in the *Note `CREATE TABLE': create-table. statements. For example, Oracle recommends the `ENGINE=INNODB' clause for most tables, and makes `InnoDB' the default storage engine in MySQL 5.5 and up. Using `InnoDB' tables enables transactional behavior that helps scalability of read-write workloads and offers automatic crash recovery (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_crash_recovery). Another recommendation is to declare a numeric primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key) for each table, which offers the fastest way to look up values and can act as a pointer to associated values in other tables (a foreign key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_foreign_key)). Also within the *Note `CREATE TABLE': create-table. statement, using the most compact column data types that meet your application requirements helps performance and scalability because that enables the database server to move less data back and forth between memory and disk.  File: manual.info, Node: connector-python-versions, Next: connector-python-installation, Prev: connector-python-coding, Up: connector-python 21.6.2 Connector/Python Versions -------------------------------- The MySQL Connector/Python 1.1 is the current development series. The MySQL Connector/Python 1.0 series went through a series of beta releases, leading to the first generally available (GA) version of 1.0.7. Any development releases prior to the GA version (1.0.7) are no longer supported. The following table summarizes the available Connector/Python versions: *Connector/Python Version Reference* For each Connector/Python version, this table lists the corresponding MySQL Server versions that it works with, the corresponding Python versions that it works with, and whether it is prerelease, recommended (supported), or obsolete. MySQL server and Python versions within parentheses are known to work with Connector/Python, but are not officially supported. Bugs might not get fixed for those versions. Connector/PythonMySQL Server Python Support Version Versions Versions Status for Connector 1.1 5.7, 5.6, 5.5 3.1 and Recommended (5.1, 5.0, later, 2.7, version 4.1) 2.6 1.0 5.7, 5.6, 5.5 3.1 and Recommended (5.1, 5.0, later, 2.7, version 4.1) 2.6 (2.5, 2.4) *Note*: MySQL server and Python versions within parentheses are known to work with Connector/Python, but are not officially supported. Bugs might not get fixed for those versions.  File: manual.info, Node: connector-python-installation, Next: connector-python-examples, Prev: connector-python-versions, Up: connector-python 21.6.3 Connector/Python Installation ------------------------------------ * Menu: * connector-python-installation-binary:: Installing Connector/Python from a Binary Distribution * connector-python-installation-source-unix:: Installing Connector/Python Source Distribution on Linux, Unix, or Mac OS X * connector-python-installation-source-windows:: Installing Connector/Python Source Distribution on Microsoft Windows * connector-python-verification:: Verifying Your Connector/Python Installation Connector/Python runs on any platform where Python is installed. Python comes preinstalled on almost any Linux distribution or Unix-like system such as Mac OS X and FreeBSD. On Microsoft Windows systems, you can install Python using the installer found on the Python Download website (http://python.org/download/). Connector/Python is a pure Python implementation of the MySQL Client/Server protocol, meaning it does not require any other MySQL client libraries or other components. It also has no third-party dependencies. If you need SSL support, verify that your Python installation has been compiled using the OpenSSL (http://www.openssl.org/) libraries. Installation of Connector/Python is similar on every platform and follows the standard Python Distribution Utilities (http://docs.python.org/install/index.html#install-index) or Distutils (http://docs.python.org/distutils/). Distributions maybe be available in native format for some platforms, such as RPM packages for Linux. When available, the installation of these is covered in this manual. Python terminology regarding distributions: * *Source Distribution* is a distribution that contains only source files and is generally platform independent. * *Built Distribution* can be regarded as a binary package. It contains both sources and platform-independent bytecode.  File: manual.info, Node: connector-python-installation-binary, Next: connector-python-installation-source-unix, Prev: connector-python-installation, Up: connector-python-installation 21.6.3.1 Installing Connector/Python from a Binary Distribution ............................................................... Installers in native package formats are available for Unix and Unix-like systems, and for Windows. You may need `root' or administrator privileges to perform the installation operation. * Installing Connector/Python on Microsoft Windows * *Note*: Connector/Python requires `python.exe' to be in the system's `PATH'. While installing the Python distribution on your system, either enable `Add python.exe to Path' or manually add it yourself. The Connector/Python MSI will fail to install if it cannot locate `python.exe'. Download and install Python for Windows from `http://python.org/download/'. Windows users can use the Windows MSI Installer (`.msi' file). To use the MSI Installer, launch it and follow the prompts in the screens it presents to install Connector/Python in the location of your choosing. This MSI is downloadable at `http://dev.mysql.com/downloads/connector/python/'. Choose the Connector/Python version appropriate for the Python version that is installed on your system. Subsequent executions of the Connector/Python MSI permit you to either repair or remove the existing Connector/Python installation. * Installing Connector/Python on Linux Using RPM Packages * A Linux RPM package is provided as a file with an `.rpm' suffix, denoted here as `PACKAGE.rpm'. To install a given RPM package, use this command: shell> rpm -i PACKAGE.rpm RPM provides a feature to verify the integrity and authenticity of packages before installing them. To learn more about this feature, see *Note verifying-package-integrity::. * Installing Connector/Python on Linux Using Debian Packages * Oracle provides Debian packages for installation on Debian or Debian-like Linux systems. A Debian package is provided as a file with an `.deb' suffix, denoted here as `PACKAGE.deb'. To install a given Debian package, use this command: shell> dpkg -i PACKAGE.deb  File: manual.info, Node: connector-python-installation-source-unix, Next: connector-python-installation-source-windows, Prev: connector-python-installation-binary, Up: connector-python-installation 21.6.3.2 Installing Connector/Python Source Distribution on Linux, Unix, or Mac OS X .................................................................................... On Unix-like systems such as Linux distributions, Solaris, Mac OS X, and FreeBSD, you can download Connector/Python as a `tar' archive from `http://dev.mysql.com/downloads/connector/python/'. To install Connector/Python from the `.tar.gz' file, download the latest version and follow these steps: shell> gunzip mysql-connector-python-1.0.10.tar.gz shell> tar xf mysql-connector-python-1.0.10.tar shell> cd mysql-connector-python-1.0.10 shell> sudo python setup.py install On Unix-like systems, Connector/Python is installed in the default location `/PREFIX/lib/pythonX.Y/site-packages/', where PREFIX is the location where Python was installed and X.Y is the Python version. See How installation works (http://docs.python.org/install/index.html#how-installation-works) in the Python manual. If you are not sure where Connector/Python was installed, do the following to determine the location: shell> python >>> from distutils.sysconfig import get_python_lib >>> print get_python_lib() # Python v2.x /Library/Python/2.7/site-packages >>> print(get_python_lib()) # Python v3.x /Library/Frameworks/Python.framework/Versions/3.1/lib/python3.1/site-packages *Note*: The preceding example shows the default installation location on Mac OS X 10.7.  File: manual.info, Node: connector-python-installation-source-windows, Next: connector-python-verification, Prev: connector-python-installation-source-unix, Up: connector-python-installation 21.6.3.3 Installing Connector/Python Source Distribution on Microsoft Windows ............................................................................. On Microsoft Windows systems, you can download Connector/Python as a Zip archive from `http://dev.mysql.com/downloads/connector/python/'. Make sure that the Python executable is available in the Windows `%PATH%' setting. For more information about installation and configuration of Python on Windows, see the section Using Python on Windows (http://docs.python.org/using/windows.html) in the Python documentation. To install Connector/Python from the `.zip' file, download the latest version and follow these steps: 1. To use a Zip archive, unpack it in the intended installation directory (for example, `C:\mysql-connector\') using `WinZip' or another tool that can read `.zip' files. 2. Start a console window (or a DOS window) and change location to the folder where you unpacked the Connector/Python Zip archive: shell> cd C:\mysql-connector\ 3. Inside the Connector/Python folder, perform the installation using this command: shell> python setup.py install On Windows, Connector/Python is installed in the default location `C:\PythonX.Y\Lib\site-packages\' where X.Y is the Python version you used to install the connector. If you are not sure where Connector/Python was installed, do the following to determine the location: shell> python >>> from distutils.sysconfig import get_python_lib >>> print get_python_lib() # Python v2.x >>> print(get_python_lib()) # Python v3.x  File: manual.info, Node: connector-python-verification, Prev: connector-python-installation-source-windows, Up: connector-python-installation 21.6.3.4 Verifying Your Connector/Python Installation ..................................................... To test that your Connector/Python installation is working and able to connect to MySQL Server, you can run a very simple program where you supply the login credentials and host information required for the connection. See *Note connector-python-example-connecting:: for an example.  File: manual.info, Node: connector-python-examples, Next: connector-python-tutorials, Prev: connector-python-installation, Up: connector-python 21.6.4 Connector/Python Coding Examples --------------------------------------- * Menu: * connector-python-example-connecting:: Connecting to MySQL Using Connector/Python * connector-python-example-ddl:: Creating Tables Using Connector/Python * connector-python-example-cursor-transaction:: Inserting Data Using Connector/Python * connector-python-example-cursor-select:: Querying Data Using Connector/Python These coding examples illustrate how to develop Python applications and scripts which connect to MySQL Server using MySQL Connector/Python.  File: manual.info, Node: connector-python-example-connecting, Next: connector-python-example-ddl, Prev: connector-python-examples, Up: connector-python-examples 21.6.4.1 Connecting to MySQL Using Connector/Python ................................................... The `connect()' constructor creates a connection to the MySQL server and returns a `MySQLConnection' object. The following example shows how to connect to the MySQL server: import mysql.connector cnx = mysql.connector.connect(user='scott', password='tiger', host='127.0.0.1', database='employees') cnx.close() See *Note connector-python-connectargs:: for all possible connection arguments. It is also possible to create connection objects using the *Note connection.MySQLConnection(): connector-python-api-mysqlconnection. class. Both methods, using the `connect()' constructor, or the class directly, are valid and functionally equal, but using `connector()' is preferred and is used in most examples in this manual. To handle connection errors, use the `try' statement and catch all errors using the *Note errors.Error: connector-python-api-errors-error. exception: import mysql.connector from mysql.connector import errorcode try: cnx = mysql.connector.connect(user='scott', database='testt') except mysql.connector.Error as err: if err.errno == errorcode.ER_ACCESS_DENIED_ERROR: print("Something is wrong with your user name or password") elif err.errno == errorcode.ER_BAD_DB_ERROR: print("Database does not exists") else: print(err) else: cnx.close() If you have lots of connection arguments, it's best to keep them in a dictionary and use the `**' operator: import mysql.connector config = { 'user': 'scott', 'password': 'tiger', 'host': '127.0.0.1', 'database': 'employees', 'raise_on_warnings': True, } cnx = mysql.connector.connect(**config) cnx.close()  File: manual.info, Node: connector-python-example-ddl, Next: connector-python-example-cursor-transaction, Prev: connector-python-example-connecting, Up: connector-python-examples 21.6.4.2 Creating Tables Using Connector/Python ............................................... All DDL (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_ddl) (Data Definition Language) statements are executed using a handle structure known as a cursor. The following examples show how to create the tables of the Employee Sample Database (http://dev.mysql.com/doc/employee/en/index.html). You need them for the other examples. In a MySQL server, tables are very long-lived objects, and are often accessed by multiple applications written in different languages. You might typically work with tables that are already set up, rather than creating them within your own application. Avoid setting up and dropping tables over and over again, as that is an expensive operation. The exception is temporary tables (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_temporary_table), which can be created and dropped quickly within an application. from __future__ import print_function import mysql.connector from mysql.connector import errorcode DB_NAME = 'employees' TABLES = {} TABLES['employees'] = ( "CREATE TABLE `employees` (" " `emp_no` int(11) NOT NULL AUTO_INCREMENT," " `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`)" ") ENGINE=InnoDB") TABLES['departments'] = ( "CREATE TABLE `departments` (" " `dept_no` char(4) NOT NULL," " `dept_name` varchar(40) NOT NULL," " PRIMARY KEY (`dept_no`), UNIQUE KEY `dept_name` (`dept_name`)" ") ENGINE=InnoDB") TABLES['salaries'] = ( "CREATE TABLE `salaries` (" " `emp_no` int(11) NOT NULL," " `salary` int(11) NOT NULL," " `from_date` date NOT NULL," " `to_date` date NOT NULL," " PRIMARY KEY (`emp_no`,`from_date`), KEY `emp_no` (`emp_no`)," " CONSTRAINT `salaries_ibfk_1` FOREIGN KEY (`emp_no`) " " REFERENCES `employees` (`emp_no`) ON DELETE CASCADE" ") ENGINE=InnoDB") TABLES['dept_emp'] = ( "CREATE TABLE `dept_emp` (" " `emp_no` int(11) NOT NULL," " `dept_no` char(4) NOT NULL," " `from_date` date NOT NULL," " `to_date` date NOT NULL," " PRIMARY KEY (`emp_no`,`dept_no`), KEY `emp_no` (`emp_no`)," " KEY `dept_no` (`dept_no`)," " CONSTRAINT `dept_emp_ibfk_1` FOREIGN KEY (`emp_no`) " " REFERENCES `employees` (`emp_no`) ON DELETE CASCADE," " CONSTRAINT `dept_emp_ibfk_2` FOREIGN KEY (`dept_no`) " " REFERENCES `departments` (`dept_no`) ON DELETE CASCADE" ") ENGINE=InnoDB") TABLES['dept_manager'] = ( " CREATE TABLE `dept_manager` (" " `dept_no` char(4) NOT NULL," " `emp_no` int(11) NOT NULL," " `from_date` date NOT NULL," " `to_date` date NOT NULL," " PRIMARY KEY (`emp_no`,`dept_no`)," " KEY `emp_no` (`emp_no`)," " KEY `dept_no` (`dept_no`)," " CONSTRAINT `dept_manager_ibfk_1` FOREIGN KEY (`emp_no`) " " REFERENCES `employees` (`emp_no`) ON DELETE CASCADE," " CONSTRAINT `dept_manager_ibfk_2` FOREIGN KEY (`dept_no`) " " REFERENCES `departments` (`dept_no`) ON DELETE CASCADE" ") ENGINE=InnoDB") TABLES['titles'] = ( "CREATE TABLE `titles` (" " `emp_no` int(11) NOT NULL," " `title` varchar(50) NOT NULL," " `from_date` date NOT NULL," " `to_date` date DEFAULT NULL," " PRIMARY KEY (`emp_no`,`title`,`from_date`), KEY `emp_no` (`emp_no`)," " CONSTRAINT `titles_ibfk_1` FOREIGN KEY (`emp_no`)" " REFERENCES `employees` (`emp_no`) ON DELETE CASCADE" ") ENGINE=InnoDB") The preceding code shows how we are storing the `CREATE' statements in a Python dictionary called `TABLES'. We also define the database in a global variable called `DB_NAME', which enables you to easily use a different schema. cnx = mysql.connector.connect(user='scott') cursor = cnx.cursor() A single MySQL server can manage multiple databases (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_database). Typically, you specify the database to switch to when connecting to the MySQL server. This example does not connect to the database upon connection, so that it can make sure the database exists, and create it if not: def create_database(cursor): try: cursor.execute( "CREATE DATABASE {} DEFAULT CHARACTER SET 'utf8'".format(DB_NAME)) except mysql.connector.Error as err: print("Failed creating database: {}".format(err)) exit(1) try: cnx.database = DB_NAME except mysql.connector.Error as err: if err.errno == errorcode.ER_BAD_DB_ERROR: create_database(cursor) cnx.database = DB_NAME else: print(err) exit(1) We first try to change to a particular database using the `database' property of the connection object `cnx'. If there is an error, we examine the error number to check if the database does not exist. If so, we call the `create_database' function to create it for us. On any other error, the application exits and displays the error message. After we successfully create or change to the target database, we create the tables by iterating over the items of the `TABLES' dictionary: for name, ddl in TABLES.iteritems(): try: print("Creating table {}: ".format(name), end='') cursor.execute(ddl) except mysql.connector.Error as err: if err.errno == errorcode.ER_TABLE_EXISTS_ERROR: print("already exists.") else: print(err.errmsg) else: print("OK") cursor.close() cnx.close() To handle the error when the table already exists, we notify the user that it was already there. Other errors are printed, but we continue creating tables. (The example shows how to handle the `table already exists' condition for illustration purposes. In a real application, we would typically avoid the error condition entirely by using the `IF NOT EXISTS' clause of the *Note `CREATE TABLE': create-table. statement.) The output would be something like this: Creating table employees: already exists. Creating table salaries: already exists. Creating table titles: OK Creating table departments: already exists. Creating table dept_manager: already exists. Creating table dept_emp: already exists. To populate the employees tables, use the dump files of the Employee Sample Database (http://dev.mysql.com/doc/employee/en/index.html). Note that you only need the data dump files that you will find in an archive named like `employees_db-dump-files-1.0.5.tar.bz2'. After downloading the dump files, execute the following commands, adding connection options to the *Note `mysql': mysql. commands if necessary: shell> tar xzf employees_db-dump-files-1.0.5.tar.bz2 shell> cd employees_db shell> mysql employees < load_employees.dump shell> mysql employees < load_titles.dump shell> mysql employees < load_departments.dump shell> mysql employees < load_salaries.dump shell> mysql employees < load_dept_emp.dump shell> mysql employees < load_dept_manager.dump  File: manual.info, Node: connector-python-example-cursor-transaction, Next: connector-python-example-cursor-select, Prev: connector-python-example-ddl, Up: connector-python-examples 21.6.4.3 Inserting Data Using Connector/Python .............................................. Inserting or updating data is also done using the handler structure known as a cursor. When you use a transactional storage engine such as `InnoDB' (the default in MySQL 5.5 and later), you must commit (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_commit) the data after a sequence of *Note `INSERT': insert, *Note `DELETE': delete, and *Note `UPDATE': update. statements. This example shows how to insert new data. The second *Note `INSERT': insert. depends on the value of the newly created primary key (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key) of the first. The example also demonstrates how to use extended formats. The task is to add a new employee starting to work tomorrow with a salary set to 50000. *Note*: The following example uses tables created in the example *Note connector-python-example-ddl::. The `AUTO_INCREMENT' column option for the primary key of the `employees' table is important to ensure reliable, easily searchable data. from __future__ import print_function from datetime import date, datetime, timedelta import mysql.connector cnx = mysql.connector.connect(user='scott', database='employees') cursor = cnx.cursor() tomorrow = datetime.now().date() + timedelta(days=1) add_employee = ("INSERT INTO employees " "(first_name, last_name, hire_date, gender, birth_date) " "VALUES (%s, %s, %s, %s, %s)") add_salary = ("INSERT INTO salaries " "(emp_no, salary, from_date, to_date) " "VALUES (%(emp_no)s, %(salary)s, %(from_date)s, %(to_date)s)") data_employee = ('Geert', 'Vanderkelen', tomorrow, 'M', date(1977, 6, 14)) # Insert new employee cursor.execute(add_employee, data_employee) emp_no = cursor.lastrowid # Insert salary information data_salary = { 'emp_no': emp_no, 'salary': 50000, 'from_date': tomorrow, 'to_date': date(9999, 1, 1), } cursor.execute(add_salary, data_salary) # Make sure data is committed to the database cnx.commit() cursor.close() cnx.close() We first open a connection to the MySQL server and store the *Note connection object: connector-python-api-mysqlconnection. in the variable `cnx'. We then create a new cursor, by default a *Note MySQLCursor: connector-python-api-mysqlcursor. object, using the connection's *Note `cursor()': connector-python-api-mysqlconnection-cursor. method. We could calculate tomorrow by calling a database function, but for clarity we do it in Python using the `datetime' module. Both `INSERT' statements are stored in the variables called `add_employee' and `add_salary'. Note that the second `INSERT' statement uses extended Python format codes. The information of the new employee is stored in the tuple `data_employee'. The query to insert the new employee is executed and we retrieve the newly inserted value for the `emp_no' column (an `AUTO_INCREMENT' column) using the `lastrowid' property of the cursor object. Next, we insert the new salary for the new employee, using the `emp_no' variable in the dictionary holding the data. This dictionary is passed to the `execute()' method of the cursor object if an error occurred. Since by default Connector/Python turns autocommit (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_autocommit) off, and MySQL 5.5 and later uses transactional `InnoDB' tables by default, it is necessary to commit your changes using the connection's `commit()' method. You could also roll back (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_rollback) using the `rollback()' method.  File: manual.info, Node: connector-python-example-cursor-select, Prev: connector-python-example-cursor-transaction, Up: connector-python-examples 21.6.4.4 Querying Data Using Connector/Python ............................................. The following example shows how to query (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_query) data using a cursor created using the connection's *Note `cursor()': connector-python-api-mysqlconnection-cursor. method. The data returned is formatted and printed on the console. The task is to select all employees hired in the year 1999 and print their names and hire dates to the console. import datetime import mysql.connector cnx = mysql.connector.connect(user='scott', database='employees') cursor = cnx.cursor() query = ("SELECT first_name, last_name, hire_date FROM employees " "WHERE hire_date BETWEEN %s AND %s") hire_start = datetime.date(1999, 1, 1) hire_end = datetime.date(1999, 12, 31) cursor.execute(query, (hire_start, hire_end)) for (first_name, last_name, hire_date) in cursor: print("{}, {} was hired on {:%d %b %Y}".format( last_name, first_name, hire_date)) cursor.close() cnx.close() We first open a connection to the MySQL server and store the *Note connection object: connector-python-api-mysqlconnection. in the variable `cnx'. We then create a new cursor, by default a *Note MySQLCursor: connector-python-api-mysqlcursor. object, using the connection's *Note `cursor()': connector-python-api-mysqlconnection-cursor. method. In the preceding example, we store the `SELECT' statement in the variable `query'. Note that we are using unquoted `%s'-markers where dates should have been. Connector/Python converts `hire_start' and `hire_end' from Python types to a data type that MySQL understands and adds the required quotes. In this case, it replaces the first `%s' with `'1999-01-01'', and the second with `'1999-12-31''. We then execute the operation stored in the `query' variable using the *Note `execute()': connector-python-api-mysqlcursor-execute. method. The data used to replace the `%s'-markers in the query is passed as a tuple: `(hire_start, hire_end)'. After executing the query, the MySQL server is ready to send the data. The result set could be zero rows, one row, or 100 million rows. Depending on the expected volume, you can use different techniques to process this result set. In this example, we use the `cursor' object as an iterator. The first column in the row is stored in the variable `first_name', the second in `last_name', and the third in `hire_date'. We print the result, formatting the output using Python's built-in `format()' function. Note that `hire_date' was converted automatically by Connector/Python to a Python `datetime.date' object. This means that we can easily format the date in a more human-readable form. The output should be something like this: .. Wilharm, LiMin was hired on 16 Dec 1999 Wielonsky, Lalit was hired on 16 Dec 1999 Kamble, Dannz was hired on 18 Dec 1999 DuBourdieux, Zhongwei was hired on 19 Dec 1999 Fujisawa, Rosita was hired on 20 Dec 1999 ..  File: manual.info, Node: connector-python-tutorials, Next: connector-python-connectargs, Prev: connector-python-examples, Up: connector-python 21.6.5 Connector/Python Tutorials --------------------------------- * Menu: * connector-python-tutorial-cursorbuffered:: Tutorial: Raise Employee's Salary Using a Buffering Cursor These tutorials illustrate how to develop Python applications and scripts that connect to a MySQL database server using MySQL Connector/Python.  File: manual.info, Node: connector-python-tutorial-cursorbuffered, Prev: connector-python-tutorials, Up: connector-python-tutorials 21.6.5.1 Tutorial: Raise Employee's Salary Using a Buffering Cursor ................................................................... The following example script gives a long-overdue 15% raise effective tomorrow to all employees who joined in the year 2000 and are still with the company. We are using buffered cursors to iterate through the selected employees. This way we do not have to fetch the rows in a new variables, but can instead use the cursor as an iterator. Note that the script is an example; there are other ways of doing this simple task. from __future__ import print_function from decimal import Decimal from datetime import datetime, date, timedelta import mysql.connector # Connect with the MySQL Server cnx = mysql.connector.connect(user='scott', database='employees') # Get two buffered cursors curA = cnx.cursor(buffered=True) curB = cnx.cursor(buffered=True) # Query to get employees who joined in a period defined by two dates query = ( "SELECT s.emp_no, salary, from_date, to_date FROM employees AS e " "LEFT JOIN salaries AS s USING (emp_no) " "WHERE to_date = DATE('9999-01-01')" "AND e.hire_date BETWEEN DATE(%s) AND DATE(%s)") # UPDATE and INSERT statements for the old and new salary update_old_salary = ( "UPDATE salaries SET to_date = %s " "WHERE emp_no = %s AND from_date = %s") insert_new_salary = ( "INSERT INTO salaries (emp_no, from_date, to_date, salary) " "VALUES (%s, %s, %s, %s)") # Select the employees getting a raise curA.execute(query, (date(2000, 1, 1), date(2000, 12, 31))) # Iterate through the result of curA for (emp_no, salary, from_date, to_date) in curA: # Update the old and insert the new salary new_salary = int(round(salary * Decimal('1.15'))) curB.execute(update_old_salary, (tomorrow, emp_no, from_date)) curB.execute(insert_new_salary, (emp_no, tomorrow, date(9999, 1, 1,), new_salary)) # Commit the changes cnx.commit() cnx.close()  File: manual.info, Node: connector-python-connectargs, Next: connector-python-other, Prev: connector-python-tutorials, Up: connector-python 21.6.6 Connector/Python Connection Arguments -------------------------------------------- A connection with the MySQL server can be established using either the `mysql.connector.connect()' function or the `mysql.connector.MySQLConnection()' class: cnx = mysql.connector.connect(user='joe', database='test') cnx = MySQLConnection(user='joe', database='test') The following table describes describes the arguments that can be used to initiate a connection. An asterisk (*) following an argument indicates a synonymous argument name, available only for compatibility with other Python MySQL drivers. Oracle recommends not to use these alternative names. *Connection Arguments for Connector/Python* Argument Name Default Description `user' (`username'*) The user name used to authenticate with the MySQL server. `password' (`passwd'*) The password to authenticate the user with the MySQL server. `database' (`db'*) The database name to use when connecting with the MySQL server. `host' 127.0.0.1 The host name or IP address of the MySQL server. `port' 3306 The TCP/IP port of the MySQL server. Must be an integer. `unix_socket' The location of the Unix socket file. `use_unicode' True Whether to use Unicode. `charset' utf8 Which MySQL character set to use. `collation' utf8_general_ciWhich MySQL collation to use. `autocommit' False Whether to autocommit (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_autocommit) transactions. `time_zone' Set the `time_zone' session variable at connection time. `sql_mode' Set the `sql_mode' session variable at connection time. `get_warnings' False Whether to fetch warnings. `raise_on_warnings' False Whether to raise an exception on warnings. `connection_timeout' Timeout for the TCP and Unix socket (`connect_timeout'*) connections. `client_flags' MySQL client flags. `buffered' False Whether cursor objects fetch the results immediately after executing queries. `raw' False Whether MySQL results are returned as is, rather than converted to Python types. `ssl_ca' File containing the SSL certificate authority. `ssl_cert' File containing the SSL certificate file. `ssl_key' File containing the SSL key. `ssl_verify_cert' False When set to `True', checks the server certificate against the certificate file specified by the `ssl_ca' option. Any mismatch causes a `ValueError' exception. `force_ipv6' False When set to `True', uses IPv6 when an address resolves to both IPv4 and IPv6. By default, IPv4 is used in such cases. `dsn' Not supported (raises `NotSupportedError' when used). `pool_name' Connection pool name. Added in 1.1.1. `pool_size' 5 Connection pool size. Added in 1.1.1. * MySQL Authentication * Authentication with MySQL uses `username' and `password'. *Note*: MySQL Connector/Python does not support the old, less-secure password protocols of MySQL versions prior to 4.1. When the `database' parameter is given, the current database is set to the given value. To change the current database later, execute a `USE' SQL statement or set the `database' property of the `MySQLConnection' instance. By default, Connector/Python tries to connect to a MySQL server running on the local host using TCP/IP. The `host' argument defaults to IP address 127.0.0.1 and `port' to 3306. Unix sockets are supported by setting `unix_socket'. Named pipes on the Windows platform are not supported. * Character Encoding * By default, strings coming from MySQL are returned as Python Unicode literals. To change this behavior, set `use_unicode' to `False'. You can change the character setting for the client connection through the `charset' argument. To change the character set after connecting to MySQL, set the `charset' property of the `MySQLConnection' instance. This technique is preferred over using the `SET NAMES' SQL statement directly. Similar to the `charset' property, you can set the `collation' for the current MySQL session. * Transactions * The `autocommit' value defaults to `False', so transactions are not automatically committed. Call the `commit()' method of the `MySQLConnection' instance within your application after doing a set of related insert, update, and delete operations. For data consistency and high throughput for write operations, it is best to leave the `autocommit' configuration option turned off when using `InnoDB' or other transactional tables. * Time Zones * The time zone can be set per connection using the `time_zone' argument. This is useful, for example, if the MySQL server is set to UTC and `TIMESTAMP' values should be returned by MySQL converted to the `PST' time zone. * SQL Modes * MySQL supports so-called SQL Modes. which change the behavior of the server globally or per connection. For example, to have warnings raised as errors, set `sql_mode' to `TRADITIONAL'. For more information, see *Note server-sql-mode::. * Troubleshooting and Error Handling * Warnings generated by queries are fetched automatically when `get_warnings' is set to `True'. You can also immediately raise an exception by setting `raise_on_warnings' to `True'. Consider using the MySQL *Note sql_mode: server-sql-mode. setting for turning warnings into errors. To set a timeout value for connections, use `connection_timeout'. * Enabling and Disabling Features Using Client Flags * MySQL uses *Note client flags: mysql-real-connect. to enable or disable features. Using the `client_flags' argument, you have control of what is set. To find out what flags are available, use the following: from mysql.connector.constants import ClientFlag print '\n'.join(ClientFlag.get_full_info()) If `client_flags' is not specified (that is, it is zero), defaults are used for MySQL v4.1 and later. If you specify an integer greater than `0', make sure all flags are set properly. A better way to set and unset flags individually is to use a list. For example, to set `FOUND_ROWS', but disable the default `LONG_FLAG': flags = [ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG] mysql.connector.connect(client_flags=flags) * Buffering for Result Sets * By default, MySQL Connector/Python does not buffer or pre-fetch results. This means that after a query is executed, your program is responsible for fetching the data. This avoids excessive memory use when queries return large result sets. If you know that the result set is small enough to handle all at once, you can fetch the results immediately by setting `buffered' to `True'. It is also possible to set this per cursor (see *Note connector-python-api-mysqlconnection-cursor::). * Type Conversions * By default, MySQL types in result sets are converted automatically to Python types. For example, a `DATETIME' column value becomes a datetime.datetime (http://docs.python.org/library/datetime.html#datetime.datetime) object. To disable conversion, set the `raw' parameter to `True'. You might do this to get better performance or perform different types of conversion yourself. * Connecting through SSL * Using SSL connections is possible when your Python installation supports SSL (http://docs.python.org/library/ssl.html), that is, when it is compiled against the OpenSSL libraries. When you provide the `ssl_ca', `ssl_key' and `ssl_cert' arguments, the connection switches to SSL, and the `client_flags' option includes the `ClientFlag.SSL' value automatically. You can use this in combination with the `compressed' argument set to `True'. # Note (Example is valid for Python v2 and v3) from __future__ import print_function import sys #sys.path.insert(0, 'python{0}/'.format(sys.version_info[0])) import mysql.connector from mysql.connector.constants import ClientFlag config = { 'user': 'ssluser', 'password': 'asecret', 'host': '127.0.0.1', 'client_flags': [ClientFlag.SSL], 'ssl_ca': '/opt/mysql/ssl/ca-cert.pem', 'ssl_cert': '/opt/mysql/ssl/client-cert.pem', 'ssl_key': '/opt/mysql/ssl/client-key.pem', } cnx = mysql.connector.connect(**config) cur = cnx.cursor(buffered=True) cur.execute("SHOW STATUS LIKE 'Ssl_cipher'") print(cur.fetchone()) cur.close() cnx.close() * Connection Pooling * With either the `pool_name' or `pool_size' argument present, Connector/Python creates the new pool. If the `pool_name' argument is not given, the `connect()' call automatically generates the name, composed from whichever of the `host', `port', `user', and `database' connection arguments are given, in that order. If the `pool_size' argument is not given, the default size is 5 connections. Connection pooling is supported as of Connector/Python 1.1.1. See *Note connector-python-connection-pooling::. * Compatibitility with Other Connection Interfaces * `passwd', `db' and `connect_timeout' are valid for compatibility with other MySQL interfaces and are respectively the same as `password', `database' and `connection_timeout'. The latter take precedence. Data source name syntax or `dsn' is not used; if specified, it raises a `NotSupportedError' exception.  File: manual.info, Node: connector-python-other, Next: connector-python-reference, Prev: connector-python-connectargs, Up: connector-python 21.6.7 Connector/Python Other Topics ------------------------------------ * Menu: * connector-python-connection-pooling:: Connector/Python Connection Pooling * connector-python-django-backend:: Connector/Python Django Backend This section describes additional Connection/Python features: * Connection pooling: *Note connector-python-connection-pooling:: * Django backend for MySQL: *Note connector-python-django-backend::  File: manual.info, Node: connector-python-connection-pooling, Next: connector-python-django-backend, Prev: connector-python-other, Up: connector-python-other 21.6.7.1 Connector/Python Connection Pooling ............................................ MySQL Connector/Python 1.1.1 and up supports simple connection pooling that has these characteristics: * The `mysql.connector.pooling' module implements pooling. * A pool opens a number of connections and handles thread safety when providing connections to requesters. * The size of a connection pool is configurable at pool creation time. It cannot be resized thereafter. * A connection pool can be named at pool creation time. If no name is given, one is generated using the connection parameters. * The connection pool name can be retrieved from the connection pool or connections obtained from it. * It is possible to have multiple connection pools. This enables applications to support pools of connections to different MySQL servers, for example. * For each connection request, the pool provides the next available connection. No round-robin or other scheduling algorithm is used. * It is possible to reconfigure the connection parameters used by a pool. These apply to connections obtained from the pool thereafter. Reconfiguring individual connections obtained from the pool by calling the connection `config()' method is not supported. Applications that can benefit from connection-pooling capability include: * Middleware that maintains multiple connections to multiple MySQL servers and requires connections to be readily available. * Web sites that can have more `permanent' connections open to the MySQL server. A connection pool can be created implicitly or explicitly. *To create a connection pool implicitly:* Open a connection and specify one or more pool-related arguments (`pool_name', `pool_size'). For example: dbconfig = { "database": "test", "user": "joe" } cnx = mysql.connector.connect(pool_name = "mypool", pool_size = 3, **dbconfig) With either the `pool_name' or `pool_size' argument present, Connector/Python creates the new pool. If the `pool_name' argument is not given, the `connect()' call automatically generates the name, composed from whichever of the `host', `port', `user', and `database' connection arguments are given, in that order. If the `pool_size' argument is not given, the default size is 5 connections. Subsequent calls to `connect()' that name the same connection pool return connections from the existing pool. Any `pool_size' or connection parameter arguments are ignored, so the following `connect()' calls are equivalent to the original `connect()' call shown earlier: cnx = mysql.connector.connect(pool_name = "mypool", pool_size = 3) cnx = mysql.connector.connect(pool_name = "mypool", **dbconfig) cnx = mysql.connector.connect(pool_name = "mypool") Pooled connections obtained by calling `connect()' with a pool-related argument have a class of `PooledMySQLConnection' (see *Note connector-python-api-pooledmysqlconnection::). `PooledMySQLConnection' pooled connection objects are similar to `MySQLConnection' unpooled connection objects, with these differences: * To release a pooled connection obtained from a connection pool, invoke its `close()' method, just as for any unpooled connection. However, for a pooled connection, `close()' does not actually close the connection but returns it to the pool and makes it available for subsequent connection requests. * A pooled connection cannot be reconfigured using its `config()' method. Connection changes must be done through the pool object itself, as described shortly. * A pooled connection has a `pool_name' property that returns the pool name. *To create a connection pool explicitly:* Create a `MySQLConnectionPool' object (see *Note connector-python-api-mysqlconnectionpool::): dbconfig = { "database": "test", "user": "joe" } cnxpool = mysql.connector.pooling.MySQLConnectionPool(pool_name = "mypool", pool_size = 3, **dbconfig) To request a connection from the pool, use its `get_connection()' method: cnx1 = cnxpool.get_connection() cnx2 = cnxpool.get_connection() When you create a connection pool explicitly, it is possible to use the pool object's `set_config()' method to reconfigure the pool connection parameters: dbconfig = { "database": "performance_schema", "user": "admin", "password": "secret" } cnxpool.set_config(**dbconfig) Connections requested from the pool after the configuration change use the new parameters. Connections obtained before the change remain unaffected, but when they are closed (returned to the pool) are reopened with the new parameters before being returned by the pool for subsequent connection requests.  File: manual.info, Node: connector-python-django-backend, Prev: connector-python-connection-pooling, Up: connector-python-other 21.6.7.2 Connector/Python Django Backend ........................................ Connector/Python 1.1.1 and up includes a `mysql.connector.django' module that provides a Django backend for MySQL. This backend supports new features found in MySQL 5.6 such as fractional seconds support for temporal data types. * Django Configuration * Django uses a configuration file named `settings.py' that contains a variable called `DATABASES' (see `https://docs.djangoproject.com/en/1.5/ref/settings/#std:setting-DATABASES'). To configure Django to use Connector/Python as the MySQL backend, the example found in the Django manual can be used as a basis: DATABASES = { 'default': { 'NAME': 'user_data', 'ENGINE': 'mysql.connector.django', 'USER': 'mysql_user', 'PASSWORD': 'priv4te', 'OPTIONS': { 'autocommit': True, }, } } It is possible to add more connection arguments using `OPTIONS'. * Support for MySQL Features * Django can launch the MySQL client application *Note `mysql': mysql. When the Connector/Python backend does this, it arranges for the `sql_mode' system variable to be set to `TRADITIONAL' at startup. Some MySQL features are enabled depending on the server version. For example, support for fractional seconds precision is enabled when connecting to a server from MySQL 5.6.4 or higher. Django's `DateTimeField' is stored in a MySQL column defined as `DATETIME(6)', and `TimeField' is stored as `TIME(6)'. For more information about fractional seconds support, see *Note fractional-seconds::. * Django Unit Testing * Django comes with an extensive set of unit tests. To run these, use the `run_django_tests.py' script located in the Connector/Python distribution `support/django' directory. For example, to run the basic tests using Django 1.5, run the following commands: shell> cd support/django shell> python run_django_tests.py --django 1.5 --tests basic The script can be run using Python 2 or Python 3. It downloads Django, unpacks it and starts the tests. To avoid the download and use an already-fetched version, use the `--offline' option. To see the script requirements, run it with the `--help' option, or examine the script itself. Here is an overview: * Two MySQL servers, configured as a master/slave pair * A database named `django_tests' on each server To alter the settings of the MySQL servers, modify the file `test_mysqlconnector_settings.py', also located in the `support/django' directory.  File: manual.info, Node: connector-python-reference, Prev: connector-python-other, Up: connector-python 21.6.8 Connector/Python API Reference ------------------------------------- * Menu: * connector-python-api-mysql-connector:: Module `mysql.connector' * connector-python-api-mysqlconnection:: Class `connection.MySQLConnection' * connector-python-api-mysqlconnectionpool:: Class `pooling.MySQLConnectionPool' * connector-python-api-pooledmysqlconnection:: Class `pooling.PooledMySQLConnection' * connector-python-api-mysqlcursor:: Class `cursor.MySQLCursor' * connector-python-api-mysqlcursorbuffered:: Class `cursor.MySQLCursorBuffered' * connector-python-api-mysqlcursorprepared:: Class `cursor.MySQLCursorPrepared' * connector-python-api-clientflag:: Class `constants.ClientFlag' * connector-python-api-fieldtype:: Class `constants.FieldType' * connector-python-api-sqlmode:: Class `constants.SQLMode' * connector-python-api-characterset:: Class `constants.CharacterSet' * connector-python-api-refreshoption:: Class `constants.RefreshOption' * connector-python-api-errors:: Errors and Exceptions This section contains the public API reference for Connector/Python. Examples should be considered working for Python 2.7, and Python 3.1 and greater. They might also work for older versions (such as Python 2.4) unless they use features introduced in newer Python versions. For example, exception handling using the `as' keyword was introduced in Python 2.6 and will not work in Python 2.4. The following overview shows the `mysql.connector' package with its modules. Currently, only the most useful modules, classes, and methods for end users are documented. mysql.connector errorcode errors connection constants conversion cursor dbapi locales eng client_error protocol utils  File: manual.info, Node: connector-python-api-mysql-connector, Next: connector-python-api-mysqlconnection, Prev: connector-python-reference, Up: connector-python-reference 21.6.8.1 Module `mysql.connector' ................................. * Menu: * connector-python-api-mysql-connector-connect:: Method `mysql.connector.connect()' * connector-python-api-mysql-connector-apilevel:: Property `mysql.connector.apilevel' * connector-python-api-mysql-connector-paramstyle:: Property `mysql.connector.paramstyle' * connector-python-api-mysql-connector-threadsafety:: Property `mysql.connector.threadsafety' * connector-python-api-mysql-connector-version:: Property `mysql.connector.__version__' * connector-python-api-mysql-connector-version-info:: Property `mysql.connector.__version_info__' The `mysql.connector' module provides top-level methods and properties.  File: manual.info, Node: connector-python-api-mysql-connector-connect, Next: connector-python-api-mysql-connector-apilevel, Prev: connector-python-api-mysql-connector, Up: connector-python-api-mysql-connector 21.6.8.2 Method `mysql.connector.connect()' ........................................... This method sets up a connection, establishing a session with the MySQL server. If no arguments are given, it uses the already configured or default values. For a complete list of possible arguments, see *Note connector-python-connectargs::. A connection with the MySQL server can be established using either the `mysql.connector.connect()' method or the `mysql.connector.MySQLConnection()' class: cnx = mysql.connector.connect(user='joe', database='test') cnx = MySQLConnection(user='joe', database='test') For descriptions of connection methods and properties, see *Note connector-python-api-mysqlconnection::.  File: manual.info, Node: connector-python-api-mysql-connector-apilevel, Next: connector-python-api-mysql-connector-paramstyle, Prev: connector-python-api-mysql-connector-connect, Up: connector-python-api-mysql-connector 21.6.8.3 Property `mysql.connector.apilevel' ............................................ This property is a string that indicates the supported DB API level. >>> mysql.connector.apilevel '2.0'  File: manual.info, Node: connector-python-api-mysql-connector-paramstyle, Next: connector-python-api-mysql-connector-threadsafety, Prev: connector-python-api-mysql-connector-apilevel, Up: connector-python-api-mysql-connector 21.6.8.4 Property `mysql.connector.paramstyle' .............................................. This property is a string that indicates the Connector/Python default parameter style. >>> mysql.connector.paramstyle 'pyformat'  File: manual.info, Node: connector-python-api-mysql-connector-threadsafety, Next: connector-python-api-mysql-connector-version, Prev: connector-python-api-mysql-connector-paramstyle, Up: connector-python-api-mysql-connector 21.6.8.5 Property `mysql.connector.threadsafety' ................................................ This property is an integer that indicates the supported level of thread safety provided by Connector/Python. >>> mysql.connector.threadsafety 1  File: manual.info, Node: connector-python-api-mysql-connector-version, Next: connector-python-api-mysql-connector-version-info, Prev: connector-python-api-mysql-connector-threadsafety, Up: connector-python-api-mysql-connector 21.6.8.6 Property `mysql.connector.__version__' ............................................... This property indicates the Connector/Python version as a string. It is available as of Connector/Python 1.1.0. >>> mysql.connector.__version__ '1.1.0'  File: manual.info, Node: connector-python-api-mysql-connector-version-info, Prev: connector-python-api-mysql-connector-version, Up: connector-python-api-mysql-connector 21.6.8.7 Property `mysql.connector.__version_info__' .................................................... This property indicates the Connector/Python version as an array of version components. It is available as of Connector/Python 1.1.0. >>> mysql.connector.__version_info__ (1, 1, 0, 'a', 0)  File: manual.info, Node: connector-python-api-mysqlconnection, Next: connector-python-api-mysqlconnectionpool, Prev: connector-python-api-mysql-connector, Up: connector-python-reference 21.6.8.8 Class `connection.MySQLConnection' ........................................... * Menu: * connector-python-api-mysqlconnection-constructor:: Constructor `connection.MySQLConnection(**kwargs)' * connector-python-api-mysqlconnection-close:: Method `MySQLConnection.close()' * connector-python-api-mysqlconnection-commit:: Method `MySQLConnection.commit()' * connector-python-api-mysqlconnection-config:: Method `MySQLConnection.config(**kwargs)' * connector-python-api-mysqlconnection-connect:: Method `MySQLConnection.connect()' * connector-python-api-mysqlconnection-cursor:: Method `MySQLConnection.cursor(buffered=None, raw=None, cursor_class=None)' * connector-python-api-mysqlconnection-cmd-change-user:: Method `MySQLConnection.cmd_change_user(username='', password='', database='', charset=33)' * connector-python-api-mysqlconnection-cmd-debug:: Method `MySQLConnection.cmd_debug()' * connector-python-api-mysqlconnection-cmd-init-db:: Method `MySQLConnection.cmd_init_db(database)' * connector-python-api-mysqlconnection-cmd-ping:: Method `MySQLConnection.cmd_ping()' * connector-python-api-mysqlconnection-cmd-process-info:: Method `MySQLConnection.cmd_process_info()' * connector-python-api-mysqlconnection-cmd-process-kill:: Method `MySQLConnection.cmd_process_kill(mysql_pid)' * connector-python-api-mysqlconnection-cmd-query:: Method `MySQLConnection.cmd_query(statement)' * connector-python-api-mysqlconnection-cmd-query-iter:: Method `MySQLConnection.cmd_query_iter(statement)' * connector-python-api-mysqlconnection-cmd-quit:: Method `MySQLConnection.cmd_quit()' * connector-python-api-mysqlconnection-cmd-refresh:: Method `MySQLConnection.cmd_refresh(options)' * connector-python-api-mysqlconnection-cmd-shutdown:: Method `MySQLConnection.cmd_shutdown()' * connector-python-api-mysqlconnection-cmd-statistics:: Method `MySQLConnection.cmd_statistics()' * connector-python-api-mysqlconnection-disconnect:: Method `MySQLConnection.disconnect()' * connector-python-api-mysqlconnection-get-row:: Method `MySQLConnection.get_row()' * connector-python-api-mysqlconnection-get-rows:: Method `MySQLConnection.get_rows(count=None)' * connector-python-api-mysqlconnection-get-server-info:: Method `MySQLConnection.get_server_info()' * connector-python-api-mysqlconnection-get-server-version:: Method `MySQLConnection.get_server_version()' * connector-python-api-mysqlconnection-is-connected:: Method `MySQLConnection.is_connected()' * connector-python-api-mysqlconnection-isset-client-flag:: Method `MySQLConnection.isset_client_flag(flag)' * connector-python-api-mysqlconnection-ping:: Method `MySQLConnection.ping(attempts=1, delay=0)' * connector-python-api-mysqlconnection-reconnect:: Method `MySQLConnection.reconnect(attempts=1, delay=0)' * connector-python-api-mysqlconnection-rollback:: Method `MySQLConnection.rollback()' * connector-python-api-mysqlconnection-set-charset-collation:: Method `MySQLConnection.set_charset_collation(charset=None, collation=None)' * connector-python-api-mysqlconnection-set-client-flags:: Method `MySQLConnection.set_client_flags(flags)' * connector-python-api-mysqlconnection-start-transaction:: Method `MySQLConnection.start_transaction()' * connector-python-api-mysqlconnection-autocommit:: Property `MySQLConnection.autocommit' * connector-python-api-mysqlconnection-charset-name:: Property `MySQLConnection.charset_name' * connector-python-api-mysqlconnection-collation-name:: Property `MySQLConnection.collation_name' * connector-python-api-mysqlconnection-connection-id:: Property `MySQLConnection.connection_id' * connector-python-api-mysqlconnection-database:: Property `MySQLConnection.database' * connector-python-api-mysqlconnection-get-warnings:: Property `MySQLConnection.get_warnings' * connector-python-api-mysqlconnection-in-transaction:: Property `MySQLConnection.in_transaction' * connector-python-api-mysqlconnection-raise-on-warnings:: Property `MySQLConnection.raise_on_warnings' * connector-python-api-mysqlconnection-server-host:: Property `MySQLConnection.server_host' * connector-python-api-mysqlconnection-server-port:: Property `MySQLConnection.server_port' * connector-python-api-mysqlconnection-sql-mode:: Property `MySQLConnection.sql_mode' * connector-python-api-mysqlconnection-time-zone:: Property `MySQLConnection.time_zone' * connector-python-api-mysqlconnection-unix-socket:: Property `MySQLConnection.unix_socket' * connector-python-api-mysqlconnection-user:: Property `MySQLConnection.user' The `MySQLConnection' class is used to open and manage a connection to a MySQL server. It also used to send commands and SQL statements and read the results.  File: manual.info, Node: connector-python-api-mysqlconnection-constructor, Next: connector-python-api-mysqlconnection-close, Prev: connector-python-api-mysqlconnection, Up: connector-python-api-mysqlconnection 21.6.8.9 Constructor `connection.MySQLConnection(**kwargs)' ........................................................... The `MySQLConnection' constructor initializes the attributes and when at least one argument is passed, it tries to connect to the MySQL server. For a complete list or arguments, see *Note connector-python-connectargs::.  File: manual.info, Node: connector-python-api-mysqlconnection-close, Next: connector-python-api-mysqlconnection-commit, Prev: connector-python-api-mysqlconnection-constructor, Up: connector-python-api-mysqlconnection 21.6.8.10 Method `MySQLConnection.close()' .......................................... Syntax: cnx.close() `close()' is a synonym for `disconnect()'. See *Note connector-python-api-mysqlconnection-disconnect::. For a connection obtained from a connection pool, `close()' does not actually close it but returns it to the pool and makes it available for subsequent connection requests. See *Note connector-python-connection-pooling::.  File: manual.info, Node: connector-python-api-mysqlconnection-commit, Next: connector-python-api-mysqlconnection-config, Prev: connector-python-api-mysqlconnection-close, Up: connector-python-api-mysqlconnection 21.6.8.11 Method `MySQLConnection.commit()' ........................................... This method sends a `COMMIT' statement to the MySQL server, committing the current transaction. Since by default Connector/Python does not autocommit, it is important to call this method after every transaction that modifies data for tables that use transactional storage engines. >>> cursor.execute("INSERT INTO employees (first_name) VALUES (%s)", ('Jane')) >>> cnx.commit() To roll back instead and discard modifications, see the *Note rollback(): connector-python-api-mysqlconnection-rollback. method.  File: manual.info, Node: connector-python-api-mysqlconnection-config, Next: connector-python-api-mysqlconnection-connect, Prev: connector-python-api-mysqlconnection-commit, Up: connector-python-api-mysqlconnection 21.6.8.12 Method `MySQLConnection.config(**kwargs)' ................................................... Syntax: cnx.config(**kwargs) Configures a `MySQLConnection' instance after it has been instantiated. For a complete list of possible arguments, see *Note connector-python-connectargs::. Arguments: * `kwargs': Connection arguments. You could use the `config()' method to change (for example) the user name, then call `reconnect()'. Example: cnx = mysql.connector.connect(user='joe', database='test') # Connected as 'joe' cnx.config(user='jane') cnx.reconnect() # Now connected as 'jane' For a connection obtained from a connection pool, `config()' raises an exception. See *Note connector-python-connection-pooling::.  File: manual.info, Node: connector-python-api-mysqlconnection-connect, Next: connector-python-api-mysqlconnection-cursor, Prev: connector-python-api-mysqlconnection-config, Up: connector-python-api-mysqlconnection 21.6.8.13 Method `MySQLConnection.connect()' ............................................ Syntax: MySQLConnection.connect(**kwargs) This method sets up a connection, establishing a session with the MySQL server. If no arguments are given, it uses the already configured or default values. For a complete list of possible arguments, see *Note connector-python-connectargs::. Arguments: * `kwargs': Connection arguments. Example: cnx = MySQLConnection(user='joe', database='test') For a connection obtained from a conection pool, the connection object class is `PooledMySQLConnection'. A pooled connection differs from an unpooled connection as described in *Note connector-python-connection-pooling::.  File: manual.info, Node: connector-python-api-mysqlconnection-cursor, Next: connector-python-api-mysqlconnection-cmd-change-user, Prev: connector-python-api-mysqlconnection-connect, Up: connector-python-api-mysqlconnection 21.6.8.14 Method `MySQLConnection.cursor(buffered=None, raw=None, cursor_class=None)' ..................................................................................... This method returns a `MySQLCursor()' object, or a subclass of it depending on the passed arguments. When `buffered' is `True', the cursor fetches all rows after the operation is executed. This is useful when queries return small result sets. Setting `raw' skips the conversion from MySQL data types to Python types when fetching rows. Raw is usually used when you want to get better performance or you want to do the conversion yourself. The `cursor_class' argument can be used to pass a class to use for instantiating a new cursor. It must be a subclass of `cursor.CursorBase'. The returned object depends on the combination of the `buffered' and `raw' arguments. * If not buffered and not raw: `cursor.MySQLCursor' * If buffered and not raw: `cursor.MySQLCursorBuffered' * If buffered and raw: `cursor.MySQLCursorBufferedRaw' * If not buffered and raw: `cursor.MySQLCursorRaw' Returns a `CursorBase' instance.  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-change-user, Next: connector-python-api-mysqlconnection-cmd-debug, Prev: connector-python-api-mysqlconnection-cursor, Up: connector-python-api-mysqlconnection 21.6.8.15 Method `MySQLConnection.cmd_change_user(username='', password='', database='', charset=33)' ..................................................................................................... Changes the user using `username' and `password'. It also causes the specified `database' to become the default (current) database. It is also possible to change the character set using the `charset' argument. Returns a dictionary containing the OK packet information.  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-debug, Next: connector-python-api-mysqlconnection-cmd-init-db, Prev: connector-python-api-mysqlconnection-cmd-change-user, Up: connector-python-api-mysqlconnection 21.6.8.16 Method `MySQLConnection.cmd_debug()' .............................................. Instructs the server to write debugging information to the error log. The connected user must have the `SUPER' privilege. Returns a dictionary containing the OK packet information.  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-init-db, Next: connector-python-api-mysqlconnection-cmd-ping, Prev: connector-python-api-mysqlconnection-cmd-debug, Up: connector-python-api-mysqlconnection 21.6.8.17 Method `MySQLConnection.cmd_init_db(database)' ........................................................ This method makes specified database the default (current) database. In subsequent queries, this database is the default for table references that include no explicit database qualifier. Returns a dictionary containing the OK packet information.  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-ping, Next: connector-python-api-mysqlconnection-cmd-process-info, Prev: connector-python-api-mysqlconnection-cmd-init-db, Up: connector-python-api-mysqlconnection 21.6.8.18 Method `MySQLConnection.cmd_ping()' ............................................. Checks whether the connection to the server is working. This method is not to be used directly. Use *Note ping(): connector-python-api-mysqlconnection-ping. or *Note is_connected(): connector-python-api-mysqlconnection-is-connected. instead. Returns a dictionary containing the OK packet information.  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-process-info, Next: connector-python-api-mysqlconnection-cmd-process-kill, Prev: connector-python-api-mysqlconnection-cmd-ping, Up: connector-python-api-mysqlconnection 21.6.8.19 Method `MySQLConnection.cmd_process_info()' ..................................................... This method raises the NotSupportedError exception. Instead, use the `SHOW PROCESSLIST' statement or query the tables found in the database `INFORMATION_SCHEMA'.  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-process-kill, Next: connector-python-api-mysqlconnection-cmd-query, Prev: connector-python-api-mysqlconnection-cmd-process-info, Up: connector-python-api-mysqlconnection 21.6.8.20 Method `MySQLConnection.cmd_process_kill(mysql_pid)' .............................................................. Asks the server to kill the thread specified by `mysql_pid'. Although still available, it is better to use the `KILL' SQL statement. Returns a dictionary containing the OK packet information. The following two lines have the same effect: >>> cnx.cmd_process_kill(123) >>> cnx.cmd_query('KILL 123')  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-query, Next: connector-python-api-mysqlconnection-cmd-query-iter, Prev: connector-python-api-mysqlconnection-cmd-process-kill, Up: connector-python-api-mysqlconnection 21.6.8.21 Method `MySQLConnection.cmd_query(statement)' ....................................................... This method sends the given `statement' to the MySQL server and returns a result. To send multiple statements, use the *Note cmd_query_iter(): connector-python-api-mysqlconnection-cmd-query-iter. method instead. The returned dictionary contains information depending on what kind of query was executed. If the query is a *Note `SELECT': select. statement, the result contains information about columns. Other statements return a dictionary containing OK or EOF packet information. Errors received from the MySQL server are raised as exceptions. An `InterfaceError' is raised when multiple results are found. Returns a dictionary.  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-query-iter, Next: connector-python-api-mysqlconnection-cmd-quit, Prev: connector-python-api-mysqlconnection-cmd-query, Up: connector-python-api-mysqlconnection 21.6.8.22 Method `MySQLConnection.cmd_query_iter(statement)' ............................................................ Similar to the *Note cmd_query(): connector-python-api-mysqlconnection-cmd-query. method, but returns a generator object to iterate through results. Use `cmd_query_iter()' when sending multiple statements, and separate the statements with semicolons. The following example shows how to iterate through the results after sending multiple statements: statement = 'SELECT 1; INSERT INTO t1 VALUES (); SELECT 2' for result in cnx.cmd_query_iter(statement): if 'columns' in result: columns = result['columns'] rows = cnx.get_rows() else: # do something useful with INSERT result Returns a generator object.  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-quit, Next: connector-python-api-mysqlconnection-cmd-refresh, Prev: connector-python-api-mysqlconnection-cmd-query-iter, Up: connector-python-api-mysqlconnection 21.6.8.23 Method `MySQLConnection.cmd_quit()' ............................................. This method sends a `QUIT' command to the MySQL server, closing the current connection. Since there is no response from the MySQL server, the packet that was sent is returned.  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-refresh, Next: connector-python-api-mysqlconnection-cmd-shutdown, Prev: connector-python-api-mysqlconnection-cmd-quit, Up: connector-python-api-mysqlconnection 21.6.8.24 Method `MySQLConnection.cmd_refresh(options)' ....................................................... This method flushes tables or caches, or resets replication server information. The connected user must have the `RELOAD' privilege. The `options' argument should be a bitmask value constructed using constants from the `constants.RefreshOption' class. For a list of options, see *Note connector-python-api-refreshoption::. Example: >>> from mysql.connector import RefreshOption >>> refresh = RefreshOption.LOG | RefreshOption.THREADS >>> cnx.cmd_refresh(refresh)  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-shutdown, Next: connector-python-api-mysqlconnection-cmd-statistics, Prev: connector-python-api-mysqlconnection-cmd-refresh, Up: connector-python-api-mysqlconnection 21.6.8.25 Method `MySQLConnection.cmd_shutdown()' ................................................. Asks the database server to shut down. The connected user must have the `SHUTDOWN' privilege. Returns a dictionary containing the OK packet information.  File: manual.info, Node: connector-python-api-mysqlconnection-cmd-statistics, Next: connector-python-api-mysqlconnection-disconnect, Prev: connector-python-api-mysqlconnection-cmd-shutdown, Up: connector-python-api-mysqlconnection 21.6.8.26 Method `MySQLConnection.cmd_statistics()' ................................................... Returns a dictionary containing information about the MySQL server including uptime in seconds and the number of running threads, questions, reloads, and open tables.  File: manual.info, Node: connector-python-api-mysqlconnection-disconnect, Next: connector-python-api-mysqlconnection-get-row, Prev: connector-python-api-mysqlconnection-cmd-statistics, Up: connector-python-api-mysqlconnection 21.6.8.27 Method `MySQLConnection.disconnect()' ............................................... This method tries to send a `QUIT' command and close the socket. It raises no exceptions. `MySQLConnection.close()' is a synonymous method name and more commonly used.  File: manual.info, Node: connector-python-api-mysqlconnection-get-row, Next: connector-python-api-mysqlconnection-get-rows, Prev: connector-python-api-mysqlconnection-disconnect, Up: connector-python-api-mysqlconnection 21.6.8.28 Method `MySQLConnection.get_row()' ............................................ This method retrieves the next row of a query result set, returning a tuple. The tuple returned by `get_row()' consists of: * The row as a tuple containing byte objects, or `None' when no more rows are available. * EOF packet information as a dictionary containing `status_flag' and `warning_count', or `None' when the row returned is not the last row. The `get_row()' method is used by *Note MySQLCursor: connector-python-api-mysqlcursor. to fetch rows.  File: manual.info, Node: connector-python-api-mysqlconnection-get-rows, Next: connector-python-api-mysqlconnection-get-server-info, Prev: connector-python-api-mysqlconnection-get-row, Up: connector-python-api-mysqlconnection 21.6.8.29 Method `MySQLConnection.get_rows(count=None)' ....................................................... This method retrieves all or remaining rows of a query result set, returning a tuple containing the rows as sequences and the EOF packet information. The count argument can be used to obtain a given number of rows. If count is not specified or is `None', all rows are retrieved. The tuple returned by `get_rows()' consists of: * A list of tuples containing the row data as byte objects, or an empty list when no rows are available. * EOF packet information as a dictionary containing `status_flag' and `warning_count'. An `InterfaceError' is raised when all rows have been retrieved. *Note MySQLCursor: connector-python-api-mysqlcursor. uses the `get_rows()' method to fetch rows. Returns a tuple.  File: manual.info, Node: connector-python-api-mysqlconnection-get-server-info, Next: connector-python-api-mysqlconnection-get-server-version, Prev: connector-python-api-mysqlconnection-get-rows, Up: connector-python-api-mysqlconnection 21.6.8.30 Method `MySQLConnection.get_server_info()' .................................................... This method returns the MySQL server information verbatim as a string, for example `'5.6.11-log'', or `None' when not connected.  File: manual.info, Node: connector-python-api-mysqlconnection-get-server-version, Next: connector-python-api-mysqlconnection-is-connected, Prev: connector-python-api-mysqlconnection-get-server-info, Up: connector-python-api-mysqlconnection 21.6.8.31 Method `MySQLConnection.get_server_version()' ....................................................... This method returns the MySQL server version as a tuple, or `None' when not connected.  File: manual.info, Node: connector-python-api-mysqlconnection-is-connected, Next: connector-python-api-mysqlconnection-isset-client-flag, Prev: connector-python-api-mysqlconnection-get-server-version, Up: connector-python-api-mysqlconnection 21.6.8.32 Method `MySQLConnection.is_connected()' ................................................. Reports whether the connection to MySQL Server is available. This method checks whether the connection to MySQL is available using the *Note ping(): connector-python-api-mysqlconnection-ping. method, but unlike `ping()', `is_connected()' returns `True' when the connection is available, `False' otherwise.  File: manual.info, Node: connector-python-api-mysqlconnection-isset-client-flag, Next: connector-python-api-mysqlconnection-ping, Prev: connector-python-api-mysqlconnection-is-connected, Up: connector-python-api-mysqlconnection 21.6.8.33 Method `MySQLConnection.isset_client_flag(flag)' .......................................................... This method returns `True' if the client flag was set, `False' otherwise.  File: manual.info, Node: connector-python-api-mysqlconnection-ping, Next: connector-python-api-mysqlconnection-reconnect, Prev: connector-python-api-mysqlconnection-isset-client-flag, Up: connector-python-api-mysqlconnection 21.6.8.34 Method `MySQLConnection.ping(attempts=1, delay=0)' ............................................................ Check whether the connection to the MySQL server is still available. When `reconnect' is set to `True', one or more attempts are made to try to reconnect to the MySQL server using the `reconnect()' method. Use the `delay' argument (seconds) if you want to wait between each retry. When the connection is not available, an `InterfaceError' is raised. Use the *Note is_connected(): connector-python-api-mysqlconnection-is-connected. method to check the connection without raising an error. Raises `InterfaceError' on errors.  File: manual.info, Node: connector-python-api-mysqlconnection-reconnect, Next: connector-python-api-mysqlconnection-rollback, Prev: connector-python-api-mysqlconnection-ping, Up: connector-python-api-mysqlconnection 21.6.8.35 Method `MySQLConnection.reconnect(attempts=1, delay=0)' ................................................................. Attempt to reconnect to the MySQL server. The argument `attempts' specifies the number of times a reconnect is tried. The `delay' argument is the number of seconds to wait between each retry. You might set the number of attempts higher and use a longer delay when you expect the MySQL server to be down for maintenance, or when you expect the network to be temporarily unavailable.  File: manual.info, Node: connector-python-api-mysqlconnection-rollback, Next: connector-python-api-mysqlconnection-set-charset-collation, Prev: connector-python-api-mysqlconnection-reconnect, Up: connector-python-api-mysqlconnection 21.6.8.36 Method `MySQLConnection.rollback()' ............................................. This method sends a `ROLLBACK' statement to the MySQL server, undoing all data changes from the current transaction. By default, Connector/Python does not autocommit, so it is possible to cancel transactions when using transactional storage engines such as `InnoDB'. >>> cursor.execute("INSERT INTO employees (first_name) VALUES (%s)", ('Jane')) >>> cnx.rollback() To commit (http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_commit) modifications, see the *Note commit(): connector-python-api-mysqlconnection-commit. method.  File: manual.info, Node: connector-python-api-mysqlconnection-set-charset-collation, Next: connector-python-api-mysqlconnection-set-client-flags, Prev: connector-python-api-mysqlconnection-rollback, Up: connector-python-api-mysqlconnection 21.6.8.37 Method `MySQLConnection.set_charset_collation(charset=None, collation=None)' ...................................................................................... This method sets the character set and collation to be used for the current connection. The `charset' argument can be either the name of a character set, or the numerical equivalent as defined in `constants.CharacterSet'. When `collation' is `None', the default collation for the character set is used. In the following example, we set the character set to `latin1' and the collation to `latin1_swedish_ci' (the default collation for: `latin1'): >>> cnx = mysql.connector.connect(user='scott') >>> cnx.set_charset('latin1') Specify a given collation as follows: >>> cnx = mysql.connector.connect(user='scott') >>> cnx.set_charset('latin1', 'latin1_general_ci')  File: manual.info, Node: connector-python-api-mysqlconnection-set-client-flags, Next: connector-python-api-mysqlconnection-start-transaction, Prev: connector-python-api-mysqlconnection-set-charset-collation, Up: connector-python-api-mysqlconnection 21.6.8.38 Method `MySQLConnection.set_client_flags(flags)' .......................................................... This method sets the client flags to use when connecting to the MySQL server, and returns the new value as an integer. The `flags' argument can be either an integer or a sequence of valid client flag values (see *Note connector-python-api-clientflag::). If `flags' is a sequence, each item in the sequence sets the flag when the value is positive or unsets it when negative. For example, to unset `LONG_FLAG' and set the `FOUND_ROWS' flags: >>> from mysql.connector.constants import ClientFlag >>> cnx.set_client_flags([ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG]) >>> cnx.reconnect() Note that client flags are only set or used when connecting to the MySQL server. It is therefore necessary to reconnect after making changes.  File: manual.info, Node: connector-python-api-mysqlconnection-start-transaction, Next: connector-python-api-mysqlconnection-autocommit, Prev: connector-python-api-mysqlconnection-set-client-flags, Up: connector-python-api-mysqlconnection 21.6.8.39 Method `MySQLConnection.start_transaction()' ...................................................... This method starts a transaction. It accepts accepts arguments indicating whether to use a consistent snapshot and which transaction isolation level to use: cnx.start_transaction(consistent_snapshot=BOOL, isolation_level=LEVEL) The default `consistent_snapshot' value is `False'. The default `isolation_level' value is `None', and permitted values are `'READ UNCOMMITTED'', `'READ COMMITTED'', `'REPEATABLE READ'', and `'SERIALIZABLE''. Invoking `start_transaction()' raises a `ProgrammingError' if invoked while a transaction is currently in progress. This differs from executing a *Note `START TRANSACTION': commit. SQL statement while a transaction is in progress; the statement implicitly commits the current transaction. To determine whether a transaction is active for the connection, use the the *Note in_transaction: connector-python-api-mysqlconnection-in-transaction. property. `start_transaction()' was added in MySQL Connector/Python 1.1.0.  File: manual.info, Node: connector-python-api-mysqlconnection-autocommit, Next: connector-python-api-mysqlconnection-charset-name, Prev: connector-python-api-mysqlconnection-start-transaction, Up: connector-python-api-mysqlconnection 21.6.8.40 Property `MySQLConnection.autocommit' ............................................... This property can be assigned a value of `True' or `False' to enable or disable the autocommit feature of MySQL. The property can be invoked to retrieve the current autocommit setting. Note that autocommit is disabled by default when connecting through Connector/Python. This can be enabled using the `autocommit' *Note connection parameter: connector-python-connectargs. When the autocommit is turned off, you must *Note commit: connector-python-api-mysqlconnection-commit. transactions when using transactional storage engines such as `InnoDB' or `NDBCluster'. >>> cnx.autocommit False >>> cnx.autocommit = True >>> cnx.autocommit True  File: manual.info, Node: connector-python-api-mysqlconnection-charset-name, Next: connector-python-api-mysqlconnection-collation-name, Prev: connector-python-api-mysqlconnection-autocommit, Up: connector-python-api-mysqlconnection 21.6.8.41 Property `MySQLConnection.charset_name' ................................................. This property returns a string indicating which character set is used for the connection, whether or not it is connected.  File: manual.info, Node: connector-python-api-mysqlconnection-collation-name, Next: connector-python-api-mysqlconnection-connection-id, Prev: connector-python-api-mysqlconnection-charset-name, Up: connector-python-api-mysqlconnection 21.6.8.42 Property `MySQLConnection.collation_name' ................................................... This property returns a string indicating which collation is used for the connection, whether or not it is connected.  File: manual.info, Node: connector-python-api-mysqlconnection-connection-id, Next: connector-python-api-mysqlconnection-database, Prev: connector-python-api-mysqlconnection-collation-name, Up: connector-python-api-mysqlconnection 21.6.8.43 Property `MySQLConnection.connection_id' .................................................. This property returns the integer connection ID (thread ID or session ID) for the current connection or `None' when not connected.  File: manual.info, Node: connector-python-api-mysqlconnection-database, Next: connector-python-api-mysqlconnection-get-warnings, Prev: connector-python-api-mysqlconnection-connection-id, Up: connector-python-api-mysqlconnection 21.6.8.44 Property `MySQLConnection.database' ............................................. This property sets the current (default) database by executing a `USE' statement. The property can also be used to retrieve the current database name. >>> cnx.database = 'test' >>> cnx.database = 'mysql' >>> cnx.database u'mysql' Returns a string.  File: manual.info, Node: connector-python-api-mysqlconnection-get-warnings, Next: connector-python-api-mysqlconnection-in-transaction, Prev: connector-python-api-mysqlconnection-database, Up: connector-python-api-mysqlconnection 21.6.8.45 Property `MySQLConnection.get_warnings' ................................................. This property can be assigned a value of `True' or `False' to enable or disable whether warnings should be fetched automatically. The default is `False' (default). The property can be invoked to retrieve the current warnings setting. Fetching warnings automatically can be useful when debugging queries. Cursors make warnings available through the method *Note MySQLCursor.fetchwarnings(): connector-python-api-mysqlcursor-fetchwarnings. >>> cnx.get_warnings = True >>> cursor.execute('SELECT "a"+1') >>> cursor.fetchall() [(1.0,)] >>> cursor.fetchwarnings() [(u'Warning', 1292, u"Truncated incorrect DOUBLE value: 'a'")] Returns `True' or `False'.  File: manual.info, Node: connector-python-api-mysqlconnection-in-transaction, Next: connector-python-api-mysqlconnection-raise-on-warnings, Prev: connector-python-api-mysqlconnection-get-warnings, Up: connector-python-api-mysqlconnection 21.6.8.46 Property `MySQLConnection.in_transaction' ................................................... This property returns `True' or `False' to indicate whether a transaction is active for the connection. The value is `True' regardless of whether you start a transaction using the *Note `start_transaction()': connector-python-api-mysqlconnection-start-transaction. API call or by directly executing a SQL statement such as *Note `START TRANSACTION': commit. or *Note `BEGIN': commit. >>> cnx.start_transaction() >>> cnx.in_transaction True >>> cnx.commit() >>> cnx.in_transaction False `in_transaction' was added in MySQL Connector/Python 1.1.0.  File: manual.info, Node: connector-python-api-mysqlconnection-raise-on-warnings, Next: connector-python-api-mysqlconnection-server-host, Prev: connector-python-api-mysqlconnection-in-transaction, Up: connector-python-api-mysqlconnection 21.6.8.47 Property `MySQLConnection.raise_on_warnings' ...................................................... This property can be assigned a value of `True' or `False' to enable or disable whether warnings should raise exceptions. The default is `False' (default). The property can be invoked to retrieve the current exceptions setting. Setting `raise_on_warnings' also sets `get_warnings' because warnings need to be fetched so they can be raised as exceptions. Note that you might always want to set the SQL mode if you would like to have the MySQL server directly report warnings as errors (see *Note connector-python-api-mysqlconnection-sql-mode::). It is also good to use transactional engines so transactions can be rolled back when catching the exception. Result sets needs to be fetched completely before any exception can be raised. The following example shows the execution of a query that produces a warning: >>> cnx.raise_on_warnings = True >>> cursor.execute('SELECT "a"+1') >>> cursor.fetchall() .. mysql.connector.errors.DataError: 1292: Truncated incorrect DOUBLE value: 'a' Returns `True' or `False'.  File: manual.info, Node: connector-python-api-mysqlconnection-server-host, Next: connector-python-api-mysqlconnection-server-port, Prev: connector-python-api-mysqlconnection-raise-on-warnings, Up: connector-python-api-mysqlconnection 21.6.8.48 Property `MySQLConnection.server_host' ................................................ This read-only property returns the host name or IP address used for connecting to the MySQL server. Returns a string.  File: manual.info, Node: connector-python-api-mysqlconnection-server-port, Next: connector-python-api-mysqlconnection-sql-mode, Prev: connector-python-api-mysqlconnection-server-host, Up: connector-python-api-mysqlconnection 21.6.8.49 Property `MySQLConnection.server_port' ................................................ This read-only property returns the TCP/IP port used for connecting to the MySQL server. Returns an integer.  File: manual.info, Node: connector-python-api-mysqlconnection-sql-mode, Next: connector-python-api-mysqlconnection-time-zone, Prev: connector-python-api-mysqlconnection-server-port, Up: connector-python-api-mysqlconnection 21.6.8.50 Property `MySQLConnection.sql_mode' ............................................. This property is used to retrieve and set the SQL Modes for the current connection. The value should be a list of different modes separated by comma (","), or a sequence of modes, preferably using the `constants.SQLMode' class. To unset all modes, pass an empty string or an empty sequence. >>> cnx.sql_mode = 'TRADITIONAL,NO_ENGINE_SUBSTITUTION' >>> cnx.sql_mode.split(',') [u'STRICT_TRANS_TABLES', u'STRICT_ALL_TABLES', u'NO_ZERO_IN_DATE', u'NO_ZERO_DATE', u'ERROR_FOR_DIVISION_BY_ZERO', u'TRADITIONAL', u'NO_AUTO_CREATE_USER', u'NO_ENGINE_SUBSTITUTION'] >>> from mysql.connector.constants import SQLMode >>> cnx.sql_mode = [ SQLMode.NO_ZERO_DATE, SQLMode.REAL_AS_FLOAT] >>> cnx.sql_mode u'REAL_AS_FLOAT,NO_ZERO_DATE' Returns a string.  File: manual.info, Node: connector-python-api-mysqlconnection-time-zone, Next: connector-python-api-mysqlconnection-unix-socket, Prev: connector-python-api-mysqlconnection-sql-mode, Up: connector-python-api-mysqlconnection 21.6.8.51 Property `MySQLConnection.time_zone' .............................................. This property is used to set or retrieve the time zone session variable for the current connection. >>> cnx.time_zone = '+00:00' >>> cur.execute('SELECT NOW()') ; cur.fetchone() (datetime.datetime(2012, 6, 15, 11, 24, 36),) >>> cnx.time_zone = '-09:00' >>> cur.execute('SELECT NOW()') ; cur.fetchone() (datetime.datetime(2012, 6, 15, 2, 24, 44),) >>> cnx.time_zone u'-09:00' Returns a string.  File: manual.info, Node: connector-python-api-mysqlconnection-unix-socket, Next: connector-python-api-mysqlconnection-user, Prev: connector-python-api-mysqlconnection-time-zone, Up: connector-python-api-mysqlconnection 21.6.8.52 Property `MySQLConnection.unix_socket' ................................................ This read-only property returns the Unix socket file for connecting to the MySQL server. Returns a string.  File: manual.info, Node: connector-python-api-mysqlconnection-user, Prev: connector-python-api-mysqlconnection-unix-socket, Up: connector-python-api-mysqlconnection 21.6.8.53 Property `MySQLConnection.user' ......................................... This read-only property returns the user name used for connecting to the MySQL server. Returns a string.  File: manual.info, Node: connector-python-api-mysqlconnectionpool, Next: connector-python-api-pooledmysqlconnection, Prev: connector-python-api-mysqlconnection, Up: connector-python-reference 21.6.8.54 Class `pooling.MySQLConnectionPool' ............................................. * Menu: * connector-python-api-mysqlconnectionpool-constructor:: Constructor `pooling.MySQLConnectionPool' * connector-python-api-mysqlconnectionpool-add-connection:: Method `MySQLConnectionPool.add_connection()' * connector-python-api-mysqlconnectionpool-get-connection:: Method `MySQLConnectionPool.get_connection()' * connector-python-api-mysqlconnectionpool-set-config:: Method `MySQLConnectionPool.set_config()' * connector-python-api-mysqlconnectionpool-pool-name:: Property `MySQLConnectionPool.pool_name' This class provides for the instantiation and management of connection pools.  File: manual.info, Node: connector-python-api-mysqlconnectionpool-constructor, Next: connector-python-api-mysqlconnectionpool-add-connection, Prev: connector-python-api-mysqlconnectionpool, Up: connector-python-api-mysqlconnectionpool 21.6.8.55 Constructor `pooling.MySQLConnectionPool' ................................................... Syntax: MySQLConnectionPool(pool_name = None, pool_size = 5, **kwargs) This constructor instantiates an object that manages a connection pool. Arguments: * `pool_name': The pool name. If this argument is not given, Connector/Python automatically generates the name, composed from whichever of the `host', `port', `user', and `database' connection arguments are given in `kwargs', in that order. It is not an error for multiple pools to have the same name. An application that must distinguish pools by their `pool_name' property should create each pool with a distinct name. * `pool_size': The pool size. If this argument is not given, the default is 5. * `kwargs': Optional additional connection arguments, as described in *Note connector-python-connectargs::. Example: dbconfig = { "database": "test", "user": "joe" } cnxpool = mysql.connector.pooling.MySQLConnectionPool(pool_name = "mypool", pool_size = 3, **dbconfig)  File: manual.info, Node: connector-python-api-mysqlconnectionpool-add-connection, Next: connector-python-api-mysqlconnectionpool-get-connection, Prev: connector-python-api-mysqlconnectionpool-constructor, Up: connector-python-api-mysqlconnectionpool 21.6.8.56 Method `MySQLConnectionPool.add_connection()' ....................................................... Syntax: cnxpool.add_connection(cnx = None) This method adds a new or existing `MySQLConnection' to the pool, or raises a `PoolError' if the pool is full. Arguments: * `cnx': The `MySQLConnection' object to be added to the pool. If this argument is missing, the pool creates a new connection and adds it. Example: cnxpool.add_connection() # add new connection to pool cnxpool.add_connection(cnx) # add existing connection to pool  File: manual.info, Node: connector-python-api-mysqlconnectionpool-get-connection, Next: connector-python-api-mysqlconnectionpool-set-config, Prev: connector-python-api-mysqlconnectionpool-add-connection, Up: connector-python-api-mysqlconnectionpool 21.6.8.57 Method `MySQLConnectionPool.get_connection()' ....................................................... Syntax: cnxpool.get_connection() This method returns a connection from the pool, or raises a `PoolError' if no connections are available. Example: cnx = cnxpool.get_connection()  File: manual.info, Node: connector-python-api-mysqlconnectionpool-set-config, Next: connector-python-api-mysqlconnectionpool-pool-name, Prev: connector-python-api-mysqlconnectionpool-get-connection, Up: connector-python-api-mysqlconnectionpool 21.6.8.58 Method `MySQLConnectionPool.set_config()' ................................................... Syntax: cnxpool.set_config(**kwargs) This method sets the configuration parameters for connections in the pool. Connections requested from the pool after the configuration change use the new parameters. Connections obtained before the change remain unaffected, but when they are closed (returned to the pool) are reopened with the new parameters before being returned by the pool for subsequent connection requests. Arguments: * `kwargs': Connection arguments. Example: dbconfig = { "database": "performance_schema", "user": "admin", "password": "secret" } cnxpool.set_config(**dbconfig)  File: manual.info, Node: connector-python-api-mysqlconnectionpool-pool-name, Prev: connector-python-api-mysqlconnectionpool-set-config, Up: connector-python-api-mysqlconnectionpool 21.6.8.59 Property `MySQLConnectionPool.pool_name' .................................................. Syntax: cnxpool.pool_name This property returns the connection pool name. Example: name = cnxpool.pool_name  File: manual.info, Node: connector-python-api-pooledmysqlconnection, Next: connector-python-api-mysqlcursor, Prev: connector-python-api-mysqlconnectionpool, Up: connector-python-reference 21.6.8.60 Class `pooling.PooledMySQLConnection' ............................................... * Menu: * connector-python-api-pooledmysqlconnection-constructor:: Constructor `pooling.PooledMySQLConnection' * connector-python-api-pooledmysqlconnection-close:: Method `PooledMySQLConnection.close()' * connector-python-api-pooledmysqlconnection-config:: Method `PooledMySQLConnection.config()' * connector-python-api-pooledmysqlconnection-pool-name:: Property `PooledMySQLConnection.pool_name' This class is used by `MySQLConnectionPool' to return a pooled connection instance. It is also the class used for connections obtained with calls to the `connect()' method that name a connection pool (see *Note connector-python-connection-pooling::). `PooledMySQLConnection' pooled connection objects are similar to `MySQLConnection' unpooled connection objects, with these differences: * To release a pooled connection obtained from a connection pool, invoke its `close()' method, just as for any unpooled connection. However, for a pooled connection, `close()' does not actually close the connection but returns it to the pool and makes it available for subsequent connection requests. * A pooled connection cannot be reconfigured using its `config()' method. Connection changes must be done through the pool object itself, as described shortly. * A pooled connection has a `pool_name' property that returns the pool name.  File: manual.info, Node: connector-python-api-pooledmysqlconnection-constructor, Next: connector-python-api-pooledmysqlconnection-close, Prev: connector-python-api-pooledmysqlconnection, Up: connector-python-api-pooledmysqlconnection 21.6.8.61 Constructor `pooling.PooledMySQLConnection' ..................................................... Syntax: PooledMySQLConnection(cnxpool, cnx) This constructor takes connection pool and connection arguments and returns a pooled connection. It is used by the `MySQLConnectionPool' class. Arguments: * `cnxpool': A `MySQLConnectionPool' instance. * `cnx': A `MySQLConnection' instance. Example: pcnx = mysql.connector.pooling.PooledMySQLConnection(cnxpool, cnx)  File: manual.info, Node: connector-python-api-pooledmysqlconnection-close, Next: connector-python-api-pooledmysqlconnection-config, Prev: connector-python-api-pooledmysqlconnection-constructor, Up: connector-python-api-pooledmysqlconnection 21.6.8.62 Method `PooledMySQLConnection.close()' ................................................ Syntax: cnx.close() Returns a pooled connection to its connection pool. For a pooled connection, `close()' does not actually close it but returns it to the pool and makes it available for subsequent connection requests. If the pool configuration parameters are changed, a returned connection is closed and reopened with the new configuration before being returned from the pool again in response to a connection request.  File: manual.info, Node: connector-python-api-pooledmysqlconnection-config, Next: connector-python-api-pooledmysqlconnection-pool-name, Prev: connector-python-api-pooledmysqlconnection-close, Up: connector-python-api-pooledmysqlconnection 21.6.8.63 Method `PooledMySQLConnection.config()' ................................................. For pooled connections, the `config()' method raises a `PoolError' exception. Configuration for pooled connections should be done using the pool object.  File: manual.info, Node: connector-python-api-pooledmysqlconnection-pool-name, Prev: connector-python-api-pooledmysqlconnection-config, Up: connector-python-api-pooledmysqlconnection 21.6.8.64 Property `PooledMySQLConnection.pool_name' .................................................... Syntax: cnx.pool_name This property returns the name of the connection pool to which the connection belongs. Example: cnx = cnxpool.get_connection() name = cnx.pool_name  File: manual.info, Node: connector-python-api-mysqlcursor, Next: connector-python-api-mysqlcursorbuffered, Prev: connector-python-api-pooledmysqlconnection, Up: connector-python-reference 21.6.8.65 Class `cursor.MySQLCursor' .................................... * Menu: * connector-python-api-mysqlcursor-constructor:: Constructor `cursor.MySQLCursor' * connector-python-api-mysqlcursor-callproc:: Method `MySQLCursor.callproc(procname, args=())' * connector-python-api-mysqlcursor-close:: Method `MySQLCursor.close()' * connector-python-api-mysqlcursor-execute:: Method `MySQLCursor.execute(operation, params=None, multi=False)' * connector-python-api-mysqlcursor-executemany:: Method `MySQLCursor.executemany(operation, seq_params)' * connector-python-api-mysqlcursor-fetchall:: Method `MySQLCursor.fetchall()' * connector-python-api-mysqlcursor-fetchmany:: Method `MySQLCursor.fetchmany(size=1)' * connector-python-api-mysqlcursor-fetchone:: Method `MySQLCursor.fetchone()' * connector-python-api-mysqlcursor-fetchwarnings:: Method `MySQLCursor.fetchwarnings()' * connector-python-api-mysqlcursor-stored-results:: Method `MySQLCursor.stored_results()' * connector-python-api-mysqlcursor-column-names:: Property `MySQLCursor.column_names' * connector-python-api-mysqlcursor-description:: Property `MySQLCursor.description' * connector-python-api-mysqlcursor-lastrowid:: Property `MySQLCursor.lastrowid' * connector-python-api-mysqlcursor-statement:: Property `MySQLCursor.statement' * connector-python-api-mysqlcursor-with-rows:: Property `MySQLCursor.with_rows' The `MySQLCursor' class is used to instantiate objects that can execute operations such as SQL queries. They interact with the MySQL server using a `MySQLConnection' object. These related classes inherit from `cursor.MySQLCursor': * `cursor.MySQLCursorBuffered' creates a buffered cursor. See *Note connector-python-api-mysqlcursorbuffered::. * `cursor.MySQLCursorBuffered' creates a cursor for executing prepared statements. See *Note connector-python-api-mysqlcursorprepared::.  File: manual.info, Node: connector-python-api-mysqlcursor-constructor, Next: connector-python-api-mysqlcursor-callproc, Prev: connector-python-api-mysqlcursor, Up: connector-python-api-mysqlcursor 21.6.8.66 Constructor `cursor.MySQLCursor' .......................................... The constructor initializes the instance with the optional `connection', which should be an instance of *Note `MySQLConnection': connector-python-api-mysqlconnection. In most cases, the `MySQLConnection' *Note `cursor()': connector-python-api-mysqlconnection-cursor. method is used to instantiate a `MySQLCursor' object.  File: manual.info, Node: connector-python-api-mysqlcursor-callproc, Next: connector-python-api-mysqlcursor-close, Prev: connector-python-api-mysqlcursor-constructor, Up: connector-python-api-mysqlcursor 21.6.8.67 Method `MySQLCursor.callproc(procname, args=())' .......................................................... This method calls a stored procedure with the given name. The `args' sequence of parameters must contain one entry for each argument that the routine expects. The result is returned as modified copy of the input sequence. Input parameters are left untouched. Output and input/output parameters may be replaced with new values. Result sets produced by the stored procedure are automatically fetched and stored as *Note MySQLCursorBuffered: connector-python-api-mysqlcursorbuffered. instances. For more information, see *Note stored_results(): connector-python-api-mysqlcursor-stored-results. The following example shows how to execute a stored procedure which takes two parameters, multiplies the values and returns the product: # Definition of the multiply stored procedure: # CREATE PROCEDURE multiply(IN pFac1 INT, IN pFac2 INT, OUT pProd INT) # BEGIN # SET pProd := pFac1 * pFac2; # END >>> args = (5, 5, 0) # 0 is to hold value of the OUT parameter pProd >>> cursor.callproc('multiply', args) ('5', '5', 25L)  File: manual.info, Node: connector-python-api-mysqlcursor-close, Next: connector-python-api-mysqlcursor-execute, Prev: connector-python-api-mysqlcursor-callproc, Up: connector-python-api-mysqlcursor 21.6.8.68 Method `MySQLCursor.close()' ...................................... This method closes the MySQL cursor, resetting all results, and make sure that the cursor object has no reference to the connection object. Use `close()' every time you are done using the cursor.  File: manual.info, Node: connector-python-api-mysqlcursor-execute, Next: connector-python-api-mysqlcursor-executemany, Prev: connector-python-api-mysqlcursor-close, Up: connector-python-api-mysqlcursor 21.6.8.69 Method `MySQLCursor.execute(operation, params=None, multi=False)' ........................................................................... This method prepare the given database `operation' (query or command). The parameters found in the tuple or dictionary `params' are bound to the variables in the operation. Variables are specified using `%s' (`format') or `%(NAME)s' (`pyformat') parameter style. This example inserts information about a new employee, then selects the data for this person: insert = ( "INSERT INTO employees (emp_no, first_name, last_name, hire_date) " "VALUES (%s, %s, %s, %s)") data = (2, 'Jane', 'Doe', datetime.date(2012, 3, 23)) cursor.execute(insert, data) select = "SELECT * FROM employees WHERE emp_no = %(emp_no)s" cursor.execute(select, { 'emp_no': 2 }) Note that the data values are converted as necessar from Python objects to something MySQL understand. In the preceding example, the `datetime.date()' instance is converted to `'2012-03-23''. When `multi' is set to `True', `execute()' is able to execute multiple statements. It returns an iterator that makes it possible to process the results for each statement. Note that using parameters is not working well in this case, and it is usually a good idea to execute each statement on its own. The following example selects and inserts data in one operation and displays the result: operation = 'SELECT 1; INSERT INTO t1 VALUES (); SELECT 2' for result in cursor.execute(operation): if result.with_rows: print("Statement '{}' has following rows:".format( result.statement)) print(result.fetchall()) else: print("Affected row(s) by query '{}' was {}".format( result.statement, result.rowcount)) If the connection was configured to fetch warnings, warnings generated by the operation are available through the *Note MySQLCursor.fetchwarnings(): connector-python-api-mysqlcursor-fetchwarnings. method. Returns an iterator when `multi' is `True'.  File: manual.info, Node: connector-python-api-mysqlcursor-executemany, Next: connector-python-api-mysqlcursor-fetchall, Prev: connector-python-api-mysqlcursor-execute, Up: connector-python-api-mysqlcursor 21.6.8.70 Method `MySQLCursor.executemany(operation, seq_params)' ................................................................. This method prepares a database operation (query or command) and then executes it against all parameter sequences or mappings found in the sequence `seq_of_params'. The `executemany()' iterates through the sequence of parameters calling the `execute()' method. Inserting data, however, is optimized by batching them using multipler-row syntax. The following example inserts three records: data = [ ('Jane', date(2005, 2, 12)), ('Joe', date(2006, 5, 23)), ('John', date(2010, 10, 3)), ] stmt = "INSERT INTO employees (first_name, hire_date) VALUES (%s, %s)" cursor.executemany(stmt, data) In the preceding example, the *Note `INSERT': insert. statement sent to MySQL would be: INSERT INTO employees (first_name, hire_date) VALUES ('Jane', '2005-02-12'), ('Joe', '2006-05-23'), ('John', '2010-10-03') Tt is not possible to execute multiple statements using the `executemany()' method. Doing so raises an `InternalError' exception.  File: manual.info, Node: connector-python-api-mysqlcursor-fetchall, Next: connector-python-api-mysqlcursor-fetchmany, Prev: connector-python-api-mysqlcursor-executemany, Up: connector-python-api-mysqlcursor 21.6.8.71 Method `MySQLCursor.fetchall()' ......................................... The method fetches all or remaining rows of a query result set, returning a list of tuples. When no more rows are available, it returns an empty list. The following example shows how to retrieve the first two rows of a result set, and then retrieve the remaining rows: >>> cursor.execute("SELECT * FROM employees ORDER BY emp_no") >>> head_rows = cursor.fetchmany(size=2) >>> remaining_rows = cursor.fetchall() You must fetch all rows before being able to execute new queries using the same connection.  File: manual.info, Node: connector-python-api-mysqlcursor-fetchmany, Next: connector-python-api-mysqlcursor-fetchone, Prev: connector-python-api-mysqlcursor-fetchall, Up: connector-python-api-mysqlcursor 21.6.8.72 Method `MySQLCursor.fetchmany(size=1)' ................................................ This method fetches the next set of rows of a query result, returning a list of tuples. When no more rows are available, it returns an empty list. The number of rows returned can be specified using the size argument, which defaults to one. Fewer rows might be returned, when there are not more rows available than specified by the argument. Note that you must fetch all rows before being able to execute new queries using the same connection.  File: manual.info, Node: connector-python-api-mysqlcursor-fetchone, Next: connector-python-api-mysqlcursor-fetchwarnings, Prev: connector-python-api-mysqlcursor-fetchmany, Up: connector-python-api-mysqlcursor 21.6.8.73 Method `MySQLCursor.fetchone()' ......................................... This method retrieves the next row of a query result set, returning a single sequence, or `None' when no more rows are available.The returned tuple consists of data returned by the MySQL server converted to Python objects. The `fetchone()' method is used by *Note fetchmany(): connector-python-api-mysqlcursor-fetchmany. and *Note fetchall(): connector-python-api-mysqlcursor-fetchall. It is also used when using the `MySQLCursor' instance as an iterator. The following example shows how to use `fetchone()' to process a query result, first using a `while' loop, then using an iterator: # Using a while-loop cursor.execute("SELECT * FROM employees") row = cursor.fetchone() while row is not None: print(row) row = cursor.fetchone() # Using the cursor as iterator cursor.execute("SELECT * FROM employees") for row in cursor: print(row) You must fetch all rows before being able to execute new queries using the same connection.  File: manual.info, Node: connector-python-api-mysqlcursor-fetchwarnings, Next: connector-python-api-mysqlcursor-stored-results, Prev: connector-python-api-mysqlcursor-fetchone, Up: connector-python-api-mysqlcursor 21.6.8.74 Method `MySQLCursor.fetchwarnings()' .............................................. This method returns a list of tuples containing warnings generated by previously executed statement. Use the connection's `get_warnings' property to set whether warnings are to be fetched. The following example shows a *Note `SELECT': select. statement which generated a warning: >>> cnx.get_warnings = True >>> cursor.execute('SELECT "a"+1') >>> cursor.fetchall() [(1.0,)] >>> cursor.fetchwarnings() [(u'Warning', 1292, u"Truncated incorrect DOUBLE value: 'a'")] It is also possible to raise errors when warnings are found. See the `MySQLConnection' *Note raise_on_warnings: connector-python-api-mysqlconnection-raise-on-warnings. property.  File: manual.info, Node: connector-python-api-mysqlcursor-stored-results, Next: connector-python-api-mysqlcursor-column-names, Prev: connector-python-api-mysqlcursor-fetchwarnings, Up: connector-python-api-mysqlcursor 21.6.8.75 Method `MySQLCursor.stored_results()' ............................................... This method returns a list iterator object that can be used to process result sets produced by a stored procedure after calling it using the *Note callproc(): connector-python-api-mysqlcursor-callproc. method. The following example executes a stored procedure that produces two result sets, then uses `stored_results()' to retrieve them: >>> cursor.callproc('sp1') () >>> for result in cursor.stored_results(): ... print result.fetchall() ... [(1,)] [(2,)] The result sets remain available until you execute another operation or call another stored procedure.  File: manual.info, Node: connector-python-api-mysqlcursor-column-names, Next: connector-python-api-mysqlcursor-description, Prev: connector-python-api-mysqlcursor-stored-results, Up: connector-python-api-mysqlcursor 21.6.8.76 Property `MySQLCursor.column_names' ............................................. This read-only property returns the column names of a result set as sequence of (Unicode) strings. The following example shows how to create a dictionary from a tuple containing data with keys using `column_names': cursor.execute("SELECT last_name, first_name, hire_date " "FROM employees WHERE emp_no = %s", (123,)) row = dict(zip(cursor.column_names, cursor.fetchone()) print("{last_name}, {first_name}: {hire_date}".format(row))  File: manual.info, Node: connector-python-api-mysqlcursor-description, Next: connector-python-api-mysqlcursor-lastrowid, Prev: connector-python-api-mysqlcursor-column-names, Up: connector-python-api-mysqlcursor 21.6.8.77 Property `MySQLCursor.description' ............................................ This read-only property returns a list of tuples describing the columns in a result set. Each tuple contains values as follows: (column_name, type, None, None, None, None, null_ok, column_flags) The following example shows how to interpret `description' tuples: import mysql.connector from mysql.connector import FieldType ... cursor.execute("SELECT emp_no, last_name, hire_date " "FROM employees WHERE emp_no = %s", (123,)) for i in range(len(cursor.description)): print("Column {}:".format(i+1)) desc = cursor.description[i] print("column_name = {}".format(desc[0])) print("type = {} ({})".format(desc[1], FieldType.get_info(desc[1]))) print("null_ok = {}".format(desc[6])) print("column_flags = {}".format(desc[7])) The output looks like this: Column 1: column_name = emp_no type = 3 (LONG) null_ok = 0 column_flags = 20483 Column 2: column_name = last_name type = 253 (VAR_STRING) null_ok = 0 column_flags = 4097 Column 3: column_name = hire_date type = 10 (DATE) null_ok = 0 column_flags = 4225 The `column_flags' value is an instance of the `constants.FieldFlag' class. To see how to interpret it, do this: >>> from mysql.connector import FieldFlag >>> FieldFlag.desc  File: manual.info, Node: connector-python-api-mysqlcursor-lastrowid, Next: connector-python-api-mysqlcursor-statement, Prev: connector-python-api-mysqlcursor-description, Up: connector-python-api-mysqlcursor 21.6.8.78 Property `MySQLCursor.lastrowid' .......................................... This read-only property returns the row ID of the last modified row. For example, if you perform an *Note `INSERT': insert. into a table that contains an `AUTO_INCREMENT' column, `lastrowid' returns the `AUTO_INCREMENT' value for the new row. For an example, see *Note connector-python-example-cursor-transaction::.  File: manual.info, Node: connector-python-api-mysqlcursor-statement, Next: connector-python-api-mysqlcursor-with-rows, Prev: connector-python-api-mysqlcursor-lastrowid, Up: connector-python-api-mysqlcursor 21.6.8.79 Property `MySQLCursor.statement' .......................................... This read-only property returns the last executed statement as a string. The string can contain multiple statements if a multiple-statement string was executed. The `statement' property can be useful for debugging and displaying what was sent to the MySQL server.  File: manual.info, Node: connector-python-api-mysqlcursor-with-rows, Prev: connector-python-api-mysqlcursor-statement, Up: connector-python-api-mysqlcursor 21.6.8.80 Property `MySQLCursor.with_rows' .......................................... This read-only property returns `True' when the result of the executed operation provides rows. The `with_rows' property is useful when it is necessary to determine whether a statement produces a result set and you need to fetch rows. The following example retrieves the rows returned by the *Note `SELECT': select. statement, but reports only the affected-rows value for the *Note `UPDATE': update. statement: import mysql.connector cnx = mysql.connector.connect(user='scott', database='test') cursor = cnx.cursor() operation = 'SELECT 1; UPDATE t1 SET c1 = 2; SELECT 2' for result in cursor.execute(operation, multi=True): if result.with_rows: result.fetchall() else: print("Updated row(s): {}".format(result.rowcount))  File: manual.info, Node: connector-python-api-mysqlcursorbuffered, Next: connector-python-api-mysqlcursorprepared, Prev: connector-python-api-mysqlcursor, Up: connector-python-reference 21.6.8.81 Class `cursor.MySQLCursorBuffered' ............................................ This class inherits from `cursor.MySQLCursor' and, if needed, automatically retrieves rows after an operation has been executed. `MySQLCursorBuffered' can be useful in situations where two queries, with small result sets, need to be combined or computed with each other. You can either use the `buffered' argument when using the connection's *Note `cursor()': connector-python-api-mysqlconnection-cursor. method, or you can use the `buffered' *Note connection option: connector-python-connectargs. to make all cursors created for the connection buffering by default. import mysql.connector cnx = mysql.connector.connect() # Only this particular cursor will buffer results cnx.cursor(buffered=True) # All cursors will be buffering by default cnx2 = mysql.connector.connect(buffered=True) For a practical use case, see *Note connector-python-tutorial-cursorbuffered::.  File: manual.info, Node: connector-python-api-mysqlcursorprepared, Next: connector-python-api-clientflag, Prev: connector-python-api-mysqlcursorbuffered, Up: connector-python-reference 21.6.8.82 Class `cursor.MySQLCursorPrepared' ............................................ One way to execute a prepared SQL statement is by use of the `PREPARE' and `EXECUTE' statements. However, to repeatedly execute the same statement with different data for different executions, it is more efficient to use the binary client/server protocol to send and receive data. For information about this protocol, see *Note c-api-prepared-statements::. The `MySQLCursorPrepared' class enables within Connector/Python execution of prepared statements using the binary protocol. This class inherits from `cursor.MySQLCursor'. To create an instance of the `MySQLCursorPrepared' class, use the `cursor_class' argument to the `cursor()' method: import mysql.connector from mysql.connector.cursor import MySQLCursorPrepared cnx = mysql.connector.connect(database='employees') cursor = cnx.cursor(cursor_class=MySQLCursorPrepared) The `cursor()' method of the connection object returns a `MySQLCursorPrepared' object when called with a `cursor_class=MySQLCursorPrepared' argument. A cursor instantiated from the `MySQLCursorPrepared' class works like this: * The first time you pass a statement to the cursor's `execute()' method, it prepares the statement. For subsequent invocations of `execute()', the prepare phase is skipped if the statement is the same. * The `execute()' method takes an optional second argument containing a list of data values to associate with parameter markers in the statement. If the list argument is present, there must be one value per parameter marker. Example: cursor = cnx.cursor(cursor_class=MySQLCursorPrepared) stmt = "SELECT fullname FROM employees WHERE id = ?" # (1) cursor.execute(stmt, (5,)) # (2) # ... fetch data ... cursor.execute(stmt, (10,)) # (3) # ... fetch data ... 1. The `?' within the statement is a parameter marker. Do not put quote marks around parameter markers. 2. For the first call to the `execute()' method, the cursor prepares the statement. If data is given in the same call, it also executes the statement and you should fetch the data. 3. For subsequent `execute()' calls that pass the same SQL statement, the cursor skips the prepare phase. Prepared statements executed with `MySQLCursorPrepared' can use the `format' or `qmark' parameterization style. This differs from nonprepared statements executed with `MySQLCursor', which can use the `format' or `pyformat' parameterization style. To use multiple prepared statements simultaneously, instantiate multiple cursors from the `MySQLCursorPrepared' class. The `MySQLCursorPrepared' class is available as of Connector/Python 1.1.0.  File: manual.info, Node: connector-python-api-clientflag, Next: connector-python-api-fieldtype, Prev: connector-python-api-mysqlcursorprepared, Up: connector-python-reference 21.6.8.83 Class `constants.ClientFlag' ...................................... This class provides constants defining MySQL client flags that can be used when the connection is established to configure the session. The `ClientFlag' class is available when importing `mysql.connector'. >>> import mysql.connector >>> mysql.connector.ClientFlag.FOUND_ROWS 2 See *Note connector-python-api-mysqlconnection-set-client-flags:: and the *Note connection argument: connector-python-connectargs. `client_flag'. The `ClientFlag' class cannot be instantiated.  File: manual.info, Node: connector-python-api-fieldtype, Next: connector-python-api-sqlmode, Prev: connector-python-api-clientflag, Up: connector-python-reference 21.6.8.84 Class `constants.FieldType' ..................................... This class provides all supported MySQL field or data types. They can be useful when dealing with raw data or defining your own converters. The field type is stored with every cursor in the description for each column. The following example shows how to print the name of the data type for each column in a result set. from __future__ import print_function import mysql.connector from mysql.connector import FieldType cnx = mysql.connector.connect(user='scott', database='test') cursor = cnx.cursor() cursor.execute( "SELECT DATE(NOW()) AS `c1`, TIME(NOW()) AS `c2`, " "NOW() AS `c3`, 'a string' AS `c4`, 42 AS `c5`") rows = cursor.fetchall() for desc in cursor.description: colname = desc[0] coltype = desc[1] print("Column {} has type {}".format( colname, FieldType.get_info(coltype))) cursor.close() cnx.close() The `FieldType' class cannot be instantiated.  File: manual.info, Node: connector-python-api-sqlmode, Next: connector-python-api-characterset, Prev: connector-python-api-fieldtype, Up: connector-python-reference 21.6.8.85 Class `constants.SQLMode' ................................... This class provides all known MySQL *Note Server SQL Modes: server-sql-mode. It is mostly used when setting the SQL modes at connection time using the connection's `sql_mode' property. See *Note connector-python-api-mysqlconnection-sql-mode::. The `SQLMode' class cannot be instantiated.  File: manual.info, Node: connector-python-api-characterset, Next: connector-python-api-refreshoption, Prev: connector-python-api-sqlmode, Up: connector-python-reference 21.6.8.86 Class `constants.CharacterSet' ........................................ This class provides all known MySQL characters sets and their default collations. For examples, see *Note connector-python-api-mysqlconnection-set-charset-collation::. The `CharacterSet' class cannot be instantiated.  File: manual.info, Node: connector-python-api-refreshoption, Next: connector-python-api-errors, Prev: connector-python-api-characterset, Up: connector-python-reference 21.6.8.87 Class `constants.RefreshOption' ......................................... This class performs various flush operations. * `RefreshOption.GRANT' Refresh the grant tables, like *Note `FLUSH PRIVILEGES': flush. * `RefreshOption.LOG' Flush the logs, like *Note `FLUSH LOGS': flush. * `RefreshOption.TABLES' Flush the table cache, like *Note `FLUSH TABLES': flush. * `RefreshOption.HOSTS' Flush the host cache, like *Note `FLUSH HOSTS': flush. * `RefreshOption.STATUS' Reset status variables, like *Note `FLUSH STATUS': flush. * `RefreshOption.THREADS' Flush the thread cache. * `RefreshOption.SLAVE' On a slave replication server, reset the master server information and restart the slave, like *Note `RESET SLAVE': reset-slave. * `RefreshOption.MASTER' On a master replication server, remove the binary log files listed in the binary log index and truncate the index file, like *Note `RESET MASTER': reset-master.  File: manual.info, Node: connector-python-api-errors, Prev: connector-python-api-refreshoption, Up: connector-python-reference 21.6.8.88 Errors and Exceptions ............................... * Menu: * connector-python-api-errorcode:: Module `errorcode' * connector-python-api-errors-error:: Exception `errors.Error' * connector-python-api-errors-dataerror:: Exception `errors.DataError' * connector-python-api-errors-databaseerror:: Exception `errors.DatabaseError' * connector-python-api-errors-integrityerror:: Exception `errors.IntegrityError' * connector-python-api-errors-interfaceerror:: Exception `errors.InterfaceError' * connector-python-api-errors-internalerror:: Exception `errors.InternalError' * connector-python-api-errors-notsupportederror:: Exception `errors.NotSupportedError' * connector-python-api-errors-operationalerror:: Exception `errors.OperationalError' * connector-python-api-errors-poolerror:: Exception `errors.PoolError' * connector-python-api-errors-programmingerror:: Exception `errors.ProgrammingError' * connector-python-api-errors-warning:: Exception `errors.Warning' * connector-python-api-errors-custom-error-exception:: Function `errors.custom_error_exception(error=None, exception=None)' The `mysql.connector.errors' module defines exception classes for errors and warnings raised by MySQL Connector/Python. Most classes defined in this module are available when you import `mysql.connector'. The exception classes defined in this module mostly follow the Python Database Specification v2.0 (PEP-249). For some MySQL client or server errors it is not always clear which exception to raise. It is good to discuss whether an error should be reclassified by opening a bug report. MySQL Server errors are mapped with Python exception based on their SQLSTATE value (see *Note error-messages-server::). The following table shows the SQLSTATE classes and the exception Connector/Python raises. It is, however, possible to redefine which exception is raised for each server error. Note that the default exception is `DatabaseError'. ** SQLSTATE Class Connector/Python Exception `02' `DataError' `02' `DataError' `07' `DatabaseError' `08' `OperationalError' `0A' `NotSupportedError' `21' `DataError' `22' `DataError' `23' `IntegrityError' `24' `ProgrammingError' `25' `ProgrammingError' `26' `ProgrammingError' `27' `ProgrammingError' `28' `ProgrammingError' `2A' `ProgrammingError' `2B' `DatabaseError' `2C' `ProgrammingError' `2D' `DatabaseError' `2E' `DatabaseError' `33' `DatabaseError' `34' `ProgrammingError' `35' `ProgrammingError' `37' `ProgrammingError' `3C' `ProgrammingError' `3D' `ProgrammingError' `3F' `ProgrammingError' `40' `InternalError' `42' `ProgrammingError' `44' `InternalError' `HZ' `OperationalError' `XA' `IntegrityError' `0K' `OperationalError' `HY' `DatabaseError'  File: manual.info, Node: connector-python-api-errorcode, Next: connector-python-api-errors-error, Prev: connector-python-api-errors, Up: connector-python-api-errors 21.6.8.89 Module `errorcode' ............................ This module contains both MySQL server and client error codes defined as module attributes with the error number as value. Using error codes instead of error numbers could make reading the source code a bit easier. >>> from mysql.connector import errorcode >>> errorcode.ER_BAD_TABLE_ERROR 1051 See *Note error-messages-server:: and *Note error-messages-client::.  File: manual.info, Node: connector-python-api-errors-error, Next: connector-python-api-errors-dataerror, Prev: connector-python-api-errorcode, Up: connector-python-api-errors 21.6.8.90 Exception `errors.Error' .................................. This exception is the base class for all other exceptions in the `errors' module. It can be used to catch all errors in a single `except' statement. The following example shows how we could catch syntax errors: import mysql.connector try: cnx = mysql.connector.connect(user='scott', database='employees') cursor = cnx.cursor() cursor.execute("SELECT * FORM employees") # Syntax error in query cnx.close() except mysql.connector.Error as err: print("Something went wrong: {}".format(err)) Initializing the exception supports a few optional arguments, namely `msg', `errno', `values' and `sqlstate'. All of them are optional and default to `None'. `errors.Error' is internally used by Connector/Python to raise MySQL client and server errors and should not be used by your application to raise exceptions. The following examples show the result when using no arguments or a combination of the arguments: >>> from mysql.connector.errors import Error >>> str(Error()) 'Unknown error' >>> str(Error("Oops! There was an error.")) 'Oops! There was an error.' >>> str(Error(errno=2006)) '2006: MySQL server has gone away' >>> str(Error(errno=2002, values=('/tmp/mysql.sock', 2))) "2002: Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)" >>> str(Error(errno=1146, sqlstate='42S02', msg="Table 'test.spam' doesn't exist")) "1146 (42S02): Table 'test.spam' doesn't exist" The example which uses error number 1146 is used when Connector/Python receives an error packet from the MySQL Server. The information is parsed and passed to the `Error' exception as shown. Each exception subclassing from `Error' can be initialized using the previously mentioned arguments. Additionally, each instance has the attributes `errno', `msg' and `sqlstate' which can be used in your code. The following example shows how to handle errors when dropping a table which does not exist (when the *Note `DROP TABLE': drop-table. statement does not include a `IF EXISTS' clause): import mysql.connector from mysql.connector import errorcode cnx = mysql.connector.connect(user='scott', database='test') try: cur.execute("DROP TABLE spam") except mysql.connector.Error as err: if err.errno == errorcode.ER_BAD_TABLE_ERROR: print("Creating table spam") else: raise `errors.Error' is a subclass of the Python `StandardError'.  File: manual.info, Node: connector-python-api-errors-dataerror, Next: connector-python-api-errors-databaseerror, Prev: connector-python-api-errors-error, Up: connector-python-api-errors 21.6.8.91 Exception `errors.DataError' ...................................... This exception is raised when there were problems with the data. Examples are a column set to `NULL' that cannot be `NULL', out-of-range values for a column, division by zero, column count does not match value count, and so on. `errors.DataError' is a subclass of `errors.DatabaseError'.  File: manual.info, Node: connector-python-api-errors-databaseerror, Next: connector-python-api-errors-integrityerror, Prev: connector-python-api-errors-dataerror, Up: connector-python-api-errors 21.6.8.92 Exception `errors.DatabaseError' .......................................... This exception is the default for any MySQL error which does not fit the other exceptions. `errors.DatabaseError' is a subclass of `errors.Error'.  File: manual.info, Node: connector-python-api-errors-integrityerror, Next: connector-python-api-errors-interfaceerror, Prev: connector-python-api-errors-databaseerror, Up: connector-python-api-errors 21.6.8.93 Exception `errors.IntegrityError' ........................................... This exception is raised when the relational integrity of the data is affected. For example, a duplicate key was inserted or a foreign key constraint would fail. The following example shows a duplicate key error raised as IntegrityError: cursor.execute("CREATE TABLE t1 (id int, PRIMARY KEY (id))") try: cursor.execute("INSERT INTO t1 (id) VALUES (1)") cursor.execute("INSERT INTO t1 (id) VALUES (1)") except mysql.connector.IntegrityError as err: print("Error: {}".format(err)) `errors.IntegrityError' is a subclass of `errors.DatabaseError'.  File: manual.info, Node: connector-python-api-errors-interfaceerror, Next: connector-python-api-errors-internalerror, Prev: connector-python-api-errors-integrityerror, Up: connector-python-api-errors 21.6.8.94 Exception `errors.InterfaceError' ........................................... This exception is raised for errors originating from Connector/Python itself, not related to the MySQL server. `errors.InterfaceError' is a subclass of `errors.Error'.  File: manual.info, Node: connector-python-api-errors-internalerror, Next: connector-python-api-errors-notsupportederror, Prev: connector-python-api-errors-interfaceerror, Up: connector-python-api-errors 21.6.8.95 Exception `errors.InternalError' .......................................... This exception is raised when the MySQL server encounters an internal error, for example, when a deadlock occurred. `errors.InternalError' is a subclass of `errors.DatabaseError'.  File: manual.info, Node: connector-python-api-errors-notsupportederror, Next: connector-python-api-errors-operationalerror, Prev: connector-python-api-errors-internalerror, Up: connector-python-api-errors 21.6.8.96 Exception `errors.NotSupportedError' .............................................. This exception is raised when some feature was used that is not supported by the version of MySQL that returned the error. It is also raised when using functions or statements that are not supported by stored routines. `errors.NotSupportedError' is a subclass of `errors.DatabaseError'.  File: manual.info, Node: connector-python-api-errors-operationalerror, Next: connector-python-api-errors-poolerror, Prev: connector-python-api-errors-notsupportederror, Up: connector-python-api-errors 21.6.8.97 Exception `errors.OperationalError' ............................................. This exception is raised for errors which are related to MySQL's operations. For example: too many connections; a host name could not be resolved; bad handshake; server is shutting down, communication errors. `errors.OperationalError' is a subclass of `errors.DatabaseError'.  File: manual.info, Node: connector-python-api-errors-poolerror, Next: connector-python-api-errors-programmingerror, Prev: connector-python-api-errors-operationalerror, Up: connector-python-api-errors 21.6.8.98 Exception `errors.PoolError' ...................................... This exception is raised for connection pool errors. `errors.PoolError' is a subclass of `errors.Error'.  File: manual.info, Node: connector-python-api-errors-programmingerror, Next: connector-python-api-errors-warning, Prev: connector-python-api-errors-poolerror, Up: connector-python-api-errors 21.6.8.99 Exception `errors.ProgrammingError' ............................................. This exception is raised on programming errors, for example when you have a syntax error in your SQL or a table was not found. The following example shows how to handle syntax errors: try: cursor.execute("CREATE DESK t1 (id int, PRIMARY KEY (id))") except mysql.connector.ProgrammingError as err: if err.errno == errorcode.ER_SYNTAX_ERROR: print("Check your syntax!") else: print("Error: {}".format(err)) `errors.ProgrammingError' is a subclass of `errors.DatabaseError'.  File: manual.info, Node: connector-python-api-errors-warning, Next: connector-python-api-errors-custom-error-exception, Prev: connector-python-api-errors-programmingerror, Up: connector-python-api-errors 21.6.8.100 Exception `errors.Warning' ..................................... This exception is used for reporting important warnings, however, Connector/Python does not use it. It is included to be compliant with the Python Database Specification v2.0 (PEP-249). Consider using either more strict *Note Server SQL Modes: server-sql-mode. or the *Note raise_on_warnings: connector-python-connectargs. connection argument to make Connector/Python raise errors when your queries produce warnings. `errors.Warning' is a subclass of the Python `StandardError'.  File: manual.info, Node: connector-python-api-errors-custom-error-exception, Prev: connector-python-api-errors-warning, Up: connector-python-api-errors 21.6.8.101 Function `errors.custom_error_exception(error=None, exception=None)' ............................................................................... This method defines custom exceptions for MySQL server errors and returns current customizations. If `error' is a MySQL Server error number, you must also pass the `exception' class. The `error' argument can be a dictionary, in which case the key is the server error number, and value the class of the exception to be raised. To reset the customizations, supply an empty dictionary. import mysql.connector from mysql.connector import errorcode # Server error 1028 should raise a DatabaseError mysql.connector.custom_error_exception(1028, mysql.connector.DatabaseError) # Or using a dictionary: mysql.connector.custom_error_exception({ 1028: mysql.connector.DatabaseError, 1029: mysql.connector.OperationalError, }) # To reset, pass an empty dictionary: mysql.connector.custom_error_exception({})  File: manual.info, Node: libmysqld, Next: c-api, Prev: connector-python, Up: connectors-apis 21.7 libmysqld, the Embedded MySQL Server Library ================================================= * Menu: * libmysqld-compiling:: Compiling Programs with `libmysqld' * libmysqld-restrictions:: Restrictions When Using the Embedded MySQL Server * libmysqld-options:: Options with the Embedded Server * libmysqld-example:: Embedded Server Examples 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. 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 an old threaded application to use the embedded library, you normally only have to add calls to the following functions. *MySQL Embedded Server Library Functions* This table lists MySQL embedded server library functions and describes when the functions should be called. Function When to Call *Note Call it before any other MySQL function is called, `mysql_library_init()':preferably early in the `main()' function. mysql-library-init. *Note Call it before your program exits. `mysql_library_end()': mysql-library-end. *Note Call it in each thread you create that accesses `mysql_thread_init()': MySQL. mysql-thread-init. *Note Call it before calling `pthread_exit()'. `mysql_thread_end()': mysql-thread-end. Then you must link your code with `libmysqld.a' instead of `libmysqlclient.a'. To ensure binary compatibility between your application and the server library, be sure to 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 4.1 headers, do not compile your application against MySQL 5.1 headers, or vice versa. The `mysql_library_XXX()' functions are also included in `libmysqlclient.a' to enable you to change between the embedded and the client/server version by just linking your application with the right library. See *Note 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. To use authentication for the embedded server, specify the `--with-embedded-privilege-control' option when you invoke `configure' to configure your MySQL distribution.  File: manual.info, Node: libmysqld-compiling, Next: libmysqld-restrictions, Prev: libmysqld, Up: libmysqld 21.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 `--with-embedded-server' option. See *Note 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 *Note `mysql_config --libmysqld-libs': mysql-config. 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 -lz \ `/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. Because of a problem with *Note `mysql_config': mysql-config, the option `-lz' (for compression) is added here. The *Note `mysql_config': 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.  File: manual.info, Node: libmysqld-restrictions, Next: libmysqld-options, Prev: libmysqld-compiling, Up: libmysqld 21.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. Some of these limitations can be changed by editing the `mysql_embed.h' include file and recompiling MySQL.  File: manual.info, Node: libmysqld-options, Next: libmysqld-example, Prev: libmysqld-restrictions, Up: libmysqld 21.7.3 Options with the Embedded Server --------------------------------------- Any options that may be given with the *Note `mysqld': mysqld. server daemon, may be used with an embedded server library. Server options may be given in an array as an argument to the *Note `mysql_library_init()': 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 *Note `mysql_library_init()': mysql-library-init. function. See *Note mysql-library-init::, for more information on the *Note `mysql_library_init()': 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 *Note option-files::.  File: manual.info, Node: libmysqld-example, Prev: libmysqld-options, Up: libmysqld 21.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 #include #include #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 -lz \ `/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 #include #include #include 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.1/include #lib := $(HOME)/mysql-5.1/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 -lz -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  File: manual.info, Node: c-api, Next: apis-php, Prev: libmysqld, Up: connectors-apis 21.8 MySQL C API ================ * Menu: * c-api-implementations:: MySQL C API Implementations * c-api-multiple-installations:: Simultaneous MySQL Server and MySQL Connector/C Installations * c-api-example-programs:: Example C API Client Programs * c-api-building-running-clients:: Building and Running C API Client Programs * c-api-data-structures:: C API Data Structures * c-api-function-overview:: C API Function Overview * c-api-functions:: C API Function Descriptions * c-api-prepared-statements:: C API Prepared Statements * c-api-prepared-statement-data-structures:: C API Prepared Statement Data Structures * c-api-prepared-statement-function-overview:: C API Prepared Statement Function Overview * c-api-prepared-statement-functions:: C API Prepared Statement Function Descriptions * c-api-thread-functions:: C API Threaded Function Descriptions * c-api-embedded-server-functions:: C API Embedded Server Function Descriptions * c-api-problems:: Common Questions and Problems When Using the C API * auto-reconnect:: Controlling Automatic Reconnection Behavior * c-api-multiple-queries:: C API Support for Multiple Statement Execution * c-api-prepared-statement-problems:: C API Prepared Statement Problems * c-api-prepared-statement-date-handling:: C API Prepared Statement Handling of Date and Time Values * c-api-prepared-call-statements:: C API Support for Prepared `CALL' Statements 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 *Note c-api-implementations::. Most other client APIs use the `libmysqlclient' library to communicate with the MySQL server. (Exceptions are except 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 *Note programs-overview::. For instructions on building client programs using the C API, see *Note c-api-building-clients::. For programming with threads, see *Note 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 *Note 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 *Note 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 *Note `BLOB': 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 *Note server-parameters::. 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.  File: manual.info, Node: c-api-implementations, Next: c-api-multiple-installations, Prev: c-api, Up: c-api 21.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. 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 MySQL Connector/C distribution. Connector/C distributions include only `libmysqlclient'. They do not include `libmysqld'. For both MySQL Server and MySQL 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 MySQL Connector/C distribution, but not both. For information about issues involved with simultaneous MySQL Server and MySQL Connector/C installations, see *Note 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 Mac 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.  File: manual.info, Node: c-api-multiple-installations, Next: c-api-example-programs, Prev: c-api-implementations, Up: c-api 21.8.2 Simultaneous MySQL Server and MySQL Connector/C Installations -------------------------------------------------------------------- MySQL Server and MySQL 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 *Note c-api-building-clients::, and *Note 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 MySQL 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 MySQL Connector/C installers do not conflict. Mac 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 MySQL 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 MySQL Connector/C RPM packages. These RPM package types cannot coexist because the MySQL Server and MySQL 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 MySQL Connector/C RPM packages. To install the MySQL Connector/C packages anyway, you must first remove the corresponding MySQL Server packages. * To install MySQL Server RPM packages if you already have MySQL Connector/C RPM packages installed, you must first remove the MySQL Connector/C RPM packages. MySQL Server RPM packages other than `shared' and `devel' do not conflict with MySQL Connector/C packages and can be installed if MySQL Connector/C is installed. This includes the main server RPM that includes the *Note `mysqld': mysqld. server itself.  File: manual.info, Node: c-api-example-programs, Next: c-api-building-running-clients, Prev: c-api-multiple-installations, Up: c-api 21.8.3 Example C API Client Programs ------------------------------------ Many of the clients in MySQL source distributions are written in C, such as *Note `mysql': mysql, *Note `mysqladmin': mysqladmin, and *Note `mysqlshow': 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 *Note getting-mysql::.  File: manual.info, Node: c-api-building-running-clients, Next: c-api-data-structures, Prev: c-api-example-programs, Up: c-api 21.8.4 Building and Running C API Client Programs ------------------------------------------------- * Menu: * c-api-building-clients:: Building C API Client Programs * c-api-threaded-clients:: Writing C API Threaded Client Programs * c-api-running-clients:: 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.  File: manual.info, Node: c-api-building-clients, Next: c-api-threaded-clients, Prev: c-api-building-running-clients, Up: c-api-building-running-clients 21.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 * 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 -lz' options 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 -lz 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 *Note `mysql_config': mysql-config. script. See *Note mysql-config::. *Note `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 *Note `mysql_config': 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` * Compiling MySQL Clients on Microsoft Windows * To specify header and library file locations, use the facilities provided by your development environment. On Windows, you can link your code with either the dynamic or static C client library. 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 you link with the static library, failure can occur unless these conditions are satisfied: * The client application must be compiled with the same version of Visual Studio used to compile the library. * The client application should link the C runtime statically by using the `/MT' compiler option. If the client application is built in in debug mode and uses the static debug C runtime (`/MTd' compiler option), it can link to the `mysqlclient.lib' static library if that library was built using the same option. If the client application uses the dynamic C runtime (`/MD' option, or `/MDd' option in debug mode), it must must be linked to the `libmysql.dll' dynamic library. It cannot link to the static client library. The MSDN page describing the link options can be found here: `http://msdn.microsoft.com/en-us/library/2kzt1wy3.aspx' * Troubleshooting Problems Linking to the MySQL Client Library * Linking with the single-threaded library (`libmysqlclient') may lead to linker errors related to `pthread' symbols. When using the single-threaded library, please compile your client with `MYSQL_CLIENT_NO_THREADS' defined. This can be done on the command line by using the `-D' option to the compiler, or in your source code before including the MySQL header files. This define should not be used when building for use with the thread-safe client library (`libmysqlclient_r'). 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 *Note `mysql_config': mysql-config. might indicate other libraries that should be specified on the link command as well. You can include *Note `mysql_config': 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. If you get `undefined reference' errors for the `uncompress' or `compress' function, add `-lz' to the end of your link command and try again. 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 don't 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 MySQL Connector/C source distribution and compile the MySQL client library yourself. See *Note source-installation::, and *Note connector-c::.  File: manual.info, Node: c-api-threaded-clients, Next: c-api-running-clients, Prev: c-api-building-clients, Up: c-api-building-running-clients 21.8.4.2 Writing C API Threaded Client Programs ............................................... The client library is almost thread-safe. The biggest problem is that the subroutines in `net.c' 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 *Note `mysql_library_init()': mysql-library-init, *Note `mysql_init()': mysql-init, or *Note `mysql_connect()': mysql-connect. To use your own `SIGPIPE' handler, first call *Note `mysql_library_init()': mysql-library-init, then install your handler. Current binary distributions should have both a normal client library, `libmysqlclient', and a thread-safe library, `libmysqlclient_r'. For threaded clients, link against the latter library. If `undefined symbol' errors occur, in most cases this is because you have not included the thread libraries on the link/compile command. The thread-safe client library, `libmysqlclient_r', 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 *Note `mysql_query()': mysql-query. and *Note `mysql_store_result()': mysql-store-result. in one thread, no other thread uses the same connection. You must have a mutex lock around your pair of *Note `mysql_query()': mysql-query. and *Note `mysql_store_result()': mysql-store-result. calls. After *Note `mysql_store_result()': 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 *Note `mysql_store_result()': mysql-store-result. * To use *Note `mysql_use_result()': 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 *Note `mysql_store_result()': 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 *Note `mysql_init()': 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 *Note `mysql_init()': 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 *Note `mysql_library_init()': 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 *Note `mysql_thread_init()': mysql-thread-init. to be called early in the thread handler before calling any MySQL function. If you call *Note `mysql_init()': mysql-init, it will call *Note `mysql_thread_init()': mysql-thread-init. for you. 3. In the thread, call *Note `mysql_thread_end()': mysql-thread-end. before calling `pthread_exit()'. This frees the memory used by MySQL thread-specific variables. The preceding notes regarding *Note `mysql_init()': mysql-init. also apply to *Note `mysql_connect()': mysql-connect, which calls *Note `mysql_init()': mysql-init.  File: manual.info, Node: c-api-running-clients, Prev: c-api-threaded-clients, Up: c-api-building-running-clients 21.8.4.3 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 Mac 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. Another way to solve this problem is by linking your program statically with the `-static' option, or by removing the dynamic MySQL libraries before linking your code. Before trying the second method, you should be sure that no other programs are using the dynamic libraries.  File: manual.info, Node: c-api-data-structures, Next: c-api-function-overview, Prev: c-api-building-running-clients, Up: c-api 21.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 *Note c-api-prepared-statement-data-structures::. * `MYSQL' This structure represents a handle to 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 (*Note `SELECT': select, *Note `SHOW': show, *Note `DESCRIBE': describe, *Note `EXPLAIN': 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 *Note `mysql_fetch_row()': 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 *Note `mysql_fetch_field()': 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 *Note `mysql_field_seek()': 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 *Note `mysql_affected_rows()': mysql-affected-rows, *Note `mysql_num_rows()': mysql-num-rows, and *Note `mysql_insert_id()': mysql-insert-id. This type provides a range of `0' to `1.84e19'. 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: * `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. * `char * org_name' The name of the field, as a null-terminated string. Aliases are ignored. For expressions, the value is an empty string. * `char * table' The name of the table containing this field, if it isn't 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 *Note `UNION': union, the value is the empty string. * `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. For a *Note `UNION': union, the value is the empty string. * `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 *Note `UNION': union, the value is the empty string. * `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 *Note `mysql_list_fields()': 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 *Note `mysql_store_result()': mysql-store-result. or *Note `mysql_list_fields()': mysql-list-fields, this contains the maximum length for the field. If you use *Note `mysql_use_result()': 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 *Note `FLOAT': floating-point-types. 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 *Note c-api-prepared-statement-data-structures::.) If you want the `max_length' values anyway, enable the `STMT_ATTR_UPDATE_MAX_LENGTH' option with *Note `mysql_stmt_attr_set()': mysql-stmt-attr-set. and the lengths will be set when you call *Note `mysql_stmt_store_result()': mysql-stmt-store-result. (See *Note mysql-stmt-attr-set::, and *Note 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. This table lists bit-flag values and provides a description of each flag. Flag Value Flag Description `NOT_NULL_FLAG' Field can't 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 *Note `ENUM': enum. `SET_FLAG' Field is a *Note `SET': set. `BLOB_FLAG' Field is a *Note `BLOB': blob. or *Note `TEXT': blob. (deprecated) `TIMESTAMP_FLAG' Field is a *Note `TIMESTAMP': datetime. (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 *Note `BLOB': blob. or *Note `TIMESTAMP': datetime. values, check whether `type' is `MYSQL_TYPE_BLOB' or `MYSQL_TYPE_TIMESTAMP'. (The `BLOB_FLAG' and `TIMESTAMP_FLAG' flags are unneeded.) * *Note `ENUM': enum. and *Note `SET': 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_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 can't be null\n"); You may use the convenience macros shown in the following table to determine the boolean status of the `flags' value. This table lists flag status values and provides a description of each. 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 *Note `BLOB': blob. or *Note `TEXT': blob. (deprecated; test `field->type' instead) * `unsigned int decimals' The number of decimals for numeric 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 *Note 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 *Note `BINARY': binary-varbinary. from *Note `CHAR': char, *Note `VARBINARY': binary-varbinary. from *Note `VARCHAR': char, and the *Note `BLOB': blob. types from the *Note `TEXT': blob. types. `charsetnr' values are the same as those displayed in the `Id' column of the *Note `SHOW COLLATION': show-collation. statement or the `ID' column of the `INFORMATION_SCHEMA' *Note `COLLATIONS': collations-table. 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. This table lists `MYSQL_TYPE_' values and provides a description of each type. Type Value Type Description `MYSQL_TYPE_TINY' *Note `TINYINT': integer-types. field `MYSQL_TYPE_SHORT' *Note `SMALLINT': integer-types. field `MYSQL_TYPE_LONG' *Note `INTEGER': integer-types. field `MYSQL_TYPE_INT24' *Note `MEDIUMINT': integer-types. field `MYSQL_TYPE_LONGLONG' *Note `BIGINT': integer-types. field `MYSQL_TYPE_DECIMAL' *Note `DECIMAL': fixed-point-types. or *Note `NUMERIC': fixed-point-types. field `MYSQL_TYPE_NEWDECIMAL' Precision math *Note `DECIMAL': fixed-point-types. or *Note `NUMERIC': fixed-point-types. `MYSQL_TYPE_FLOAT' *Note `FLOAT': floating-point-types. field `MYSQL_TYPE_DOUBLE' *Note `DOUBLE': floating-point-types. or *Note `REAL': floating-point-types. field `MYSQL_TYPE_BIT' *Note `BIT': bit-type. field `MYSQL_TYPE_TIMESTAMP' *Note `TIMESTAMP': datetime. field `MYSQL_TYPE_DATE' *Note `DATE': datetime. field `MYSQL_TYPE_TIME' *Note `TIME': time. field `MYSQL_TYPE_DATETIME' *Note `DATETIME': datetime. field `MYSQL_TYPE_YEAR' *Note `YEAR': year. field `MYSQL_TYPE_STRING' *Note `CHAR': char. or *Note `BINARY': binary-varbinary. field `MYSQL_TYPE_VAR_STRING' *Note `VARCHAR': char. or *Note `VARBINARY': binary-varbinary. field `MYSQL_TYPE_BLOB' *Note `BLOB': blob. or *Note `TEXT': blob. field (use `max_length' to determine the maximum length) `MYSQL_TYPE_SET' *Note `SET': set. field `MYSQL_TYPE_ENUM' *Note `ENUM': enum. field `MYSQL_TYPE_GEOMETRY' Spatial field `MYSQL_TYPE_NULL' `NULL'-type field 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"); *Note `ENUM': enum. and *Note `SET': 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.  File: manual.info, Node: c-api-function-overview, Next: c-api-functions, Prev: c-api-data-structures, Up: c-api 21.8.6 C API Function Overview ------------------------------ The functions available in the C API are summarized here and described in greater detail in a later section. See *Note c-api-functions::. *C API Function Names and Descriptions* Function Description *Note `my_init()': Initialize global variables, and thread handler my-init. in thread-safe programs *Note Returns the number of rows `mysql_affected_rows()':changed/deleted/inserted by the last *Note mysql-affected-rows. `UPDATE': update, *Note `DELETE': delete, or *Note `INSERT': insert. query *Note Toggles autocommit mode on/off `mysql_autocommit()': mysql-autocommit. *Note Changes user and database on an open connection `mysql_change_user()': mysql-change-user. *Note Return default character set name for current `mysql_character_set_name()':connection mysql-character-set-name. *Note `mysql_close()': Closes a server connection mysql-close. *Note Commits the transaction `mysql_commit()': mysql-commit. *Note Connects to a MySQL server (this function is `mysql_connect()': deprecated; use *Note `mysql_real_connect()': mysql-connect. mysql-real-connect. instead) *Note Creates a database (this function is deprecated; `mysql_create_db()': use the SQL statement *Note `CREATE DATABASE': mysql-create-db. create-database. instead) *Note Seeks to an arbitrary row number in a query `mysql_data_seek()': result set mysql-data-seek. *Note `mysql_debug()': Does a `DBUG_PUSH' with the given string mysql-debug. *Note Drops a database (this function is deprecated; `mysql_drop_db()': use the SQL statement *Note `DROP DATABASE': mysql-drop-db. drop-database. instead) *Note Makes the server write debug information to the `mysql_dump_debug_info()':log mysql-dump-debug-info. *Note `mysql_eof()': Determines whether the last row of a result set mysql-eof. has been read (this function is deprecated; *Note `mysql_errno()': mysql-errno. or *Note `mysql_error()': mysql-error. may be used instead) *Note `mysql_errno()': Returns the error number for the most recently mysql-errno. invoked MySQL function *Note `mysql_error()': Returns the error message for the most recently mysql-error. invoked MySQL function *Note Escapes special characters in a string for use `mysql_escape_string()':in an SQL statement mysql-escape-string. *Note Returns the type of the next table field `mysql_fetch_field()': mysql-fetch-field. *Note Returns the type of a table field, given a field `mysql_fetch_field_direct()':number mysql-fetch-field-direct. *Note Returns an array of all field structures `mysql_fetch_fields()': mysql-fetch-fields. *Note Returns the lengths of all columns in the `mysql_fetch_lengths()':current row mysql-fetch-lengths. *Note Fetches the next row from the result set `mysql_fetch_row()': mysql-fetch-row. *Note Returns the number of result columns for the `mysql_field_count()': most recent statement mysql-field-count. *Note Puts the column cursor on a specified column `mysql_field_seek()': mysql-field-seek. *Note Returns the position of the field cursor used `mysql_field_tell()': for the last *Note `mysql_fetch_field()': mysql-field-tell. mysql-fetch-field. *Note Frees memory used by a result set `mysql_free_result()': mysql-free-result. *Note Return information about default character set `mysql_get_character_set_info()': mysql-get-character-set-info. *Note Returns client version information as a string `mysql_get_client_info()': mysql-get-client-info. *Note Returns client version information as an integer `mysql_get_client_version()': mysql-get-client-version. *Note Returns a string describing the connection `mysql_get_host_info()': mysql-get-host-info. *Note Returns the protocol version used by the `mysql_get_proto_info()':connection mysql-get-proto-info. *Note Returns the server version number `mysql_get_server_info()': mysql-get-server-info. *Note Returns version number of server as an integer `mysql_get_server_version()': mysql-get-server-version. *Note Return current SSL cipher `mysql_get_ssl_cipher()': mysql-get-ssl-cipher. *Note Encode string in hexadecimal format `mysql_hex_string()': mysql-hex-string. *Note `mysql_info()': Returns information about the most recently mysql-info. executed query *Note `mysql_init()': Gets or initializes a `MYSQL' structure mysql-init. *Note Returns the ID generated for an `AUTO_INCREMENT' `mysql_insert_id()': column by the previous query mysql-insert-id. *Note `mysql_kill()': Kills a given thread mysql-kill. *Note Finalize the MySQL C API library `mysql_library_end()': mysql-library-end. *Note Initialize the MySQL C API library `mysql_library_init()': mysql-library-init. *Note Returns database names matching a simple regular `mysql_list_dbs()': expression mysql-list-dbs. *Note Returns field names matching a simple regular `mysql_list_fields()': expression mysql-list-fields. *Note Returns a list of the current server threads `mysql_list_processes()': mysql-list-processes. *Note Returns table names matching a simple regular `mysql_list_tables()': expression mysql-list-tables. *Note Checks whether any more results exist `mysql_more_results()': mysql-more-results. *Note Returns/initiates the next result in `mysql_next_result()': multiple-result executions mysql-next-result. *Note Returns the number of columns in a result set `mysql_num_fields()': mysql-num-fields. *Note Returns the number of rows in a result set `mysql_num_rows()': mysql-num-rows. *Note Sets connect options for *Note `mysql_options()': `mysql_real_connect()': mysql-real-connect. mysql-options. *Note `mysql_ping()': Checks whether the connection to the server is mysql-ping. working, reconnecting as necessary *Note `mysql_query()': Executes an SQL query specified as a mysql-query. null-terminated string *Note Connects to a MySQL server `mysql_real_connect()': mysql-real-connect. *Note Escapes special characters in a string for use `mysql_real_escape_string()':in an SQL statement, taking into account the mysql-real-escape-string.current character set of the connection *Note Executes an SQL query specified as a counted `mysql_real_query()': string mysql-real-query. *Note Flush or reset tables and caches `mysql_refresh()': mysql-refresh. *Note Tells the server to reload the grant tables `mysql_reload()': mysql-reload. *Note Rolls back the transaction `mysql_rollback()': mysql-rollback. *Note Seeks to a row offset in a result set, using `mysql_row_seek()': value returned from *Note `mysql_row_tell()': mysql-row-seek. mysql-row-tell. *Note Returns the row cursor position `mysql_row_tell()': mysql-row-tell. *Note Selects a database `mysql_select_db()': mysql-select-db. *Note Finalize the MySQL C API library `mysql_server_end()': mysql-server-end. *Note Initialize the MySQL C API library `mysql_server_init()': mysql-server-init. *Note Set default character set for current connection `mysql_set_character_set()': mysql-set-character-set. *Note Set the *Note `LOAD DATA LOCAL INFILE': `mysql_set_local_infile_default()':load-data. handler callbacks to their default mysql-set-local-infile-default.values *Note Install application-specific *Note `LOAD DATA `mysql_set_local_infile_handler()':LOCAL INFILE': load-data. handler callbacks mysql-set-local-infile-handler. *Note Sets an option for the connection (like `mysql_set_server_option()':`multi-statements') mysql-set-server-option. *Note Returns the SQLSTATE error code for the last `mysql_sqlstate()': error mysql-sqlstate. *Note Shuts down the database server `mysql_shutdown()': mysql-shutdown. *Note Prepare to establish SSL connection to server `mysql_ssl_set()': mysql-ssl-set. *Note `mysql_stat()': Returns the server status as a string mysql-stat. *Note Retrieves a complete result set to the client `mysql_store_result()': mysql-store-result. *Note Finalize thread handler `mysql_thread_end()': mysql-thread-end. *Note Returns the current thread ID `mysql_thread_id()': mysql-thread-id. *Note Initialize thread handler `mysql_thread_init()': mysql-thread-init. *Note Returns 1 if the clients are compiled as `mysql_thread_safe()': thread-safe mysql-thread-safe. *Note Initiates a row-by-row result set retrieval `mysql_use_result()': mysql-use-result. *Note Returns the warning count for the previous SQL `mysql_warning_count()':statement mysql-warning-count. Application programs should use this general outline for interacting with MySQL: 1. Initialize the MySQL library by calling *Note `mysql_library_init()': 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 *Note `mysql_init()': mysql-init. and connect to the server by calling *Note `mysql_real_connect()': 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 *Note `mysql_close()': mysql-close. 5. End use of the MySQL library by calling *Note `mysql_library_end()': mysql-library-end. The purpose of calling *Note `mysql_library_init()': mysql-library-init. and *Note `mysql_library_end()': mysql-library-end. is to provide proper initialization and finalization of the MySQL library. For applications that are linked with the client library, they provide improved memory management. If you don't call *Note `mysql_library_end()': 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 *Note `mysql_library_init()': mysql-library-init. may be omitted, because *Note `mysql_init()': mysql-init. will invoke it automatically as necessary. However, *Note `mysql_library_init()': mysql-library-init. is not thread-safe in a multi-threaded environment, and thus neither is *Note `mysql_init()': mysql-init, which calls *Note `mysql_library_init()': mysql-library-init. You must either call *Note `mysql_library_init()': mysql-library-init. prior to spawning any threads, or else use a mutex to protect the call, whether you invoke *Note `mysql_library_init()': mysql-library-init. or indirectly through *Note `mysql_init()': mysql-init. This should be done prior to any other client library call. To connect to the server, call *Note `mysql_init()': mysql-init. to initialize a connection handler, then call *Note `mysql_real_connect()': mysql-real-connect. with that handler (along with other information such as the host name, user name, and password). Upon connection, *Note `mysql_real_connect()': 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 *Note `mysql_options()': mysql-options. to control reconnection behavior. When you are done with the connection, call *Note `mysql_close()': mysql-close. to terminate it. While a connection is active, the client may send SQL statements to the server using *Note `mysql_query()': mysql-query. or *Note `mysql_real_query()': mysql-real-query. The difference between the two is that *Note `mysql_query()': mysql-query. expects the query to be specified as a null-terminated string whereas *Note `mysql_real_query()': mysql-real-query. expects a counted string. If the string contains binary data (which may include null bytes), you must use *Note `mysql_real_query()': mysql-real-query. For each non-*Note `SELECT': select. query (for example, *Note `INSERT': insert, *Note `UPDATE': update, *Note `DELETE': delete.), you can find out how many rows were changed (affected) by calling *Note `mysql_affected_rows()': mysql-affected-rows. For *Note `SELECT': select. queries, you retrieve the selected rows as a result set. (Note that some statements are *Note `SELECT': select.-like in that they return rows. These include *Note `SHOW': show, *Note `DESCRIBE': describe, and *Note `EXPLAIN': explain. Treat these statements the same way as *Note `SELECT': 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 *Note `mysql_store_result()': 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 *Note `mysql_use_result()': 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 *Note `mysql_fetch_row()': mysql-fetch-row. With *Note `mysql_store_result()': mysql-store-result, *Note `mysql_fetch_row()': mysql-fetch-row. accesses rows that have previously been fetched from the server. With *Note `mysql_use_result()': mysql-use-result, *Note `mysql_fetch_row()': mysql-fetch-row. actually retrieves the row from the server. Information about the size of the data in each row is available by calling *Note `mysql_fetch_lengths()': mysql-fetch-lengths. After you are done with a result set, call *Note `mysql_free_result()': 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 *Note `mysql_store_result()': mysql-store-result. more commonly. An advantage of *Note `mysql_store_result()': 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 *Note `mysql_data_seek()': mysql-data-seek. or *Note `mysql_row_seek()': 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 *Note `mysql_num_rows()': mysql-num-rows. On the other hand, the memory requirements for *Note `mysql_store_result()': 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 *Note `mysql_use_result()': 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, *Note `mysql_use_result()': mysql-use-result. can be faster). Disadvantages are that you must process each row quickly to avoid tying up the server, you don't have random access to rows within the result set (you can only access rows sequentially), and you don't know how many rows are in the result set 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 *Note `SELECT': select. You can do this by calling *Note `mysql_store_result()': mysql-store-result. after each *Note `mysql_query()': mysql-query. (or *Note `mysql_real_query()': mysql-real-query.). If the result set call succeeds, the statement was a *Note `SELECT': select. and you can read the rows. If the result set call fails, call *Note `mysql_field_count()': mysql-field-count. to determine whether a result was actually to be expected. If *Note `mysql_field_count()': mysql-field-count. returns zero, the statement returned no data (indicating that it was an *Note `INSERT': insert, *Note `UPDATE': update, *Note `DELETE': delete, and so forth), and was not expected to return rows. If *Note `mysql_field_count()': mysql-field-count. is nonzero, the statement should have returned rows, but didn't. This indicates that the statement was a *Note `SELECT': select. that failed. See the description for *Note `mysql_field_count()': mysql-field-count. for an example of how this can be done. Both *Note `mysql_store_result()': mysql-store-result. and *Note `mysql_use_result()': 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 *Note `mysql_fetch_field()': mysql-fetch-field. repeatedly, or by field number within the row by calling *Note `mysql_fetch_field_direct()': mysql-fetch-field-direct. The current field cursor position may be changed by calling *Note `mysql_field_seek()': mysql-field-seek. Setting the field cursor affects subsequent calls to *Note `mysql_fetch_field()': mysql-fetch-field. You can also get information for fields all at once by calling *Note `mysql_fetch_fields()': mysql-fetch-fields. For detecting and reporting errors, MySQL provides access to error information by means of the *Note `mysql_errno()': mysql-errno. and *Note `mysql_error()': 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.  File: manual.info, Node: c-api-functions, Next: c-api-prepared-statements, Prev: c-api-function-overview, Up: c-api 21.8.7 C API Function Descriptions ---------------------------------- * Menu: * mysql-affected-rows:: `mysql_affected_rows()' * mysql-autocommit:: `mysql_autocommit()' * mysql-change-user:: `mysql_change_user()' * mysql-character-set-name:: `mysql_character_set_name()' * mysql-close:: `mysql_close()' * mysql-commit:: `mysql_commit()' * mysql-connect:: `mysql_connect()' * mysql-create-db:: `mysql_create_db()' * mysql-data-seek:: `mysql_data_seek()' * mysql-debug:: `mysql_debug()' * mysql-drop-db:: `mysql_drop_db()' * mysql-dump-debug-info:: `mysql_dump_debug_info()' * mysql-eof:: `mysql_eof()' * mysql-errno:: `mysql_errno()' * mysql-error:: `mysql_error()' * mysql-escape-string:: `mysql_escape_string()' * mysql-fetch-field:: `mysql_fetch_field()' * mysql-fetch-field-direct:: `mysql_fetch_field_direct()' * mysql-fetch-fields:: `mysql_fetch_fields()' * mysql-fetch-lengths:: `mysql_fetch_lengths()' * mysql-fetch-row:: `mysql_fetch_row()' * mysql-field-count:: `mysql_field_count()' * mysql-field-seek:: `mysql_field_seek()' * mysql-field-tell:: `mysql_field_tell()' * mysql-free-result:: `mysql_free_result()' * mysql-get-character-set-info:: `mysql_get_character_set_info()' * mysql-get-client-info:: `mysql_get_client_info()' * mysql-get-client-version:: `mysql_get_client_version()' * mysql-get-host-info:: `mysql_get_host_info()' * mysql-get-proto-info:: `mysql_get_proto_info()' * mysql-get-server-info:: `mysql_get_server_info()' * mysql-get-server-version:: `mysql_get_server_version()' * mysql-get-ssl-cipher:: `mysql_get_ssl_cipher()' * mysql-hex-string:: `mysql_hex_string()' * mysql-info:: `mysql_info()' * mysql-init:: `mysql_init()' * mysql-insert-id:: `mysql_insert_id()' * mysql-kill:: `mysql_kill()' * mysql-library-end:: `mysql_library_end()' * mysql-library-init:: `mysql_library_init()' * mysql-list-dbs:: `mysql_list_dbs()' * mysql-list-fields:: `mysql_list_fields()' * mysql-list-processes:: `mysql_list_processes()' * mysql-list-tables:: `mysql_list_tables()' * mysql-more-results:: `mysql_more_results()' * mysql-next-result:: `mysql_next_result()' * mysql-num-fields:: `mysql_num_fields()' * mysql-num-rows:: `mysql_num_rows()' * mysql-options:: `mysql_options()' * mysql-ping:: `mysql_ping()' * mysql-query:: `mysql_query()' * mysql-real-connect:: `mysql_real_connect()' * mysql-real-escape-string:: `mysql_real_escape_string()' * mysql-real-query:: `mysql_real_query()' * mysql-refresh:: `mysql_refresh()' * mysql-reload:: `mysql_reload()' * mysql-rollback:: `mysql_rollback()' * mysql-row-seek:: `mysql_row_seek()' * mysql-row-tell:: `mysql_row_tell()' * mysql-select-db:: `mysql_select_db()' * mysql-set-character-set:: `mysql_set_character_set()' * mysql-set-local-infile-default:: `mysql_set_local_infile_default()' * mysql-set-local-infile-handler:: `mysql_set_local_infile_handler()' * mysql-set-server-option:: `mysql_set_server_option()' * mysql-shutdown:: `mysql_shutdown()' * mysql-sqlstate:: `mysql_sqlstate()' * mysql-ssl-set:: `mysql_ssl_set()' * mysql-stat:: `mysql_stat()' * mysql-store-result:: `mysql_store_result()' * mysql-thread-id:: `mysql_thread_id()' * mysql-use-result:: `mysql_use_result()' * mysql-warning-count:: `mysql_warning_count()' 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 *Note `mysql_errno()': mysql-errno. A string representation of the error may be obtained by calling *Note `mysql_error()': mysql-error.  File: manual.info, Node: mysql-affected-rows, Next: mysql-autocommit, Prev: c-api-functions, Up: c-api-functions 21.8.7.1 `mysql_affected_rows()' ................................ `my_ulonglong mysql_affected_rows(MYSQL *mysql)' * Description * *Note `mysql_affected_rows()': mysql-affected-rows. may be called immediately after executing a statement with *Note `mysql_query()': mysql-query. or *Note `mysql_real_query()': mysql-real-query. It returns the number of rows changed, deleted, or inserted by the last statement if it was an *Note `UPDATE': update, *Note `DELETE': delete, or *Note `INSERT': insert. For *Note `SELECT': select. statements, *Note `mysql_affected_rows()': mysql-affected-rows. works like *Note `mysql_num_rows()': mysql-num-rows. For *Note `UPDATE': update. statements, the affected-rows value by default is the number of rows actually changed. If you specify the `CLIENT_FOUND_ROWS' flag to *Note `mysql_real_connect()': mysql-real-connect. when connecting to *Note `mysqld': mysqld, the affected-rows value is the number of rows `found'; that is, matched by the `WHERE' clause. For *Note `REPLACE': 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 *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. statements, the affected-rows value is 1 if the row is inserted as a new row and 2 if an existing row is updated. Following a *Note `CALL': call. statement for a stored procedure, *Note `mysql_affected_rows()': 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. * Return Values * An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records were updated for an *Note `UPDATE': 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 *Note `SELECT': select. query, *Note `mysql_affected_rows()': mysql-affected-rows. was called prior to calling *Note `mysql_store_result()': mysql-store-result. Because *Note `mysql_affected_rows()': 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));  File: manual.info, Node: mysql-autocommit, Next: mysql-change-user, Prev: mysql-affected-rows, Up: c-api-functions 21.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 if successful. Nonzero if an error occurred. * Errors * None.  File: manual.info, Node: mysql-change-user, Next: mysql-character-set-name, Prev: mysql-autocommit, Up: c-api-functions 21.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 do not include an explicit database specifier. *Note `mysql_change_user()': mysql-change-user. fails if the connected user cannot be authenticated or doesn't have permission to use the database. In this case, the user and database are not changed. The `db' parameter may be set to `NULL' if you don't want to have a default database. This command resets the state as if one had done a new connect. (See *Note auto-reconnect::.) It always performs a *Note `ROLLBACK': commit. 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 *Note `HANDLER': handler. variables are closed. Locks acquired with `GET_LOCK()' are released. These effects occur even if the user didn't change. * Return Values * Zero for success. Nonzero if an error occurred. * Errors * The same that you can get from *Note `mysql_real_connect()': mysql-real-connect. * `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 doesn't implement this command (probably an old server). * `ER_ACCESS_DENIED_ERROR' The user or password was wrong. * `ER_BAD_DB_ERROR' The database didn't 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)); }  File: manual.info, Node: mysql-character-set-name, Next: mysql-close, Prev: mysql-change-user, Up: c-api-functions 21.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.  File: manual.info, Node: mysql-close, Next: mysql-commit, Prev: mysql-character-set-name, Up: c-api-functions 21.8.7.5 `mysql_close()' ........................ `void mysql_close(MYSQL *mysql)' * Description * Closes a previously opened connection. *Note `mysql_close()': mysql-close. also deallocates the connection handle pointed to by `mysql' if the handle was allocated automatically by *Note `mysql_init()': mysql-init. or *Note `mysql_connect()': mysql-connect. * Return Values * None. * Errors * None.  File: manual.info, Node: mysql-commit, Next: mysql-connect, Prev: mysql-close, Up: c-api-functions 21.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 2, the server performs a release after terminating a transaction and closes the client connection. The client program should call *Note `mysql_close()': mysql-close. to close the connection from the client side. * Return Values * Zero if successful. Nonzero if an error occurred. * Errors * None.  File: manual.info, Node: mysql-connect, Next: mysql-create-db, Prev: mysql-commit, Up: c-api-functions 21.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 *Note `mysql_real_connect()': mysql-real-connect. instead. *Note `mysql_connect()': mysql-connect. attempts to establish a connection to a MySQL database engine running on `host'. *Note `mysql_connect()': mysql-connect. must complete successfully before you can execute any of the other API functions, with the exception of *Note `mysql_get_client_info()': mysql-get-client-info. The meanings of the parameters are the same as for the corresponding parameters for *Note `mysql_real_connect()': 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 *Note `mysql_close()': mysql-close. The disadvantage of this approach is that you can't retrieve an error message if the connection fails. (To get error information from *Note `mysql_errno()': mysql-errno. or *Note `mysql_error()': mysql-error, you must provide a valid `MYSQL' pointer.) * Return Values * Same as for *Note `mysql_real_connect()': mysql-real-connect. * Errors * Same as for *Note `mysql_real_connect()': mysql-real-connect.  File: manual.info, Node: mysql-create-db, Next: mysql-data-seek, Prev: mysql-connect, Up: c-api-functions 21.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. It is preferable to use *Note `mysql_query()': mysql-query. to issue an SQL *Note `CREATE DATABASE': create-database. statement instead. * Return Values * Zero if the database was created successfully. 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)); }  File: manual.info, Node: mysql-data-seek, Next: mysql-debug, Prev: mysql-create-db, Up: c-api-functions 21.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 *Note `mysql_num_rows(result)-1': mysql-num-rows. This function requires that the result set structure contains the entire result of the query, so *Note `mysql_data_seek()': mysql-data-seek. may be used only in conjunction with *Note `mysql_store_result()': mysql-store-result, not with *Note `mysql_use_result()': mysql-use-result. * Return Values * None. * Errors * None.  File: manual.info, Node: mysql-debug, Next: mysql-drop-db, Prev: mysql-data-seek, Up: c-api-functions 21.8.7.10 `mysql_debug()' ......................... `void mysql_debug(const char *debug)' * Description * Does a `DBUG_PUSH' with the given string. *Note `mysql_debug()': mysql-debug. uses the Fred Fish debug library. To use this function, you must compile the client library to support debugging. See *Note 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");  File: manual.info, Node: mysql-drop-db, Next: mysql-dump-debug-info, Prev: mysql-debug, Up: c-api-functions 21.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. It is preferable to use *Note `mysql_query()': mysql-query. to issue an SQL *Note `DROP DATABASE': drop-database. statement instead. * Return Values * Zero if the database was dropped successfully. 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));  File: manual.info, Node: mysql-dump-debug-info, Next: mysql-eof, Prev: mysql-drop-db, Up: c-api-functions 21.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 if the command was successful. 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.  File: manual.info, Node: mysql-eof, Next: mysql-errno, Prev: mysql-dump-debug-info, Up: c-api-functions 21.8.7.13 `mysql_eof()' ....................... `my_bool mysql_eof(MYSQL_RES *result)' * Description * This function is deprecated. *Note `mysql_errno()': mysql-errno. or *Note `mysql_error()': mysql-error. may be used instead. *Note `mysql_eof()': 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 *Note `mysql_store_result()': mysql-store-result, the client receives the entire set in one operation. In this case, a `NULL' return from *Note `mysql_fetch_row()': mysql-fetch-row. always means the end of the result set has been reached and it is unnecessary to call *Note `mysql_eof()': mysql-eof. When used with *Note `mysql_store_result()': mysql-store-result, *Note `mysql_eof()': mysql-eof. always returns true. On the other hand, if you use *Note `mysql_use_result()': 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 *Note `mysql_fetch_row()': mysql-fetch-row. repeatedly. Because an error may occur on the connection during this process, a `NULL' return value from *Note `mysql_fetch_row()': mysql-fetch-row. does not necessarily mean the end of the result set was reached normally. In this case, you can use *Note `mysql_eof()': mysql-eof. to determine what happened. *Note `mysql_eof()': mysql-eof. returns a nonzero value if the end of the result set was reached and zero if an error occurred. Historically, *Note `mysql_eof()': mysql-eof. predates the standard MySQL error functions *Note `mysql_errno()': mysql-errno. and *Note `mysql_error()': mysql-error. Because those error functions provide the same information, their use is preferred over *Note `mysql_eof()': mysql-eof, which is deprecated. (In fact, they provide more information, because *Note `mysql_eof()': mysql-eof. returns only a boolean value whereas the error functions indicate a reason for the error when one occurs.) * Return Values * Zero if no error occurred. Nonzero if the end of the result set has been reached. * Errors * None. * Example * The following example shows how you might use *Note `mysql_eof()': 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)); }  File: manual.info, Node: mysql-errno, Next: mysql-error, Prev: mysql-eof, Up: c-api-functions 21.8.7.14 `mysql_errno()' ......................... `unsigned int mysql_errno(MYSQL *mysql)' * Description * For the connection specified by `mysql', *Note `mysql_errno()': 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 *Note error-handling::. Note that some functions like *Note `mysql_fetch_row()': mysql-fetch-row. don't set *Note `mysql_errno()': mysql-errno. if they succeed. A rule of thumb is that all functions that have to ask the server for information reset *Note `mysql_errno()': mysql-errno. if they succeed. MySQL-specific error numbers returned by *Note `mysql_errno()': mysql-errno. differ from SQLSTATE values returned by *Note `mysql_sqlstate()': mysql-sqlstate. For example, the *Note `mysql': mysql. client program displays errors using the following format, where `1146' is the *Note `mysql_errno()': mysql-errno. value and `'42S02'' is the corresponding *Note `mysql_sqlstate()': 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.  File: manual.info, Node: mysql-error, Next: mysql-escape-string, Prev: mysql-errno, Up: c-api-functions 21.8.7.15 `mysql_error()' ......................... `const char *mysql_error(MYSQL *mysql)' * Description * For the connection specified by `mysql', *Note `mysql_error()': mysql-error. returns a null-terminated string containing the error message for the most recently invoked API function that failed. If a function didn't fail, the return value of *Note `mysql_error()': 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 *Note `mysql_error()': mysql-error. if they succeed. For functions that reset *Note `mysql_error()': 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. Currently, you can choose error messages in several different languages. See *Note error-message-language::. * Return Values * A null-terminated character string that describes the error. An empty string if no error occurred. * Errors * None.  File: manual.info, Node: mysql-escape-string, Next: mysql-fetch-field, Prev: mysql-error, Up: c-api-functions 21.8.7.16 `mysql_escape_string()' ................................. Use *Note `mysql_real_escape_string()': mysql-real-escape-string. instead! This function is identical to *Note `mysql_real_escape_string()': mysql-real-escape-string. except that *Note `mysql_real_escape_string()': mysql-real-escape-string. takes a connection handler as its first argument and escapes the string according to the current character set. *Note `mysql_escape_string()': mysql-escape-string. does not take a connection argument and does not respect the current character set.  File: manual.info, Node: mysql-fetch-field, Next: mysql-fetch-field-direct, Prev: mysql-escape-string, Up: c-api-functions 21.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. *Note `mysql_fetch_field()': mysql-fetch-field. returns `NULL' when no more fields are left. *Note `mysql_fetch_field()': mysql-fetch-field. is reset to return information about the first field each time you execute a new *Note `SELECT': select. query. The field returned by *Note `mysql_fetch_field()': mysql-fetch-field. is also affected by calls to *Note `mysql_field_seek()': mysql-field-seek. If you've called *Note `mysql_query()': mysql-query. to perform a *Note `SELECT': select. on a table but have not called *Note `mysql_store_result()': mysql-store-result, MySQL returns the default blob length (8KB) if you call *Note `mysql_fetch_field()': mysql-fetch-field. to ask for the length of a *Note `BLOB': blob. field. (The 8KB size is chosen because MySQL doesn't know the maximum length for the *Note `BLOB': 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); }  File: manual.info, Node: mysql-fetch-field-direct, Next: mysql-fetch-fields, Prev: mysql-fetch-field, Up: c-api-functions 21.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 *Note `mysql_num_fields(result)-1': mysql-num-fields. * 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); }  File: manual.info, Node: mysql-fetch-fields, Next: mysql-fetch-lengths, Prev: mysql-fetch-field-direct, Up: c-api-functions 21.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); }  File: manual.info, Node: mysql-fetch-lengths, Next: mysql-fetch-row, Prev: mysql-fetch-fields, Up: c-api-functions 21.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 *Note `mysql_fetch_row()': mysql-fetch-row. * Return Values * An array of unsigned long integers representing the size of each column (not including any terminating null characters). `NULL' if an error occurred. * Errors * *Note `mysql_fetch_lengths()': mysql-fetch-lengths. is valid only for the current row of the result set. It returns `NULL' if you call it before calling *Note `mysql_fetch_row()': 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]); } }  File: manual.info, Node: mysql-fetch-row, Next: mysql-field-count, Prev: mysql-fetch-lengths, Up: c-api-functions 21.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 *Note `mysql_store_result()': mysql-store-result, *Note `mysql_fetch_row()': mysql-fetch-row. returns `NULL' when there are no more rows to retrieve. When used after *Note `mysql_use_result()': mysql-use-result, *Note `mysql_fetch_row()': 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 *Note `mysql_num_fields(result)': mysql-num-fields. If `row' holds the return value from a call to *Note `mysql_fetch_row()': 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 *Note `mysql_fetch_lengths()': 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 * Note that error is not reset between calls to *Note `mysql_fetch_row()': 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"); }  File: manual.info, Node: mysql-field-count, Next: mysql-field-seek, Prev: mysql-fetch-row, Up: c-api-functions 21.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 *Note `mysql_store_result()': mysql-store-result. returned `NULL' (and thus you have no result set pointer). In this case, you can call *Note `mysql_field_count()': mysql-field-count. to determine whether *Note `mysql_store_result()': 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 *Note `SELECT': select. (or *Note `SELECT': select.-like) statement. The example shown here illustrates how this may be done. See *Note 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 *Note `mysql_field_count(&mysql)': mysql-field-count. call with *Note `mysql_errno(&mysql)': mysql-errno. In this case, you are checking directly for an error from *Note `mysql_store_result()': mysql-store-result. rather than inferring from the value of *Note `mysql_field_count()': mysql-field-count. whether the statement was a *Note `SELECT': select.  File: manual.info, Node: mysql-field-seek, Next: mysql-field-tell, Prev: mysql-field-count, Up: c-api-functions 21.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 *Note `mysql_fetch_field()': 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.  File: manual.info, Node: mysql-field-tell, Next: mysql-free-result, Prev: mysql-field-seek, Up: c-api-functions 21.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 *Note `mysql_fetch_field()': mysql-fetch-field. This value can be used as an argument to *Note `mysql_field_seek()': mysql-field-seek. * Return Values * The current offset of the field cursor. * Errors * None.  File: manual.info, Node: mysql-free-result, Next: mysql-get-character-set-info, Prev: mysql-field-tell, Up: c-api-functions 21.8.7.25 `mysql_free_result()' ............................... `void mysql_free_result(MYSQL_RES *result)' * Description * Frees the memory allocated for a result set by *Note `mysql_store_result()': mysql-store-result, *Note `mysql_use_result()': mysql-use-result, *Note `mysql_list_dbs()': mysql-list-dbs, and so forth. When you are done with a result set, you must free the memory it uses by calling *Note `mysql_free_result()': mysql-free-result. Do not attempt to access a result set after freeing it. * Return Values * None. * Errors * None.  File: manual.info, Node: mysql-get-character-set-info, Next: mysql-get-client-info, Prev: mysql-free-result, Up: c-api-functions 21.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 *Note `mysql_set_character_set()': 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); }  File: manual.info, Node: mysql-get-client-info, Next: mysql-get-client-version, Prev: mysql-get-character-set-info, Up: c-api-functions 21.8.7.27 `mysql_get_client_info()' ................................... `const char *mysql_get_client_info(void)' * Description * Returns a string that represents the client library version. * Return Values * A character string that represents the MySQL client library version. * Errors * None.  File: manual.info, Node: mysql-get-client-version, Next: mysql-get-host-info, Prev: mysql-get-client-info, Up: c-api-functions 21.8.7.28 `mysql_get_client_version()' ...................................... `unsigned long mysql_get_client_version(void)' * Description * Returns an integer that represents the client library version. The value has the format `XYYZZ' where `X' is the major version, `YY' is the release level, and `ZZ' is the version number within the release level. For example, a value of `40102' represents a client library version of `4.1.2'. * Return Values * An integer that represents the MySQL client library version. * Errors * None.  File: manual.info, Node: mysql-get-host-info, Next: mysql-get-proto-info, Prev: mysql-get-client-version, Up: c-api-functions 21.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.  File: manual.info, Node: mysql-get-proto-info, Next: mysql-get-server-info, Prev: mysql-get-host-info, Up: c-api-functions 21.8.7.30 `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.  File: manual.info, Node: mysql-get-server-info, Next: mysql-get-server-version, Prev: mysql-get-proto-info, Up: c-api-functions 21.8.7.31 `mysql_get_server_info()' ................................... `const char *mysql_get_server_info(MYSQL *mysql)' * Description * Returns a string that represents the server version number. * Return Values * A character string that represents the server version number. * Errors * None.  File: manual.info, Node: mysql-get-server-version, Next: mysql-get-ssl-cipher, Prev: mysql-get-server-info, Up: c-api-functions 21.8.7.32 `mysql_get_server_version()' ...................................... `unsigned long mysql_get_server_version(MYSQL *mysql)' * Description * Returns the version number of the server as an integer. * Return Values * A number that represents the MySQL server version in this format: major_version*10000 + minor_version *100 + sub_version For example, 5.1.5 is returned as 50105. This function is useful in client programs for quickly determining whether some version-specific server capability exists. * Errors * None.  File: manual.info, Node: mysql-get-ssl-cipher, Next: mysql-hex-string, Prev: mysql-get-server-version, Up: c-api-functions 21.8.7.33 `mysql_get_ssl_cipher()' .................................. `const char *mysql_get_ssl_cipher(MYSQL *mysql)' * Description * *Note `mysql_get_ssl_cipher()': mysql-get-ssl-cipher. returns the SSL cipher used for the given connection to the server. `mysql' is the connection handler returned from *Note `mysql_init()': mysql-init. This function was added in MySQL 5.1.11. * Return Values * A string naming the SSL cipher used for the connection, or `NULL' if no cipher is being used.  File: manual.info, Node: mysql-hex-string, Next: mysql-info, Prev: mysql-get-ssl-cipher, Up: c-api-functions 21.8.7.34 `mysql_hex_string()' .............................. `unsigned long mysql_hex_string(char *to, const char *from, unsigned long length)' * Description * This function is used to create a legal SQL string that you can use in an SQL statement. See *Note string-literals::. The string in `from' is encoded to hexadecimal format, with each character encoded as two hexadecimal digits. The result is placed in `to' and a terminating null byte is appended. 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 *Note `mysql_hex_string()': 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 character. The return value can be placed into an SQL statement using either `0xVALUE' or `X'VALUE'' format. However, the return value does not include the `0x' or `X'...''. 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,"0x"); end += mysql_hex_string(end,"What is this",12); end = strmov(end,",0x"); end += mysql_hex_string(end,"binary data: \0\r\n",16); *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 value placed into `to', not including the terminating null character. * Errors * None.  File: manual.info, Node: mysql-info, Next: mysql-init, Prev: mysql-hex-string, Up: c-api-functions 21.8.7.35 `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, *Note `mysql_info()': 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. * *Note `INSERT INTO ... SELECT ...': insert-select. String format: `Records: 100 Duplicates: 0 Warnings: 0' * `INSERT INTO ... VALUES (...),(...),(...)...' String format: `Records: 3 Duplicates: 0 Warnings: 0' * *Note `LOAD DATA INFILE ...': load-data. String format: `Records: 1 Deleted: 0 Skipped: 0 Warnings: 0' * *Note `ALTER TABLE': alter-table. String format: `Records: 3 Duplicates: 0 Warnings: 0' * *Note `UPDATE': update. String format: `Rows matched: 40 Changed: 40 Warnings: 0' Note that *Note `mysql_info()': mysql-info. returns a non-`NULL' value for *Note `INSERT ... VALUES': insert. 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.  File: manual.info, Node: mysql-init, Next: mysql-insert-id, Prev: mysql-info, Up: c-api-functions 21.8.7.36 `mysql_init()' ........................ `MYSQL *mysql_init(MYSQL *mysql)' * Description * Allocates or initializes a `MYSQL' object suitable for *Note `mysql_real_connect()': 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 *Note `mysql_init()': mysql-init. allocates a new object, it is freed when *Note `mysql_close()': mysql-close. is called to close the connection. * Return Values * An initialized `MYSQL*' handle. `NULL' if there was insufficient memory to allocate a new object. * Errors * In case of insufficient memory, `NULL' is returned.  File: manual.info, Node: mysql-insert-id, Next: mysql-kill, Prev: mysql-init, Up: c-api-functions 21.8.7.37 `mysql_insert_id()' ............................. `my_ulonglong mysql_insert_id(MYSQL *mysql)' * Description * Returns the value generated for an `AUTO_INCREMENT' column by the previous *Note `INSERT': insert. or *Note `UPDATE': update. statement. Use this function after you have performed an *Note `INSERT': insert. statement into a table that contains an `AUTO_INCREMENT' field, or have used *Note `INSERT': insert. or *Note `UPDATE': update. to set a column value with `LAST_INSERT_ID(EXPR)'. The return value of *Note `mysql_insert_id()': mysql-insert-id. is always zero unless explicitly updated under one of the following conditions: * *Note `INSERT': 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 *Note `INSERT': insert. statement, the return value of *Note `mysql_insert_id()': mysql-insert-id. depends on the MySQL server version. In MySQL 5.1.12 and later, *Note `mysql_insert_id()': mysql-insert-id. returns the first automatically generated `AUTO_INCREMENT' value that was successfully inserted. In MySQL 5.1.11 and earlier, *Note `mysql_insert_id()': mysql-insert-id. returns the first automatically generated `AUTO_INCREMENT' value, regardless of whether insertion of that value was successful. If no rows are successfully inserted, *Note `mysql_insert_id()': mysql-insert-id. returns 0. * Starting in MySQL 5.1.12, if an *Note `INSERT ... SELECT': insert-select. statement is executed, and no automatically generated value is successfully inserted, *Note `mysql_insert_id()': mysql-insert-id. returns the ID of the last inserted row. * Starting in MySQL 5.1.12, if an *Note `INSERT ... SELECT': insert-select. statement uses `LAST_INSERT_ID(EXPR)', *Note `mysql_insert_id()': mysql-insert-id. returns EXPR. * *Note `INSERT': 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 *Note `mysql_insert_id()': mysql-insert-id. is undefined. For 5.1.12 and later, the return value of *Note `mysql_insert_id()': 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 *Note `INSERT': 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 *Note `INSERT ... ON DUPLICATE KEY UPDATE': insert-on-duplicate. 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. *Note `mysql_insert_id()': 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 *Note `mysql_insert_id()': mysql-insert-id. immediately after the statement that generates the value. The value of *Note `mysql_insert_id()': 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 returns the value of the first automatically generated value that was successfully inserted (starting from 5.1.12) or the first automatically generated value if any rows were successfully inserted (before 5.1.12). `LAST_INSERT_ID()' is not reset between statements because the value of that function is maintained in the server. Another difference from *Note `mysql_insert_id()': mysql-insert-id. is that `LAST_INSERT_ID()' is not updated if you set an `AUTO_INCREMENT' column to a specific nonspecial value. See *Note information-functions::. *Note `mysql_insert_id()': mysql-insert-id. returns `0' following a *Note `CALL': call. statement for a stored procedure that generates an `AUTO_INCREMENT' value because in this case *Note `mysql_insert_id()': mysql-insert-id. applies to *Note `CALL': 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 *Note `mysql_insert_id()': mysql-insert-id. is that `LAST_INSERT_ID()' is made easy to use in scripts while *Note `mysql_insert_id()': mysql-insert-id. tries to provide more exact information about what happens to the `AUTO_INCREMENT' column. * Return Values * Described in the preceding discussion. * Errors * None.  File: manual.info, Node: mysql-kill, Next: mysql-library-end, Prev: mysql-insert-id, Up: c-api-functions 21.8.7.38 `mysql_kill()' ........................ `int mysql_kill(MYSQL *mysql, unsigned long pid)' * Description * Asks the server to kill the thread specified by `pid'. This function is deprecated. It is preferable to use *Note `mysql_query()': mysql-query. to issue an SQL *Note `KILL': kill. 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.  File: manual.info, Node: mysql-library-end, Next: mysql-library-init, Prev: mysql-kill, Up: c-api-functions 21.8.7.39 `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, *Note `mysql_library_end()': 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, *Note `mysql_library_end()': mysql-library-end. shuts down the embedded server and then cleans up. For usage information, see *Note c-api-function-overview::, and *Note mysql-library-init::.  File: manual.info, Node: mysql-library-init, Next: mysql-list-dbs, Prev: mysql-library-end, Up: c-api-functions 21.8.7.40 `mysql_library_init()' ................................ `int mysql_library_init(int argc, char **argv, char **groups)' * Description * Call this function to initialize the MySQL 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. After your application is done using the MySQL library, call *Note `mysql_library_end()': mysql-library-end. to clean up. See *Note 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 *Note c-api-function-overview::. In a nonmulti-threaded environment, the call to *Note `mysql_library_init()': mysql-library-init. may be omitted, because *Note `mysql_init()': mysql-init. will invoke it automatically as necessary. However, *Note `mysql_library_init()': mysql-library-init. is not thread-safe in a multi-threaded environment, and thus neither is *Note `mysql_init()': mysql-init, which calls *Note `mysql_library_init()': mysql-library-init. You must either call *Note `mysql_library_init()': mysql-library-init. prior to spawning any threads, or else use a mutex to protect the call, whether you invoke *Note `mysql_library_init()': mysql-library-init. or indirectly through *Note `mysql_init()': 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 *Note `mysql_library_init(0, NULL, NULL)': mysql-library-init. #include #include int main(void) { if (mysql_library_init(0, NULL, NULL)) { fprintf(stderr, "could not initialize MySQL 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). *Note `mysql_library_init()': 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 *Note 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 #include 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 library\n"); exit(1); } /* Use any MySQL API functions here */ mysql_library_end(); return EXIT_SUCCESS; } * Return Values * Zero if successful. Nonzero if an error occurred.  File: manual.info, Node: mysql-list-dbs, Next: mysql-list-fields, Prev: mysql-library-init, Up: c-api-functions 21.8.7.41 `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 *Note `mysql_list_dbs()': mysql-list-dbs. is similar to executing the query `SHOW DATABASES [LIKE WILD]'. You must free the result set with *Note `mysql_free_result()': 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.  File: manual.info, Node: mysql-list-fields, Next: mysql-list-processes, Prev: mysql-list-dbs, Up: c-api-functions 21.8.7.42 `mysql_list_fields()' ............................... `MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)' * Description * Returns an empty result set for which the metadata provides information aobut 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 *Note `mysql_list_fields()': 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 *Note `mysql_list_fields()': mysql-list-fields. You must free the result set with *Note `mysql_free_result()': 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);  File: manual.info, Node: mysql-list-processes, Next: mysql-list-tables, Prev: mysql-list-fields, Up: c-api-functions 21.8.7.43 `mysql_list_processes()' .................................. `MYSQL_RES *mysql_list_processes(MYSQL *mysql)' * Description * Returns a result set describing the current server threads. This is the same kind of information as that reported by *Note `mysqladmin processlist': mysqladmin. or a *Note `SHOW PROCESSLIST': show-processlist. query. You must free the result set with *Note `mysql_free_result()': 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.  File: manual.info, Node: mysql-list-tables, Next: mysql-more-results, Prev: mysql-list-processes, Up: c-api-functions 21.8.7.44 `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 *Note `mysql_list_tables()': mysql-list-tables. is similar to executing the query `SHOW TABLES [LIKE WILD]'. You must free the result set with *Note `mysql_free_result()': 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.  File: manual.info, Node: mysql-more-results, Next: mysql-next-result, Prev: mysql-list-tables, Up: c-api-functions 21.8.7.45 `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 *Note `CALL': call. statements, which can return multiple result sets. *Note `mysql_more_results()': mysql-more-results. true if more results exist from the currently executed statement, in which case the application must call *Note `mysql_next_result()': 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 *Note `mysql_next_result()': mysql-next-result. instead to test whether more results exist and initiate retrieval if so. See *Note c-api-multiple-queries::, and *Note mysql-next-result::. * Errors * None.  File: manual.info, Node: mysql-next-result, Next: mysql-num-fields, Prev: mysql-more-results, Up: c-api-functions 21.8.7.46 `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 *Note `CALL': call. statements to execute stored procedures, which can return multiple result sets. *Note `mysql_next_result()': mysql-next-result. reads the next statement result and returns a status to indicate whether more results exist. If *Note `mysql_next_result()': mysql-next-result. returns an error, there are no more results. Before each call to *Note `mysql_next_result()': mysql-next-result, you must call *Note `mysql_free_result()': 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 *Note `mysql_next_result()': mysql-next-result. the state of the connection is as if you had called *Note `mysql_real_query()': mysql-real-query. or *Note `mysql_query()': mysql-query. for the next statement. This means that you can call *Note `mysql_store_result()': mysql-store-result, *Note `mysql_warning_count()': mysql-warning-count, *Note `mysql_affected_rows()': mysql-affected-rows, and so forth. If your program uses *Note `CALL': call. statements to execute stored procedures, the `CLIENT_MULTI_RESULTS' flag must be enabled. This is because each *Note `CALL': 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 *Note `CALL': call. can return multiple results, process them using a loop that calls *Note `mysql_next_result()': mysql-next-result. to determine whether there are more results. `CLIENT_MULTI_RESULTS' can be enabled when you call *Note `mysql_real_connect()': 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'). It is also possible to test whether there are more results by calling *Note `mysql_more_results()': mysql-more-results. However, this function does not change the connection state, so if it returns true, you must still call *Note `mysql_next_result()': mysql-next-result. to advance to the next result. For an example that shows how to use *Note `mysql_next_result()': mysql-next-result, see *Note c-api-multiple-queries::. * Return Values * This table lists *Note `mysql_next_result()': mysql-next-result. return values and provides a description of each. 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 didn't call *Note `mysql_use_result()': 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.  File: manual.info, Node: mysql-num-fields, Next: mysql-num-rows, Prev: mysql-next-result, Up: c-api-functions 21.8.7.47 `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. Note that you can get the number of columns either from a pointer to a result set or to a connection handle. You would use the connection handle if *Note `mysql_store_result()': mysql-store-result. or *Note `mysql_use_result()': mysql-use-result. returned `NULL' (and thus you have no result set pointer). In this case, you can call *Note `mysql_field_count()': mysql-field-count. to determine whether *Note `mysql_store_result()': 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 *Note `SELECT': select. (or *Note `SELECT': select.-like) statement. The example shown here illustrates how this may be done. See *Note 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 *Note `mysql_errno(&mysql)': mysql-errno. call with a check whether *Note `mysql_field_count(&mysql)': mysql-field-count. returns 0. This happens only if something went wrong.  File: manual.info, Node: mysql-num-rows, Next: mysql-options, Prev: mysql-num-fields, Up: c-api-functions 21.8.7.48 `mysql_num_rows()' ............................ `my_ulonglong mysql_num_rows(MYSQL_RES *result)' * Description * Returns the number of rows in the result set. The use of *Note `mysql_num_rows()': mysql-num-rows. depends on whether you use *Note `mysql_store_result()': mysql-store-result. or *Note `mysql_use_result()': mysql-use-result. to return the result set. If you use *Note `mysql_store_result()': mysql-store-result, *Note `mysql_num_rows()': mysql-num-rows. may be called immediately. If you use *Note `mysql_use_result()': mysql-use-result, *Note `mysql_num_rows()': mysql-num-rows. does not return the correct value until all the rows in the result set have been retrieved. *Note `mysql_num_rows()': mysql-num-rows. is intended for use with statements that return a result set, such as *Note `SELECT': select. For statements such as *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': delete, the number of affected rows can be obtained with *Note `mysql_affected_rows()': mysql-affected-rows. * Return Values * The number of rows in the result set. * Errors * None.  File: manual.info, Node: mysql-options, Next: mysql-ping, Prev: mysql-num-rows, Up: c-api-functions 21.8.7.49 `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. Call *Note `mysql_options()': mysql-options. after *Note `mysql_init()': mysql-init. and before *Note `mysql_connect()': mysql-connect. or *Note `mysql_real_connect()': 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. The following list describes the possible options, their effect, and how `arg' is used for each option. 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. For option descriptions that indicate `arg' is unused, its value is irrelevant; it is conventional to pass 0. * `MYSQL_INIT_COMMAND' (argument type: `char *') SQL statement to execute when connecting to the MySQL server. Automatically re-executed if reconnection occurs. * `MYSQL_OPT_COMPRESS' (argument: not used) Use the compressed client/server protocol. * `MYSQL_OPT_CONNECT_TIMEOUT' (argument type: `unsigned int *') Connect timeout in seconds. * `MYSQL_OPT_GUESS_CONNECTION' (argument: not used) For an application linked against the `libmysqld' embedded server library, this 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') If no pointer is given or if pointer points to an `unsigned int' that has a nonzero value, the `LOAD LOCAL INFILE' statement is enabled. * `MYSQL_OPT_NAMED_PIPE' (argument: not used) Use named pipes to connect to a MySQL server on Windows, if the server permits named-pipe connections. * `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. Before MySQL 5.1.41, this option applies only to TCP/IP connections and, prior to MySQL 5.1.12, only for Windows. Implementation of this timeout uses mechanisms that may not be available on all platforms. On such a platform, a client that issues a read call might under certain circumstances wait without timing out. For example, a client might not time out if the server is not responding because it is waiting for a `disk full' condition to clear. * `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. Note: *Note `mysql_real_connect()': mysql-real-connect. incorrectly reset the `MYSQL_OPT_RECONNECT' option to its default value before MySQL 5.1.6. Therefore, prior to that version, if you want reconnect to be enabled for each connection, you must call *Note `mysql_options()': mysql-options. with the `MYSQL_OPT_RECONNECT' option after each call to *Note `mysql_real_connect()': mysql-real-connect. This is not necessary as of 5.1.6: Call *Note `mysql_options()': mysql-options. only before *Note `mysql_real_connect()': mysql-real-connect. as usual. * `MYSQL_OPT_SSL_VERIFY_SERVER_CERT' (argument type: `my_bool *') Enable or disable verification of the server's Common Name value in its certificate against the host name used when connecting to the server. The connection is rejected if there is a mismatch. This feature can be used to prevent man-in-the-middle attacks. Verification is disabled by default. Added in MySQL 5.1.11. * `MYSQL_OPT_USE_EMBEDDED_CONNECTION' (argument: not used) For an application linked against the `libmysqld' embedded server library, this forces the use of the embedded server for the connection. This option 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 forces the use of a remote server for the connection. This option 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. Before MySQL 5.1.41, this option applies only to TCP/IP connections and, prior to MySQL 5.1.12, only for Windows. * `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. * `MYSQL_SET_CHARSET_DIR' (argument type: `char *') The path name to 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. * `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 means that the user is considered to have connected from the specified IP address (specified as a string) for authentication purposes. This option 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 *Note `mysqld': 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. This table lists options that may appear in the option file and provides a description of each option. Option Description `character-sets-dir=PATH' The directory where character sets are installed. `compress' Use the compressed client/server protocol. `connect-timeout=SECONDS' 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 *Note `LOAD DATA LOCAL': load-data. `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 *Note `mysql_real_connect()': mysql-real-connect. See *Note mysql-real-connect::. `local-infile[={0|1}]' If no argument or nonzero argument, enable use of *Note `LOAD DATA LOCAL': load-data.; 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 ``;''). `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 *Note `mysql_info()': mysql-info. to return found rows instead of updated rows when using *Note `UPDATE': update. `shared-memory-base-name=NAME'Shared-memory name to use to connect to server. `socket=PATH' Default socket file. `ssl-ca=FILE_NAME' Certificate Authority file. `ssl-capath=PATH' 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 in MySQL 5.1 for backward compatibility. For more information about option files, see *Note option-files::. Before MySQL 5.1.18, the `arg' argument was declared as `char *'. * Return Values * Zero for success. Nonzero if you specify an unknown option. * Example * The following *Note `mysql_options()': mysql-options. calls request the use of compression in the client/server protocol, cause options to be read from the `[odbc]' group of 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)); } This code requests that the client use the compressed client/server protocol and read the additional options from the `odbc' section in the `my.cnf' file.  File: manual.info, Node: mysql-ping, Next: mysql-query, Prev: mysql-options, Up: c-api-functions 21.8.7.50 `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, *Note `mysql_ping()': mysql-ping. returns an error. Auto-reconnect is disabled by default. To enable it, call *Note `mysql_options()': mysql-options. with the `MYSQL_OPT_RECONNECT' option. For details, see *Note mysql-options::. *Note `mysql_ping()': 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 *Note `mysql_ping()': mysql-ping.) does cause a reconnect, there is no explicit indication of it. To determine whether a reconnect occurs, call *Note `mysql_thread_id()': mysql-thread-id. to get the original connection identifier before calling *Note `mysql_ping()': mysql-ping, then call *Note `mysql_thread_id()': 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 *Note 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.  File: manual.info, Node: mysql-query, Next: mysql-real-connect, Prev: mysql-ping, Up: c-api-functions 21.8.7.51 `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 *Note c-api-multiple-queries::. *Note `mysql_query()': mysql-query. cannot be used for statements that contain binary data; you must use *Note `mysql_real_query()': mysql-real-query. instead. (Binary data may contain the ``\0'' character, which *Note `mysql_query()': mysql-query. interprets as the end of the statement string.) If you want to know whether the statement should return a result set, you can use *Note `mysql_field_count()': mysql-field-count. to check for this. See *Note mysql-field-count::. * Return Values * Zero if the statement was successful. 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.  File: manual.info, Node: mysql-real-connect, Next: mysql-real-escape-string, Prev: mysql-query, Up: c-api-functions 21.8.7.52 `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 * *Note `mysql_real_connect()': mysql-real-connect. attempts to establish a connection to a MySQL database engine running on `host'. *Note `mysql_real_connect()': mysql-real-connect. must complete successfully before you can execute any other API functions that require a valid `MYSQL' connection handle structure. The parameters are specified as follows: * For the first parameter, specify the address of an existing `MYSQL' structure. Before calling *Note `mysql_real_connect()': mysql-real-connect, call *Note `mysql_init()': mysql-init. to initialize the `MYSQL' structure. You can change a lot of connect options with the *Note `mysql_options()': mysql-options. call. See *Note 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 *Note `mysql_options()': 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 *Note 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 *Note `mysql_real_connect()': 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 *Note `mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "CHARSET_NAME")': mysql-options. 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. This table lists flag names and provides a description of each. Flag Name Flag Description `CLIENT_COMPRESS' Use compression 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 (instead of `wait_timeout' seconds) of inactivity 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 *Note `LOAD DATA LOCAL': load-data. 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 ``;''). 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 the 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 *Note `mysql_ssl_set()': mysql-ssl-set. before calling *Note `mysql_real_connect()': mysql-real-connect. `CLIENT_REMEMBER_OPTIONS'Remember options specified by calls to *Note `mysql_options()': mysql-options. Without this option, if *Note `mysql_real_connect()': mysql-real-connect. fails, you must repeat the *Note `mysql_options()': mysql-options. calls before trying to connect again. With this option, the *Note `mysql_options()': mysql-options. calls need not be repeated. If your program uses *Note `CALL': call. statements to execute stored procedures, the `CLIENT_MULTI_RESULTS' flag must be enabled. This is because each *Note `CALL': 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 *Note `CALL': call. can return multiple results, process them using a loop that calls *Note `mysql_next_result()': mysql-next-result. to determine whether there are more results. `CLIENT_MULTI_RESULTS' can be enabled when you call *Note `mysql_real_connect()': 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'). If you enable `CLIENT_MULTI_STATEMENTS' or `CLIENT_MULTI_RESULTS', you should process the result for every call to *Note `mysql_query()': mysql-query. or *Note `mysql_real_query()': mysql-real-query. by using a loop that calls *Note `mysql_next_result()': mysql-next-result. to determine whether there are more results. For an example, see *Note 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 *Note `mysql_real_connect()': mysql-real-connect. call. To do this, call *Note `mysql_options()': mysql-options. with the `MYSQL_READ_DEFAULT_FILE' or `MYSQL_READ_DEFAULT_GROUP' option before calling *Note `mysql_real_connect()': mysql-real-connect. Then, in the *Note `mysql_real_connect()': 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 *Note `mysql_real_connect()': 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 handle 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'. * 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 *Note `mysql_options()': mysql-options. the MySQL 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. Note that upon connection, *Note `mysql_real_connect()': 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 *Note `mysql_options()': mysql-options. to control reconnection behavior.  File: manual.info, Node: mysql-real-escape-string, Next: mysql-real-query, Prev: mysql-real-connect, Up: c-api-functions 21.8.7.53 `mysql_real_escape_string()' ...................................... `unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)' Note that `mysql' must be a valid, open connection. This is needed because the escaping depends on the character set in use by the server. * Description * This function is used to create a legal SQL string that you can use in an SQL statement. See *Note string-literals::. The string in `from' is encoded to an escaped SQL string, taking into account the current character set of the connection. The result is placed in `to' and a terminating null byte is appended. 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. *Note `mysql_real_escape_string()': 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 *Note string-literals::, and *Note 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 you need room for the terminating null byte.) When *Note `mysql_real_escape_string()': 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 character. If you need to change the character set of the connection, use the *Note `mysql_set_character_set()': mysql-set-character-set. function rather than executing a `SET NAMES' (or `SET CHARACTER SET') statement. *Note `mysql_set_character_set()': mysql-set-character-set. works like `SET NAMES' but also affects the character set used by *Note `mysql_real_escape_string()': mysql-real-escape-string, which `SET NAMES' does not. * Example * char query[1000],*end; end = strmov(query,"INSERT INTO test_table values("); *end++ = '\''; end += mysql_real_escape_string(&mysql, end,"What is this",12); *end++ = '\''; *end++ = ','; *end++ = '\''; end += mysql_real_escape_string(&mysql, end,"binary data: \0\r\n",16); *end++ = '\''; *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 value placed into `to', not including the terminating null character. * Errors * None.  File: manual.info, Node: mysql-real-query, Next: mysql-refresh, Prev: mysql-real-escape-string, Up: c-api-functions 21.8.7.54 `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 *Note c-api-multiple-queries::. *Note `mysql_query()': mysql-query. cannot be used for statements that contain binary data; you must use *Note `mysql_real_query()': mysql-real-query. instead. (Binary data may contain the ``\0'' character, which *Note `mysql_query()': mysql-query. interprets as the end of the statement string.) In addition, *Note `mysql_real_query()': mysql-real-query. is faster than *Note `mysql_query()': mysql-query. because it does not call `strlen()' on the statement string. If you want to know whether the statement should return a result set, you can use *Note `mysql_field_count()': mysql-field-count. to check for this. See *Note mysql-field-count::. * Return Values * Zero if the statement was successful. 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.  File: manual.info, Node: mysql-refresh, Next: mysql-reload, Prev: mysql-real-query, Up: c-api-functions 21.8.7.55 `mysql_refresh()' ........................... `int mysql_refresh(MYSQL *mysql, unsigned int options)' * Description * This function flushes tables or caches, or resets replication server information. The connected user must have the `RELOAD' privilege. The `options' argument is a bit mask 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 *Note `FLUSH PRIVILEGES': flush. * `REFRESH_LOG' Flush the logs, like *Note `FLUSH LOGS': flush. * `REFRESH_TABLES' Flush the table cache, like *Note `FLUSH TABLES': flush. * `REFRESH_HOSTS' Flush the host cache, like *Note `FLUSH HOSTS': flush. * `REFRESH_STATUS' Reset status variables, like *Note `FLUSH STATUS': flush. * `REFRESH_THREADS' Flush the thread cache. * `REFRESH_SLAVE' On a slave replication server, reset the master server information and restart the slave, like *Note `RESET SLAVE': 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 *Note `RESET MASTER': 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.  File: manual.info, Node: mysql-reload, Next: mysql-rollback, Prev: mysql-refresh, Up: c-api-functions 21.8.7.56 `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. It is preferable to use *Note `mysql_query()': mysql-query. to issue an SQL *Note `FLUSH PRIVILEGES': flush. 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.  File: manual.info, Node: mysql-rollback, Next: mysql-row-seek, Prev: mysql-reload, Up: c-api-functions 21.8.7.57 `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 2, the server performs a release after terminating a transaction and closes the client connection. The client program should call *Note `mysql_close()': mysql-close. to close the connection from the client side. * Return Values * Zero if successful. Nonzero if an error occurred. * Errors * None.  File: manual.info, Node: mysql-row-seek, Next: mysql-row-tell, Prev: mysql-rollback, Up: c-api-functions 21.8.7.58 `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 *Note `mysql_row_tell()': mysql-row-tell. or from *Note `mysql_row_seek()': mysql-row-seek. This value is not a row number; to seek to a row within a result set by number, use *Note `mysql_data_seek()': mysql-data-seek. instead. This function requires that the result set structure contains the entire result of the query, so *Note `mysql_row_seek()': mysql-row-seek. may be used only in conjunction with *Note `mysql_store_result()': mysql-store-result, not with *Note `mysql_use_result()': mysql-use-result. * Return Values * The previous value of the row cursor. This value may be passed to a subsequent call to *Note `mysql_row_seek()': mysql-row-seek. * Errors * None.  File: manual.info, Node: mysql-row-tell, Next: mysql-select-db, Prev: mysql-row-seek, Up: c-api-functions 21.8.7.59 `mysql_row_tell()' ............................ `MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)' * Description * Returns the current position of the row cursor for the last *Note `mysql_fetch_row()': mysql-fetch-row. This value can be used as an argument to *Note `mysql_row_seek()': mysql-row-seek. Use *Note `mysql_row_tell()': mysql-row-tell. only after *Note `mysql_store_result()': mysql-store-result, not after *Note `mysql_use_result()': mysql-use-result. * Return Values * The current offset of the row cursor. * Errors * None.  File: manual.info, Node: mysql-select-db, Next: mysql-set-character-set, Prev: mysql-row-tell, Up: c-api-functions 21.8.7.60 `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 do not include an explicit database specifier. *Note `mysql_select_db()': 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.  File: manual.info, Node: mysql-set-character-set, Next: mysql-set-local-infile-default, Prev: mysql-select-db, Up: c-api-functions 21.8.7.61 `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 *Note `mysql_real_escape_string()': 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)); }  File: manual.info, Node: mysql-set-local-infile-default, Next: mysql-set-local-infile-handler, Prev: mysql-set-character-set, Up: c-api-functions 21.8.7.62 `mysql_set_local_infile_default()' ............................................ `void mysql_set_local_infile_default(MYSQL *mysql);' * Description * Sets the `LOAD LOCAL DATA INFILE' handler callback functions to the defaults used internally by the C client library. The library calls this function automatically if *Note `mysql_set_local_infile_handler()': 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.  File: manual.info, Node: mysql-set-local-infile-handler, Next: mysql-set-server-option, Prev: mysql-set-local-infile-default, Up: c-api-functions 21.8.7.63 `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 *Note `LOAD DATA LOCAL INFILE': load-data. 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 *Note `mysql_set_local_infile_handler()': 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 *Note `mysql_set_local_infile_handler()': mysql-set-local-infile-handler. The initialization function should 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 *Note `mysql_set_local_infile_handler()': mysql-set-local-infile-handler. in your C code and passing pointers to your callback functions, you can then issue a *Note `LOAD DATA LOCAL INFILE': load-data. statement (for example, by using *Note `mysql_query()': mysql-query.). The client library automatically invokes your callbacks. The file name specified in *Note `LOAD DATA LOCAL INFILE': load-data. will be passed as the second parameter to the `local_infile_init()' callback. * Return Values * None. * Errors * None.  File: manual.info, Node: mysql-set-server-option, Next: mysql-shutdown, Prev: mysql-set-local-infile-handler, Up: c-api-functions 21.8.7.64 `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. This table lists options for *Note `mysql_set_server_option()': mysql-set-server-option. and provides a description of each option. 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 *Note `mysql_query()': mysql-query. or *Note `mysql_real_query()': mysql-real-query. by using a loop that calls *Note `mysql_next_result()': mysql-next-result. to determine whether there are more results. For an example, see *Note 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 *Note `mysql_real_connect()': mysql-real-connect.: `CLIENT_MULTI_STATEMENTS' also enables `CLIENT_MULTI_RESULTS'. If you are using the *Note `CALL': 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 *Note `CALL': 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 didn't support *Note `mysql_set_server_option()': mysql-set-server-option. (which is the case that the server is older than 4.1.1) or the server didn't support the option one tried to set.  File: manual.info, Node: mysql-shutdown, Next: mysql-sqlstate, Prev: mysql-set-server-option, Up: c-api-functions 21.8.7.65 `mysql_shutdown()' ............................ `int mysql_shutdown(MYSQL *mysql, enum mysql_enum_shutdown_level shutdown_level)' * Description * Asks the database server to shut down. The connected user must have the `SHUTDOWN' privilege. MySQL 5.1 servers support only one type of shutdown; `shutdown_level' must be equal to `SHUTDOWN_DEFAULT'. Additional shutdown levels are planned to make it possible to choose the desired level. Dynamically linked executables which have been compiled with older versions of the `libmysqlclient' headers and call *Note `mysql_shutdown()': mysql-shutdown. need to be used with the old `libmysqlclient' dynamic library. The shutdown process is described in *Note 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.  File: manual.info, Node: mysql-sqlstate, Next: mysql-ssl-set, Prev: mysql-shutdown, Up: c-api-functions 21.8.7.66 `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 *Note error-handling::. SQLSTATE values returned by *Note `mysql_sqlstate()': mysql-sqlstate. differ from MySQL-specific error numbers returned by *Note `mysql_errno()': mysql-errno. For example, the *Note `mysql': mysql. client program displays errors using the following format, where `1146' is the *Note `mysql_errno()': mysql-errno. value and `'42S02'' is the corresponding *Note `mysql_sqlstate()': 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 *Note `mysql_sqlstate()': mysql-sqlstate. after *Note `mysql_real_connect()': mysql-real-connect. fails, *Note `mysql_sqlstate()': 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 *Note mysql-errno::, *Note mysql-error::, and *Note mysql-stmt-sqlstate::.  File: manual.info, Node: mysql-ssl-set, Next: mysql-stat, Prev: mysql-sqlstate, Up: c-api-functions 21.8.7.67 `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 * *Note `mysql_ssl_set()': mysql-ssl-set. is used for establishing secure connections using SSL. It must be called before *Note `mysql_real_connect()': mysql-real-connect. *Note `mysql_ssl_set()': mysql-ssl-set. does nothing unless SSL support is enabled in the client library. `mysql' is the connection handler returned from *Note `mysql_init()': mysql-init. The other parameters are specified as follows: * `key' is the path name to the key file. * `cert' is the path name to the certificate file. * `ca' is the path name to the certificate authority file. * `capath' is the path name to a directory that contains trusted SSL CA certificates in PEM format. * `cipher' is a list of permissible ciphers to use for SSL encryption. Any unused SSL parameters may be given as `NULL'. * Return Values * This function always returns `0'. If SSL setup is incorrect, *Note `mysql_real_connect()': mysql-real-connect. returns an error when you attempt to connect.  File: manual.info, Node: mysql-stat, Next: mysql-store-result, Prev: mysql-ssl-set, Up: c-api-functions 21.8.7.68 `mysql_stat()' ........................ `const char *mysql_stat(MYSQL *mysql)' * Description * Returns a character string containing information similar to that provided by the *Note `mysqladmin status': mysqladmin. 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.  File: manual.info, Node: mysql-store-result, Next: mysql-thread-id, Prev: mysql-stat, Up: c-api-functions 21.8.7.69 `mysql_store_result()' ................................ `MYSQL_RES *mysql_store_result(MYSQL *mysql)' * Description * After invoking *Note `mysql_query()': mysql-query. or *Note `mysql_real_query()': mysql-real-query, you must call *Note `mysql_store_result()': mysql-store-result. or *Note `mysql_use_result()': mysql-use-result. for every statement that successfully produces a result set (*Note `SELECT': select, *Note `SHOW': show, *Note `DESCRIBE': describe, *Note `EXPLAIN': explain, *Note `CHECK TABLE': check-table, and so forth). You must also call *Note `mysql_free_result()': mysql-free-result. after you are done with the result set. You don't have to call *Note `mysql_store_result()': mysql-store-result. or *Note `mysql_use_result()': mysql-use-result. for other statements, but it does not do any harm or cause any notable performance degradation if you call *Note `mysql_store_result()': mysql-store-result. in all cases. You can detect whether the statement has a result set by checking whether *Note `mysql_store_result()': mysql-store-result. returns a nonzero value (more about this later). If you enable multiple-statement support, you should retrieve results from calls to *Note `mysql_query()': mysql-query. or *Note `mysql_real_query()': mysql-real-query. by using a loop that calls *Note `mysql_next_result()': mysql-next-result. to determine whether there are more results. For an example, see *Note c-api-multiple-queries::. If you want to know whether a statement should return a result set, you can use *Note `mysql_field_count()': mysql-field-count. to check for this. See *Note mysql-field-count::. *Note `mysql_store_result()': 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. *Note `mysql_store_result()': mysql-store-result. returns a null pointer if the statement didn't return a result set (for example, if it was an *Note `INSERT': insert. statement). *Note `mysql_store_result()': 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 *Note `mysql_error()': mysql-error. returns a nonempty string, *Note `mysql_errno()': mysql-errno. returns nonzero, or *Note `mysql_field_count()': 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 *Note `mysql_store_result()': mysql-store-result. and gotten back a result that isn't a null pointer, you can call *Note `mysql_num_rows()': mysql-num-rows. to find out how many rows are in the result set. You can call *Note `mysql_fetch_row()': mysql-fetch-row. to fetch rows from the result set, or *Note `mysql_row_seek()': mysql-row-seek. and *Note `mysql_row_tell()': mysql-row-tell. to obtain or set the current row position within the result set. See *Note null-mysql-store-result::. * Return Values * A `MYSQL_RES' result structure with the results. `NULL' (0) if an error occurred. * Errors * *Note `mysql_store_result()': mysql-store-result. resets *Note `mysql_error()': mysql-error. and *Note `mysql_errno()': 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.  File: manual.info, Node: mysql-thread-id, Next: mysql-use-result, Prev: mysql-store-result, Up: c-api-functions 21.8.7.70 `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 *Note `mysql_kill()': mysql-kill. to kill the thread. If the connection is lost and you reconnect with *Note `mysql_ping()': 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 *Note `mysql_thread_id()': 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.  File: manual.info, Node: mysql-use-result, Next: mysql-warning-count, Prev: mysql-thread-id, Up: c-api-functions 21.8.7.71 `mysql_use_result()' .............................. `MYSQL_RES *mysql_use_result(MYSQL *mysql)' * Description * After invoking *Note `mysql_query()': mysql-query. or *Note `mysql_real_query()': mysql-real-query, you must call *Note `mysql_store_result()': mysql-store-result. or *Note `mysql_use_result()': mysql-use-result. for every statement that successfully produces a result set (*Note `SELECT': select, *Note `SHOW': show, *Note `DESCRIBE': describe, *Note `EXPLAIN': explain, *Note `CHECK TABLE': check-table, and so forth). You must also call *Note `mysql_free_result()': mysql-free-result. after you are done with the result set. *Note `mysql_use_result()': mysql-use-result. initiates a result set retrieval but does not actually read the result set into the client like *Note `mysql_store_result()': mysql-store-result. does. Instead, each row must be retrieved individually by making calls to *Note `mysql_fetch_row()': 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 *Note `mysql_store_result()': 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 shouldn't use *Note `mysql_use_result()': mysql-use-result. 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 *Note `mysql_use_result()': mysql-use-result, you must execute *Note `mysql_fetch_row()': 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 *Note `mysql_data_seek()': mysql-data-seek, *Note `mysql_row_seek()': mysql-row-seek, *Note `mysql_row_tell()': mysql-row-tell, *Note `mysql_num_rows()': mysql-num-rows, or *Note `mysql_affected_rows()': mysql-affected-rows. with a result returned from *Note `mysql_use_result()': mysql-use-result, nor may you issue other queries until *Note `mysql_use_result()': mysql-use-result. has finished. (However, after you have fetched all the rows, *Note `mysql_num_rows()': mysql-num-rows. accurately returns the number of rows fetched.) You must call *Note `mysql_free_result()': 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 *Note `mysql_free_result()': mysql-free-result. is called. * Return Values * A `MYSQL_RES' result structure. `NULL' if an error occurred. * Errors * *Note `mysql_use_result()': mysql-use-result. resets *Note `mysql_error()': mysql-error. and *Note `mysql_errno()': 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.  File: manual.info, Node: mysql-warning-count, Prev: mysql-use-result, Up: c-api-functions 21.8.7.72 `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.  File: manual.info, Node: c-api-prepared-statements, Next: c-api-prepared-statement-data-structures, Prev: c-api-functions, Up: c-api 21.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 *Note `mysql_stmt_init()': 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 handle 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 *Note sql-syntax-prepared-statements::. As of MySQL 5.1.25, 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 *Note statement-repreparation::.  File: manual.info, Node: c-api-prepared-statement-data-structures, Next: c-api-prepared-statement-function-overview, Prev: c-api-prepared-statements, Up: c-api 21.8.9 C API Prepared Statement Data Structures ----------------------------------------------- * Menu: * c-api-prepared-statement-type-codes:: C API Prepared Statement Type Codes * c-api-prepared-statement-type-conversions:: C API Prepared Statement Type Conversions Prepared statements use several data structures: * To obtain a statement handle, pass a `MYSQL' connection handler to *Note `mysql_stmt_init()': 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 *Note `mysql_stmt_prepare()': mysql-stmt-prepare. * To provide input parameters for a prepared statement, set up `MYSQL_BIND' structures and pass them to *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param. To receive output column values, set up `MYSQL_BIND' structures and pass them to *Note `mysql_stmt_bind_result()': 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 *Note mysql-stmt-execute::, and *Note mysql-stmt-fetch::. * `MYSQL_STMT' This structure is a handle for a prepared statement. A handle is created by calling *Note `mysql_stmt_init()': mysql-stmt-init, which returns a pointer to a `MYSQL_STMT'. The handle is used for all subsequent operations with the statement until you close it with *Note `mysql_stmt_close()': mysql-stmt-close, at which point the handle becomes invalid. 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 handles can be associated with a single connection. The limit on the number of handles 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 *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param. to bind parameter data values to buffers for use by *Note `mysql_stmt_execute()': mysql-stmt-execute. * For output, use `MYSQL_BIND' structures with *Note `mysql_stmt_bind_result()': mysql-stmt-bind-result. to bind buffers to result set columns, for use in fetching rows with *Note `mysql_stmt_fetch()': 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 *Note 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 *Note `mysql_stmt_execute()': 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 *Note `mysql_stmt_fetch()': 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 *Note c-api-prepared-statement-type-codes::, and *Note 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 *Note `mysql_stmt_bind_param()': 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 *Note `mysql_stmt_bind_result()': 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 *Note `mysql_stmt_execute()': mysql-stmt-execute. For output value binding, MySQL sets `*length' when you call *Note `mysql_stmt_fetch()': mysql-stmt-fetch. The *Note `mysql_stmt_fetch()': 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 *Note 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 *Note `BIGINT': integer-types. 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, *Note `mysql_stmt_fetch()': 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 *Note `mysql_options()': mysql-options. with the `MYSQL_REPORT_DATA_TRUNCATION' option. * `MYSQL_TIME' This structure is used to send and receive *Note `DATE': datetime, *Note `TIME': time, *Note `DATETIME': datetime, and *Note `TIMESTAMP': datetime. 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. This table lists members of the `MYSQL_TIME' structure and provides a description of each member. 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; currently unused 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 *Note `DATE': datetime, *Note `DATETIME': datetime, and *Note `TIMESTAMP': datetime. values. The `hour', `minute', and `second' elements are used for *Note `TIME': time, *Note `DATETIME': datetime, and *Note `TIMESTAMP': datetime. values. See *Note c-api-prepared-statement-date-handling::.  File: manual.info, Node: c-api-prepared-statement-type-codes, Next: c-api-prepared-statement-type-conversions, Prev: c-api-prepared-statement-data-structures, Up: c-api-prepared-statement-data-structures 21.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. This table lists C type input variables, corresponding `buffer_type' values, and the SQL data types for which the supplied value can be used without conversion. Input Variable C Type `buffer_type' Value SQL Type of Destination Value `signed char' `MYSQL_TYPE_TINY' *Note `TINYINT': integer-types. `short int' `MYSQL_TYPE_SHORT' *Note `SMALLINT': integer-types. `int' `MYSQL_TYPE_LONG' *Note `INT': integer-types. `long long int' `MYSQL_TYPE_LONGLONG' *Note `BIGINT': integer-types. `float' `MYSQL_TYPE_FLOAT' *Note `FLOAT': floating-point-types. `double' `MYSQL_TYPE_DOUBLE' *Note `DOUBLE': floating-point-types. `MYSQL_TIME' `MYSQL_TYPE_TIME' *Note `TIME': time. `MYSQL_TIME' `MYSQL_TYPE_DATE' *Note `DATE': datetime. `MYSQL_TIME' `MYSQL_TYPE_DATETIME' *Note `DATETIME': datetime. `MYSQL_TIME' `MYSQL_TYPE_TIMESTAMP' *Note `TIMESTAMP': datetime. `char[]' `MYSQL_TYPE_STRING' *Note `TEXT': blob, *Note `CHAR': char, *Note `VARCHAR': char. `char[]' `MYSQL_TYPE_BLOB' *Note `BLOB': blob, *Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary. `MYSQL_TYPE_NULL' `NULL' Use `MYSQL_TYPE_NULL' as indicated in the description for the `is_null' member in *Note 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. This table shows SQL types of received values, corresponding `buffer_type' values, and recommended C data type output variables. SQL Type of Received `buffer_type' Value Output Variable C Type Value *Note `TINYINT': `MYSQL_TYPE_TINY' `signed char' integer-types. *Note `SMALLINT': `MYSQL_TYPE_SHORT' `short int' integer-types. *Note `MEDIUMINT': `MYSQL_TYPE_INT24' `int' integer-types. *Note `INT': `MYSQL_TYPE_LONG' `int' integer-types. *Note `BIGINT': `MYSQL_TYPE_LONGLONG' `long long int' integer-types. *Note `FLOAT': `MYSQL_TYPE_FLOAT' `float' floating-point-types. *Note `DOUBLE': `MYSQL_TYPE_DOUBLE' `double' floating-point-types. *Note `DECIMAL': `MYSQL_TYPE_NEWDECIMAL' `char[]' fixed-point-types. *Note `YEAR': year. `MYSQL_TYPE_SHORT' `short int' *Note `TIME': time. `MYSQL_TYPE_TIME' `MYSQL_TIME' *Note `DATE': `MYSQL_TYPE_DATE' `MYSQL_TIME' datetime. *Note `DATETIME': `MYSQL_TYPE_DATETIME' `MYSQL_TIME' datetime. *Note `TIMESTAMP': `MYSQL_TYPE_TIMESTAMP' `MYSQL_TIME' datetime. *Note `CHAR': char, `MYSQL_TYPE_STRING' `char[]' *Note `BINARY': binary-varbinary. *Note `VARCHAR': char, `MYSQL_TYPE_VAR_STRING' `char[]' *Note `VARBINARY': binary-varbinary. *Note `TINYBLOB': `MYSQL_TYPE_TINY_BLOB' `char[]' blob, *Note `TINYTEXT': blob. *Note `BLOB': blob, `MYSQL_TYPE_BLOB' `char[]' *Note `TEXT': blob. *Note `MEDIUMBLOB': `MYSQL_TYPE_MEDIUM_BLOB' `char[]' blob, *Note `MEDIUMTEXT': blob. *Note `LONGBLOB': `MYSQL_TYPE_LONG_BLOB' `char[]' blob, *Note `LONGTEXT': blob. *Note `BIT': bit-type. `MYSQL_TYPE_BIT' `char[]'  File: manual.info, Node: c-api-prepared-statement-type-conversions, Prev: c-api-prepared-statement-type-codes, Up: c-api-prepared-statement-data-structures 21.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 *Note `FLOAT': floating-point-types. column, MySQL converts the value to floating-point format before storing it. * If you fetch an SQL *Note `MEDIUMINT': integer-types. 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 *Note `MEDIUMINT': integer-types. 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 *Note `DECIMAL': fixed-point-types. 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, *Note `mysql_stmt_fetch()': mysql-stmt-fetch. stores the value in the buffer as a string without conversion. If instead you specify a numeric variable and type code, *Note `mysql_stmt_fetch()': mysql-stmt-fetch. converts the string-format *Note `DECIMAL': fixed-point-types. value to numeric form. * For the `MYSQL_TYPE_BIT' type code, *Note `BIT': bit-type. 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 *Note `mysql_stmt_result_metadata()': mysql-stmt-result-metadata. after executing the prepared statement with *Note `mysql_stmt_execute()': mysql-stmt-execute. The metadata provides access to the type codes for the result set as described in *Note mysql-stmt-result-metadata::, and *Note 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 *Note c-api-data-structures::). If so, the character set is `binary', which indicates binary rather than nonbinary data. This enables you to distinguish *Note `BINARY': binary-varbinary. from *Note `CHAR': char, *Note `VARBINARY': binary-varbinary. from *Note `VARCHAR': char, and the *Note `BLOB': blob. types from the *Note `TEXT': blob. types. If you cause the `max_length' member of the `MYSQL_FIELD' column metadata structures to be set (by calling *Note `mysql_stmt_attr_set()': 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. As of MySQL 5.1.25, 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 *Note statement-repreparation::.  File: manual.info, Node: c-api-prepared-statement-function-overview, Next: c-api-prepared-statement-functions, Prev: c-api-prepared-statement-data-structures, Up: c-api 21.8.10 C API Prepared Statement Function Overview -------------------------------------------------- The functions available for prepared statement processing are summarized here and described in greater detail in a later section. See *Note c-api-prepared-statement-functions::. This table lists functions that are available for C API prepared statement processing and provides a description of each function. Function Description *Note Returns the number of rows changed, deleted, or `mysql_stmt_affected_rows()':inserted by prepared *Note `UPDATE': update, mysql-stmt-affected-rows.*Note `DELETE': delete, or *Note `INSERT': insert. statement *Note Gets value of an attribute for a prepared `mysql_stmt_attr_get()':statement mysql-stmt-attr-get. *Note Sets an attribute for a prepared statement `mysql_stmt_attr_set()': mysql-stmt-attr-set. *Note Associates application data buffers with the `mysql_stmt_bind_param()':parameter markers in a prepared SQL statement mysql-stmt-bind-param. *Note Associates application data buffers with columns `mysql_stmt_bind_result()':in a result set mysql-stmt-bind-result. *Note Frees memory used by a prepared statement `mysql_stmt_close()': mysql-stmt-close. *Note Seeks to an arbitrary row number in a statement `mysql_stmt_data_seek()':result set mysql-stmt-data-seek. *Note Returns the error number for the last statement `mysql_stmt_errno()': execution mysql-stmt-errno. *Note Returns the error message for the last statement `mysql_stmt_error()': execution mysql-stmt-error. *Note Executes a prepared statement `mysql_stmt_execute()': mysql-stmt-execute. *Note Fetches the next row of data from a result set `mysql_stmt_fetch()': and returns data for all bound columns mysql-stmt-fetch. *Note Fetch data for one column of the current row of `mysql_stmt_fetch_column()':a result set mysql-stmt-fetch-column. *Note Returns the number of result columns for the `mysql_stmt_field_count()':most recent statement mysql-stmt-field-count. *Note Free the resources allocated to a statement `mysql_stmt_free_result()':handle mysql-stmt-free-result. *Note Allocates memory for a `MYSQL_STMT' structure and `mysql_stmt_init()': initializes it mysql-stmt-init. *Note Returns the ID generated for an `AUTO_INCREMENT' `mysql_stmt_insert_id()':column by a prepared statement mysql-stmt-insert-id. *Note Returns the row count from a buffered statement `mysql_stmt_num_rows()':result set mysql-stmt-num-rows. *Note Returns the number of parameters in a prepared `mysql_stmt_param_count()':statement mysql-stmt-param-count. *Note (Return parameter metadata in the form of a `mysql_stmt_param_metadata()':result set) Currently, this function does nothing mysql-stmt-param-metadata. *Note Prepares an SQL statement string for execution `mysql_stmt_prepare()': mysql-stmt-prepare. *Note Resets the statement buffers in the server `mysql_stmt_reset()': mysql-stmt-reset. *Note Returns prepared statement metadata in the form `mysql_stmt_result_metadata()':of a result set mysql-stmt-result-metadata. *Note Seeks to a row offset in a statement result set, `mysql_stmt_row_seek()':using value returned from *Note mysql-stmt-row-seek. `mysql_stmt_row_tell()': mysql-stmt-row-tell. *Note Returns the statement row cursor position `mysql_stmt_row_tell()': mysql-stmt-row-tell. *Note Sends long data in chunks to server `mysql_stmt_send_long_data()': mysql-stmt-send-long-data. *Note Returns the SQLSTATE error code for the last `mysql_stmt_sqlstate()':statement execution mysql-stmt-sqlstate. *Note Retrieves a complete result set to the client `mysql_stmt_store_result()': mysql-stmt-store-result. Call *Note `mysql_stmt_init()': mysql-stmt-init. to create a statement handle, then *Note `mysql_stmt_prepare()': mysql-stmt-prepare. to prepare the statement string, *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param. to supply the parameter data, and *Note `mysql_stmt_execute()': mysql-stmt-execute. to execute the statement. You can repeat the *Note `mysql_stmt_execute()': mysql-stmt-execute. by changing parameter values in the respective buffers supplied through *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param. You can send text or binary data in chunks to server using *Note `mysql_stmt_send_long_data()': mysql-stmt-send-long-data. See *Note mysql-stmt-send-long-data::. If the statement is a *Note `SELECT': select. or any other statement that produces a result set, *Note `mysql_stmt_prepare()': mysql-stmt-prepare. also returns the result set metadata information in the form of a `MYSQL_RES' result set through *Note `mysql_stmt_result_metadata()': mysql-stmt-result-metadata. You can supply the result buffers using *Note `mysql_stmt_bind_result()': mysql-stmt-bind-result, so that the *Note `mysql_stmt_fetch()': mysql-stmt-fetch. automatically returns data to these buffers. This is row-by-row fetching. When statement execution has been completed, close the statement handle using *Note `mysql_stmt_close()': mysql-stmt-close. so that all resources associated with it can be freed. If you obtained a *Note `SELECT': select. statement's result set metadata by calling *Note `mysql_stmt_result_metadata()': mysql-stmt-result-metadata, you should also free the metadata using *Note `mysql_free_result()': mysql-free-result. * Execution Steps * To prepare and execute a statement, an application follows these steps: 1. Create a prepared statement handle with *Note `mysql_stmt_init()': mysql-stmt-init. To prepare the statement on the server, call *Note `mysql_stmt_prepare()': mysql-stmt-prepare. and pass it a string containing the SQL statement. 2. If the statement will produce a result set, call *Note `mysql_stmt_result_metadata()': 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 *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param. All parameters must be set. Otherwise, statement execution returns an error or produces unexpected results. 4. Call *Note `mysql_stmt_execute()': 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 *Note `mysql_stmt_bind_result()': mysql-stmt-bind-result. 6. Fetch the data into the buffers row by row by calling *Note `mysql_stmt_fetch()': 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 *Note `mysql_stmt_prepare()': 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 *Note `mysql_stmt_execute()': mysql-stmt-execute. is called, the MySQL client/server protocol performs these actions: * The client uses the statement handle 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 *Note `mysql_stmt_fetch()': 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 *Note `mysql_stmt_errno()': mysql-stmt-errno, *Note `mysql_stmt_error()': mysql-stmt-error, and *Note `mysql_stmt_sqlstate()': mysql-stmt-sqlstate, respectively. * Prepared Statement Logging * For prepared statements that are executed with the *Note `mysql_stmt_prepare()': mysql-stmt-prepare. and *Note `mysql_stmt_execute()': 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 *Note `mysql_stmt_prepare()': mysql-stmt-prepare. to prepare the statement string `"SELECT ?"'. 2. Call *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param. to bind the value `3' to the parameter in the prepared statement. 3. Call *Note `mysql_stmt_execute()': 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.  File: manual.info, Node: c-api-prepared-statement-functions, Next: c-api-thread-functions, Prev: c-api-prepared-statement-function-overview, Up: c-api 21.8.11 C API Prepared Statement Function Descriptions ------------------------------------------------------ * Menu: * mysql-stmt-affected-rows:: `mysql_stmt_affected_rows()' * mysql-stmt-attr-get:: `mysql_stmt_attr_get()' * mysql-stmt-attr-set:: `mysql_stmt_attr_set()' * mysql-stmt-bind-param:: `mysql_stmt_bind_param()' * mysql-stmt-bind-result:: `mysql_stmt_bind_result()' * mysql-stmt-close:: `mysql_stmt_close()' * mysql-stmt-data-seek:: `mysql_stmt_data_seek()' * mysql-stmt-errno:: `mysql_stmt_errno()' * mysql-stmt-error:: `mysql_stmt_error()' * mysql-stmt-execute:: `mysql_stmt_execute()' * mysql-stmt-fetch:: `mysql_stmt_fetch()' * mysql-stmt-fetch-column:: `mysql_stmt_fetch_column()' * mysql-stmt-field-count:: `mysql_stmt_field_count()' * mysql-stmt-free-result:: `mysql_stmt_free_result()' * mysql-stmt-init:: `mysql_stmt_init()' * mysql-stmt-insert-id:: `mysql_stmt_insert_id()' * mysql-stmt-num-rows:: `mysql_stmt_num_rows()' * mysql-stmt-param-count:: `mysql_stmt_param_count()' * mysql-stmt-param-metadata:: `mysql_stmt_param_metadata()' * mysql-stmt-prepare:: `mysql_stmt_prepare()' * mysql-stmt-reset:: `mysql_stmt_reset()' * mysql-stmt-result-metadata:: `mysql_stmt_result_metadata()' * mysql-stmt-row-seek:: `mysql_stmt_row_seek()' * mysql-stmt-row-tell:: `mysql_stmt_row_tell()' * mysql-stmt-send-long-data:: `mysql_stmt_send_long_data()' * mysql-stmt-sqlstate:: `mysql_stmt_sqlstate()' * mysql-stmt-store-result:: `mysql_stmt_store_result()' 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' handle, use the *Note `mysql_stmt_init()': mysql-stmt-init. function.  File: manual.info, Node: mysql-stmt-affected-rows, Next: mysql-stmt-attr-get, Prev: c-api-prepared-statement-functions, Up: c-api-prepared-statement-functions 21.8.11.1 `mysql_stmt_affected_rows()' ...................................... `my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)' * Description * *Note `mysql_stmt_affected_rows()': mysql-stmt-affected-rows. may be called immediately after executing a statement with *Note `mysql_stmt_execute()': mysql-stmt-execute. It is like *Note `mysql_affected_rows()': mysql-affected-rows. but for prepared statements. For a description of what the affected-rows value returned by this function means, See *Note mysql-affected-rows::. * Errors * None. * Example * See the Example in *Note mysql-stmt-execute::.  File: manual.info, Node: mysql-stmt-attr-get, Next: mysql-stmt-attr-set, Prev: mysql-stmt-affected-rows, Up: c-api-prepared-statement-functions 21.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 *Note mysql-stmt-attr-set::, for a list of options and option types. *Note*: In MySQL 5.1, *Note `mysql_stmt_attr_get()': mysql-stmt-attr-get. originally used `unsigned int *', not `my_bool *', for `STMT_ATTR_UPDATE_MAX_LENGTH'. This was corrected in MySQL 5.1.7. * Return Values * Zero if successful. Nonzero if `option' is unknown. * Errors * None.  File: manual.info, Node: mysql-stmt-attr-set, Next: mysql-stmt-bind-param, Prev: mysql-stmt-attr-get, Up: c-api-prepared-statement-functions 21.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. This table lists *Note `mysql_stmt_attr_set()': mysql-stmt-attr-set. option values along with the argument type and function of each option. Option Argument Type Function `STMT_ATTR_UPDATE_MAX_LENGTH' `my_bool *' If set to 1, causes *Note `mysql_stmt_store_result()': mysql-stmt-store-result. to update the metadata `MYSQL_FIELD->max_length' value. `STMT_ATTR_CURSOR_TYPE' `unsigned Type of cursor to open for long *' statement when *Note `mysql_stmt_execute()': 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 *Note `mysql_stmt_execute()': mysql-stmt-execute. If there is already an open cursor from a previous *Note `mysql_stmt_execute()': mysql-stmt-execute. call, it closes the cursor before opening a new one. *Note `mysql_stmt_reset()': mysql-stmt-reset. also closes any open cursor before preparing the statement for re-execution. *Note `mysql_stmt_free_result()': mysql-stmt-free-result. closes any open cursor. If you open a cursor for a prepared statement, *Note `mysql_stmt_store_result()': mysql-stmt-store-result. is unnecessary, because that function causes the result set to be buffered on the client side. * Return Values * Zero if successful. 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 ... */  File: manual.info, Node: mysql-stmt-bind-param, Next: mysql-stmt-bind-result, Prev: mysql-stmt-attr-set, Up: c-api-prepared-statement-functions 21.8.11.4 `mysql_stmt_bind_param()' ................................... `my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)' * Description * *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param. is used to bind input data for the parameter markers in the SQL statement that was passed to *Note `mysql_stmt_prepare()': 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]; *Note 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 if the bind operation was successful. 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 *Note mysql-stmt-execute::.  File: manual.info, Node: mysql-stmt-bind-result, Next: mysql-stmt-close, Prev: mysql-stmt-bind-param, Up: c-api-prepared-statement-functions 21.8.11.5 `mysql_stmt_bind_result()' .................................... `my_bool mysql_stmt_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)' * Description * *Note `mysql_stmt_bind_result()': mysql-stmt-bind-result. is used to associate (that is, bind) output columns in the result set to data buffers and length buffers. When *Note `mysql_stmt_fetch()': 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 *Note `mysql_stmt_fetch()': 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, *Note `mysql_stmt_fetch()': mysql-stmt-fetch. simply ignores the data fetch. The buffers should be large enough to hold the data values, because the protocol doesn't 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 *Note `mysql_stmt_fetch()': mysql-stmt-fetch. is called. Suppose that an application binds the columns in a result set and calls *Note `mysql_stmt_fetch()': 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 *Note `mysql_stmt_fetch()': mysql-stmt-fetch. occurs. To bind a column, an application calls *Note `mysql_stmt_bind_result()': mysql-stmt-bind-result. and passes the type, address, and length of the output buffer into which the value should be stored. *Note 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 if the bind operation was successful. 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 *Note mysql-stmt-fetch::.  File: manual.info, Node: mysql-stmt-close, Next: mysql-stmt-data-seek, Prev: mysql-stmt-bind-result, Up: c-api-prepared-statement-functions 21.8.11.6 `mysql_stmt_close()' .............................. `my_bool mysql_stmt_close(MYSQL_STMT *)' * Description * Closes the prepared statement. *Note `mysql_stmt_close()': mysql-stmt-close. also deallocates the statement handle pointed to by `stmt'. If the current statement has pending or unread results, this function cancels them so that the next query can be executed. * Return Values * Zero if the statement was freed successfully. 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 *Note mysql-stmt-execute::.  File: manual.info, Node: mysql-stmt-data-seek, Next: mysql-stmt-errno, Prev: mysql-stmt-close, Up: c-api-prepared-statement-functions 21.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 *Note `mysql_stmt_num_rows(stmt)-1': mysql-stmt-num-rows. This function requires that the statement result set structure contains the entire result of the last executed query, so *Note `mysql_stmt_data_seek()': mysql-stmt-data-seek. may be used only in conjunction with *Note `mysql_stmt_store_result()': mysql-stmt-store-result. * Return Values * None. * Errors * None.  File: manual.info, Node: mysql-stmt-errno, Next: mysql-stmt-error, Prev: mysql-stmt-data-seek, Up: c-api-prepared-statement-functions 21.8.11.8 `mysql_stmt_errno()' .............................. `unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)' * Description * For the statement specified by `stmt', *Note `mysql_stmt_errno()': 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 *Note error-handling::. * Return Values * An error code value. Zero if no error occurred. * Errors * None.  File: manual.info, Node: mysql-stmt-error, Next: mysql-stmt-execute, Prev: mysql-stmt-errno, Up: c-api-prepared-statement-functions 21.8.11.9 `mysql_stmt_error()' .............................. `const char *mysql_stmt_error(MYSQL_STMT *stmt)' * Description * For the statement specified by `stmt', *Note `mysql_stmt_error()': 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 } The language of the client error messages may be changed by recompiling the MySQL client library. Currently, 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.  File: manual.info, Node: mysql-stmt-execute, Next: mysql-stmt-fetch, Prev: mysql-stmt-error, Up: c-api-prepared-statement-functions 21.8.11.10 `mysql_stmt_execute()' ................................. `int mysql_stmt_execute(MYSQL_STMT *stmt)' * Description * *Note `mysql_stmt_execute()': mysql-stmt-execute. executes the prepared query associated with the statement handle. 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 *Note `mysql_stmt_execute()': mysql-stmt-execute. depends on the type of statement: * For an *Note `UPDATE': update, *Note `DELETE': delete, or *Note `INSERT': insert, the number of changed, deleted, or inserted rows can be found by calling *Note `mysql_stmt_affected_rows()': mysql-stmt-affected-rows. * For a statement such as *Note `SELECT': select. that generates a result set, you must call *Note `mysql_stmt_fetch()': 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 *Note mysql-stmt-fetch::. Do not following invocation of *Note `mysql_stmt_execute()': mysql-stmt-execute. with a call to *Note `mysql_store_result()': mysql-store-result. or *Note `mysql_use_result()': 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 *Note `mysql_stmt_execute()': mysql-stmt-execute. open a cursor for the statement by calling *Note `mysql_stmt_attr_set()': mysql-stmt-attr-set. before executing the statement. If you execute a statement multiple times, *Note `mysql_stmt_execute()': mysql-stmt-execute. closes any open cursor before opening a new one. As of MySQL 5.1.25, 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 *Note statement-repreparation::. * Return Values * Zero if execution was successful. 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 *Note `mysql_stmt_init()': mysql-stmt-init, *Note `mysql_stmt_prepare()': mysql-stmt-prepare, *Note `mysql_stmt_param_count()': mysql-stmt-param-count, *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param, *Note `mysql_stmt_execute()': mysql-stmt-execute, and *Note `mysql_stmt_affected_rows()': mysql-stmt-affected-rows. The `mysql' variable is assumed to be a valid connection handle. For an example that shows how to retrieve data, see *Note 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)) { fprintf(stderr, " failed while closing the statement\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); 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 Bazaar source repository.  File: manual.info, Node: mysql-stmt-fetch, Next: mysql-stmt-fetch-column, Prev: mysql-stmt-execute, Up: c-api-prepared-statement-functions 21.8.11.11 `mysql_stmt_fetch()' ............................... `int mysql_stmt_fetch(MYSQL_STMT *stmt)' * Description * *Note `mysql_stmt_fetch()': 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 *Note `mysql_stmt_execute()': mysql-stmt-execute. for a statement such as *Note `SELECT': select. that produces a result set. *Note `mysql_stmt_fetch()': mysql-stmt-fetch. returns row data using the buffers bound by *Note `mysql_stmt_bind_result()': 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 *Note `mysql_stmt_fetch()': 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 *Note `mysql_stmt_store_result()': mysql-stmt-store-result. after binding the data buffers and before calling *Note `mysql_stmt_fetch()': 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'. This table lists numeric and temporal MySQL types and provides the fixed length of each type. 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 *Note `mysql_stmt_fetch()': mysql-stmt-fetch. For example, the value might be a long string or *Note `BLOB': blob. value for which you want to know how much space must be allocated. To accomplish this, you can use these strategies: * Before invoking *Note `mysql_stmt_fetch()': mysql-stmt-fetch. to retrieve individual rows, pass `STMT_ATTR_UPDATE_MAX_LENGTH' to *Note `mysql_stmt_attr_set()': mysql-stmt-attr-set, then invoke *Note `mysql_stmt_store_result()': 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 *Note `mysql_stmt_result_metadata()': mysql-stmt-result-metadata. * Invoke *Note `mysql_stmt_fetch()': 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 *Note `mysql_stmt_fetch_column()': 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 * This table lists return values for *Note `mysql_stmt_fetch()': mysql-stmt-fetch. and provides a description of each value. 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 *Note `mysql_stmt_errno()': mysql-stmt-errno. and *Note `mysql_stmt_error()': 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 *Note `mysql_options()': 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 *Note `DATE': datetime, *Note `TIME': time, *Note `DATETIME': datetime, or *Note `TIMESTAMP': datetime. * All other unsupported conversion errors are returned from *Note `mysql_stmt_bind_result()': mysql-stmt-bind-result. * Example * The following example demonstrates how to fetch data from a table using *Note `mysql_stmt_result_metadata()': mysql-stmt-result-metadata, *Note `mysql_stmt_bind_result()': mysql-stmt-bind-result, and *Note `mysql_stmt_fetch()': mysql-stmt-fetch. (This example expects to retrieve the two rows inserted by the example shown in *Note mysql-stmt-execute::.) The `mysql' variable is assumed to be a valid connection handle. #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)) { fprintf(stderr, " failed while closing the statement\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); }  File: manual.info, Node: mysql-stmt-fetch-column, Next: mysql-stmt-field-count, Prev: mysql-stmt-fetch, Up: c-api-prepared-statement-functions 21.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 * Fetch 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 *Note `mysql_stmt_bind_result()': 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 if the value was fetched successfully. 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.  File: manual.info, Node: mysql-stmt-field-count, Next: mysql-stmt-free-result, Prev: mysql-stmt-fetch-column, Up: c-api-prepared-statement-functions 21.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 *Note `INSERT': insert. or *Note `DELETE': delete. that do not produce result sets. *Note `mysql_stmt_field_count()': mysql-stmt-field-count. can be called after you have prepared a statement by invoking *Note `mysql_stmt_prepare()': mysql-stmt-prepare. * Return Values * An unsigned integer representing the number of columns in a result set. * Errors * None.  File: manual.info, Node: mysql-stmt-free-result, Next: mysql-stmt-init, Prev: mysql-stmt-field-count, Up: c-api-prepared-statement-functions 21.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, *Note `mysql_stmt_free_result()': mysql-stmt-free-result. closes it. * Return Values * Zero if the result set was freed successfully. Nonzero if an error occurred. * Errors *  File: manual.info, Node: mysql-stmt-init, Next: mysql-stmt-insert-id, Prev: mysql-stmt-free-result, Up: c-api-prepared-statement-functions 21.8.11.15 `mysql_stmt_init()' .............................. `MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)' * Description * Create a `MYSQL_STMT' handle. The handle should be freed with *Note `mysql_stmt_close(MYSQL_STMT *)': mysql-stmt-close. See also *Note 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.  File: manual.info, Node: mysql-stmt-insert-id, Next: mysql-stmt-num-rows, Prev: mysql-stmt-init, Up: c-api-prepared-statement-functions 21.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 *Note `INSERT': insert. or *Note `UPDATE': update. statement. Use this function after you have executed a prepared *Note `INSERT': insert. statement on a table which contains an `AUTO_INCREMENT' field. See *Note 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.  File: manual.info, Node: mysql-stmt-num-rows, Next: mysql-stmt-param-count, Prev: mysql-stmt-insert-id, Up: c-api-prepared-statement-functions 21.8.11.17 `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 *Note `mysql_stmt_num_rows()': mysql-stmt-num-rows. depends on whether you used *Note `mysql_stmt_store_result()': mysql-stmt-store-result. to buffer the entire result set in the statement handle. If you use *Note `mysql_stmt_store_result()': mysql-stmt-store-result, *Note `mysql_stmt_num_rows()': mysql-stmt-num-rows. may be called immediately. Otherwise, the row count is unavailable unless you count the rows as you fetch them. *Note `mysql_stmt_num_rows()': mysql-stmt-num-rows. is intended for use with statements that return a result set, such as *Note `SELECT': select. For statements such as *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': delete, the number of affected rows can be obtained with *Note `mysql_stmt_affected_rows()': mysql-stmt-affected-rows. * Return Values * The number of rows in the result set. * Errors * None.  File: manual.info, Node: mysql-stmt-param-count, Next: mysql-stmt-param-metadata, Prev: mysql-stmt-num-rows, Up: c-api-prepared-statement-functions 21.8.11.18 `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 *Note mysql-stmt-execute::.  File: manual.info, Node: mysql-stmt-param-metadata, Next: mysql-stmt-prepare, Prev: mysql-stmt-param-count, Up: c-api-prepared-statement-functions 21.8.11.19 `mysql_stmt_param_metadata()' ........................................ `MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)' This function currently does nothing. * Description * * Return Values * * Errors *  File: manual.info, Node: mysql-stmt-prepare, Next: mysql-stmt-reset, Prev: mysql-stmt-param-metadata, Up: c-api-prepared-statement-functions 21.8.11.20 `mysql_stmt_prepare()' ................................. `int mysql_stmt_prepare(MYSQL_STMT *stmt, const char *stmt_str, unsigned long length)' * Description * Given the statement handle returned by *Note `mysql_stmt_init()': 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 *Note `INSERT': 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 *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param. before executing the statement. * Return Values * Zero if the statement was prepared successfully. 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, *Note `mysql_stmt_prepare()': mysql-stmt-prepare. returns nonzero), the error message can be obtained by calling *Note `mysql_stmt_error()': mysql-stmt-error. * Example * See the Example in *Note mysql-stmt-execute::.  File: manual.info, Node: mysql-stmt-reset, Next: mysql-stmt-result-metadata, Prev: mysql-stmt-prepare, Up: c-api-prepared-statement-functions 21.8.11.21 `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 *Note `mysql_stmt_send_long_data()': 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 *Note `mysql_stmt_prepare()': mysql-stmt-prepare. * Return Values * Zero if the statement was reset successfully. 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.  File: manual.info, Node: mysql-stmt-result-metadata, Next: mysql-stmt-row-seek, Prev: mysql-stmt-reset, Up: c-api-prepared-statement-functions 21.8.11.22 `mysql_stmt_result_metadata()' ......................................... `MYSQL_RES *mysql_stmt_result_metadata(MYSQL_STMT *stmt)' * Description * If a statement passed to *Note `mysql_stmt_prepare()': mysql-stmt-prepare. is one that produces a result set, *Note `mysql_stmt_result_metadata()': 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: * *Note `mysql_num_fields()': mysql-num-fields. * *Note `mysql_fetch_field()': mysql-fetch-field. * *Note `mysql_fetch_field_direct()': mysql-fetch-field-direct. * *Note `mysql_fetch_fields()': mysql-fetch-fields. * *Note `mysql_field_count()': mysql-field-count. * *Note `mysql_field_seek()': mysql-field-seek. * *Note `mysql_field_tell()': mysql-field-tell. * *Note `mysql_free_result()': mysql-free-result. The result set structure should be freed when you are done with it, which you can do by passing it to *Note `mysql_free_result()': mysql-free-result. This is similar to the way you free a result set obtained from a call to *Note `mysql_store_result()': mysql-store-result. The result set returned by *Note `mysql_stmt_result_metadata()': mysql-stmt-result-metadata. contains only metadata. It does not contain any row results. The rows are obtained by using the statement handle with *Note `mysql_stmt_fetch()': 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 *Note mysql-stmt-fetch::.  File: manual.info, Node: mysql-stmt-row-seek, Next: mysql-stmt-row-tell, Prev: mysql-stmt-result-metadata, Up: c-api-prepared-statement-functions 21.8.11.23 `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 *Note `mysql_stmt_row_tell()': mysql-stmt-row-tell. or from *Note `mysql_stmt_row_seek()': 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 *Note `mysql_stmt_data_seek()': mysql-stmt-data-seek. instead. This function requires that the result set structure contains the entire result of the query, so *Note `mysql_stmt_row_seek()': mysql-stmt-row-seek. may be used only in conjunction with *Note `mysql_stmt_store_result()': mysql-stmt-store-result. * Return Values * The previous value of the row cursor. This value may be passed to a subsequent call to *Note `mysql_stmt_row_seek()': mysql-stmt-row-seek. * Errors * None.  File: manual.info, Node: mysql-stmt-row-tell, Next: mysql-stmt-send-long-data, Prev: mysql-stmt-row-seek, Up: c-api-prepared-statement-functions 21.8.11.24 `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 *Note `mysql_stmt_fetch()': mysql-stmt-fetch. This value can be used as an argument to *Note `mysql_stmt_row_seek()': mysql-stmt-row-seek. You should use *Note `mysql_stmt_row_tell()': mysql-stmt-row-tell. only after *Note `mysql_stmt_store_result()': mysql-stmt-store-result. * Return Values * The current offset of the row cursor. * Errors * None.  File: manual.info, Node: mysql-stmt-send-long-data, Next: mysql-stmt-sqlstate, Prev: mysql-stmt-row-tell, Up: c-api-prepared-statement-functions 21.8.11.25 `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 *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param. and before *Note `mysql_stmt_execute()': 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 *Note `TEXT': blob. or *Note `BLOB': 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 *Note `mysql_stmt_execute()': mysql-stmt-execute. call ignores the bind buffer for all parameters that have been used with *Note `mysql_stmt_send_long_data()': mysql-stmt-send-long-data. since last *Note `mysql_stmt_execute()': mysql-stmt-execute. or *Note `mysql_stmt_reset()': mysql-stmt-reset. If you want to reset/forget the sent data, you can do it with *Note `mysql_stmt_reset()': mysql-stmt-reset. See *Note mysql-stmt-reset::. As of MySQL 5.1.57, the `max_long_data_size' system variable controls the maximum size of parameter values that can be sent with *Note `mysql_stmt_send_long_data()': mysql-stmt-send-long-data. If this variable not set at server startup, the default is the value of the `max_allowed_packet' system variable. `max_long_data_size' is deprecated. In MySQL 5.6, it is removed and the maximum parameter size is controlled by `max_allowed_packet'. * Return Values * Zero if the data is sent successfully to server. Nonzero if an error occurred. * Errors * * `CR_INVALID_BUFFER_USE' The parameter does not have a string or binary type. * `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 *Note `TEXT': blob. 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 handle. #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); }  File: manual.info, Node: mysql-stmt-sqlstate, Next: mysql-stmt-store-result, Prev: mysql-stmt-send-long-data, Up: c-api-prepared-statement-functions 21.8.11.26 `mysql_stmt_sqlstate()' .................................. `const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)' * Description * For the statement specified by `stmt', *Note `mysql_stmt_sqlstate()': 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 *Note error-handling::. Note that not all MySQL errors are yet mapped to SQLSTATE codes. The value `"HY000"' (general error) is used for unmapped errors. * Return Values * A null-terminated character string containing the SQLSTATE error code.  File: manual.info, Node: mysql-stmt-store-result, Prev: mysql-stmt-sqlstate, Up: c-api-prepared-statement-functions 21.8.11.27 `mysql_stmt_store_result()' ...................................... `int mysql_stmt_store_result(MYSQL_STMT *stmt)' * Description * Result sets are produced by calling *Note `mysql_stmt_execute()': mysql-stmt-execute. to executed prepared statements for SQL statements such as *Note `SELECT': select, *Note `SHOW': show, *Note `DESCRIBE': describe, and *Note `EXPLAIN': explain. By default, result sets for successfully executed prepared statements are not buffered on the client and *Note `mysql_stmt_fetch()': 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 *Note `mysql_stmt_store_result()': mysql-stmt-store-result. after binding data buffers with *Note `mysql_stmt_bind_result()': mysql-stmt-bind-result. and before calling *Note `mysql_stmt_fetch()': mysql-stmt-fetch. to fetch rows. (For an example, see *Note mysql-stmt-fetch::.) *Note `mysql_stmt_store_result()': mysql-stmt-store-result. is optional for result set processing, unless you will call *Note `mysql_stmt_data_seek()': mysql-stmt-data-seek, *Note `mysql_stmt_row_seek()': mysql-stmt-row-seek, or *Note `mysql_stmt_row_tell()': mysql-stmt-row-tell. Those functions require a seekable result set. It is unnecessary to call *Note `mysql_stmt_store_result()': 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 *Note `mysql_stmt_result_metadata()': mysql-stmt-result-metadata. returns `NULL'. For more information, refer to *Note mysql-stmt-result-metadata::. *Note*: MySQL doesn't by default calculate `MYSQL_FIELD->max_length' for all columns in *Note `mysql_stmt_store_result()': mysql-stmt-store-result. because calculating this would slow down *Note `mysql_stmt_store_result()': mysql-stmt-store-result. considerably and most applications don't need `max_length'. If you want `max_length' to be updated, you can call *Note `mysql_stmt_attr_set(MYSQL_STMT, STMT_ATTR_UPDATE_MAX_LENGTH, &flag)': mysql-stmt-attr-set. to enable this. See *Note mysql-stmt-attr-set::. * Return Values * Zero if the results are buffered successfully. 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 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.  File: manual.info, Node: c-api-thread-functions, Next: c-api-embedded-server-functions, Prev: c-api-prepared-statement-functions, Up: c-api 21.8.12 C API Threaded Function Descriptions -------------------------------------------- * Menu: * my-init:: `my_init()' * mysql-thread-end:: `mysql_thread_end()' * mysql-thread-init:: `mysql_thread_init()' * mysql-thread-safe:: `mysql_thread_safe()' To create a threaded client, use the functions described in the following sections. See also *Note c-api-threaded-clients::.  File: manual.info, Node: my-init, Next: mysql-thread-end, Prev: c-api-thread-functions, Up: c-api-thread-functions 21.8.12.1 `my_init()' ..................... `void my_init(void)' * Description * *Note `my_init()': my-init. initializes some global variables that MySQL needs. If you are using a thread-safe client library, it also calls *Note `mysql_thread_init()': mysql-thread-init. for this thread. It is necessary for *Note `my_init()': my-init. to be called early in the initialization phase of a program's use of the MySQL library. However, *Note `my_init()': my-init. is automatically called by *Note `mysql_init()': mysql-init, *Note `mysql_library_init()': mysql-library-init, *Note `mysql_server_init()': mysql-server-init, and *Note `mysql_connect()': mysql-connect. If you ensure that your program invokes one of those functions before any other MySQL calls, there is no need to invoke *Note `my_init()': my-init. explicitly. To access the prototype for *Note `my_init()': my-init, your program should include these header files: #include #include * Return Values * None.  File: manual.info, Node: mysql-thread-end, Next: mysql-thread-init, Prev: my-init, Up: c-api-thread-functions 21.8.12.2 `mysql_thread_end()' .............................. `void mysql_thread_end(void)' * Description * This function needs to be called before calling `pthread_exit()' to free memory allocated by *Note `mysql_thread_init()': mysql-thread-init. *Note `mysql_thread_end()': mysql-thread-end. _is not invoked automatically by the client library_. It must be called explicitly to avoid a memory leak. * Return Values * None.  File: manual.info, Node: mysql-thread-init, Next: mysql-thread-safe, Prev: mysql-thread-end, Up: c-api-thread-functions 21.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: *Note `mysql_thread_init()': mysql-thread-init. is automatically called by *Note `my_init()': my-init, which itself is automatically called by *Note `mysql_init()': mysql-init, *Note `mysql_library_init()': mysql-library-init, *Note `mysql_server_init()': mysql-server-init, and *Note `mysql_connect()': mysql-connect. If you invoke any of those functions, *Note `mysql_thread_init()': mysql-thread-init. will be called for you. * Return Values * Zero if successful. Nonzero if an error occurred.  File: manual.info, Node: mysql-thread-safe, Prev: mysql-thread-init, Up: c-api-thread-functions 21.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.  File: manual.info, Node: c-api-embedded-server-functions, Next: c-api-problems, Prev: c-api-thread-functions, Up: c-api 21.8.13 C API Embedded Server Function Descriptions --------------------------------------------------- * Menu: * mysql-server-init:: `mysql_server_init()' * mysql-server-end:: `mysql_server_end()' MySQL applications can be written to use an embedded server. See *Note 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 *Note `mysql_library_init()': mysql-library-init. to initialize the library and *Note `mysql_library_end()': mysql-library-end. when you are done with it. See *Note c-api-function-overview::.  File: manual.info, Node: mysql-server-init, Next: mysql-server-end, Prev: c-api-embedded-server-functions, Up: c-api-embedded-server-functions 21.8.13.1 `mysql_server_init()' ............................... `int mysql_server_init(int argc, char **argv, char **groups)' * Description * This function initializes the MySQL library, which must be done before you call any other MySQL function. However, *Note `mysql_server_init()': mysql-server-init. is deprecated and you should call *Note `mysql_library_init()': mysql-library-init. instead. See *Note mysql-library-init::. * Return Values * Zero if successful. Nonzero if an error occurred.  File: manual.info, Node: mysql-server-end, Prev: mysql-server-init, Up: c-api-embedded-server-functions 21.8.13.2 `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, *Note `mysql_server_end()': mysql-server-end. is deprecated and *Note `mysql_library_end()': mysql-library-end. should be used instead. See *Note mysql-library-end::. * Return Values * None.  File: manual.info, Node: c-api-problems, Next: auto-reconnect, Prev: c-api-embedded-server-functions, Up: c-api 21.8.14 Common Questions and Problems When Using the C API ---------------------------------------------------------- * Menu: * null-mysql-store-result:: Why `mysql_store_result()' Sometimes Returns `NULL' After `mysql_query()' Returns Success * query-results:: What Results You Can Get from a Query * getting-unique-id:: How to Get the Unique ID for the Last Inserted Row  File: manual.info, Node: null-mysql-store-result, Next: query-results, Prev: c-api-problems, Up: c-api-problems 21.8.14.1 Why `mysql_store_result()' Sometimes Returns `NULL' After `mysql_query()' Returns Success ................................................................................................... It is possible for *Note `mysql_store_result()': mysql-store-result. to return `NULL' following a successful call to *Note `mysql_query()': 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 *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': delete.). You can always check whether the statement should have produced a nonempty result by calling *Note `mysql_field_count()': mysql-field-count. If *Note `mysql_field_count()': mysql-field-count. returns zero, the result is empty and the last query was a statement that does not return values (for example, an *Note `INSERT': insert. or a *Note `DELETE': delete.). If *Note `mysql_field_count()': mysql-field-count. returns a nonzero value, the statement should have produced a nonempty result. See the description of the *Note `mysql_field_count()': mysql-field-count. function for an example. You can test for an error by calling *Note `mysql_error()': mysql-error. or *Note `mysql_errno()': mysql-errno.  File: manual.info, Node: query-results, Next: getting-unique-id, Prev: null-mysql-store-result, Up: c-api-problems 21.8.14.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: * *Note `mysql_affected_rows()': mysql-affected-rows. returns the number of rows affected by the last query when doing an *Note `INSERT': insert, *Note `UPDATE': update, or *Note `DELETE': delete. For a fast re-create, use *Note `TRUNCATE TABLE': truncate-table. * *Note `mysql_num_rows()': mysql-num-rows. returns the number of rows in a result set. With *Note `mysql_store_result()': mysql-store-result, *Note `mysql_num_rows()': mysql-num-rows. may be called as soon as *Note `mysql_store_result()': mysql-store-result. returns. With *Note `mysql_use_result()': mysql-use-result, *Note `mysql_num_rows()': mysql-num-rows. may be called only after you have fetched all the rows with *Note `mysql_fetch_row()': mysql-fetch-row. * *Note `mysql_insert_id()': mysql-insert-id. returns the ID generated by the last query that inserted a row into a table with an `AUTO_INCREMENT' index. See *Note mysql-insert-id::. * Some queries (*Note `LOAD DATA INFILE ...': load-data, *Note `INSERT INTO ... SELECT ...': insert-select, *Note `UPDATE': update.) return additional information. The result is returned by *Note `mysql_info()': mysql-info. See the description for *Note `mysql_info()': mysql-info. for the format of the string that it returns. *Note `mysql_info()': mysql-info. returns a `NULL' pointer if there is no additional information.  File: manual.info, Node: getting-unique-id, Prev: query-results, Up: c-api-problems 21.8.14.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 *Note `mysql_insert_id()': 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 *Note `INSERT': 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 *Note `mysql_query()': 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 Note that *Note `mysql_insert_id()': 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 *Note information-functions::. * For information on *Note `mysql_insert_id()': mysql-insert-id, the function you use from within the C API, see *Note mysql-insert-id::. * For information on obtaining the auto-incremented value when using Connector/J, see *Note connector-j-usagenotes-last-insert-id::. * For information on obtaining the auto-incremented value when using Connector/ODBC, see *Note connector-odbc-usagenotes-functionality-last-insert-id::.  File: manual.info, Node: auto-reconnect, Next: c-api-multiple-queries, Prev: c-api-problems, Up: c-api 21.8.15 Controlling Automatic Reconnection Behavior --------------------------------------------------- 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. In this case, the library tries once to reconnect to the server and send the statement again. In MySQL 5.1, auto-reconnect is disabled by default. If it is important for your application to know that the connection has been dropped (so that is can exit or take action to adjust for the loss of state information), be sure that auto-reconnect is disabled. To ensure this, call *Note `mysql_options()': 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 *Note `mysql_ping()': mysql-ping. depends on the auto-reconnect state. If auto-reconnect is enabled, *Note `mysql_ping()': mysql-ping. performs a reconnect. Otherwise, it returns an error. Some client programs might provide the capability of controlling automatic reconnection. For example, *Note `mysql': 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 *Note `mysql_ping()': mysql-ping.), there is no explicit indication of it. To check for reconnection, call *Note `mysql_thread_id()': mysql-thread-id. to get the original connection identifier before calling *Note `mysql_ping()': mysql-ping, then call *Note `mysql_thread_id()': mysql-thread-id. again to see whether the identifier has 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 know about it. 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 variables are reinitialized to the values of the corresponding variables. This also affects variables that are set implicitly by statements such as `SET NAMES'. * User variable settings are lost. * Prepared statements are released. * *Note `HANDLER': handler. variables are closed. * The value of `LAST_INSERT_ID()' is reset to 0. * Locks acquired with `GET_LOCK()' are released. 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 *Note `mysql_kill()': mysql-kill.  File: manual.info, Node: c-api-multiple-queries, Next: c-api-prepared-statement-problems, Prev: auto-reconnect, Up: c-api 21.8.16 C API Support for Multiple Statement Execution ------------------------------------------------------ By default, *Note `mysql_query()': mysql-query. and *Note `mysql_real_query()': 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 *Note `SELECT': select.) or an affected-rows count (as for *Note `INSERT': insert, *Note `UPDATE': update, and so forth). MySQL 5.1 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 *Note `mysql_real_connect()': mysql-real-connect. or after connecting by calling` *Note `mysql_set_server_option()': 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 *Note `mysql_more_results()': mysql-more-results. and *Note `mysql_next_result()': 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 *Note `CALL': 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 *Note `SELECT': 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 *Note `mysql_query()': mysql-query. or *Note `mysql_real_query()': mysql-real-query. They cannot be used with the prepared statement interface. Prepared statement handles are defined to work only with strings that contain a single statement. See *Note c-api-prepared-statements::. To enable multiple-statement execution and result processing, the following options may be used: * The *Note `mysql_real_connect()': 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 *Note `CALL': 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'. * `CLIENT_MULTI_STATEMENTS' enables *Note `mysql_query()': mysql-query. and *Note `mysql_real_query()': 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 *Note `mysql_real_connect()': 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 *Note `mysql_set_server_option()': 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 *Note `mysql_real_connect()': mysql-real-connect, to fully enable multiple-statement execution and multiple-result processing. 2. After calling *Note `mysql_query()': mysql-query. or *Note `mysql_real_query()': 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 *Note `mysql_next_result()': 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 *Note `mysql_next_result()': 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);  File: manual.info, Node: c-api-prepared-statement-problems, Next: c-api-prepared-statement-date-handling, Prev: c-api-multiple-queries, Up: c-api 21.8.17 C API Prepared Statement Problems ----------------------------------------- Here follows a list of the currently known problems with prepared statements: * *Note `TIME': time, *Note `TIMESTAMP': datetime, and *Note `DATETIME': 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 doesn't 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. * Before MySQL 5.1.17, prepared statements do not use the query cache. As of 5.1.17, prepared statements use the query cache under the conditions described in *Note query-cache-operation::. * Prepared statements do not support multi-statements (that is, multiple statements within a single string separated by ``;'' characters). * In MySQL 5.1, prepared *Note `CALL': call. statements cannot invoke stored procedures that return result sets because prepared statements do not support multiple result sets. Nor can the calling application access a stored procedure's `OUT' or `INOUT' parameters when the procedure returns. These capabilities are supported beginning with MySQL 5.5.  File: manual.info, Node: c-api-prepared-statement-date-handling, Next: c-api-prepared-call-statements, Prev: c-api-prepared-statement-problems, Up: c-api 21.8.18 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 (*Note `DATE': datetime, *Note `TIME': time, *Note `DATETIME': datetime, and *Note `TIMESTAMP': datetime.), using the `MYSQL_TIME' structure. The members of this structure are described in *Note c-api-prepared-statement-data-structures::. To send temporal data values, create a prepared statement using *Note `mysql_stmt_prepare()': mysql-stmt-prepare. Then, before calling *Note `mysql_stmt_execute()': 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 *Note `DATE': datetime, *Note `TIME': time, *Note `DATETIME': datetime, or *Note `TIMESTAMP': datetime. 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 be passed. Use *Note `mysql_stmt_bind_param()': mysql-stmt-bind-param. to bind the parameter data to the statement. Then you can call *Note `mysql_stmt_execute()': 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 *Note `mysql_stmt_bind_result()': mysql-stmt-bind-result. to bind the buffers to the statement after calling *Note `mysql_stmt_execute()': mysql-stmt-execute. and before fetching the results. Here is a simple example that inserts *Note `DATE': datetime, *Note `TIME': time, and *Note `TIMESTAMP': datetime. data. The `mysql' variable is assumed to be a valid connection handle. 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); ..  File: manual.info, Node: c-api-prepared-call-statements, Prev: c-api-prepared-statement-date-handling, Up: c-api 21.8.19 C API Support for Prepared `CALL' Statements ---------------------------------------------------- In MySQL 5.1, prepared *Note `CALL': call. statements can be used only for stored procedures that produce at most one result set. Nor can the calling application use placeholders for `OUT' or `INOUT' parameters. MySQL 5.5 expands prepared *Note `CALL': call. statement support for stored procedures that produce multiple result sets and to provide placeholder access to `OUT' and `INOUT' parameters.  File: manual.info, Node: apis-php, Next: apis-perl, Prev: c-api, Up: connectors-apis 21.9 MySQL PHP API ================== * Menu: * apis-php-mysqlinfo:: Overview of the MySQL PHP drivers * apis-php-book.mysqlnd-ms:: Mysqlnd replication and load balancing plugin (`mysqlnd_ms') * apis-php-book.mysqlnd-qc:: Mysqlnd query result cache plugin (`mysqlnd_qc') * apis-php-book.mysqlnd-uh:: Mysqlnd user handler plugin (`mysqlnd_uh') * apis-php-book.mysqlnd-mux:: Mysqlnd connection multiplexing plugin (`mysqlnd_mux') * apis-php-book.mysqlnd-memcache:: Mysqlnd Memcache plugin (`mysqlnd_memcache') * connector-php:: Connector/PHP * apis-php-problems:: Common Problems with MySQL and PHP * php-mysql-mysqli:: Enabling Both `mysql' and `mysqli' in PHP PHP is a server-side, HTML-embedded scripting language that may be used to create dynamic Web pages. It is available for most operating systems and Web servers, and can access most common databases, including MySQL. PHP may be run as a separate program or compiled as a module for use with a Web server. PHP provides three different MySQL API extensions: * See section "apis-php-mysqli" in the online manual: Stands for `MySQL, Improved'; this extension is available as of PHP 5.0.0. It is intended for use with MySQL 4.1.1 and later. This extension fully supports the authentication protocol used in MySQL 5.0, as well as the Prepared Statements and Multiple Statements APIs. In addition, this extension provides an advanced, object-oriented programming interface. * See section "apis-php-ref.pdo-mysql" in the online manual: Not its own API, but instead it's a MySQL driver for the PHP database abstraction layer PDO (PHP Data Objects). The PDO MySQL driver sits in the layer below PDO itself, and provides MySQL-specific functionality. This extension is available as of PHP 5.1.0. * See section "apis-php-mysql" in the online manual: Available for PHP versions 4 and 5, this extension is intended for use with MySQL versions prior to MySQL 4.1. This extension does not support the improved authentication protocol used in MySQL 4.1, nor does it support prepared statements or multiple statements. To use this extension with MySQL 4.1, you will likely configure the MySQL server to set the `old_passwords' system variable to 1 (see *Note old-client::). *Warning*: This extension was removed from PHP 5.5.0. All users must migrate to either `mysqli' or `PDO_MySQL'. For further information, see *Note apis-php-mysqlinfo.api.choosing::. The PHP distribution and documentation are available from the PHP Web site (http://www.php.net/). _Portions of this section are Copyright (c) 1997-2012 the PHP Documentation Group_ This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution 3.0 License or later. A copy of the Creative Commons Attribution 3.0 license is distributed with this manual. The latest version is presently available at http://creativecommons.org/licenses/by/3.0/ (http://creativecommons.org/licenses/by/3.0/).  File: manual.info, Node: apis-php-mysqlinfo, Next: apis-php-book.mysqlnd-ms, Prev: apis-php, Up: apis-php 21.9.1 Overview of the MySQL PHP drivers ---------------------------------------- * Menu: * apis-php-mysqlinfo.intro:: Introduction * apis-php-mysqlinfo.terminology:: Terminology overview * apis-php-mysqlinfo.api.choosing:: Choosing an API * apis-php-mysqlinfo.library.choosing:: Choosing a library * apis-php-mysqlinfo.concepts:: Concepts Copyright 1997-2012 the PHP Documentation Group.  File: manual.info, Node: apis-php-mysqlinfo.intro, Next: apis-php-mysqlinfo.terminology, Prev: apis-php-mysqlinfo, Up: apis-php-mysqlinfo 21.9.1.1 Introduction ..................... There are three PHP APIs for accessing the MySQL database. This guide explains the *Note terminology: apis-php-mysqlinfo.terminology. used to describe each API, information about *Note choosing which API: apis-php-mysqlinfo.api.choosing. to use, and also information to help choose which MySQL *Note library to use: apis-php-mysqlinfo.library.choosing. with the API.  File: manual.info, Node: apis-php-mysqlinfo.terminology, Next: apis-php-mysqlinfo.api.choosing, Prev: apis-php-mysqlinfo.intro, Up: apis-php-mysqlinfo 21.9.1.2 Terminology overview ............................. Copyright 1997-2012 the PHP Documentation Group. This section provides an introduction to the options available to you when developing a PHP application that needs to interact with a MySQL database. _What is an API?_ An Application Programming Interface, or API, defines the classes, methods, functions and variables that your application will need to call in order to carry out its desired task. In the case of PHP applications that need to communicate with databases the necessary APIs are usually exposed via PHP extensions. APIs can be procedural or object-oriented. With a procedural API you call functions to carry out tasks, with the object-oriented API you instantiate classes and then call methods on the resulting objects. Of the two the latter is usually the preferred interface, as it is more modern and leads to better organized code. When writing PHP applications that need to connect to the MySQL server there are several API options available. This document discusses what is available and how to select the best solution for your application. _What is a Connector?_ In the MySQL documentation, the term _connector_ refers to a piece of software that allows your application to connect to the MySQL database server. MySQL provides connectors for a variety of languages, including PHP. If your PHP application needs to communicate with a database server you will need to write PHP code to perform such activities as connecting to the database server, querying the database and other database-related functions. Software is required to provide the API that your PHP application will use, and also handle the communication between your application and the database server, possibly using other intermediate libraries where necessary. This software is known generically as a connector, as it allows your application to _connect_ to a database server. _What is a Driver?_ A driver is a piece of software designed to communicate with a specific type of database server. The driver may also call a library, such as the MySQL Client Library or the MySQL Native Driver. These libraries implement the low-level protocol used to communicate with the MySQL database server. By way of an example, the PHP Data Objects (PDO) database abstraction layer may use one of several database-specific drivers. One of the drivers it has available is the PDO MYSQL driver, which allows it to interface with the MySQL server. Sometimes people use the terms connector and driver interchangeably, this can be confusing. In the MySQL-related documentation the term `driver' is reserved for software that provides the database-specific part of a connector package. _What is an Extension?_ In the PHP documentation you will come across another term - _extension_. The PHP code consists of a core, with optional extensions to the core functionality. PHP's MySQL-related extensions, such as the `mysqli' extension, and the `mysql' extension, are implemented using the PHP extension framework. An extension typically exposes an API to the PHP programmer, to allow its facilities to be used programmatically. However, some extensions which use the PHP extension framework do not expose an API to the PHP programmer. The PDO MySQL driver extension, for example, does not expose an API to the PHP programmer, but provides an interface to the PDO layer above it. The terms API and extension should not be taken to mean the same thing, as an extension may not necessarily expose an API to the programmer.  File: manual.info, Node: apis-php-mysqlinfo.api.choosing, Next: apis-php-mysqlinfo.library.choosing, Prev: apis-php-mysqlinfo.terminology, Up: apis-php-mysqlinfo 21.9.1.3 Choosing an API ........................ Copyright 1997-2012 the PHP Documentation Group. PHP offers three different APIs to connect to MySQL. Below we show the APIs provided by the mysql, mysqli, and PDO extensions. Each code snippet creates a connection to a MySQL server running on "example.com" using the username "user" and the password "password". And a query is run to greet the user. query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL"); $row = $result->fetch_assoc(); echo htmlentities($row['_message']); // PDO $pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password'); $statement = $pdo->query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL"); $row = $statement->fetch(PDO::FETCH_ASSOC); echo htmlentities($row['_message']); // mysql $c = mysql_connect("example.com", "user", "password"); mysql_select_db("database"); $result = mysql_query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL"); $row = mysql_fetch_assoc($result); echo htmlentities($row['_message']); ?> _Recommended API_ It is recommended to use either the See section "apis-php-mysqli" in the online manual or See section "apis-php-ref.pdo-mysql" in the online manual extensions. It is not recommended to use the old mysql extension for new development, as it has been deprecated as of PHP 5.5.0 and will be removed in the future. A detailed feature comparison matrix is provided below. The overall performance of all three extensions is considered to be about the same. Although the performance of the extension contributes only a fraction of the total run time of a PHP web request. Often, the impact is as low as 0.1%. _Feature comparison_ Unknown PHP API feature. ext/mysqli PDO_MySQL ext/mysql PHP version 5.0 5.1 2.0 introduced Included with PHP Yes Yes Yes 5.x Development status Active Active Maintenance only Lifecycle Active Active Deprecated Recommended for Yes Yes No new projects OOP Interface Yes Yes No Procedural Yes No Yes Interface API supports Yes No No non-blocking, asynchronous queries with mysqlnd Persistent Yes Yes Yes Connections API supports Yes Yes Yes Charsets API supports Yes Yes No server-side Prepared Statements API supports No Yes No client-side Prepared Statements API supports Yes Yes No Stored Procedures API supports Yes Most No Multiple Statements API supports Yes Yes No Transactions Transactions can Yes Yes Yes be controlled with SQL Supports all Yes Most No MySQL 5.1+ functionality  File: manual.info, Node: apis-php-mysqlinfo.library.choosing, Next: apis-php-mysqlinfo.concepts, Prev: apis-php-mysqlinfo.api.choosing, Up: apis-php-mysqlinfo 21.9.1.4 Choosing a library ........................... Copyright 1997-2012 the PHP Documentation Group. The mysqli, PDO_MySQL and mysql PHP extensions are lightweight wrappers on top of a C client library. The extensions can either use the See section "apis-php-mysqli" in the online manual library or the `libmysqlclient' library. Choosing a library is a compile time decision. The mysqlnd library is part of the PHP distribution since 5.3.0. It offers features like lazy connections and query caching, features that are not available with libmysqlclient, so using the built-in mysqlnd library is highly recommended. See the See section "apis-php-mysqli" in the online manual for additional details, and a listing of features and functionality that it offers. // Recommended, compiles with mysqlnd $ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd --with-mysql=mysqlnd // Not recommended, compiles with libmysqlclient $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config --with-mysql=/path/to/mysql_config _Library feature comparison_ It is recommended to use the See section "apis-php-mysqli" in the online manual library instead of the MySQL Client Server library (libmysqlclient). Both libraries are supported and constantly being improved. Unknown PHP API feature. MySQL native driver MySQL client server (See section library "apis-php-mysqli" in (`libmysqlclient') the online manual) Part of the PHP Yes No distribution PHP version introduced 5.3.0 N/A License PHP License 3.01 Dual-License Development status Active Active Lifecycle No end announced No end announced PHP 5.4 compile default Yes No (for all MySQL extensions) PHP 5.3 compile default No Yes (for all MySQL extensions) Compression protocol Yes (5.3.1+) Yes support SSL support Yes (5.3.3+) Yes Named pipe support Yes (5.3.4+) Yes Non-blocking, Yes No asynchronous queries Performance statistics Yes No LOAD LOCAL INFILE Yes No respects the open_basedir directive (http://www.php.net/ini.open-basedir) Uses PHP's native Yes No memory management system (e.g., follows PHP memory limits) Return numeric column Yes No as double (COM_QUERY) Return numeric column Yes Yes as string (COM_QUERY) Plugin API Yes Limited Read/Write splitting Yes, with plugin No for MySQL Replication Load Balancing Yes, with plugin No Fail over Yes, with plugin No Lazy connections Yes, with plugin No Query caching Yes, with plugin No Transparent query Yes, with plugin No manipulations (E.g., auto-EXPLAIN or monitoring)  File: manual.info, Node: apis-php-mysqlinfo.concepts, Prev: apis-php-mysqlinfo.library.choosing, Up: apis-php-mysqlinfo 21.9.1.5 Concepts ................. * Menu: * apis-php-mysqlinfo.concepts.buffering:: Buffered and Unbuffered queries * apis-php-mysqlinfo.concepts.charset:: Character sets Copyright 1997-2012 the PHP Documentation Group. These concepts are specific to the MySQL drivers for PHP.  File: manual.info, Node: apis-php-mysqlinfo.concepts.buffering, Next: apis-php-mysqlinfo.concepts.charset, Prev: apis-php-mysqlinfo.concepts, Up: apis-php-mysqlinfo.concepts 21.9.1.6 Buffered and Unbuffered queries ........................................ Copyright 1997-2012 the PHP Documentation Group. Queries are using the buffered mode by default. This means that query results are immediately transferred from the MySQL Server to PHP in is then kept in the memory of the PHP process. This allows additional operations like counting the number of rows, and moving (seeking) the current result pointer. It also allows issuing further queries on the same connection while working on the result set. The downside of the buffered mode is that larger result sets might require quite a lot memory. The memory will be kept occupied till all references to the result set are unset or the result set was explicitly freed, which will automatically happen during request end the latest. The terminology "store result" is also used for buffered mode, as the whole result set is stored at once. *Note*: When using libmysqlclient as library PHP's memory limit won't count the memory used for result sets unless the data is fetched into PHP variables. With mysqlnd the memory accounted for will include the full result set. Unbuffered MySQL queries execute the query and then return a resource while the data is still waiting on the MySQL server for being fetched. This uses less memory on the PHP-side, but can increase the load on the server. Unless the full result set was fetched from the server no further queries can be sent over the same connection. Unbuffered queries can also be referred to as "use result". Following these characteristics buffered queries should be used in cases where you expect only a limited result set or need to know the amount of returned rows before reading all rows. Unbuffered mode should be used when you expect larger results. Because buffered queries are the default, the examples below will demonstrate how to execute unbuffered queries with each API. query("SELECT Name FROM City", MYSQLI_USE_RESULT); if ($uresult) { while ($row = $uresult->fetch_assoc()) { echo $row['Name'] . PHP_EOL; } } $uresult->close(); ?> setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false); $uresult = $pdo->query("SELECT Name FROM City"); if ($uresult) { while ($row = $uresult->fetch(PDO::FETCH_ASSOC)) { echo $row['Name'] . PHP_EOL; } } ?>  File: manual.info, Node: apis-php-mysqlinfo.concepts.charset, Prev: apis-php-mysqlinfo.concepts.buffering, Up: apis-php-mysqlinfo.concepts 21.9.1.7 Character sets ....................... Copyright 1997-2012 the PHP Documentation Group. Ideally a proper character set will be set at the server level, and doing this is described within the Character Set Configuration (http://dev.mysql.com/doc/mysql/en/charset-configuration.html) section of the MySQL Server manual. Alternatively, each MySQL API offers a method to set the character set at runtime. *The character set and character escaping*: The character set should be understood and defined, as it has an affect on every action, and includes security implications. For example, the escaping mechanism (e.g., `mysqli_real_escape_string' for mysqli, `mysql_real_escape_string' for mysql, and `PDO::quote' (http://www.php.net/PDO::quote) for PDO_MySQL) will adhere to this setting. It is important to realize that these functions will not use the character set that is defined with a query, so for example the following will not have an effect on them: real_escape_string(); $mysqli->query("SET NAMES utf8"); // Will not affect $mysqli->real_escape_string(); $mysqli->query("SET CHARACTER SET utf8"); // But, this will affect $mysqli->real_escape_string(); $mysqli->set_charset('utf8'); ?> Below are examples that demonstrate how to properly alter the character set at runtime using each each API. set_charset('utf8')) { printf("Error loading character set utf8: %s\n", $mysqli->error); } else { printf("Current character set: %s\n", $mysqli->character_set_name()); } print_r( $mysqli->get_charset() ); ?> Note: This only works as of PHP 5.3.6.  File: manual.info, Node: apis-php-book.mysqlnd-ms, Next: apis-php-book.mysqlnd-qc, Prev: apis-php-mysqlinfo, Up: apis-php 21.9.2 Mysqlnd replication and load balancing plugin (`mysqlnd_ms') ------------------------------------------------------------------- * Menu: * apis-php-mysqlnd-ms.key-features:: Key Features * apis-php-mysqlnd-ms.limitations:: Limitations * apis-php-mysqlnd-ms.name:: On the name * apis-php-mysqlnd-ms.quickstart:: Quickstart and Examples * apis-php-mysqlnd-ms.concepts:: Concepts * apis-php-mysqlnd-ms.setup:: Installing/Configuring * apis-php-mysqlnd-ms.constants:: Predefined Constants * apis-php-ref.mysqlnd-ms:: Mysqlnd_ms Functions * apis-php-mysqlnd-ms.changes:: Change History Copyright 1997-2012 the PHP Documentation Group. The mysqlnd replication and load balancing plugin (`mysqlnd_ms') adds easy to use MySQL replication support to all PHP MySQL extensions that use See section "apis-php-mysqli" in the online manual. As of version PHP 5.3.3 the MySQL native driver for PHP (`mysqlnd') features an internal plugin C API. C plugins, such as the replication and load balancing plugin, can extend the functionality of See section "apis-php-mysqli" in the online manual. The MySQL native driver for PHP is a C library that ships together with PHP as of PHP 5.3.0. It serves as a drop-in replacement for the MySQL Client Library (libmysqlclient). Using mysqlnd has several advantages: no extra downloads are required because it's bundled with PHP, it's under the PHP license, there is lower memory consumption in certain cases, and it contains new functionality such as asynchronous queries. Mysqlnd plugins like `mysqlnd_ms' operate, for the most part, transparently from a user perspective. The replication and load balancing plugin supports all PHP applications, and all MySQL PHP extensions. It does not change existing APIs. Therefore, it can easily be used with existing PHP applications.  File: manual.info, Node: apis-php-mysqlnd-ms.key-features, Next: apis-php-mysqlnd-ms.limitations, Prev: apis-php-book.mysqlnd-ms, Up: apis-php-book.mysqlnd-ms 21.9.2.1 Key Features ..................... Copyright 1997-2012 the PHP Documentation Group. The key features of PECL/mysqlnd_ms are as follows. * Transparent and therefore easy to use. * Supports all of the PHP MySQL extensions. * SSL support. * A consistent API. * Little to no application changes required, dependent on the required usage scenario. * Lazy connections: connections to master and slave servers are not opened before a SQL statement is executed. * Optional: automatic use of master after the first write in a web request, to lower the possible impact of replication lag. * Can be used with any MySQL clustering solution. * MySQL Replication: Read-write splitting is done by the plugin. Primary focus of the plugin. * MySQL Cluster: Read-write splitting can be disabled. Configuration of multiple masters possible * Third-party solutions: the plugin is optimized for MySQL Replication but can be used with any other kind of MySQL clustering solution. * Featured read-write split strategies * Automatic detection of SELECT. * Supports SQL hints to overrule automatism. * User-defined. * Can be disabled for, for example, when using synchronous clusters such as MySQL Cluster. * Featured load balancing strategies * Round Robin: choose a different slave in round-robin fashion for every slave request. * Random: choose a random slave for every slave request. * Random once (sticky): choose a random slave once to run all slave requests for the duration of a web request. * User-defined. The application can register callbacks with mysqlnd_ms. * PHP 5.4.0 or newer: transaction aware when using API calls only to control transactions. * Weighted load balancing: servers can be assigned different priorities, for example, to direct more requests to a powerful machine than to another less powerful machine. Or, to prefer nearby machines to reduce latency. * Global transaction ID * Client-side emulation. Makes manual master server failover and slave promotion easier with asynchronous clusters, such as MySQL Replication. * Support for built-in global transaction identifier feature of MySQL 5.6.5 or newer. * Supports using transaction ids to identify up-to-date asynchronous slaves for reading when session consistency is required. * Throttling: optionally, the plugin can wait for a slave to become "synchronous" before continuing. * Service and consistency levels * Applications can request eventual, session and strong consistency service levels for connections. Appropriate cluster nodes will be searched automatically. * Eventual consistent MySQL Replication slave accesses can be replaced with fast local cache accesses transparently to reduce server load. * Partitioning and sharding * Servers of a replication cluster can be organized into groups. SQL hints can be used to manually direct queries to a specific group. Grouping can be used to partition (shard) the data, or to cure the issue of hotspots with updates. * MySQL Replication filters are supported through the table filter.  File: manual.info, Node: apis-php-mysqlnd-ms.limitations, Next: apis-php-mysqlnd-ms.name, Prev: apis-php-mysqlnd-ms.key-features, Up: apis-php-book.mysqlnd-ms 21.9.2.2 Limitations .................... Copyright 1997-2012 the PHP Documentation Group. The built-in read-write-split mechanism is very basic. Every query which starts with `SELECT' is considered a read request to be sent to a MySQL slave server. All other queries (such as `SHOW' statements) are considered as write requests that are sent to the MySQL master server. The build-in behavior can be overruled using *Note SQL hints: apis-php-mysqlnd-ms.constants, or a user-defined callback function. The read-write splitter is not aware of multi-statements. Multi-statements are considered as one statement. The decision of where to run the statement will be based on the beginning of the statement string. For example, if using `mysqli_multi_query' to execute the multi-statement `SELECT id FROM test ; INSERT INTO test(id) VALUES (1)', the statement will be redirected to a slave server because it begins with `SELECT'. The `INSERT' statement, which is also part of the multi-statement, will not be redirected to a master server. *Note*: Applications must be aware of the consequences of connection switches that are performed for load balancing purposes. Please check the documentation on *Note connection pooling and switching: apis-php-mysqlnd-ms.pooling, *Note transaction handling: apis-php-mysqlnd-ms.transaction, *Note failover: apis-php-mysqlnd-ms.failover. *Note load balancing: apis-php-mysqlnd-ms.loadbalancing. and *Note read-write splitting: apis-php-mysqlnd-ms.rwsplit.  File: manual.info, Node: apis-php-mysqlnd-ms.name, Next: apis-php-mysqlnd-ms.quickstart, Prev: apis-php-mysqlnd-ms.limitations, Up: apis-php-book.mysqlnd-ms 21.9.2.3 On the name .................... Copyright 1997-2012 the PHP Documentation Group. The shortcut `mysqlnd_ms' stands for `mysqlnd master slave plugin'. The name was chosen for a quick-and-dirty proof-of-concept. In the beginning the developers did not expect to continue using the code base.  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart, Next: apis-php-mysqlnd-ms.concepts, Prev: apis-php-mysqlnd-ms.name, Up: apis-php-book.mysqlnd-ms 21.9.2.4 Quickstart and Examples ................................ * Menu: * apis-php-mysqlnd-ms.quickstart.configuration:: Setup * apis-php-mysqlnd-ms.quickstart.usage:: Running statements * apis-php-mysqlnd-ms.quickstart.connectionpooling:: Connection state * apis-php-mysqlnd-ms.quickstart.sqlhints:: SQL Hints * apis-php-mysqlnd-ms.quickstart.transactions:: Transactions * apis-php-mysqlnd-ms.quickstart.qos-consistency:: Service level and consistency * apis-php-mysqlnd-ms.quickstart.gtid:: Global transaction IDs * apis-php-mysqlnd-ms.quickstart.cache:: Cache integration * apis-php-mysqlnd-ms.quickstart.failover:: Failover * apis-php-mysqlnd-ms.quickstart.partitioning:: Partitioning and Sharding Copyright 1997-2012 the PHP Documentation Group. The mysqlnd replication load balancing plugin is easy to use. This quickstart will demo typical use-cases, and provide practical advice on getting started. It is strongly recommended to read the reference sections in addition to the quickstart. The quickstart tries to avoid discussing theoretical concepts and limitations. Instead, it will link to the reference sections. It is safe to begin with the quickstart. However, before using the plugin in mission critical environments we urge you to read additionally the background information from the reference sections. The focus is on using PECL mysqlnd_ms for work with an asynchronous MySQL cluster, namely MySQL replication. Generally speaking an asynchronous cluster is more difficult to use than a synchronous one. Thus, users of, for example, MySQL Cluster will find more information than needed.  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart.configuration, Next: apis-php-mysqlnd-ms.quickstart.usage, Prev: apis-php-mysqlnd-ms.quickstart, Up: apis-php-mysqlnd-ms.quickstart 21.9.2.5 Setup .............. Copyright 1997-2012 the PHP Documentation Group. The plugin is implemented as a PHP extension. See also the *Note installation instructions: apis-php-mysqlnd-ms.installation. to install the PECL/mysqlnd_ms (http://pecl.php.net/package/mysqlnd_ms) extension. Compile or configure the PHP MySQL extension (API) (mysqli, See section "apis-php-ref.pdo-mysql" in the online manual, mysql) that you plan to use with support for the See section "apis-php-mysqli" in the online manual library. PECL/mysqlnd_ms is a plugin for the mysqlnd library. To use the plugin with any of the PHP MySQL extensions, the extension has to use the mysqlnd library. Then, load the extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_ms.enable. mysqlnd_ms.enable=1 mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini The plugin uses its own configuration file. Use the PHP configuration directive mysqlnd_ms.config_file to set the full file path to the plugin-specific configuration file. This file must be readable by PHP (e.g., the web server user). Please note, the configuration directive mysqlnd_ms.config_file superseeds mysqlnd_ms.ini_file since 1.4.0. It is a common pitfall to use the old, no longer available configuration directive. Create a plugin-specific configuration file. Save the file to the path set by the PHP configuration directive mysqlnd_ms.config_file. The plugins *Note configuration file: apis-php-mysqlnd-ms.plugin-ini-json. is JSON based. It is divided into one or more sections. Each section has a name, for example, `myapp'. Every section makes its own set of configuration settings. A section must, at a minimum, list the MySQL replication master server, and set a list of slaves. The plugin supports using only one master server per section. Multi-master MySQL replication setups are not yet fully supported. Use the configuration setting master to set the hostname, and the port or socket of the MySQL master server. MySQL slave servers are configured using the slave keyword. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": [ ] } } Configuring a MySQL slave server list is required, although it may contain an empty list. It is recommended to always configure at least one slave server. Server lists can use anonymous or non-anonymous syntax. Non-anonymous lists include alias names for the servers, such as `master_0' for the master in the above example. The quickstart uses the more verbose non-anonymous syntax. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "192.168.2.27", "port": "3306" } } } } If there are at least two servers in total, the plugin can start to load balance and switch connections. Switching connections is not always transparent and can cause issues in certain cases. The reference sections about *Note connection pooling and switching: apis-php-mysqlnd-ms.pooling, *Note transaction handling: apis-php-mysqlnd-ms.transaction, *Note fail over: apis-php-mysqlnd-ms.failover. *Note load balancing: apis-php-mysqlnd-ms.loadbalancing. and *Note read-write splitting: apis-php-mysqlnd-ms.rwsplit. all provide more details. And potential pitfalls are described later in this guide. It is the responsibility of the application to handle potential issues caused by connection switches, by configuring a master with at least one slave server, which allows switching to work therefore related problems can be found. The MySQL master and MySQL slave servers, which you configure, do not need to be part of MySQL replication setup. For testing purpose you can use single MySQL server and make it known to the plugin as a master and slave server as shown below. This could help you to detect many potential issues with connection switches. However, such a setup will not be prone to the issues caused by replication lag. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } } } } The plugin attempts to notify you of invalid configurations. Since 1.5.0 it will throw a warning during PHP startup if the configuration file cannot be read, is empty or parsing the JSON failed. Depending on your PHP settings those errors may appear in some log files only. Further validation is done when a connection is to be established and the configuration file is searched for valid sections. Setting mysqlnd_ms.force_config_usage may help debugging a faulty setup. Please, see also configuration file debugging notes.  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart.usage, Next: apis-php-mysqlnd-ms.quickstart.connectionpooling, Prev: apis-php-mysqlnd-ms.quickstart.configuration, Up: apis-php-mysqlnd-ms.quickstart 21.9.2.6 Running statements ........................... Copyright 1997-2012 the PHP Documentation Group. The plugin can be used with any PHP MySQL extension (mysqli, mysql, and See section "apis-php-ref.pdo-mysql" in the online manual) that is compiled to use the See section "apis-php-mysqli" in the online manual library. PECL/mysqlnd_ms plugs into the See section "apis-php-mysqli" in the online manual library. It does not change the API or behavior of those extensions. Whenever a connection to MySQL is being opened, the plugin compares the host parameter value of the connect call, with the section names from the plugin specific configuration file. If, for example, the plugin specific configuration file has a section `myapp' then the section should be referenced by opening a MySQL connection to the host `myapp' { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "192.168.2.27", "port": "3306" } } } } The connection examples above will be load balanced. The plugin will send read-only statements to the MySQL slave server with the IP `192.168.2.27' and will listen on port `3306' for the MySQL client connection. All other statements will be directed to the MySQL master server running on the host `localhost'. If on Unix like operating systems, the master on `localhost' will be accepting MySQL client connections on the Unix domain socket `/tmp/mysql.sock', while TCP/IP is the default port on Windows. The plugin will use the user name `username' and the password `password' to connect to any of the MySQL servers listed in the section `myapp' of the plugins configuration file. Upon connect, the plugin will select `database' as the current schemata. The username, password and schema name are taken from the connect API calls and used for all servers. In other words: you must use the same username and password for every MySQL server listed in a plugin configuration file section. The is not a general limitation. As of PECL/mysqlnd_ms 1.1.0, it is possible to set the username and password for any server in the plugins configuration file, to be used instead of the credentials passed to the API call. The plugin does not change the API for running statements. *Note Read-write splitting: apis-php-mysqlnd-ms.rwsplit. works out of the box. The following example assumes that there is no significant replication lag between the master and the slave. query("DROP TABLE IF EXISTS test")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } if (!$mysqli->query("CREATE TABLE test(id INT)")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } /* read-only: statement will be run on a slave */ if (!($res = $mysqli->query("SELECT id FROM test")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } else { $row = $res->fetch_assoc(); $res->close(); printf("Slave returns id = '%s'\n", $row['id']; } $mysqli->close(); ?> The above example will output something similar to: Slave returns id = '1'  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart.connectionpooling, Next: apis-php-mysqlnd-ms.quickstart.sqlhints, Prev: apis-php-mysqlnd-ms.quickstart.usage, Up: apis-php-mysqlnd-ms.quickstart 21.9.2.7 Connection state ......................... Copyright 1997-2012 the PHP Documentation Group. The plugin changes the semantics of a PHP MySQL connection handle. A new connection handle represents a connection pool, instead of a single MySQL client-server network connection. The connection pool consists of a master connection, and optionally any number of slave connections. Every connection from the connection pool has its own state. For example, SQL user variables, temporary tables and transactions are part of the state. For a complete list of items that belong to the state of a connection, see the *Note connection pooling and switching: apis-php-mysqlnd-ms.pooling. concepts documentation. If the plugin decides to switch connections for load balancing, the application could be given a connection which has a different state. Applications must be made aware of this. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "192.168.2.27", "port": "3306" } } } } query("SET @myrole='master'")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } /* Connection 2, run on slave because SELECT */ if (!($res = $mysqli->query("SELECT @myrole AS _role"))) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } else { $row = $res->fetch_assoc(); $res->close(); printf("@myrole = '%s'\n", $row['_role']); } $mysqli->close(); ?> The above example will output: @myrole = '' The example opens a load balanced connection and executes two statements. The first statement `SET @myrole='master'' does not begin with the string `SELECT'. Therefore the plugin does not recognize it as a read-only query which shall be run on a slave. The plugin runs the statement on the connection to the master. The statement sets a SQL user variable which is bound to the master connection. The state of the master connection has been changed. The next statement is `SELECT @myrole AS _role'. The plugin does recognize it as a read-only query and sends it to the slave. The statement is run on a connection to the slave. This second connection does not have any SQL user variables bound to it. It has a different state than the first connection to the master. The requested SQL user variable is not set. The example script prints `@myrole = '''. It is the responsibility of the application developer to take care of the connection state. The plugin does not monitor all connection state changing activities. Monitoring all possible cases would be a very CPU intensive task, if it could be done at all. The pitfalls can easily be worked around using SQL hints.  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart.sqlhints, Next: apis-php-mysqlnd-ms.quickstart.transactions, Prev: apis-php-mysqlnd-ms.quickstart.connectionpooling, Up: apis-php-mysqlnd-ms.quickstart 21.9.2.8 SQL Hints .................. Copyright 1997-2012 the PHP Documentation Group. SQL hints can force a query to choose a specific server from the connection pool. It gives the plugin a hint to use a designated server, which can solve issues caused by connection switches and connection state. SQL hints are standard compliant SQL comments. Because SQL comments are supposed to be ignored by SQL processing systems, they do not interfere with other programs such as the MySQL Server, the MySQL Proxy, or a firewall. Three SQL hints are supported by the plugin: The MYSQLND_MS_MASTER_SWITCH hint makes the plugin run a statement on the master, MYSQLND_MS_SLAVE_SWITCH enforces the use of the slave, and MYSQLND_MS_LAST_USED_SWITCH will run a statement on the same server that was used for the previous statement. The plugin scans the beginning of a statement for the existence of an SQL hint. SQL hints are only recognized if they appear at the beginning of the statement. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "192.168.2.27", "port": "3306" } } } } query("SET @myrole='master'")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } /* Connection 1, run on master because of SQL hint */ if (!($res = $mysqli->query(sprintf("/*%s*/SELECT @myrole AS _role", MYSQLND_MS_LAST_USED_SWITCH)))) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } else { $row = $res->fetch_assoc(); $res->close(); printf("@myrole = '%s'\n", $row['_role']); } $mysqli->close(); ?> The above example will output: @myrole = 'master' In the above example, using MYSQLND_MS_LAST_USED_SWITCH prevents session switching from the master to a slave when running the `SELECT' statement. SQL hints can also be used to run `SELECT' statements on the MySQL master server. This may be desired if the MySQL slave servers are typically behind the master, but you need current data from the cluster. In version 1.2.0 the concept of a service level has been introduced to address cases when current data is required. Using a service level requires less attention and removes the need of using SQL hints for this use case. Please, find more information below in the service level and consistency section. query(sprintf("/*%s*/SELECT critical_data FROM important_table", MYSQLND_MS_MASTER_SWITCH))) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } ?> A use case may include the creation of tables on a slave. If an SQL hint is not given, then the plugin will send `CREATE' and `INSERT' statements to the master. Use the SQL hint MYSQLND_MS_SLAVE_SWITCH if you want to run any such statement on a slave, for example, to build temporary reporting tables. query(sprintf("/*%s*/CREATE TABLE slave_reporting(id INT)", MYSQLND_MS_SLAVE_SWITCH))) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } /* Continue using this particular slave connection */ if (!$mysqli->query(sprintf("/*%s*/INSERT INTO slave_reporting(id) VALUES (1), (2), (3)", MYSQLND_MS_LAST_USED_SWITCH))) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } /* Don't use MYSQLND_MS_SLAVE_SWITCH which would allow switching to another slave! */ if ($res = $mysqli->query(sprintf("/*%s*/SELECT COUNT(*) AS _num FROM slave_reporting", MYSQLND_MS_LAST_USED_SWITCH))) { $row = $res->fetch_assoc(); $res->close(); printf("There are %d rows in the table 'slave_reporting'", $row['_num']); } else { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } $mysqli->close(); ?> The SQL hint MYSQLND_MS_LAST_USED forbids switching a connection, and forces use of the previously used connection.  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart.transactions, Next: apis-php-mysqlnd-ms.quickstart.qos-consistency, Prev: apis-php-mysqlnd-ms.quickstart.sqlhints, Up: apis-php-mysqlnd-ms.quickstart 21.9.2.9 Transactions ..................... Copyright 1997-2012 the PHP Documentation Group. The current version of the plugin is not transaction safe by default, because it is not aware of running transactions in all cases. SQL transactions are units of work to be run on a single server. The plugin does not always know when the unit of work starts and when it ends. Therefore, the plugin may decide to switch connections in the middle of a transaction. No kind of MySQL load balancer can detect transaction boundaries without any kind of hint from the application. You can either use SQL hints to work around this limitation. Alternatively, you can activate transaction API call monitoring. In the latter case you must use API calls only to control transactions, see below. [myapp] { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "192.168.2.27", "port": "3306" } } } } query("START TRANSACTION")) { /* Please use better error handling in your code */ die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } /* Prevent connection switch! */ if (!$mysqli->query(sprintf("/*%s*/INSERT INTO test(id) VALUES (1)", MYSQLND_MS_LAST_USED_SWITCH)))) { /* Please do proper ROLLBACK in your code, don't just die */ die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } if ($res = $mysqli->query(sprintf("/*%s*/SELECT COUNT(*) AS _num FROM test", MYSQLND_MS_LAST_USED_SWITCH)))) { $row = $res->fetch_assoc(); $res->close(); if ($row['_num'] > 1000) { if (!$mysqli->query(sprintf("/*%s*/INSERT INTO events(task) VALUES ('cleanup')", MYSQLND_MS_LAST_USED_SWITCH)))) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } } } else { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } if (!$mysqli->query(sprintf("/*%s*/UPDATE log SET last_update = NOW()", MYSQLND_MS_LAST_USED_SWITCH)))) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } if (!$mysqli->query(sprintf("/*%s*/COMMIT", MYSQLND_MS_LAST_USED_SWITCH)))) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } $mysqli->close(); ?> Starting with PHP 5.4.0, the `mysqlnd' library allows the plugin to monitor the status of the `autocommit' mode, if the mode is set by API calls instead of using SQL statements such as `SET AUTOCOMMIT=0'. This makes it possible for the plugin to become transaction aware. In this case, you do not need to use SQL hints. If using PHP 5.4.0 or newer, API calls that enable `autocommit' mode, and when setting the plugin configuration option trx_stickiness=master, the plugin can automatically disable load balancing and connection switches for SQL transactions. In this configuration, the plugin stops load balancing if `autocommit' is disabled and directs all statements to the master. This prevents connection switches in the middle of a transaction. Once `autocommit' is re-enabled, the plugin starts to load balance statements again. API based transaction boundary detection has been improved with PHP 5.5.0 and PECL/mysqlnd_ms 1.5.0 to cover not only calls to `mysqli_autocommit' but also `mysqli_begin' (http://www.php.net/mysqli_begin), `mysqli_commit' and `mysqli_rollback'. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } }, "trx_stickiness": "master" } } autocommit(FALSE); if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) { /* Please do proper ROLLBACK in your code, don't just die */ die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } if ($res = $mysqli->query("SELECT COUNT(*) AS _num FROM test")) { $row = $res->fetch_assoc(); $res->close(); if ($row['_num'] > 1000) { if (!$mysqli->query("INSERT INTO events(task) VALUES ('cleanup')")) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } } } else { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } if (!$mysqli->query("UPDATE log SET last_update = NOW()")) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } if (!$mysqli->commit()) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } /* Plugin assumes that the transaction has ended and starts load balancing again */ $mysqli->autocommit(TRUE); $mysqli->close(); ?> *Version requirement*: The plugin configuration option trx_stickiness=master requires PHP 5.4.0 or newer. Please note the restrictions outlined in the *Note transaction handling: apis-php-mysqlnd-ms.transaction. concepts section.  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart.qos-consistency, Next: apis-php-mysqlnd-ms.quickstart.gtid, Prev: apis-php-mysqlnd-ms.quickstart.transactions, Up: apis-php-mysqlnd-ms.quickstart 21.9.2.10 Service level and consistency ....................................... Copyright 1997-2012 the PHP Documentation Group. *Version requirement*: Service levels have been introduced in PECL mysqlnd_ms version 1.2.0-alpha. *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. is available with PHP 5.4.0 or newer. Different types of MySQL cluster solutions offer different service and data consistency levels to their users. An asynchronous MySQL replication cluster offers eventual consistency by default. A read executed on an asynchronous slave may return current, stale or no data at all, depending on whether the slave has replayed all changesets from the master or not. Applications using an MySQL replication cluster need to be designed to work correctly with eventual consistent data. In some cases, however, stale data is not acceptable. In those cases only certain slaves or even only master accesses are allowed to achieve the required quality of service from the cluster. As of PECL mysqlnd_ms 1.2.0 the plugin is capable of selecting MySQL replication nodes automatically that deliver session consistency or strong consistency. Session consistency means that one client can read its writes. Other clients may or may not see the clients' write. Strong consistency means that all clients will see all writes from the client. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } } } } query("INSERT INTO orders(order_id, item) VALUES (1, 'christmas tree, 1.8m')")) { /* Please use better error handling in your code */ die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } /* Request session consistency: read your writes */ if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION)) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* Plugin picks a node which has the changes, here: master */ if (!$res = $mysqli->query("SELECT item FROM orders WHERE order_id = 1")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); var_dump($res->fetch_assoc()); /* Back to eventual consistency: stale data allowed */ if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL)) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* Plugin picks any slave, stale data is allowed */ if (!$res = $mysqli->query("SELECT item, price FROM specials")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); ?> Service levels can be set in the plugins configuration file and at runtime using *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. In the example the function is used to enforce session consistency (read your writes) for all future statements until further notice. The `SELECT' statement on the `orders' table is run on the master to ensure the previous write can be seen by the client. Read-write splitting logic has been adapted to fulfill the service level. After the application has read its changes from the `orders' table it returns to the default service level, which is eventual consistency. Eventual consistency puts no restrictions on choosing a node for statement execution. Thus, the `SELECT' statement on the `specials' table is executed on a slave. The new functionality supersedes the use of SQL hints and the `master_on_write' configuration option. In many cases *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. is easier to use, more powerful improves portability. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } }, "failover" : "master" } } errno, $mysqli->error)); /* Plugin picks any slave, which may or may not have the changes */ if (!$res = $mysqli->query("SELECT item, price FROM daytrade")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* Back to default: use of all slaves and masters permitted */ if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL)) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); ?> The eventual consistency service level can be used with an optional parameter to set a maximum slave lag for choosing slaves. If set, the plugin checks `SHOW SLAVE STATUS' for all configured slaves. In case of the example, only slaves for which `Slave_IO_Running=Yes', `Slave_SQL_Running=Yes' and `Seconds_Behind_Master <= 4' is true are considered for executing the statement `SELECT item, price FROM daytrade'. Checking `SHOW SLAVE STATUS' is done transparently from an applications perspective. Errors, if any, are reported as warnings. No error will be set on the connection handle. Even if all `SHOW SLAVE STATUS' SQL statements executed by the plugin fail, the execution of the users statement is not stopped, given that master fail over is enabled. Thus, no application changes are required. *Expensive and slow operation*: Checking `SHOW SLAVE STATUS' for all slaves adds overhead to the application. It is an expensive and slow background operation. Try to minimize the use of it. Unfortunately, a MySQL replication cluster does not give clients the possibility to request a list of candidates from a central instance. Thus, a more efficient way of checking the slaves lag is not available. Please, note the limitations and properties of `SHOW SLAVE STATUS' as explained in the MySQL reference manual. To prevent mysqlnd_ms from emitting a warning if no slaves can be found that lag no more than the defined number of seconds behind the master, it is necessary to enable master fail over in the plugins configuration file. If no slaves can be found and fail over is turned on, the plugin picks a master for executing the statement. If no slave can be found and fail over is turned off, the plugin emits a warning, it does not execute the statement and it sets an error on the connection. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } } } } errno, $mysqli->error)); /* Plugin picks any slave, which may or may not have the changes */ if (!$res = $mysqli->query("SELECT item, price FROM daytrade")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* Back to default: use of all slaves and masters permitted */ if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL)) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); ?> The above example will output: PHP Warning: mysqli::query(): (mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from. Something is wrong in %s on line %d PHP Warning: mysqli::query(): (mysqlnd_ms) No connection selected by the last filter in %s on line %d [2000] (mysqlnd_ms) No connection selected by the last filter  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart.gtid, Next: apis-php-mysqlnd-ms.quickstart.cache, Prev: apis-php-mysqlnd-ms.quickstart.qos-consistency, Up: apis-php-mysqlnd-ms.quickstart 21.9.2.11 Global transaction IDs ................................ Copyright 1997-2012 the PHP Documentation Group. *Version requirement*: A client-side global transaction ID injection has been introduced in mysqlnd_ms version 1.2.0-alpha. The feature is not required for synchronous clusters, such as MySQL Cluster. Use it with asynchronous clusters such as classical MySQL replication. As of MySQL 5.6.5-m8 the MySQL server features built-in global transaction identifiers. The MySQL built-in global transaction ID feature is supported by PECL/mysqlnd_ms 1.3.0-alpha or later. PECL/mysqlnd_ms can either use its own global transaction ID emulation or the global transaction ID feature built-in to MySQL 5.6.5-m8 or later. From a developer perspective the client-side and server-side approach offer the same features with regards to service levels provided by PECL/mysqlnd_ms. Their differences are discussed in the *Note concepts section: apis-php-mysqlnd-ms.gtid. The quickstart first demonstrates the use of the client-side global transaction ID emulation built-in to PECL/mysqlnd_ms before its show how to use the server-side counterpart. The order ensures that the underlying idea is discussed first. _Idea and client-side emulation_ In its most basic form a global transaction ID (GTID) is a counter in a table on the master. The counter is incremented whenever a transaction is committed on the master. Slaves replicate the table. The counter serves two purposes. In case of a master failure, it helps the database administrator to identify the most recent slave for promoting it to the new master. The most recent slave is the one with the highest counter value. Applications can use the global transaction ID to search for slaves which have replicated a certain write (identified by a global transaction ID) already. PECL/mysqlnd_ms can inject SQL for every committed transaction to increment a GTID counter. The so created GTID is accessible by the application to identify an applications write operation. This enables the plugin to deliver session consistency (read your writes) service level by not only querying masters but also slaves which have replicated the change already. Read load is taken away from the master. Client-side global transaction ID emulation has some limitations. Please, read the *Note concepts section: apis-php-mysqlnd-ms.gtid. carefully to fully understand the principles and ideas behind it, before using in production environments. The background knowledge is not required to continue with the quickstart. First, create a counter table on your master server and insert a record into it. The plugin does not assist creating the table. Database administrators must make sure it exists. Depending on the error reporting mode, the plugin will silently ignore the lack of the table or bail out. CREATE TABLE `trx` ( `trx_id` int(11) DEFAULT NULL, `last_update` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ) ENGINE=InnoDB DEFAULT CHARSET=latin1 INSERT INTO `trx`(`trx_id`) VALUES (1); In the plugins configuration file set the SQL to update the global transaction ID table using `on_commit' from the `global_transaction_id_injection' section. Make sure the table name used for the `UPDATE' statement is fully qualified. In the example, `test.trx' is used to refer to table `trx' in the schema (database) `test'. Use the table that was created in the previous step. It is important to set the fully qualified table name because the connection on which the injection is done may use a different default database. Make sure the user that opens the connection is allowed to execute the `UPDATE'. Enable reporting of errors that may occur when mysqlnd_ms does global transaction ID injection. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } }, "global_transaction_id_injection":{ "on_commit":"UPDATE test.trx SET trx_id = trx_id + 1", "report_error":true } } } query("DROP TABLE IF EXISTS test")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* auto commit mode, transaction on master, GTID must be incremented */ if (!$mysqli->query("CREATE TABLE test(id INT)")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* auto commit mode, transaction on master, GTID must be incremented */ if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* auto commit mode, read on slave, no increment */ if (!($res = $mysqli->query("SELECT id FROM test"))) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); var_dump($res->fetch_assoc()); ?> The above example will output: array(1) { ["id"]=> string(1) "1" } The example runs three statements in auto commit mode on the master, causing three transactions on the master. For every such statement, the plugin will inject the configured `UPDATE' transparently before executing the users SQL statement. When the script ends the global transaction ID counter on the master has been incremented by three. The fourth SQL statement executed in the example, a `SELECT', does not trigger an increment. Only transactions (writes) executed on a master shall increment the GTID counter. *SQL for global transaction ID: efficient solution wanted!*: The SQL used for the client-side global transaction ID emulation is inefficient. It is optimized for clearity not for performance. Do not use it for production environments. Please, help finding an efficient solution for inclusion in the manual. We appreciate your input. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } }, "global_transaction_id_injection":{ "on_commit":"UPDATE test.trx SET trx_id = trx_id + 1", "fetch_last_gtid" : "SELECT MAX(trx_id) FROM test.trx", "report_error":true } } } query("DROP TABLE IF EXISTS test")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli)); /* auto commit mode, transaction on master, GTID must be incremented */ if (!$mysqli->query("CREATE TABLE test(id INT)")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli)); ?> The above example will output: GTID after transaction 7 GTID after transaction 8 Applications can ask PECL mysqlnd_ms for a global transaction ID which belongs to the last write operation performed by the application. The function *Note `mysqlnd_ms_get_last_gtid': apis-php-function.mysqlnd-ms-get-last-gtid. returns the GTID obtained when executing the SQL statement from the `fetch_last_gtid' entry of the `global_transaction_id_injection' section from the plugins configuration file. The function may be called after the GTID has been incremented. Applications are adviced not to run the SQL statement themselves as this bares the risk of accidently causing an implicit GTID increment. Also, if the function is used, it is easy to migrate an application from one SQL statement for fetching a transaction ID to another, for example, if any MySQL server ever features built-in global transaction ID support. The quickstart shows a SQL statement which will return a GTID equal or greater to that created for the previous statement. It is exactly the GTID created for the previous statement if no other clients have incremented the GTID in the time span between the statement execution and the `SELECT' to fetch the GTID. Otherwise, it is greater. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } }, "global_transaction_id_injection":{ "on_commit":"UPDATE test.trx SET trx_id = trx_id + 1", "fetch_last_gtid" : "SELECT MAX(trx_id) FROM test.trx", "check_for_gtid" : "SELECT trx_id FROM test.trx WHERE trx_id >= #GTID", "report_error":true } } } query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)") || !$mysqli->query("INSERT INTO test(id) VALUES (1)")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* GTID as an identifier for the last write */ $gtid = mysqlnd_ms_get_last_gtid($mysqli); /* Session consistency (read your writes): try to read from slaves not only master */ if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION, MYSQLND_MS_QOS_OPTION_GTID, $gtid)) { die(sprintf("[006] [%d] %s\n", $mysqli->errno, $mysqli->error)); } /* Either run on master or a slave which has replicated the INSERT */ if (!($res = $mysqli->query("SELECT id FROM test"))) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } var_dump($res->fetch_assoc()); ?> A GTID returned from *Note `mysqlnd_ms_get_last_gtid': apis-php-function.mysqlnd-ms-get-last-gtid. can be used as an option for the session consistency service level. Session consistency delivers read your writes. Session consistency can be requested by calling *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. In the example, the plugin will execute the `SELECT' statement either on the master or on a slave which has replicated the previous `INSERT' already. PECL mysqlnd_ms will transparently check every configured slave if it has replicated the `INSERT' by checking the slaves GTID table. The check is done running the SQL set with the `check_for_gtid' option from the `global_transaction_id_injection' section of the plugins configuration file. Please note, that this is a slow and expensive procedure. Applications should try to use it sparsely and only if read load on the master becomes to high otherwise. _Use of the server-side global transaction ID feature_ Starting with MySQL 5.6.5-m8 the MySQL Replication system features server-side global transaction IDs. Transaction identifiers are automatically generated and maintained by the server. Users do not need to take care of maintaining them. There is no need to setup any tables in advance, or for setting `on_commit'. A client-side emulation is no longer needed. Clients can continue to use global transaction identifier to achieve session consistency when reading from MySQL Replication slaves. The algorithm works as described above. Different SQL statements must be configured for `fetch_last_gtid' and `check_for_gtid'. The statements are given below. Please note, MySQL 5.6.5-m8 is a development version. Details of the server implementation may change in the future and require adoption of the SQL statements shown. Using the following configuration any of the above described functionality can be used together with the server-side global transaction ID feature. *Note `mysqlnd_ms_get_last_gtid': apis-php-function.mysqlnd-ms-get-last-gtid. and *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. continue to work as described above. The only difference is that the server does not use a simple sequence number but a string containing of a server identifier and a sequence number. Thus, users cannot easily derive an order from GTIDs returned by *Note `mysqlnd_ms_get_last_gtid': apis-php-function.mysqlnd-ms-get-last-gtid. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } }, "global_transaction_id_injection":{ "fetch_last_gtid" : "SELECT @@GLOBAL.GTID_DONE AS trx_id FROM DUAL", "check_for_gtid" : "SELECT GTID_SUBSET('#GTID', @@GLOBAL.GTID_DONE) AS trx_id FROM DUAL", "report_error":true } } }  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart.cache, Next: apis-php-mysqlnd-ms.quickstart.failover, Prev: apis-php-mysqlnd-ms.quickstart.gtid, Up: apis-php-mysqlnd-ms.quickstart 21.9.2.12 Cache integration ........................... Copyright 1997-2012 the PHP Documentation Group. *Version requirement, dependencies and status*: Please, find more about version requirements, extension load order dependencies and the current status in the *Note concepts section: apis-php-mysqlnd-ms.concept_cache.! Databases clusters can deliver different levels of consistency. As of PECL/mysqlnd_ms 1.2.0 it is possible to advice the plugin to consider only cluster nodes that can deliver the consistency level requested. For example, if using asynchronous MySQL Replication with its cluster-wide eventual consistency, it is possible to request session consistency (read your writes) at any time using `mysqlnd_ms_set_quos' (http://www.php.net/mysqlnd_ms_set_quos). Please, see also the *Note service level and consistency: apis-php-mysqlnd-ms.quickstart.qos-consistency. introduction. /* Request session consistency: read your writes */ if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION)) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); Assuming PECL/mysqlnd has been explicitly told to deliver no consistency level higher than eventual consistency, it is possible to replace a database node read access with a client-side cache using time-to-live (TTL) as its invalidation strategy. Both the database node and the cache may or may not serve current data as this is what eventual consistency defines. Replacing a database node read access with a local cache access can improve overall performance and lower the database load. If the cache entry is every reused by other clients than the one creating the cache entry, a database access is saved and thus database load is lowered. Furthermore, system performance can become better if computation and delivery of a database query is slower than a local cache access. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } }, } } query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)") || !$mysqli->query("INSERT INTO test(id) VALUES (1)")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* Explicitly allow eventual consistency and caching (TTL <= 60 seconds) */ if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL, MYSQLND_MS_QOS_OPTION_CACHE, 60)) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } /* To make this example work, we must wait for a slave to catch up. Brute force style. */ $attempts = 0; do { /* check if slave has the table */ if ($res = $mysqli->query("SELECT id FROM test")) { break; } else if ($mysqli->errno) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } /* wait for slave to catch up */ usleep(200000); } while ($attempts++ < 10); /* Query has been run on a slave, result is in the cache */ assert($res); var_dump($res->fetch_assoc()); /* Served from cache */ $res = $mysqli->query("SELECT id FROM test"); ?> The example shows how to use the cache feature. First, you have to set the quality of service to eventual consistency and explicitly allow for caching. This is done by calling *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. Then, the result set of every read-only statement is cached for upto that many seconds as allowed with *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. The actual TTL is lower or equal to the value set with *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. The value passed to the function sets the maximum age (seconds) of the data delivered. To calculate the actual TTL value the replication lag on a slave is checked and subtracted from the given value. If, for example, the maximum age is set to 60 seconds and the slave reports a lag of 10 seconds the resulting TTL is 50 seconds. The TTL is calculated individually for every cached query. query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)") || !$mysqli->query("INSERT INTO test(id) VALUES (1)")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* Explicitly allow eventual consistency and caching (TTL <= 60 seconds) */ if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL, MYSQLND_MS_QOS_OPTION_CACHE, 60)) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } /* To make this example work, we must wait for a slave to catch up. Brute force style. */ $attempts = 0; do { /* check if slave has the table */ if ($res = $mysqli->query("SELECT id FROM test")) { break; } else if ($mysqli->errno) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } /* wait for slave to catch up */ usleep(200000); } while ($attempts++ < 10); assert($res); /* Query has been run on a slave, result is in the cache */ var_dump($res->fetch_assoc()); /* Served from cache */ if (!($res = $mysqli->query("SELECT id FROM test"))) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); var_dump($res->fetch_assoc()); /* Update on master */ if (!$mysqli->query("UPDATE test SET id = 2")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* Read your writes */ if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION)) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } /* Fetch latest data */ if (!($res = $mysqli->query("SELECT id FROM test"))) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); var_dump($res->fetch_assoc()); ?> The quality of service can be changed at any time to avoid further cache usage. If needed, you can switch to read your writes (session consistency). In that case, the cache will not be used and fresh data is read.  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart.failover, Next: apis-php-mysqlnd-ms.quickstart.partitioning, Prev: apis-php-mysqlnd-ms.quickstart.cache, Up: apis-php-mysqlnd-ms.quickstart 21.9.2.13 Failover .................. Copyright 1997-2012 the PHP Documentation Group. By default, the plugin does not attempt to fail over if connecting to a host fails. This prevents pitfalls related to *Note connection state: apis-php-mysqlnd-ms.quickstart.connectionpooling. It is recommended to manually handle connection errors in a way similar to a failed transaction. You should catch the error, rebuild the connection state and rerun your query as shown below. If connection state is no issue to you, you can alternatively enable automatic and silent failover. Depending on the configuration, the automatic and silent failover will either attempt to fail over to the master before issuing and error or, try to connect to other slaves, given the query allowes for it, before attempting to connect to a master. Because *Note automatic failover: apis-php-mysqlnd-ms.failover. is not fool-proof, it is not discussed in the quickstart. Instead, details are given in the concepts section below. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "simulate_slave_failure", "port": "0" }, "slave_1": { "host": "127.0.0.1", "port": 3311 } }, "filters": { "roundrobin": [] } } } query($sql))) { /* plugin specific: check for connection error */ switch ($link->errno) { case 2002: case 2003: case 2005: printf("Connection error - trying next slave!\n"); /* load balancer will pick next slave */ $res = $link->query($sql); break; default: /* no connection error, failover is unlikely to help */ die(sprintf("SQL error: [%d] %s", $link->errno, $link->error)); break; } } if ($res) { var_dump($res->fetch_assoc()); } ?>  File: manual.info, Node: apis-php-mysqlnd-ms.quickstart.partitioning, Prev: apis-php-mysqlnd-ms.quickstart.failover, Up: apis-php-mysqlnd-ms.quickstart 21.9.2.14 Partitioning and Sharding ................................... Copyright 1997-2012 the PHP Documentation Group. Database clustering is done for various reasons. Clusters can improve availability, fault tolerance, and increase performance by applying a divide and conquer approach as work is distributed over many machines. Clustering is sometimes combined with partitioning and sharding to further break up a large complex task into smaller, more manageable units. The mysqlnd_ms plugin aims to support a wide variety of MySQL database clusters. Some flavors of MySQL database clusters have built-in methods for partitioning and sharding, which could be transparent to use. The plugin supports the two most common approaches: MySQL Replication table filtering, and Sharding (application based partitioning). MySQL Replication supports partitioning as filters that allow you to create slaves that replicate all or specific databases of the master, or tables. It is then in the responsibility of the application to choose a slave according to the filter rules. You can either use the mysqlnd_ms `node_groups' filter to manually support this, or use the experimental table filter. Manual partitioning or sharding is supported through the node grouping filter, and SQL hints as of 1.5.0. The node_groups filter lets you assign a symbolic name to a group of master and slave servers. In the example, the master `master_0' and `slave_0' form a group with the name `Partition_A'. It is entirely up to you to decide what makes up a group. For example, you may use node groups for sharding, and use the group names to address shards like `Shard_A_Range_0_100'. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "simulate_slave_failure", "port": "0" }, "slave_1": { "host": "127.0.0.1", "port": 3311 } }, "filters": { "node_groups": { "Partition_A" : { "master": ["master_0"], "slave": ["slave_0"] } }, "roundrobin": [] } } } query($sql))) { printf("[%d] %s", $mysqli->errno, $mysqli->error); return false; } $row = $res->fetch_assoc(); printf("%d - %s - %s\n", $row['_thread'], $row['_hint'], $sql); return true; } $mysqli = new mysqli("myapp", "user", "password", "database"); if (!$mysqli) /* Of course, your error handling is nicer... */ die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error())); /* All slaves allowed */ select($mysqli, "slave_0"); select($mysqli, "slave_1"); /* only servers of node group "Partition_A" allowed */ select($mysqli, "slave_1", "/*Partition_A*/"); select($mysqli, "slave_1", "/*Partition_A*/"); ?> 6804 - slave_0 - SELECT CONNECTION_ID() AS _thread, 'slave1' AS _hint FROM DUAL 2442 - slave_1 - SELECT CONNECTION_ID() AS _thread, 'slave2' AS _hint FROM DUAL 6804 - slave_0 - /*Partition_A*/SELECT CONNECTION_ID() AS _thread, 'slave1' AS _hint FROM DUAL 6804 - slave_0 - /*Partition_A*/SELECT CONNECTION_ID() AS _thread, 'slave1' AS _hint FROM DUAL By default, the plugin will use all configured master and slave servers for query execution. But if a query begins with a SQL hint like `/*node_group*/', the plugin will only consider the servers listed in the `node_group' for query execution. Thus, `SELECT' queries prefixed with `/*Partition_A*/' will only be executed on `slave_0'.  File: manual.info, Node: apis-php-mysqlnd-ms.concepts, Next: apis-php-mysqlnd-ms.setup, Prev: apis-php-mysqlnd-ms.quickstart, Up: apis-php-book.mysqlnd-ms 21.9.2.15 Concepts .................. * Menu: * apis-php-mysqlnd-ms.architecture:: Architecture * apis-php-mysqlnd-ms.pooling:: Connection pooling and switching * apis-php-mysqlnd-ms.transaction:: Transaction handling * apis-php-mysqlnd-ms.errorhandling:: Error handling * apis-php-mysqlnd-ms.transient_errors:: Transient errors * apis-php-mysqlnd-ms.failover:: Failover * apis-php-mysqlnd-ms.loadbalancing:: Load balancing * apis-php-mysqlnd-ms.rwsplit:: Read-write splitting * apis-php-mysqlnd-ms.filter:: Filter * apis-php-mysqlnd-ms.qos-consistency:: Service level and consistency * apis-php-mysqlnd-ms.gtid:: Global transaction IDs * apis-php-mysqlnd-ms.concept_cache:: Cache integration * apis-php-mysqlnd-ms.supportedclusters:: Supported clusters Copyright 1997-2012 the PHP Documentation Group. This explains the architecture and related concepts for this plugin, and describes the impact that MySQL replication and this plugin have on developmental tasks while using a database cluster. Reading and understanding these concepts is required, in order to use this plugin with success.  File: manual.info, Node: apis-php-mysqlnd-ms.architecture, Next: apis-php-mysqlnd-ms.pooling, Prev: apis-php-mysqlnd-ms.concepts, Up: apis-php-mysqlnd-ms.concepts 21.9.2.16 Architecture ...................... Copyright 1997-2012 the PHP Documentation Group. The mysqlnd replication and load balancing plugin is implemented as a PHP extension. It is written in C and operates under the hood of PHP. During the startup of the PHP interpreter, in the module init phase of the PHP engine, it gets registered as a See section "apis-php-mysqli" in the online manual plugin to replace selected mysqlnd C methods. At PHP runtime, it inspects queries sent from mysqlnd (PHP) to the MySQL server. If a query is recognized as read-only, it will be sent to one of the configured slave servers. Statements are considered read-only if they either start with `SELECT', the SQL hint `/*ms=slave*/' or a slave had been chosen for running the previous query, and the query started with the SQL hint `/*ms=last_used*/'. In all other cases, the query will be sent to the MySQL replication master server. For better portability, applications should use the MYSQLND_MS_MASTER_SWITCH , MYSQLND_MS_SLAVE_SWITCH , and MYSQLND_MS_LAST_USED_SWITCH *Note predefined mysqlnd_ms constants: apis-php-mysqlnd-ms.constants, instead of their literal values, such as `/*ms=slave*/'. The plugin handles the opening and closing of database connections to both master and slave servers. From an application point of view, there continues to be only one connection handle. However, internally, this one public connection handle represents a pool of network connections that are managed by the plugin. The plugin proxies queries to the master server, and to the slaves using multiple connections. Database connections have a state consisting of, for example, transaction status, transaction settings, character set settings, and temporary tables. The plugin will try to maintain the same state among all internal connections, whenever this can be done in an automatic and transparent way. In cases where it is not easily possible to maintain state among all connections, such as when using `BEGIN TRANSACTION', the plugin leaves it to the user to handle.  File: manual.info, Node: apis-php-mysqlnd-ms.pooling, Next: apis-php-mysqlnd-ms.transaction, Prev: apis-php-mysqlnd-ms.architecture, Up: apis-php-mysqlnd-ms.concepts 21.9.2.17 Connection pooling and switching .......................................... Copyright 1997-2012 the PHP Documentation Group. The replication and load balancing plugin changes the semantics of a PHP MySQL connection handle. The existing API of the PHP MySQL extensions (mysqli, mysql, and See section "apis-php-ref.pdo-mysql" in the online manual) are not changed in a way that functions are added or removed. But their behaviour changes when using the plugin. Existing applications do not need to be adapted to a new API, but they may need to be modified because of the behaviour changes. The plugin breaks the one-by-one relationship between a mysqli, mysql, and See section "apis-php-ref.pdo-mysql" in the online manual connection handle and a MySQL network connection. And a mysqli, mysql, and See section "apis-php-ref.pdo-mysql" in the online manual connection handle represents a local pool of connections to the configured MySQL replication master and MySQL replication slave servers. The plugin redirects queries to the master and slave servers. At some point in time one and the same PHP connection handle may point to the MySQL master server. Later on, it may point to one of the slave servers or still the master. Manipulating and replacing the network connection referenced by a PHP MySQL connection handle is not a transparent operation. Every MySQL connection has a state. The state of the connections in the connection pool of the plugin can differ. Whenever the plugin switches from one wire connection to another, the current state of the user connection may change. The applications must be aware of this. The following list shows what the connection state consists of. The list may not be complete. * Transaction status * Temporary tables * Table locks * Session system variables and session user variables * The current database set using `USE' and other state chaining SQL commands * Prepared statements * `HANDLER' variables * Locks acquired with `GET_LOCK()' Connection switches happen right before queries are executed. The plugin does not switch the current connection until the next statement is executed. *Replication issues*: See also the MySQL reference manual chapter about replication features (http://dev.mysql.com/doc/mysql/en/replication.html) and related issues. Some restrictions may not be related to the PHP plugin, but are properties of the MySQL replication system. Broadcasted messages The plugins philosophy is to align the state of connections in the pool only if the state is under full control of the plugin, or if it is necessary for security reasons. Just a few actions that change the state of the connection fall into this category. The following is a list of connection client library calls that change state, and are broadcasted to all open connections in the connection pool. If any of the listed calls below are to be executed, the plugin loops over all open master and slave connections. The loop continues until all servers have been contacted, and the loop does not break if a server indicates a failure. If possible, the failure will propagate to the called user API function, which may be detected depending on which underlying library function was triggered. Unknown PHP API feature. Library Notes Version call `change_user()'Called by the `mysqli_change_user' user API call. Since 1.0.0. Also triggered upon reuse of a persistent `mysqli' connection. `select_db'Called by the following user API calls: Since 1.0.0. `mysql_select_db', `mysql_list_tables', `mysql_db_query', `mysql_list_fields', `mysqli_select_db'. Note, that SQL `USE' is not monitored. `set_charset()'Called by the following user API calls: Since 1.0.0. `mysql_set_charset'. `mysqli_set_charset'. Note, that SQL `SET NAMES' is not monitored. `set_server_option()'Called by the following user API calls: Since 1.0.0. `mysqli_multi_query', `mysqli_real_query', `mysqli_query', `mysql_query'. `set_client_option()'Called by the following user API calls: Since 1.0.0. `mysqli_options', `mysqli_ssl_set', `mysqli_connect', `mysql_connect', `mysql_pconnect'. `set_autocommit()'Called by the following user API calls: Since 1.0.0. `mysqli_autocommit', PHP >= 5.4.0. `PDO::setAttribute(PDO::ATTR_AUTOCOMMIT)'. `ssl_set()'Called by the following user API calls: Since 1.1.0. `mysqli_ssl_set'. Broadcasting and lazy connections The plugin does not proxy or `remember' all settings to apply them on connections opened in the future. This is important to remember, if using lazy connections. Lazy connections are connections which are not opened before the client sends the first connection. Use of lazy connections is the default plugin action. The following connection library calls each changed state, and their execution is recorded for later use when lazy connections are opened. This helps ensure that the connection state of all connections in the connection pool are comparable. Unknown PHP API feature. Library Notes Version call `change_user()'User, password and database recorded for future Since 1.1.0. use. `select_db'Database recorded for future use. Since 1.1.0. `set_charset()'Calls `set_client_option(MYSQL_SET_CHARSET_NAME, Since 1.1.0. charset)' on lazy connection to ensure `charset' will be used upon opening the lazy connection. `set_autocommit()'Adds `SET AUTOCOMMIT=0|1' to the list of init Since 1.1.0. commands of a lazy connection using PHP >= 5.4.0. `set_client_option(MYSQL_INIT_COMMAND, "SET AUTOCOMMIT=...%quot;)'. *Connection state*: The connection state is not only changed by API calls. Thus, even if PECL mysqlnd_ms monitors all API calls, the application must still be aware. Ultimately, it is the applications responsibility to maintain the connection state, if needed. Charsets and string escaping Due to the use of lazy connections, which are a default, it can happen that an application tries to escape a string for use within SQL statements before a connection has been established. In this case string escaping is not possible. The string escape function does not know what charset to use before a connection has been established. To overcome the problem a new configuration setting `server_charset' has been introduced in version 1.4.0. Attention has to be paid on escaping strings with a certain charset but using the result on a connection that uses a different charset. Please note, that PECL/mysqlnd_ms manipulates connections and one application level connection represents a pool of multiple connections that all may have different default charsets. It is recommended to configure the servers involved to use the same default charsets. The configuration setting `server_charset' does help with this situation as well. If using `server_charset', the plugin will set the given charset on all newly opened connections.  File: manual.info, Node: apis-php-mysqlnd-ms.transaction, Next: apis-php-mysqlnd-ms.errorhandling, Prev: apis-php-mysqlnd-ms.pooling, Up: apis-php-mysqlnd-ms.concepts 21.9.2.18 Transaction handling .............................. Copyright 1997-2012 the PHP Documentation Group. Transaction handling is fundamentally changed. An SQL transaction is a unit of work that is run on one database server. The unit of work consists of one or more SQL statements. By default the plugin is not aware of SQL transactions. The plugin may switch connections for load balancing at any point in time. Connection switches may happen in the middle of a transaction. This is against the nature of an SQL transaction. By default, the plugin is not transaction safe. Any kind of MySQL load balancer must be hinted about the begin and end of a transaction. Hinting can either be done implicitly by monitoring API calls or using SQL hints. Both options are supported by the plugin, depending on your PHP version. API monitoring requires PHP 5.4.0 or newer. The plugin, like any other MySQL load balancer, cannot detect transaction boundaries based on the MySQL Client Server Protocol. Thus, entirely transparent transaction aware load balancing is not possible. The least intrusive option is API monitoring, which requires little to no application changes, depending on your application. Please, find examples of using SQL hints or the API monitoring in the *Note examples section: apis-php-mysqlnd-ms.quickstart. The details behind the API monitoring, which makes the plugin transaction aware, are described below. Beginning with PHP 5.4.0, the See section "apis-php-mysqli" in the online manual library allows this plugin to subclass the library C API call `set_autocommit()', to detect the status of `autocommit' mode. The PHP MySQL extensions either issue a query (such as `SET AUTOCOMMIT=0|1'), or use the mysqlnd library call `set_autocommit()' to control the `autocommit' setting. If an extension makes use of `set_autocommit()', the plugin can be made transaction aware. Transaction awareness cannot be achieved if using SQL to set the autocommit mode. The library function `set_autocommit()' is called by the `mysqli_autocommit' and `PDO::setAttribute(PDO::ATTR_AUTOCOMMIT)' user API calls. The plugin configuration option trx_stickiness=master can be used to make the plugin transactional aware. In this mode, the plugin stops load balancing if autocommit becomes disabled, and directs all statements to the master until autocommit gets enabled. An application that does not want to set SQL hints for transactions but wants to use the transparent API monitoring to avoid application changes must make sure that the autocommit settings is changed exclusively through the listed API calls. API based transaction boundary detection has been improved with PHP 5.5.0 and PECL/mysqlnd_ms 1.5.0 to cover not only calls to `mysqli_autocommit' but also `mysqli_begin' (http://www.php.net/mysqli_begin), `mysqli_commit' and `mysqli_rollback'.  File: manual.info, Node: apis-php-mysqlnd-ms.errorhandling, Next: apis-php-mysqlnd-ms.transient_errors, Prev: apis-php-mysqlnd-ms.transaction, Up: apis-php-mysqlnd-ms.concepts 21.9.2.19 Error handling ........................ Copyright 1997-2012 the PHP Documentation Group. Applications using PECL/mysqlnd_ms should implement proper error handling for all user API calls. And because the plugin changes the semantics of a connection handle, API calls may return unexpected errors. If using the plugin on a connection handle that no longer represents an individual network connection, but a connection pool, an error code and error message will be set on the connection handle whenever an error occurs on any of the network connections behind. If using lazy connections, which is the default, connections are not opened until they are needed for query execution. Therefore, an API call for a statement execution may return a connection error. In the example below, an error is provoked when trying to run a statement on a slave. Opening a slave connection fails because the plugin configuration file lists an invalid host name for the slave. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "invalid_host_name", } }, "lazy_connections": 1 } } The explicit activation of lazy connections is for demonstration purpose only. query("SET @myrole='master'")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } /* Connection 2, run on slave because SELECT, provoke connection error */ if (!($res = $mysqli->query("SELECT @myrole AS _role"))) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } else { $row = $res->fetch_assoc(); $res->close(); printf("@myrole = '%s'\n", $row['_role']); } $mysqli->close(); ?> The above example will output something similar to: PHP Warning: mysqli::query(): php_network_getaddresses: getaddrinfo failed: Name or service not known in %s on line %d PHP Warning: mysqli::query(): [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known (trying to connect via tcp://invalid_host_name:3306) in %s on line %d [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known Applications are expected to handle possible connection errors by implementing proper error handling. Depending on the use case, applications may want to handle connection errors differently from other errors. Typical connection errors are `2002 (CR_CONNECTION_ERROR) - Can't connect to local MySQL server through socket '%s' (%d)', `2003 (CR_CONN_HOST_ERROR) - Can't connect to MySQL server on '%s' (%d)' and `2005 (CR_UNKNOWN_HOST) - Unknown MySQL server host '%s' (%d)'. For example, the application may test for the error codes and manually perform a fail over. The plugins philosophy is not to offer automatic fail over, beyond master fail over, because fail over is not a transparent operation. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "invalid_host_name" }, "slave_1": { "host": "192.168.78.136" } }, "lazy_connections": 1, "filters": { "roundrobin": [ ] } } } Explicitly activating lazy connections is done for demonstration purposes, as is round robin load balancing as opposed to the default `random once' type. query("SET @myrole='master'")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } /* Connection 2, first slave */ $res = $mysqli->query("SELECT VERSION() AS _version"); /* Hackish manual fail over */ if (2002 == $mysqli->errno || 2003 == $mysqli->errno || 2004 == $mysqli->errno) { /* Connection 3, first slave connection failed, trying next slave */ $res = $mysqli->query("SELECT VERSION() AS _version"); } if (!$res) { printf("ERROR, [%d] '%s'\n", $mysqli->errno, $mysqli->error); } else { /* Error messages are taken from connection 3, thus no error */ printf("SUCCESS, [%d] '%s'\n", $mysqli->errno, $mysqli->error); $row = $res->fetch_assoc(); $res->close(); printf("version = %s\n", $row['_version']); } $mysqli->close(); ?> The above example will output something similar to: [1045] Access denied for user 'username'@'localhost' (using password: YES) PHP Warning: mysqli::query(): php_network_getaddresses: getaddrinfo failed: Name or service not known in %s on line %d PHP Warning: mysqli::query(): [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known (trying to connect via tcp://invalid_host_name:3306) in %s on line %d SUCCESS, [0] '' version = 5.6.2-m5-log In some cases, it may not be easily possible to retrieve all errors that occur on all network connections through a connection handle. For example, let's assume a connection handle represents a pool of three open connections. One connection to a master and two connections to the slaves. The application changes the current database using the user API call `mysqli_select_db', which then calls the mysqlnd library function to change the schemata. mysqlnd_ms monitors the function, and tries to change the current database on all connections to harmonize their state. Now, assume the master succeeds in changing the database, and both slaves fail. Upon the initial error from the first slave, the plugin will set an appropriate error on the connection handle. The same is done when the second slave fails to change the database. The error message from the first slave is lost. Such cases can be debugged by either checking for errors of the type `E_WARNING' (see above) or, if no other option, investigation of the *Note mysqlnd_ms debug and trace log: apis-php-mysqlnd-ms.debugging.  File: manual.info, Node: apis-php-mysqlnd-ms.transient_errors, Next: apis-php-mysqlnd-ms.failover, Prev: apis-php-mysqlnd-ms.errorhandling, Up: apis-php-mysqlnd-ms.concepts 21.9.2.20 Transient errors .......................... Copyright 1997-2012 the PHP Documentation Group. Some distributed database clusters make use of transient errors. A transient error is a temporary error that is likely to disappear soon. By definition it is safe for a client to ignore a transient error and retry the failed operation on the same database server. The retry is free of side effects. Clients are not forced to abort their work or to fail over to another database server immediately. They may enter a retry loop before to wait for the error to disappear before giving up on the database server. Transient errors can be seen, for example, when using MySQL Cluster. But they are not bound to any specific clustering solution per se. `PECL/mysqlnd_ms' can perform an automatic retry loop in case of a transient error. This increases distribution transparency and thus makes it easier to migrate an application running on a single database server to run on a cluster of database servers without having to change the source of the application. The automatic retry loop will repeat the requested operation up to a user configurable number of times and pause between the attempts for a configurable amount of time. If the error disappears during the loop, the application will never see it. If not, the error is forwarded to the application for handling. In the example below a duplicate key error is provoked to make the plugin retry the failing query two times before the error is passed to the application. Between the two attempts the plugin sleeps for 100 milliseconds. mysqlnd_ms.enable=1 mysqlnd_ms.collect_statistics=1 { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "transient_error": { "mysql_error_codes": [ 1062 ], "max_retries": 2, "usleep_retry": 100 } } } query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT PRIMARY KEY)") || !$mysqli->query("INSERT INTO test(id) VALUES (1))")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } /* Retry loop is completely transparent. Checking statistics is the only way to know about implicit retries */ $stats = mysqlnd_ms_get_stats(); printf("Transient error retries before error: %d\n", $stats['transient_error_retries']); /* Provoking duplicate key error to see statistics change */ if (!$mysqli->query("INSERT INTO test(id) VALUES (1))")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } $stats = mysqlnd_ms_get_stats(); printf("Transient error retries after error: %d\n", $stats['transient_error_retries']); $mysqli->close(); ?> The above example will output something similar to: Transient error retries before error: 0 [1062] Duplicate entry '1' for key 'PRIMARY' Transient error retries before error: 2 Because the execution of the retry loop is transparent from a users point of view, the example checks the *Note statistics: apis-php-function.mysqlnd-ms-get-stats. provided by the plugin to learn about it. As the example shows, the plugin can be instructed to consider any error transient regardless of the database servers error semantics. The only error that a stock MySQL server considers temporary has the error code 1297 . When configuring other error codes but 1297 make sure your configuration reflects the semantics of your clusters error codes. The following mysqlnd C API calls are monitored by the plugin to check for transient errors: `query()', `change_user()', `select_db()', `set_charset()', `set_server_option()' `prepare()', `execute()', `set_autocommit()', `tx_begin()', `tx_commit()', `tx_rollback()', `tx_commit_or_rollback()'. The corresponding user API calls have similar names. The maximum time the plugin may sleep during the retry loop depends on the function in question. The a retry loop for `query()', `prepare()' or `execute()' will sleep for up to `max_retries * usleep_retry' milliseconds. However, functions that *Note control connection state: apis-php-mysqlnd-ms.pooling. are dispatched to all all connections. The retry loop settings are applied to every connection on which the command is to be run. Thus, such a function may interrupt program execution for longer than a function that is run on one server only. For example, `set_autocommit()' is dispatched to connections and may sleep up to `(max_retries * usleep_retry) * number_of_open_connections)' milliseconds. Please, keep this in mind when setting long sleep times and large retry numbers. Using the default settings of `max_retries=1', `usleep_retry=100' and `lazy_connections=1' it is unlikely that you will ever see a delay of more than 1 second.  File: manual.info, Node: apis-php-mysqlnd-ms.failover, Next: apis-php-mysqlnd-ms.loadbalancing, Prev: apis-php-mysqlnd-ms.transient_errors, Up: apis-php-mysqlnd-ms.concepts 21.9.2.21 Failover .................. Copyright 1997-2012 the PHP Documentation Group. By default, connection failover handling is left to the user. The application is responsible for checking return values of the database functions it calls and reacting to possible errors. If, for example, the plugin recognizes a query as a read-only query to be sent to the slave servers, and the slave server selected by the plugin is not available, the plugin will raise an error after not executing the statement. _Default: manual failover_ It is up to the application to handle the error and, if required, re-issue the query to trigger the selection of another slave server for statement execution. The plugin will make no attempts to failover automatically, because the plugin cannot ensure that an automatic failover will not change the state of the connection. For example, the application may have issued a query which depends on SQL user variables which are bound to a specific connection. Such a query might return incorrect results if the plugin would switch the connection implicitly as part of automatic failover. To ensure correct results, the application must take care of the failover, and rebuild the required connection state. Therefore, by default, no automatic failover is performed by the plugin. A user that does not change the connection state after opening a connection may activate automatic failover. Please note, that automatic failover logic is limited to connection attempts. Automatic failover is not used for already established connections. There is no way to instruct the plugin to attempt failover on a connection that has been connected to MySQL already in the past. _Automatic failover_ The failover policy is configured in the plugins configuration file, by using the failover configuration directive. Automatic and silent failover can be enabled through the failover configuration directive. Automatic failover can either be configured to try exactly one master after a slave failure or, alternatively, loop over slaves and masters before returning an error to the user. The number of connection attempts can be limited and failed hosts can be excluded from future load balancing attempts. Limiting the number of retries and remembering failed hosts are considered experimental features, albeit being reasonable stable. Syntax and semantics may change in future versions. Please note, since version 1.5.0 automatic failover is disabled for the duration of a transaction if transaction stickiness is enabled and transaction boundaries have been detected. The plugin will not switch connections for the duration of a transaction. It will also not perform automatic and silent failover. Instead an error will be thrown. It is then left to the user to handle the failure of the transaction. Please check, the `trx_stickiness' documentation how to do this. A basic manual failover example is provided within the *Note error handling: apis-php-mysqlnd-ms.errorhandling. section. _Standby servers_ Using weighted load balancing, introduced in PECL/mysqlnd 1.4.0, it is possible to configure standby servers that are sparsely used during normal operations. A standby server that is primarily used as a worst-case standby failover target can be assigned a very low weight/priority in relation to all other servers. As long as all servers are up and running the majority of the workload is assigned to the servers which have hight weight values. Few requests will be directed to the standby system which has a very low weight value. Upon failure of the servers with a high priority, you can still failover to the standby, which has been given a low load balancing priority by assigning a low weight to it. Failover can be some manually or automatically. If done automatically, you may want to combine it with the `remember_failed' option. At this point, it is not possible to instruct the load balancer to direct no requests at all to a standby. This may not be much of a limitation given that the highest weight you can assign to a server is 65535. Given two slaves, of which one shall act as a standby and has been assigned a weight of 1, the standby will have to handle far less than one percent of the overall workload. _Failover and primary copy_ Please note, if using a primary copy cluster, such as MySQL Replication, it is difficult to do connection failover in case of a master failure. At any time there is only one master in the cluster for a given dataset. The master is a single point of failure. If the master fails, clients have no target to fail over write requests. In case of a master outage the database administrator must take care of the situation and update the client configurations, if need be.  File: manual.info, Node: apis-php-mysqlnd-ms.loadbalancing, Next: apis-php-mysqlnd-ms.rwsplit, Prev: apis-php-mysqlnd-ms.failover, Up: apis-php-mysqlnd-ms.concepts 21.9.2.22 Load balancing ........................ Copyright 1997-2012 the PHP Documentation Group. Four load balancing strategies are supported to distribute statements over the configured MySQL slave servers: 1. random Chooses a random server whenever a statement is executed. 2. random once (default) Chooses a random server after the first statement is executed, and uses the decision for the rest of the PHP request. It is the default, and the lowest impact on the connection state. 3. round robin Iterates over the list of configured servers. 4. user-defined via callback Is used to implement any other strategy. The load balancing policy is configured in the plugins configuration file using the random, roundrobin, and user *Note filters: apis-php-mysqlnd-ms.filter. Servers can be prioritized assigning a weight. A server that has been given a weight of two will get twice as many requests as a server that has been given the default weight of one. Prioritization can be handy in heterogenous environments. For example, you may want to assign more requests to a powerful machine than to a less powerful. Or, you may have configured servers that are close or far from the client, thus expose different latencies.  File: manual.info, Node: apis-php-mysqlnd-ms.rwsplit, Next: apis-php-mysqlnd-ms.filter, Prev: apis-php-mysqlnd-ms.loadbalancing, Up: apis-php-mysqlnd-ms.concepts 21.9.2.23 Read-write splitting .............................. Copyright 1997-2012 the PHP Documentation Group. The plugin executes read-only statements on the configured MySQL slaves, and all other queries on the MySQL master. Statements are considered read-only if they either start with `SELECT', the SQL hint `/*ms=slave*/', or if a slave had been chosen for running the previous query and the query starts with the SQL hint `/*ms=last_used*/'. In all other cases, the query will be sent to the MySQL replication master server. It is recommended to use the constants MYSQLND_MS_SLAVE_SWITCH , MYSQLND_MS_MASTER_SWITCH and MYSQLND_MS_LAST_USED_SWITCH instead of `/*ms=slave*/'. See also the *Note list of mysqlnd_ms constants: apis-php-mysqlnd-ms.constants. SQL hints are a special kind of standard compliant SQL comments. The plugin does check every statement for certain SQL hints. The SQL hints are described within the *Note mysqlnd_ms constants: apis-php-mysqlnd-ms.constants. documentation, constants that are exported by the extension. Other systems involved with the statement processing, such as the MySQL server, SQL firewalls, and SQL proxies, are unaffected by the SQL hints, because those systems are designed to ignore SQL comments. The built-in read-write splitter can be replaced by a user-defined filter, see also the user filter documentation. A user-defined read-write splitter can request the built-in logic to send a statement to a specific location, by invoking `mysqlnd_ms_is_select' (http://www.php.net/mysqlnd_ms_is_select). *Note*: The built-in read-write splitter is not aware of multi-statements. Multi-statements are seen as one statement. The splitter will check the beginning of the statement to decide where to run the statement. If, for example, a multi-statement begins with `SELECT 1 FROM DUAL; INSERT INTO test(id) VALUES (1); ...' the plugin will run it on a slave although the statement is not read-only.  File: manual.info, Node: apis-php-mysqlnd-ms.filter, Next: apis-php-mysqlnd-ms.qos-consistency, Prev: apis-php-mysqlnd-ms.rwsplit, Up: apis-php-mysqlnd-ms.concepts 21.9.2.24 Filter ................ Copyright 1997-2012 the PHP Documentation Group. *Version requirement*: Filters exist as of mysqlnd_ms version 1.1.0-beta. *Note filters: apis-php-mysqlnd-ms.plugin-ini-json. PHP applications that implement a MySQL replication cluster must first identify a group of servers in the cluster which could execute a statement before the statement is executed by one of the candidates. In other words: a defined list of servers must be filtered until only one server is available. The process of filtering may include using one or more filters, and filters can be chained. And they are executed in the order they are defined in the plugins configuration file. *Explanation: comparing filter chaining to pipes*: The concept of chained filters can be compared to using pipes to connect command line utilities on an operating system command shell. For example, an input stream is passed to a processor, filtered, and then transferred to be output. Then, the output is passed as input to the next command, which is connected to the previous using the pipe operator. Available filters: * Load balancing filters: random and roundrobin. * Selection filter: user, user_multi, quality_of_service. The `random' filter implements the 'random' and 'random once' load balancing policies. The 'round robin' load balancing can be configured through the `roundrobin' filter. Setting a 'user defined callback' for server selection is possible with the `user' filter. The `quality_of_service' filter finds cluster nodes capable of delivering a certain service, for example, read-your-writes or, not lagging more seconds behind the master than allowed. Filters can accept parameters to change their behaviour. The `random' filter accepts an optional `sticky' parameter. If set to true, the filter changes load balancing from random to random once. Random picks a random server every time a statement is to be executed. Random once picks a random server when the first statement is to be executed and uses the same server for the rest of the PHP request. One of the biggest strength of the filter concept is the possibility to chain filters. This strength does not become immediately visible because tje `random', `roundrobin' and `user' filters are supposed to output no more than one server. If a filter reduces the list of candidates for running a statement to only one server, it makes little sense to use that one server as input for another filter for further reduction of the list of candidates. An example filter sequence that will fail: * Statement to be executed: `SELECT 1 FROM DUAL'. Passed to all filters. * All configured nodes are passed as input to the first filter. Master nodes: `master_0'. Slave nodes:`slave_0', `slave_1' * Filter: `random', argument `sticky=1'. Picks a random slave once to be used for the rest of the PHP request. Output: `slave_0'. * Output of `slave_0' and the statement to be executed is passed as input to the next filter. Here: `roundrobin', server list passed to filter is: `slave_0'. * Filter: `roundrobin'. Server list consists of one server only, round robin will always return the same server. If trying to use such a filter sequence, the plugin may emit a warning like `(mysqlnd_ms) Error while creating filter '%s' . Non-multi filter '%s' already created. Stopping in %s on line %d'. Furthermore, an appropriate error on the connection handle may be set. A second type of filter exists: multi filter. A multi filter emits zero, one or multiple servers after processing. The `quality_of_service' filter is an example. If the service quality requested sets an upper limit for the slave lag and more than one slave is lagging behind less than the allowed number of seconds, the filter returns more than one cluster node. A multi filter must be followed by other to further reduce the list of candidates for statement execution until a candidate is found. A filter sequence with the `quality_of_service' multi filter followed by a load balancing filter. * Statement to be executed: `SELECT sum(price) FROM orders WHERE order_id = 1'. Passed to all filters. * All configured nodes are passed as input to the first filter. Master nodes: `master_0'. Slave nodes: `slave_0', `slave_1', `slave_2', `slave_3' * Filter: `quality_of_service', rule set: session_consistency (read-your-writes) Output: `master_0' * Output of `master_0' and the statement to be executed is passed as input to the next filter, which is `roundrobin'. * Filter: `roundrobin'. Server list consists of one server. Round robin selects `master_0'. A filter sequence must not end with a multi filter. If trying to use a filter sequence which ends with a multi filter the plugin may emit a warning like `(mysqlnd_ms) Error in configuration. Last filter is multi filter. Needs to be non-multi one. Stopping in %s on line %d'. Furthermore, an appropriate error on the connection handle may be set. *Speculation towards the future: MySQL replication filtering*: In future versions, there may be additional multi filters. For example, there may be a `table' filter to support MySQL replication filtering. This would allow you to define rules for which database or table is to be replicated to which node of a replication cluster. Assume your replication cluster consists of four slaves (`slave_0', `slave_1', `slave_2', `slave_3') two of which replicate a database named `sales' (`slave_0', `slave_1'). If the application queries the database `slaves', the hypothetical `table' filter reduces the list of possible servers to `slave_0' and `slave_1'. Because the output and list of candidates consists of more than one server, it is necessary and possible to add additional filters to the candidate list, for example, using a load balancing filter to identify a server for statement execution.  File: manual.info, Node: apis-php-mysqlnd-ms.qos-consistency, Next: apis-php-mysqlnd-ms.gtid, Prev: apis-php-mysqlnd-ms.filter, Up: apis-php-mysqlnd-ms.concepts 21.9.2.25 Service level and consistency ....................................... Copyright 1997-2012 the PHP Documentation Group. *Version requirement*: Service levels have been introduced in mysqlnd_ms version 1.2.0-alpha. *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. requires PHP 5.4.0 or newer. The plugin can be used with different kinds of MySQL database clusters. Different clusters can deliver different levels of service to applications. The service levels can be grouped by the data consistency levels that can be achieved. The plugin knows about: * eventual consistency * session consistency * strong consistency Depending how a cluster is used it may be possible to achieve higher service levels than the default one. For example, a read from an asynchronous MySQL replication slave is eventual consistent. Thus, one may say the default consistency level of a MySQL replication cluster is eventual consistency. However, if the master only is used by a client for reading and writing during a session, session consistency (read your writes) is given. PECL mysqlnd 1.2.0 abstracts the details of choosing an appropriate node for any of the above service levels from the user. Service levels can be set through the qualify-of-service filter in the *Note plugins configuration file: apis-php-mysqlnd-ms.plugin-ini-json. and at runtime using the function *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. The plugin defines the different service levels as follows. Eventual consistency is the default service provided by an asynchronous cluster, such as classical MySQL replication. A read operation executed on an arbitrary node may or may not return stale data. The applications view of the data is eventual consistent. Session consistency is given if a client can always read its own writes. An asynchronous MySQL replication cluster can deliver session consistency if clients always use the master after the first write or never query a slave which has not yet replicated the clients write operation. The plugins understanding of strong consistency is that all clients always see the committed writes of all other clients. This is the default when using MySQL Cluster or any other cluster offering synchronous data distribution. _Service level parameters_ Eventual consistency and session consistency service level accept parameters. Eventual consistency is the service provided by classical MySQL replication. By default, all nodes qualify for read requests. An optional `age' parameter can be given to filter out nodes which lag more than a certain number of seconds behind the master. The plugin is using `SHOW SLAVE STATUS' to measure the lag. Please, see the MySQL reference manual to learn about accuracy and reliability of the `SHOW SLAVE STATUS' command. Session consistency (read your writes) accepts an optional `GTID' parameter to consider reading not only from the master but also from slaves which already have replicated a certain write described by its transaction identifier. This way, when using asynchronous MySQL replication, read requests may be load balanced over slaves while still ensuring session consistency. The latter requires the use of *Note client-side global transaction id injection: apis-php-mysqlnd-ms.gtid. _Advantages of the new approach_ The new approach supersedes the use of SQL hints and the configuration option `master_on_write' in some respects. If an application running on top of an asynchronous MySQL replication cluster cannot accept stale data for certain reads, it is easier to tell the plugin to choose appropriate nodes than prefixing all read statements in question with the SQL hint to enforce the use of the master. Furthermore, the plugin may be able to use selected slaves for reading. The `master_on_write' configuration option makes the plugin use the master after the first write (session consistency, read your writes). In some cases, session consistency may not be needed for the rest of the session but only for some, few read operations. Thus, `master_on_write' may result in more read load on the master than necessary. In those cases it is better to request a higher than default service level only for those reads that actually need it. Once the reads are done, the application can return to default service level. Switching between service levels is only possible using *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. _Performance considerations_ A MySQL replication cluster cannot tell clients which slaves are capable of delivering which level of service. Thus, in some cases, clients need to query the slaves to check their status. PECL mysqlnd_ms transparently runs the necessary SQL in the background. However, this is an expensive and slow operation. SQL statements are run if eventual consistency is combined with an age (slave lag) limit and if session consistency is combined with a global transaction ID. If eventual consistency is combined with an maximum age (slave lag), the plugin selects candidates for statement execution and load balancing for each statement as follows. If the statement is a write all masters are considered as candidates. Slaves are not checked and not considered as candidates. If the statement is a read, the plugin transparently executes `SHOW SLAVE STATUS' on every slaves connection. It will loop over all connections, send the statement and then start checking for results. Usually, this is slightly faster than a loop over all connections in which for every connection a query is send and the plugin waits for its results. A slave is considered a candidate if `SHOW SLAVE STATUS' reports `Slave_IO_Running=Yes', `Slave_SQL_Running=Yes' and `Seconds_Behind_Master' is less or equal than the allowed maximum age. In case of an SQL error, the plugin emits a warning but does not set an error on the connection. The error is not set to make it possible to use the plugin as a drop-in. If session consistency is combined with a global transaction ID, the plugin executes the SQL statement set with the `fetch_last_gtid' entry of the `global_transaction_id_injection' section from the plugins configuration file. Further details are identical to those described above. In version 1.2.0 no additional optimizations are done for executing background queries. Future versions may contain optimizations, depending on user demand. If no parameters and options are set, no SQL is needed. In that case, the plugin consider all nodes of the type shown below. * eventual consistency, no further options set: all masters, all slaves * session consistency, no further options set: all masters * strong consistency (no options allowed): all masters _Throttling_ The quality of service filter can be combined with *Note Global transaction IDs: apis-php-mysqlnd-ms.gtid. to throttle clients. Throttling does reduce the write load on the master by slowing down clients. If session consistency is requested and global transactions idenentifier are used to check the status of a slave, the check can be done in two ways. By default a slave is checked and skipped immediately if it does not match the criteria for session consistency. Alternatively, the plugin can wait for a slave to catch up to the master until session consistency is possible. To enable the throttling, you have to set wait_for_gtid_timeout configuration option.  File: manual.info, Node: apis-php-mysqlnd-ms.gtid, Next: apis-php-mysqlnd-ms.concept_cache, Prev: apis-php-mysqlnd-ms.qos-consistency, Up: apis-php-mysqlnd-ms.concepts 21.9.2.26 Global transaction IDs ................................ Copyright 1997-2012 the PHP Documentation Group. *Version requirement*: Client side global transaction ID injection exists as of mysqlnd_ms version 1.2.0-alpha. Transaction boundaries are detected by monitoring API calls. This is possible as of PHP 5.4.0. Please, see also *Note Transaction handling: apis-php-mysqlnd-ms.transaction. As of MySQL 5.6.5-m8 the MySQL server features built-in global transaction identifiers. The MySQL built-in global transaction ID feature is supported by PECL/mysqlnd_ms 1.3.0-alpha or later. Neither are client-side transaction boundary monitoring nor any setup activities required if using the server feature. _Idea and client-side emulation_ PECL/mysqlnd_ms can do client-side transparent global transaction ID injection. In its most basic form, a global transaction identifier is a counter which is incremented for every transaction executed on the master. The counter is held in a table on the master. Slaves replicate the counter table. In case of a master failure a database administrator can easily identify the most recent slave for promiting it as a new master. The most recent slave has the highest transaction identifier. Application developers can ask the plugin for the global transaction identifier (GTID) for their last successful write operation. The plugin will return an identifier that refers to an transaction no older than that of the clients last write operation. Then, the GTID can be passed as a parameter to the quality of service (QoS) filter as an option for session consistency. Session consistency ensures read your writes. The filter ensures that all reads are either directed to a master or a slave which has replicated the write referenced by the GTID. _When injection is done_ The plugin transparently maintains the GTID table on the master. In autocommit mode the plugin injects an `UPDATE' statement before executing the users statement for every master use. In manual transaction mode, the injection is done before the application calls `commit()' to close a transaction. The configuration option `report_error' of the GTID section in the plugins configuration file is used to control whether a failed injection shall abort the current operation or be ignored silently (default). Please note, the PHP version requirements for *Note transaction boundary monitoring: apis-php-mysqlnd-ms.transaction. and their limits. _Limitations_ Client-side global transaction ID injection has shortcomings. The potential issues are not specific to PECL/mysqlnd_ms but are rather of general nature. * Global transaction ID tables must be deployed on all masters and replicas. * The GTID can have holes. Only PHP clients using the plugin will maintain the table. Other clients will not. * Client-side transaction boundary detection is based on API calls only. * Client-side transaction boundary detection does not take implicit commit into account. Some MySQL SQL statements cause an implicit commit and cannot be rolled back. _Using server-side global transaction identifier_ Starting with PECL/mysqlnd_ms 1.3.0-alpha the MySQL 5.6.5-m8 or newer built-in global transaction identifier feature is supported. Use of the server feature lifts all of the above listed limitations. Please, see the MySQL Reference Manual for limitations and preconditions for using server built-in global transaction identifiers. Whether to use the client-side emulation or the server built-in functionality is a question not directly related to the plugin, thus it is not discussed in depth. There are no plans to remove the client-side emulation and you can continue to use it, if the server-side solution is no option. This may be the case in heterogenous environments with old MySQL server or, if any of the server-side solution limitations is not acceptable. From an applications perspective there is hardly a difference in using one or the other approach. The following properties differ. * Client-side emulation, as shown in the manual, is using an easy to compare sequence number for global transactions. Multi-master is not handled to keep the manual examples easy. Server-side built-in feature is using a combination of a server identifier and a sequence number as a global transaction identifier. Comparison cannot use numeric algebra. Instead a SQL function must be used. Please, see the MySQL Reference Manual for details. * Plugin global transaction ID statistics are only available with client-side emulation because they monitor the emulation. *Global transaction identifiers in distributed systems*: Global transaction identifiers can serve multiple purposes in the context of distributed systems, such as a database cluster. Global transaction identifiers can be used for, for example, system wide identification of transactions, global ordering of transactions, heartbeat mechanism and for checking the replication status of replicas. PECL/mysqlnd_ms, a clientside driver based software, does focus on using GTIDs for tasks that can be handled at the client, such as checking the replication status of replicas for asynchronous replication setups.  File: manual.info, Node: apis-php-mysqlnd-ms.concept_cache, Next: apis-php-mysqlnd-ms.supportedclusters, Prev: apis-php-mysqlnd-ms.gtid, Up: apis-php-mysqlnd-ms.concepts 21.9.2.27 Cache integration ........................... Copyright 1997-2012 the PHP Documentation Group. *Version requirement*: The feature requires use of PECL/mysqlnd_ms 1.3.0-beta or later, and PECL/mysqlnd_qc 1.1.0-alpha or newer. PECL/mysqlnd_ms must be compiled to support the feature. PHP 5.4.0 or newer is required. *Setup: extension load order*: PECL/mysqlnd_ms must be loaded before PECL/mysqlnd_qc, when using shared extensions. *Feature stability*: The cache integration is of beta quality. *Suitable MySQL clusters*: The feature is targeted for use with MySQL Replication (primary copy). Currently, no other kinds of MySQL clusters are supported. Users of such cluster must control PECL/mysqlnd_qc manually if they are interested in client-side query caching. Support for MySQL replication clusters (asynchronous primary copy) is the main focus of PECL/mysqlnd_ms. The slaves of a MySQL replication cluster may or may not reflect the latest updates from the master. Slaves are asynchronous and can lag behind the master. A read from a slave is eventual consistent from a cluster-wide perspective. The same level of consistency is offered by a local cache using time-to-live (TTL) invalidation strategy. Current data or stale data may be served. Eventually, data searched for in the cache is not available and the source of the cache needs to be accessed. Given that both a MySQL Replication slave (asynchronous secondary) and a local TTL-driven cache deliver the same level of service it is possible to transparently replace a remote database access with a local cache access to gain better possibility. As of PECL/mysqlnd_ms 1.3.0-beta the plugin is capable of transparently controlling PECL/mysqlnd_ms 1.1.0-alpha or newer to cache a read-only query if explicitly allowed by setting an appropriate quality of service through *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. Please, see the *Note quickstart: apis-php-mysqlnd-ms.quickstart.cache. for a code example. Both plugins must be installed, PECL/mysqlnd_ms must be compiled to support the cache feature and PHP 5.4.0 or newer has to be used. Applications have full control of cache usage and can request fresh data at any time, if need be. Thec ache usage can be enabled and disabled time during the execution of a script. The cache will be used if *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. sets the quality of service to eventual consistency and enables cache usage. Cache usage is disabled by requesting higher consistency levels, for example, session consistency (read your writes). Once the quality of service has been relaxed to eventual consistency the cache can be used again. If caching is enabled for a read-only statement, PECL/mysqlnd_ms may inject *Note SQL hints to control caching: apis-php-mysqlnd-qc.quickstart.caching. by PECL/mysqlnd_qc. It may modify the SQL statement it got from the application. Subsequent SQL processors are supposed to ignore the SQL hints. A SQL hint is a SQL comment. Comments must not be ignored, for example, by the database server. The TTL of a cache entry is computed on a per statement basis. Applications set an maximum age for the data they want to retrieve using *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. The age sets an approximate upper limit of how many seconds the data returned may lag behind the master. The following logic is used to compute the actual TTL if caching is enabled. The logic takes the estimated slave lag into account for choosing a TTL. If, for example, there are two slaves lagging 5 and 10 seconds behind and the maximum age allowed is 60 seconds, the TTL is set to 50 seconds. Please note, the age setting is no more than an estimated guess. * Check whether the statement is read-only. If not, don't cache. * If caching is enabled, check the slave lag of all configured slaves. Establish slave connections if none exist so far and lazy connections are used. * Send `SHOW SLAVE STATUS' to all slaves. Do not wait for the first slave to reply before sending to the second slave. Clients often wait long for replies, thus we send out all requests in a burst before fetching in a second stage. * Loop over all slaves. For every slave wait for its reply. Do not start checking another slave before the currently waited for slave has replied. Check for `Slave_IO_Running=Yes' and `Slave_SQL_Running=Yes'. If both conditions hold true, fetch the value of `Seconds_Behind_Master'. In case of any errors or if conditions fail, set an error on the slave connection. Skip any such slave connection for the rest of connection filtering. * Search for the maximum value of `Seconds_Behind_Master' from all slaves that passed the previous conditions. Subtract the value from the maximum age provided by the user with *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. Use the result as a TTL. * The filtering may sort out all slaves. If so, the maximum age is used as TTL, because the maximum lag found equals zero. It is perfectly valid to sort out all slaves. In the following it is up to subsequent filter to decide what to do. The built-in load balancing filter will pick the master. * Inject the appropriate SQL hints to enable caching by PECL/mysqlnd_qc. * Proceed with the connection filtering, e.g. apply load balancing rules to pick a slave. * PECL/mysqlnd_qc is loaded after PECL/mysqlnd_ms by PHP. Thus, it will see all query modifications of PECL/mysqlnd_ms and cache the query if instructed to do so. The algorithm may seem expensive. `SHOW SLAVE STATUS' is a very fast operation. Given a sufficient number of requests and cache hits per second the cost of checking the slaves lag can easily outweight the costs of the cache decision. Suggestions on a better algorithm are always welcome.  File: manual.info, Node: apis-php-mysqlnd-ms.supportedclusters, Prev: apis-php-mysqlnd-ms.concept_cache, Up: apis-php-mysqlnd-ms.concepts 21.9.2.28 Supported clusters ............................ Copyright 1997-2012 the PHP Documentation Group. Any application using any kind of MySQL cluster is faced with the same tasks: * Identify nodes capable of executing a given statement with the required service level * Load balance requests within the list of candidates * Automatic fail over within candidates, if needed The plugin is optimized for fulfilling these tasks in the context of a classical asynchronous MySQL replication cluster consisting of a single master and many slaves (primary copy). When using classical, asynchronous MySQL replication all of the above listed tasks need to be mastered at the client side. Other types of MySQL cluster may have lower requirements on the application side. For example, if all nodes in the cluster can answer read and write requests, no read-write splitting needs to be done (multi-master, update-all). If all nodes in the cluster are synchronous, they automatically provide the highest possible quality of service which makes choosing a node easier. In this case, the plugin may serve the application after some reconfiguration to disable certain features, such as built-in read-write splitting. *Documentation focus*: The documentation focusses describing the use of the plugin with classical asynchronous MySQL replication clusters (primary copy). Support for this kind of cluster has been the original development goal. Use of other clusters is briefly described below. Please note, that this is still work in progress. _Primary copy (MySQL Replication)_ This is the primary use case of the plugin. Follow the hints given in the descriptions of each feature. * Configure one master and one or more slaves. Server configuration details are given in the setup section. * Use random load balancing policy together with the sticky flag. * If you do not plan to use the *Note service level: apis-php-mysqlnd-ms.quickstart.qos-consistency. API calls, add the master on write flag. * Please, make yourself aware of the properties of automatic failover before adding a failover directive. * Consider the use of trx_stickiness to execute transactions on the primary only. Please, read carefully how it works before you rely on it. mysqlnd_ms.enable=1 mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini { "myapp": { "master": { "master_1": { "host": "localhost", "socket": "\/tmp\/mysql57.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": 3308 }, "slave_1": { "host": "192.168.2.28", "port": 3306 } }, "filters": { "random": { "sticky": "1" } } } } _Primary copy with multi primaries (MMM - MySQL Multi Master)_ MySQL Replication allows you to create cluster topologies with multiple masters (primaries). Write-write conflicts are not handled by the replication system. This is no update anywhere setup. Thus, data must be partitioned manually and clients must redirected in accordance to the partitioning rules. The recommended setup is equal to the sharding setup below. _Manual sharding, possibly combined with primary copy and multiple primaries_ Use SQL hints and the node group filter for clusters that use data partitioning but leave query redirection to the client. The example configuration shows a multi master setup with two shards. mysqlnd_ms.enable=1 mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini mysqlnd_ms.multi_master=1 { "myapp": { "master": { "master_1": { "host": "localhost", "socket": "\/tmp\/mysql57.sock" } "master_2": { "host": "192.168.2.27", "socket": "3306" } }, "slave": { "slave_1": { "host": "127.0.0.1", "port": 3308 }, "slave_2": { "host": "192.168.2.28", "port": 3306 } }, "filters": { "node_groups": { "Partition_A" : { "master": ["master_1"], "slave": ["slave_1"] }, "Partition_B" : { "master": ["master_2"], "slave": ["slave_2"] } }, "roundrobin": [] } } } The plugin can also be used with a loose collection of unrelated shards. For such a cluster, configure masters only and disable read write splitting. The nodes of such a cluster are called masters in the plugin configuration as they accept both reads and writes for their partition. _Using synchronous update everywhere clusters such as MySQL Cluster_ MySQL Cluster is a synchronous cluster solution. All cluster nodes accept read and write requests. In the context of the plugin, all nodes shall be considered as masters. Use the load balancing and fail over features only. * Disable the plugins *Note built-in read-write splitting: apis-php-mysqlnd-ms.rwsplit. * Configure masters only. * Consider random once load balancing strategy, which is the plugins default. If random once is used, only masters are configured and no SQL hints are used to force using a certain node, no connection switches will happen for the duration of a web request. Thus, no special handling is required for transactions. The plugin will pick one master at the beginning of the PHP script and use it until the script terminates. * Do not set the quality of service. All nodes have all the data. This automatically gives you the highest possible service quality (strong consistency). * Do not enable client-side global transaction injection. It is neither required to help with server-side fail over nor to assist the quality of service filter choosing an appropriate node. Disabling built-in read-write splitting. * Set *Note `mysqlnd_ms.disable_rw_split=1': apis-php-mysqlnd-ms.configuration. * Do not use *Note SQL hints: apis-php-mysqlnd-ms.rwsplit. to enforce the use of slaves Configure masters only. * Set *Note `mysqlnd_ms.multi_master=1'.: apis-php-mysqlnd-ms.configuration. * Do not configure any slaves. * Set `*Note failover=loop_before_master: apis-php-mysqlnd-ms.plugin-ini-json.' in the plugins configuration file to avoid warnings about the empty slave list and to make the failover logic loop over all configured masters before emitting an error. Please, note the warnings about automatic failover given in the previous sections. mysqlnd_ms.enable=1 mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini mysqlnd_ms.multi_master=1 mysqlnd_ms.disable_rw_split=1 "myapp": { "master": { "master_1": { "host": "localhost", "socket": "\/tmp\/mysql57.sock" }, "master_2": { "host": "192.168.2.28", "port": 3306 } }, "slave": { }, "filters": { "roundrobin": { } }, "failover": { "strategy": "loop_before_master", "remember_failed": true } } } If running an update everywhere cluster that has no built-in partitioning to avoid hot spots and high collision rates, consider using the node groups filter to keep updates on a frequently accessed table on one of the nodes. This may help to reduce collision rates and thus improve performance.  File: manual.info, Node: apis-php-mysqlnd-ms.setup, Next: apis-php-mysqlnd-ms.constants, Prev: apis-php-mysqlnd-ms.concepts, Up: apis-php-book.mysqlnd-ms 21.9.2.29 Installing/Configuring ................................ * Menu: * apis-php-mysqlnd-ms.requirements:: Requirements * apis-php-mysqlnd-ms.installation:: Installation * apis-php-mysqlnd-ms.configuration:: Runtime Configuration * apis-php-mysqlnd-ms.plugin-ini-json:: Plugin configuration file (>=1.1.x) * apis-php-mysqlnd-ms.plugin-ini-v1:: Plugin configuration file (<= 1.0.x) * apis-php-mysqlnd-ms.testing:: Testing * apis-php-mysqlnd-ms.debugging:: Debugging and Tracing * apis-php-mysqlnd-ms.monitoring:: Monitoring Copyright 1997-2012 the PHP Documentation Group.  File: manual.info, Node: apis-php-mysqlnd-ms.requirements, Next: apis-php-mysqlnd-ms.installation, Prev: apis-php-mysqlnd-ms.setup, Up: apis-php-mysqlnd-ms.setup 21.9.2.30 Requirements ...................... Copyright 1997-2012 the PHP Documentation Group. `PHP 5.3.6' or newer. Some advanced functionality requires `PHP 5.4.0' or newer. The `mysqlnd_ms' replication and load balancing plugin supports all PHP applications and all available PHP MySQL extensions (mysqli, mysql, See section "apis-php-ref.pdo-mysql" in the online manual). The PHP MySQL extension must be configured to use See section "apis-php-mysqli" in the online manual in order to be able to use the `mysqlnd_ms' plugin for See section "apis-php-mysqli" in the online manual.  File: manual.info, Node: apis-php-mysqlnd-ms.installation, Next: apis-php-mysqlnd-ms.configuration, Prev: apis-php-mysqlnd-ms.requirements, Up: apis-php-mysqlnd-ms.setup 21.9.2.31 Installation ...................... Copyright 1997-2012 the PHP Documentation Group. This PECL (http://pecl.php.net/) extension is not bundled with PHP. Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions (http://www.php.net/install.pecl). Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/mysqlnd_ms (http://pecl.php.net/package/mysqlnd_ms) A DLL for this PECL extension is currently unavailable. See also the building on Windows (http://www.php.net/install.windows.building) section.  File: manual.info, Node: apis-php-mysqlnd-ms.configuration, Next: apis-php-mysqlnd-ms.plugin-ini-json, Prev: apis-php-mysqlnd-ms.installation, Up: apis-php-mysqlnd-ms.setup 21.9.2.32 Runtime Configuration ............................... Copyright 1997-2012 the PHP Documentation Group. The behaviour of these functions is affected by settings in `php.ini'. *Mysqlnd_ms Configure Options* Name Default Changeable Changelog mysqlnd_ms.enable 0 PHP_INI_SYSTEM mysqlnd_ms.force_config_usage0 PHP_INI_SYSTEM mysqlnd_ms.ini_file"" PHP_INI_SYSTEM mysqlnd_ms.config_file"" PHP_INI_SYSTEM mysqlnd_ms.collect_statistics0 PHP_INI_SYSTEM mysqlnd_ms.multi_master0 PHP_INI_SYSTEM mysqlnd_ms.disable_rw_split0 PHP_INI_SYSTEM Here's a short explanation of the configuration directives. 1. mysqlnd_ms.enable integer Enables or disables the plugin. If disabled, the extension will not plug into See section "apis-php-mysqli" in the online manual to proxy internal See section "apis-php-mysqli" in the online manual C API calls. 2. mysqlnd_ms.force_config_usage integer If enabled, the plugin checks if the host (server) parameters value of any MySQL connection attempt, matches a section name from the plugin configuration file. If not, the connection attempt is blocked. This setting is not only useful to restrict PHP to certain servers but also to debug configuration file problems. The configuration file validity is checked at two different stages. The first check is performed when PHP begins to handle a web request. At this point the plugin reads and decodes the configuration file. Errors thrown at this early stage in an extensions life cycle may not be shown properly to the user. Thus, the plugin buffers the errors, if any, and additionally displays them when establishing a connection to MySQL. By default a buffered startup error will emit an error of type `E_WARNING'. If `force_config_usage' is set, the error type used is `E_RECOVERABLE_ERROR'. Please, see also configuration file debugging notes. 3. mysqlnd_ms.ini_file string Plugin specific configuration file. This setting has been renamed to `mysqlnd_ms.config_file' in version 1.4.0. 4. mysqlnd_ms.config_file string Plugin specific configuration file. This setting superseeds `mysqlnd_ms.ini_file' since 1.4.0. 5. mysqlnd_ms.collect_statistics integer Enables or disables the collection of statistics. The collection of statistics is disabled by default for performance reasons. Statistics are returned by the function *Note `mysqlnd_ms_get_stats': apis-php-function.mysqlnd-ms-get-stats. 6. mysqlnd_ms.multi_master integer Enables or disables support of MySQL multi master replication setups. Please, see also *Note supported clusters: apis-php-mysqlnd-ms.supportedclusters. 7. mysqlnd_ms.disable_rw_split integer Enables or disables built-in read write splitting. Controls whether load balancing and lazy connection functionality can be used independently of read write splitting. If read write splitting is disabled, only servers from the master list will be used for statement execution. All configured slave servers will be ignored. The SQL hint `MYSQLND_MS_USE_SLAVE' will not be recognized. If found, the statement will be redirected to a master. Disabling read write splitting impacts the return value of *Note `mysqlnd_ms_query_is_select': apis-php-function.mysqlnd-ms-query-is-select. The function will no longer propose query execution on slave servers. *Multiple master servers*: Setting `mysqlnd_ms.multi_master=1' allows the plugin to use multiple master servers, instead of only the first master server of the master list. Please, see also *Note supported clusters: apis-php-mysqlnd-ms.supportedclusters.  File: manual.info, Node: apis-php-mysqlnd-ms.plugin-ini-json, Next: apis-php-mysqlnd-ms.plugin-ini-v1, Prev: apis-php-mysqlnd-ms.configuration, Up: apis-php-mysqlnd-ms.setup 21.9.2.33 Plugin configuration file (>=1.1.x) ............................................. Copyright 1997-2012 the PHP Documentation Group. *Changelog: Feature was added in PECL/mysqlnd_ms 1.1.0-beta*: The below description applies to PECL/mysqlnd_ms >= 1.1.0-beta. It is not valid for prior versions. The plugin uses its own configuration file. The configuration file holds information about the MySQL replication master server, the MySQL replication slave servers, the server pick (load balancing) policy, the failover strategy, and the use of lazy connections. The plugin loads its configuration file at the beginning of a web request. It is then cached in memory and used for the duration of the web request. This way, there is no need to restart PHP after deploying the configuration file. Configuration file changes will become active almost instantly. The PHP configuration directive `mysqlnd_ms.config_file' is used to set the plugins configuration file. Please note, that the PHP configuration directive may not be evaluated for every web request. Therefore, changing the plugins configuration file name or location may require a PHP restart. However, no restart is required to read changes if an already existing plugin configuration file is updated. Using and parsing JSON is efficient, and using JSON makes it easier to express hierarchical data structures than the standard `php.ini' format. Or alternatively, a developer may be more familiar with the PHP array syntax, and prefer it. This example demonstrates how a developer might convert a PHP array to JSON. array( "master" => array( "master_0" => array( "host" => "localhost", "socket" => "/tmp/mysql.sock", ), ), "slave" => array(), ), ); file_put_contents("mysqlnd_ms.ini", json_encode($config, JSON_PRETTY_PRINT)); printf("mysqlnd_ms.ini file created...\n"); printf("Dumping file contents...\n"); printf("%s\n", str_repeat("-", 80)); echo file_get_contents("mysqlnd_ms.ini"); printf("\n%s\n", str_repeat("-", 80)); ?> The above example will output: mysqlnd_ms.ini file created... Dumping file contents... -------------------------------------------------------------------------------- { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": [ ] } } -------------------------------------------------------------------------------- A plugin configuration file consists of one or more sections. Sections are represented by the top-level object properties of the object encoded in the JSON file. Sections could also be called _configuration names_. Applications reference sections by their name. Applications use section names as the host (server) parameter to the various connect methods of the mysqli, mysql and See section "apis-php-ref.pdo-mysql" in the online manual extensions. Upon connect, the See section "apis-php-mysqli" in the online manual plugin compares the hostname with all of the section names from the plugin configuration file. If the hostname and section name match, then the plugin will load the settings for that section. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.2.27" }, "slave_1": { "host": "192.168.2.27", "port": 3306 } } }, "localhost": { "master": [ { "host": "localhost", "socket": "\/path\/to\/mysql.sock" } ], "slave": [ { "host": "192.168.3.24", "port": "3305" }, { "host": "192.168.3.65", "port": "3309" } ] } } Section names are strings. It is valid to use a section name such as `192.168.2.1', `127.0.0.1' or `localhost'. If, for example, an application connects to `localhost' and a plugin configuration section `localhost' exists, the semantics of the connect operation are changed. The application will no longer only use the MySQL server running on the host `localhost', but the plugin will start to load balance MySQL queries following the rules from the `localhost' configuration section. This way you can load balance queries from an application without changing the applications source code. Please keep in mind, that such a configuration may not contribute to overall readability of your applications source code. Using section names that can be mixed up with host names should be seen as a last resort. Each configuration section contains, at a minimum, a list of master servers and a list of slave servers. The master list is configured with the keyword `master', while the slave list is configured with the `slave' keyword. Failing to provide a slave list will result in a fatal E_ERROR level error, although a slave list may be empty. It is possible to allow no slaves. However, this is only recommended with synchronous clusters, please see also *Note supported clusters: apis-php-mysqlnd-ms.supportedclusters. The main part of the documentation focusses on the use of asynchronous MySQL replication clusters. The master and slave server lists can be optionally indexed by symbolic names for the servers they describe. Alternatively, an array of descriptions for slave and master servers may be used. "slave": [ { "host": "192.168.3.24", "port": "3305" }, { "host": "192.168.3.65", "port": "3309" } ] An anonymous server list is encoded by the `JSON array' type. Optionally, symbolic names may be used for indexing the slave or master servers of a server list, and done so using the `JSON object' type. "master": { "master_0": { "host": "localhost" } } It is recommended to index the server lists with symbolic server names. The alias names will be shown in error messages. The order of servers is preserved and taken into account by mysqlnd_ms. If, for example, you configure round robin load balancing strategy, the first `SELECT' statement will be executed on the slave that appears first in the slave server list. A configured server can be described with the `host', `port', `socket', `db', `user', `password' and `connect_flags'. It is mandatory to set the database server host using the `host' keyword. All other settings are optional. { "myapp": { "master": { "master_0": { "host": "db_server_host", "port": "db_server_port", "socket": "db_server_socket", "db": "database_resp_schema", "user": "user", "password": "password", "connect_flags": 0 } }, "slave": { "slave_0": { "host": "db_server_host", "port": "db_server_port", "socket": "db_server_socket" } } } } If a setting is omitted, the plugin will use the value provided by the user API call used to open a connection. Please, see the using section names example above. The configuration file format has been changed in version 1.1.0-beta to allow for chained filters. Filters are responsible for filtering the configured list of servers to identify a server for execution of a given statement. Filters are configured with the `filter' keyword. Filters are executed by mysqlnd_ms in the order of their appearance. Defining filters is optional. A configuration section in the plugins configuration file does not need to have a `filters' entry. Filters replace the `pick[]' setting from prior versions. The new `random' and `roundrobin' provide the same functionality. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" }, "slave_1": { "host": "192.168.78.137", "port": "3306" } }, "filters": { "roundrobin": [ ] } } } The function *Note `mysqlnd_ms_set_user_pick_server': apis-php-function.mysqlnd-ms-set-user-pick-server. has been removed. Setting a callback is now done with the `user' filter. Some filters accept parameters. The `user' filter requires and accepts a mandatory `callback' parameter to set the callback previously set through the function *Note `mysqlnd_ms_set_user_pick_server': apis-php-function.mysqlnd-ms-set-user-pick-server. "filters": { "user": { "callback": "pick_server" } } The validity of the configuration file is checked both when reading the configuration file and later when establishing a connection. The configuration file is read during PHP request startup. At this early stage a PHP extension may not display error messages properly. In the worst case, no error is shown and a connection attempt fails without an adequate error message. This problem has been cured in version 1.5.0. The above example will output: Warning: mysqli::mysqli(): (mysqlnd_ms) (mysqlnd_ms) Failed to parse config file [s1.json]. Please, verify the JSON in Command line code Warning: mysqli::mysqli(): (HY000/2002): php_network_getaddresses: getaddrinfo failed: Name or service not known in Command line code on line 1 Warning: mysqli::query(): Couldn't fetch mysqli in Command line code on line 1 Fatal error: Call to a member function fetch_assoc() on a non-object in Command line code on line 1 Since version 1.5.0 startup errors are additionally buffered and emitted when a connection attempt is made. Use the configuration directive `mysqlnd_ms.force_config_usage' to set the error type used to display buffered errors. By default an error of type `E_WARNING' will be emitted. The above example will output: Warning: mysqli::mysqli(): (mysqlnd_ms) (mysqlnd_ms) Failed to parse config file [s1.json]. Please, verify the JSON in Command line code on line 1 It can be useful to set `mysqlnd_ms.force_config_usage = 1' when debugging potential configuration file errors. This will not only turn the type of buffered startup errors into `E_RECOVERABLE_ERROR' but also help detecting misspelled section names. mysqlnd_ms.force_config_usage=1 The above example will output: Warning: mysqli::mysqli(): (mysqlnd_ms) Exclusive usage of configuration enforced but did not find the correct INI file section (invalid_section) in Command line code on line 1 line 1 Here is a short explanation of the configuration directives that can be used. 1. master array or object List of MySQL replication master servers. The list of either of the `JSON type array' to declare an anonymous list of servers or of the `JSON type object'. Please, see above for examples. Setting at least one master server is mandatory. The plugin will issue an error of type `E_ERROR' if the user has failed to provide a master server list for a configuration section. The fatal error may read `(mysqlnd_ms) Section [master] doesn't exist for host [name_of_a_config_section] in %s on line %d'. A server is described with the `host', `port', `socket', `db', `user', `password' and `connect_flags'. It is mandatory to provide at a value for `host'. If any of the other values is not given, it will be taken from the user API connect call, please, see also: using section names example. Table of server configuration keywords. Unknown PHP API feature. Keyword Description Version `host' Database server host. This is a mandatory Since 1.1.0. setting. Failing to provide, will cause an error of type `E_RECOVERABLE_ERROR' when the plugin tries to connect to the server. The error message may read `(mysqlnd_ms) Cannot find [host] in [%s] section in config in %s on line %d'. `port' Database server TCP/IP port. Since 1.1.0. `socket'Database server Unix domain socket. Since 1.1.0. `db' Database (schemata). Since 1.1.0. `user' MySQL database user. Since 1.1.0. `password'MySQL database user password. Since 1.1.0. `connect_flags'Connection flags. Since 1.1.0. The plugin supports using only one master server. An experimental setting exists to enable multi-master support. The details are not documented. The setting is meant for development only. 2. slave array or object List of one or more MySQL replication slave servers. The syntax is identical to setting master servers, please, see `master' above for details. The plugin supports using one or more slave servers. Setting a list of slave servers is mandatory. The plugin will report an error of the type `E_ERROR' if `slave' is not given for a configuration section. The fatal error message may read `(mysqlnd_ms) Section [slave] doesn't exist for host [%s] in %s on line %d'. Note, that it is valid to use an empty slave server list. The error has been introduced to prevent accidently setting no slaves by forgetting about the `slave' setting. A master-only setup is still possible using an empty slave server list. If an empty slave list is configured and an attempt is made to execute a statement on a slave the plugin may emit a warning like `mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from.' upon statement execution. It is possible that another warning follows such as `(mysqlnd_ms) No connection selected by the last filter'. 3. global_transaction_id_injection array or object Global transaction identifier configuration related to both the use of the server built-in global transaction ID feature and the client-side emulation. Unknown PHP API feature. Keyword Description Version `fetch_last_gtid'SQL statement for accessing the latest global Since 1.2.0. transaction identifier. The SQL statement is run if the plugin needs to know the most recent global transaction identifier. This can be the case, for example, when checking MySQL Replication slave status. Also used with *Note `mysqlnd_ms_get_last_gtid': apis-php-function.mysqlnd-ms-get-last-gtid. `check_for_gtid'SQL statement for checking if a replica has Since 1.2.0. replicated all transactions up to and including ones searched for. The SQL statement is run when searching for replicas which can offer a higher level of consistency than eventual consistency. The statement must contain a placeholder `#GTID' which is to be replaced with the global transaction identifier searched for by the plugin. Please, check the *Note quickstart: apis-php-mysqlnd-ms.quickstart.gtid. for examples. `report_errors'Whether to emit an error of type warning if an Since 1.2.0. issue occurs while executing any of the configured SQL statements. `on_commit'Client-side global transaction ID emulation Since 1.2.0. only. SQL statement to run when a transaction finished to update the global transaction identifier sequence number on the master. Please, see the *Note quickstart: apis-php-mysqlnd-ms.quickstart.gtid. for examples. `wait_for_gtid_timeout'Instructs the plugin to wait up to Since 1.4.0. `wait_for_gtid_timeout' seconds for a slave to catch up when searching for slaves that can deliver session consistency. The setting limits the time spend for polling the slave status. If polling the status takes very long, the total clock time spend waiting may exceed `wait_for_gtid_timeout'. The plugin calls `sleep(1)' to sleep one second between each two polls. The setting can be used both with the plugins client-side emulation and the server-side global transaction identifier feature of MySQL 5.6. Waiting for a slave to replicate a certain GTID needed for session consistency also means throttling the client. By throttling the client the write load on the master is reduced indirectly. A primary copy based replication system, such as MySQL Replication, is given more time to reach a consistent state. This can be desired, for example, to increase the number of data copies for high availability considerations or to prevent the master from being overloaded. 4. filters object List of filters. A filter is responsible to filter the list of available servers for executing a given statement. Filters can be chained. The `random' and `roundrobin' filter replace the `pick[]' directive used in prior version to select a load balancing policy. The `user' filter replaces the *Note `mysqlnd_ms_set_user_pick_server': apis-php-function.mysqlnd-ms-set-user-pick-server. function. Filters may accept parameters to refine their actions. If no load balancing policy is set, the plugin will default to `random_once'. The `random_once' policy picks a random slave server when running the first read-only statement. The slave server will be used for all read-only statements until the PHP script execution ends. No load balancing policy is set and thus, defaulting takes place, if neither the `random' nor the `roundrobin' are part of a configuration section. If a filter chain is configured so that a filter which output no more than once server is used as input for a filter which should be given more than one server as input, the plugin may emit a warning upon opening a connection. The warning may read: `(mysqlnd_ms) Error while creating filter '%s' . Non-multi filter '%s' already created. Stopping in %s on line %d'. Furthermore, an error of the error code `2000', the sql state `HY000' and an error message similar to the warning may be set on the connection handle. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "filters": [ "roundrobin", "random" ] } } query("SELECT 1 FROM DUAL"); ?> The above example will output: PHP Warning: mysqli::mysqli(): (HY000/2000): (mysqlnd_ms) Error while creating filter 'random' . Non-multi filter 'roundrobin' already created. Stopping in filter_warning.php on line 1 [2000] (mysqlnd_ms) Error while creating filter 'random' . Non-multi filter 'roundrobin' already created. Stopping PHP Warning: mysqli::query(): Couldn't fetch mysqli in filter_warning.php on line 3 5. Filter: random object The `random' filter features the random and random once load balancing policies, set through the `pick[]' directive in older versions. The random policy will pick a random server whenever a read-only statement is to be executed. The random once strategy picks a random slave server once and continues using the slave for the rest of the PHP web request. Random once is a default, if load balancing is not configured through a filter. If the `random' filter is not given any arguments, it stands for random load balancing policy. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" }, "slave_1": { "host": "192.168.78.137", "port": "3306" } }, "filters": [ "random" ] } } Optionally, the `sticky' argument can be passed to the filter. If the parameter `sticky' is set to the string `1', the filter follows the random once load balancing strategy. { "filters": { "random": { "sticky": "1" } } } Both the `random' and `roundrobin' filters support setting a priority, a weight for a server, since PECL/mysqlnd_ms 1.4.0. If the `weight' argument is passed to the filter, it must assign a weight for all servers. Servers must be given an alias name in the `slave' respectively `master' server lists. The alias must be used to reference servers for assigning a priority with `weight'. [E_RECOVERABLE_ERROR] mysqli_real_connect(): (mysqlnd_ms) Unknown server 'slave3' in 'random' filter configuration. Stopping in %s on line %d Using a wrong alias name with `weight' may result in an error similar to the shown above. If `weight' is omitted, the default weight of all servers is one. { "myapp": { "master": { "master1":{ "host":"localhost", "socket":"\/var\/run\/mysql\/mysql.sock" } }, "slave": { "slave1": { "host":"192.168.2.28", "port":3306 }, "slave2": { "host":"192.168.2.29", "port":3306 }, "slave3": { "host":"192.0.43.10", "port":3306 }, }, "filters": { "random": { "weights": { "slave1":8, "slave2":4, "slave3":1, "master1":1 } } } } } At the average a server assigned a weight of two will be selected twice as often as a server assigned a weight of one. Different weights can be assigned to reflect differently sized machines, to prefer co-located slaves which have a low network latency or, to configure a standby failover server. In the latter case, you may want to assign the standby server a very low weight in relation to the other servers. For example, given the configuration above `slave3' will get only some eight percent of the requests in the average. As long as `slave1' and `slave2' are running, it will be used sparsely, similar to a standby failover server. Upon failure of `slave1' and `slave2', the usage of `slave3' increases. Please, check the notes on failover before using `weight' this way. Valid weight values range from 1 to 65535. Unknown arguments are ignored by the filter. No warning or error is given. The filter expects one or more servers as input. Outputs one server. A filter sequence such as `random', `roundrobin' may cause a warning and an error message to be set on the connection handle when executing a statement. List of filter arguments. Unknown PHP API feature. Keyword Description Version `sticky'Enables or disabled random once load balancing Since 1.2.0. policy. See above. `weight'Assigns a load balancing weight/priority to a Since 1.4.0. server. Please, see above for a description. 6. Filter: roundrobin object If using the `roundrobin' filter, the plugin iterates over the list of configured slave servers to pick a server for statement execution. If the plugin reaches the end of the list, it wraps around to the beginning of the list and picks the first configured slave server. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "filters": [ "roundrobin" ] } } Expects one or more servers as input. Outputs one server. A filter sequence such as `roundrobin', `random' may cause a warning and an error message to be set on the connection handle when executing a statement. List of filter arguments. Unknown PHP API feature. Keyword Description Version `weight'Assigns a load balancing weight/priority to a Since 1.4.0. server. Please, find a description above. 7. Filter: user object The `user' replaces *Note `mysqlnd_ms_set_user_pick_server': apis-php-function.mysqlnd-ms-set-user-pick-server. function, which was removed in 1.1.0-beta. The filter sets a callback for user-defined read/write splitting and server selection. The plugins built-in read/write query split mechanism decisions can be overwritten in two ways. The easiest way is to prepend a query string with the SQL hints MYSQLND_MS_MASTER_SWITCH , MYSQLND_MS_SLAVE_SWITCH or MYSQLND_MS_LAST_USED_SWITCH . Using SQL hints one can control, for example, whether a query shall be send to the MySQL replication master server or one of the slave servers. By help of SQL hints it is not possible to pick a certain slave server for query execution. Full control on server selection can be gained using a callback function. Use of a callback is recommended to expert users only because the callback has to cover all cases otherwise handled by the plugin. The plugin will invoke the callback function for selecting a server from the lists of configured master and slave servers. The callback function inspects the query to run and picks a server for query execution by returning the hosts URI, as found in the master and slave list. If the lazy connections are enabled and the callback chooses a slave server for which no connection has been established so far and establishing the connection to the slave fails, the plugin will return an error upon the next action on the failed connection, for example, when running a query. It is the responsibility of the application developer to handle the error. For example, the application can re-run the query to trigger a new server selection and callback invocation. If so, the callback must make sure to select a different slave, or check slave availability, before returning to the plugin to prevent an endless loop. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "filters": { "user": { "callback": "pick_server" } } } } The callback is supposed to return a host to run the query on. The host URI is to be taken from the master and slave connection lists passed to the callback function. If callback returns a value neither found in the master nor in the slave connection lists the plugin will emit an error of the type `E_RECOVERABLE_ERROR' The error may read like ` (mysqlnd_ms) User filter callback has returned an unknown server. The server 'server that is not in master or slave list' can neither be found in the master list nor in the slave list'. If the application catches the error to ignore it, follow up errors may be set on the connection handle, for example, `(mysqlnd_ms) No connection selected by the last filter' with the error code `2000' and the sqlstate `HY000'. Furthermore a warning may be emitted. Referencing a non-existing function as a callback will result in any error of the type `E_RECOVERABLE_ERROR' whenever the plugin tries to callback function. The error message may reads like: `(mysqlnd_ms) Specified callback (pick_server) is not a valid callback'. If the application catches the error to ignore it, follow up errors may be set on the connection handle, for example, `(mysqlnd_ms) Specified callback (pick_server) is not a valid callback' with the error code `2000' and the sqlstate `HY000'. Furthermore a warning may be emitted. The following parameters are passed from the plugin to the callback. Unknown PHP API feature. ParameterDescription Version `connected_host'URI of the currently connected database server. Since 1.1.0. `query' Query string of the statement for which a Since 1.1.0. server needs to be picked. `masters'List of master servers to choose from. Note, Since 1.1.0. that the list of master servers may not be identical to the list of configured master servers if the filter is not the first in the filter chain. Previously run filters may have reduced the master list already. `slaves'List of slave servers to choose from. Note, Since 1.1.0. that the list of master servers may not be identical to the list of configured master servers if the filter is not the first in the filter chain. Previously run filters may have reduced the master list already. `last_used_connection'URI of the server of the connection used to Since 1.1.0. execute the previous statement on. `in_transaction'Boolean flag indicating whether the statement Since 1.1.0. is part of an open transaction. If autocommit mode is turned off, this will be set to TRUE . Otherwise it is set to FALSE . Transaction detection is based on monitoring the mysqlnd library call `set_autocommit'. Monitoring is not possible before PHP 5.4.0. Please, see *Note connection pooling and switching: apis-php-mysqlnd-ms.pooling. concepts discussion for further details. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.2.27", "port": "3306" }, "slave_1": { "host": "192.168.78.136", "port": "3306" } }, "filters": { "user": { "callback": "pick_server" } } } } query("SELECT 1 FROM DUAL"))) printf("[%d] %s\n", $mysqli->errno, $mysqli->error); else $res->close(); if (!($res = $mysqli->query("SELECT 2 FROM DUAL"))) printf("[%d] %s\n", $mysqli->errno, $mysqli->error); else $res->close(); if (!($res = $mysqli->query("SELECT * FROM table_on_slave_a_only"))) printf("[%d] %s\n", $mysqli->errno, $mysqli->error); else $res->close(); $mysqli->close(); ?> The above example will output: User has connected to 'myapp'... ... deciding where to run 'SELECT 1 FROM DUAL' ... some read-only query for a slave ... ret = 'tcp://192.168.2.27:3306' User has connected to 'myapp'... ... deciding where to run 'SELECT 2 FROM DUAL' ... some read-only query for a slave ... ret = 'tcp://192.168.78.136:3306' User has connected to 'myapp'... ... deciding where to run 'SELECT * FROM table_on_slave_a_only' ... access to table available only on slave A detected ... ret = 'tcp://192.168.2.27:3306' 8. Filter: user_multi object The `user_multi' differs from the `user' only in one aspect. Otherwise, their syntax is identical. The `user' filter must pick and return exactly one node for statement execution. A filter chain usually ends with a filter that emits only one node. The filter chain shall reduce the list of candidates for statement execution down to one. This, only one node left, is the case after the `user' filter has been run. The `user_multi' filter is a multi filter. It returns a list of slave and a list of master servers. This list needs further filtering to identify exactly one node for statement execution. A multi filter is typically placed at the top of the filter chain. The `quality_of_service' filter is another example of a multi filter. The return value of the callback set for `user_multi' must be an an array with two elements. The first element holds a list of selected master servers. The second element contains a list of selected slave servers. The lists shall contain the keys of the slave and master servers as found in the slave and master lists passed to the callback. The below example returns random master and slave lists extracted from the functions input. $value) { if (mt_rand(0, 2) > 1) $picked_masters[] = $key; } $picked_slaves = array() foreach ($slaves as $key => $value) { if (mt_rand(0, 2) > 1) $picked_slaves[] = $key; } return array($picked_masters, $picked_slaves); } ?> The plugin will issue an error of type `E_RECOVERABLE' if the callback fails to return a server list. The error may read `(mysqlnd_ms) User multi filter callback has not returned a list of servers to use. The callback must return an array in %s on line %d'. In case the server list is not empty but has invalid servers key/ids in it, an error of type `E_RECOVERABLE' will the thrown with an error message like `(mysqlnd_ms) User multi filter callback has returned an invalid list of servers to use. Server id is negative in %s on line %d', or similar. Whether an error is emitted in case of an empty slave or master list depends on the configuration. If an empty master list is returned for a write operation, it is likely that the plugin will emit a warning that may read `(mysqlnd_ms) Couldn't find the appropriate master connection. 0 masters to choose from. Something is wrong in %s on line %d'. Typically a follow up error of type `E_ERROR' will happen. In case of a read operation and an empty slave list the behavior depends on the fail over configuration. If fail over to master is enabled, no error should appear. If fail over to master is deactivated the plugin will emit a warning that may read `(mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from. Something is wrong in %s on line %d'. 9. Filter: node_groups object The `node_groups' filter lets you group cluster nodes and query selected groups, for example, to support data partitioning. Data partitioning can be required for manual sharding, primary copy based clusters running multiple masters, or to avoid hot spots in update everywhere clusters that have no built-in partitioning. The filter is a multi filter which returns zero, one or multiple of its input servers. Thus, it must be followed by other filters to reduce the number of candidates down to one for statement execution. Unknown PHP API feature. Keyword Description Version `user One or more node groups must be defined. A Since 1.5.0. defined node group can have an arbitrary user defined node name. The name is used in combination with a group SQL hint to restrict query execution to the name' nodes listed for the node group. To run a query on any of the servers of a node group, the query must begin with the SQL hint `/*user defined node group name*/'. Please note, no white space is allowed around `user defined node group name'. Because `user defined node group name' is used as-is as part of a SQL hint, you should choose the name that is compliant with the SQL language. Each node group entry must contain a list of `master' servers. Additional `slave' servers are allowed. Failing to provide a list of `master' for a node group `name_of_group' may cause an error of type E_RECOVERABLE_ERROR like `(mysqlnd_ms) No masters configured in node group 'name_of_group' for 'node_groups' filter'. The list of master and slave servers must reference corresponding entries in the global master respectively slave server list. Referencing an unknown server in either of the both server lists may cause an E_RECOVERABLE_ERROR error like `(mysqlnd_ms) Unknown master 'server_alias_name' (section 'name_of_group') in 'node_groups' filter configuration'. { "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "192.168.2.28", "port": 3306 }, "slave_1": { "host": "127.0.0.1", "port": 3311 } }, "filters": { "node_groups": { "Partition_A" : { "master": ["master_0"], "slave": ["slave_0"] } }, "roundrobin": [] } } } Please note, if a filter chain generates an empty slave list and the PHP configuration directive `mysqlnd_ms.multi_master=0' is used, the plugin may emit a warning. 10. Filter: quality_of_service object The `quality_of_service' identifies cluster nodes capable of delivering a certain quality of service. It is a multi filter which returns zero, one or multiple of its input servers. Thus, it must be followed by other filters to reduce the number of candidates down to one for statement execution. The `quality_of_service' filter has been introduced in 1.2.0-alpha. In the 1.2 series the filters focus is on the consistency aspect of service quality. Different types of clusters offer different default data consistencies. For example, an asynchronous MySQL replication slave offers eventual consistency. The slave may not be able to deliver requested data because it has not replicated the write, it may serve stale database because its lagging behind or it may serve current information. Often, this is acceptable. In some cases higher consistency levels are needed for the application to work correct. In those cases, the `quality_of_service' can filter out cluster nodes which cannot deliver the necessary quality of service. The `quality_of_service' filter can be replaced or created at runtime. A successful call to *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. removes all existing `qos' filter entries from the filter list and installs a new one at the very beginning. All settings that can be made through *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. can also be in the plugins configuration file. However, use of the function is by far the most common use case. Instead of setting session consistency and strong consistency service levels in the plugins configuration file it is recommended to define only masters and no slaves. Both service levels will force the use of masters only. Using an empty slave list shortens the configuration file, thus improving readability. The only service level for which there is a case of defining in the plugins configuration file is the combination of eventual consistency and maximum slave lag. Unknown PHP API feature. Keyword Description Version `eventual_consistency'Request eventual consistency. Allows the use Since 1.2.0. of all master and slave servers. Data returned may or may not be current. Eventual consistency accepts an optional `age' parameter. If `age' is given the plugin considers only slaves for reading for which MySQL replication reports a slave lag less or equal to `age'. The replication lag is measure using `SHOW SLAVE STATUS'. If the plugin fails to fetch the replication lag, the slave tested is skipped. Implementation details and tips are given in the *Note quality of service concepts section: apis-php-mysqlnd-ms.qos-consistency. Please note, if a filter chain generates an empty slave list and the PHP configuration directive `mysqlnd_ms.multi_master=0' is used, the plugin may emit a warning. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.2.27", "port": "3306" }, "slave_1": { "host": "192.168.78.136", "port": "3306" } }, "filters": { "quality_of_service": { "eventual_consistency": { "age":123 } } } } } `session_consistency'Request session consistency (read your Since 1.1.0. writes). Allows use of all masters and all slaves which are in sync with the master. If no further parameters are given slaves are filtered out as there is no reliable way to test if a slave has caught up to the master or is lagging behind. Please note, if a filter chain generates an empty slave list and the PHP configuration directive `mysqlnd_ms.multi_master=0' is used, the plugin may emit a warning. Session consistency temporarily requested using *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. is a valuable alternative to using `master_on_write'. `master_on_write' is likely to send more statements to the master than needed. The application may be able to continue operation at a lower consistency level after it has done some critical reads. `strong_consistency'Request strong consistency. Only masters will Since 1.2.0. be used. 11. failover Up to and including 1.3.x: string. Since 1.4.0: object. Failover policy. Supported policies: `disabled' (default), `master', `loop_before_master' (Since 1.4.0). If no failover policy is set, the plugin will not do any automatic failover (`failover=disabled'). Whenever the plugin fails to connect a server it will emit a warning and set the connections error code and message. Thereafter it is up to the application to handle the error and, for example, resent the last statement to trigger the selection of another server. Please note, the automatic failover logic is applied when opening connections only. Once a connection has been opened no automatic attempts are made to reopen it in case of an error. If, for example, the server a connection is connected to is shut down and the user attempts to run a statement on the connection, no automatic failover will be tried. Instead, an error will be reported. If using `failover=master' the plugin will implicitly failover to a master, if available. Please check the concepts documentation to learn about potential pitfalls and risks of using `failover=master'. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "failover": "master" } } Since PECL/mysqlnd_ms 1.4.0 the failover configuration keyword refers to an object. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "failover": {"strategy": "master" } } } Unknown PHP API feature. Keyword Description Version `strategy'Failover policy. Possible values: `disabled' Since 1.4.0. (default), `master', `loop_before_master' A value of `disabled' disables automatic failover. Setting `master' instructs the plugin to try to connect to a master in case of a slave connection error. If the master connection attempt fails, the plugin exists the failover loop and returns an error to the user. If using `loop_before_master' and a slave request is made, the plugin tries to connect to other slaves before failing over to a master. If multiple master are given and multi master is enabled, the plugin also loops over the list of masters and attempts to connect before returning an error to the user. `remember_failed'Remember failures for the duration of a web Since 1.4.0. request. Default: `false'. The feature is only If set to `true' the plugin will remember available failed hosts and skip the hosts in all future together load balancing made for the duration of the with the current web request. `random' and `roundrobin' load balancing filter. Use of the setting is recommended. `max_retries'Maximum number of connection attempts before Since 1.4.0. skipping host. Default: `0' (no limit). The feature is only The setting is used to prevent hosts from available being dropped of the host list upon the first together failure. If set to `n > 0', the plugin will with the keep the node in the node list even after a `random' and failed connection attempt. The node will not `roundrobin' be removed immediately from the slave load respectively master lists after the first balancing connection failure but instead be tried to filter. connect to up to `n' times in future load balancing rounds before being removed. Setting `failover' to any other value but `disabled', `master' or `loop_before_master' will not emit any warning or error. 12. lazy_connections bool Controls the use of lazy connections. Lazy connections are connections which are not opened before the client sends the first connection. Lazy connections are a default. It is strongly recommended to use lazy connections. Lazy connections help to keep the number of open connections low. If you disable lazy connections and, for example, configure one MySQL replication master server and two MySQL replication slaves, the plugin will open three connections upon the first call to a connect function although the application might use the master connection only. Lazy connections bare a risk if you make heavy use of actions which change the state of a connection. The plugin does not dispatch all state changing actions to all connections from the connection pool. The few dispatched actions are applied to already opened connections only. Lazy connections opened in the future are not affected. Only some settings are "remembered" and applied when lazy connections are opened. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "lazy_connections": 0 } } Please, see also `server_charset' to overcome potential problems with string escaping and servers using different default charsets. 13. server_charset string The setting has been introduced in 1.4.0. It is recommended to set it if using lazy connections. The `server_charset' setting serves two purposes. It acts as a fallback charset to be used for string escaping done before a connection has been established and it helps to avoid escaping pitfalls in heterogeneous environments which servers using different default charsets. String escaping takes a connections charset into account. String escaping is not possible before a connection has been opened and the connections charset is known. The use of lazy connections delays the actual opening of connections until a statement is send. An application using lazy connections may attempt to escape a string before sending a statement. In fact, this should be a common case as the statement string may contain the string that is to be escaped. However, due to the lazy connection feature no connection has been opened yet and escaping fails. The plugin may report an error of the type `E_WARNING' and a message like `(mysqlnd_ms) string escaping doesn't work without established connection. Possible solution is to add server_charset to your configuration' to inform you of the pitfall. Setting `server_charset' makes the plugin use the given charset for string escaping done on lazy connection handles before establishing a network connection to MySQL. Furthermore, the plugin will enforce the use of the charset when the connection is established. Enforcing the use of the configured charset used for escaping is done to prevent tapping into the pitfall of using a different charset for escaping than used later for the connection. This has the additional benefit of removing the need to align the charset configuration of all servers used. No matter what the default charset on any of the servers is, the plugin will set the configured one as a default. The plugin does not stop the user from changing the charset at any time using the `set_charset' (http://www.php.net/set_charset) call or corresponding SQL statements. Please, note that the use of SQL is not recommended as it cannot be monitored by the plugin. The user can, for example, change the charset on a lazy connection handle after escaping a string and before the actual connection is opened. The charset set by the user will be used for any subsequent escaping before the connection is established. The connection will be established using the configured charset, no matter what the server charset is or what the user has set before. Once a connection has been opened, `set_charset' is of no meaning anymore. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "lazy_connections": 1, "server_charset" : "utf8" } } real_escape("this will be escaped using the server_charset setting - utf8"); $mysqli->set_charset("latin1"); $mysqli->real_escape("this will be escaped using latin1"); /* server_charset implicitly set - utf8 connection */ $mysqli->query("SELECT 'This connection will be set to server_charset upon establishing' AS _msg FROM DUAL"); /* latin1 used from now on */ $mysqli->set_charset("latin1"); ?> 14. master_on_write bool If set, the plugin will use the master server only after the first statement has been executed on the master. Applications can still send statements to the slaves using SQL hints to overrule the automatic decision. The setting may help with replication lag. If an application runs an `INSERT' the plugin will, by default, use the master to execute all following statements, including `SELECT' statements. This helps to avoid problems with reads from slaves which have not replicated the `INSERT' yet. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "master_on_write": 1 } } Please, note the `quality_of_service' filter introduced in version 1.2.0-alpha. It gives finer control, for example, for achieving read-your-writes and, it offers additional functionality introducing *Note service levels: apis-php-mysqlnd-ms.qos-consistency. All transaction stickiness settings, including `trx_stickiness=on', are overruled by `master_on_write=1'. 15. trx_stickiness string Transaction stickiness policy. Supported policies: `disabled' (default), `master'. The setting requires 5.4.0 or newer. If used with PHP older than 5.4.0, the plugin will emit a warning like `(mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99'. If no transaction stickiness policy is set or, if setting `trx_stickiness=disabled', the plugin is not transaction aware. Thus, the plugin may load balance connections and switch connections in the middle of a transaction. The plugin is not transaction safe. SQL hints must be used avoid connection switches during a transaction. As of PHP 5.4.0 the mysqlnd library allows the plugin to monitor the `autocommit' mode set by calls to the libraries `set_autocommit()' function. If setting `set_stickiness=master' and `autocommit' gets disabled by a PHP MySQL extension invoking the `mysqlnd' library internal function call `set_autocommit()', the plugin is made aware of the begin of a transaction. Then, the plugin stops load balancing and directs all statements to the master server until `autocommit' is enabled. Thus, no SQL hints are required. An example of a PHP MySQL API function calling the `mysqlnd' library internal function call `set_autocommit()' is `mysqli_autocommit'. Although setting `trx_stickiness=master', the plugin cannot be made aware of `autocommit' mode changes caused by SQL statements such as `SET AUTOCOMMIT=0' or `BEGIN'. As of PHP 5.5.0, the mysqlnd library features additional C API calls to control transactions. The level of control matches the one offered by SQL statements. The `mysqli' API has been modified to use these calls. Since version 1.5.0, PECL/mysqlnd_ms can monitor not only `mysqli_autocommit', but also `mysqli_begin' (http://www.php.net/mysqli_begin), `mysqli_commit' and `mysqli_rollback' to detect transaction boundaries and stop load balancing for the duration of a transaction. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "trx_stickiness": "master" } } Since version 1.5.0 automatic and silent failover is disabled for the duration of a transaction. If the boundaries of a transaction have been properly detected, transaction stickiness is enabled and a server fails, the plugin will not attempt to fail over to the next server, if any, regardless of the failover policy configured. The user must handle the error manually. Depending on the configuration, the plugin may emit an error of type `E_WARNING' reading like `(mysqlnd_ms) Automatic failover is not permitted in the middle of a transaction'. This error may then be overwritten by follow up errors such as `(mysqlnd_ms) No connection selected by the last filter'. Those errors will be generated by the failing query function. autocommit(false); /* assumption: server fails */ if (!($res = $mysqli->query("SELECT 'Assume this query fails' AS _msg FROM DUAL"))) { /* handle failure of transaction, plugin internal state is still in_trx = 1 */ printf("[%d] %s", $mysqli->errno, $mysqli->error); /* If using autocommit() based transaction detection it is a MUST to call autocommit(true). Otherwise the plugin assumes the current transaction continues and connection changes remain forbidden. */ $mysqli->autocommit(true); /* Likewise, you'll want to start a new transaction */ $mysqli->autocommit(false); } /* latin1 used from now on */ $mysqli->set_charset("latin1"); ?> If a server fails in the middle of a transaction the plugin continues to refuse to switch connections until the current transaction has been finished. Recall that the plugin monitors API calls to detect transaction boundaries. Thus, you have to, for example, enable auto commit mode to end the current transaction before the plugin continues load balancing and switches the server. Likewise, you will want to start a new transaction immediately thereafter and disable auto commit mode again. Not handling failed queries and not ending a failed transaction using API calls may cause all following commands emit errors such as `Commands out of sync; you can't run this command now'. Thus, it is important to handle all errors. 16. transient_error object The setting has been introduced in 1.6.0. A database cluster node may reply a transient error to a client. The client can then repeat the operation on the same node, fail over to a different node or abort the operation. Per definition is it safe for a client to retry the same operation on the same node before giving up. `PECL/mysqlnd_ms' can perform the retry loop on behalf of the application. By configuring `transient_error' the plugin can be instructed to repeat operations failing with a certain error code for a certain maximum number of times with a pause between the retries. If the transient error disappears during loop execution, it is hidden from the application. Otherwise, the error is forwarded to the application by the end of the loop. { "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "transient_error": { "mysql_error_codes": [ 1297 ], "max_retries": 2, "usleep_retry": 100 } } } Unknown PHP API feature. Keyword Description Version `mysql_error_codes'List of transient error codes. You may add any Since 1.6.0. MySQL error code to the list. It is possible to consider any error as transient not only `1297' (`HY000 (ER_GET_TEMPORARY_ERRMSG), Message: Got temporary error %d '%s' from %s'). Before adding other codes but `1297' to the list, make sure your cluster supports a new attempt without impacting the state of your application. `max_retries'How often to retry an operation which fails Since 1.6.0. with a transient error before forwarding the failure to the user. Default: `1' `usleep_retry'Milliseconds to sleep between transient error Since 1.6.0. retries. The value is passed to the C function `usleep' (http://www.php.net/usleep), hence the name. Default: `100'  File: manual.info, Node: apis-php-mysqlnd-ms.plugin-ini-v1, Next: apis-php-mysqlnd-ms.testing, Prev: apis-php-mysqlnd-ms.plugin-ini-json, Up: apis-php-mysqlnd-ms.setup 21.9.2.34 Plugin configuration file (<= 1.0.x) .............................................. Copyright 1997-2012 the PHP Documentation Group. *Note*: The below description applies to PECL/mysqlnd_ms < 1.1.0-beta. It is not valid for later versions. The plugin is using its own configuration file. The configuration file holds information on the MySQL replication master server, the MySQL replication slave servers, the server pick (load balancing) policy, the failover strategy and the use of lazy connections. The PHP configuration directive `mysqlnd_ms.ini_file' is used to set the plugins configuration file. The configuration file mimics standard the `php.ini' format. It consists of one or more sections. Every section defines its own unit of settings. There is no global section for setting defaults. Applications reference sections by their name. Applications use section names as the host (server) parameter to the various connect methods of the mysqli, mysql and See section "apis-php-ref.pdo-mysql" in the online manual extensions. Upon connect the See section "apis-php-mysqli" in the online manual plugin compares the hostname with all section names from the plugin configuration file. If hostname and section name match, the plugin will load the sections settings. [myapp] master[] = localhost slave[] = 192.168.2.27 slave[] = 192.168.2.28:3306 [localhost] master[] = localhost:/tmp/mysql/mysql.sock slave[] = 192.168.3.24:3305 slave[] = 192.168.3.65:3309 Section names are strings. It is valid to use a section name such as `192.168.2.1', `127.0.0.1' or `localhost'. If, for example, an application connects to `localhost' and a plugin configuration section `[localhost]' exists, the semantics of the connect operation are changed. The application will no longer only use the MySQL server running on the host `localhost' but the plugin will start to load balance MySQL queries following the rules from the `[localhost]' configuration section. This way you can load balance queries from an application without changing the applications source code. The `master[]', `slave[]' and `pick[]' configuration directives use a list-like syntax. Configuration directives supporting list-like syntax may appear multiple times in a configuration section. The plugin maintains the order in which entries appear when interpreting them. For example, the below example shows two `slave[]' configuration directives in the configuration section `[myapp]'. If doing round-robin load balancing for read-only queries, the plugin will send the first read-only query to the MySQL server `mysql_slave_1' because it is the first in the list. The second read-only query will be send to the MySQL server `mysql_slave_2' because it is the second in the list. Configuration directives supporting list-like syntax result are ordered from top to bottom in accordance to their appearance within a configuration section. [myapp] master[] = mysql_master_server slave[] = mysql_slave_1 slave[] = mysql_slave_2 Here is a short explanation of the configuration directives that can be used. 1. master[] string URI of a MySQL replication master server. The URI follows the syntax `hostname[:port|unix_domain_socket]'. The plugin supports using only one master server. Setting a master server is mandatory. The plugin will report a warning upon connect if the user has failed to provide a master server for a configuration section. The warning may read `(mysqlnd_ms) Cannot find master section in config'. Furthermore the plugin may set an error code for the connection handle such as `HY000/2000 (CR_UNKNOWN_ERROR)'. The corresponding error message depends on your language settings. 2. slave[] string URI of one or more MySQL replication slave servers. The URI follows the syntax `hostname[:port|unix_domain_socket]'. The plugin supports using one or more slave servers. Setting a slave server is mandatory. The plugin will report a warning upon connect if the user has failed to provide at least one slave server for a configuration section. The warning may read `(mysqlnd_ms) Cannot find slaves section in config'. Furthermore the plugin may set an error code for the connection handle such as `HY000/2000 (CR_UNKNOWN_ERROR)'. The corresponding error message depends on your language settings. 3. pick[] string Load balancing (server picking) policy. Supported policies: `random', `random_once' (default), `roundrobin', `user'. If no load balancing policy is set, the plugin will default to `random_once'. The `random_once' policy picks a random slave server when running the first read-only statement. The slave server will be used for all read-only statements until the PHP script execution ends. The `random' policy will pick a random server whenever a read-only statement is to be executed. If using `roundrobin' the plugin iterates over the list of configured slave servers to pick a server for statement execution. If the plugin reaches the end of the list, it wraps around to the beginning of the list and picks the first configured slave server. Setting more than one load balancing policy for a configuration section makes only sense in conjunction with `user' and *Note `mysqlnd_ms_set_user_pick_server': apis-php-function.mysqlnd-ms-set-user-pick-server. If the user defined callback fails to pick a server, the plugin falls back to the second configured load balancing policy. 4. failover string Failover policy. Supported policies: `disabled' (default), `master'. If no failover policy is set, the plugin will not do any automatic failover (`failover=disabled'). Whenever the plugin fails to connect a server it will emit a warning and set the connections error code and message. Thereafter it is up to the application to handle the error and, for example, resent the last statement to trigger the selection of another server. If using `failover=master' the plugin will implicitly failover to a slave, if available. Please check the concepts documentation to learn about potential pitfalls and risks of using `failover=master'. 5. lazy_connections bool Controls the use of lazy connections. Lazy connections are connections which are not opened before the client sends the first connection. It is strongly recommended to use lazy connections. Lazy connections help to keep the number of open connections low. If you disable lazy connections and, for example, configure one MySQL replication master server and two MySQL replication slaves, the plugin will open three connections upon the first call to a connect function although the application might use the master connection only. Lazy connections bare a risk if you make heavy use of actions which change the state of a connection. The plugin does not dispatch all state changing actions to all connections from the connection pool. The few dispatched actions are applied to already opened connections only. Lazy connections opened in the future are not affected. If, for example, the connection character set is changed using a PHP MySQL API call, the plugin will change the character set of all currently opened connection. It will not remember the character set change to apply it on lazy connections opened in the future. As a result the internal connection pool would hold connections using different character sets. This is not desired. Remember that character sets are taken into account for escaping. 6. master_on_write bool If set, the plugin will use the master server only after the first statement has been executed on the master. Applications can still send statements to the slaves using SQL hints to overrule the automatic decision. The setting may help with replication lag. If an application runs an `INSERT' the plugin will, by default, use the master to execute all following statements, including `SELECT' statements. This helps to avoid problems with reads from slaves which have not replicated the `INSERT' yet. 7. trx_stickiness string Transaction stickiness policy. Supported policies: `disabled' (default), `master'. Experimental feature. The setting requires 5.4.0 or newer. If used with PHP older than 5.4.0, the plugin will emit a warning like `(mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99'. If no transaction stickiness policy is set or, if setting `trx_stickiness=disabled', the plugin is not transaction aware. Thus, the plugin may load balance connections and switch connections in the middle of a transaction. The plugin is not transaction safe. SQL hints must be used avoid connection switches during a transaction. As of PHP 5.4.0 the mysqlnd library allows the plugin to monitor the `autocommit' mode set by calls to the libraries `trx_autocommit()' function. If setting `trx_stickiness=master' and `autocommit' gets disabled by a PHP MySQL extension invoking the `mysqlnd' library internal function call `trx_autocommit()', the plugin is made aware of the begin of a transaction. Then, the plugin stops load balancing and directs all statements to the master server until `autocommit' is enabled. Thus, no SQL hints are required. An example of a PHP MySQL API function calling the `mysqlnd' library internal function call `trx_autocommit()' is `mysqli_autocommit'. Although setting `trx_stickiness=master', the plugin cannot be made aware of `autocommit' mode changes caused by SQL statements such as `SET AUTOCOMMIT=0'.  File: manual.info, Node: apis-php-mysqlnd-ms.testing, Next: apis-php-mysqlnd-ms.debugging, Prev: apis-php-mysqlnd-ms.plugin-ini-v1, Up: apis-php-mysqlnd-ms.setup 21.9.2.35 Testing ................. Copyright 1997-2012 the PHP Documentation Group. *Note*: The section applies to mysqlnd_ms 1.1.0 or newer, not the 1.0 series. The PECL/mysqlnd_ms test suite is in the `tests/' directory of the source distribution. The test suite consists of standard phpt tests, which are described on the PHP Quality Assurance Teams website. Running the tests requires setting up one to four MySQL servers. Some tests don't connect to MySQL at all. Others require one server for testing. Some require two distinct servers. In some cases two servers are used to emulate a replication setup. In other cases a master and a slave of an existing MySQL replication setup are required for testing. The tests will try to detect how many servers and what kind of servers are given. If the required servers are not found, the test will be skipped automatically. Before running the tests, edit `tests/config.inc' to configure the MySQL servers to be used for testing. The most basic configuration is as follows. putenv("MYSQL_TEST_HOST=localhost"); putenv("MYSQL_TEST_PORT=3306"); putenv("MYSQL_TEST_USER=root"); putenv("MYSQL_TEST_PASSWD="); putenv("MYSQL_TEST_DB=test"); putenv("MYSQL_TEST_ENGINE=MyISAM"); putenv("MYSQL_TEST_SOCKET="); putenv("MYSQL_TEST_SKIP_CONNECT_FAILURE=1"); putenv("MYSQL_TEST_CONNECT_FLAGS=0"); putenv("MYSQL_TEST_EXPERIMENTAL=0"); /* replication cluster emulation */ putenv("MYSQL_TEST_EMULATED_MASTER_HOST=". getenv("MYSQL_TEST_HOST")); putenv("MYSQL_TEST_EMULATED_SLAVE_HOST=". getenv("MYSQL_TEST_HOST")); /* real replication cluster */ putenv("MYSQL_TEST_MASTER_HOST=". getenv("MYSQL_TEST_EMULATED_MASTER_HOST")); putenv("MYSQL_TEST_SLAVE_HOST=". getenv("MYSQL_TEST_EMULATED_SLAVE_HOST")); `MYSQL_TEST_HOST', `MYSQL_TEST_PORT' and `MYSQL_TEST_SOCKET' define the hostname, TCP/IP port and Unix domain socket of the default database server. `MYSQL_TEST_USER' and `MYSQL_TEST_PASSWD' contain the user and password needed to connect to the database/schema configured with `MYSQL_TEST_DB'. All configured servers must have the same database user configured to give access to the test database. Using `host', `host:port' or `host:/path/to/socket' syntax one can set an alternate host, host and port or host and socket for any of the servers. putenv("MYSQL_TEST_SLAVE_HOST=192.168.78.136:3307")); putenv("MYSQL_TEST_MASTER_HOST=myserver_hostname:/path/to/socket"));  File: manual.info, Node: apis-php-mysqlnd-ms.debugging, Next: apis-php-mysqlnd-ms.monitoring, Prev: apis-php-mysqlnd-ms.testing, Up: apis-php-mysqlnd-ms.setup 21.9.2.36 Debugging and Tracing ............................... Copyright 1997-2012 the PHP Documentation Group. The mysqlnd debug log can be used to debug and trace the actitivities of PECL/mysqlnd_ms. As a mysqlnd PECL/mysqlnd_ms adds trace information to the mysqlnd library debug file. Please, see the `mysqlnd.debug' PHP configuration directive documentation for a detailed description on how to configure the debug log. Configuration setting example to activate the debug log: mysqlnd.debug=d:t:x:O,/tmp/mysqlnd.trace *Note*: This feature is only available with a debug build of PHP. Works on Microsoft Windows if using a debug build of PHP and PHP was built using Microsoft Visual C version 9 and above. The debug log shows mysqlnd library and PECL/mysqlnd_ms plugin function calls, similar to a trace log. Mysqlnd library calls are usually prefixed with `mysqlnd_'. PECL/mysqlnd internal calls begin with `mysqlnd_ms'. Example excerpt from the debug log (connect): [...] >mysqlnd_connect | info : host=myapp user=root db=test port=3306 flags=131072 | >mysqlnd_ms::connect | | >mysqlnd_ms_config_json_section_exists | | | info : section=[myapp] len=[5] | | | >mysqlnd_ms_config_json_sub_section_exists | | | | info : section=[myapp] len=[5] | | | | info : ret=1 | | | error_info.error_no = 1045 | | | | | mysqlnd_conn::free_contents | | | | | | >mysqlnd_net::free_contents | | | | | | mysqlnd_error_list_pdtor | | | | | | mysqlnd_ms::query | info : query=DROP TABLE IF EXISTS test | >_mysqlnd_plugin_get_plugin_connection_data | | info : plugin_id=5 | <_mysqlnd_plugin_get_plugin_connection_data | >mysqlnd_ms_pick_server_ex | | info : conn_data=0x7fb6a7d3e5a0 *conn_data=0x7fb6a7d410d0 | | >mysqlnd_ms_select_servers_all | | mysqlnd_ms_choose_connection_rr | | | >mysqlnd_ms_query_is_select [...] | | | mysqlnd_ms_advanced_connect | | | | >mysqlnd_conn::connect | | | | | info : host=localhost user=root db=test port=3306 flags=131072 persistent=0 state=0 In this case the statement `DROP TABLE IF EXISTS test' has been executed. Note that the statement string is shown in the log file. You may want to take measures to restrict access to the log for security considerations. The statement has been load balanced using round robin policy, as you can easily guess from the functions name `>mysqlnd_ms_choose_connection_rr'. It has been sent to a master server running on `host=localhost user=root db=test port=3306 flags=131072 persistent=0 state=0'.  File: manual.info, Node: apis-php-mysqlnd-ms.monitoring, Prev: apis-php-mysqlnd-ms.debugging, Up: apis-php-mysqlnd-ms.setup 21.9.2.37 Monitoring .................... Copyright 1997-2012 the PHP Documentation Group. Plugin activity can be monitored using the mysqlnd trace log, mysqlnd statistics, mysqlnd_ms plugin statistics and external PHP debugging tools. Use of the trace log should be limited to debugging. It is recommended to use the plugins statistics for monitoring. Writing a trace log is a slow operation. If using an external PHP debugging tool, please refer to the vendors manual about its performance impact and the type of information collected. In many cases, external debugging tools will provide call stacks. Often, a call stack or a trace log is more difficult to interpret than the statistics provided by the plugin. Plugin statistics tell how often which kind of cluster node has been used (slave or master), why the node was used, if lazy connections have been used and if global transaction ID injection has been performed. The monitoring information provided enables user to verify plugin decisions and to plan their cluster resources based on usage pattern. The function *Note `mysqlnd_ms_get_stats': apis-php-function.mysqlnd-ms-get-stats. is used to access the statistics. Please, see the functions description for a list of available statistics. Statistics are collected on a per PHP process basis. Their scope is a PHP process. Depending on the PHP deployment model a process may serve one or multiple web requests. If using CGI model, a PHP process serves one web request. If using FastCGI or pre-fork web server models, a PHP process usually serves multiple web requests. The same is the case with a threaded web server. Please, note that threads running in parallel can update the statistics in parallel. Thus, if using a threaded PHP deployment model, statistics can be changed by more than one script at a time. A script cannot rely on the fact that it sees only its own changes to statistics. mysqlnd_ms.enable=1 mysqlnd_ms.collect_statistics=1 query("SELECT 'Read request' FROM DUAL")) { var_dump($res->fetch_all()); } $stats_after = mysqlnd_ms_get_stats(); if ($stats_after['use_slave'] <= $stats_before['use_slave']) { echo "According to the statistics the read request has not been run on a slave!"; } ?> Statistics are aggregated for all plugin activities and all connections handled by the plugin. It is not possible to tell how much a certain connection handle has contributed to the overall statistics. Utilizing PHPs `register_shutdown_function' (http://www.php.net/register_shutdown_function) function or the `auto_append_file' PHP configuration directive it is easily possible to dump statistics into, for example, a log file when a script finishes. Instead of using a log file it is also possible to send the statistics to an external monitoring tool for recording and display. mysqlnd_ms.enable=1 mysqlnd_ms.collect_statistics=1 error_log=/tmp/php_errors.log  File: manual.info, Node: apis-php-mysqlnd-ms.constants, Next: apis-php-ref.mysqlnd-ms, Prev: apis-php-mysqlnd-ms.setup, Up: apis-php-book.mysqlnd-ms 21.9.2.38 Predefined Constants .............................. Copyright 1997-2012 the PHP Documentation Group. The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime. _SQL hint related_ The mysqlnd replication and load balancing plugin (`mysqlnd_ms') performs read/write splitting. This directs write queries to a MySQL master server, and read-only queries to the MySQL slave servers. The plugin has a built-in read/write split logic. All queries which start with `SELECT' are considered read-only queries, which are then sent to a MySQL slave server that is listed in the plugin configuration file. All other queries are directed to the MySQL master server that is also specified in the plugin configuration file. User supplied SQL hints can be used to overrule automatic read/write splitting, to gain full control on the process. SQL hints are standards compliant SQL comments. The plugin will scan the beginning of a query string for an SQL comment for certain commands, which then control query redirection. Other systems involved in the query processing are unaffected by the SQL hints because other systems will ignore the SQL comments. The plugin supports three SQL hints to direct queries to either the MySQL slave servers, the MySQL master server, or the last used MySQL server. SQL hints must be placed at the beginning of a query to be recognized by the plugin. For better portability, it is recommended to use the string constants MYSQLND_MS_MASTER_SWITCH , MYSQLND_MS_SLAVE_SWITCH and MYSQLND_MS_LAST_USED_SWITCH instead of their literal values. The above examples will output: master_query = /*ms=master*/SELECT id FROM test slave_query = /*ms=slave*/SHOW TABLES 1. MYSQLND_MS_MASTER_SWITCH (string) SQL hint used to send a query to the MySQL replication master server. 2. MYSQLND_MS_SLAVE_SWITCH (string) SQL hint used to send a query to one of the MySQL replication slave servers. 3. MYSQLND_MS_LAST_USED_SWITCH (string) SQL hint used to send a query to the last used MySQL server. The last used MySQL server can either be a master or a slave server in a MySQL replication setup. *Note `mysqlnd_ms_query_is_select': apis-php-function.mysqlnd-ms-query-is-select. related 1. MYSQLND_MS_QUERY_USE_MASTER (integer) If `mysqlnd_ms_is_select' (http://www.php.net/mysqlnd_ms_is_select) returns MYSQLND_MS_QUERY_USE_MASTER for a given query, the built-in read/write split mechanism recommends sending the query to a MySQL replication master server. 2. MYSQLND_MS_QUERY_USE_SLAVE (integer) If `mysqlnd_ms_is_select' (http://www.php.net/mysqlnd_ms_is_select) returns MYSQLND_MS_QUERY_USE_SLAVE for a given query, the built-in read/write split mechanism recommends sending the query to a MySQL replication slave server. 3. MYSQLND_MS_QUERY_USE_LAST_USED (integer) If `mysqlnd_ms_is_select' (http://www.php.net/mysqlnd_ms_is_select) returns MYSQLND_MS_QUERY_USE_LAST_USED for a given query, the built-in read/write split mechanism recommends sending the query to the last used server. *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos, quality of service filter and service level related 1. MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL (integer) Use to request the service level eventual consistency from the *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. Eventual consistency is the default quality of service when reading from an asynchronous MySQL replication slave. Data returned in this service level may or may not be stale, depending on whether the selected slaves happen to have replicated the latest changes from the MySQL replication master or not. 2. MYSQLND_MS_QOS_CONSISTENCY_SESSION (integer) Use to request the service level session consistency from the *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. Session consistency is defined as read your writes. The client is guaranteed to see his latest changes. 3. MYSQLND_MS_QOS_CONSISTENCY_STRONG (integer) Use to request the service level strong consistency from the *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. Strong consistency is used to ensure all clients see each others changes. 4. MYSQLND_MS_QOS_OPTION_GTID (integer) Used as a service level option with *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. to parameterize session consistency. 5. MYSQLND_MS_QOS_OPTION_AGE (integer) Used as a service level option with *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. to parameterize eventual consistency. _Other_ The plugins version number can be obtained using MYSQLND_MS_VERSION or MYSQLND_MS_VERSION_ID . MYSQLND_MS_VERSION is the string representation of the numerical version number MYSQLND_MS_VERSION_ID , which is an integer such as 10000. Developers can calculate the version number as follows. Unknown PHP API feature. Version (part) Example Major*10000 1*10000 = 10000 Minor*100 0*100 = 0 Patch 0 = 0 MYSQLND_MS_VERSION_ID 10000 1. MYSQLND_MS_VERSION (string) Plugin version string, for example, `1.0.0-prototype'. 2. MYSQLND_MS_VERSION_ID (integer) Plugin version number, for example, 10000.  File: manual.info, Node: apis-php-ref.mysqlnd-ms, Next: apis-php-mysqlnd-ms.changes, Prev: apis-php-mysqlnd-ms.constants, Up: apis-php-book.mysqlnd-ms 21.9.2.39 Mysqlnd_ms Functions .............................. * Menu: * apis-php-function.mysqlnd-ms-get-last-gtid:: `mysqlnd_ms_get_last_gtid' * apis-php-function.mysqlnd-ms-get-last-used-connection:: `mysqlnd_ms_get_last_used_connection' * apis-php-function.mysqlnd-ms-get-stats:: `mysqlnd_ms_get_stats' * apis-php-function.mysqlnd-ms-match-wild:: `mysqlnd_ms_match_wild' * apis-php-function.mysqlnd-ms-query-is-select:: `mysqlnd_ms_query_is_select' * apis-php-function.mysqlnd-ms-set-qos:: `mysqlnd_ms_set_qos' * apis-php-function.mysqlnd-ms-set-user-pick-server:: `mysqlnd_ms_set_user_pick_server' Copyright 1997-2012 the PHP Documentation Group.  File: manual.info, Node: apis-php-function.mysqlnd-ms-get-last-gtid, Next: apis-php-function.mysqlnd-ms-get-last-used-connection, Prev: apis-php-ref.mysqlnd-ms, Up: apis-php-ref.mysqlnd-ms 21.9.2.40 `mysqlnd_ms_get_last_gtid' .................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_ms_get_last_gtid' Returns the latest global transaction ID *Description* string mysqlnd_ms_get_last_gtid mixedconnection Returns a global transaction identifier which belongs to a write operation no older than the last write performed by the client. It is not guaranteed that the global transaction identifier is identical to that one created for the last write transaction performed by the client. *Parameters* 1. connection A PECL/mysqlnd_ms connection handle to a MySQL server of the type See section "apis-php-ref.pdo-mysql" in the online manual, See section "apis-php-mysqli" in the online manual> or See section "apis-php-mysql" in the online manual. The connection handle is obtained when opening a connection with a host name that matches a mysqlnd_ms configuration file entry using any of the above three MySQL driver extensions. *Return Values* Returns a global transaction ID (GTID) on success. Otherwise, returns FALSE . The function *Note `mysqlnd_ms_get_last_gtid': apis-php-function.mysqlnd-ms-get-last-gtid. returns the GTID obtained when executing the SQL statement from the `fetch_last_gtid' entry of the `global_transaction_id_injection' section from the plugins configuration file. The function may be called after the GTID has been incremented. *Notes* *Note*: *Note `mysqlnd_ms_get_last_gtid': apis-php-function.mysqlnd-ms-get-last-gtid. requires PHP >= 5.4.0 and PECL mysqlnd_ms >= 1.2.0. Internally, it is using a `mysqlnd' library C functionality not available with PHP 5.3. *Examples* query("DROP TABLE IF EXISTS test")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli)); /* auto commit mode, transaction on master, GTID must be incremented */ if (!$mysqli->query("CREATE TABLE test(id INT)")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli)); ?> *See Also* *Note Global Transaction IDs: apis-php-mysqlnd-ms.gtid.  File: manual.info, Node: apis-php-function.mysqlnd-ms-get-last-used-connection, Next: apis-php-function.mysqlnd-ms-get-stats, Prev: apis-php-function.mysqlnd-ms-get-last-gtid, Up: apis-php-ref.mysqlnd-ms 21.9.2.41 `mysqlnd_ms_get_last_used_connection' ............................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_ms_get_last_used_connection' Returns an array which describes the last used connection *Description* array mysqlnd_ms_get_last_used_connection mixedconnection Returns an array which describes the last used connection from the plugins connection pool currently pointed to by the user connection handle. If using the plugin, a user connection handle represents a pool of database connections. It is not possible to tell from the user connection handles properties to which database server from the pool the user connection handle points. The function can be used to debug or monitor PECL mysqlnd_ms. *Parameters* 1. connection A MySQL connection handle obtained from any of the connect functions of the mysqli, mysql or See section "apis-php-ref.pdo-mysql" in the online manual extensions. *Return Values* FALSE on error. Otherwise, an array which describes the connection used to execute the last statement on. Array which describes the connection. Unknown PHP API feature. PropertyDescription Version `scheme'Connection scheme. Either `tcp://host:port' or Since 1.1.0. `unix://host:socket'. If you want to distinguish connections from each other use a combination of `scheme' and `thread_id' as a unique key. Neither `scheme' nor `thread_id' alone are sufficient to distinguish two connections from each other. Two servers may assign the same `thread_id' to two different connections. Thus, connections in the pool may have the same `thread_id'. Also, do not rely on uniqueness of `scheme' in a pool. Your QA engineers may use the same MySQL server instance for two distinct logical roles and add it multiple times to the pool. This hack is used, for example, in the test suite. `host' Database server host used with the connection. Since 1.1.0. The host is only set with TCP/IP connections. It is empty with Unix domain or Windows named pipe connections, `host_info'A character string representing the server Since 1.1.2. hostname and the connection type. `port' Database server port used with the connection. Since 1.1.0. `socket_or_pipe'Unix domain socket or Windows named pipe used Since 1.1.2. with the connection. The value is empty for TCP/IP connections. `thread_id'Connection thread id. Since 1.1.0. `last_message'Info message obtained from the MySQL C API Since 1.1.0. function mysql_info(). Please, see `mysqli_info' for a description. `errno' Error code. Since 1.1.0. `error' Error message. Since 1.1.0. `sqlstate'Error SQLstate code. Since 1.1.0. *Notes* *Note*: *Note `mysqlnd_ms_get_last_used_connection': apis-php-function.mysqlnd-ms-get-last-used-connection. requires PHP >= 5.4.0 and PECL mysqlnd_ms >> 1.1.0. Internally, it is using a `mysqlnd' library C call not available with PHP 5.3. *Examples* The example assumes that `myapp' refers to a plugin configuration file section and represents a connection pool. query("SELECT 1 FROM DUAL"); var_dump(mysqlnd_ms_get_last_used_connection($link)); ?> The above example will output: array(10) { ["scheme"]=> string(22) "unix:///tmp/mysql.sock" ["host_info"]=> string(25) "Localhost via UNIX socket" ["host"]=> string(0) "" ["port"]=> int(3306) ["socket_or_pipe"]=> string(15) "/tmp/mysql.sock" ["thread_id"]=> int(46253) ["last_message"]=> string(0) "" ["errno"]=> int(0) ["error"]=> string(0) "" ["sqlstate"]=> string(5) "00000" }  File: manual.info, Node: apis-php-function.mysqlnd-ms-get-stats, Next: apis-php-function.mysqlnd-ms-match-wild, Prev: apis-php-function.mysqlnd-ms-get-last-used-connection, Up: apis-php-ref.mysqlnd-ms 21.9.2.42 `mysqlnd_ms_get_stats' ................................ Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_ms_get_stats' Returns query distribution and connection statistics *Description* array mysqlnd_ms_get_stats Returns an array of statistics collected by the replication and load balancing plugin. The PHP configuration setting `mysqlnd_ms.collect_statistics' controls the collection of statistics. The collection of statistics is disabled by default for performance reasons. The scope of the statistics is the `PHP' process. Depending on your deployment model a `PHP' process may handle one or multiple requests. Statistics are aggregated for all connections and all storage handler. It is not possible to tell how much queries originating from `mysqli', `PDO_MySQL' or `mysql' API calls have contributed to the aggregated data values. *Parameters* This function has no parameters. *Return Values* Returns NULL if the PHP configuration directive `mysqlnd_ms.enable' has disabled the plugin. Otherwise, returns array of statistics. Array of statistics Unknown PHP API feature. StatisticDescription Version `use_slave'The semantics of this statistic has changed Since 1.0.0. between 1.0.1 - 1.1.0. The meaning for version 1.0.1 is as follows. Number of statements considered as read-only by the built-in query analyzer. Neither statements which begin with a SQL hint to force use of slave nor statements directed to a slave by an user-defined callback are included. The total number of statements sent to the slaves is `use_slave' + `use_slave_sql_hint' + `use_slave_callback'. PECL/mysqlnd_ms 1.1.0 introduces a new concept of chained filters. The statistics is now set by the internal load balancing filter. With version 1.1.0 the load balancing filter is always the last in the filter chain, if used. In future versions a load balancing filter may be followed by other filters causing another change in the meaning of the statistic. If, in the future, a load balancing filter is followed by another filter it is no longer guaranteed that the statement, which increments `use_slave', will be executed on the slaves. The meaning for version 1.1.0 is as follows. Number of statements sent to the slaves. Statements directed to a slave by the user filter (an user-defined callback) are not included. The latter are counted by `use_slave_callback'. `use_master'The semantics of this statistic has changed Since 1.0.0. between 1.0.1 - 1.1.0. The meaning for version 1.0.1 is as follows. Number of statements not considered as read-only by the built-in query analyzer. Neither statements which begin with a SQL hint to force use of master nor statements directed to a master by an user-defined callback are included. The total number of statements sent to the master is `use_master' + `use_master_sql_hint' + `use_master_callback'. PECL/mysqlnd_ms 1.1.0 introduces a new concept of chained filters. The statictics is now set by the internal load balancing filter. With version 1.1.0 the load balancing filter is always the last in the filter chain, if used. In future versions a load balancing filter may be followed by other filters causing another change in the meaning of the statistic. If, in the future, a load balancing filter is followed by another filter it is no longer guaranteed that the statement, which increments `use_master', will be executed on the slaves. The meaning for version 1.1.0 is as follows. Number of statements sent to the masters. Statements directed to a master by the user filter (an user-defined callback) are not included. The latter are counted by `use_master_callback'. `use_slave_guess'Number of statements the built-in query analyzer Since 1.1.0. recommends sending to a slave because they contain no SQL hint to force use of a certain server. The recommendation may be overruled in the following. It is not guaranteed whether the statement will be executed on a slave or not. This is how often the internal `is_select' function has guessed that a slave shall be used. Please, see also the user space function *Note `mysqlnd_ms_query_is_select': apis-php-function.mysqlnd-ms-query-is-select. `use_master_guess'Number of statements the built-in query analyzer Since 1.1.0. recommends sending to a master because they contain no SQL hint to force use of a certain server. The recommendation may be overruled in the following. It is not guaranteed whether the statement will be executed on a slave or not. This is how often the internal `is_select' function has guessed that a master shall be used. Please, see also the user space function *Note `mysqlnd_ms_query_is_select': apis-php-function.mysqlnd-ms-query-is-select. `use_slave_sql_hint'Number of statements sent to a slave because Since 1.0.0. statement begins with the SQL hint to force use of slave. `use_master_sql_hint'Number of statements sent to a master because Since 1.0.0. statement begins with the SQL hint to force use of master. `use_last_used_sql_hint'Number of statements sent to server which has run Since 1.0.0. the previous statement, because statement begins with the SQL hint to force use of previously used server. `use_slave_callback'Number of statements sent to a slave because an Since 1.0.0. user-defined callback has chosen a slave server for statement execution. `use_master_callback'Number of statements sent to a master because an Since 1.0.0. user-defined callback has chosen a master server for statement execution. `non_lazy_connections_slave_success'Number of successfully opened slave connections Since 1.0.0. from configurations not using `lazy connections'. The total number of successfully opened slave connections is `non_lazy_connections_slave_success' + `lazy_connections_slave_success' `non_lazy_connections_slave_failure'Number of failed slave connection attempts from Since 1.0.0. configurations not using `lazy connections'. The total number of failed slave connection attempts is `non_lazy_connections_slave_failure' + `lazy_connections_slave_failure' `non_lazy_connections_master_success'Number of successfully opened master connections Since 1.0.0. from configurations not using `lazy connections'. The total number of successfully opened master connections is `non_lazy_connections_master_success' + `lazy_connections_master_success' `non_lazy_connections_master_failure'Number of failed master connection attempts from Since 1.0.0. configurations not using `lazy connections'. The total number of failed master connection attempts is `non_lazy_connections_master_failure' + `lazy_connections_master_failure' `lazy_connections_slave_success'Number of successfully opened slave connections Since 1.0.0. from configurations using `lazy connections'. `lazy_connections_slave_failure'Number of failed slave connection attempts from Since 1.0.0. configurations using `lazy connections'. `lazy_connections_master_success'Number of successfully opened master connections Since 1.0.0. from configurations using `lazy connections'. `lazy_connections_master_failure'Number of failed master connection attempts from Since 1.0.0. configurations using `lazy connections'. `trx_autocommit_on'Number of `autocommit' mode activations via API Since 1.0.0. calls. This figure may be used to monitor activity related to the plugin configuration setting `trx_stickiness'. If, for example, you want to know if a certain API call invokes the `mysqlnd' library function `trx_autocommit()', which is a requirement for `trx_stickiness', you may call the user API function in question and check if the statistic has changed. The statistic is modified only by the plugins internal subclassed `trx_autocommit()' method. `trx_autocommit_off'Number of `autocommit' mode deactivations via API Since 1.0.0. calls. `trx_master_forced'Number of statements redirected to the master Since 1.0.0. while `trx_stickiness=master' and `autocommit' mode is disabled. `gtid_autocommit_injections_success'Number of successful SQL injections in autocommit Since 1.2.0. mode as part of the plugins client-side *Note global transaction id emulation: apis-php-mysqlnd-ms.gtid. `gtid_autocommit_injections_failure'Number of failed SQL injections in autocommit Since 1.2.0. mode as part of the plugins client-side *Note global transaction id emulation: apis-php-mysqlnd-ms.gtid. `gtid_commit_injections_success'Number of successful SQL injections in commit Since 1.2.0. mode as part of the plugins client-side *Note global transaction id emulation: apis-php-mysqlnd-ms.gtid. `gtid_commit_injections_failure'Number of failed SQL injections in commit mode as Since 1.2.0. part of the plugins client-side *Note global transaction id emulation: apis-php-mysqlnd-ms.gtid. `gtid_implicit_commit_injections_success'Number of successful SQL injections when implicit Since 1.2.0. commit is detected as part of the plugins client-side *Note global transaction id emulation: apis-php-mysqlnd-ms.gtid. Implicit commit happens, for example, when autocommit has been turned off, a query is executed and autocommit is enabled again. In that case, the statement will be committed by the server and SQL to maintain is injected before the autocommit is re-enabled. Another sequence causing an an implicit commit is `begin()', `query()', `begin()'. The second call to `begin()' will implicitly commit the transaction started by the first call to `begin()'. `begin()' refers to internal library calls not actual PHP user API calls. `gtid_implicit_commit_injections_failure'Number of failed SQL injections when implicit Since 1.2.0. commit is detected as part of the plugins client-side *Note global transaction id emulation: apis-php-mysqlnd-ms.gtid. Implicit commit happens, for example, when autocommit has been turned off, a query is executed and autocommit is enabled again. In that case, the statement will be committed by the server and SQL to maintain is injected before the autocommit is re-enabled. `transient_error_retries'How often an operation has been retried when a Since 1.6.0. transient error was detected. See also, `transient_error' plugin configuration file setting. *Examples* The above example will output: mysqlnd_ms.enable = 1 mysqlnd_ms.collect_statistics = 1 array(26) { ["use_slave"]=> string(1) "0" ["use_master"]=> string(1) "0" ["use_slave_guess"]=> string(1) "0" ["use_master_guess"]=> string(1) "0" ["use_slave_sql_hint"]=> string(1) "0" ["use_master_sql_hint"]=> string(1) "0" ["use_last_used_sql_hint"]=> string(1) "0" ["use_slave_callback"]=> string(1) "0" ["use_master_callback"]=> string(1) "0" ["non_lazy_connections_slave_success"]=> string(1) "0" ["non_lazy_connections_slave_failure"]=> string(1) "0" ["non_lazy_connections_master_success"]=> string(1) "0" ["non_lazy_connections_master_failure"]=> string(1) "0" ["lazy_connections_slave_success"]=> string(1) "0" ["lazy_connections_slave_failure"]=> string(1) "0" ["lazy_connections_master_success"]=> string(1) "0" ["lazy_connections_master_failure"]=> string(1) "0" ["trx_autocommit_on"]=> string(1) "0" ["trx_autocommit_off"]=> string(1) "0" ["trx_master_forced"]=> string(1) "0" ["gtid_autocommit_injections_success"]=> string(1) "0" ["gtid_autocommit_injections_failure"]=> string(1) "0" ["gtid_commit_injections_success"]=> string(1) "0" ["gtid_commit_injections_failure"]=> string(1) "0" ["gtid_implicit_commit_injections_success"]=> string(1) "0" ["gtid_implicit_commit_injections_failure"]=> string(1) "0" ["transient_error_retries"]=> string(1) "0" } *See Also* *Note Runtime configuration: apis-php-mysqlnd-ms.configuration. mysqlnd_ms.collect_statistics mysqlnd_ms.enable *Note Monitoring: apis-php-mysqlnd-ms.monitoring.  File: manual.info, Node: apis-php-function.mysqlnd-ms-match-wild, Next: apis-php-function.mysqlnd-ms-query-is-select, Prev: apis-php-function.mysqlnd-ms-get-stats, Up: apis-php-ref.mysqlnd-ms 21.9.2.43 `mysqlnd_ms_match_wild' ................................. Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_ms_match_wild' Finds whether a table name matches a wildcard pattern or not *Description* bool mysqlnd_ms_match_wild stringtable_name stringwildcard Finds whether a table name matches a wildcard pattern or not. This function is not of much practical relevance with PECL mysqlnd_ms 1.1.0 because the plugin does not support MySQL replication table filtering yet. *Parameters* 1. table_name The table name to check if it is matched by the wildcard. 2. wildcard The wildcard pattern to check against the table name. The wildcard pattern supports the same placeholders as MySQL replication filters do. MySQL replication filters can be configured by using the MySQL Server configuration options `--replicate-wild-do-table' and `--replicate-wild-do-db'. Please, consult the MySQL Reference Manual to learn more about this MySQL Server feature. The supported placeholders are: * `%' - zero or more literals * `%' - one literal Placeholders can be escaped using `\'. *Return Values* Returns TRUE `table_name' is matched by `wildcard'. Otherwise, returns FALSE *Examples* The above example will output: bool(true) bool(false) bool(true) bool(true) bool(true) bool(true)  File: manual.info, Node: apis-php-function.mysqlnd-ms-query-is-select, Next: apis-php-function.mysqlnd-ms-set-qos, Prev: apis-php-function.mysqlnd-ms-match-wild, Up: apis-php-ref.mysqlnd-ms 21.9.2.44 `mysqlnd_ms_query_is_select' ...................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_ms_query_is_select' Find whether to send the query to the master, the slave or the last used MySQL server *Description* int mysqlnd_ms_query_is_select stringquery Finds whether to send the query to the master, the slave or the last used MySQL server. The plugins built-in read/write split mechanism will be used to analyze the query string to make a recommendation where to send the query. The built-in read/write split mechanism is very basic and simple. The plugin will recommend sending all queries to the MySQL replication master server but those which begin with `SELECT', or begin with a SQL hint which enforces sending the query to a slave server. Due to the basic but fast algorithm the plugin may propose to run some read-only statements such as `SHOW TABLES' on the replication master. *Parameters* 1. query Query string to test. *Return Values* A return value of MYSQLND_MS_QUERY_USE_MASTER indicates that the query should be send to the MySQL replication master server. The function returns a value of MYSQLND_MS_QUERY_USE_SLAVE if the query can be run on a slave because it is considered read-only. A value of MYSQLND_MS_QUERY_USE_LAST_USED is returned to recommend running the query on the last used server. This can either be a MySQL replication master server or a MySQL replication slave server. If read write splitting has been disabled by setting `mysqlnd_ms.disable_rw_split', the function will always return MYSQLND_MS_QUERY_USE_MASTER or MYSQLND_MS_QUERY_USE_LAST_USED . *Examples* The above example will output: INSERT INTO test(id) VALUES (1) should be run on the master. SELECT 1 FROM DUAL should be run on a slave. /*ms=last_used*/SELECT 2 FROM DUAL should be run on the server that has run the previous query *See Also* *Note Predefined Constants: apis-php-mysqlnd-ms.constants. `user' filter *Note Runtime configuration: apis-php-mysqlnd-ms.configuration. mysqlnd_ms.disable_rw_split mysqlnd_ms.enable  File: manual.info, Node: apis-php-function.mysqlnd-ms-set-qos, Next: apis-php-function.mysqlnd-ms-set-user-pick-server, Prev: apis-php-function.mysqlnd-ms-query-is-select, Up: apis-php-ref.mysqlnd-ms 21.9.2.45 `mysqlnd_ms_set_qos' .............................. Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_ms_set_qos' Sets the quality of service needed from the cluster *Description* bool mysqlnd_ms_set_qos mixedconnection intservice_level intservice_level_option mixedoption_value Sets the quality of service needed from the cluster. A database cluster delivers a certain quality of service to the user depending on its architecture. A major aspect of the quality of service is the consistency level the cluster can offer. An asynchronous MySQL replication cluster defaults to eventual consistency for slave reads: a slave may serve stale data, current data, or it may have not the requested data at all, because it is not synchronous to the master. In a MySQL replication cluster, only master accesses can give strong consistency, which promises that all clients see each others changes. PECL/mysqlnd_ms hides the complexity of choosing appropriate nodes to achieve a certain level of service from the cluster. The "Quality of Service" filter implements the necessary logic. The filter can either be configured in the plugins configuration file, or at runtime using *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. Similar results can be achieved with PECL mysqlnd_ms < 1.2.0, if using SQL hints to force the use of a certain type of node or using the `master_on_write' plugin configuration option. The first requires more code and causes more work on the application side. The latter is less refined than using the quality of service filter. Settings made through the function call can be reversed, as shown in the example below. The example temporarily switches to a higher service level (session consistency, read your writes) and returns back to the clusters default after it has performed all operations that require the better service. This way, read load on the master can be minimized compared to using `master_on_write', which would continue using the master after the first write. Since 1.5.0 calls will fail when done in the middle of a transaction if transaction stickiness is enabled and transaction boundaries have been detected. properly. *Parameters* 1. connection A PECL/mysqlnd_ms connection handle to a MySQL server of the type See section "apis-php-ref.pdo-mysql" in the online manual, See section "apis-php-mysqli" in the online manual or See section "apis-php-mysql" in the online manual for which a service level is to be set. The connection handle is obtained when opening a connection with a host name that matches a mysqlnd_ms configuration file entry using any of the above three MySQL driver extensions. 2. service_level The requested service level: MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL , MYSQLND_MS_QOS_CONSISTENCY_SESSION or MYSQLND_MS_QOS_CONSISTENCY_STRONG . 3. service_level_option An option to parameterize the requested service level. The option can either be MYSQLND_MS_QOS_OPTION_GTID or MYSQLND_MS_QOS_OPTION_AGE . The option MYSQLND_MS_QOS_OPTION_GTID can be used to refine the service level MYSQLND_MS_QOS_CONSISTENCY_SESSION . It must be combined with a fourth function parameter, the option_value. The option_value shall be a global transaction ID obtained from *Note `mysqlnd_ms_get_last_gtid': apis-php-function.mysqlnd-ms-get-last-gtid. If set, the plugin considers both master servers and asynchronous slaves for session consistency (read your writes). Otherwise, only masters are used to achieve session consistency. A slave is considered up-to-date and checked if it has already replicated the global transaction ID from option_value. Please note, searching appropriate slaves is an expensive and slow operation. Use the feature sparsely, if the master cannot handle the read load alone. The MYSQLND_MS_QOS_OPTION_AGE option can be combined with the MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL service level, to filter out asynchronous slaves that lag more seconds behind the master than option_value. If set, the plugin will only consider slaves for reading if `SHOW SLAVE STATUS' reports `Slave_IO_Running=Yes', `Slave_SQL_Running=Yes' and `Seconds_Behind_Master <= option_value'. Please note, searching appropriate slaves is an expensive and slow operation. Use the feature sparsely in version 1.2.0. Future versions may improve the algorithm used to identify candidates. Please, see the MySQL reference manual about the precision, accuracy and limitations of the MySQL administrative command `SHOW SLAVE STATUS'. 4. option_value Parameter value for the service level option. See also the service_level_option parameter. *Return Values* Returns TRUE if the connections service level has been switched to the requested. Otherwise, returns FALSE *Notes* *Note*: *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. requires PHP >= 5.4.0 and PECL mysqlnd_ms >= 1.2.0. Internally, it is using a `mysqlnd' library C functionality not available with PHP 5.3. *Examples* errno, $mysqli->error)); /* Will use master and return fresh data, client can see his last write */ if (!$res = $mysqli->query("SELECT item, price FROM orders WHERE order_id = 1")) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* Back to default: use of all slaves and masters permitted, stale data can happen */ if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL)) die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); ?> *See Also* *Note `mysqlnd_ms_get_last_gtid': apis-php-function.mysqlnd-ms-get-last-gtid. *Note Service level and consistency concept: apis-php-mysqlnd-ms.qos-consistency. *Note Filter concept: apis-php-mysqlnd-ms.filter.  File: manual.info, Node: apis-php-function.mysqlnd-ms-set-user-pick-server, Prev: apis-php-function.mysqlnd-ms-set-qos, Up: apis-php-ref.mysqlnd-ms 21.9.2.46 `mysqlnd_ms_set_user_pick_server' ........................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_ms_set_user_pick_server' Sets a callback for user-defined read/write splitting *Description* bool mysqlnd_ms_set_user_pick_server stringfunction Sets a callback for user-defined read/write splitting. The plugin will call the callback only if `pick[]=user' is the default rule for server picking in the relevant section of the plugins configuration file. The plugins built-in read/write query split mechanism decisions can be overwritten in two ways. The easiest way is to prepend the query string with the SQL hints MYSQLND_MS_MASTER_SWITCH , MYSQLND_MS_SLAVE_SWITCH or MYSQLND_MS_LAST_USED_SWITCH . Using SQL hints one can control, for example, whether a query shall be send to the MySQL replication master server or one of the slave servers. By help of SQL hints it is not possible to pick a certain slave server for query execution. Full control on server selection can be gained using a callback function. Use of a callback is recommended to expert users only because the callback has to cover all cases otherwise handled by the plugin. The plugin will invoke the callback function for selecting a server from the lists of configured master and slave servers. The callback function inspects the query to run and picks a server for query execution by returning the hosts URI, as found in the master and slave list. If the lazy connections are enabled and the callback chooses a slave server for which no connection has been established so far and establishing the connection to the slave fails, the plugin will return an error upon the next action on the failed connection, for example, when running a query. It is the responsibility of the application developer to handle the error. For example, the application can re-run the query to trigger a new server selection and callback invocation. If so, the callback must make sure to select a different slave, or check slave availability, before returning to the plugin to prevent an endless loop. *Parameters* 1. function The function to be called. Class methods may also be invoked statically using this function by passing `array($classname, $methodname)' to this parameter. Additionally class methods of an object instance may be called by passing `array($objectinstance, $methodname)' to this parameter. *Return Values* Host to run the query on. The host URI is to be taken from the master and slave connection lists passed to the callback function. If callback returns a value neither found in the master nor in the slave connection lists the plugin will fallback to the second pick method configured via the `pick[]' setting in the plugin configuration file. If not second pick method is given, the plugin falls back to the build-in default pick method for server selection. *Notes* *Note*: *Note `mysqlnd_ms_set_user_pick_server': apis-php-function.mysqlnd-ms-set-user-pick-server. is available with PECL mysqlnd_ms < 1.1.0. It has been replaced by the `user' filter. Please, check the *Note Change History: apis-php-mysqlnd-ms.changes-one-one. for upgrade notes. *Examples* [myapp] master[] = localhost slave[] = 192.168.2.27:3306 slave[] = 192.168.78.136:3306 pick[] = user query("SELECT 1 FROM DUAL"))) printf("[%d] %s\n", $mysqli->errno, $mysqli->error); else $res->close(); if (!($res = $mysqli->query("SELECT 2 FROM DUAL"))) printf("[%d] %s\n", $mysqli->errno, $mysqli->error); else $res->close(); if (!($res = $mysqli->query("SELECT * FROM table_on_slave_a_only"))) printf("[%d] %s\n", $mysqli->errno, $mysqli->error); else $res->close(); $mysqli->close(); ?> The above example will output: User has connected to 'myapp'... ... deciding where to run 'SELECT 1 FROM DUAL' ... some read-only query for a slave ... ret = 'tcp://192.168.2.27:3306' User has connected to 'myapp'... ... deciding where to run 'SELECT 2 FROM DUAL' ... some read-only query for a slave ... ret = 'tcp://192.168.78.136:3306' User has connected to 'myapp'... ... deciding where to run 'SELECT * FROM table_on_slave_a_only' ... access to table available only on slave A detected ... ret = 'tcp://192.168.2.27:3306' *See Also* *Note `mysqlnd_ms_query_is_select': apis-php-function.mysqlnd-ms-query-is-select. *Note Filter concept: apis-php-mysqlnd-ms.filter. `user' filter  File: manual.info, Node: apis-php-mysqlnd-ms.changes, Prev: apis-php-ref.mysqlnd-ms, Up: apis-php-book.mysqlnd-ms 21.9.2.47 Change History ........................ * Menu: * apis-php-mysqlnd-ms.changes-one-six:: PECL/mysqlnd_ms 1.6 series * apis-php-mysqlnd-ms.changes-one-five:: PECL/mysqlnd_ms 1.5 series * apis-php-mysqlnd-ms.changes-one-four:: PECL/mysqlnd_ms 1.4 series * apis-php-mysqlnd-ms.changes-one-three:: PECL/mysqlnd_ms 1.3 series * apis-php-mysqlnd-ms.changes-one-two:: PECL/mysqlnd_ms 1.2 series * apis-php-mysqlnd-ms.changes-one-one:: PECL/mysqlnd_ms 1.1 series * apis-php-mysqlnd-ms.changes-one-o:: PECL/mysqlnd_ms 1.0 series Copyright 1997-2012 the PHP Documentation Group. This change history is a high level summary of selected changes that may impact applications and/or break backwards compatibility. See also the `CHANGES' file in the source distribution for a complete list of changes.  File: manual.info, Node: apis-php-mysqlnd-ms.changes-one-six, Next: apis-php-mysqlnd-ms.changes-one-five, Prev: apis-php-mysqlnd-ms.changes, Up: apis-php-mysqlnd-ms.changes 21.9.2.48 PECL/mysqlnd_ms 1.6 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.6.0-alpha * Release date: TBD * Motto/theme: Maintenance *Note*: This is the current development series. All features are at an early stage. Changes may happen at any time without prior notice. Please, do not use this version in production environments. The documentation may not reflect all changes yet. Bug fixes * No new bugs reported Feature changes * Introduced automatic retry loop for *Note transient errors: apis-php-mysqlnd-ms.transient_errors. and *Note corresponding statistic: apis-php-function.mysqlnd-ms-get-stats. to count the number of implicit retries. Some distributed database clusters use transient errors to hint a client to retry its operation in a bit. Most often, the client is then supposed to halt execution (sleep) for a short moment before retrying the desired operation. Immediately failing over to another node is not necessary in response to the error. Instead, a retry loop can be performed. Common situation when using MySQL Cluster.  File: manual.info, Node: apis-php-mysqlnd-ms.changes-one-five, Next: apis-php-mysqlnd-ms.changes-one-four, Prev: apis-php-mysqlnd-ms.changes-one-six, Up: apis-php-mysqlnd-ms.changes 21.9.2.49 PECL/mysqlnd_ms 1.5 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.5.1-stable * Release date: 06/2013 * Motto/theme: Sharding support, improved transaction support *Note*: This is the current stable series. Use this version in production environments. The documentation is complete. 1.5.0-alpha * Release date: 03/2013 * Motto/theme: Sharding support, improved transaction support Bug fixes * Fixed #60605 PHP segmentation fault when mysqlnd_ms is enabled. * Setting transaction stickiness disables all load balancing, including automatic failover, for the duration of a transaction. So far connection switches could have happened in the middle of a transaction in multi-master configurations and during automatic failover although transaction monitoring had detected transaction boundaries properly. * BC break and bug fix. SQL hints enforcing the use of a specific kind of server ( MYSQLND_MS_MASTER_SWITCH , MYSQLND_MS_SLAVE_SWITCH , MYSQLND_MS_LAST_USED_SWITCH ) are ignored for the duration of a transaction of transaction stickiness is enabled and transaction boundaries have been detected properly. This is a change in behaviour. However, it is also a bug fix and a step to align behaviour. If, in previous versions, transaction stickiness, one of the above listed SQL hints and the quality of service filtering was combined it could happened that the SQL hints got ignored. In some case the SQL hints did work, in other cases they did not. The new behaviour is more consistent. SQL hints will always be ignore for the duration of a transaction, if transaction stickiness is enabled. Please note, transaction boundary detection continues to be based on API call monitoring. SQL commands controlling transactions are not monitored. * BC break and bug fix. Calls to *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. will fail when done in the middle of a transaction if transaction stickiness is enabled. Connection switches are not allowed for the duration of a transaction. Changing the quality of service likely results on a different set of servers qualifying for query execution, possibly making it necessary to switch connections. Thus, the call is not allowed in during an active transaction. The quality of server can, however, be changed in between transactions. Feature changes * Introduced the `node_group' filter. The filter lets you organize servers (master and slaves) into groups. Queries can be directed to a certain group of servers by prefixing the query statement with a SQL hint/comment that contains the groups configured name. Grouping can be used for partitioning and sharding, and also to optimize for local caching. In the case of sharding, a group name can be thought of like a shard key. All queries for a given shard key will be executed on the configured shard. Note: both the client and server must support sharding for sharding to function with mysqlnd_ms. * Extended configuration file validation during PHP startup (RINIT). An E_WARNING level error will be thrown if the configuration file can not be read (permissions), is empty, or the file (JSON) could not be parsed. Warnings may appear in log files, which depending on how PHP is configured. Distributions that aim to provide a pre-configured setup, including a configuration file stub, are asked to put `{}' into the configuration file to prevent this warning about an invalid configuration file. Further configuration file validation is done when parsing sections upon opening a connection. Please, note that there may still be situations when an invalid plugin configuration file does not lead to proper error messages but a failure to connect. * As of PHP 5.5.0, improved support for transaction boundaries detection was added for `mysqli'. The `mysqli' extension has been modified to use the new C API calls of the `mysqlnd' library to begin, commit, and rollback a transaction or savepoint. If trx_stickiness is used to enable transaction aware load balancing, the `mysqli_begin' (http://www.php.net/mysqli_begin), `mysqli_commit' and `mysqli_rollback' functions will now be monitered by the plugin, to go along with the `mysqli_autocommit' function that was already supported. All SQL features to control transactions are also available through the improved `mysqli' transaction control related functions. This means that it is not required to issue SQL statements instead of using API calls. Applications using the appropriate API calls can be load balanced by PECL/mysqlnd_ms in a completely transaction-aware way. Please note, `PDO_MySQL' has not been updated yet to utilize the new mysqlnd API calls. Thus, transaction boundary detection with `PDO_MySQL' continues to be limited to the monitoring by passing in PDO::ATTR_AUTOCOMMIT to `PDO::setAttribute' (http://www.php.net/PDO::setAttribute). * Introduced `trx_stickiness=on'. This trx_stickiness option differs from `trx_stickiness=master' as it tries to execute a read-only transaction on a slave, if quality of service (consistency level) allows the use of a slave. Read-only transactions were introduced in MySQL 5.6, and they offer performance gains. * Query cache support is considered beta if used with the `mysqli' API. It should work fine with primary copy based clusters. For all other APIs, this feature continues to be called experimental. * The code examples in the mysqlnd_ms source were updated.  File: manual.info, Node: apis-php-mysqlnd-ms.changes-one-four, Next: apis-php-mysqlnd-ms.changes-one-three, Prev: apis-php-mysqlnd-ms.changes-one-five, Up: apis-php-mysqlnd-ms.changes 21.9.2.50 PECL/mysqlnd_ms 1.4 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.4.2-stable * Release date: 08/2012 * Motto/theme: Tweaking based on user feedback 1.4.1-beta * Release date: 08/2012 * Motto/theme: Tweaking based on user feedback Bug fixes * Fixed build with PHP 5.5 1.4.0-alpha * Release date: 07/2012 * Motto/theme: Tweaking based on user feedback Feature changes * BC break: Renamed plugin configuration setting `ini_file' to `config_file'. In early versions the plugin configuration file used ini style. Back then the configuration setting was named accordingly. It has now been renamed to reflect the newer file format and to distinguish it from PHP's own ini file (configuration directives file). * Introduced new default charset setting `server_charset' to allow proper escaping before a connection is opened. This is most useful when using lazy connections, which are a default. * Introduced `wait_for_gtid_timeout' setting to throttle slave reads that need session consistency. If global transaction identifier are used and the service level is set to session consistency, the plugin tries to find up-to-date slaves. The slave status check is done by a SQL statement. If nothing else is set, the slave status is checked only one can the search for more up-to-date slaves continues immediately thereafter. Setting `wait_for_gtid_timeout' instructs the plugin to poll a slaves status for `wait_for_gtid_timeout' seconds if the first execution of the SQL statement has shown that the slave is not up-to-date yet. The poll will be done once per second. This way, the plugin will wait for slaves to catch up and throttle the client. * New failover strategy `loop_before_master'. By default the plugin does no failover. It is possible to enable automatic failover if a connection attempt fails. Upto version 1.3 only `master' strategy existed to failover to a master if a slave connection fails. `loop_before_master' is similar but tries all other slaves before attempting to connect to the master if a slave connection fails. The number of attempts can be limited using the `max_retries' option. Failed hosts can be remembered and skipped in load balancing for the rest of the web request. `max_retries' and `remember_failed' are considered experimental although decent stability is given. Syntax and semantics may change in the future without prior notice.  File: manual.info, Node: apis-php-mysqlnd-ms.changes-one-three, Next: apis-php-mysqlnd-ms.changes-one-two, Prev: apis-php-mysqlnd-ms.changes-one-four, Up: apis-php-mysqlnd-ms.changes 21.9.2.51 PECL/mysqlnd_ms 1.3 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.3.2-stable * Release date: 04/2012 * Motto/theme: see 1.3.0-alpha Bug fixes * Fixed problem with multi-master where although in a transaction the queries to the master weren't sticky and were spread all over the masters (RR). Still not sticky for Random. Random_once is not affected. 1.3.1-beta * Release date: 04/2012 * Motto/theme: see 1.3.0-alpha Bug fixes * Fixed problem with building together with QC. 1.3.0-alpha * Release date: 04/2012 * Motto/theme: Query caching through quality-of-service concept The 1.3 series aims to improve the performance of applications and the overall load of an asynchronous MySQL cluster, for example, a MySQL cluster using MySQL Replication. This is done by transparently replacing a slave access with a local cache access, if the application allows it by setting an appropriate quality of service flag. When using MySQL replication a slave can serve stale data. An application using MySQL replication must continue to work correctly with stale data. Given that the application is know to work correctly with stale data, the slave access can transparently be replace with a local cache access. *Note PECL/mysqlnd_qc: apis-php-book.mysqlnd-qc. serves as a cache backend. PECL/mysqlnd_qc supports use of various storage locations, among others main memory, `APC' and `MEMCACHE'. Feature changes * Added cache option to quality-of-service (QoS) filter. * New configure option `enable-mysqlnd-ms-cache-support' * New constant `MYSQLND_MS_HAVE_CACHE_SUPPORT'. * New constant `MYSQLND_MS_QOS_OPTION_CACHE' to be used with *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. * Support for built-in global transaction identifier feature of MySQL 5.6.5-m8 or newer.  File: manual.info, Node: apis-php-mysqlnd-ms.changes-one-two, Next: apis-php-mysqlnd-ms.changes-one-one, Prev: apis-php-mysqlnd-ms.changes-one-three, Up: apis-php-mysqlnd-ms.changes 21.9.2.52 PECL/mysqlnd_ms 1.2 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.2.1-beta * Release date: 01/2012 * Motto/theme: see 1.2.0-alpha Minor test changes. 1.2.0-alpha * Release date: 11/2011 * Motto/theme: Global Transaction ID injection and quality-of-service concept In version 1.2 the focus continues to be on supporting MySQL database clusters with asynchronous replication. The plugin tries to make using the cluster introducing a quality-of-service filter which applications can use to define what service quality they need from the cluster. Service levels provided are eventual consistency with optional maximum age/slave slag, session consistency and strong consistency. Additionally the plugin can do client-side global transaction id injection to make manual master failover easier. Feature changes * Introduced quality-of-service (QoS) filter. Service levels provided by QoS filter: * eventual consistency, optional option slave lag * session consistency, optional option GTID * strong consistency * Added the *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. function to set the required connection quality at runtime. The new constants related to *Note `mysqlnd_ms_set_qos': apis-php-function.mysqlnd-ms-set-qos. are: * MYSQLND_MS_QOS_CONSISTENCY_STRONG * MYSQLND_MS_QOS_CONSISTENCY_SESSION * MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL * MYSQLND_MS_QOS_OPTION_GTID * MYSQLND_MS_QOS_OPTION_AGE * Added client-side global transaction id injection (GTID). * New statistics related to GTID: * `gtid_autocommit_injections_success' * `gtid_autocommit_injections_failure' * `gtid_commit_injections_success' * `gtid_commit_injections_failure' * `gtid_implicit_commit_injections_success' * `gtid_implicit_commit_injections_failure' * Added *Note `mysqlnd_ms_get_last_gtid': apis-php-function.mysqlnd-ms-get-last-gtid. to fetch the last global transaction id. * Enabled support for multi master without slaves.  File: manual.info, Node: apis-php-mysqlnd-ms.changes-one-one, Next: apis-php-mysqlnd-ms.changes-one-o, Prev: apis-php-mysqlnd-ms.changes-one-two, Up: apis-php-mysqlnd-ms.changes 21.9.2.53 PECL/mysqlnd_ms 1.1 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.1.0 * Release date: 09/2011 * Motto/theme: Cover replication basics with production quality The 1.1 and 1.0 series expose a similar feature set. Internally, the 1.1 series has been refactored to plan for future feature additions. A new configuration file format has been introduced, and limitations have been lifted. And the code quality and quality assurance has been improved. Feature changes * Added the (chainable) *Note filter concept: apis-php-mysqlnd-ms.filter.: * BC break: *Note `mysqlnd_ms_set_user_pick_server': apis-php-function.mysqlnd-ms-set-user-pick-server. has been removed. Thehttp://svn.php.net/viewvc/pecl/mysqlnd_ms/trunk/ *Note `user': apis-php-mysqlnd-ms.filter. filter has been introduced to replace it. The filter offers similar functionality, but see below for an explanation of the differences. * New powerful JSON based configuration syntax. * *Note Lazy connections improved: apis-php-mysqlnd-ms.pooling.: security relevant, and state changing commands are covered. * Support for (native) prepared statements. * New statistics: `use_master_guess', `use_slave_guess'. * BC break: Semantics of statistics changed for `use_slave', `use_master'. Future changes are likely. Please see, *Note `mysqlnd_ms_get_stats': apis-php-function.mysqlnd-ms-get-stats. * List of broadcasted messages extended by `ssl_set'. * Library calls now monitored to remember settings for lazy connections: `change_user', `select_db', `set_charset', `set_autocommit'. * Introduced `mysqlnd_ms.disable_rw_split'. The configuration setting allows using the load balancing and lazy connection functionality independently of read write splitting. Bug fixes * Fixed PECL #22724 - Server switching (mysqlnd_ms_query_is_select() case sensitive) * Fixed PECL #22784 - Using mysql_connect and mysql_select_db did not work * Fixed PECL #59982 - Unusable extension with -enable-mysqlnd-ms-table-filter. Use of the option is NOT supported. You must not used it. Added note to m4. * Fixed Bug #60119 - host="localhost" lost in mysqlnd_ms_get_last_used_connection() The *Note `mysqlnd_ms_set_user_pick_server': apis-php-function.mysqlnd-ms-set-user-pick-server. function was removed, and replaced in favor of a new `user' filter. You can no longer set a callback function using *Note `mysqlnd_ms_set_user_pick_server': apis-php-function.mysqlnd-ms-set-user-pick-server. at runtime, but instead have to configure it in the plugins configuration file. The `user' filter will pass the same arguments to the callback as before. Therefore, you can continue to use the same procedural function as a callback.callback It is no longer possible to use static class methods, or class methods of an object instance, as a callback. Doing so will cause the function executing a statement handled by the plugin to emit an E_RECOVERABLE_ERROR level error, which might look like: "`(mysqlnd_ms) Specified callback (picker) is not a valid callback'." Note: this may halt your application.  File: manual.info, Node: apis-php-mysqlnd-ms.changes-one-o, Prev: apis-php-mysqlnd-ms.changes-one-one, Up: apis-php-mysqlnd-ms.changes 21.9.2.54 PECL/mysqlnd_ms 1.0 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.0.1-alpha * Release date: 04/2011 * Motto/theme: bug fix release 1.0.0-alpha * Release date: 04/2011 * Motto/theme: Cover replication basics to test user feedback The first release of practical use. It features basic automatic read-write splitting, SQL hints to overrule automatic redirection, load balancing of slave requests, lazy connections, and optional, automatic use of the master after the first write. The public feature set is close to that of the 1.1 release. 1.0.0-pre-alpha * Release date: 09/2010 * Motto/theme: Proof of concept Initial check-in. Essentially a demo of the See section "apis-php-mysqli" in the online manual plugin API.  File: manual.info, Node: apis-php-book.mysqlnd-qc, Next: apis-php-book.mysqlnd-uh, Prev: apis-php-book.mysqlnd-ms, Up: apis-php 21.9.3 Mysqlnd query result cache plugin (`mysqlnd_qc') ------------------------------------------------------- * Menu: * apis-php-mysqlnd-qc.key-features:: Key Features * apis-php-mysqlnd-qc.limitations:: Limitations * apis-php-mysqlnd-qc.name:: On the name * apis-php-mysqlnd-qc.quickstart:: Quickstart and Examples * apis-php-mysqlnd-qc.setup:: Installing/Configuring * apis-php-mysqlnd-qc.constants:: Predefined Constants * apis-php-ref.mysqlnd-qc:: mysqlnd_qc Functions * apis-php-mysqlnd-qc.changes:: Change History Copyright 1997-2012 the PHP Documentation Group. The mysqlnd query result cache plugin adds easy to use client-side query caching to all PHP MySQL extensions using See section "apis-php-mysqli" in the online manual. As of version PHP 5.3.3 the MySQL native driver for PHP ( `mysqlnd') features an internal plugin C API. C plugins, such as the query cache plugin, can extend the functionality of See section "apis-php-mysqli" in the online manual. Mysqlnd plugins such as the query cache plugin operate transparent from a user perspective. The cache plugin supports all PHP applications and all PHP MySQL extensions ( mysqli, mysql, See section "apis-php-ref.pdo-mysql" in the online manual). It does not change existing APIs. No significant application changes are required to cache a query. The cache has two operation modes. It will either cache all queries (not recommended) or only those queries marked with a certain SQL hint (recommended).  File: manual.info, Node: apis-php-mysqlnd-qc.key-features, Next: apis-php-mysqlnd-qc.limitations, Prev: apis-php-book.mysqlnd-qc, Up: apis-php-book.mysqlnd-qc 21.9.3.1 Key Features ..................... Copyright 1997-2012 the PHP Documentation Group. * Transparent and therefore easy to use * supports all PHP MySQL extensions * no API changes * very little application changes required * Flexible invalidation strategy * Time-to-Live (TTL) * user-defined * Storage with different scope and life-span * Default (Hash, process memory) * APC (http://www.php.net/ref.apc) * MEMCACHE * sqlite * user-defined * Built-in slam defense to prevent cache stampeding.  File: manual.info, Node: apis-php-mysqlnd-qc.limitations, Next: apis-php-mysqlnd-qc.name, Prev: apis-php-mysqlnd-qc.key-features, Up: apis-php-book.mysqlnd-qc 21.9.3.2 Limitations .................... Copyright 1997-2012 the PHP Documentation Group. The current 1.0.1 release of PECL mysqlnd_qc does not support PHP 5.4. Version 1.1.0-alpha lifts this limitation. Prepared statements and unbuffered queries are fully supported. Thus, the plugin is capable of caching all statements issued with `mysqli' or `PDO_MySQL', which are the only two PHP MySQL APIs to offer prepared statement support.  File: manual.info, Node: apis-php-mysqlnd-qc.name, Next: apis-php-mysqlnd-qc.quickstart, Prev: apis-php-mysqlnd-qc.limitations, Up: apis-php-book.mysqlnd-qc 21.9.3.3 On the name .................... Copyright 1997-2012 the PHP Documentation Group. The shortcut `mysqlnd_qc' stands for `mysqlnd query cache plugin'. The name was chosen for a quick-and-dirty proof-of-concept. In the beginning the developers did not expect to continue using the code base. Sometimes PECL/mysqlnd_qc has also been called `client-side query result set cache'.  File: manual.info, Node: apis-php-mysqlnd-qc.quickstart, Next: apis-php-mysqlnd-qc.setup, Prev: apis-php-mysqlnd-qc.name, Up: apis-php-book.mysqlnd-qc 21.9.3.4 Quickstart and Examples ................................ * Menu: * apis-php-mysqlnd-qc.quickstart.concepts:: Architecture and Concepts * apis-php-mysqlnd-qc.quickstart.configuration:: Setup * apis-php-mysqlnd-qc.quickstart.caching:: Caching queries * apis-php-mysqlnd-qc.per-query-ttl:: Setting the TTL * apis-php-mysqlnd-qc.pattern-based-caching:: Pattern based caching * apis-php-mysqlnd-qc.slam-defense:: Slam defense * apis-php-mysqlnd-qc.cache-candidates:: Finding cache candidates * apis-php-mysqlnd-qc.cache-efficiency:: Measuring cache efficiency * apis-php-mysqlnd-qc.set-user-handlers:: Beyond TTL: user-defined storage Copyright 1997-2012 the PHP Documentation Group. The mysqlnd query cache plugin is easy to use. This quickstart will demo typical use-cases, and provide practical advice on getting started. It is strongly recommended to read the reference sections in addition to the quickstart. It is safe to begin with the quickstart. However, before using the plugin in mission critical environments we urge you to read additionally the background information from the reference sections. Most of the examples use the mysqli extension because it is the most feature complete PHP MySQL extension. However, the plugin can be used with any PHP MySQL extension that is using the See section "apis-php-mysqli" in the online manual library.  File: manual.info, Node: apis-php-mysqlnd-qc.quickstart.concepts, Next: apis-php-mysqlnd-qc.quickstart.configuration, Prev: apis-php-mysqlnd-qc.quickstart, Up: apis-php-mysqlnd-qc.quickstart 21.9.3.5 Architecture and Concepts .................................. Copyright 1997-2012 the PHP Documentation Group. The query cache plugin is implemented as a PHP extension. It is written in C and operates under the hood of PHP. During the startup of the PHP interpreter, it gets registered as a See section "apis-php-mysqli" in the online manual plugin to replace selected mysqlnd C methods. Hereby, it can change the behaviour of any PHP MySQL extension (mysqli, See section "apis-php-ref.pdo-mysql" in the online manual, mysql) compiled to use the mysqlnd library without changing the extensions API. This makes the plugin compatible with each and every PHP MySQL application. Because existing APIs are not changed, it is almost transparent to use. Please, see the mysqlnd plugin API description for a discussion of the advantages of the plugin architecture and a comparison with proxy based solutions. _Transparent to use_ At PHP run time PECL/mysqlnd_qc can proxy queries send from PHP (See section "apis-php-mysqli" in the online manual) to the MySQL server. It then inspects the statement string to find whether it shall cache its results. If so, result set is cached using a storage handler and further executions of the statement are served from the cache for a user-defined period. The Time to Live (TTL) of the cache entry can either be set globally or on a per statement basis. A statement is either cached if the plugin is instructed to cache all statements globally using a or, if the query string starts with the SQL hint (`/*qc=on*/'). The plugin is capable of caching any query issued by calling appropriate API calls of any of the existing PHP MySQL extensions. _Flexible storage: various storage handler_ Various storage handler are supported to offer different scopes for cache entries. Different scopes allow for different degrees in sharing cache entries among clients. * `default' (built-in): process memory, scope: process, one or more web requests depending on PHP deployment model used * `APC': shared memory, scope: single server, multiple web requests * `SQLite': memory or file, scope: single server, multiple web requests * `MEMCACHE': main memory, scope: single or multiple server, multiple web requests * `user' (built-in): user-defined - any, scope: user-defined - any Support for the `APC', `SQLite' and ` MEMCACHE' storage handler has to be enabled at compile time. The ` default' and `user' handler are built-in. It is possible to switch between compiled-in storage handlers on a per query basis at run time. However, it is recommended to pick one storage handler and use it for all cache entries. _Built-in slam defense to avoid overloading_ To avoid overload situations the cache plugin has a built-in slam defense mechanism. If a popular cache entries expires many clients using the cache entries will try to refresh the cache entry. For the duration of the refresh many clients may access the database server concurrently. In the worst case, the database server becomes overloaded and it takes more and more time to refresh the cache entry, which in turn lets more and more clients try to refresh the cache entry. To prevent this from happening the plugin has a slam defense mechanism. If slam defense is enabled and the plugin detects an expired cache entry it extends the life time of the cache entry before it refreshes the cache entry. This way other concurrent accesses to the expired cache entry are still served from the cache for a certain time. The other concurrent accesses to not trigger a concurrent refresh. Ideally, the cache entry gets refreshed by the client which extended the cache entries lifespan before other clients try to refresh the cache and potentially cause an overload situation. _Unique approach to caching_ PECL/mysqlnd_qc has a unique approach to caching result sets that is superior to application based cache solutions. Application based solutions first fetch a result set into PHP variables. Then, the PHP variables are serialized for storage in a persistent cache, and then unserialized when fetching. The mysqlnd query cache stores the raw wire protocol data sent from MySQL to PHP in its cache and replays it, if still valid, on a cache hit. This way, it saves an extra serialization step for a cache put that all application based solutions have to do. It can store the raw wire protocol data in the cache without having to serialize into a PHP variable first and deserializing the PHP variable for storing in the cache again.  File: manual.info, Node: apis-php-mysqlnd-qc.quickstart.configuration, Next: apis-php-mysqlnd-qc.quickstart.caching, Prev: apis-php-mysqlnd-qc.quickstart.concepts, Up: apis-php-mysqlnd-qc.quickstart 21.9.3.6 Setup .............. Copyright 1997-2012 the PHP Documentation Group. The plugin is implemented as a PHP extension. See also the *Note installation instructions: apis-php-mysqlnd-qc.installation. to install the PECL/mysqlnd_qc (http://pecl.php.net/package/mysqlnd_qc) extension. Compile or configure the PHP MySQL extension (mysqli, See section "apis-php-ref.pdo-mysql" in the online manual, mysql) that you plan to use with support for the See section "apis-php-mysqli" in the online manual library. PECL/mysqlnd_qc is a plugin for the mysqlnd library. To use the plugin with any of the existing PHP MySQL extensions (APIs), the extension has to use the mysqlnd library. Then, load the extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_qc.enable_qc. mysqlnd_qc.enable_qc=1  File: manual.info, Node: apis-php-mysqlnd-qc.quickstart.caching, Next: apis-php-mysqlnd-qc.per-query-ttl, Prev: apis-php-mysqlnd-qc.quickstart.configuration, Up: apis-php-mysqlnd-qc.quickstart 21.9.3.7 Caching queries ........................ Copyright 1997-2012 the PHP Documentation Group. There are four ways to trigger caching of a query. * Use of SQL hints on a per query basis * User supplied callbacks to decide on a per query basis, for example, using `mysqlnd_qc_is_select' (http://www.php.net/mysqlnd_qc_is_select) * `mysqlnd_set_cache_condition' (http://www.php.net/mysqlnd_set_cache_condition) for rule based automatic per query decisions * `*Note mysqlnd_qc.cache_by_default = 1: apis-php-mysqlnd-qc.configuration.' to cache all queries blindly Use of SQL hints and `*Note mysqlnd_qc.cache_by_default = 1: apis-php-mysqlnd-qc.configuration.' are explained below. Please, refer to the function reference on `mysqlnd_qc_is_select' (http://www.php.net/mysqlnd_qc_is_select) for a description of using a callback and, *Note `mysqlnd_qc_set_cache_condition': apis-php-function.mysqlnd-qc-set-cache-condition. on how to set rules for automatic caching. A SQL hint is a SQL standards compliant comment. As a SQL comment it is ignored by the database. A statement is considered eligible for caching if it either begins with the SQL hint enabling caching or it is a `SELECT' statement. An individual query which shall be cached must begin with the SQL hint `/*qc=on*/'. It is recommended to use the PHP constant `*Note MYSQLND_QC_ENABLE_SWITCH: apis-php-mysqlnd-qc.constants.' instead of using the string value. * not eligible for caching and not cached: `INSERT INTO test(id) VALUES (1)' * not eligible for caching and not cached: `SHOW ENGINES' * eligible for caching but uncached: `SELECT id FROM test' * eligible for caching and cached: `/*qc=on*/SELECT id FROM test' The examples `SELECT' statement string is prefixed with the `*Note MYSQLND_QC_ENABLE_SWITCH: apis-php-mysqlnd-qc.constants.' SQL hint to enable caching of the statement. The SQL hint must be given at the very beginning of the statement string to enable caching. mysqlnd_qc.enable_qc=1 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2)"); /* Will be cached because of the SQL hint */ $start = microtime(true); $res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 1"); var_dump($res->fetch_assoc()); $res->free(); printf("Total time uncached query: %.6fs\n", microtime(true) - $start); /* Cache hit */ $start = microtime(true); $res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 1"); var_dump($res->fetch_assoc()); $res->free(); printf("Total time cached query: %.6fs\n", microtime(true) - $start); ?> The above examples will output something similar to: array(1) { ["id"]=> string(1) "1" } Total time uncached query: 0.000740s array(1) { ["id"]=> string(1) "1" } Total time cached query: 0.000098s If nothing else is configured, as it is the case in the quickstart example, the plugin will use the built-in `default' storage handler. The `default' storage handler uses process memory to hold a cache entry. Depending on the PHP deployment model, a PHP process may serve one or more web requests. Please, consult the web server manual for details. Details make no difference for the examples given in the quickstart. The query cache plugin will cache all queries regardless if the query string begins with the SQL hint which enables caching or not, if the PHP configuration directive `*Note mysqlnd_qc.cache_by_default: apis-php-mysqlnd-qc.configuration.' is set to `1'. The setting `*Note mysqlnd_qc.cache_by_default: apis-php-mysqlnd-qc.configuration.' is evaluated by the core of the query cache plugins. Neither the built-in nor user-defined storage handler can overrule the setting. The SQL hint `/*qc=off*/' can be used to disable caching of individual queries if `*Note mysqlnd_qc.cache_by_default = 1: apis-php-mysqlnd-qc.configuration.' It is recommended to use the PHP constant `*Note MYSQLND_QC_DISABLE_SWITCH: apis-php-mysqlnd-qc.constants.' instead of using the string value. mysqlnd_qc.enable_qc=1 mysqlnd_qc.cache_by_default=1 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2)"); /* Will be cached although no SQL hint is present because of mysqlnd_qc.cache_by_default = 1*/ $res = $mysqli->query("SELECT id FROM test WHERE id = 1"); var_dump($res->fetch_assoc()); $res->free(); $mysqli->query("DELETE FROM test WHERE id = 1"); /* Cache hit - no automatic invalidation and still valid! */ $res = $mysqli->query("SELECT id FROM test WHERE id = 1"); var_dump($res->fetch_assoc()); $res->free(); /* Cache miss - query must not be cached because of the SQL hint */ $res = $mysqli->query("/*" . MYSQLND_QC_DISABLE_SWITCH . "*/SELECT id FROM test WHERE id = 1"); var_dump($res->fetch_assoc()); $res->free(); ?> The above examples will output: array(1) { ["id"]=> string(1) "1" } array(1) { ["id"]=> string(1) "1" } NULL PECL/mysqlnd_qc forbids caching of statements for which at least one column from the statements result set shows no table name in its meta data by default. This is usually the case for columns originating from SQL functions such as `NOW()' or `LAST_INSERT_ID()'. The policy aims to prevent pitfalls if caching by default is used. mysqlnd_qc.enable_qc=1 mysqlnd_qc.cache_by_default=1 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1)"); for ($i = 0; $i < 3; $i++) { $start = microtime(true); /* Note: statement will not be cached because of NOW() use */ $res = $mysqli->query("SELECT id, NOW() AS _time FROM test"); $row = $res->fetch_assoc(); /* dump results */ var_dump($row); printf("Total time: %.6fs\n", microtime(true) - $start); /* pause one second */ sleep(1); } ?> The above examples will output something similar to: array(2) { ["id"]=> string(1) "1" ["_time"]=> string(19) "2012-01-11 15:43:10" } Total time: 0.000540s array(2) { ["id"]=> string(1) "1" ["_time"]=> string(19) "2012-01-11 15:43:11" } Total time: 0.000555s array(2) { ["id"]=> string(1) "1" ["_time"]=> string(19) "2012-01-11 15:43:12" } Total time: 0.000549s It is possible to enable caching for all statements including those which has columns in their result set for which MySQL reports no table, such as the statement from the example. Set `mysqlnd_qc.cache_no_table = 1' to enable caching of such statements. Please, note the difference in the measured times for the above and below examples. mysqlnd_qc.enable_qc=1 mysqlnd_qc.cache_by_default=1 mysqlnd_qc.cache_no_table=1 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1)"); for ($i = 0; $i < 3; $i++) { $start = microtime(true); /* Note: statement will not be cached because of NOW() use */ $res = $mysqli->query("SELECT id, NOW() AS _time FROM test"); $row = $res->fetch_assoc(); /* dump results */ var_dump($row); printf("Total time: %.6fs\n", microtime(true) - $start); /* pause one second */ sleep(1); } ?> The above examples will output something similar to: array(2) { ["id"]=> string(1) "1" ["_time"]=> string(19) "2012-01-11 15:47:45" } Total time: 0.000546s array(2) { ["id"]=> string(1) "1" ["_time"]=> string(19) "2012-01-11 15:47:45" } Total time: 0.000187s array(2) { ["id"]=> string(1) "1" ["_time"]=> string(19) "2012-01-11 15:47:45" } Total time: 0.000167s *Note*: Although `mysqlnd_qc.cache_no_table = 1' has been created for use with `*Note mysqlnd_qc.cache_by_default = 1: apis-php-mysqlnd-qc.configuration.' it is bound it. The plugin will evaluate the `mysqlnd_qc.cache_no_table' whenever a query is to be cached, no matter whether caching has been enabled using a SQL hint or any other measure.  File: manual.info, Node: apis-php-mysqlnd-qc.per-query-ttl, Next: apis-php-mysqlnd-qc.pattern-based-caching, Prev: apis-php-mysqlnd-qc.quickstart.caching, Up: apis-php-mysqlnd-qc.quickstart 21.9.3.8 Setting the TTL ........................ Copyright 1997-2012 the PHP Documentation Group. The default invalidation strategy of the query cache plugin is Time to Live (`TTL'). The built-in storage handlers will use the default `TTL' defined by the PHP configuration value `*Note mysqlnd_qc.ttl: apis-php-mysqlnd-qc.configuration.' unless the query string contains a hint for setting a different `TTL'. The `TTL' is specified in seconds. By default cache entries expire after `30' seconds The example sets `mysqlnd_qc.ttl=3' to cache statements for three seconds by default. Every second it updates a database table record to hold the current time and executes a `SELECT' statement to fetch the record from the database. The `SELECT' statement is cached for three seconds because it is prefixed with the SQL hint enabling caching. The output verifies that the query results are taken from the cache for the duration of three seconds before they are refreshed. mysqlnd_qc.enable_qc=1 mysqlnd_qc.ttl=3 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id VARCHAR(255))"); for ($i = 0; $i < 7; $i++) { /* update DB row */ if (!$mysqli->query("DELETE FROM test") || !$mysqli->query("INSERT INTO test(id) VALUES (NOW())")) /* Of course, a real-life script should do better error handling */ die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); /* select latest row but cache results */ $query = "/*" . MYSQLND_QC_ENABLE_SWITCH . "*/"; $query .= "SELECT id AS _time FROM test"; if (!($res = $mysqli->query($query)) || !($row = $res->fetch_assoc())) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } $res->free(); printf("Wall time %s - DB row time %s\n", date("H:i:s"), $row['_time']); /* pause one second */ sleep(1); } ?> The above examples will output something similar to: Wall time 14:55:59 - DB row time 2012-01-11 14:55:59 Wall time 14:56:00 - DB row time 2012-01-11 14:55:59 Wall time 14:56:01 - DB row time 2012-01-11 14:55:59 Wall time 14:56:02 - DB row time 2012-01-11 14:56:02 Wall time 14:56:03 - DB row time 2012-01-11 14:56:02 Wall time 14:56:04 - DB row time 2012-01-11 14:56:02 Wall time 14:56:05 - DB row time 2012-01-11 14:56:05 As can be seen from the example, any `TTL' based cache can serve stale data. Cache entries are not automatically invalidated, if underlying data changes. Applications using the default `TTL' invalidation strategy must be able to work correctly with stale data. A user-defined cache storage handler can implement any invalidation strategy to work around this limitation. The default `TTL' can be overruled using the SQL hint `/*qc_tt=seconds*/'. The SQL hint must be appear immediately after the SQL hint which enables caching. It is recommended to use the PHP constant `*Note MYSQLND_QC_TTL_SWITCH: apis-php-mysqlnd-qc.constants.' instead of using the string value. query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2)"); printf("Default TTL\t: %d seconds\n", ini_get("mysqlnd_qc.ttl")); /* Will be cached for 2 seconds */ $sql = sprintf("/*%s*//*%s%d*/SELECT id FROM test WHERE id = 1", MYSQLND_QC_ENABLE_SWITCH, MYSQLND_QC_TTL_SWITCH, 2); $res = $mysqli->query($sql); var_dump($res->fetch_assoc()); $res->free(); $mysqli->query("DELETE FROM test WHERE id = 1"); sleep(1); /* Cache hit - no automatic invalidation and still valid! */ $res = $mysqli->query($sql); var_dump($res->fetch_assoc()); $res->free(); sleep(2); /* Cache miss - cache entry has expired */ $res = $mysqli->query($sql); var_dump($res->fetch_assoc()); $res->free(); printf("Script runtime\t: %d seconds\n", microtime(true) - $start); ?> The above examples will output something similar to: Default TTL : 30 seconds array(1) { ["id"]=> string(1) "1" } array(1) { ["id"]=> string(1) "1" } NULL Script runtime : 3 seconds  File: manual.info, Node: apis-php-mysqlnd-qc.pattern-based-caching, Next: apis-php-mysqlnd-qc.slam-defense, Prev: apis-php-mysqlnd-qc.per-query-ttl, Up: apis-php-mysqlnd-qc.quickstart 21.9.3.9 Pattern based caching .............................. Copyright 1997-2012 the PHP Documentation Group. An application has three options for telling PECL/mysqlnd_qc whether a particular statement shall be used. The most basic approach is to cache all statements by setting `*Note mysqlnd_qc.cache_by_default = 1: apis-php-mysqlnd-qc.configuration.'. This approach is often of little practical value. But it enables users to make a quick estimation about the maximum performance gains from caching. An application designed to use a cache may be able to prefix selected statements with the appropriate SQL hints. However, altering an applications source code may not always be possible or desired, for example, to avoid problems with software updates. Therefore, PECL/mysqlnd_qc allows setting a callback which decides if a query is to be cached. The callback is installed with the *Note `mysqlnd_qc_set_is_select': apis-php-function.mysqlnd-qc-set-is-select. function. The callback is given the statement string of every statement inspected by the plugin. Then, the callback can decide whether to cache the function. The callback is supposed to return FALSE if the statement shall not be cached. A return value of TRUE makes the plugin try to add the statement into the cache. The cache entry will be given the default TTL (`*Note mysqlnd_qc.ttl: apis-php-mysqlnd-qc.configuration.'). If the callback returns a numerical value it is used as the TTL instead of the global default. mysqlnd_qc.enable_qc=1 mysqlnd_qc.collect_statistics=1 true, /* 3 - use TTL = 3 seconds */ "@SELECT\s+.*\s+FROM\s+news@ismU" => 3 ); /* check if query does match pattern */ foreach ($patterns as $pattern => $ttl) { if (preg_match($pattern, $query)) { printf("is_select(%45s): cache\n", $query); return $ttl; } } printf("is_select(%45s): do not cache\n", $query); return false; } /* install callback */ mysqlnd_qc_set_is_select("is_select"); /* Connect, create and populate test table */ $mysqli = new mysqli("host", "user", "password", "schema", "port", "socket"); $mysqli->query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)"); /* cache put */ $mysqli->query("SELECT id FROM test WHERE id = 1"); /* cache hit */ $mysqli->query("SELECT id FROM test WHERE id = 1"); /* cache put */ $mysqli->query("SELECT * FROM test"); $stats = mysqlnd_qc_get_core_stats(); printf("Cache put: %d\n", $stats['cache_put']); printf("Cache hit: %d\n", $stats['cache_hit']); ?> The above examples will output something similar to: is_select( DROP TABLE IF EXISTS test): do not cache is_select( CREATE TABLE test(id INT)): do not cache is_select( INSERT INTO test(id) VALUES (1), (2), (3)): do not cache is_select( SELECT id FROM test WHERE id = 1): cache is_select( SELECT id FROM test WHERE id = 1): cache is_select( SELECT * FROM test): cache Cache put: 2 Cache hit: 1 The examples callback tests if a statement string matches a pattern. If this is the case, it either returns TRUE to cache the statement using the global default TTL or an alternative TTL. To minimize application changes the callback can put into and registered in an auto prepend file.  File: manual.info, Node: apis-php-mysqlnd-qc.slam-defense, Next: apis-php-mysqlnd-qc.cache-candidates, Prev: apis-php-mysqlnd-qc.pattern-based-caching, Up: apis-php-mysqlnd-qc.quickstart 21.9.3.10 Slam defense ...................... Copyright 1997-2012 the PHP Documentation Group. A badly designed cache can do more harm than good. In the worst case a cache can increase database server load instead of minimizing it. An overload situation can occur if a highly shared cache entry expires (cache stampeding). Cache entries are shared and reused to a different degree depending on the storage used. The default storage handler stores cache entries in process memory. Thus, a cache entry can be reused for the life-span of a process. Other PHP processes cannot access it. If Memcache is used, a cache entry can be shared among multiple PHP processes and even among multiple machines, depending on the set up being used. If a highly shared cache entry stored, for example, in Memcache expires, many clients gets a cache miss. Many client requests can no longer be served from the cache but try to run the underlying query on the database server. Until the cache entry is refreshed, more and more clients contact the database server. In the worst case, a total lost of service is the result. The overload can be avoided using a storage handler which limits the reuse of cache entries to few clients. Then, at the average, its likely that only a limited number of clients will try to refresh a cache entry concurrently. Additionally, the built-in slam defense mechanism can and should be used. If slam defense is activated an expired cache entry is given an extended life time. The first client getting a cache miss for the expired cache entry tries to refresh the cache entry within the extended life time. All other clients requesting the cache entry are temporarily served from the cache although the original `TTL' of the cache entry has expired. The other clients will not experience a cache miss before the extended life time is over. mysqlnd_qc.slam_defense=1 mysqlnd_qc.slam_defense_ttl=1 The slam defense mechanism is enabled with the PHP configuration directive `mysqlnd_qc.slam_defense'. The extended life time of a cache entry is set with `mysqlnd_qc.slam_defense_ttl'. The function *Note `mysqlnd_qc_get_core_stats': apis-php-function.mysqlnd-qc-get-core-stats. returns an array of statistics. The statistics `slam_stale_refresh' and `slam_stale_hit' are incremented if slam defense takes place. It is not possible to give a one-fits-all recommendation on the slam defense configuration. Users are advised to monitor and test their setup and derive settings accordingly.  File: manual.info, Node: apis-php-mysqlnd-qc.cache-candidates, Next: apis-php-mysqlnd-qc.cache-efficiency, Prev: apis-php-mysqlnd-qc.slam-defense, Up: apis-php-mysqlnd-qc.quickstart 21.9.3.11 Finding cache candidates .................................. Copyright 1997-2012 the PHP Documentation Group. A statement should be considered for caching if it is executed often and has a long run time. Cache candidates are found by creating a list of statements sorted by the product of the number of executions multiplied by the statements run time. The function *Note `mysqlnd_qc_get_query_trace_log': apis-php-function.mysqlnd-qc-get-query-trace-log. returns a query log which help with the task. Collecting a query trace is a slow operation. Thus, it is disabled by default. The PHP configuration directive `mysqlnd_qc.collect_query_trace' is used to enable it. The functions trace contains one entry for every query issued before the function is called. mysqlnd_qc.enable_qc=1 mysqlnd_qc.collect_query_trace=1 query("SELECT 1 AS _one FROM DUAL"); $res->free(); } /* dump trace */ var_dump(mysqlnd_qc_get_query_trace_log()); ?> The above examples will output: array(2) { [0]=> array(8) { ["query"]=> string(26) "SELECT 1 AS _one FROM DUAL" ["origin"]=> string(102) "#0 qc.php(7): mysqli->query('SELECT 1 AS _on...') #1 {main}" ["run_time"]=> int(0) ["store_time"]=> int(25) ["eligible_for_caching"]=> bool(false) ["no_table"]=> bool(false) ["was_added"]=> bool(false) ["was_already_in_cache"]=> bool(false) } [1]=> array(8) { ["query"]=> string(26) "SELECT 1 AS _one FROM DUAL" ["origin"]=> string(102) "#0 qc.php(7): mysqli->query('SELECT 1 AS _on...') #1 {main}" ["run_time"]=> int(0) ["store_time"]=> int(8) ["eligible_for_caching"]=> bool(false) ["no_table"]=> bool(false) ["was_added"]=> bool(false) ["was_already_in_cache"]=> bool(false) } } Assorted information is given in the trace. Among them timings and the origin of the query call. The origin property holds a code backtrace to identify the source of the query. The depth of the backtrace can be limited with the PHP configuration directive `mysqlnd_qc.query_trace_bt_depth'. The default depth is `3'. mysqlnd_qc.enable_qc=1 mysqlnd_qc.collect_query_trace=1 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)"); /* dummy queries to fill the query trace */ for ($i = 0; $i < 3; $i++) { $res = $mysqli->query("SELECT id FROM test WHERE id = " . $mysqli->real_escape_string($i)); $res->free(); } $trace = mysqlnd_qc_get_query_trace_log(); $summary = array(); foreach ($trace as $entry) { if (!isset($summary[$entry['query']])) { $summary[$entry['query']] = array( "executions" => 1, "time" => $entry['run_time'] + $entry['store_time'], ); } else { $summary[$entry['query']]['executions']++; $summary[$entry['query']]['time'] += $entry['run_time'] + $entry['store_time']; } } foreach ($summary as $query => $details) { printf("%45s: %5dms (%dx)\n", $query, $details['time'], $details['executions']); } ?> The above examples will output something similar to: DROP TABLE IF EXISTS test: 0ms (1x) CREATE TABLE test(id INT): 0ms (1x) INSERT INTO test(id) VALUES (1), (2), (3): 0ms (1x) SELECT id FROM test WHERE id = 0: 25ms (1x) SELECT id FROM test WHERE id = 1: 10ms (1x) SELECT id FROM test WHERE id = 2: 9ms (1x)  File: manual.info, Node: apis-php-mysqlnd-qc.cache-efficiency, Next: apis-php-mysqlnd-qc.set-user-handlers, Prev: apis-php-mysqlnd-qc.cache-candidates, Up: apis-php-mysqlnd-qc.quickstart 21.9.3.12 Measuring cache efficiency .................................... Copyright 1997-2012 the PHP Documentation Group. PECL/mysqlnd_qc offers three ways to measure the cache efficiency. The function *Note `mysqlnd_qc_get_normalized_query_trace_log': apis-php-function.mysqlnd-qc-get-normalized-query-trace-log. returns statistics aggregated by the normalized query string, *Note `mysqlnd_qc_get_cache_info': apis-php-function.mysqlnd-qc-get-cache-info. gives storage handler specific information which includes a list of all cached items, depending on the storage handler. Additionally, the core of PECL/mysqlnd_qc collects high-level summary statistics aggregated per PHP process. The high-level statistics are returned by *Note `mysqlnd_qc_get_core_stats': apis-php-function.mysqlnd-qc-get-core-stats. The functions *Note `mysqlnd_qc_get_normalized_query_trace_log': apis-php-function.mysqlnd-qc-get-normalized-query-trace-log. and *Note `mysqlnd_qc_get_core_stats': apis-php-function.mysqlnd-qc-get-core-stats. will not collect data unless data collection has been enabled through their corresponding PHP configuration directives. Data collection is disabled by default for performance considerations. It is configurable with the mysqlnd_qc.time_statistics option, which determines if timing information should be collected. Collection of time statistics is enabled by default but only performed if data collection as such has been enabled. Recording time statistics causes extra system calls. In most cases, the benefit of the monitoring outweighs any potential performance penalty of the additional system calls. mysqlnd_qc.enable_qc=1 mysqlnd_qc.collect_statistics=1 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)"); /* dummy queries */ for ($i = 1; $i <= 4; $i++) { $query = sprintf("/*%s*/SELECT id FROM test WHERE id = %d", MYSQLND_QC_ENABLE_SWITCH, $i % 2); $res = $mysqli->query($query); $res->free(); } var_dump(mysqlnd_qc_get_core_stats()); ?> The above examples will output something similar to: array(26) { ["cache_hit"]=> string(1) "2" ["cache_miss"]=> string(1) "2" ["cache_put"]=> string(1) "2" ["query_should_cache"]=> string(1) "4" ["query_should_not_cache"]=> string(1) "3" ["query_not_cached"]=> string(1) "3" ["query_could_cache"]=> string(1) "4" ["query_found_in_cache"]=> string(1) "2" ["query_uncached_other"]=> string(1) "0" ["query_uncached_no_table"]=> string(1) "0" ["query_uncached_no_result"]=> string(1) "0" ["query_uncached_use_result"]=> string(1) "0" ["query_aggr_run_time_cache_hit"]=> string(2) "28" ["query_aggr_run_time_cache_put"]=> string(3) "900" ["query_aggr_run_time_total"]=> string(3) "928" ["query_aggr_store_time_cache_hit"]=> string(2) "14" ["query_aggr_store_time_cache_put"]=> string(2) "40" ["query_aggr_store_time_total"]=> string(2) "54" ["receive_bytes_recorded"]=> string(3) "136" ["receive_bytes_replayed"]=> string(3) "136" ["send_bytes_recorded"]=> string(2) "84" ["send_bytes_replayed"]=> string(2) "84" ["slam_stale_refresh"]=> string(1) "0" ["slam_stale_hit"]=> string(1) "0" ["request_counter"]=> int(1) ["process_hash"]=> int(1929695233) } For a quick overview, call *Note `mysqlnd_qc_get_core_stats': apis-php-function.mysqlnd-qc-get-core-stats. It delivers cache usage, cache timing and traffic related statistics. Values are aggregated on a per process basis for all queries issued by any PHP MySQL API call. Some storage handler, such as the default handler, can report cache entries, statistics related to the entries and meta data for the underlying query through the *Note `mysqlnd_qc_get_cache_info': apis-php-function.mysqlnd-qc-get-cache-info. function. Please note, that the information returned depends on the storage handler. Values are aggregated on a per process basis. mysqlnd_qc.enable_qc=1 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)"); /* dummy queries to fill the query trace */ for ($i = 1; $i <= 4; $i++) { $query = sprintf("/*%s*/SELECT id FROM test WHERE id = %d", MYSQLND_QC_ENABLE_SWITCH, $i % 2); $res = $mysqli->query($query); $res->free(); } var_dump(mysqlnd_qc_get_cache_info()); ?> The above examples will output something similar to: array(4) { ["num_entries"]=> int(2) ["handler"]=> string(7) "default" ["handler_version"]=> string(5) "1.0.0" ["data"]=> array(2) { ["Localhost via UNIX socket 3306 root test|/*qc=on*/SELECT id FROM test WHERE id = 1"]=> array(2) { ["statistics"]=> array(11) { ["rows"]=> int(1) ["stored_size"]=> int(71) ["cache_hits"]=> int(1) ["run_time"]=> int(391) ["store_time"]=> int(27) ["min_run_time"]=> int(16) ["max_run_time"]=> int(16) ["min_store_time"]=> int(8) ["max_store_time"]=> int(8) ["avg_run_time"]=> int(8) ["avg_store_time"]=> int(4) } ["metadata"]=> array(1) { [0]=> array(8) { ["name"]=> string(2) "id" ["orig_name"]=> string(2) "id" ["table"]=> string(4) "test" ["orig_table"]=> string(4) "test" ["db"]=> string(4) "test" ["max_length"]=> int(1) ["length"]=> int(11) ["type"]=> int(3) } } } ["Localhost via UNIX socket 3306 root test|/*qc=on*/SELECT id FROM test WHERE id = 0"]=> array(2) { ["statistics"]=> array(11) { ["rows"]=> int(0) ["stored_size"]=> int(65) ["cache_hits"]=> int(1) ["run_time"]=> int(299) ["store_time"]=> int(13) ["min_run_time"]=> int(11) ["max_run_time"]=> int(11) ["min_store_time"]=> int(6) ["max_store_time"]=> int(6) ["avg_run_time"]=> int(5) ["avg_store_time"]=> int(3) } ["metadata"]=> array(1) { [0]=> array(8) { ["name"]=> string(2) "id" ["orig_name"]=> string(2) "id" ["table"]=> string(4) "test" ["orig_table"]=> string(4) "test" ["db"]=> string(4) "test" ["max_length"]=> int(0) ["length"]=> int(11) ["type"]=> int(3) } } } } } It is possible to further break down the granularity of statistics to the level of the normalized statement string. The normalized statement string is the statements string with all parameters replaced with question marks. For example, the two statements `SELECT id FROM test WHERE id = 0' and `SELECT id FROM test WHERE id = 1' are normalized into `SELECT id FROM test WHERE id = ?'. Their both statistics are aggregated into one entry for `SELECT id FROM test WHERE id = ?'. mysqlnd_qc.enable_qc=1 mysqlnd_qc.collect_normalized_query_trace=1 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)"); /* dummy queries to fill the query trace */ for ($i = 1; $i <= 4; $i++) { $query = sprintf("/*%s*/SELECT id FROM test WHERE id = %d", MYSQLND_QC_ENABLE_SWITCH, $i % 2); $res = $mysqli->query($query); $res->free(); } var_dump(mysqlnd_qc_get_normalized_query_trace_log()); ?> The above examples will output something similar to: array(4) { [0]=> array(9) { ["query"]=> string(25) "DROP TABLE IF EXISTS test" ["occurences"]=> int(0) ["eligible_for_caching"]=> bool(false) ["avg_run_time"]=> int(0) ["min_run_time"]=> int(0) ["max_run_time"]=> int(0) ["avg_store_time"]=> int(0) ["min_store_time"]=> int(0) ["max_store_time"]=> int(0) } [1]=> array(9) { ["query"]=> string(27) "CREATE TABLE test (id INT )" ["occurences"]=> int(0) ["eligible_for_caching"]=> bool(false) ["avg_run_time"]=> int(0) ["min_run_time"]=> int(0) ["max_run_time"]=> int(0) ["avg_store_time"]=> int(0) ["min_store_time"]=> int(0) ["max_store_time"]=> int(0) } [2]=> array(9) { ["query"]=> string(46) "INSERT INTO test (id ) VALUES (? ), (? ), (? )" ["occurences"]=> int(0) ["eligible_for_caching"]=> bool(false) ["avg_run_time"]=> int(0) ["min_run_time"]=> int(0) ["max_run_time"]=> int(0) ["avg_store_time"]=> int(0) ["min_store_time"]=> int(0) ["max_store_time"]=> int(0) } [3]=> array(9) { ["query"]=> string(31) "SELECT id FROM test WHERE id =?" ["occurences"]=> int(4) ["eligible_for_caching"]=> bool(true) ["avg_run_time"]=> int(179) ["min_run_time"]=> int(11) ["max_run_time"]=> int(393) ["avg_store_time"]=> int(12) ["min_store_time"]=> int(7) ["max_store_time"]=> int(25) } } The source distribution of PECL/mysqlnd_qc contains a directory `web/' in which web based monitoring scripts can be found which give an example how to write a cache monitor. Please, follow the instructions given in the source. Since PECL/mysqlnd_qc 1.1.0 it is possible to write statistics into a log file. Please, see ` mysqlnd_qc.collect_statistics_log_file'.  File: manual.info, Node: apis-php-mysqlnd-qc.set-user-handlers, Prev: apis-php-mysqlnd-qc.cache-efficiency, Up: apis-php-mysqlnd-qc.quickstart 21.9.3.13 Beyond TTL: user-defined storage .......................................... Copyright 1997-2012 the PHP Documentation Group. The query cache plugin supports the use of user-defined storage handler. User-defined storage handler can use arbitrarily complex invalidation algorithms and support arbitrary storage media. All user-defined storage handlers have to provide a certain interface. The functions of the user-defined storage handler will be called by the core of the cache plugin. The necessary interface consists of seven public functions. Both procedural and object oriented user-defined storage handler must implement the same set of functions. $data, "row_count" => $row_count, "valid_until" => time() + $ttl, "hits" => 0, "run_time" => $run_time, "store_time" => $store_time, "cached_run_times" => array(), "cached_store_times" => array(), ); return TRUE; } function query_is_select($query) { printf("\t%s('%s'): ", __FUNCTION__, $query); $ret = FALSE; if (stristr($query, "SELECT") !== FALSE) { /* cache for 5 seconds */ $ret = 5; } printf("%s\n", (FALSE === $ret) ? "FALSE" : $ret); return $ret; } function update_query_run_time_stats($key, $run_time, $store_time) { global $__cache; printf("\t%s(%d)\n", __FUNCTION__, func_num_args()); if (isset($__cache[$key])) { $__cache[$key]['hits']++; $__cache[$key]["cached_run_times"][] = $run_time; $__cache[$key]["cached_store_times"][] = $store_time; } } function get_stats($key = NULL) { global $__cache; printf("\t%s(%d)\n", __FUNCTION__, func_num_args()); if ($key && isset($__cache[$key])) { $stats = $__cache[$key]; } else { $stats = array(); foreach ($__cache as $key => $details) { $stats[$key] = array( 'hits' => $details['hits'], 'bytes' => strlen($details['data']), 'uncached_run_time' => $details['run_time'], 'cached_run_time' => (count($details['cached_run_times'])) ? array_sum($details['cached_run_times']) / count($details['cached_run_times']) : 0, ); } } return $stats; } function clear_cache() { global $__cache; printf("\t%s(%d)\n", __FUNCTION__, func_num_args()); $__cache = array(); return TRUE; } /* Install procedural user-defined storage handler */ if (!mysqlnd_qc_set_user_handlers("get_hash", "find_query_in_cache", "return_to_cache", "add_query_to_cache_if_not_exists", "query_is_select", "update_query_run_time_stats", "get_stats", "clear_cache")) { printf("Failed to install user-defined storage handler\n"); } /* Connect, create and populate test table */ $mysqli = new mysqli("host", "user", "password", "schema", "port", "socket"); $mysqli->query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2)"); printf("\nCache put/cache miss\n"); $res = $mysqli->query("SELECT id FROM test WHERE id = 1"); var_dump($res->fetch_assoc()); $res->free(); /* Delete record to verify we get our data from the cache */ $mysqli->query("DELETE FROM test WHERE id = 1"); printf("\nCache hit\n"); $res = $mysqli->query("SELECT id FROM test WHERE id = 1"); var_dump($res->fetch_assoc()); $res->free(); printf("\nDisplay cache statistics\n"); var_dump(mysqlnd_qc_get_cache_info()); printf("\nFlushing cache, cache put/cache miss"); var_dump(mysqlnd_qc_clear_cache()); $res = $mysqli->query("SELECT id FROM test WHERE id = 1"); var_dump($res->fetch_assoc()); $res->free(); ?> The above examples will output something similar to: query_is_select('DROP TABLE IF EXISTS test'): FALSE query_is_select('CREATE TABLE test(id INT)'): FALSE query_is_select('INSERT INTO test(id) VALUES (1), (2)'): FALSE Cache put/cache miss query_is_select('SELECT id FROM test WHERE id = 1'): 5 get_hash(5) find_query_in_cache(1) add_query_to_cache_if_not_exists(6) array(1) { ["id"]=> string(1) "1" } query_is_select('DELETE FROM test WHERE id = 1'): FALSE Cache hit query_is_select('SELECT id FROM test WHERE id = 1'): 5 get_hash(5) find_query_in_cache(1) return_to_cache(1) update_query_run_time_stats(3) array(1) { ["id"]=> string(1) "1" } Display cache statistics get_stats(0) array(4) { ["num_entries"]=> int(1) ["handler"]=> string(4) "user" ["handler_version"]=> string(5) "1.0.0" ["data"]=> array(1) { ["18683c177dc89bb352b29965d112fdaa"]=> array(4) { ["hits"]=> int(1) ["bytes"]=> int(71) ["uncached_run_time"]=> int(398) ["cached_run_time"]=> int(4) } } } Flushing cache, cache put/cache miss clear_cache(0) bool(true) query_is_select('SELECT id FROM test WHERE id = 1'): 5 get_hash(5) find_query_in_cache(1) add_query_to_cache_if_not_exists(6) NULL  File: manual.info, Node: apis-php-mysqlnd-qc.setup, Next: apis-php-mysqlnd-qc.constants, Prev: apis-php-mysqlnd-qc.quickstart, Up: apis-php-book.mysqlnd-qc 21.9.3.14 Installing/Configuring ................................ * Menu: * apis-php-mysqlnd-qc.requirements:: Requirements * apis-php-mysqlnd-qc.installation:: Installation * apis-php-mysqlnd-qc.configuration:: Runtime Configuration Copyright 1997-2012 the PHP Documentation Group.  File: manual.info, Node: apis-php-mysqlnd-qc.requirements, Next: apis-php-mysqlnd-qc.installation, Prev: apis-php-mysqlnd-qc.setup, Up: apis-php-mysqlnd-qc.setup 21.9.3.15 Requirements ...................... Copyright 1997-2012 the PHP Documentation Group. `PHP 5.3.3' or a newer version of `PHP'. PECL/mysqlnd_qc is a mysqlnd plugin. It plugs into the mysqlnd library. To use you this plugin with a PHP MySQL extension, the extension (mysqli, mysql, or See section "apis-php-ref.pdo-mysql" in the online manual) must enable the mysqlnd library. For using the APC (http://www.php.net/ref.apc) storage handler with PECL/mysqlnd_qc 1.0 `APC 3.1.3p1-beta' or newer. PECL/mysqlnd_qc 1.2 has been tested with `APC 3.1.13-beta'. The APC storage handler cannot be used with a shared build. You cannot use the PHP configuration directive `extension' to load the APC and PECL/mysqlnd_qc extensions if PECL/mysqlnd_qc will use APC as a storage handler. For using the APC storage handler, you have to statically compile PHP with APC and PECL/mysqlnd_qc support into PHP. For using `MEMCACHE' storage handler: Use `libmemcache 0.38' or newer. PECL/mysqlnd_qc 1.2 has been tested with `libmemcache 1.4.0'. For using `sqlite' storage handler: Use the sqlite3 (http://www.php.net/book.sqlite3) extension that bundled with PHP.  File: manual.info, Node: apis-php-mysqlnd-qc.installation, Next: apis-php-mysqlnd-qc.configuration, Prev: apis-php-mysqlnd-qc.requirements, Up: apis-php-mysqlnd-qc.setup 21.9.3.16 Installation ...................... Copyright 1997-2012 the PHP Documentation Group. This PECL (http://pecl.php.net/) extension is not bundled with PHP. Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions (http://www.php.net/install.pecl). Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/mysqlnd_qc (http://pecl.php.net/package/mysqlnd_qc) A DLL for this PECL extension is currently unavailable. See also the building on Windows (http://www.php.net/install.windows.building) section.  File: manual.info, Node: apis-php-mysqlnd-qc.configuration, Prev: apis-php-mysqlnd-qc.installation, Up: apis-php-mysqlnd-qc.setup 21.9.3.17 Runtime Configuration ............................... Copyright 1997-2012 the PHP Documentation Group. The behaviour of these functions is affected by settings in `php.ini'. *mysqlnd_qc Configure Options* Name Default Changeable Changelog mysqlnd_qc.enable_qc1 PHP_INI_SYSTEM mysqlnd_qc.ttl 30 PHP_INI_ALL mysqlnd_qc.cache_by_default0 PHP_INI_ALL mysqlnd_qc.cache_no_table0 PHP_INI_ALL mysqlnd_qc.use_request_time0 PHP_INI_ALL mysqlnd_qc.time_statistics1 PHP_INI_ALL mysqlnd_qc.collect_statistics0 PHP_INI_ALL mysqlnd_qc.collect_statistics_log_file/tmp/mysqlnd_qc.statsPHP_INI_SYSTEM mysqlnd_qc.collect_query_trace0 PHP_INI_SYSTEM mysqlnd_qc.query_trace_bt_depth3 PHP_INI_SYSTEM mysqlnd_qc.collect_normalized_query_trace0 PHP_INI_SYSTEM mysqlnd_qc.ignore_sql_comments1 PHP_INI_ALL mysqlnd_qc.slam_defense0 PHP_INI_SYSTEM mysqlnd_qc.slam_defense_ttl30 PHP_INI_SYSTEM mysqlnd_qc.std_data_copy0 PHP_INI_SYSTEM mysqlnd_qc.apc_prefixqc_ PHP_INI_ALL mysqlnd_qc.memc_server127.0.0.1 PHP_INI_ALL mysqlnd_qc.memc_port11211 PHP_INI_ALL mysqlnd_qc.sqlite_data_file:memory: PHP_INI_ALL Here's a short explanation of the configuration directives. 1. mysqlnd_qc.enable_qc integer Enables or disables the plugin. If disabled the extension will not plug into See section "apis-php-mysqli" in the online manual to proxy internal See section "apis-php-mysqli" in the online manual C API calls. 2. mysqlnd_qc.ttl integer Default Time-to-Live (TTL) for cache entries in seconds. 3. mysqlnd_qc.cache_by_default integer Cache all queries regardless if they begin with the SQL hint that enables caching of a query or not. Storage handler cannot overrule the setting. It is evaluated by the core of the plugin. 4. mysqlnd_qc.cache_no_table integer Whether to cache queries with no table name in any of columns meta data of their result set, for example, `SELECT SLEEP(1)', `SELECT NOW()', `SELECT SUBSTRING()'. 5. mysqlnd_qc.use_request_time integer Use PHP global request time to avoid `gettimeofday()' system calls? If using ` APC (http://www.php.net/ref.apc) ' storage handler it should be set to the value of ` apc.use_request_time (http://www.php.net/apc.configuration) ', if not warnings will be generated. 6. mysqlnd_qc.time_statistics integer Collect run time and store time statistics using `gettimeofday()' system call? Data will be collected only if you also set `mysqlnd_qc.collect_statistics = 1', 7. mysqlnd_qc.collect_statistics integer Collect statistics for *Note `mysqlnd_qc_get_core_stats': apis-php-function.mysqlnd-qc-get-core-stats.? Does not influence storage handler statistics! Handler statistics can be an integral part of the handler internal storage format. Therefore, collection of some handler statistics cannot be disabled. 8. mysqlnd_qc.collect_statistics-log-file integer If `mysqlnd_qc.collect_statistics' and `mysqlnd_qc.collect_statistics_log_file' are set, the plugin will dump statistics into the specified log file at every 10th web request during PHP request shutdown. The log file needs to be writable by the web server user. Since 1.1.0. 9. mysqlnd_qc.collect_query_trace integer Collect query back traces? 10. mysqlnd_qc.query_trace_bt_depth integer Maximum depth/level of a query code backtrace. 11. mysqlnd_qc.ignore_sql_comments integer Whether to remove SQL comments from a query string before hashing it to generate a cache key. Disable if you do not want two statemts such as `SELECT /*my_source_ip=123*/ id FROM test' and `SELECT /*my_source_ip=456*/ id FROM test' to refer to the same cache entry. Since 1.1.0. 12. mysqlnd_qc.slam_defense integer Activates handler based slam defense (cache stampeding protection) if available. Supported by `Default' and ` APC (http://www.php.net/ref.apc) ' storage handler 13. mysqlnd_qc.slam_defense_ttl integer `TTL' for stale cache entries which are served while another client updates the entries. Supported by ` APC (http://www.php.net/ref.apc) ' storage handler. 14. mysqlnd_qc.collect_normalized_query_trace integer Collect aggregated normalized query traces? The setting has no effect by default. You compile the extension using the define `NORM_QUERY_TRACE_LOG' to make use of the setting. 15. mysqlnd_qc.std_data_copy integer Default storage handler: copy cached wire data? EXPERIMENTAL - use default setting! 16. mysqlnd_qc.apc_prefix string The ` APC (http://www.php.net/ref.apc) ' storage handler stores data in the `APC' user cache. The setting sets a prefix to be used for cache entries. 17. mysqlnd_qc.memc_server string `MEMCACHE' storage handler: memcache server host. 18. mysqlnd_qc.memc_port integer `MEMCACHE' storage handler: memcached server port. 19. mysqlnd_qc.sqlite_data_file string `sqlite' storage handler: data file. Any setting but `:memory:' may be of little practical value.  File: manual.info, Node: apis-php-mysqlnd-qc.constants, Next: apis-php-ref.mysqlnd-qc, Prev: apis-php-mysqlnd-qc.setup, Up: apis-php-book.mysqlnd-qc 21.9.3.18 Predefined Constants .............................. Copyright 1997-2012 the PHP Documentation Group. The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime. _SQL hint related_ The query cache is controlled by SQL hints. SQL hints are used to enable and disable caching. SQL hints can be used to set the `TTL' of a query. The SQL hints recognized by the query cache can be manually changed at compile time. This makes it possible to use `mysqlnd_qc' in environments in which the default SQL hints are already taken and interpreted by other systems. Therefore it is recommended to use the SQL hint string constants instead of manually adding the default SQL hints to the query string. The above examples will output: MYSQLND_QC_ENABLE_SWITCH: qc=on MYSQLND_QC_DISABLE_SWITCH: qc=off MYSQLND_QC_TTL_SWITCH: qc_ttl= 1. MYSQLND_QC_ENABLE_SWITCH (string) SQL hint used to enable caching of a query. 2. MYSQLND_QC_DISABLE_SWITCH (string) SQL hint used to disable caching of a query if `mysqlnd_qc.cache_by_default = 1'. 3. MYSQLND_QC_TTL_SWITCH (string) SQL hint used to set the TTL of a result set. 4. MYSQLND_QC_SERVER_ID_SWITCH (string) This SQL hint should not be used in general. It is needed by *Note PECL/mysqlnd_ms: apis-php-book.mysqlnd-ms. to group cache entries for one statement but originating from different physical connections. If the hint is used connection settings such as user, hostname and charset are not considered for generating a cache key of a query. Instead the given value and the query string are used as input to the hashing function that generates the key. PECL/mysqlnd_ms may, if instructed, cache results from MySQL Replication slaves. Because it can hold many connections to the slave the cache key shall not be formed from the user, hostname or other settings that may vary for the various slave connections. Instead, PECL/mysqlnd_ms provides an identifier which refers to the group of slave connections that shall be enabled to share cache entries no matter which physical slave connection was to generate the cache entry. Use of this feature outside of PECL/mysqlnd_ms is not recommended. _*Note `mysqlnd_qc_set_cache_condition': apis-php-function.mysqlnd-qc-set-cache-condition. related_ The function *Note `mysqlnd_qc_set_cache_condition': apis-php-function.mysqlnd-qc-set-cache-condition. allows setting conditions for automatic caching of statements which don't begin with the SQL hints necessary to manually enable caching. query("SELECT id, title FROM news"); $pdo_mysql = new PDO("mysql:host=host;dbname=db_example;port=port", "user", "password"); /* not cached: no SQL hint, no pattern match */ $pdo_mysql->query("SELECT id, title FROM latest_news"); /* cached: TTL 1 second, pattern match */ $pdo_mysql->query("SELECT id, title FROM news"); ?> 1. MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN (int) Used as a parameter of *Note `mysqlnd_qc_set_cache_condition': apis-php-function.mysqlnd-qc-set-cache-condition. to set conditions for schema based automatic caching. _Other_ The plugin version number can be obtained using either MYSQLND_QC_VERSION , which is the string representation of the numerical version number, or MYSQLND_QC_VERSION_ID , which is an integer such as 10000. Developers can calculate the version number as follows. Unknown PHP API feature. Version (part) Example Major*10000 1*10000 = 10000 Minor*100 0*100 = 0 Patch 0 = 0 MYSQLND_QC_VERSION_ID 10000 1. MYSQLND_QC_VERSION (string) Plugin version string, for example, `1.0.0-prototype'. 1. MYSQLND_QC_VERSION_ID (int) Plugin version number, for example, 10000.  File: manual.info, Node: apis-php-ref.mysqlnd-qc, Next: apis-php-mysqlnd-qc.changes, Prev: apis-php-mysqlnd-qc.constants, Up: apis-php-book.mysqlnd-qc 21.9.3.19 mysqlnd_qc Functions .............................. * Menu: * apis-php-function.mysqlnd-qc-clear-cache:: `mysqlnd_qc_clear_cache' * apis-php-function.mysqlnd-qc-get-available-handlers:: `mysqlnd_qc_get_available_handlers' * apis-php-function.mysqlnd-qc-get-cache-info:: `mysqlnd_qc_get_cache_info' * apis-php-function.mysqlnd-qc-get-core-stats:: `mysqlnd_qc_get_core_stats' * apis-php-function.mysqlnd-qc-get-normalized-query-trace-log:: `mysqlnd_qc_get_normalized_query_trace_log' * apis-php-function.mysqlnd-qc-get-query-trace-log:: `mysqlnd_qc_get_query_trace_log' * apis-php-function.mysqlnd-qc-set-cache-condition:: `mysqlnd_qc_set_cache_condition' * apis-php-function.mysqlnd-qc-set-is-select:: `mysqlnd_qc_set_is_select' * apis-php-function.mysqlnd-qc-set-storage-handler:: `mysqlnd_qc_set_storage_handler' * apis-php-function.mysqlnd-qc-set-user-handlers:: `mysqlnd_qc_set_user_handlers' Copyright 1997-2012 the PHP Documentation Group.  File: manual.info, Node: apis-php-function.mysqlnd-qc-clear-cache, Next: apis-php-function.mysqlnd-qc-get-available-handlers, Prev: apis-php-ref.mysqlnd-qc, Up: apis-php-ref.mysqlnd-qc 21.9.3.20 `mysqlnd_qc_clear_cache' .................................. Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_qc_clear_cache' Flush all cache contents *Description* bool mysqlnd_qc_clear_cache Flush all cache contents. Flushing the cache is a storage handler responsibility. All built-in storage handler but the `memcache' storage handler support flushing the cache. The `memcache' storage handler cannot flush its cache contents. User-defined storage handler may or may not support the operation. *Parameters* This function has no parameters. *Return Values* Returns TRUE on success or FALSE on failure. A return value of FALSE indicates that flushing all cache contents has failed or the operation is not supported by the active storage handler. Applications must not expect that calling the function will always flush the cache.  File: manual.info, Node: apis-php-function.mysqlnd-qc-get-available-handlers, Next: apis-php-function.mysqlnd-qc-get-cache-info, Prev: apis-php-function.mysqlnd-qc-clear-cache, Up: apis-php-ref.mysqlnd-qc 21.9.3.21 `mysqlnd_qc_get_available_handlers' ............................................. Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_qc_get_available_handlers' Returns a list of available storage handler *Description* array mysqlnd_qc_get_available_handlers Which storage are available depends on the compile time configuration of the query cache plugin. The `default' storage handler is always available. All other storage handler must be enabled explicitly when building the extension. *Parameters* This function has no parameters. *Return Values* Returns an array of available built-in storage handler. For each storage handler the version number and version string is given. *Examples* The above examples will output: array(5) { ["default"]=> array(2) { ["version"]=> string(5) "1.0.0" ["version_number"]=> int(100000) } ["user"]=> array(2) { ["version"]=> string(5) "1.0.0" ["version_number"]=> int(100000) } ["APC"]=> array(2) { ["version"]=> string(5) "1.0.0" ["version_number"]=> int(100000) } ["MEMCACHE"]=> array(2) { ["version"]=> string(5) "1.0.0" ["version_number"]=> int(100000) } ["sqlite"]=> array(2) { ["version"]=> string(5) "1.0.0" ["version_number"]=> int(100000) } } *See Also* *Note Installation: apis-php-mysqlnd-qc.installation. *Note `mysqlnd_qc_set_storage_handler': apis-php-function.mysqlnd-qc-set-storage-handler.  File: manual.info, Node: apis-php-function.mysqlnd-qc-get-cache-info, Next: apis-php-function.mysqlnd-qc-get-core-stats, Prev: apis-php-function.mysqlnd-qc-get-available-handlers, Up: apis-php-ref.mysqlnd-qc 21.9.3.22 `mysqlnd_qc_get_cache_info' ..................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_qc_get_cache_info' Returns information on the current handler, the number of cache entries and cache entries, if available *Description* array mysqlnd_qc_get_cache_info *Parameters* This function has no parameters. *Return Values* Returns information on the current handler, the number of cache entries and cache entries, if available. If and what data will be returned for the cache entries is subject to the active storage handler. Storage handler are free to return any data. Storage handler are recommended to return at least the data provided by the default handler, if technically possible. The scope of the information is the PHP process. Depending on the PHP deployment model a process may serve one or more web requests. Values are aggregated for all cache activities on a per storage handler basis. It is not possible to tell how much queries originating from `mysqli', `PDO_MySQL' or `mysql'.API calls have contributed to the aggregated data values. Use *Note `mysqlnd_qc_get_core_stats': apis-php-function.mysqlnd-qc-get-core-stats. to get timing data aggregated for all storage handlers. Array of cache information 1. handler string The active storage handler. All storage handler. Since 1.0.0. 2. handler_version string The version of the active storage handler. All storage handler. Since 1.0.0. 3. num_entries int The number of cache entries. The value depends on the storage handler in use. The default, APC and SQLite storage handler provide the actual number of cache entries. The MEMCACHE storage handler always returns `0'. MEMCACHE does not support counting the number of cache entries. If a user defined handler is used, the number of entries of the `data' property is reported. Since 1.0.0. 4. data array The version of the active storage handler. Additional storage handler dependent data on the cache entries. Storage handler are requested to provide similar and comparable information. A user defined storage handler is free to return any data. Since 1.0.0. The following information is provided by the default storage handler for the `data' property. The `data' property holds a hash. The hash is indexed by the internal cache entry identifier of the storage handler. The cache entry identifier is human-readable and contains the query string leading to the cache entry. Please, see also the example below. The following data is given for every cache entry. 1. statistics array Statistics of the cache entry. Since 1.0.0. Unknown PHP API feature. PropertyDescription Version `rows' Number of rows of the cached result set. Since 1.0.0. `stored_size'The size of the cached result set in Since 1.0.0. bytes. This is the size of the payload. The value is not suited for calculating the total memory consumption of all cache entries including the administrative overhead of the cache entries. `cache_hits'How often the cached entry has been Since 1.0.0. returned. `run_time'Run time of the statement to which the Since 1.0.0. cache entry belongs. This is the run time of the uncached statement. It is the time between sending the statement to MySQL receiving a reply from MySQL. Run time saved by using the query cache plugin can be calculated like this: `cache_hits * ((run_time - avg_run_time) + (store_time - avg_store_time))'. `store_time'Store time of the statements result set to Since 1.0.0. which the cache entry belongs. This is the time it took to fetch and store the results of the uncached statement. `min_run_time'Minimum run time of the cached statement. Since 1.0.0. How long it took to find the statement in the cache. `min_store_time'Minimum store time of the cached Since 1.0.0. statement. The time taken for fetching the cached result set from the storage medium and decoding `avg_run_time'Average run time of the cached statement. Since 1.0.0. `avg_store_time'Average store time of the cached statement. Since 1.0.0. `max_run_time'Average run time of the cached statement. Since 1.0.0. `max_store_time'Average store time of the cached statement. Since 1.0.0. `valid_until'Timestamp when the cache entry expires. Since 1.1.0. 2. metadata array Metadata of the cache entry. This is the metadata provided by MySQL together with the result set of the statement in question. Different versions of the MySQL server may return different metadata. Unlike with some of the PHP MySQL extensions no attempt is made to hide MySQL server version dependencies and version details from the caller. Please, refer to the MySQL C API documentation that belongs to the MySQL server in use for further details. The metadata list contains one entry for every column. Since 1.0.0. Unknown PHP API feature. PropertyDescription Version `name' The field name. Depending on the MySQL Since 1.0.0. version this may be the fields alias name. `org_name'The field name. Since 1.0.0. `table'The table name. If an alias name was used Since 1.0.0. for the table, this usually holds the alias name. `org_table'The table name. Since 1.0.0. `db' The database/schema name. Since 1.0.0. `max_length'The maximum width of the field. Details Since 1.0.0. may vary by MySQL server version. `length'The width of the field. Details may vary Since 1.0.0. by MySQL server version. `type' The data type of the field. Details may Since 1.0.0. vary by the MySQL server in use. This is the MySQL C API type constants value. It is recommended to use type constants provided by the `mysqli' extension to test for its meaning. You should not test for certain type values by comparing with certain numbers. The APC storage handler returns the same information for the `data' property but no `metadata'. The `metadata' of a cache entry is set to `NULL'. The MEMCACHE storage handler does not fill the `data' property. Statistics are not available on a per cache entry basis with the MEMCACHE storage handler. A user defined storage handler is free to provide any data. *Examples* The example shows the output from the built-in default storage handler. Other storage handler may report different data. query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/SELECT id FROM test"); /* Display cache information */ var_dump(mysqlnd_qc_get_cache_info()); ?> The above examples will output: array(4) { ["num_entries"]=> int(1) ["handler"]=> string(7) "default" ["handler_version"]=> string(5) "1.0.0" ["data"]=> array(1) { ["Localhost via UNIX socket 3306 user schema|/*qc=on*/SELECT id FROM test"]=> array(2) { ["statistics"]=> array(11) { ["rows"]=> int(6) ["stored_size"]=> int(101) ["cache_hits"]=> int(0) ["run_time"]=> int(471) ["store_time"]=> int(27) ["min_run_time"]=> int(0) ["max_run_time"]=> int(0) ["min_store_time"]=> int(0) ["max_store_time"]=> int(0) ["avg_run_time"]=> int(0) ["avg_store_time"]=> int(0) } ["metadata"]=> array(1) { [0]=> array(8) { ["name"]=> string(2) "id" ["orig_name"]=> string(2) "id" ["table"]=> string(4) "test" ["orig_table"]=> string(4) "test" ["db"]=> string(4) "schema" ["max_length"]=> int(1) ["length"]=> int(11) ["type"]=> int(3) } } } } } *See Also* *Note `mysqlnd_qc_get_core_stats': apis-php-function.mysqlnd-qc-get-core-stats.  File: manual.info, Node: apis-php-function.mysqlnd-qc-get-core-stats, Next: apis-php-function.mysqlnd-qc-get-normalized-query-trace-log, Prev: apis-php-function.mysqlnd-qc-get-cache-info, Up: apis-php-ref.mysqlnd-qc 21.9.3.23 `mysqlnd_qc_get_core_stats' ..................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_qc_get_core_stats' Statistics collected by the core of the query cache *Description* array mysqlnd_qc_get_core_stats Returns an array of statistics collected by the core of the cache plugin. The same data fields will be reported for any storage handler because the data is collected by the core. The `PHP' configuration setting `mysqlnd_qc.collect_statistics' controls the collection of statistics. The collection of statistics is disabled by default for performance reasons. Disabling the collection of statistics will also disable the collection of time related statistics. The `PHP' configuration setting `mysqlnd_qc.collect_time_statistics' controls the collection of time related statistics. The scope of the core statistics is the `PHP' process. Depending on your deployment model a `PHP' process may handle one or multiple requests. Statistics are aggregated for all cache entries and all storage handler. It is not possible to tell how much queries originating from `mysqli', `PDO_MySQL' or `mysql' API calls have contributed to the aggregated data values. *Parameters* This function has no parameters. *Return Values* Array of core statistics Unknown PHP API feature. StatisticDescription Version `cache_hit'Statement is considered cacheable and cached data Since 1.0.0. has been reused. Statement is considered cacheable and a cache miss happened but the statement got cached by someone else while we process it and thus we can fetch the result from the refreshed cache. `cache_miss'Statement is considered cacheable... Since 1.0.0. * ... and has been added to the cache * ... but the `PHP' configuration directive setting of `mysqlnd_qc.cache_no_table = 1' has prevented caching. * ... but an unbuffered result set is requested. * ... but a buffered result set was empty. `cache_put'Statement is considered cacheable and has been Since 1.0.0. added to the cache. Take care when calculating derived statistics. Storage handler with a storage life time beyond process scope may report `cache_put = 0' together with `cache_hit > 0', if another process has filled the cache. You may want to use `num_entries' from *Note `mysqlnd_qc_get_cache_info': apis-php-function.mysqlnd-qc-get-cache-info. if the handler supports it ( `default', `APC'). `query_should_cache'Statement is considered cacheable based on query Since 1.0.0. string analysis. The statement may or may not be added to the cache. See also `cache_put'. `query_should_not_cache'Statement is considered not cacheable based on Since 1.0.0. query string analysis. `query_not_cached'Statement is considered not cacheable or it is Since 1.0.0. considered cachable but the storage handler has not returned a hash key for it. `query_could_cache'Statement is considered cacheable... Since 1.0.0. * ... and statement has been run without errors * ... and meta data shows at least one column in the result set The statement may or may not be in the cache already. It may or may not be added to the cache later on. `query_found_in_cache'Statement is considered cacheable and we have Since 1.0.0. found it in the cache but we have not replayed the cached data yet and we have not send the result set to the client yet. This is not considered a cache hit because the client might not fetch the result or the cached data may be faulty. `query_uncached_other'Statement is considered cacheable and it may or may not be in the cache already but either replaying cached data has failed, no result set is available or some other error has happened. `query_uncached_no_table'Statement has not been cached because the result Since 1.0.0. set has at least one column which has no table name in its meta data. An example of such a query is `SELECT SLEEP(1)'. To cache those statements you have to change default value of the PHP configuration directive `mysqlnd_qc.cache_no_table' and set `mysqlnd_qc.cache_no_table = 1'. Often, it is not desired to cache such statements. `query_uncached_use_result'Statement would have been cached if a buffered Since 1.0.0. result set had been used. The situation is also considered as a cache miss and `cache_miss' will be incremented as well. `query_aggr_run_time_cache_hit'Aggregated run time (ms) of all cached queries. Since 1.0.0. Cached queries are those which have incremented `cache_hit'. `query_aggr_run_time_cache_put'Aggregated run time (ms) of all uncached queries Since 1.0.0. that have been put into the cache. See also `cache_put'. `query_aggr_run_time_total'Aggregated run time (ms) of all uncached and Since 1.0.0. cached queries that have been inspected and executed by the query cache. `query_aggr_store_time_cache_hit'Aggregated store time (ms) of all cached queries. Since 1.0.0. Cached queries are those which have incremented `cache_hit'. `query_aggr_store_time_cache_put'Aggregated store time ( `ms') of all uncached Since 1.0.0. queries that have been put into the cache. See also `cache_put'. `query_aggr_store_time_total'Aggregated store time (ms) of all uncached and Since 1.0.0. cached queries that have been inspected and executed by the query cache. `receive_bytes_recorded'Recorded incoming network traffic ( `bytes') send Since 1.0.0. from MySQL to PHP. The traffic may or may not have been added to the cache. The traffic is the total for all queries regardless if cached or not. `receive_bytes_replayed'Network traffic replayed during cache. This is Since 1.0.0. the total amount of incoming traffic saved because of the usage of the query cache plugin. `send_bytes_recorded'Recorded outgoing network traffic ( `bytes') send Since 1.0.0. from MySQL to PHP. The traffic may or may not have been added to the cache. The traffic is the total for all queries regardless if cached or not. `send_bytes_replayed'Network traffic replayed during cache. This is Since 1.0.0. the total amount of outgoing traffic saved because of the usage of the query cache plugin. `slam_stale_refresh'Number of cache misses which triggered serving Since 1.0.0. stale data until the client causing the cache miss has refreshed the cache entry. `slam_stale_hit'Number of cache hits while a stale cache entry Since 1.0.0. gets refreshed. *Examples* query("/*qc=on*/SELECT id FROM test"); /* Cache hit */ $mysqli->query("/*qc=on*/SELECT id FROM test"); /* Display core statistics */ var_dump(mysqlnd_qc_get_core_stats()); ?> The above examples will output: array(26) { ["cache_hit"]=> string(1) "1" ["cache_miss"]=> string(1) "1" ["cache_put"]=> string(1) "1" ["query_should_cache"]=> string(1) "2" ["query_should_not_cache"]=> string(1) "0" ["query_not_cached"]=> string(1) "0" ["query_could_cache"]=> string(1) "2" ["query_found_in_cache"]=> string(1) "1" ["query_uncached_other"]=> string(1) "0" ["query_uncached_no_table"]=> string(1) "0" ["query_uncached_no_result"]=> string(1) "0" ["query_uncached_use_result"]=> string(1) "0" ["query_aggr_run_time_cache_hit"]=> string(1) "4" ["query_aggr_run_time_cache_put"]=> string(3) "395" ["query_aggr_run_time_total"]=> string(3) "399" ["query_aggr_store_time_cache_hit"]=> string(1) "2" ["query_aggr_store_time_cache_put"]=> string(1) "8" ["query_aggr_store_time_total"]=> string(2) "10" ["receive_bytes_recorded"]=> string(2) "65" ["receive_bytes_replayed"]=> string(2) "65" ["send_bytes_recorded"]=> string(2) "29" ["send_bytes_replayed"]=> string(2) "29" ["slam_stale_refresh"]=> string(1) "0" ["slam_stale_hit"]=> string(1) "0" ["request_counter"]=> int(1) ["process_hash"]=> int(3547549858) } *See Also* *Note Runtime configuration: apis-php-mysqlnd-qc.configuration. mysqlnd_qc.collect_statistics mysqlnd_qc.time_statistics *Note `mysqlnd_qc_get_cache_info': apis-php-function.mysqlnd-qc-get-cache-info.  File: manual.info, Node: apis-php-function.mysqlnd-qc-get-normalized-query-trace-log, Next: apis-php-function.mysqlnd-qc-get-query-trace-log, Prev: apis-php-function.mysqlnd-qc-get-core-stats, Up: apis-php-ref.mysqlnd-qc 21.9.3.24 `mysqlnd_qc_get_normalized_query_trace_log' ..................................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_qc_get_normalized_query_trace_log' Returns a normalized query trace log for each query inspected by the query cache *Description* array mysqlnd_qc_get_normalized_query_trace_log Returns a normalized query trace log for each query inspected by the query cache. The collection of the trace log is disabled by default. To collect the trace log you have to set the PHP configuration directive `mysqlnd_qc.collect_normalized_query_trace' to `1' Entries in the trace log are grouped by the normalized query statement. The normalized query statement is the query statement with all statement parameter values being replaced with a question mark. For example, the two statements `SELECT id FROM test WHERE id = 1' and `SELECT id FROM test WHERE id = 2' are normalized as `SELECT id FROM test WHERE id = ?'. Whenever a statement is inspected by the query cache which matches the normalized statement pattern, its statistics are grouped by the normalized statement string. *Parameters* This function has no parameters. *Return Values* An array of query log. Every list entry contains the normalized query stringand further detail information. Unknown PHP API feature. Key Description `query' Normalized statement string. `occurences'How many statements have matched the normalized statement string in addition to the one which has created the log entry. The value is zero if a statement has been normalized, its normalized representation has been added to the log but no further queries inspected by PECL/mysqlnd_qc have the same normalized statement string. `eligible_for_caching'Whether the statement could be cached. An statement eligible for caching has not necessarily been cached. It not possible to tell for sure if or how many cached statement have contributed to the aggregated normalized statement log entry. However, comparing the minimum and average run time one can make an educated guess. `avg_run_time'The average run time of all queries contributing to the query log entry. The run time is the time between sending the query statement to MySQL and receiving an answer from MySQL. `avg_store_time'The average store time of all queries contributing to the query log entry. The store time is the time needed to fetch a statements result set from the server to the client and, storing it on the client. `min_run_time'The minimum run time of all queries contributing to the query log entry. `min_store_time'The minimum store time of all queries contributing to the query log entry. `max_run_time'The maximum run time of all queries contributing to the query log entry. `max_store_time'The maximum store time of all queries contributing to the query log entry. *Examples* mysqlnd_qc.collect_normalized_query_trace=1 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2)"); /* not cached */ $res = $mysqli->query("SELECT id FROM test WHERE id = 1"); var_dump($res->fetch_assoc()); $res->free(); /* cache put */ $res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2"); var_dump($res->fetch_assoc()); $res->free(); /* cache hit */ $res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2"); var_dump($res->fetch_assoc()); $res->free(); var_dump(mysqlnd_qc_get_normalized_query_trace_log()); ?> The above examples will output: array(1) { ["id"]=> string(1) "1" } array(1) { ["id"]=> string(1) "2" } array(1) { ["id"]=> string(1) "2" } array(4) { [0]=> array(9) { ["query"]=> string(25) "DROP TABLE IF EXISTS test" ["occurences"]=> int(0) ["eligible_for_caching"]=> bool(false) ["avg_run_time"]=> int(0) ["min_run_time"]=> int(0) ["max_run_time"]=> int(0) ["avg_store_time"]=> int(0) ["min_store_time"]=> int(0) ["max_store_time"]=> int(0) } [1]=> array(9) { ["query"]=> string(27) "CREATE TABLE test (id INT )" ["occurences"]=> int(0) ["eligible_for_caching"]=> bool(false) ["avg_run_time"]=> int(0) ["min_run_time"]=> int(0) ["max_run_time"]=> int(0) ["avg_store_time"]=> int(0) ["min_store_time"]=> int(0) ["max_store_time"]=> int(0) } [2]=> array(9) { ["query"]=> string(40) "INSERT INTO test (id ) VALUES (? ), (? )" ["occurences"]=> int(0) ["eligible_for_caching"]=> bool(false) ["avg_run_time"]=> int(0) ["min_run_time"]=> int(0) ["max_run_time"]=> int(0) ["avg_store_time"]=> int(0) ["min_store_time"]=> int(0) ["max_store_time"]=> int(0) } [3]=> array(9) { ["query"]=> string(31) "SELECT id FROM test WHERE id =?" ["occurences"]=> int(2) ["eligible_for_caching"]=> bool(true) ["avg_run_time"]=> int(159) ["min_run_time"]=> int(12) ["max_run_time"]=> int(307) ["avg_store_time"]=> int(10) ["min_store_time"]=> int(8) ["max_store_time"]=> int(13) } } *See Also* *Note Runtime configuration: apis-php-mysqlnd-qc.configuration. mysqlnd_qc.collect_normalized_query_trace mysqlnd_qc.time_statistics *Note `mysqlnd_qc_get_query_trace_log': apis-php-function.mysqlnd-qc-get-query-trace-log.  File: manual.info, Node: apis-php-function.mysqlnd-qc-get-query-trace-log, Next: apis-php-function.mysqlnd-qc-set-cache-condition, Prev: apis-php-function.mysqlnd-qc-get-normalized-query-trace-log, Up: apis-php-ref.mysqlnd-qc 21.9.3.25 `mysqlnd_qc_get_query_trace_log' .......................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_qc_get_query_trace_log' Returns a backtrace for each query inspected by the query cache *Description* array mysqlnd_qc_get_query_trace_log Returns a backtrace for each query inspected by the query cache. The collection of the backtrace is disabled by default. To collect the backtrace you have to set the PHP configuration directive `mysqlnd_qc.collect_query_trace' to `1' The maximum depth of the backtrace is limited to the depth set with the PHP configuration directive `mysqlnd_qc.query_trace_bt_depth'. *Parameters* This function has no parameters. *Return Values* An array of query backtrace. Every list entry contains the query string, a backtrace and further detail information. Unknown PHP API feature. Key Description `query' Query string. `origin'Code backtrace. `run_time'Query run time in milliseconds. The collection of all times and the necessary `gettimeofday' system calls can be disabled by setting the PHP configuration directive `mysqlnd_qc.time_statistics' to `0' `store_time'Query result set store time in milliseconds. The collection of all times and the necessary `gettimeofday' system calls can be disabled by setting the PHP configuration directive `mysqlnd_qc.time_statistics' to `0' `eligible_for_caching'TRUE if query is cacheable otherwise FALSE . `no_table'TRUE if the query has generated a result set and at least one column from the result set has no table name set in its metadata. This is usually the case with queries which one probably do not want to cache such as `SELECT SLEEP(1)'. By default any such query will not be added to the cache. See also PHP configuration directive `mysqlnd_qc.cache_no_table'. `was_added'TRUE if the query result has been put into the cache, otherwise FALSE . `was_already_in_cache'TRUE if the query result would have been added to the cache if it was not already in the cache (cache hit). Otherwise FALSE . *Examples* mysqlnd_qc.collect_query_trace=1 query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2)"); /* not cached */ $res = $mysqli->query("SELECT id FROM test WHERE id = 1"); var_dump($res->fetch_assoc()); $res->free(); /* cache put */ $res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2"); var_dump($res->fetch_assoc()); $res->free(); /* cache hit */ $res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2"); var_dump($res->fetch_assoc()); $res->free(); var_dump(mysqlnd_qc_get_query_trace_log()); ?> The above examples will output: array(1) { ["id"]=> string(1) "1" } array(1) { ["id"]=> string(1) "2" } array(1) { ["id"]=> string(1) "2" } array(6) { [0]=> array(8) { ["query"]=> string(25) "DROP TABLE IF EXISTS test" ["origin"]=> string(102) "#0 qc.php(4): mysqli->query('DROP TABLE IF E...') #1 {main}" ["run_time"]=> int(0) ["store_time"]=> int(0) ["eligible_for_caching"]=> bool(false) ["no_table"]=> bool(false) ["was_added"]=> bool(false) ["was_already_in_cache"]=> bool(false) } [1]=> array(8) { ["query"]=> string(25) "CREATE TABLE test(id INT)" ["origin"]=> string(102) "#0 qc.php(5): mysqli->query('CREATE TABLE te...') #1 {main}" ["run_time"]=> int(0) ["store_time"]=> int(0) ["eligible_for_caching"]=> bool(false) ["no_table"]=> bool(false) ["was_added"]=> bool(false) ["was_already_in_cache"]=> bool(false) } [2]=> array(8) { ["query"]=> string(36) "INSERT INTO test(id) VALUES (1), (2)" ["origin"]=> string(102) "#0 qc.php(6): mysqli->query('INSERT INTO tes...') #1 {main}" ["run_time"]=> int(0) ["store_time"]=> int(0) ["eligible_for_caching"]=> bool(false) ["no_table"]=> bool(false) ["was_added"]=> bool(false) ["was_already_in_cache"]=> bool(false) } [3]=> array(8) { ["query"]=> string(32) "SELECT id FROM test WHERE id = 1" ["origin"]=> string(102) "#0 qc.php(9): mysqli->query('SELECT id FROM ...') #1 {main}" ["run_time"]=> int(0) ["store_time"]=> int(25) ["eligible_for_caching"]=> bool(false) ["no_table"]=> bool(false) ["was_added"]=> bool(false) ["was_already_in_cache"]=> bool(false) } [4]=> array(8) { ["query"]=> string(41) "/*qc=on*/SELECT id FROM test WHERE id = 2" ["origin"]=> string(103) "#0 qc.php(14): mysqli->query('/*qc=on*/SELECT...') #1 {main}" ["run_time"]=> int(311) ["store_time"]=> int(13) ["eligible_for_caching"]=> bool(true) ["no_table"]=> bool(false) ["was_added"]=> bool(true) ["was_already_in_cache"]=> bool(false) } [5]=> array(8) { ["query"]=> string(41) "/*qc=on*/SELECT id FROM test WHERE id = 2" ["origin"]=> string(103) "#0 qc.php(19): mysqli->query('/*qc=on*/SELECT...') #1 {main}" ["run_time"]=> int(13) ["store_time"]=> int(8) ["eligible_for_caching"]=> bool(true) ["no_table"]=> bool(false) ["was_added"]=> bool(false) ["was_already_in_cache"]=> bool(true) } } *See Also* *Note Runtime configuration: apis-php-mysqlnd-qc.configuration. mysqlnd_qc.collect_query_trace mysqlnd_qc.query_trace_bt_depth mysqlnd_qc.time_statistics mysqlnd_qc.cache_no_table *Note `mysqlnd_qc_get_normalized_query_trace_log': apis-php-function.mysqlnd-qc-get-normalized-query-trace-log.  File: manual.info, Node: apis-php-function.mysqlnd-qc-set-cache-condition, Next: apis-php-function.mysqlnd-qc-set-is-select, Prev: apis-php-function.mysqlnd-qc-get-query-trace-log, Up: apis-php-ref.mysqlnd-qc 21.9.3.26 `mysqlnd_qc_set_cache_condition' .......................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_qc_set_cache_condition' Set conditions for automatic caching *Description* bool mysqlnd_qc_set_cache_condition int condition_type mixed condition mixed condition_option Sets a condition for automatic caching of statements which do not contain the necessary SQL hints to enable caching of them. *Parameters* 1. condition_type Type of the condition. The only allowed value is MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN . 2. condition Parameter for the condition set with `condition_type'. Parameter type and structure depend on `condition_type' If `condition_type' equals `MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN' `condition' must be a string. The string sets a pattern. Statements are cached if table and database meta data entry of their result sets match the pattern. The pattern is checked for a match with the `db' and `org_table' meta data entries provided by the underlying MySQL client server library. Please, check the MySQL Reference manual for details about the two entries. The `db' and `org_table' values are concatenated with a dot (`.') before matched against `condition'. Pattern matching supports the wildcards `%' and `_'. The wildcard `%' will match one or many arbitrary characters. `_' will match one arbitrary character. The escape symbol is backslash. 3. condition_option Option for `condition'. Type and structure depend on `condition_type'. If `condition_type' equals `MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN' `condition_options' is the TTL to be used. *Examples* query("SELECT id, title FROM news"); $pdo_mysql = new PDO("mysql:host=host;dbname=db_example;port=port", "user", "password"); /* not cached: no SQL hint, no pattern match */ $pdo_mysql->query("SELECT id, title FROM latest_news"); /* cached: TTL 1 second, pattern match */ $pdo_mysql->query("SELECT id, title FROM news"); ?> *Return Values* Returns TRUE on success or FALSE on FAILURE. *See Also* *Note Quickstart: pattern based caching: apis-php-mysqlnd-qc.pattern-based-caching.  File: manual.info, Node: apis-php-function.mysqlnd-qc-set-is-select, Next: apis-php-function.mysqlnd-qc-set-storage-handler, Prev: apis-php-function.mysqlnd-qc-set-cache-condition, Up: apis-php-ref.mysqlnd-qc 21.9.3.27 `mysqlnd_qc_set_is_select' .................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_qc_set_is_select' Installs a callback which decides whether a statement is cached *Description* mixed mysqlnd_qc_set_is_select string callback Installs a callback which decides whether a statement is cached. There are several ways of hinting PELC/mysqlnd_qc to cache a query. By default, PECL/mysqlnd_qc attempts to cache a if caching of all statements is enabled or the query string begins with a certain SQL hint. The plugin internally calls a function named `is_select()' to find out. This internal function can be replaced with a user-defined callback. Then, the user-defined callback is responsible to decide whether the plugin attempts to cache a statement. Because the internal function is replaced with the callback, the callback gains full control. The callback is free to ignore the configuration setting `mysqlnd_qc.cache_by_default' and SQL hints. The callback is invoked for every statement inspected by the plugin. It is given the statements string as a parameter. The callback returns FALSE if the statement shall not be cached. It returns TRUE to make the plugin attempt to cache the statements result set, if any. A so-created cache entry is given the default TTL set with the PHP configuration directive `mysqlnd_qc.ttl'. If a different TTL shall be used, the callback returns a numeric value to be used as the TTL. The internal `is_select' function is part of the internal cache storage handler interface. Thus, a user-defined storage handler offers the same capabilities. *Parameters* This function has no parameters. *Return Values* Returns TRUE on success or FALSE on failure. *Examples* true, /* 3 - use TTL = 3 seconds */ "@SELECT\s+.*\s+FROM\s+news@ismU" => 3 ); /* check if query does match pattern */ foreach ($patterns as $pattern => $ttl) { if (preg_match($pattern, $query)) { printf("is_select(%45s): cache\n", $query); return $ttl; } } printf("is_select(%45s): do not cache\n", $query); return false; } mysqlnd_qc_set_is_select("is_select"); /* Connect, create and populate test table */ $mysqli = new mysqli("host", "user", "password", "schema"); $mysqli->query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)"); /* cache put */ $mysqli->query("SELECT id FROM test WHERE id = 1"); /* cache hit */ $mysqli->query("SELECT id FROM test WHERE id = 1"); /* cache put */ $mysqli->query("SELECT * FROM test"); ?> The above examples will output: is_select( DROP TABLE IF EXISTS test): do not cache is_select( CREATE TABLE test(id INT)): do not cache is_select( INSERT INTO test(id) VALUES (1), (2), (3)): do not cache is_select( SELECT id FROM test WHERE id = 1): cache is_select( SELECT id FROM test WHERE id = 1): cache is_select( SELECT * FROM test): cache *See Also* *Note Runtime configuration: apis-php-mysqlnd-qc.configuration. mysqlnd_qc.ttl mysqlnd_qc.cache_by_default *Note `mysqlnd_qc_set_user_handlers': apis-php-function.mysqlnd-qc-set-user-handlers.  File: manual.info, Node: apis-php-function.mysqlnd-qc-set-storage-handler, Next: apis-php-function.mysqlnd-qc-set-user-handlers, Prev: apis-php-function.mysqlnd-qc-set-is-select, Up: apis-php-ref.mysqlnd-qc 21.9.3.28 `mysqlnd_qc_set_storage_handler' .......................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_qc_set_storage_handler' Change current storage handler *Description* bool mysqlnd_qc_set_storage_handler string handler Sets the storage handler used by the query cache. A list of available storage handler can be obtained from *Note `mysqlnd_qc_get_available_handlers': apis-php-function.mysqlnd-qc-get-available-handlers. Which storage are available depends on the compile time configuration of the query cache plugin. The `default' storage handler is always available. All other storage handler must be enabled explicitly when building the extension. *Parameters* 1. handler Handler can be of type string representing the name of a built-in storage handler or an object of type `mysqlnd_qc_handler_default'. The names of the built-in storage handler are `default', `APC', `MEMCACHE', `sqlite'. *Return Values* Returns TRUE on success or FALSE on failure. If changing the storage handler fails a catchable fatal error will be thrown. The query cache cannot operate if the previous storage handler has been shutdown but no new storage handler has been installed. *Examples* The example shows the output from the built-in default storage handler. Other storage handler may report different data. The above examples will output: bool(true) Default storage handler activated Catchable fatal error: mysqlnd_qc_set_storage_handler(): Unknown handler 'unknown' in (file) on line (line) *See Also* *Note Installation: apis-php-mysqlnd-qc.installation. *Note `mysqlnd_qc_get_available_handlers': apis-php-function.mysqlnd-qc-get-available-handlers.  File: manual.info, Node: apis-php-function.mysqlnd-qc-set-user-handlers, Prev: apis-php-function.mysqlnd-qc-set-storage-handler, Up: apis-php-ref.mysqlnd-qc 21.9.3.29 `mysqlnd_qc_set_user_handlers' ........................................ Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_qc_set_user_handlers' Sets the callback functions for a user-defined procedural storage handler *Description* bool mysqlnd_qc_set_user_handlers string get_hash string find_query_in_cache string return_to_cache string add_query_to_cache_if_not_exists string query_is_select string update_query_run_time_stats string get_stats string clear_cache Sets the callback functions for a user-defined procedural storage handler. *Parameters* 1. get_hash Name of the user function implementing the storage handler `get_hash' functionality. 2. find_query_in_cache Name of the user function implementing the storage handler `find_in_cache' functionality. 3. return_to_cache Name of the user function implementing the storage handler `return_to_cache' functionality. 4. add_query_to_cache_if_not_exists Name of the user function implementing the storage handler `add_query_to_cache_if_not_exists' functionality. 5. query_is_select Name of the user function implementing the storage handler `query_is_select' functionality. 6. update_query_run_time_stats Name of the user function implementing the storage handler `update_query_run_time_stats' functionality. 7. get_stats Name of the user function implementing the storage handler `get_stats' functionality. 8. clear_cache Name of the user function implementing the storage handler `clear_cache' functionality. *Return Values* Returns TRUE on success or FALSE on FAILURE. *See Also* *Note Procedural user-defined storage handler example: apis-php-mysqlnd-qc.set-user-handlers.  File: manual.info, Node: apis-php-mysqlnd-qc.changes, Prev: apis-php-ref.mysqlnd-qc, Up: apis-php-book.mysqlnd-qc 21.9.3.30 Change History ........................ * Menu: * apis-php-mysqlnd-qc.changes-one-two:: PECL/mysqlnd_qc 1.2 series * apis-php-mysqlnd-qc.changes-one-one:: PECL/mysqlnd_qc 1.1 series * apis-php-mysqlnd-qc.changes-one-o:: PECL/mysqlnd_qc 1.0 series Copyright 1997-2012 the PHP Documentation Group. This change history is a high level summary of selected changes that may impact applications and/or break backwards compatibility. See also the `CHANGES' file in the source distribution for a complete list of changes.  File: manual.info, Node: apis-php-mysqlnd-qc.changes-one-two, Next: apis-php-mysqlnd-qc.changes-one-one, Prev: apis-php-mysqlnd-qc.changes, Up: apis-php-mysqlnd-qc.changes 21.9.3.31 PECL/mysqlnd_qc 1.2 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.2.0 - alpha * Release date: 03/2013 * Motto/theme: PHP 5.5 compatibility Feature changes * Update build for PHP 5.5 (Credits: Remi Collet) * APC storage handler update * Fix build for APC 3.1.13-beta and trunk * Introduced MYSQLND_QC_VERSION and MYSQLND_QC_VERSION_ID .  File: manual.info, Node: apis-php-mysqlnd-qc.changes-one-one, Next: apis-php-mysqlnd-qc.changes-one-o, Prev: apis-php-mysqlnd-qc.changes-one-two, Up: apis-php-mysqlnd-qc.changes 21.9.3.32 PECL/mysqlnd_qc 1.1 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.1.0 - stable * Release date: 04/2012 * Motto/theme: PHP 5.4 compatibility, schema pattern based caching and mysqlnd_ms support 1.1.0 - beta * Release date: 04/2012 * Motto/theme: PHP 5.4 compatibility, schema pattern based caching and mysqlnd_ms support 1.1.0 - alpha * Release date: 04/2012 * Motto/theme: PHP 5.4 compatibility, schema pattern based caching and mysqlnd_ms support Feature changes * APC storage handler update * Fix build for APC 3.1.9+ * Note: Use of the APC storage handler is currently not recommended due to stability issues of APC itself. * New PHP configuration directives * ` mysqlnd_qc.collect_statistics_log_file'. Aggregated cache statistics log file written after every 10th request served by the PHP process. * ` mysqlnd_qc.ignore_sql_comments'. Control whether SQL comments are ignored for cache key hash generation. * New constants and SQL hints * MYSQLND_QC_SERVER_ID_SWITCH allows grouping of cache entries from different physical connections. This is needed by PECL/mysqlnd_ms. * MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN to be used with *Note ` mysqlnd_qc_set_cache_condition' (http://www.php.net/ mysqlnd_qc_set_cache_condition): apis-php-function.mysqlnd-qc-set-cache-condition. * New function *Note ` mysqlnd_qc_set_cache_condition' (http://www.php.net/ mysqlnd_qc_set_cache_condition): apis-php-function.mysqlnd-qc-set-cache-condition. for built-in schema pattern based caching. Likely to support a wider range of conditions in the future. * Report `valid_until' timestamp for cache entries of the default handler through *Note `mysqlnd_qc_get_cache_info': apis-php-function.mysqlnd-qc-get-cache-info. * Include charset number for cache entry hashing. This should prevent serving result sets which have the wrong charset. API change: get_hash_key expects new "charsetnr" (int) parameter after "port". * API change: changing is_select() signature from bool is_select() to mixed is_select(). Mixed can be either boolean or array(long ttl, string server_id). This is needed by PECL/mysqlnd_ms. Other * Support acting as a cache backend for *Note PECL/mysqlnd_ms: apis-php-book.mysqlnd-ms. 1.3.0-beta or later to transparently replace MySQL Replication slave reads with cache accesses, if the user explicitly allows. Bug fixes * Fixed Bug #59959 (config.m4, wrong library - 64bit memcached handler builds) (Credits: Remi Collet)  File: manual.info, Node: apis-php-mysqlnd-qc.changes-one-o, Prev: apis-php-mysqlnd-qc.changes-one-one, Up: apis-php-mysqlnd-qc.changes 21.9.3.33 PECL/mysqlnd_qc 1.0 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.0.1-stable * Release date: 12/2010 * Motto/theme: Prepared statement support Added support for Prepared statements and unbuffered queries. 1.0.0-beta * Release date: 07/2010 * Motto/theme: TTL-based cache with various storage options (Memcache, APC, SQLite, user-defined) Initial public release of the transparent TTL-based query result cache. Flexible storage of cached results. Various storage media supported.  File: manual.info, Node: apis-php-book.mysqlnd-uh, Next: apis-php-book.mysqlnd-mux, Prev: apis-php-book.mysqlnd-qc, Up: apis-php 21.9.4 Mysqlnd user handler plugin (`mysqlnd_uh') ------------------------------------------------- * Menu: * apis-php-mysqlnd-uh.security:: Security considerations * apis-php-mysqlnd-uh.docs-note:: Documentation note * apis-php-mysqlnd-uh.name:: On the name * apis-php-mysqlnd-uh.quickstart:: Quickstart and Examples * apis-php-mysqlnd-uh.setup:: Installing/Configuring * apis-php-mysqlnd-uh.constants:: Predefined Constants * apis-php-class.mysqlnduhconnection:: The MysqlndUhConnection class (`MysqlndUhConnection') * apis-php-class.mysqlnduhpreparedstatement:: The MysqlndUhPreparedStatement class (`MysqlndUhPreparedStatement') * apis-php-ref.mysqlnd-uh:: Mysqlnd_uh Functions * apis-php-mysqlnd-uh.changes:: Change History Copyright 1997-2012 the PHP Documentation Group. The mysqlnd user handler plugin (`mysqlnd_uh') allows users to set hooks for most internal calls of the MySQL native driver for PHP (`See section "apis-php-mysqli" in the online manual'). Mysqlnd and its plugins, including PECL/mysqlnd_uh, operate on a layer beneath the PHP MySQL extensions. A mysqlnd plugin can be considered as a proxy between the PHP MySQL extensions and the MySQL server as part of the PHP executable on the client-side. Because the plugins operates on their own layer below the PHP MySQL extensions, they can monitor and change application actions without requiring application changes. If the PHP MySQL extensions (mysqli, mysql, See section "apis-php-ref.pdo-mysql" in the online manual) are compiled to use `mysqlnd' this can be used for: * Monitoring * Queries executed by any of the PHP MySQL extensions * Prepared statements executing by any of the PHP MySQL extensions * Auditing * Detection of database usage * SQL injection protection using black and white lists * Assorted * Load Balancing connections The MySQL native driver for PHP (See section "apis-php-mysqli" in the online manual) features an internal plugin C API. C plugins, such as the mysqlnd user handler plugin, can extend the functionality of See section "apis-php-mysqli" in the online manual. PECL/mysqlnd_uh makes parts of the internal plugin C API available to the PHP user for plugin development with PHP. *Status*: The mysqlnd user handler plugin is in alpha status. Take appropriate care before using it in production environments.  File: manual.info, Node: apis-php-mysqlnd-uh.security, Next: apis-php-mysqlnd-uh.docs-note, Prev: apis-php-book.mysqlnd-uh, Up: apis-php-book.mysqlnd-uh 21.9.4.1 Security considerations ................................ Copyright 1997-2012 the PHP Documentation Group. PECL/mysqlnd_uh gives users access to MySQL user names, MySQL password used by any of the PHP MySQL extensions to connect to MySQL. It allows monitoring of all queries and prepared statements exposing the statement string to the user. Therefore, the extension should be installed with care. The `PHP_INI_SYSTEM' configuration setting `mysqlnd_uh.enable' can be used to prevent users from hooking mysqlnd calls. Code obfuscators and similar technologies are not suitable to prevent monitoring of mysqlnd library activities if PECL/mysqlnd_uh is made available and the user can install a proxy, for example, using auto_prepend_file (http://www.php.net/ini.auto-prepend-file).  File: manual.info, Node: apis-php-mysqlnd-uh.docs-note, Next: apis-php-mysqlnd-uh.name, Prev: apis-php-mysqlnd-uh.security, Up: apis-php-book.mysqlnd-uh 21.9.4.2 Documentation note ........................... Copyright 1997-2012 the PHP Documentation Group. Many of the mysqlnd_uh functions are briefly described because the mysqli extension is a thin abstraction layer on top of the MySQL C API that the `mysqlnd' library provides. Therefore, the corresponding mysqli documentation (along with the MySQL reference manual) can be consulted to receive more information about a particular function.  File: manual.info, Node: apis-php-mysqlnd-uh.name, Next: apis-php-mysqlnd-uh.quickstart, Prev: apis-php-mysqlnd-uh.docs-note, Up: apis-php-book.mysqlnd-uh 21.9.4.3 On the name .................... Copyright 1997-2012 the PHP Documentation Group. The shortcut `mysqlnd_uh' stands for `mysqlnd user handler', and has been the name since early development.  File: manual.info, Node: apis-php-mysqlnd-uh.quickstart, Next: apis-php-mysqlnd-uh.setup, Prev: apis-php-mysqlnd-uh.name, Up: apis-php-book.mysqlnd-uh 21.9.4.4 Quickstart and Examples ................................ * Menu: * apis-php-mysqlnd-uh.quickstart.configuration:: Setup * apis-php-mysqlnd-uh.quickstart.how-it-works:: How it works * apis-php-mysqlnd-uh.quickstart.proxy-installation:: Installing a proxy * apis-php-mysqlnd-uh.quickstart.query-monitoring:: Basic query monitoring Copyright 1997-2012 the PHP Documentation Group. The mysqlnd user handler plugin can be understood as a client-side proxy for all PHP MySQL extensions (mysqli, mysql, See section "apis-php-ref.pdo-mysql" in the online manual), if they are compiled to use the See section "apis-php-mysqli" in the online manual library. The extensions use the `mysqlnd' library internally, at the C level, to communicate with the MySQL server. PECL/mysqlnd_uh allows it to hook many `mysqlnd' calls. Therefore, most activities of the PHP MySQL extensions can be monitored. Because monitoring happens at the level of the library, at a layer below the application, it is possible to monitor applications without changing them. On the C level, the `mysqlnd' library is structured in modules or classes. The extension hooks almost all methods of the `mysqlnd' internal `connection' class and exposes them through the user space class MysqlndUhConnection. Some few methods of the mysqlnd internal `statement' class are made available to the PHP user with the class MysqlndUhPreparedStatement. By subclassing the classes MysqlndUhConnection and MysqlndUhPreparedStatement users get access to `mysqlnd' internal function calls. *Note*: The internal `mysqlnd' function calls are not designed to be exposed to the PHP user. Manipulating their activities may cause PHP to crash or leak memory. Often, this is not considered a bug. Please, keep in mind that you are accessing C library functions through PHP which are expected to take certain actions, which you may not be able to emulate in user space. Therefore, it is strongly recommended to always call the parent method implementation when subclassing MysqlndUhConnection or MysqlndUhPreparedStatement. To prevent the worst case, the extension performs some sanity checks. Please, see also the *Note Mysqlnd_uh Configure Options: apis-php-mysqlnd-uh.configuration.  File: manual.info, Node: apis-php-mysqlnd-uh.quickstart.configuration, Next: apis-php-mysqlnd-uh.quickstart.how-it-works, Prev: apis-php-mysqlnd-uh.quickstart, Up: apis-php-mysqlnd-uh.quickstart 21.9.4.5 Setup .............. Copyright 1997-2012 the PHP Documentation Group. The plugin is implemented as a PHP extension. See the *Note installation instructions: apis-php-mysqlnd-uh.installation. to install the PECL/mysqlnd_uh (http://pecl.php.net/package/mysqlnd_ms) extension. Then, load the extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_uh.enable. The below example shows the default settings of the extension. mysqlnd_uh.enable=1 mysqlnd_uh.report_wrong_types=1  File: manual.info, Node: apis-php-mysqlnd-uh.quickstart.how-it-works, Next: apis-php-mysqlnd-uh.quickstart.proxy-installation, Prev: apis-php-mysqlnd-uh.quickstart.configuration, Up: apis-php-mysqlnd-uh.quickstart 21.9.4.6 How it works ..................... Copyright 1997-2012 the PHP Documentation Group. This describes the background and inner workings of the mysqlnd_uh extension. Two classes are provided by the extension: MysqlndUhConnection and MysqlndUhPreparedStatement. MysqlndUhConnection lets you access almost all methods of the `mysqlnd' internal `connection' class. The latter exposes some selected methods of the `mysqlnd' internal `statement' class. For example, *Note `MysqlndUhConnection::connect': apis-php-mysqlnduhconnection.connect. maps to the `mysqlnd' library C function `mysqlnd_conn__connect'. As a mysqlnd plugin, the PECL/mysqlnd_uh extension replaces `mysqlnd' library C functions with its own functions. Whenever a PHP MySQL extension compiled to use `mysqlnd' calls a mysqlnd function, the functions installed by the plugin are executed instead of the original `mysqlnd' ones. For example, `mysqli_connect' invokes `mysqlnd_conn__connect', so the connect function installed by PECL/mysqlnd_uh will be called. The functions installed by PECL/mysqlnd_uh are the methods of the built-in classes. The built-in PHP classes and their methods do nothing but call their `mysqlnd' C library counterparts, to behave exactly like the original `mysqlnd' function they replace. The code below illustrates in pseudo-code what the extension does. class MysqlndUhConnection { public function connect(($conn, $host, $user, $passwd, $db, $port, $socket, $mysql_flags) { MYSQLND* c_mysqlnd_connection = convert_from_php_to_c($conn); ... return call_c_function(mysqlnd_conn__connect(c_mysqlnd_connection, ...)); } } The build-in classes behave like a transparent proxy. It is possible for you to replace the proxy with your own. This is done by subclassing MysqlndUhConnection or MysqlndUhPreparedStatement to extend the functionality of the proxy, followed by registering a new proxy object. Proxy objects are installed by *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. and *Note `mysqlnd_uh_set_statement_proxy': apis-php-function.mysqlnd-uh-set-statement-proxy. The above example will output: proxy::connect(array ( 0 => NULL, 1 => 'localhost', 2 => 'root', 3 => '', 4 => 'test', 5 => 3306, 6 => NULL, 7 => 131072, )) proxy::connect returns true  File: manual.info, Node: apis-php-mysqlnd-uh.quickstart.proxy-installation, Next: apis-php-mysqlnd-uh.quickstart.query-monitoring, Prev: apis-php-mysqlnd-uh.quickstart.how-it-works, Up: apis-php-mysqlnd-uh.quickstart 21.9.4.7 Installing a proxy ........................... Copyright 1997-2012 the PHP Documentation Group. The extension provides two built-in classes: MysqlndUhConnection and MysqlndUhPreparedStatement. The classes are used for hooking `mysqlnd' library calls. Their methods correspond to `mysqlnd' internal functions. By default they act like a transparent proxy and do nothing but call their `mysqlnd' counterparts. By subclassing the classes you can install your own proxy to monitor `mysqlnd'. See also the *Note How it works: apis-php-mysqlnd-uh.quickstart.how-it-works. guide to learn about the inner workings of this extension. Connection proxies are objects of the type MysqlndUhConnection. Connection proxy objects are installed by *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. If you install the built-in class MysqlndUhConnection as a proxy, nothing happens. It behaves like a transparent proxy. The `PHP_INI_SYSTEM' configuration setting `mysqlnd_uh.enable' controls whether a proxy may be set. If disabled, the extension will throw errors of type `E_WARNING' mysqlnd_uh.enable=0 The above example will output: PHP Warning: MysqlndUhConnection::__construct(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enabled = false. You must not use any of the base classes in %s on line %d PHP Warning: mysqlnd_uh_set_connection_proxy(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false. The proxy has not been installed in %s on line %d To monitor `mysqlnd', you have to write your own proxy object subclassing MysqlndUhConnection. Please, see the function reference for a the list of methods that can be subclassed. Alternatively, you can use reflection to inspect the built-in MysqlndUhConnection. Create a new class `proxy'. Derive it from the built-in class MysqlndUhConnection. Replace the *Note `MysqlndUhConnection::connect': apis-php-mysqlnduhconnection.connect. method. Print out the host parameter value passed to the method. Make sure that you call the parent implementation of the `connect' method. Failing to do so may give unexpected and undesired results, including memory leaks and crashes. Register your proxy and open three connections using the PHP MySQL extensions mysqli, mysql, See section "apis-php-ref.pdo-mysql" in the online manual. If the extensions have been compiled to use the `mysqlnd' library, the `proxy::connect' method will be called three times, once for each connection opened. The above example will output: Connection opened to 'localhost' Connection opened to 'localhost' Connection opened to 'localhost' The use of prepared statement proxies follows the same pattern: create a proxy object of the type MysqlndUhPreparedStatement and install the proxy using *Note `mysqlnd_uh_set_statement_proxy': apis-php-function.mysqlnd-uh-set-statement-proxy. prepare("SELECT 'mysqlnd hacking made easy' AS _msg FROM DUAL"); ?> The above example will output: stmt_proxy::prepare(SELECT 'mysqlnd hacking made easy' AS _msg FROM DUAL)  File: manual.info, Node: apis-php-mysqlnd-uh.quickstart.query-monitoring, Prev: apis-php-mysqlnd-uh.quickstart.proxy-installation, Up: apis-php-mysqlnd-uh.quickstart 21.9.4.8 Basic query monitoring ............................... Copyright 1997-2012 the PHP Documentation Group. Basic monitoring of a query statement is easy with PECL/mysqlnd_uh. Combined with `debug_print_backtrace' (http://www.php.net/debug_print_backtrace) it can become a powerful tool, for example, to find the origin of certain statement. This may be desired when searching for slow queries but also after database refactoring to find code still accessing deprecated databases or tables. The latter may be a complicated matter to do otherwise, especially if the application uses auto-generated queries. query("SELECT 1 AS _one FROM DUAL")->fetchAll(PDO::FETCH_ASSOC)); $mysqli = new mysqli("localhost", "root", "", "test"); $mysqli->prepare("SELECT 1 AS _two FROM DUAL"); ?> The above example will output: #0 conn_proxy->query(Resource id #19, SELECT 1 AS _one FROM DUAL) #1 PDO->query(SELECT 1 AS _one FROM DUAL) called at [example.php:19] array(1) { [0]=> array(1) { ["_one"]=> string(1) "1" } } #0 stmt_proxy->prepare(Resource id #753, SELECT 1 AS _two FROM DUAL) #1 mysqli->prepare(SELECT 1 AS _two FROM DUAL) called at [example.php:22] For basic query monitoring you should install a connection and a prepared statement proxy. The connection proxy should subclass *Note `MysqlndUhConnection::query': apis-php-mysqlnduhconnection.query. All database queries not using native prepared statements will call this method. In the example the `query' function is invoked by a PDO call. By default, `PDO_MySQL' is using prepared statement emulation. All native prepared statements are prepared with the `prepare' method of `mysqlnd' exported through *Note `MysqlndUhPreparedStatement::prepare': apis-php-mysqlnduhpreparedstatement.prepare. Subclass MysqlndUhPreparedStatement and overwrite `prepare' for native prepared statement monitoring.  File: manual.info, Node: apis-php-mysqlnd-uh.setup, Next: apis-php-mysqlnd-uh.constants, Prev: apis-php-mysqlnd-uh.quickstart, Up: apis-php-book.mysqlnd-uh 21.9.4.9 Installing/Configuring ............................... * Menu: * apis-php-mysqlnd-uh.requirements:: Requirements * apis-php-mysqlnd-uh.installation:: Installation * apis-php-mysqlnd-uh.configuration:: Runtime Configuration * apis-php-mysqlnd-uh.resources:: Resource Types Copyright 1997-2012 the PHP Documentation Group.  File: manual.info, Node: apis-php-mysqlnd-uh.requirements, Next: apis-php-mysqlnd-uh.installation, Prev: apis-php-mysqlnd-uh.setup, Up: apis-php-mysqlnd-uh.setup 21.9.4.10 Requirements ...................... Copyright 1997-2012 the PHP Documentation Group. `PHP 5.3.3' or later. It is recommended to use `PHP 5.4.0' or later to get access to the latest mysqlnd features. The `mysqlnd_uh' user handler plugin supports all PHP applications and all available PHP MySQL extensions (mysqli, mysql, See section "apis-php-ref.pdo-mysql" in the online manual). The PHP MySQL extension must be configured to use See section "apis-php-mysqli" in the online manual in order to be able to use the `mysqlnd_uh' plugin for See section "apis-php-mysqli" in the online manual. The alpha versions makes use of some mysqli features. You must enable mysqli to compile the plugin. This requirement may be removed in the future. Note, that this requirement does not restrict you to use the plugin only with `mysqli'. You can use the plugin to monitor `mysql', `mysqli' and `PDO_MYSQL'.  File: manual.info, Node: apis-php-mysqlnd-uh.installation, Next: apis-php-mysqlnd-uh.configuration, Prev: apis-php-mysqlnd-uh.requirements, Up: apis-php-mysqlnd-uh.setup 21.9.4.11 Installation ...................... Copyright 1997-2012 the PHP Documentation Group. Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions (http://www.php.net/install.pecl). Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/mysqlnd-uh (http://pecl.php.net/package/mysqlnd-uh) PECL/mysqlnd_uh is currently not available on Windows. The source code of the extension makes use of `C99' constructs not allowed with PHP Windows builds.  File: manual.info, Node: apis-php-mysqlnd-uh.configuration, Next: apis-php-mysqlnd-uh.resources, Prev: apis-php-mysqlnd-uh.installation, Up: apis-php-mysqlnd-uh.setup 21.9.4.12 Runtime Configuration ............................... Copyright 1997-2012 the PHP Documentation Group. The behaviour of these functions is affected by settings in `php.ini'. *Mysqlnd_uh Configure Options* Name Default Changeable Changelog mysqlnd_uh.enable 1 PHP_INI_SYSTEM mysqlnd_uh.report_wrong_types1 PHP_INI_ALL Here's a short explanation of the configuration directives. 1. mysqlnd_uh.enable integer Enables or disables the plugin. If set to disabled, the extension will not allow users to plug into See section "apis-php-mysqli" in the online manual to hook See section "apis-php-mysqli" in the online manual calls. 2. mysqlnd_uh.report_wrong_types integer Whether to report wrong return value types of user hooks as E_WARNING level errors. This is recommended for detecting errors.  File: manual.info, Node: apis-php-mysqlnd-uh.resources, Prev: apis-php-mysqlnd-uh.configuration, Up: apis-php-mysqlnd-uh.setup 21.9.4.13 Resource Types ........................ Copyright 1997-2012 the PHP Documentation Group. This extension has no resource types defined.  File: manual.info, Node: apis-php-mysqlnd-uh.constants, Next: apis-php-class.mysqlnduhconnection, Prev: apis-php-mysqlnd-uh.setup, Up: apis-php-book.mysqlnd-uh 21.9.4.14 Predefined Constants .............................. Copyright 1997-2012 the PHP Documentation Group. The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime. Most of the constants refer to details of the MySQL Client Server Protocol. Please, refer to the MySQL reference manual to learn about their meaning. To avoid content duplication, only short descriptions are given. _*Note `MysqlndUhConnection::simpleCommand': apis-php-mysqlnduhconnection.simplecommand. related_ The following constants can be used to detect what command is to be send through *Note `MysqlndUhConnection::simpleCommand': apis-php-mysqlnduhconnection.simplecommand. 1. MYSQLND_UH_MYSQLND_COM_SLEEP (integer) MySQL Client Server protocol command: COM_SLEEP. 2. MYSQLND_UH_MYSQLND_COM_QUIT (integer) MySQL Client Server protocol command: COM_QUIT. 3. MYSQLND_UH_MYSQLND_COM_INIT_DB (integer) MySQL Client Server protocol command: COM_INIT_DB. 4. MYSQLND_UH_MYSQLND_COM_QUERY (integer) MySQL Client Server protocol command: COM_QUERY. 5. MYSQLND_UH_MYSQLND_COM_FIELD_LIST (integer) MySQL Client Server protocol command: COM_FIELD_LIST. 6. MYSQLND_UH_MYSQLND_COM_CREATE_DB (integer) MySQL Client Server protocol command: COM_CREATE_DB. 7. MYSQLND_UH_MYSQLND_COM_DROP_DB (integer) MySQL Client Server protocol command: COM_DROP_DB. 8. MYSQLND_UH_MYSQLND_COM_REFRESH (integer) MySQL Client Server protocol command: COM_REFRESH. 9. MYSQLND_UH_MYSQLND_COM_SHUTDOWN (integer) MySQL Client Server protocol command: COM_SHUTDOWN. 10. MYSQLND_UH_MYSQLND_COM_STATISTICS (integer) MySQL Client Server protocol command: COM_STATISTICS. 11. MYSQLND_UH_MYSQLND_COM_PROCESS_INFO (integer) MySQL Client Server protocol command: COM_PROCESS_INFO. 12. MYSQLND_UH_MYSQLND_COM_CONNECT (integer) MySQL Client Server protocol command: COM_CONNECT. 13. MYSQLND_UH_MYSQLND_COM_PROCESS_KILL (integer) MySQL Client Server protocol command: COM_PROCESS_KILL. 14. MYSQLND_UH_MYSQLND_COM_DEBUG (integer) MySQL Client Server protocol command: COM_DEBUG. 15. MYSQLND_UH_MYSQLND_COM_PING (integer) MySQL Client Server protocol command: COM_PING. 16. MYSQLND_UH_MYSQLND_COM_TIME (integer) MySQL Client Server protocol command: COM_TIME. 17. MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT (integer) MySQL Client Server protocol command: COM_DELAYED_INSERT. 18. MYSQLND_UH_MYSQLND_COM_CHANGE_USER (integer) MySQL Client Server protocol command: COM_CHANGE_USER. 19. MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP (integer) MySQL Client Server protocol command: COM_BINLOG_DUMP. 20. MYSQLND_UH_MYSQLND_COM_TABLE_DUMP (integer) MySQL Client Server protocol command: COM_TABLE_DUMP. 21. MYSQLND_UH_MYSQLND_COM_CONNECT_OUT (integer) MySQL Client Server protocol command: COM_CONNECT_OUT. 22. MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED (integer) MySQL Client Server protocol command: COM_REGISTER_SLAVED. 23. MYSQLND_UH_MYSQLND_COM_STMT_PREPARE (integer) MySQL Client Server protocol command: COM_STMT_PREPARE. 24. MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE (integer) MySQL Client Server protocol command: COM_STMT_EXECUTE. 25. MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA (integer) MySQL Client Server protocol command: COM_STMT_SEND_LONG_DATA. 26. MYSQLND_UH_MYSQLND_COM_STMT_CLOSE (integer) MySQL Client Server protocol command: COM_STMT_CLOSE. 27. MYSQLND_UH_MYSQLND_COM_STMT_RESET (integer) MySQL Client Server protocol command: COM_STMT_RESET. 28. MYSQLND_UH_MYSQLND_COM_SET_OPTION (integer) MySQL Client Server protocol command: COM_SET_OPTION. 29. MYSQLND_UH_MYSQLND_COM_STMT_FETCH (integer) MySQL Client Server protocol command: COM_STMT_FETCH. 30. MYSQLND_UH_MYSQLND_COM_DAEMON (integer) MySQL Client Server protocol command: COM_DAEMON. 31. MYSQLND_UH_MYSQLND_COM_END (integer) MySQL Client Server protocol command: COM_END. The following constants can be used to analyze the `ok_packet' argument of *Note `MysqlndUhConnection::simpleCommand': apis-php-mysqlnduhconnection.simplecommand. 1. MYSQLND_UH_MYSQLND_PROT_GREET_PACKET (integer) MySQL Client Server protocol packet: greeting. 2. MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET (integer) MySQL Client Server protocol packet: authentication. 3. MYSQLND_UH_MYSQLND_PROT_OK_PACKET (integer) MySQL Client Server protocol packet: OK. 4. MYSQLND_UH_MYSQLND_PROT_EOF_PACKET (integer) MySQL Client Server protocol packet: EOF. 5. MYSQLND_UH_MYSQLND_PROT_CMD_PACKET (integer) MySQL Client Server protocol packet: command. 6. MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET (integer) MySQL Client Server protocol packet: result set header. 7. MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET (integer) MySQL Client Server protocol packet: resultset field. 8. MYSQLND_UH_MYSQLND_PROT_ROW_PACKET (integer) MySQL Client Server protocol packet: row. 9. MYSQLND_UH_MYSQLND_PROT_STATS_PACKET (integer) MySQL Client Server protocol packet: stats. 10. MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET (integer) MySQL Client Server protocol packet: prepare response. 11. MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET (integer) MySQL Client Server protocol packet: change user response. 12. MYSQLND_UH_MYSQLND_PROT_LAST (integer) No practical meaning. Last entry marker of internal C data structure list. _*Note `MysqlndUhConnection::close': apis-php-mysqlnduhconnection.close. related_ The following constants can be used to detect why a connection has been closed through `MysqlndUhConnection::close()'. 1. MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT (integer) User has called mysqlnd to close the connection. 2. MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT (integer) Implicitly closed, for example, during garbage connection. 3. MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTED (integer) Connection error. 4. MYSQLND_UH_MYSQLND_CLOSE_LAST (integer) No practical meaning. Last entry marker of internal C data structure list. _MysqlndUhConnection::setServerOption() related_ The following constants can be used to detect which option is set through `MysqlndUhConnection::setServerOption()'. 1. MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON (integer) Option: enables multi statement support. 2. MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_OFF (integer) Option: disables multi statement support. _*Note `MysqlndUhConnection::setClientOption': apis-php-mysqlnduhconnection.setclientoption. related_ The following constants can be used to detect which option is set through *Note `MysqlndUhConnection::setClientOption': apis-php-mysqlnduhconnection.setclientoption. 1. MYSQLND_UH_MYSQLND_OPTION_OPT_CONNECT_TIMEOUT (integer) Option: connection timeout. 2. MYSQLND_UH_MYSQLND_OPTION_OPT_COMPRESS (integer) Option: whether the MySQL compressed protocol is to be used. 3. MYSQLND_UH_MYSQLND_OPTION_OPT_NAMED_PIPE (integer) Option: named pipe to use for connection (Windows). 4. MYSQLND_UH_MYSQLND_OPTION_INIT_COMMAND (integer) Option: init command to execute upon connect. 5. MYSQLND_UH_MYSQLND_READ_DEFAULT_FILE (integer) Option: MySQL server default file to read upon connect. 6. MYSQLND_UH_MYSQLND_READ_DEFAULT_GROUP (integer) Option: MySQL server default file group to read upon connect. 7. MYSQLND_UH_MYSQLND_SET_CHARSET_DIR (integer) Option: charset description files directory. 8. MYSQLND_UH_MYSQLND_SET_CHARSET_NAME (integer) Option: charset name. 9. MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE (integer) Option: Whether to allow `LOAD DATA LOCAL INFILE' use. 10. MYSQLND_UH_MYSQLND_OPT_PROTOCOL (integer) Option: supported protocol version. 11. MYSQLND_UH_MYSQLND_SHARED_MEMORY_BASE_NAME (integer) Option: shared memory base name for shared memory connections. 12. MYSQLND_UH_MYSQLND_OPT_READ_TIMEOUT (integer) Option: connection read timeout. 13. MYSQLND_UH_MYSQLND_OPT_WRITE_TIMEOUT (integer) Option: connection write timeout. 14. MYSQLND_UH_MYSQLND_OPT_USE_RESULT (integer) Option: unbuffered result sets. 15. MYSQLND_UH_MYSQLND_OPT_USE_REMOTE_CONNECTION (integer) Embedded server related. 16. MYSQLND_UH_MYSQLND_OPT_USE_EMBEDDED_CONNECTION (integer) Embedded server related. 17. MYSQLND_UH_MYSQLND_OPT_GUESS_CONNECTION (integer) TODO 18. MYSQLND_UH_MYSQLND_SET_CLIENT_IP (integer) TODO 19. MYSQLND_UH_MYSQLND_SECURE_AUTH (integer) TODO 20. MYSQLND_UH_MYSQLND_REPORT_DATA_TRUNCATION (integer) Option: Whether to report data truncation. 21. MYSQLND_UH_MYSQLND_OPT_RECONNECT (integer) Option: Whether to reconnect automatically. 22. MYSQLND_UH_MYSQLND_OPT_SSL_VERIFY_SERVER_CERT (integer) Option: TODO 23. MYSQLND_UH_MYSQLND_OPT_NET_CMD_BUFFER_SIZE (integer) Option: mysqlnd network buffer size for commands. 24. MYSQLND_UH_MYSQLND_OPT_NET_READ_BUFFER_SIZE (integer) Option: mysqlnd network buffer size for reading from the server. 25. MYSQLND_UH_MYSQLND_OPT_SSL_KEY (integer) Option: SSL key. 26. MYSQLND_UH_MYSQLND_OPT_SSL_CERT (integer) Option: SSL certificate. 27. MYSQLND_UH_MYSQLND_OPT_SSL_CA (integer) Option: SSL CA. 28. MYSQLND_UH_MYSQLND_OPT_SSL_CAPATH (integer) Option: Path to SSL CA. 29. MYSQLND_UH_MYSQLND_OPT_SSL_CIPHER (integer) Option: SSL cipher. 30. MYSQLND_UH_MYSQLND_OPT_SSL_PASSPHRASE (integer) Option: SSL passphrase. 31. MYSQLND_UH_SERVER_OPTION_PLUGIN_DIR (integer) Option: server plugin directory. 32. MYSQLND_UH_SERVER_OPTION_DEFAULT_AUTH (integer) Option: default authentication method. 33. MYSQLND_UH_SERVER_OPTION_SET_CLIENT_IP (integer) TODO 34. MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET (integer) Option: maximum allowed packet size. Available as of `PHP 5.4.0'. 35. MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL (integer) Option: TODO. Available as of `PHP 5.4.0'. 36. MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE (integer) Option: make mysqlnd return integer and float columns as long even when using the MySQL Client Server text protocol. Only available with a custom build of mysqlnd. _Other_ The plugins version number can be obtained using MYSQLND_UH_VERSION or MYSQLND_UH_VERSION_ID . MYSQLND_UH_VERSION is the string representation of the numerical version number MYSQLND_UH_VERSION_ID , which is an integer such as 10000. Developers can calculate the version number as follows. Unknown PHP API feature. Version (part) Example Major*10000 1*10000 = 10000 Minor*100 0*100 = 0 Patch 0 = 0 MYSQLND_UH_VERSION_ID 10000 1. MYSQLND_UH_VERSION (string) Plugin version string, for example, `1.0.0-alpha'. 2. MYSQLND_UH_VERSION_ID (integer) Plugin version number, for example, 10000.  File: manual.info, Node: apis-php-class.mysqlnduhconnection, Next: apis-php-class.mysqlnduhpreparedstatement, Prev: apis-php-mysqlnd-uh.constants, Up: apis-php-book.mysqlnd-uh 21.9.4.15 The MysqlndUhConnection class (`MysqlndUhConnection') ............................................................... * Menu: * apis-php-mysqlnduhconnection.changeuser:: `MysqlndUhConnection::changeUser' * apis-php-mysqlnduhconnection.charsetname:: `MysqlndUhConnection::charsetName' * apis-php-mysqlnduhconnection.close:: `MysqlndUhConnection::close' * apis-php-mysqlnduhconnection.connect:: `MysqlndUhConnection::connect' * apis-php-mysqlnduhconnection.construct:: `MysqlndUhConnection::__construct' * apis-php-mysqlnduhconnection.endpsession:: `MysqlndUhConnection::endPSession' * apis-php-mysqlnduhconnection.escapestring:: `MysqlndUhConnection::escapeString' * apis-php-mysqlnduhconnection.getaffectedrows:: `MysqlndUhConnection::getAffectedRows' * apis-php-mysqlnduhconnection.geterrornumber:: `MysqlndUhConnection::getErrorNumber' * apis-php-mysqlnduhconnection.geterrorstring:: `MysqlndUhConnection::getErrorString' * apis-php-mysqlnduhconnection.getfieldcount:: `MysqlndUhConnection::getFieldCount' * apis-php-mysqlnduhconnection.gethostinformation:: `MysqlndUhConnection::getHostInformation' * apis-php-mysqlnduhconnection.getlastinsertid:: `MysqlndUhConnection::getLastInsertId' * apis-php-mysqlnduhconnection.getlastmessage:: `MysqlndUhConnection::getLastMessage' * apis-php-mysqlnduhconnection.getprotocolinformation:: `MysqlndUhConnection::getProtocolInformation' * apis-php-mysqlnduhconnection.getserverinformation:: `MysqlndUhConnection::getServerInformation' * apis-php-mysqlnduhconnection.getserverstatistics:: `MysqlndUhConnection::getServerStatistics' * apis-php-mysqlnduhconnection.getserverversion:: `MysqlndUhConnection::getServerVersion' * apis-php-mysqlnduhconnection.getsqlstate:: `MysqlndUhConnection::getSqlstate' * apis-php-mysqlnduhconnection.getstatistics:: `MysqlndUhConnection::getStatistics' * apis-php-mysqlnduhconnection.getthreadid:: `MysqlndUhConnection::getThreadId' * apis-php-mysqlnduhconnection.getwarningcount:: `MysqlndUhConnection::getWarningCount' * apis-php-mysqlnduhconnection.init:: `MysqlndUhConnection::init' * apis-php-mysqlnduhconnection.killconnection:: `MysqlndUhConnection::killConnection' * apis-php-mysqlnduhconnection.listfields:: `MysqlndUhConnection::listFields' * apis-php-mysqlnduhconnection.listmethod:: `MysqlndUhConnection::listMethod' * apis-php-mysqlnduhconnection.moreresults:: `MysqlndUhConnection::moreResults' * apis-php-mysqlnduhconnection.nextresult:: `MysqlndUhConnection::nextResult' * apis-php-mysqlnduhconnection.ping:: `MysqlndUhConnection::ping' * apis-php-mysqlnduhconnection.query:: `MysqlndUhConnection::query' * apis-php-mysqlnduhconnection.queryreadresultsetheader:: `MysqlndUhConnection::queryReadResultsetHeader' * apis-php-mysqlnduhconnection.reapquery:: `MysqlndUhConnection::reapQuery' * apis-php-mysqlnduhconnection.refreshserver:: `MysqlndUhConnection::refreshServer' * apis-php-mysqlnduhconnection.restartpsession:: `MysqlndUhConnection::restartPSession' * apis-php-mysqlnduhconnection.selectdb:: `MysqlndUhConnection::selectDb' * apis-php-mysqlnduhconnection.sendclose:: `MysqlndUhConnection::sendClose' * apis-php-mysqlnduhconnection.sendquery:: `MysqlndUhConnection::sendQuery' * apis-php-mysqlnduhconnection.serverdumpdebuginformation:: `MysqlndUhConnection::serverDumpDebugInformation' * apis-php-mysqlnduhconnection.setautocommit:: `MysqlndUhConnection::setAutocommit' * apis-php-mysqlnduhconnection.setcharset:: `MysqlndUhConnection::setCharset' * apis-php-mysqlnduhconnection.setclientoption:: `MysqlndUhConnection::setClientOption' * apis-php-mysqlnduhconnection.setserveroption:: `MysqlndUhConnection::setServerOption' * apis-php-mysqlnduhconnection.shutdownserver:: `MysqlndUhConnection::shutdownServer' * apis-php-mysqlnduhconnection.simplecommand:: `MysqlndUhConnection::simpleCommand' * apis-php-mysqlnduhconnection.simplecommandhandleresponse:: `MysqlndUhConnection::simpleCommandHandleResponse' * apis-php-mysqlnduhconnection.sslset:: `MysqlndUhConnection::sslSet' * apis-php-mysqlnduhconnection.stmtinit:: `MysqlndUhConnection::stmtInit' * apis-php-mysqlnduhconnection.storeresult:: `MysqlndUhConnection::storeResult' * apis-php-mysqlnduhconnection.txcommit:: `MysqlndUhConnection::txCommit' * apis-php-mysqlnduhconnection.txrollback:: `MysqlndUhConnection::txRollback' * apis-php-mysqlnduhconnection.useresult:: `MysqlndUhConnection::useResult' Copyright 1997-2012 the PHP Documentation Group. MysqlndUhConnection MysqlndUhConnection Methods public boolMysqlndUhConnection::changeUser mysqlnd_connectionconnection stringuser stringpassword stringdatabase boolsilent intpasswd_len public stringMysqlndUhConnection::charsetName mysqlnd_connectionconnection public boolMysqlndUhConnection::close mysqlnd_connectionconnection intclose_type public boolMysqlndUhConnection::connect mysqlnd_connectionconnection stringhost stringuse" stringpassword stringdatabase intport stringsocket intmysql_flags public MysqlndUhConnection::__construct public boolMysqlndUhConnection::endPSession mysqlnd_connectionconnection public stringMysqlndUhConnection::escapeString mysqlnd_connectionconnection stringescape_string public intMysqlndUhConnection::getAffectedRows mysqlnd_connectionconnection public intMysqlndUhConnection::getErrorNumber mysqlnd_connectionconnection public stringMysqlndUhConnection::getErrorString mysqlnd_connectionconnection public intMysqlndUhConnection::getFieldCount mysqlnd_connectionconnection public stringMysqlndUhConnection::getHostInformation mysqlnd_connectionconnection public intMysqlndUhConnection::getLastInsertId mysqlnd_connectionconnection public voidMysqlndUhConnection::getLastMessage mysqlnd_connectionconnection public stringMysqlndUhConnection::getProtocolInformation mysqlnd_connectionconnection public stringMysqlndUhConnection::getServerInformation mysqlnd_connectionconnection public stringMysqlndUhConnection::getServerStatistics mysqlnd_connectionconnection public intMysqlndUhConnection::getServerVersion mysqlnd_connectionconnection public stringMysqlndUhConnection::getSqlstate mysqlnd_connectionconnection public arrayMysqlndUhConnection::getStatistics mysqlnd_connectionconnection public intMysqlndUhConnection::getThreadId mysqlnd_connectionconnection public intMysqlndUhConnection::getWarningCount mysqlnd_connectionconnection public boolMysqlndUhConnection::init mysqlnd_connectionconnection public boolMysqlndUhConnection::killConnection mysqlnd_connectionconnection intpid public arrayMysqlndUhConnection::listFields mysqlnd_connectionconnection stringtable stringachtung_wild public voidMysqlndUhConnection::listMethod mysqlnd_connectionconnection stringquery stringachtung_wild stringpar1 public boolMysqlndUhConnection::moreResults mysqlnd_connectionconnection public boolMysqlndUhConnection::nextResult mysqlnd_connectionconnection public boolMysqlndUhConnection::ping mysqlnd_connectionconnection public boolMysqlndUhConnection::query mysqlnd_connectionconnection stringquery public boolMysqlndUhConnection::queryReadResultsetHeader mysqlnd_connectionconnection mysqlnd_statementmysqlnd_stmt public boolMysqlndUhConnection::reapQuery mysqlnd_connectionconnection public boolMysqlndUhConnection::refreshServer mysqlnd_connectionconnection intoptions public boolMysqlndUhConnection::restartPSession mysqlnd_connectionconnection public boolMysqlndUhConnection::selectDb mysqlnd_connectionconnection stringdatabase public boolMysqlndUhConnection::sendClose mysqlnd_connectionconnection public boolMysqlndUhConnection::sendQuery mysqlnd_connectionconnection stringquery public boolMysqlndUhConnection::serverDumpDebugInformation mysqlnd_connectionconnection public boolMysqlndUhConnection::setAutocommit mysqlnd_connectionconnection intmode public boolMysqlndUhConnection::setCharset mysqlnd_connectionconnection stringcharset public boolMysqlndUhConnection::setClientOption mysqlnd_connectionconnection intoption intvalue public voidMysqlndUhConnection::setServerOption mysqlnd_connectionconnection intoption public voidMysqlndUhConnection::shutdownServer stringMYSQLND_UH_RES_MYSQLND_NAME string"level" public boolMysqlndUhConnection::simpleCommand mysqlnd_connectionconnection intcommand stringarg intok_packet boolsilent boolignore_upsert_status public boolMysqlndUhConnection::simpleCommandHandleResponse mysqlnd_connectionconnection intok_packet boolsilent intcommand boolignore_upsert_status public boolMysqlndUhConnection::sslSet mysqlnd_connectionconnection stringkey stringcert stringca stringcapath stringcipher public resourceMysqlndUhConnection::stmtInit mysqlnd_connectionconnection public resourceMysqlndUhConnection::storeResult mysqlnd_connectionconnection public boolMysqlndUhConnection::txCommit mysqlnd_connectionconnection public boolMysqlndUhConnection::txRollback mysqlnd_connectionconnection public resourceMysqlndUhConnection::useResult mysqlnd_connectionconnection  File: manual.info, Node: apis-php-mysqlnduhconnection.changeuser, Next: apis-php-mysqlnduhconnection.charsetname, Prev: apis-php-class.mysqlnduhconnection, Up: apis-php-class.mysqlnduhconnection 21.9.4.16 `MysqlndUhConnection::changeUser' ........................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::changeUser' Changes the user of the specified mysqlnd database connection *Description* public boolMysqlndUhConnection::changeUser mysqlnd_connectionconnection stringuser stringpassword stringdatabase boolsilent intpasswd_len Changes the user of the specified mysqlnd database connection *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. user The MySQL user name. 3. password The MySQL password. 4. database The MySQL database to change to. 5. silent Controls if mysqlnd is allowed to emit errors or not. 6. passwd_len Length of the MySQL password. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* change_user("root", "bar", "test")); ?> The above example will output: proxy::changeUser(array ( 0 => NULL, 1 => 'root', 2 => 'bar', 3 => 'test', 4 => false, 5 => 3, )) proxy::changeUser returns false bool(false) *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_change_user'  File: manual.info, Node: apis-php-mysqlnduhconnection.charsetname, Next: apis-php-mysqlnduhconnection.close, Prev: apis-php-mysqlnduhconnection.changeuser, Up: apis-php-class.mysqlnduhconnection 21.9.4.17 `MysqlndUhConnection::charsetName' ............................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::charsetName' Returns the default character set for the database connection *Description* public stringMysqlndUhConnection::charsetName mysqlnd_connectionconnection Returns the default character set for the database connection. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* The default character set. *Examples* The above example will output: proxy::charsetName(array ( 0 => NULL, )) proxy::charsetName returns 'latin1' string(6) "latin1" *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_character_set_name'  File: manual.info, Node: apis-php-mysqlnduhconnection.close, Next: apis-php-mysqlnduhconnection.connect, Prev: apis-php-mysqlnduhconnection.charsetname, Up: apis-php-class.mysqlnduhconnection 21.9.4.18 `MysqlndUhConnection::close' ...................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::close' Closes a previously opened database connection *Description* public boolMysqlndUhConnection::close mysqlnd_connectionconnection intclose_type Closes a previously opened database connection. *Note*: Failing to call the parent implementation may cause memory leaks or crash PHP. This is not considered a bug. Please, keep in mind that the `mysqlnd' library functions have never been designed to be exposed to the user space. *Parameters* 1. connection The connection to be closed. Do not modify! 2. close_type Why the connection is to be closed. The value of close_type is one of MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT , MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT , MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTED or MYSQLND_UH_MYSQLND_CLOSE_LAST . The latter should never be seen, unless the default behaviour of the `mysqlnd' library has been changed by a plugin. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* "MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTED", MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT => "MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT", MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT => "MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT", MYSQLND_UH_MYSQLND_CLOSE_LAST => "MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT" ); return (isset($mapping[$close_type])) ? $mapping[$close_type] : 'unknown'; } class proxy extends MysqlndUhConnection { public function close($res, $close_type) { printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true)); printf("close_type = %s\n", close_type_to_string($close_type)); /* WARNING: you must call the parent */ $ret = parent::close($res, $close_type); printf("%s returns %s\n", __METHOD__, var_export($ret, true)); return $ret; } } mysqlnd_uh_set_connection_proxy(new proxy()); $mysqli = new mysqli("localhost", "root", "", "test"); $mysqli->close(); ?> The above example will output: proxy::close(array ( 0 => NULL, 1 => 0, )) close_type = MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT proxy::close returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_close' `mysql_close'  File: manual.info, Node: apis-php-mysqlnduhconnection.connect, Next: apis-php-mysqlnduhconnection.construct, Prev: apis-php-mysqlnduhconnection.close, Up: apis-php-class.mysqlnduhconnection 21.9.4.19 `MysqlndUhConnection::connect' ........................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::connect' Open a new connection to the MySQL server *Description* public boolMysqlndUhConnection::connect mysqlnd_connectionconnection stringhost stringuse" stringpassword stringdatabase intport stringsocket intmysql_flags Open a new connection to the MySQL server. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. host Can be either a host name or an IP address. Passing the NULL value or the string "localhost" to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol. 3. user The MySQL user name. 4. password If not provided or NULL , the MySQL server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password as provided or not). 5. database If provided will specify the default database to be used when performing queries. 6. port Specifies the port number to attempt to connect to the MySQL server. 7. socket Specifies the socket or named pipe that should be used. If NULL , mysqlnd will default to `/tmp/mysql.sock'. 8. mysql_flags Connection options. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* The above example will output: proxy::connect(array ( 0 => NULL, 1 => 'localhost', 2 => 'root', 3 => '', 4 => 'test', 5 => 3306, 6 => NULL, 7 => 131072, )) proxy::connect returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_connect' `mysql_connect'  File: manual.info, Node: apis-php-mysqlnduhconnection.construct, Next: apis-php-mysqlnduhconnection.endpsession, Prev: apis-php-mysqlnduhconnection.connect, Up: apis-php-class.mysqlnduhconnection 21.9.4.20 `MysqlndUhConnection::__construct' ............................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::__construct' The __construct purpose *Description* public MysqlndUhConnection::__construct *Warning*: This function is currently not documented; only its argument list is available. *Parameters* This function has no parameters. *Return Values*  File: manual.info, Node: apis-php-mysqlnduhconnection.endpsession, Next: apis-php-mysqlnduhconnection.escapestring, Prev: apis-php-mysqlnduhconnection.construct, Up: apis-php-class.mysqlnduhconnection 21.9.4.21 `MysqlndUhConnection::endPSession' ............................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::endPSession' End a persistent connection *Description* public boolMysqlndUhConnection::endPSession mysqlnd_connectionconnection End a persistent connection *Warning*: This function is currently not documented; only its argument list is available. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* close(); ?> The above example will output: proxy::endPSession(array ( 0 => NULL, )) proxy::endPSession returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy.  File: manual.info, Node: apis-php-mysqlnduhconnection.escapestring, Next: apis-php-mysqlnduhconnection.getaffectedrows, Prev: apis-php-mysqlnduhconnection.endpsession, Up: apis-php-class.mysqlnduhconnection 21.9.4.22 `MysqlndUhConnection::escapeString' ............................................. Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::escapeString' Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection *Description* public stringMysqlndUhConnection::escapeString mysqlnd_connectionconnection stringescape_string Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection. *Parameters* 1. MYSQLND_UH_RES_MYSQLND_NAME Mysqlnd connection handle. Do not modify! 2. escape_string The string to be escaped. *Return Values* The escaped string. *Examples* set_charset("latin1"); $mysqli->real_escape_string("test0'test"); ?> The above example will output: proxy::escapeString(array ( 0 => NULL, 1 => 'test0\'test', )) proxy::escapeString returns 'test0\\\'test' *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_real_escape_string' `mysql_real_escape_string'  File: manual.info, Node: apis-php-mysqlnduhconnection.getaffectedrows, Next: apis-php-mysqlnduhconnection.geterrornumber, Prev: apis-php-mysqlnduhconnection.escapestring, Up: apis-php-class.mysqlnduhconnection 21.9.4.23 `MysqlndUhConnection::getAffectedRows' ................................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getAffectedRows' Gets the number of affected rows in a previous MySQL operation *Description* public intMysqlndUhConnection::getAffectedRows mysqlnd_connectionconnection Gets the number of affected rows in a previous MySQL operation. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Number of affected rows. *Examples* query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT)"); $mysqli->query("INSERT INTO test(id) VALUES (1)"); var_dump($mysqli->affected_rows); ?> The above example will output: proxy::getAffectedRows(array ( 0 => NULL, )) proxy::getAffectedRows returns 1 int(1) *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_affected_rows' `mysql_affected_rows'  File: manual.info, Node: apis-php-mysqlnduhconnection.geterrornumber, Next: apis-php-mysqlnduhconnection.geterrorstring, Prev: apis-php-mysqlnduhconnection.getaffectedrows, Up: apis-php-class.mysqlnduhconnection 21.9.4.24 `MysqlndUhConnection::getErrorNumber' ............................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getErrorNumber' Returns the error code for the most recent function call *Description* public intMysqlndUhConnection::getErrorNumber mysqlnd_connectionconnection Returns the error code for the most recent function call. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Error code for the most recent function call. *Examples* *Note `MysqlndUhConnection::getErrorNumber': apis-php-mysqlnduhconnection.geterrornumber. is not only executed after the invocation of a user space API call which maps directly to it but also called internally. query("PLEASE_LET_THIS_BE_INVALID_SQL"); printf("errno...\n"); var_dump($mysqli->errno); printf("close...\n"); $mysqli->close(); ?> The above example will output: connect... proxy::getErrorNumber(array ( 0 => NULL, )) proxy::getErrorNumber returns 0 query... errno... proxy::getErrorNumber(array ( 0 => NULL, )) proxy::getErrorNumber returns 1064 int(1064) close... *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. *Note `MysqlndUhConnection::getErrorString': apis-php-mysqlnduhconnection.geterrorstring. `mysqli_errno' `mysql_errno'  File: manual.info, Node: apis-php-mysqlnduhconnection.geterrorstring, Next: apis-php-mysqlnduhconnection.getfieldcount, Prev: apis-php-mysqlnduhconnection.geterrornumber, Up: apis-php-class.mysqlnduhconnection 21.9.4.25 `MysqlndUhConnection::getErrorString' ............................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getErrorString' Returns a string description of the last error *Description* public stringMysqlndUhConnection::getErrorString mysqlnd_connectionconnection Returns a string description of the last error. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Error string for the most recent function call. *Examples* *Note `MysqlndUhConnection::getErrorString': apis-php-mysqlnduhconnection.geterrorstring. is not only executed after the invocation of a user space API call which maps directly to it but also called internally. query("WILL_I_EVER_LEARN_SQL?"); printf("errno...\n"); var_dump($mysqli->error); printf("close...\n"); $mysqli->close(); ?> The above example will output: connect... proxy::getErrorString(array ( 0 => NULL, )) proxy::getErrorString returns '' query... errno... proxy::getErrorString(array ( 0 => NULL, )) proxy::getErrorString returns '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 \'WILL_I_EVER_LEARN_SQL?\' at line 1' string(168) "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 'WILL_I_EVER_LEARN_SQL?' at line 1" close... *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. *Note `MysqlndUhConnection::getErrorNumber': apis-php-mysqlnduhconnection.geterrornumber. `mysqli_error' `mysql_error'  File: manual.info, Node: apis-php-mysqlnduhconnection.getfieldcount, Next: apis-php-mysqlnduhconnection.gethostinformation, Prev: apis-php-mysqlnduhconnection.geterrorstring, Up: apis-php-class.mysqlnduhconnection 21.9.4.26 `MysqlndUhConnection::getFieldCount' .............................................. Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getFieldCount' Returns the number of columns for the most recent query *Description* public intMysqlndUhConnection::getFieldCount mysqlnd_connectionconnection Returns the number of columns for the most recent query. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Number of columns. *Examples* *Note `MysqlndUhConnection::getFieldCount': apis-php-mysqlnduhconnection.getfieldcount. is not only executed after the invocation of a user space API call which maps directly to it but also called internally. query("WILL_I_EVER_LEARN_SQL?"); var_dump($mysqli->field_count); $mysqli->query("SELECT 1, 2, 3 FROM DUAL"); var_dump($mysqli->field_count); ?> The above example will output: proxy::getFieldCount(array ( 0 => NULL, )) proxy::getFieldCount returns 0 int(0) proxy::getFieldCount(array ( 0 => NULL, )) proxy::getFieldCount returns 3 proxy::getFieldCount(array ( 0 => NULL, )) proxy::getFieldCount returns 3 int(3) *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_field_count'  File: manual.info, Node: apis-php-mysqlnduhconnection.gethostinformation, Next: apis-php-mysqlnduhconnection.getlastinsertid, Prev: apis-php-mysqlnduhconnection.getfieldcount, Up: apis-php-class.mysqlnduhconnection 21.9.4.27 `MysqlndUhConnection::getHostInformation' ................................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getHostInformation' Returns a string representing the type of connection used *Description* public stringMysqlndUhConnection::getHostInformation mysqlnd_connectionconnection Returns a string representing the type of connection used. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Connection description. *Examples* host_info); ?> The above example will output: proxy::getHostInformation(array ( 0 => NULL, )) proxy::getHostInformation returns 'Localhost via UNIX socket' string(25) "Localhost via UNIX socket" *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_get_host_info' `mysql_get_host_info'  File: manual.info, Node: apis-php-mysqlnduhconnection.getlastinsertid, Next: apis-php-mysqlnduhconnection.getlastmessage, Prev: apis-php-mysqlnduhconnection.gethostinformation, Up: apis-php-class.mysqlnduhconnection 21.9.4.28 `MysqlndUhConnection::getLastInsertId' ................................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getLastInsertId' Returns the auto generated id used in the last query. *Description* public intMysqlndUhConnection::getLastInsertId mysqlnd_connectionconnection Returns the auto generated id used in the last query. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Last insert id. *Examples* query("DROP TABLE IF EXISTS test"); $mysqli->query("CREATE TABLE test(id INT AUTO_INCREMENT PRIMARY KEY, col VARCHAR(255))"); $mysqli->query("INSERT INTO test(col) VALUES ('a')"); var_dump($mysqli->insert_id); ?> The above example will output: proxy::getLastInsertId(array ( 0 => NULL, )) proxy::getLastInsertId returns 1 int(1) *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_insert_id' `mysql_insert_id'  File: manual.info, Node: apis-php-mysqlnduhconnection.getlastmessage, Next: apis-php-mysqlnduhconnection.getprotocolinformation, Prev: apis-php-mysqlnduhconnection.getlastinsertid, Up: apis-php-class.mysqlnduhconnection 21.9.4.29 `MysqlndUhConnection::getLastMessage' ............................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getLastMessage' Retrieves information about the most recently executed query *Description* public voidMysqlndUhConnection::getLastMessage mysqlnd_connectionconnection Retrieves information about the most recently executed query. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Last message. Trying to return a string longer than 511 bytes will cause an error of the type `E_WARNING' and result in the string being truncated. *Examples* info); $mysqli->query("DROP TABLE IF EXISTS test"); var_dump($mysqli->info); ?> The above example will output: proxy::getLastMessage(array ( 0 => NULL, )) proxy::getLastMessage returns '' string(0) "" proxy::getLastMessage(array ( 0 => NULL, )) proxy::getLastMessage returns '' string(0) "" *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_info' `mysql_info'  File: manual.info, Node: apis-php-mysqlnduhconnection.getprotocolinformation, Next: apis-php-mysqlnduhconnection.getserverinformation, Prev: apis-php-mysqlnduhconnection.getlastmessage, Up: apis-php-class.mysqlnduhconnection 21.9.4.30 `MysqlndUhConnection::getProtocolInformation' ....................................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getProtocolInformation' Returns the version of the MySQL protocol used *Description* public stringMysqlndUhConnection::getProtocolInformation mysqlnd_connectionconnection Returns the version of the MySQL protocol used. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* The protocol version. *Examples* protocol_version); ?> The above example will output: proxy::getProtocolInformation(array ( 0 => NULL, )) proxy::getProtocolInformation returns 10 int(10) *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_get_proto_info' `mysql_get_proto_info'  File: manual.info, Node: apis-php-mysqlnduhconnection.getserverinformation, Next: apis-php-mysqlnduhconnection.getserverstatistics, Prev: apis-php-mysqlnduhconnection.getprotocolinformation, Up: apis-php-class.mysqlnduhconnection 21.9.4.31 `MysqlndUhConnection::getServerInformation' ..................................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getServerInformation' Returns the version of the MySQL server *Description* public stringMysqlndUhConnection::getServerInformation mysqlnd_connectionconnection Returns the version of the MySQL server. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* The server version. *Examples* server_info); ?> The above example will output: proxy::getServerInformation(array ( 0 => NULL, )) proxy::getServerInformation returns '5.1.45-debug-log' string(16) "5.1.45-debug-log" *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_get_server_info' `mysql_get_server_info'  File: manual.info, Node: apis-php-mysqlnduhconnection.getserverstatistics, Next: apis-php-mysqlnduhconnection.getserverversion, Prev: apis-php-mysqlnduhconnection.getserverinformation, Up: apis-php-class.mysqlnduhconnection 21.9.4.32 `MysqlndUhConnection::getServerStatistics' .................................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getServerStatistics' Gets the current system status *Description* public stringMysqlndUhConnection::getServerStatistics mysqlnd_connectionconnection Gets the current system status. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* The system status message. *Examples* The above example will output: proxy::getServerStatistics(array ( 0 => NULL, )) proxy::getServerStatistics returns 'Uptime: 2059995 Threads: 1 Questions: 126157 Slow queries: 0 Opens: 6377 Flush tables: 1 Open tables: 18 Queries per second avg: 0.61' string(140) "Uptime: 2059995 Threads: 1 Questions: 126157 Slow queries: 0 Opens: 6377 Flush tables: 1 Open tables: 18 Queries per second avg: 0.61" *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_stat' `mysql_stat'  File: manual.info, Node: apis-php-mysqlnduhconnection.getserverversion, Next: apis-php-mysqlnduhconnection.getsqlstate, Prev: apis-php-mysqlnduhconnection.getserverstatistics, Up: apis-php-class.mysqlnduhconnection 21.9.4.33 `MysqlndUhConnection::getServerVersion' ................................................. Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getServerVersion' Returns the version of the MySQL server as an integer *Description* public intMysqlndUhConnection::getServerVersion mysqlnd_connectionconnection Returns the version of the MySQL server as an integer. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* The MySQL version. *Examples* server_version); ?> The above example will output: proxy::getServerVersion(array ( 0 => NULL, )) proxy::getServerVersion returns 50145 int(50145) *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_get_server_version' `mysql_get_server_version' (http://www.php.net/mysql_get_server_version)  File: manual.info, Node: apis-php-mysqlnduhconnection.getsqlstate, Next: apis-php-mysqlnduhconnection.getstatistics, Prev: apis-php-mysqlnduhconnection.getserverversion, Up: apis-php-class.mysqlnduhconnection 21.9.4.34 `MysqlndUhConnection::getSqlstate' ............................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getSqlstate' Returns the SQLSTATE error from previous MySQL operation *Description* public stringMysqlndUhConnection::getSqlstate mysqlnd_connectionconnection Returns the SQLSTATE error from previous MySQL operation. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* The SQLSTATE code. *Examples* sqlstate); $mysqli->query("AN_INVALID_REQUEST_TO_PROVOKE_AN_ERROR"); var_dump($mysqli->sqlstate); ?> The above example will output: proxy::getSqlstate(array ( 0 => NULL, )) proxy::getSqlstate returns '00000' string(5) "00000" proxy::getSqlstate(array ( 0 => NULL, )) proxy::getSqlstate returns '42000' string(5) "42000" *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_sql_state' (http://www.php.net/mysqli_sql_state)  File: manual.info, Node: apis-php-mysqlnduhconnection.getstatistics, Next: apis-php-mysqlnduhconnection.getthreadid, Prev: apis-php-mysqlnduhconnection.getsqlstate, Up: apis-php-class.mysqlnduhconnection 21.9.4.35 `MysqlndUhConnection::getStatistics' .............................................. Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getStatistics' Returns statistics about the client connection. *Description* public arrayMysqlndUhConnection::getStatistics mysqlnd_connectionconnection Returns statistics about the client connection. *Warning*: This function is currently not documented; only its argument list is available. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Connection statistics collected by mysqlnd. *Examples* get_connection_stats()); ?> The above example will output: proxy::getStatistics(array ( 0 => NULL, )) proxy::getStatistics returns array ( 'bytes_sent' => '73', 'bytes_received' => '77', 'packets_sent' => '2', 'packets_received' => '2', 'protocol_overhead_in' => '8', 'protocol_overhead_out' => '8', 'bytes_received_ok_packet' => '0', 'bytes_received_eof_packet' => '0', 'bytes_received_rset_header_packet' => '0', 'bytes_received_rset_field_meta_packet' => '0', 'bytes_received_rset_row_packet' => '0', 'bytes_received_prepare_response_packet' => '0', 'bytes_received_change_user_packet' => '0', 'packets_sent_command' => '0', 'packets_received_ok' => '0', 'packets_received_eof' => '0', 'packets_received_rset_header' => '0', 'packets_received_rset_field_meta' => '0', 'packets_received_rset_row' => '0', 'packets_received_prepare_response' => '0', 'packets_received_change_user' => '0', 'result_set_queries' => '0', 'non_result_set_queries' => '0', 'no_index_used' => '0', 'bad_index_used' => '0', 'slow_queries' => '0', 'buffered_sets' => '0', 'unbuffered_sets' => '0', 'ps_buffered_sets' => '0', 'ps_unbuffered_sets' => '0', 'flushed_normal_sets' => '0', 'flushed_ps_sets' => '0', 'ps_prepared_never_executed' => '0', 'ps_prepared_once_executed' => '0', 'rows_fetched_from_server_normal' => '0', 'rows_fetched_from_server_ps' => '0', 'rows_buffered_from_client_normal' => '0', 'rows_buffered_from_client_ps' => '0', 'rows_fetched_from_client_normal_buffered' => '0', 'rows_fetched_from_client_normal_unbuffered' => '0', 'rows_fetched_from_client_ps_buffered' => '0', 'rows_fetched_from_client_ps_unbuffered' => '0', 'rows_fetched_from_client_ps_cursor' => '0', 'rows_affected_normal' => '0', 'rows_affected_ps' => '0', 'rows_skipped_normal' => '0', 'rows_skipped_ps' => '0', 'copy_on_write_saved' => '0', 'copy_on_write_performed' => '0', 'command_buffer_too_small' => '0', 'connect_success' => '1', 'connect_failure' => '0', 'connection_reused' => '0', 'reconnect' => '0', 'pconnect_success' => '0', 'active_connections' => '1', 'active_persistent_connections' => '0', 'explicit_close' => '0', 'implicit_close' => '0', 'disconnect_close' => '0', 'in_middle_of_command_close' => '0', 'explicit_free_result' => '0', 'implicit_free_result' => '0', 'explicit_stmt_close' => '0', 'implicit_stmt_close' => '0', 'mem_emalloc_count' => '0', 'mem_emalloc_amount' => '0', 'mem_ecalloc_count' => '0', 'mem_ecalloc_amount' => '0', 'mem_erealloc_count' => '0', 'mem_erealloc_amount' => '0', 'mem_efree_count' => '0', 'mem_efree_amount' => '0', 'mem_malloc_count' => '0', 'mem_malloc_amount' => '0', 'mem_calloc_count' => '0', 'mem_calloc_amount' => '0', 'mem_realloc_count' => '0', 'mem_realloc_amount' => '0', 'mem_free_count' => '0', 'mem_free_amount' => '0', 'mem_estrndup_count' => '0', 'mem_strndup_count' => '0', 'mem_estndup_count' => '0', 'mem_strdup_count' => '0', 'proto_text_fetched_null' => '0', 'proto_text_fetched_bit' => '0', 'proto_text_fetched_tinyint' => '0', 'proto_text_fetched_short' => '0', 'proto_text_fetched_int24' => '0', 'proto_text_fetched_int' => '0', 'proto_text_fetched_bigint' => '0', 'proto_text_fetched_decimal' => '0', 'proto_text_fetched_float' => '0', 'proto_text_fetched_double' => '0', 'proto_text_fetched_date' => '0', 'proto_text_fetched_year' => '0', 'proto_text_fetched_time' => '0', 'proto_text_fetched_datetime' => '0', 'proto_text_fetched_timestamp' => '0', 'proto_text_fetched_string' => '0', 'proto_text_fetched_blob' => '0', 'proto_text_fetched_enum' => '0', 'proto_text_fetched_set' => '0', 'proto_text_fetched_geometry' => '0', 'proto_text_fetched_other' => '0', 'proto_binary_fetched_null' => '0', 'proto_binary_fetched_bit' => '0', 'proto_binary_fetched_tinyint' => '0', 'proto_binary_fetched_short' => '0', 'proto_binary_fetched_int24' => '0', 'proto_binary_fetched_int' => '0', 'proto_binary_fetched_bigint' => '0', 'proto_binary_fetched_decimal' => '0', 'proto_binary_fetched_float' => '0', 'proto_binary_fetched_double' => '0', 'proto_binary_fetched_date' => '0', 'proto_binary_fetched_year' => '0', 'proto_binary_fetched_time' => '0', 'proto_binary_fetched_datetime' => '0', 'proto_binary_fetched_timestamp' => '0', 'proto_binary_fetched_string' => '0', 'proto_binary_fetched_blob' => '0', 'proto_binary_fetched_enum' => '0', 'proto_binary_fetched_set' => '0', 'proto_binary_fetched_geometry' => '0', 'proto_binary_fetched_other' => '0', 'init_command_executed_count' => '0', 'init_command_failed_count' => '0', 'com_quit' => '0', 'com_init_db' => '0', 'com_query' => '0', 'com_field_list' => '0', 'com_create_db' => '0', 'com_drop_db' => '0', 'com_refresh' => '0', 'com_shutdown' => '0', 'com_statistics' => '0', 'com_process_info' => '0', 'com_connect' => '0', 'com_process_kill' => '0', 'com_debug' => '0', 'com_ping' => '0', 'com_time' => '0', 'com_delayed_insert' => '0', 'com_change_user' => '0', 'com_binlog_dump' => '0', 'com_table_dump' => '0', 'com_connect_out' => '0', 'com_register_slave' => '0', 'com_stmt_prepare' => '0', 'com_stmt_execute' => '0', 'com_stmt_send_long_data' => '0', 'com_stmt_close' => '0', 'com_stmt_reset' => '0', 'com_stmt_set_option' => '0', 'com_stmt_fetch' => '0', 'com_deamon' => '0', 'bytes_received_real_data_normal' => '0', 'bytes_received_real_data_ps' => '0', ) array(160) { ["bytes_sent"]=> string(2) "73" ["bytes_received"]=> string(2) "77" ["packets_sent"]=> string(1) "2" ["packets_received"]=> string(1) "2" ["protocol_overhead_in"]=> string(1) "8" ["protocol_overhead_out"]=> string(1) "8" ["bytes_received_ok_packet"]=> string(1) "0" ["bytes_received_eof_packet"]=> string(1) "0" ["bytes_received_rset_header_packet"]=> string(1) "0" ["bytes_received_rset_field_meta_packet"]=> string(1) "0" ["bytes_received_rset_row_packet"]=> string(1) "0" ["bytes_received_prepare_response_packet"]=> string(1) "0" ["bytes_received_change_user_packet"]=> string(1) "0" ["packets_sent_command"]=> string(1) "0" ["packets_received_ok"]=> string(1) "0" ["packets_received_eof"]=> string(1) "0" ["packets_received_rset_header"]=> string(1) "0" ["packets_received_rset_field_meta"]=> string(1) "0" ["packets_received_rset_row"]=> string(1) "0" ["packets_received_prepare_response"]=> string(1) "0" ["packets_received_change_user"]=> string(1) "0" ["result_set_queries"]=> string(1) "0" ["non_result_set_queries"]=> string(1) "0" ["no_index_used"]=> string(1) "0" ["bad_index_used"]=> string(1) "0" ["slow_queries"]=> string(1) "0" ["buffered_sets"]=> string(1) "0" ["unbuffered_sets"]=> string(1) "0" ["ps_buffered_sets"]=> string(1) "0" ["ps_unbuffered_sets"]=> string(1) "0" ["flushed_normal_sets"]=> string(1) "0" ["flushed_ps_sets"]=> string(1) "0" ["ps_prepared_never_executed"]=> string(1) "0" ["ps_prepared_once_executed"]=> string(1) "0" ["rows_fetched_from_server_normal"]=> string(1) "0" ["rows_fetched_from_server_ps"]=> string(1) "0" ["rows_buffered_from_client_normal"]=> string(1) "0" ["rows_buffered_from_client_ps"]=> string(1) "0" ["rows_fetched_from_client_normal_buffered"]=> string(1) "0" ["rows_fetched_from_client_normal_unbuffered"]=> string(1) "0" ["rows_fetched_from_client_ps_buffered"]=> string(1) "0" ["rows_fetched_from_client_ps_unbuffered"]=> string(1) "0" ["rows_fetched_from_client_ps_cursor"]=> string(1) "0" ["rows_affected_normal"]=> string(1) "0" ["rows_affected_ps"]=> string(1) "0" ["rows_skipped_normal"]=> string(1) "0" ["rows_skipped_ps"]=> string(1) "0" ["copy_on_write_saved"]=> string(1) "0" ["copy_on_write_performed"]=> string(1) "0" ["command_buffer_too_small"]=> string(1) "0" ["connect_success"]=> string(1) "1" ["connect_failure"]=> string(1) "0" ["connection_reused"]=> string(1) "0" ["reconnect"]=> string(1) "0" ["pconnect_success"]=> string(1) "0" ["active_connections"]=> string(1) "1" ["active_persistent_connections"]=> string(1) "0" ["explicit_close"]=> string(1) "0" ["implicit_close"]=> string(1) "0" ["disconnect_close"]=> string(1) "0" ["in_middle_of_command_close"]=> string(1) "0" ["explicit_free_result"]=> string(1) "0" ["implicit_free_result"]=> string(1) "0" ["explicit_stmt_close"]=> string(1) "0" ["implicit_stmt_close"]=> string(1) "0" ["mem_emalloc_count"]=> string(1) "0" ["mem_emalloc_amount"]=> string(1) "0" ["mem_ecalloc_count"]=> string(1) "0" ["mem_ecalloc_amount"]=> string(1) "0" ["mem_erealloc_count"]=> string(1) "0" ["mem_erealloc_amount"]=> string(1) "0" ["mem_efree_count"]=> string(1) "0" ["mem_efree_amount"]=> string(1) "0" ["mem_malloc_count"]=> string(1) "0" ["mem_malloc_amount"]=> string(1) "0" ["mem_calloc_count"]=> string(1) "0" ["mem_calloc_amount"]=> string(1) "0" ["mem_realloc_count"]=> string(1) "0" ["mem_realloc_amount"]=> string(1) "0" ["mem_free_count"]=> string(1) "0" ["mem_free_amount"]=> string(1) "0" ["mem_estrndup_count"]=> string(1) "0" ["mem_strndup_count"]=> string(1) "0" ["mem_estndup_count"]=> string(1) "0" ["mem_strdup_count"]=> string(1) "0" ["proto_text_fetched_null"]=> string(1) "0" ["proto_text_fetched_bit"]=> string(1) "0" ["proto_text_fetched_tinyint"]=> string(1) "0" ["proto_text_fetched_short"]=> string(1) "0" ["proto_text_fetched_int24"]=> string(1) "0" ["proto_text_fetched_int"]=> string(1) "0" ["proto_text_fetched_bigint"]=> string(1) "0" ["proto_text_fetched_decimal"]=> string(1) "0" ["proto_text_fetched_float"]=> string(1) "0" ["proto_text_fetched_double"]=> string(1) "0" ["proto_text_fetched_date"]=> string(1) "0" ["proto_text_fetched_year"]=> string(1) "0" ["proto_text_fetched_time"]=> string(1) "0" ["proto_text_fetched_datetime"]=> string(1) "0" ["proto_text_fetched_timestamp"]=> string(1) "0" ["proto_text_fetched_string"]=> string(1) "0" ["proto_text_fetched_blob"]=> string(1) "0" ["proto_text_fetched_enum"]=> string(1) "0" ["proto_text_fetched_set"]=> string(1) "0" ["proto_text_fetched_geometry"]=> string(1) "0" ["proto_text_fetched_other"]=> string(1) "0" ["proto_binary_fetched_null"]=> string(1) "0" ["proto_binary_fetched_bit"]=> string(1) "0" ["proto_binary_fetched_tinyint"]=> string(1) "0" ["proto_binary_fetched_short"]=> string(1) "0" ["proto_binary_fetched_int24"]=> string(1) "0" ["proto_binary_fetched_int"]=> string(1) "0" ["proto_binary_fetched_bigint"]=> string(1) "0" ["proto_binary_fetched_decimal"]=> string(1) "0" ["proto_binary_fetched_float"]=> string(1) "0" ["proto_binary_fetched_double"]=> string(1) "0" ["proto_binary_fetched_date"]=> string(1) "0" ["proto_binary_fetched_year"]=> string(1) "0" ["proto_binary_fetched_time"]=> string(1) "0" ["proto_binary_fetched_datetime"]=> string(1) "0" ["proto_binary_fetched_timestamp"]=> string(1) "0" ["proto_binary_fetched_string"]=> string(1) "0" ["proto_binary_fetched_blob"]=> string(1) "0" ["proto_binary_fetched_enum"]=> string(1) "0" ["proto_binary_fetched_set"]=> string(1) "0" ["proto_binary_fetched_geometry"]=> string(1) "0" ["proto_binary_fetched_other"]=> string(1) "0" ["init_command_executed_count"]=> string(1) "0" ["init_command_failed_count"]=> string(1) "0" ["com_quit"]=> string(1) "0" ["com_init_db"]=> string(1) "0" ["com_query"]=> string(1) "0" ["com_field_list"]=> string(1) "0" ["com_create_db"]=> string(1) "0" ["com_drop_db"]=> string(1) "0" ["com_refresh"]=> string(1) "0" ["com_shutdown"]=> string(1) "0" ["com_statistics"]=> string(1) "0" ["com_process_info"]=> string(1) "0" ["com_connect"]=> string(1) "0" ["com_process_kill"]=> string(1) "0" ["com_debug"]=> string(1) "0" ["com_ping"]=> string(1) "0" ["com_time"]=> string(1) "0" ["com_delayed_insert"]=> string(1) "0" ["com_change_user"]=> string(1) "0" ["com_binlog_dump"]=> string(1) "0" ["com_table_dump"]=> string(1) "0" ["com_connect_out"]=> string(1) "0" ["com_register_slave"]=> string(1) "0" ["com_stmt_prepare"]=> string(1) "0" ["com_stmt_execute"]=> string(1) "0" ["com_stmt_send_long_data"]=> string(1) "0" ["com_stmt_close"]=> string(1) "0" ["com_stmt_reset"]=> string(1) "0" ["com_stmt_set_option"]=> string(1) "0" ["com_stmt_fetch"]=> string(1) "0" ["com_deamon"]=> string(1) "0" ["bytes_received_real_data_normal"]=> string(1) "0" ["bytes_received_real_data_ps"]=> string(1) "0" } *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_get_connection_stats'  File: manual.info, Node: apis-php-mysqlnduhconnection.getthreadid, Next: apis-php-mysqlnduhconnection.getwarningcount, Prev: apis-php-mysqlnduhconnection.getstatistics, Up: apis-php-class.mysqlnduhconnection 21.9.4.36 `MysqlndUhConnection::getThreadId' ............................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getThreadId' Returns the thread ID for the current connection *Description* public intMysqlndUhConnection::getThreadId mysqlnd_connectionconnection Returns the thread ID for the current connection. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Connection thread id. *Examples* thread_id); ?> The above example will output: proxy::getThreadId(array ( 0 => NULL, )) proxy::getThreadId returns 27646 int(27646) *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_thread_id' `mysql_thread_id'  File: manual.info, Node: apis-php-mysqlnduhconnection.getwarningcount, Next: apis-php-mysqlnduhconnection.init, Prev: apis-php-mysqlnduhconnection.getthreadid, Up: apis-php-class.mysqlnduhconnection 21.9.4.37 `MysqlndUhConnection::getWarningCount' ................................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::getWarningCount' Returns the number of warnings from the last query for the given link *Description* public intMysqlndUhConnection::getWarningCount mysqlnd_connectionconnection Returns the number of warnings from the last query for the given link. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Number of warnings. *Examples* warning_count); ?> The above example will output: proxy::getWarningCount(array ( 0 => NULL, )) proxy::getWarningCount returns 0 int(0) *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_warning_count'  File: manual.info, Node: apis-php-mysqlnduhconnection.init, Next: apis-php-mysqlnduhconnection.killconnection, Prev: apis-php-mysqlnduhconnection.getwarningcount, Up: apis-php-class.mysqlnduhconnection 21.9.4.38 `MysqlndUhConnection::init' ..................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::init' Initialize mysqlnd connection *Description* public boolMysqlndUhConnection::init mysqlnd_connectionconnection Initialize mysqlnd connection. This is an mysqlnd internal call to initialize the connection object. *Note*: Failing to call the parent implementation may cause memory leaks or crash PHP. This is not considered a bug. Please, keep in mind that the `mysqlnd' library functions have never been designed to be exposed to the user space. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* The above example will output: proxy::init(array ( 0 => NULL, )) proxy::init returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy.  File: manual.info, Node: apis-php-mysqlnduhconnection.killconnection, Next: apis-php-mysqlnduhconnection.listfields, Prev: apis-php-mysqlnduhconnection.init, Up: apis-php-class.mysqlnduhconnection 21.9.4.39 `MysqlndUhConnection::killConnection' ............................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::killConnection' Asks the server to kill a MySQL thread *Description* public boolMysqlndUhConnection::killConnection mysqlnd_connectionconnection intpid Asks the server to kill a MySQL thread. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. pid Thread Id of the connection to be killed. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* kill($mysqli->thread_id); ?> The above example will output: proxy::killConnection(array ( 0 => NULL, 1 => 27650, )) proxy::killConnection returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_kill'  File: manual.info, Node: apis-php-mysqlnduhconnection.listfields, Next: apis-php-mysqlnduhconnection.listmethod, Prev: apis-php-mysqlnduhconnection.killconnection, Up: apis-php-class.mysqlnduhconnection 21.9.4.40 `MysqlndUhConnection::listFields' ........................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::listFields' List MySQL table fields *Description* public arrayMysqlndUhConnection::listFields mysqlnd_connectionconnection stringtable stringachtung_wild List MySQL table fields. *Warning*: This function is currently not documented; only its argument list is available. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. table The name of the table that's being queried. 3. pattern Name pattern. *Return Values* *Examples* The above example will output: proxy::listFields(array ( 0 => NULL, 1 => 'test_a', 2 => '', )) proxy::listFields returns NULL num_rows = 0 *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysql_list_fields'  File: manual.info, Node: apis-php-mysqlnduhconnection.listmethod, Next: apis-php-mysqlnduhconnection.moreresults, Prev: apis-php-mysqlnduhconnection.listfields, Up: apis-php-class.mysqlnduhconnection 21.9.4.41 `MysqlndUhConnection::listMethod' ........................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::listMethod' Wrapper for assorted list commands *Description* public voidMysqlndUhConnection::listMethod mysqlnd_connectionconnection stringquery stringachtung_wild stringpar1 Wrapper for assorted list commands. *Warning*: This function is currently not documented; only its argument list is available. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. query SHOW command to be executed. 3. achtung_wild 4. par1 *Return Values* *Return Values* TODO *Examples* The above example will output: proxy::listMethod(array ( 0 => NULL, 1 => 'SHOW DATABASES', 2 => '', 3 => '', )) proxy::listMethod returns NULL num_rows = 6 array(1) { ["Database"]=> string(18) "information_schema" } array(1) { ["Database"]=> string(5) "mysql" } array(1) { ["Database"]=> string(8) "oxid_new" } array(1) { ["Database"]=> string(7) "phptest" } array(1) { ["Database"]=> string(7) "pushphp" } array(1) { ["Database"]=> string(4) "test" } *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysql_list_dbs'  File: manual.info, Node: apis-php-mysqlnduhconnection.moreresults, Next: apis-php-mysqlnduhconnection.nextresult, Prev: apis-php-mysqlnduhconnection.listmethod, Up: apis-php-class.mysqlnduhconnection 21.9.4.42 `MysqlndUhConnection::moreResults' ............................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::moreResults' Check if there are any more query results from a multi query *Description* public boolMysqlndUhConnection::moreResults mysqlnd_connectionconnection Check if there are any more query results from a multi query. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* multi_query("SELECT 1 AS _one; SELECT 2 AS _two"); do { $res = $mysqli->store_result(); var_dump($res->fetch_assoc()); printf("%s\n", str_repeat("-", 40)); } while ($mysqli->more_results() && $mysqli->next_result()); ?> The above example will output: array(1) { ["_one"]=> string(1) "1" } ---------------------------------------- proxy::moreResults(array ( 0 => NULL, )) proxy::moreResults returns true proxy::moreResults(array ( 0 => NULL, )) proxy::moreResults returns true array(1) { ["_two"]=> string(1) "2" } ---------------------------------------- proxy::moreResults(array ( 0 => NULL, )) proxy::moreResults returns false *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_more_results'  File: manual.info, Node: apis-php-mysqlnduhconnection.nextresult, Next: apis-php-mysqlnduhconnection.ping, Prev: apis-php-mysqlnduhconnection.moreresults, Up: apis-php-class.mysqlnduhconnection 21.9.4.43 `MysqlndUhConnection::nextResult' ........................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::nextResult' Prepare next result from multi_query *Description* public boolMysqlndUhConnection::nextResult mysqlnd_connectionconnection Prepare next result from multi_query. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* multi_query("SELECT 1 AS _one; SELECT 2 AS _two"); do { $res = $mysqli->store_result(); var_dump($res->fetch_assoc()); printf("%s\n", str_repeat("-", 40)); } while ($mysqli->more_results() && $mysqli->next_result()); ?> The above example will output: array(1) { ["_one"]=> string(1) "1" } ---------------------------------------- proxy::nextResult(array ( 0 => NULL, )) proxy::nextResult returns true array(1) { ["_two"]=> string(1) "2" } ---------------------------------------- *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_next_result'  File: manual.info, Node: apis-php-mysqlnduhconnection.ping, Next: apis-php-mysqlnduhconnection.query, Prev: apis-php-mysqlnduhconnection.nextresult, Up: apis-php-class.mysqlnduhconnection 21.9.4.44 `MysqlndUhConnection::ping' ..................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::ping' Pings a server connection, or tries to reconnect if the connection has gone down *Description* public boolMysqlndUhConnection::ping mysqlnd_connectionconnection Pings a server connection, or tries to reconnect if the connection has gone down. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* ping(); ?> The above example will output: proxy::ping(array ( 0 => NULL, )) proxy::ping returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_ping' `mysql_ping'  File: manual.info, Node: apis-php-mysqlnduhconnection.query, Next: apis-php-mysqlnduhconnection.queryreadresultsetheader, Prev: apis-php-mysqlnduhconnection.ping, Up: apis-php-class.mysqlnduhconnection 21.9.4.45 `MysqlndUhConnection::query' ...................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::query' Performs a query on the database *Description* public boolMysqlndUhConnection::query mysqlnd_connectionconnection stringquery Performs a query on the database (COM_QUERY). *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. query The query string. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* query("SELECT 'Welcome mysqlnd_uh!' FROM DUAL"); var_dump($res->fetch_assoc()); ?> The above example will output: proxy::query(array ( 0 => NULL, 1 => 'SELECT \'Welcome mysqlnd_uh!\' FROM DUAL', )) proxy::query returns true array(1) { ["How about query rewriting?"]=> string(26) "How about query rewriting?" } *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_query' `mysql_query'  File: manual.info, Node: apis-php-mysqlnduhconnection.queryreadresultsetheader, Next: apis-php-mysqlnduhconnection.reapquery, Prev: apis-php-mysqlnduhconnection.query, Up: apis-php-class.mysqlnduhconnection 21.9.4.46 `MysqlndUhConnection::queryReadResultsetHeader' ......................................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::queryReadResultsetHeader' Read a result set header *Description* public boolMysqlndUhConnection::queryReadResultsetHeader mysqlnd_connectionconnection mysqlnd_statementmysqlnd_stmt Read a result set header. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. mysqlnd_stmt Mysqlnd statement handle. Do not modify! Set to NULL , if function is not used in the context of a prepared statement. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* query("SELECT 'Welcome mysqlnd_uh!' FROM DUAL"); var_dump($res->fetch_assoc()); ?> The above example will output: proxy::queryReadResultsetHeader(array ( 0 => NULL, 1 => NULL, )) proxy::queryReadResultsetHeader returns true array(1) { ["Welcome mysqlnd_uh!"]=> string(19) "Welcome mysqlnd_uh!" } *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy.  File: manual.info, Node: apis-php-mysqlnduhconnection.reapquery, Next: apis-php-mysqlnduhconnection.refreshserver, Prev: apis-php-mysqlnduhconnection.queryreadresultsetheader, Up: apis-php-class.mysqlnduhconnection 21.9.4.47 `MysqlndUhConnection::reapQuery' .......................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::reapQuery' Get result from async query *Description* public boolMysqlndUhConnection::reapQuery mysqlnd_connectionconnection Get result from async query. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* query("SELECT 1 as 'one', SLEEP(1) AS _sleep FROM DUAL", MYSQLI_ASYNC | MYSQLI_USE_RESULT); $conn2->query("SELECT 1.1 as 'one dot one' FROM DUAL", MYSQLI_ASYNC | MYSQLI_USE_RESULT); $links = array( $conn1->thread_id => array('link' => $conn1, 'processed' => false), $conn2->thread_id => array('link' => $conn2, 'processed' => false) ); $saved_errors = array(); do { $poll_links = $poll_errors = $poll_reject = array(); foreach ($links as $thread_id => $link) { if (!$link['processed']) { $poll_links[] = $link['link']; $poll_errors[] = $link['link']; $poll_reject[] = $link['link']; } } if (0 == count($poll_links)) break; if (0 == ($num_ready = mysqli_poll($poll_links, $poll_errors, $poll_reject, 0, 200000))) continue; if (!empty($poll_errors)) { die(var_dump($poll_errors)); } foreach ($poll_links as $link) { $thread_id = mysqli_thread_id($link); $links[$thread_id]['processed'] = true; if (is_object($res = mysqli_reap_async_query($link))) { // result set object while ($row = mysqli_fetch_assoc($res)) { // eat up all results var_dump($row); } mysqli_free_result($res); } else { // either there is no result (no SELECT) or there is an error if (mysqli_errno($link) > 0) { $saved_errors[$thread_id] = mysqli_errno($link); printf("'%s' caused %d\n", $links[$thread_id]['query'], mysqli_errno($link)); } } } } while (true); ?> The above example will output: proxy::reapQuery(array ( 0 => NULL, )) proxy::reapQuery returns true array(1) { ["one dot one"]=> string(3) "1.1" } proxy::reapQuery(array ( 0 => NULL, )) proxy::reapQuery returns true array(2) { ["one"]=> string(1) "1" ["_sleep"]=> string(1) "0" } *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_real_async_query' (http://www.php.net/mysqli_real_async_query)  File: manual.info, Node: apis-php-mysqlnduhconnection.refreshserver, Next: apis-php-mysqlnduhconnection.restartpsession, Prev: apis-php-mysqlnduhconnection.reapquery, Up: apis-php-class.mysqlnduhconnection 21.9.4.48 `MysqlndUhConnection::refreshServer' .............................................. Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::refreshServer' Flush or reset tables and caches *Description* public boolMysqlndUhConnection::refreshServer mysqlnd_connectionconnection intoptions Flush or reset tables and caches. *Warning*: This function is currently not documented; only its argument list is available. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. options What to refresh. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* The above example will output: proxy::refreshServer(array ( 0 => NULL, 1 => 1, )) proxy::refreshServer returns false *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy.  File: manual.info, Node: apis-php-mysqlnduhconnection.restartpsession, Next: apis-php-mysqlnduhconnection.selectdb, Prev: apis-php-mysqlnduhconnection.refreshserver, Up: apis-php-class.mysqlnduhconnection 21.9.4.49 `MysqlndUhConnection::restartPSession' ................................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::restartPSession' Restart a persistent mysqlnd connection *Description* public boolMysqlndUhConnection::restartPSession mysqlnd_connectionconnection Restart a persistent mysqlnd connection. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* ping(); ?> The above example will output: proxy::restartPSession(array ( 0 => NULL, )) proxy::restartPSession returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy.  File: manual.info, Node: apis-php-mysqlnduhconnection.selectdb, Next: apis-php-mysqlnduhconnection.sendclose, Prev: apis-php-mysqlnduhconnection.restartpsession, Up: apis-php-class.mysqlnduhconnection 21.9.4.50 `MysqlndUhConnection::selectDb' ......................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::selectDb' Selects the default database for database queries *Description* public boolMysqlndUhConnection::selectDb mysqlnd_connectionconnection stringdatabase Selects the default database for database queries. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. database The database name. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* select_db("mysql"); ?> The above example will output: proxy::selectDb(array ( 0 => NULL, 1 => 'mysql', )) proxy::selectDb returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_select_db' `mysql_select_db'  File: manual.info, Node: apis-php-mysqlnduhconnection.sendclose, Next: apis-php-mysqlnduhconnection.sendquery, Prev: apis-php-mysqlnduhconnection.selectdb, Up: apis-php-class.mysqlnduhconnection 21.9.4.51 `MysqlndUhConnection::sendClose' .......................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::sendClose' Sends a close command to MySQL *Description* public boolMysqlndUhConnection::sendClose mysqlnd_connectionconnection Sends a close command to MySQL. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* close(); ?> The above example will output: proxy::sendClose(array ( 0 => NULL, )) proxy::sendClose returns true proxy::sendClose(array ( 0 => NULL, )) proxy::sendClose returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy.  File: manual.info, Node: apis-php-mysqlnduhconnection.sendquery, Next: apis-php-mysqlnduhconnection.serverdumpdebuginformation, Prev: apis-php-mysqlnduhconnection.sendclose, Up: apis-php-class.mysqlnduhconnection 21.9.4.52 `MysqlndUhConnection::sendQuery' .......................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::sendQuery' Sends a query to MySQL *Description* public boolMysqlndUhConnection::sendQuery mysqlnd_connectionconnection stringquery Sends a query to MySQL. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. query The query string. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* query("SELECT 1"); ?> The above example will output: proxy::sendQuery(array ( 0 => NULL, 1 => 'SELECT 1', )) proxy::sendQuery returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy.  File: manual.info, Node: apis-php-mysqlnduhconnection.serverdumpdebuginformation, Next: apis-php-mysqlnduhconnection.setautocommit, Prev: apis-php-mysqlnduhconnection.sendquery, Up: apis-php-class.mysqlnduhconnection 21.9.4.53 `MysqlndUhConnection::serverDumpDebugInformation' ........................................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::serverDumpDebugInformation' Dump debugging information into the log for the MySQL server *Description* public boolMysqlndUhConnection::serverDumpDebugInformation mysqlnd_connectionconnection Dump debugging information into the log for the MySQL server. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* dump_debug_info(); ?> The above example will output: proxy::serverDumpDebugInformation(array ( 0 => NULL, )) proxy::serverDumpDebugInformation returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_dump_debug_info'  File: manual.info, Node: apis-php-mysqlnduhconnection.setautocommit, Next: apis-php-mysqlnduhconnection.setcharset, Prev: apis-php-mysqlnduhconnection.serverdumpdebuginformation, Up: apis-php-class.mysqlnduhconnection 21.9.4.54 `MysqlndUhConnection::setAutocommit' .............................................. Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::setAutocommit' Turns on or off auto-committing database modifications *Description* public boolMysqlndUhConnection::setAutocommit mysqlnd_connectionconnection intmode Turns on or off auto-committing database modifications *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. mode Whether to turn on auto-commit or not. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* autocommit(false); $mysqli->autocommit(true); ?> The above example will output: proxy::setAutocommit(array ( 0 => NULL, 1 => 0, )) proxy::setAutocommit returns true proxy::setAutocommit(array ( 0 => NULL, 1 => 1, )) proxy::setAutocommit returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_autocommit'  File: manual.info, Node: apis-php-mysqlnduhconnection.setcharset, Next: apis-php-mysqlnduhconnection.setclientoption, Prev: apis-php-mysqlnduhconnection.setautocommit, Up: apis-php-class.mysqlnduhconnection 21.9.4.55 `MysqlndUhConnection::setCharset' ........................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::setCharset' Sets the default client character set *Description* public boolMysqlndUhConnection::setCharset mysqlnd_connectionconnection stringcharset Sets the default client character set. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. charset The charset to be set as default. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* set_charset("latin1"); ?> The above example will output: proxy::setCharset(array ( 0 => NULL, 1 => 'latin1', )) proxy::setCharset returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_set_charset'  File: manual.info, Node: apis-php-mysqlnduhconnection.setclientoption, Next: apis-php-mysqlnduhconnection.setserveroption, Prev: apis-php-mysqlnduhconnection.setcharset, Up: apis-php-class.mysqlnduhconnection 21.9.4.56 `MysqlndUhConnection::setClientOption' ................................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::setClientOption' Sets a client option *Description* public boolMysqlndUhConnection::setClientOption mysqlnd_connectionconnection intoption intvalue Sets a client option. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. option The option to be set. 3. value Optional option value, if required. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* "MYSQLND_UH_MYSQLND_OPTION_OPT_CONNECT_TIMEOUT", MYSQLND_UH_MYSQLND_OPTION_OPT_COMPRESS => "MYSQLND_UH_MYSQLND_OPTION_OPT_COMPRESS", MYSQLND_UH_MYSQLND_OPTION_OPT_NAMED_PIPE => "MYSQLND_UH_MYSQLND_OPTION_OPT_NAMED_PIPE", MYSQLND_UH_MYSQLND_OPTION_INIT_COMMAND => "MYSQLND_UH_MYSQLND_OPTION_INIT_COMMAND", MYSQLND_UH_MYSQLND_READ_DEFAULT_FILE => "MYSQLND_UH_MYSQLND_READ_DEFAULT_FILE", MYSQLND_UH_MYSQLND_READ_DEFAULT_GROUP => "MYSQLND_UH_MYSQLND_READ_DEFAULT_GROUP", MYSQLND_UH_MYSQLND_SET_CHARSET_DIR => "MYSQLND_UH_MYSQLND_SET_CHARSET_DIR", MYSQLND_UH_MYSQLND_SET_CHARSET_NAME => "MYSQLND_UH_MYSQLND_SET_CHARSET_NAME", MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE => "MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE", MYSQLND_UH_MYSQLND_OPT_PROTOCOL => "MYSQLND_UH_MYSQLND_OPT_PROTOCOL", MYSQLND_UH_MYSQLND_SHARED_MEMORY_BASE_NAME => "MYSQLND_UH_MYSQLND_SHARED_MEMORY_BASE_NAME", MYSQLND_UH_MYSQLND_OPT_READ_TIMEOUT => "MYSQLND_UH_MYSQLND_OPT_READ_TIMEOUT", MYSQLND_UH_MYSQLND_OPT_WRITE_TIMEOUT => "MYSQLND_UH_MYSQLND_OPT_WRITE_TIMEOUT", MYSQLND_UH_MYSQLND_OPT_USE_RESULT => "MYSQLND_UH_MYSQLND_OPT_USE_RESULT", MYSQLND_UH_MYSQLND_OPT_USE_REMOTE_CONNECTION => "MYSQLND_UH_MYSQLND_OPT_USE_REMOTE_CONNECTION", MYSQLND_UH_MYSQLND_OPT_USE_EMBEDDED_CONNECTION => "MYSQLND_UH_MYSQLND_OPT_USE_EMBEDDED_CONNECTION", MYSQLND_UH_MYSQLND_OPT_GUESS_CONNECTION => "MYSQLND_UH_MYSQLND_OPT_GUESS_CONNECTION", MYSQLND_UH_MYSQLND_SET_CLIENT_IP => "MYSQLND_UH_MYSQLND_SET_CLIENT_IP", MYSQLND_UH_MYSQLND_SECURE_AUTH => "MYSQLND_UH_MYSQLND_SECURE_AUTH", MYSQLND_UH_MYSQLND_REPORT_DATA_TRUNCATION => "MYSQLND_UH_MYSQLND_REPORT_DATA_TRUNCATION", MYSQLND_UH_MYSQLND_OPT_RECONNECT => "MYSQLND_UH_MYSQLND_OPT_RECONNECT", MYSQLND_UH_MYSQLND_OPT_SSL_VERIFY_SERVER_CERT => "MYSQLND_UH_MYSQLND_OPT_SSL_VERIFY_SERVER_CERT", MYSQLND_UH_MYSQLND_OPT_NET_CMD_BUFFER_SIZE => "MYSQLND_UH_MYSQLND_OPT_NET_CMD_BUFFER_SIZE", MYSQLND_UH_MYSQLND_OPT_NET_READ_BUFFER_SIZE => "MYSQLND_UH_MYSQLND_OPT_NET_READ_BUFFER_SIZE", MYSQLND_UH_MYSQLND_OPT_SSL_KEY => "MYSQLND_UH_MYSQLND_OPT_SSL_KEY", MYSQLND_UH_MYSQLND_OPT_SSL_CERT => "MYSQLND_UH_MYSQLND_OPT_SSL_CERT", MYSQLND_UH_MYSQLND_OPT_SSL_CA => "MYSQLND_UH_MYSQLND_OPT_SSL_CA", MYSQLND_UH_MYSQLND_OPT_SSL_CAPATH => "MYSQLND_UH_MYSQLND_OPT_SSL_CAPATH", MYSQLND_UH_MYSQLND_OPT_SSL_CIPHER => "MYSQLND_UH_MYSQLND_OPT_SSL_CIPHER", MYSQLND_UH_MYSQLND_OPT_SSL_PASSPHRASE => "MYSQLND_UH_MYSQLND_OPT_SSL_PASSPHRASE", MYSQLND_UH_SERVER_OPTION_PLUGIN_DIR => "MYSQLND_UH_SERVER_OPTION_PLUGIN_DIR", MYSQLND_UH_SERVER_OPTION_DEFAULT_AUTH => "MYSQLND_UH_SERVER_OPTION_DEFAULT_AUTH", MYSQLND_UH_SERVER_OPTION_SET_CLIENT_IP => "MYSQLND_UH_SERVER_OPTION_SET_CLIENT_IP" ); if (version_compare(PHP_VERSION, '5.3.99-dev', '>')) { $mapping[MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET] = "MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET"; $mapping[MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL] = "MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL"; } if (defined("MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE")) { /* special mysqlnd build */ $mapping["MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE"] = "MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE"; } return (isset($mapping[$option])) ? $mapping[$option] : 'unknown'; } class proxy extends MysqlndUhConnection { public function setClientOption($res, $option, $value) { printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true)); printf("Option '%s' set to %s\n", client_option_to_string($option), var_export($value, true)); $ret = parent::setClientOption($res, $option, $value); printf("%s returns %s\n", __METHOD__, var_export($ret, true)); return $ret; } } mysqlnd_uh_set_connection_proxy(new proxy()); $mysqli = new mysqli("localhost", "root", "", "test"); ?> The above example will output: proxy::setClientOption(array ( 0 => NULL, 1 => 210, 2 => 3221225472, )) Option 'MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET' set to 3221225472 proxy::setClientOption returns true proxy::setClientOption(array ( 0 => NULL, 1 => 211, 2 => 'mysql_native_password', )) Option 'MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL' set to 'mysql_native_password' proxy::setClientOption returns true proxy::setClientOption(array ( 0 => NULL, 1 => 8, 2 => 1, )) Option 'MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE' set to 1 proxy::setClientOption returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_real_connect' `mysqli_options'  File: manual.info, Node: apis-php-mysqlnduhconnection.setserveroption, Next: apis-php-mysqlnduhconnection.shutdownserver, Prev: apis-php-mysqlnduhconnection.setclientoption, Up: apis-php-class.mysqlnduhconnection 21.9.4.57 `MysqlndUhConnection::setServerOption' ................................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::setServerOption' Sets a server option *Description* public voidMysqlndUhConnection::setServerOption mysqlnd_connectionconnection intoption Sets a server option. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. option The option to be set. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* multi_query("SELECT 1; SELECT 2"); ?> The above example will output: proxy::setServerOption(array ( 0 => NULL, 1 => 0, )) Option 'MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON' set proxy::setServerOption returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_real_connect' `mysqli_options' `mysqli_multi_query'  File: manual.info, Node: apis-php-mysqlnduhconnection.shutdownserver, Next: apis-php-mysqlnduhconnection.simplecommand, Prev: apis-php-mysqlnduhconnection.setserveroption, Up: apis-php-class.mysqlnduhconnection 21.9.4.58 `MysqlndUhConnection::shutdownServer' ............................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::shutdownServer' The shutdownServer purpose *Description* public voidMysqlndUhConnection::shutdownServer stringMYSQLND_UH_RES_MYSQLND_NAME string"level" *Warning*: This function is currently not documented; only its argument list is available. *Parameters* 1. MYSQLND_UH_RES_MYSQLND_NAME 2. "level" *Return Values*  File: manual.info, Node: apis-php-mysqlnduhconnection.simplecommand, Next: apis-php-mysqlnduhconnection.simplecommandhandleresponse, Prev: apis-php-mysqlnduhconnection.shutdownserver, Up: apis-php-class.mysqlnduhconnection 21.9.4.59 `MysqlndUhConnection::simpleCommand' .............................................. Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::simpleCommand' Sends a basic COM_* command *Description* public boolMysqlndUhConnection::simpleCommand mysqlnd_connectionconnection intcommand stringarg intok_packet boolsilent boolignore_upsert_status Sends a basic COM_* command to MySQL. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. command The COM command to be send. 3. arg Optional COM command arguments. 4. ok_packet The OK packet type. 5. silent Whether mysqlnd may emit errors. 6. ignore_upsert_status Whether to ignore `UPDATE'/`INSERT' status. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* "MYSQLND_UH_MYSQLND_COM_SLEEP", MYSQLND_UH_MYSQLND_COM_QUIT => "MYSQLND_UH_MYSQLND_COM_QUIT", MYSQLND_UH_MYSQLND_COM_INIT_DB => "MYSQLND_UH_MYSQLND_COM_INIT_DB", MYSQLND_UH_MYSQLND_COM_QUERY => "MYSQLND_UH_MYSQLND_COM_QUERY", MYSQLND_UH_MYSQLND_COM_FIELD_LIST => "MYSQLND_UH_MYSQLND_COM_FIELD_LIST", MYSQLND_UH_MYSQLND_COM_CREATE_DB => "MYSQLND_UH_MYSQLND_COM_CREATE_DB", MYSQLND_UH_MYSQLND_COM_DROP_DB => "MYSQLND_UH_MYSQLND_COM_DROP_DB", MYSQLND_UH_MYSQLND_COM_REFRESH => "MYSQLND_UH_MYSQLND_COM_REFRESH", MYSQLND_UH_MYSQLND_COM_SHUTDOWN => "MYSQLND_UH_MYSQLND_COM_SHUTDOWN", MYSQLND_UH_MYSQLND_COM_STATISTICS => "MYSQLND_UH_MYSQLND_COM_STATISTICS", MYSQLND_UH_MYSQLND_COM_PROCESS_INFO => "MYSQLND_UH_MYSQLND_COM_PROCESS_INFO", MYSQLND_UH_MYSQLND_COM_CONNECT => "MYSQLND_UH_MYSQLND_COM_CONNECT", MYSQLND_UH_MYSQLND_COM_PROCESS_KILL => "MYSQLND_UH_MYSQLND_COM_PROCESS_KILL", MYSQLND_UH_MYSQLND_COM_DEBUG => "MYSQLND_UH_MYSQLND_COM_DEBUG", MYSQLND_UH_MYSQLND_COM_PING => "MYSQLND_UH_MYSQLND_COM_PING", MYSQLND_UH_MYSQLND_COM_TIME => "MYSQLND_UH_MYSQLND_COM_TIME", MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT => "MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT", MYSQLND_UH_MYSQLND_COM_CHANGE_USER => "MYSQLND_UH_MYSQLND_COM_CHANGE_USER", MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP => "MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP", MYSQLND_UH_MYSQLND_COM_TABLE_DUMP => "MYSQLND_UH_MYSQLND_COM_TABLE_DUMP", MYSQLND_UH_MYSQLND_COM_CONNECT_OUT => "MYSQLND_UH_MYSQLND_COM_CONNECT_OUT", MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED => "MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED", MYSQLND_UH_MYSQLND_COM_STMT_PREPARE => "MYSQLND_UH_MYSQLND_COM_STMT_PREPARE", MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE => "MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE", MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA => "MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA", MYSQLND_UH_MYSQLND_COM_STMT_CLOSE => "MYSQLND_UH_MYSQLND_COM_STMT_CLOSE", MYSQLND_UH_MYSQLND_COM_STMT_RESET => "MYSQLND_UH_MYSQLND_COM_STMT_RESET", MYSQLND_UH_MYSQLND_COM_SET_OPTION => "MYSQLND_UH_MYSQLND_COM_SET_OPTION", MYSQLND_UH_MYSQLND_COM_STMT_FETCH => "MYSQLND_UH_MYSQLND_COM_STMT_FETCH", MYSQLND_UH_MYSQLND_COM_DAEMON => "MYSQLND_UH_MYSQLND_COM_DAEMON", MYSQLND_UH_MYSQLND_COM_END => "MYSQLND_UH_MYSQLND_COM_END", ); return (isset($mapping[$command])) ? $mapping[$command] : 'unknown'; } function ok_packet_2_string($ok_packet) { $mapping = array( MYSQLND_UH_MYSQLND_PROT_GREET_PACKET => "MYSQLND_UH_MYSQLND_PROT_GREET_PACKET", MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET => "MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET", MYSQLND_UH_MYSQLND_PROT_OK_PACKET => "MYSQLND_UH_MYSQLND_PROT_OK_PACKET", MYSQLND_UH_MYSQLND_PROT_EOF_PACKET => "MYSQLND_UH_MYSQLND_PROT_EOF_PACKET", MYSQLND_UH_MYSQLND_PROT_CMD_PACKET => "MYSQLND_UH_MYSQLND_PROT_CMD_PACKET", MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET", MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET", MYSQLND_UH_MYSQLND_PROT_ROW_PACKET => "MYSQLND_UH_MYSQLND_PROT_ROW_PACKET", MYSQLND_UH_MYSQLND_PROT_STATS_PACKET => "MYSQLND_UH_MYSQLND_PROT_STATS_PACKET", MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET => "MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET", MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET => "MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET", MYSQLND_UH_MYSQLND_PROT_LAST => "MYSQLND_UH_MYSQLND_PROT_LAST", ); return (isset($mapping[$ok_packet])) ? $mapping[$ok_packet] : 'unknown'; } class proxy extends MysqlndUhConnection { public function simpleCommand($conn, $command, $arg, $ok_packet, $silent, $ignore_upsert_status) { printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true)); printf("Command '%s'\n", server_cmd_2_string($command)); printf("OK packet '%s'\n", ok_packet_2_string($ok_packet)); $ret = parent::simpleCommand($conn, $command, $arg, $ok_packet, $silent, $ignore_upsert_status); printf("%s returns %s\n", __METHOD__, var_export($ret, true)); return $ret; } } mysqlnd_uh_set_connection_proxy(new proxy()); $mysqli = new mysqli("localhost", "root", "", "test"); $mysqli->query("SELECT 1"); ?> The above example will output: proxy::simpleCommand(array ( 0 => NULL, 1 => 3, 2 => 'SELECT 1', 3 => 13, 4 => false, 5 => false, )) Command 'MYSQLND_UH_MYSQLND_COM_QUERY' OK packet 'MYSQLND_UH_MYSQLND_PROT_LAST' proxy::simpleCommand returns true :)proxy::simpleCommand(array ( 0 => NULL, 1 => 1, 2 => '', 3 => 13, 4 => true, 5 => true, )) Command 'MYSQLND_UH_MYSQLND_COM_QUIT' OK packet 'MYSQLND_UH_MYSQLND_PROT_LAST' proxy::simpleCommand returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy.  File: manual.info, Node: apis-php-mysqlnduhconnection.simplecommandhandleresponse, Next: apis-php-mysqlnduhconnection.sslset, Prev: apis-php-mysqlnduhconnection.simplecommand, Up: apis-php-class.mysqlnduhconnection 21.9.4.60 `MysqlndUhConnection::simpleCommandHandleResponse' ............................................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::simpleCommandHandleResponse' Process a response for a basic COM_* command send to the client *Description* public boolMysqlndUhConnection::simpleCommandHandleResponse mysqlnd_connectionconnection intok_packet boolsilent intcommand boolignore_upsert_status Process a response for a basic COM_* command send to the client. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. ok_packet The OK packet type. 3. silent Whether mysqlnd may emit errors. 4. command The COM command to process results from. 5. ignore_upsert_status Whether to ignore `UPDATE'/`INSERT' status. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* "MYSQLND_UH_MYSQLND_COM_SLEEP", MYSQLND_UH_MYSQLND_COM_QUIT => "MYSQLND_UH_MYSQLND_COM_QUIT", MYSQLND_UH_MYSQLND_COM_INIT_DB => "MYSQLND_UH_MYSQLND_COM_INIT_DB", MYSQLND_UH_MYSQLND_COM_QUERY => "MYSQLND_UH_MYSQLND_COM_QUERY", MYSQLND_UH_MYSQLND_COM_FIELD_LIST => "MYSQLND_UH_MYSQLND_COM_FIELD_LIST", MYSQLND_UH_MYSQLND_COM_CREATE_DB => "MYSQLND_UH_MYSQLND_COM_CREATE_DB", MYSQLND_UH_MYSQLND_COM_DROP_DB => "MYSQLND_UH_MYSQLND_COM_DROP_DB", MYSQLND_UH_MYSQLND_COM_REFRESH => "MYSQLND_UH_MYSQLND_COM_REFRESH", MYSQLND_UH_MYSQLND_COM_SHUTDOWN => "MYSQLND_UH_MYSQLND_COM_SHUTDOWN", MYSQLND_UH_MYSQLND_COM_STATISTICS => "MYSQLND_UH_MYSQLND_COM_STATISTICS", MYSQLND_UH_MYSQLND_COM_PROCESS_INFO => "MYSQLND_UH_MYSQLND_COM_PROCESS_INFO", MYSQLND_UH_MYSQLND_COM_CONNECT => "MYSQLND_UH_MYSQLND_COM_CONNECT", MYSQLND_UH_MYSQLND_COM_PROCESS_KILL => "MYSQLND_UH_MYSQLND_COM_PROCESS_KILL", MYSQLND_UH_MYSQLND_COM_DEBUG => "MYSQLND_UH_MYSQLND_COM_DEBUG", MYSQLND_UH_MYSQLND_COM_PING => "MYSQLND_UH_MYSQLND_COM_PING", MYSQLND_UH_MYSQLND_COM_TIME => "MYSQLND_UH_MYSQLND_COM_TIME", MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT => "MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT", MYSQLND_UH_MYSQLND_COM_CHANGE_USER => "MYSQLND_UH_MYSQLND_COM_CHANGE_USER", MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP => "MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP", MYSQLND_UH_MYSQLND_COM_TABLE_DUMP => "MYSQLND_UH_MYSQLND_COM_TABLE_DUMP", MYSQLND_UH_MYSQLND_COM_CONNECT_OUT => "MYSQLND_UH_MYSQLND_COM_CONNECT_OUT", MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED => "MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED", MYSQLND_UH_MYSQLND_COM_STMT_PREPARE => "MYSQLND_UH_MYSQLND_COM_STMT_PREPARE", MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE => "MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE", MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA => "MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA", MYSQLND_UH_MYSQLND_COM_STMT_CLOSE => "MYSQLND_UH_MYSQLND_COM_STMT_CLOSE", MYSQLND_UH_MYSQLND_COM_STMT_RESET => "MYSQLND_UH_MYSQLND_COM_STMT_RESET", MYSQLND_UH_MYSQLND_COM_SET_OPTION => "MYSQLND_UH_MYSQLND_COM_SET_OPTION", MYSQLND_UH_MYSQLND_COM_STMT_FETCH => "MYSQLND_UH_MYSQLND_COM_STMT_FETCH", MYSQLND_UH_MYSQLND_COM_DAEMON => "MYSQLND_UH_MYSQLND_COM_DAEMON", MYSQLND_UH_MYSQLND_COM_END => "MYSQLND_UH_MYSQLND_COM_END", ); return (isset($mapping[$command])) ? $mapping[$command] : 'unknown'; } function ok_packet_2_string($ok_packet) { $mapping = array( MYSQLND_UH_MYSQLND_PROT_GREET_PACKET => "MYSQLND_UH_MYSQLND_PROT_GREET_PACKET", MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET => "MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET", MYSQLND_UH_MYSQLND_PROT_OK_PACKET => "MYSQLND_UH_MYSQLND_PROT_OK_PACKET", MYSQLND_UH_MYSQLND_PROT_EOF_PACKET => "MYSQLND_UH_MYSQLND_PROT_EOF_PACKET", MYSQLND_UH_MYSQLND_PROT_CMD_PACKET => "MYSQLND_UH_MYSQLND_PROT_CMD_PACKET", MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET", MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET", MYSQLND_UH_MYSQLND_PROT_ROW_PACKET => "MYSQLND_UH_MYSQLND_PROT_ROW_PACKET", MYSQLND_UH_MYSQLND_PROT_STATS_PACKET => "MYSQLND_UH_MYSQLND_PROT_STATS_PACKET", MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET => "MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET", MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET => "MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET", MYSQLND_UH_MYSQLND_PROT_LAST => "MYSQLND_UH_MYSQLND_PROT_LAST", ); return (isset($mapping[$ok_packet])) ? $mapping[$ok_packet] : 'unknown'; } class proxy extends MysqlndUhConnection { public function simpleCommandHandleResponse($conn, $ok_packet, $silent, $command, $ignore_upsert_status) { printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true)); printf("Command '%s'\n", server_cmd_2_string($command)); printf("OK packet '%s'\n", ok_packet_2_string($ok_packet)); $ret = parent::simpleCommandHandleResponse($conn, $ok_packet, $silent, $command, $ignore_upsert_status); printf("%s returns %s\n", __METHOD__, var_export($ret, true)); return $ret; } } mysqlnd_uh_set_connection_proxy(new proxy()); $mysql = mysql_connect("localhost", "root", ""); mysql_query("SELECT 1 FROM DUAL", $mysql); ?> The above example will output: proxy::simpleCommandHandleResponse(array ( 0 => NULL, 1 => 5, 2 => false, 3 => 27, 4 => true, )) Command 'MYSQLND_UH_MYSQLND_COM_SET_OPTION' OK packet 'MYSQLND_UH_MYSQLND_PROT_EOF_PACKET' proxy::simpleCommandHandleResponse returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy.  File: manual.info, Node: apis-php-mysqlnduhconnection.sslset, Next: apis-php-mysqlnduhconnection.stmtinit, Prev: apis-php-mysqlnduhconnection.simplecommandhandleresponse, Up: apis-php-class.mysqlnduhconnection 21.9.4.61 `MysqlndUhConnection::sslSet' ....................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::sslSet' Used for establishing secure connections using SSL *Description* public boolMysqlndUhConnection::sslSet mysqlnd_connectionconnection stringkey stringcert stringca stringcapath stringcipher Used for establishing secure connections using SSL. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! 2. key The path name to the key file. 3. cert The path name to the certificate file. 4. ca The path name to the certificate authority file. 5. capath The pathname to a directory that contains trusted SSL CA certificates in PEM format. 6. cipher A list of allowable ciphers to use for SSL encryption. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* ssl_set("key", "cert", "ca", "capath", "cipher"); ?> The above example will output: proxy::sslSet(array ( 0 => NULL, 1 => 'key', 2 => 'cert', 3 => 'ca', 4 => 'capath', 5 => 'cipher', )) proxy::sslSet returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_ssl_set'  File: manual.info, Node: apis-php-mysqlnduhconnection.stmtinit, Next: apis-php-mysqlnduhconnection.storeresult, Prev: apis-php-mysqlnduhconnection.sslset, Up: apis-php-class.mysqlnduhconnection 21.9.4.62 `MysqlndUhConnection::stmtInit' ......................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::stmtInit' Initializes a statement and returns a resource for use with mysqli_statement::prepare *Description* public resourceMysqlndUhConnection::stmtInit mysqlnd_connectionconnection Initializes a statement and returns a resource for use with mysqli_statement::prepare. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Resource of type `Mysqlnd Prepared Statement (internal only - you must not modify it!)'. The documentation may also refer to such resources using the alias name `mysqlnd_prepared_statement'. *Examples* prepare("SELECT 1 AS _one FROM DUAL"); $stmt->execute(); $one = NULL; $stmt->bind_result($one); $stmt->fetch(); var_dump($one); ?> The above example will output: proxy::stmtInit(array ( 0 => NULL, )) resource(19) of type (Mysqlnd Connection) proxy::stmtInit returns NULL resource(246) of type (Mysqlnd Prepared Statement (internal only - you must not modify it!)) int(1) *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_stmt_init'  File: manual.info, Node: apis-php-mysqlnduhconnection.storeresult, Next: apis-php-mysqlnduhconnection.txcommit, Prev: apis-php-mysqlnduhconnection.stmtinit, Up: apis-php-class.mysqlnduhconnection 21.9.4.63 `MysqlndUhConnection::storeResult' ............................................ Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::storeResult' Transfers a result set from the last query *Description* public resourceMysqlndUhConnection::storeResult mysqlnd_connectionconnection Transfers a result set from the last query. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Resource of type `Mysqlnd Resultset (internal only - you must not modify it!)'. The documentation may also refer to such resources using the alias name `mysqlnd_resultset'. *Examples* query("SELECT 'Also called buffered result' AS _msg FROM DUAL"); var_dump($res->fetch_assoc()); $mysqli->real_query("SELECT 'Good morning!' AS _msg FROM DUAL"); $res = $mysqli->store_result(); var_dump($res->fetch_assoc()); ?> The above example will output: proxy::storeResult(array ( 0 => NULL, )) proxy::storeResult returns NULL resource(475) of type (Mysqlnd Resultset (internal only - you must not modify it!)) array(1) { ["_msg"]=> string(27) "Also called buffered result" } proxy::storeResult(array ( 0 => NULL, )) proxy::storeResult returns NULL resource(730) of type (Mysqlnd Resultset (internal only - you must not modify it!)) array(1) { ["_msg"]=> string(13) "Good morning!" } *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_store_result' `mysqli_real_query'  File: manual.info, Node: apis-php-mysqlnduhconnection.txcommit, Next: apis-php-mysqlnduhconnection.txrollback, Prev: apis-php-mysqlnduhconnection.storeresult, Up: apis-php-class.mysqlnduhconnection 21.9.4.64 `MysqlndUhConnection::txCommit' ......................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::txCommit' Commits the current transaction *Description* public boolMysqlndUhConnection::txCommit mysqlnd_connectionconnection Commits the current transaction. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* commit(); ?> The above example will output: proxy::txCommit(array ( 0 => NULL, )) proxy::txCommit returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_commit'  File: manual.info, Node: apis-php-mysqlnduhconnection.txrollback, Next: apis-php-mysqlnduhconnection.useresult, Prev: apis-php-mysqlnduhconnection.txcommit, Up: apis-php-class.mysqlnduhconnection 21.9.4.65 `MysqlndUhConnection::txRollback' ........................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::txRollback' Rolls back current transaction *Description* public boolMysqlndUhConnection::txRollback mysqlnd_connectionconnection Rolls back current transaction. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* rollback(); ?> The above example will output: proxy::txRollback(array ( 0 => NULL, )) proxy::txRollback returns true *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_commit'  File: manual.info, Node: apis-php-mysqlnduhconnection.useresult, Prev: apis-php-mysqlnduhconnection.txrollback, Up: apis-php-class.mysqlnduhconnection 21.9.4.66 `MysqlndUhConnection::useResult' .......................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhConnection::useResult' Initiate a result set retrieval *Description* public resourceMysqlndUhConnection::useResult mysqlnd_connectionconnection Initiate a result set retrieval. *Parameters* 1. connection Mysqlnd connection handle. Do not modify! *Return Values* Resource of type `Mysqlnd Resultset (internal only - you must not modify it!)'. The documentation may also refer to such resources using the alias name `mysqlnd_resultset'. *Examples* real_query("SELECT 'Good morning!' AS _msg FROM DUAL"); $res = $mysqli->use_result(); var_dump($res->fetch_assoc()); ?> The above example will output: proxy::useResult(array ( 0 => NULL, )) proxy::useResult returns NULL resource(425) of type (Mysqlnd Resultset (internal only - you must not modify it!)) array(1) { ["_msg"]=> string(13) "Good morning!" } *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqli_use_result' `mysqli_real_query'  File: manual.info, Node: apis-php-class.mysqlnduhpreparedstatement, Next: apis-php-ref.mysqlnd-uh, Prev: apis-php-class.mysqlnduhconnection, Up: apis-php-book.mysqlnd-uh 21.9.4.67 The MysqlndUhPreparedStatement class (`MysqlndUhPreparedStatement') ............................................................................. * Menu: * apis-php-mysqlnduhpreparedstatement.construct:: `MysqlndUhPreparedStatement::__construct' * apis-php-mysqlnduhpreparedstatement.execute:: `MysqlndUhPreparedStatement::execute' * apis-php-mysqlnduhpreparedstatement.prepare:: `MysqlndUhPreparedStatement::prepare' Copyright 1997-2012 the PHP Documentation Group. MysqlndUhPreparedStatement MysqlndUhPreparedStatement Methods public MysqlndUhPreparedStatement::__construct public boolMysqlndUhPreparedStatement::execute mysqlnd_prepared_statementstatement public boolMysqlndUhPreparedStatement::prepare mysqlnd_prepared_statementstatement stringquery  File: manual.info, Node: apis-php-mysqlnduhpreparedstatement.construct, Next: apis-php-mysqlnduhpreparedstatement.execute, Prev: apis-php-class.mysqlnduhpreparedstatement, Up: apis-php-class.mysqlnduhpreparedstatement 21.9.4.68 `MysqlndUhPreparedStatement::__construct' ................................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhPreparedStatement::__construct' The __construct purpose *Description* public MysqlndUhPreparedStatement::__construct *Warning*: This function is currently not documented; only its argument list is available. *Parameters* This function has no parameters. *Return Values*  File: manual.info, Node: apis-php-mysqlnduhpreparedstatement.execute, Next: apis-php-mysqlnduhpreparedstatement.prepare, Prev: apis-php-mysqlnduhpreparedstatement.construct, Up: apis-php-class.mysqlnduhpreparedstatement 21.9.4.69 `MysqlndUhPreparedStatement::execute' ............................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhPreparedStatement::execute' Executes a prepared Query *Description* public boolMysqlndUhPreparedStatement::execute mysqlnd_prepared_statementstatement Executes a prepared Query. *Parameters* 1. statement Mysqlnd prepared statement handle. Do not modify! Resource of type `Mysqlnd Prepared Statement (internal only - you must not modify it!)'. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* prepare("SELECT 'Labskaus' AS _msg FROM DUAL"); $stmt->execute(); $msg = NULL; $stmt->bind_result($msg); $stmt->fetch(); var_dump($msg); ?> The above example will output: stmt_proxy::execute(resource(256) of type (Mysqlnd Prepared Statement (internal only - you must not modify it!)) ) stmt_proxy::execute returns true bool(true) string(8) "Labskaus" *See Also* *Note `mysqlnd_uh_set_statement_proxy': apis-php-function.mysqlnd-uh-set-statement-proxy. `mysqli_stmt_execute'  File: manual.info, Node: apis-php-mysqlnduhpreparedstatement.prepare, Prev: apis-php-mysqlnduhpreparedstatement.execute, Up: apis-php-class.mysqlnduhpreparedstatement 21.9.4.70 `MysqlndUhPreparedStatement::prepare' ............................................... Copyright 1997-2012 the PHP Documentation Group. * `MysqlndUhPreparedStatement::prepare' Prepare an SQL statement for execution *Description* public boolMysqlndUhPreparedStatement::prepare mysqlnd_prepared_statementstatement stringquery Prepare an SQL statement for execution. *Parameters* 1. statement Mysqlnd prepared statement handle. Do not modify! Resource of type `Mysqlnd Prepared Statement (internal only - you must not modify it!)'. 2. query The query to be prepared. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* prepare("SELECT 'Labskaus' AS _msg FROM DUAL"); $stmt->execute(); $msg = NULL; $stmt->bind_result($msg); $stmt->fetch(); var_dump($msg); ?> The above example will output: stmt_proxy::prepare(array ( 0 => NULL, 1 => 'SELECT \'Labskaus\' AS _msg FROM DUAL', )) stmt_proxy::prepare returns true bool(true) string(46) "No more you-know-what-I-mean for lunch, please" *See Also* *Note `mysqlnd_uh_set_statement_proxy': apis-php-function.mysqlnd-uh-set-statement-proxy. `mysqli_stmt_prepare' `mysqli_prepare'  File: manual.info, Node: apis-php-ref.mysqlnd-uh, Next: apis-php-mysqlnd-uh.changes, Prev: apis-php-class.mysqlnduhpreparedstatement, Up: apis-php-book.mysqlnd-uh 21.9.4.71 Mysqlnd_uh Functions .............................. * Menu: * apis-php-function.mysqlnd-uh-convert-to-mysqlnd:: `mysqlnd_uh_convert_to_mysqlnd' * apis-php-function.mysqlnd-uh-set-connection-proxy:: `mysqlnd_uh_set_connection_proxy' * apis-php-function.mysqlnd-uh-set-statement-proxy:: `mysqlnd_uh_set_statement_proxy' Copyright 1997-2012 the PHP Documentation Group.  File: manual.info, Node: apis-php-function.mysqlnd-uh-convert-to-mysqlnd, Next: apis-php-function.mysqlnd-uh-set-connection-proxy, Prev: apis-php-ref.mysqlnd-uh, Up: apis-php-ref.mysqlnd-uh 21.9.4.72 `mysqlnd_uh_convert_to_mysqlnd' ......................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_uh_convert_to_mysqlnd' Converts a MySQL connection handle into a mysqlnd connection handle *Description* resource mysqlnd_uh_convert_to_mysqlnd mysqlimysql_connection Converts a MySQL connection handle into a mysqlnd connection handle. After conversion you can execute mysqlnd library calls on the connection handle. This can be used to access mysqlnd functionality not made available through user space API calls. The function can be disabled with `mysqlnd_uh.enable'. If `mysqlnd_uh.enable' is set to FALSE the function will not install the proxy and always return TRUE . Additionally, an error of the type `E_WARNING' may be emitted. The error message may read like `PHP Warning: mysqlnd_uh_convert_to_mysqlnd(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false. You are not allowed to call this function [...]'. *Parameters* 1. MySQL connection handle A MySQL connection handle of type mysql, mysqli or PDO_MySQL. *Return Values* A mysqlnd connection handle. *Changelog* Changelog information for this function Version Description 5.4.0 The mysql_connection parameter can now be of type `mysql', `PDO_MySQL', or `mysqli'. Before, only the `mysqli' type was allowed. *Examples* getThreadId($mysqlnd)); /* Use SQL to fetch connection thread id */ var_dump($mysql_connection->query("SELECT CONNECTION_ID()")->fetchAll()); ?> The above example will output: int(27054) array(1) { [0]=> array(2) { ["CONNECTION_ID()"]=> string(5) "27054" [0]=> string(5) "27054" } } *See Also* `mysqlnd_uh.enable'  File: manual.info, Node: apis-php-function.mysqlnd-uh-set-connection-proxy, Next: apis-php-function.mysqlnd-uh-set-statement-proxy, Prev: apis-php-function.mysqlnd-uh-convert-to-mysqlnd, Up: apis-php-ref.mysqlnd-uh 21.9.4.73 `mysqlnd_uh_set_connection_proxy' ........................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_uh_set_connection_proxy' Installs a proxy for mysqlnd connections *Description* boolmysqlnd_uh_set_connection_proxy MysqlndUhConnectionconnection_proxy mysqlimysqli_connection Installs a proxy object to hook mysqlnd's connection objects methods. Once installed, the proxy will be used for all MySQL connections opened with mysqli, mysql or See section "apis-php-ref.pdo-mysql" in the online manual, assuming that the listed extensions are compiled to use the See section "apis-php-mysqli" in the online manual library. The function can be disabled with `mysqlnd_uh.enable'. If `mysqlnd_uh.enable' is set to FALSE the function will not install the proxy and always return TRUE . Additionally, an error of the type `E_WARNING' may be emitted. The error message may read like `PHP Warning: mysqlnd_uh_set_connection_proxy(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false. The proxy has not been installed [...]'. *Parameters* 1. connection_proxy A proxy object of type MysqlndUhConnection. 2. mysqli_connection Object of type `mysqli'. If given, the proxy will be set for this particular connection only. *Return Values* Returns TRUE on success. Otherwise, returns FALSE *Examples* query("SELECT 'No proxy installed, yet'"); class proxy extends MysqlndUhConnection { public function query($res, $query) { printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true)); $ret = parent::query($res, $query); printf("%s returns %s\n", __METHOD__, var_export($ret, true)); return $ret; } } mysqlnd_uh_set_connection_proxy(new proxy()); $mysqli->query("SELECT 'mysqlnd rocks!'"); $mysql = mysql_connect("localhost", "root", "", "test"); mysql_query("SELECT 'Ahoy Andrey!'", $mysql); $pdo = new PDO("mysql:host=localhost;dbname=test", "root", ""); $pdo->query("SELECT 'Moin Johannes!'"); ?> The above example will output: proxy::query(array ( 0 => NULL, 1 => 'SELECT \'mysqlnd rocks!\'', )) proxy::query returns true proxy::query(array ( 0 => NULL, 1 => 'SELECT \'Ahoy Andrey!\'', )) proxy::query returns true proxy::query(array ( 0 => NULL, 1 => 'SELECT \'Moin Johannes!\'', )) proxy::query returns true *See Also* *Note `mysqlnd_uh_set_statement_proxy': apis-php-function.mysqlnd-uh-set-statement-proxy. `mysqlnd_uh.enable'  File: manual.info, Node: apis-php-function.mysqlnd-uh-set-statement-proxy, Prev: apis-php-function.mysqlnd-uh-set-connection-proxy, Up: apis-php-ref.mysqlnd-uh 21.9.4.74 `mysqlnd_uh_set_statement_proxy' .......................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_uh_set_statement_proxy' Installs a proxy for mysqlnd statements *Description* boolmysqlnd_uh_set_statement_proxy MysqlndUhStatementstatement_proxy Installs a proxy for mysqlnd statements. The proxy object will be used for all mysqlnd prepared statement objects, regardless which PHP MySQL extension (mysqli, mysql, See section "apis-php-ref.pdo-mysql" in the online manual) has created them as long as the extension is compiled to use the See section "apis-php-mysqli" in the online manual library. The function can be disabled with `mysqlnd_uh.enable'. If `mysqlnd_uh.enable' is set to FALSE the function will not install the proxy and always return TRUE . Additionally, an error of the type `E_WARNING' may be emitted. The error message may read like `PHP Warning: mysqlnd_uh_set_statement_proxy(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false. The proxy has not been installed [...]'. *Parameters* 1. statement_proxy The mysqlnd statement proxy object of type `MysqlndUhStatement' *Return Values* Returns TRUE on success. Otherwise, returns FALSE *See Also* *Note `mysqlnd_uh_set_connection_proxy': apis-php-function.mysqlnd-uh-set-connection-proxy. `mysqlnd_uh.enable'  File: manual.info, Node: apis-php-mysqlnd-uh.changes, Prev: apis-php-ref.mysqlnd-uh, Up: apis-php-book.mysqlnd-uh 21.9.4.75 Change History ........................ * Menu: * apis-php-mysqlnd-uh.changes-one-o:: PECL/mysqlnd_uh 1.0 series Copyright 1997-2012 the PHP Documentation Group. The Change History lists major changes users need to be aware if upgrading from one version to another. It is a high level summary of selected changes that may impact applications or might even break backwards compatibility. See also the `CHANGES' file contained in the source for additional changelog information. The commit history is also available.  File: manual.info, Node: apis-php-mysqlnd-uh.changes-one-o, Prev: apis-php-mysqlnd-uh.changes, Up: apis-php-mysqlnd-uh.changes 21.9.4.76 PECL/mysqlnd_uh 1.0 series .................................... Copyright 1997-2012 the PHP Documentation Group. 1.0.1-alpha * Release date: TBD * Motto/theme: bug fix release Feature changes * Support of PHP 5.4.0 or later. * BC break: *Note `MysqlndUhConnection::changeUser': apis-php-mysqlnduhconnection.changeuser. requires additional `passwd_len' parameter. * BC break: MYSQLND_UH_VERSION_STR renamed to MYSQLND_UH_VERSION. MYSQLND_UH_VERSION renamed to MYSQLND_UH_VERSION_ID. * BC break: `mysqlnd_uh.enabled' configuration setting renamed to `mysqlnd_uh.enable'. 1.0.0-alpha * Release date: 08/2010 * Motto/theme: Initial release  File: manual.info, Node: apis-php-book.mysqlnd-mux, Next: apis-php-book.mysqlnd-memcache, Prev: apis-php-book.mysqlnd-uh, Up: apis-php 21.9.5 Mysqlnd connection multiplexing plugin (`mysqlnd_mux') ------------------------------------------------------------- * Menu: * apis-php-mysqlnd-mux.key-features:: Key Features * apis-php-mysqlnd-mux.limitations:: Limitations * apis-php-mysqlnd-mux.name:: About the name mysqlnd_mux * apis-php-mysqlnd-mux.concepts:: Concepts * apis-php-mysqlnd-mux.setup:: Installing/Configuring * apis-php-mysqlnd-mux.constants:: Predefined Constants * apis-php-mysqlnd-mux.changes:: Change History Copyright 1997-2012 the PHP Documentation Group. The mysqlnd multiplexing plugin (`mysqlnd_mux') multiplexes MySQL connections established by all PHP MySQL extensions that use the MySQL native driver (See section "apis-php-mysqli" in the online manual) for PHP. The MySQL native driver for PHP features an internal C API for plugins, such as the connection multiplexing plugin, which can extend the functionality of mysqlnd. See the See section "apis-php-mysqli" in the online manual for additional details about its benefits over the MySQL Client Library libmysqlclient. Mysqlnd plugins like `mysqlnd_mux' operate, for the most part, transparently from a user perspective. The connection multiplexing plugin supports all PHP applications, and all MySQL PHP extensions. It does not change existing APIs. Therefore, it can easily be used with existing PHP applications. *Note*: This is a proof-of-concept. All features are at an early stage. Not all kinds of queries are handled by the plugin yet. Thus, it cannot be used in a drop-in fashion at the moment. Please, do not use this version in production environments.  File: manual.info, Node: apis-php-mysqlnd-mux.key-features, Next: apis-php-mysqlnd-mux.limitations, Prev: apis-php-book.mysqlnd-mux, Up: apis-php-book.mysqlnd-mux 21.9.5.1 Key Features ..................... Copyright 1997-2012 the PHP Documentation Group. The key features of mysqlnd_mux are as follows: * Transparent and therefore easy to use: * Supports all of the PHP MySQL extensions. * Little to no application changes are required, dependent on the required usage scenario. * Reduces server load and connection establishment latency: * Opens less connections to the MySQL server. * Less connections to MySQL mean less work for the MySQL server. In a client-server environment scaling the server is often more difficult than scaling the client. Multiplexing helps with horizontal scale-out (scale-by-client). * Pooling saves connection time. * Multiplexed connection: multiple user handles share the same network connection. Once opened, a network connection is cached and shared among multiple user handles. There is a 1:n relationship between internal network connection and user connection handles. * Persistent connection: a network connection is kept open at the end of the web request, if the PHP deployment model allows. Thus, subsequently web requests can reuse a previously opened connection. Like other resources, network connections are bound to the scope of a process. Thus, they can be reused for all web requests served by a process.  File: manual.info, Node: apis-php-mysqlnd-mux.limitations, Next: apis-php-mysqlnd-mux.name, Prev: apis-php-mysqlnd-mux.key-features, Up: apis-php-book.mysqlnd-mux 21.9.5.2 Limitations .................... Copyright 1997-2012 the PHP Documentation Group. The proof-of-concept does not support unbuffered queries, prepared statements, and asynchronous queries. The connection pool is using a combination of the transport method and hostname as keys. As a consequence, two connections to the same host using the same transport method (TCP/IP, Unix socket, Windows named pipe) will be linked to the same pooled connection even if username and password differ. Be aware of the possible security implications. The proof-of-concept is transaction agnostic. It does not know about SQL transactions. *Note*: Applications must be aware of the consequences of connection sharing connections.  File: manual.info, Node: apis-php-mysqlnd-mux.name, Next: apis-php-mysqlnd-mux.concepts, Prev: apis-php-mysqlnd-mux.limitations, Up: apis-php-book.mysqlnd-mux 21.9.5.3 About the name mysqlnd_mux ................................... Copyright 1997-2012 the PHP Documentation Group. The shortcut `mysqlnd_mux' stands for `mysqlnd connection multiplexing plugin'.  File: manual.info, Node: apis-php-mysqlnd-mux.concepts, Next: apis-php-mysqlnd-mux.setup, Prev: apis-php-mysqlnd-mux.name, Up: apis-php-book.mysqlnd-mux 21.9.5.4 Concepts ................. * Menu: * apis-php-mysqlnd-mux.architecture:: Architecture * apis-php-mysqlnd-mux.connection_pool:: Connection pool * apis-php-mysqlnd-mux.sharing_connections:: Sharing connections Copyright 1997-2012 the PHP Documentation Group. This explains the architecture and related concepts for this plugin. Reading and understanding these concepts is required to successfully use this plugin.  File: manual.info, Node: apis-php-mysqlnd-mux.architecture, Next: apis-php-mysqlnd-mux.connection_pool, Prev: apis-php-mysqlnd-mux.concepts, Up: apis-php-mysqlnd-mux.concepts 21.9.5.5 Architecture ..................... Copyright 1997-2012 the PHP Documentation Group. The mysqlnd connection multiplexing plugin is implemented as a PHP extension. It is written in C and operates under the hood of PHP. During the startup of the PHP interpreter, in the module initialization phase of the PHP engine, it gets registered as a See section "apis-php-mysqli" in the online manual plugin to replace specific mysqlnd C methods. The mysqlnd library uses PHP streams to communicate with the MySQL server. PHP streams are accessed by the mysqlnd library through its net module. The mysqlnd connection multiplexing plugin proxies methods of the mysqlnd library net module to control opening and closing of network streams. Upon opening a user connection to MySQL using the appropriate connection functions of either See section "apis-php-mysqli" in the online manual, See section "apis-php-ref.pdo-mysql" in the online manual or See section "apis-php-mysql" in the online manual, the plugin will search its connection pool for an open network connection. If the pool contains a network connection to the host specified by the connect function using the transport method requested (TCP/IP, Unix domain socket, Windows named pipe), the pooled connection is linked to the user handle. Otherwise, a new network connection is opened, put into the poolm and associated with the user connection handle. This way, multiple user handles can be linked to the same network connection.  File: manual.info, Node: apis-php-mysqlnd-mux.connection_pool, Next: apis-php-mysqlnd-mux.sharing_connections, Prev: apis-php-mysqlnd-mux.architecture, Up: apis-php-mysqlnd-mux.concepts 21.9.5.6 Connection pool ........................ Copyright 1997-2012 the PHP Documentation Group. The plugins connection pool is created when PHP initializes its modules (`MINIT') and free'd when PHP shuts down the modules (`MSHUTDOWN'). This is the same as for persistent MySQL connections. Depending on the deployment model, the pool is used for the duration of one or multiple web requests. Network connections are bound to the lifespan of an operating system level process. If the PHP process serves multiple web requests as it is the case for Fast-CGI or threaded web server deployments, then the pooled connections can be reused over multiple connections. Because multiplexing means sharing connections, it can even happen with a threaded deployment that two threads or two distinct web requests are linked to one pooled network connections. A pooled connection is explicitly closed once the last reference to it is released. An implicit close happens when PHP shuts down its modules.  File: manual.info, Node: apis-php-mysqlnd-mux.sharing_connections, Prev: apis-php-mysqlnd-mux.connection_pool, Up: apis-php-mysqlnd-mux.concepts 21.9.5.7 Sharing connections ............................ Copyright 1997-2012 the PHP Documentation Group. The PHP mysqlnd connection multiplexing plugin changes the relationship between a users connection handle and the underlying MySQL connection. Without the plugin, every MySQL connection belongs to exactly one user connection at a time. The multiplexing plugin changes. A MySQL connection is shared among multiple user handles. There no one-to-one relation if using the plugin. Sharing pooled connections has an impact on the connection state. State changing operations from multiple user handles pointing to one MySQL connection are not isolated from each other. If, for example, a session variable is set through one user connection handle, the session variable becomes visible to all other user handles that reference the same underlying MySQL connection. This is similar in concept to connection state related phenomens described for the PHP mysqlnd replication and load balancing plugin. Please, check the *Note PECL/mysqlnd_ms documentation: apis-php-book.mysqlnd-ms. for more details on the state of a connection. The proof-of-concept takes no measures to isolate multiplexed connections from each other.  File: manual.info, Node: apis-php-mysqlnd-mux.setup, Next: apis-php-mysqlnd-mux.constants, Prev: apis-php-mysqlnd-mux.concepts, Up: apis-php-book.mysqlnd-mux 21.9.5.8 Installing/Configuring ............................... * Menu: * apis-php-mysqlnd-mux.requirements:: Requirements * apis-php-mysqlnd-mux.installation:: Installation * apis-php-mysqlnd-mux.configuration:: Runtime Configuration Copyright 1997-2012 the PHP Documentation Group.  File: manual.info, Node: apis-php-mysqlnd-mux.requirements, Next: apis-php-mysqlnd-mux.installation, Prev: apis-php-mysqlnd-mux.setup, Up: apis-php-mysqlnd-mux.setup 21.9.5.9 Requirements ..................... Copyright 1997-2012 the PHP Documentation Group. `PHP 5.5.0' or newer. Some advanced functionality requires `PHP 5.5.0' or newer. The `mysqlnd_mux' replication and load balancing plugin supports all PHP applications and all available PHP MySQL extensions (mysqli, mysql, See section "apis-php-ref.pdo-mysql" in the online manual). The PHP MySQL extension must be configured to use See section "apis-php-mysqli" in the online manual in order to be able to use the `mysqlnd_mux' plugin for See section "apis-php-mysqli" in the online manual.  File: manual.info, Node: apis-php-mysqlnd-mux.installation, Next: apis-php-mysqlnd-mux.configuration, Prev: apis-php-mysqlnd-mux.requirements, Up: apis-php-mysqlnd-mux.setup 21.9.5.10 Installation ...................... Copyright 1997-2012 the PHP Documentation Group. Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions (http://www.php.net/install.pecl). Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/mysqlnd_mux (http://pecl.php.net/package/mysqlnd_mux)  File: manual.info, Node: apis-php-mysqlnd-mux.configuration, Prev: apis-php-mysqlnd-mux.installation, Up: apis-php-mysqlnd-mux.setup 21.9.5.11 Runtime Configuration ............................... Copyright 1997-2012 the PHP Documentation Group. The behaviour of these functions is affected by settings in `php.ini'. *Mysqlnd_mux Configure Options* Name Default Changeable Changelog mysqlnd_mux.enable 0 PHP_INI_SYSTEM Here's a short explanation of the configuration directives. 1. mysqlnd_mux.enable integer Enables or disables the plugin. If disabled, the extension will not plug into See section "apis-php-mysqli" in the online manual to proxy internal See section "apis-php-mysqli" in the online manual C API calls.  File: manual.info, Node: apis-php-mysqlnd-mux.constants, Next: apis-php-mysqlnd-mux.changes, Prev: apis-php-mysqlnd-mux.setup, Up: apis-php-book.mysqlnd-mux 21.9.5.12 Predefined Constants .............................. Copyright 1997-2012 the PHP Documentation Group. The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime. _Other_ The plugins version number can be obtained using MYSQLND_MUX_VERSION or MYSQLND_MUX_VERSION_ID . MYSQLND_MUX_VERSION is the string representation of the numerical version number MYSQLND_MUX_VERSION_ID , which is an integer such as 10000. Developers can calculate the version number as follows. Unknown PHP API feature. Version (part) Example Major*10000 1*10000 = 10000 Minor*100 0*100 = 0 Patch 0 = 0 MYSQLND_MUX_VERSION_ID 10000 1. MYSQLND_MUX_VERSION (string) Plugin version string, for example, `1.0.0-prototype'. 2. MYSQLND_MUX_VERSION_ID (integer) Plugin version number, for example, 10000.  File: manual.info, Node: apis-php-mysqlnd-mux.changes, Prev: apis-php-mysqlnd-mux.constants, Up: apis-php-book.mysqlnd-mux 21.9.5.13 Change History ........................ * Menu: * apis-php-mysqlnd-mux.changes-one-o:: PECL/mysqlnd_mux 1.0 series Copyright 1997-2012 the PHP Documentation Group. This change history is a high level summary of selected changes that may impact applications and/or break backwards compatibility. See also the `CHANGES' file in the source distribution for a complete list of changes.  File: manual.info, Node: apis-php-mysqlnd-mux.changes-one-o, Prev: apis-php-mysqlnd-mux.changes, Up: apis-php-mysqlnd-mux.changes 21.9.5.14 PECL/mysqlnd_mux 1.0 series ..................................... Copyright 1997-2012 the PHP Documentation Group. 1.0.0-pre-alpha * Release date: no package released, initial check-in 09/2012 * Motto/theme: Proof of concept Initial check-in. Essentially a demo of the See section "apis-php-mysqli" in the online manual plugin API. *Note*: This is the current development series. All features are at an early stage. Changes may happen at any time without prior notice. Please, do not use this version in production environments. The documentation may not reflect all changes yet.  File: manual.info, Node: apis-php-book.mysqlnd-memcache, Next: connector-php, Prev: apis-php-book.mysqlnd-mux, Up: apis-php 21.9.6 Mysqlnd Memcache plugin (`mysqlnd_memcache') --------------------------------------------------- * Menu: * apis-php-mysqlnd-memcache.key-features:: Key Features * apis-php-mysqlnd-memcache.limitations:: Limitations * apis-php-mysqlnd-memcache.name:: On the name * apis-php-mysqlnd-memcache.quickstart:: Quickstart and Examples * apis-php-mysqlnd-memcache.setup:: Installing/Configuring * apis-php-mysqlnd-memcache.constants:: Predefined Constants * apis-php-ref.mysqlnd-memcache:: Mysqlnd_memcache Functions * apis-php-mysqlnd-memcache.changes:: Change History Copyright 1997-2012 the PHP Documentation Group. The mysqlnd memcache plugin (`mysqlnd_memcache') is an PHP extension for transparently translating SQL into requests for the MySQL InnoDB Memcached Daemon Plugin (server plugin). It includes experimental support for the MySQL Cluster Memcached Daemon. The server plugin provides access to data stored inside MySQL InnoDB (respectively MySQL Cluster NDB) tables using the Memcache protocol. This PHP extension, which supports all PHP MySQL extensions that use See section "apis-php-mysqli" in the online manual, will identify tables exported in this way and will translate specific SELECT queries into Memcache requests. FIGURE GOES HERE: mysqlnd_memcache data flow *Note*: This plugin depends on the MySQL InnoDB Memcached Daemon Plugin. It is not provided to be used with a stand-alone Memcached. For a generic query cache using Memcached look at the *Note mysqlnd query cache plugin: apis-php-book.mysqlnd-qc. For direct Memcache access look at the memcache (http://www.php.net/book.memcache) and memcached (http://www.php.net/book.memcached) extensions. The MySQL native driver for PHP is a C library that ships together with PHP as of PHP 5.3.0. It serves as a drop-in replacement for the MySQL Client Library (libmysqlclient). Using mysqlnd has several advantages: no extra downloads are required because it's bundled with PHP, it's under the PHP license, there is lower memory consumption in certain cases, and it contains new functionality such as asynchronous queries. The `mysqlnd_mmemcache' operates, for the most part, transparently from a user perspective. The mysqlnd memcache plugin supports all PHP applications, and all MySQL PHP extensions. It does not change existing APIs. Therefore, it can easily be used with existing PHP applications. The MySQL Memcache plugins add key-value style access method for data stored in InnoDB resp. NDB (MySQL Cluster) SQL tables through the Memcache protocol. This type of key-value access if often faster than using SQL.  File: manual.info, Node: apis-php-mysqlnd-memcache.key-features, Next: apis-php-mysqlnd-memcache.limitations, Prev: apis-php-book.mysqlnd-memcache, Up: apis-php-book.mysqlnd-memcache 21.9.6.1 Key Features ..................... Copyright 1997-2012 the PHP Documentation Group. The key features of PECL/mysqlnd_memcache are as follows. * Possible performance benefits * Client-side: light-weight protocol. * Server-side: no SQL parsing, direct access to the storage. * Please, run your own benchmarks! Actual performance results are highly dependent on setup and hardware used.  File: manual.info, Node: apis-php-mysqlnd-memcache.limitations, Next: apis-php-mysqlnd-memcache.name, Prev: apis-php-mysqlnd-memcache.key-features, Up: apis-php-book.mysqlnd-memcache 21.9.6.2 Limitations .................... Copyright 1997-2012 the PHP Documentation Group. The initial version is not binary safe. Due to the way the MySQL Memcache plugins works there are restrictions related to separators. Prepared statements and asynchronous queries are not supported. Result set meta data support is limited. The mapping information for tables accessible via Memcache is not cached in the plugin between requests but fetched from the MySQL server each time a MySQL connection is associated with a Memcache connection. See *Note `mysqlnd_memcache_set': apis-php-function.mysqlnd-memcache-set. for details.  File: manual.info, Node: apis-php-mysqlnd-memcache.name, Next: apis-php-mysqlnd-memcache.quickstart, Prev: apis-php-mysqlnd-memcache.limitations, Up: apis-php-book.mysqlnd-memcache 21.9.6.3 On the name .................... Copyright 1997-2012 the PHP Documentation Group. The shortcut `mysqlnd_memcache' stands for `mysqlnd memcache plugin'. Memcache refers to support of the MySQL Memcache plugins for InnoDB and NDB (MySQL Cluster). The plugin is not related to the Memcached cache server.  File: manual.info, Node: apis-php-mysqlnd-memcache.quickstart, Next: apis-php-mysqlnd-memcache.setup, Prev: apis-php-mysqlnd-memcache.name, Up: apis-php-book.mysqlnd-memcache 21.9.6.4 Quickstart and Examples ................................ * Menu: * apis-php-mysqlnd-memcache.quickstart.configuration:: Setup * apis-php-mysqlnd-memcache.quickstart.usage:: Usage Copyright 1997-2012 the PHP Documentation Group. The mysqlnd memcache plugin is easy to use. This quickstart will demo typical use-cases, and provide practical advice on getting started. It is strongly recommended to read the reference sections in addition to the quickstart. The quickstart tries to avoid discussing theoretical concepts and limitations. Instead, it will link to the reference sections. It is safe to begin with the quickstart. However, before using the plugin in mission critical environments we urge you to read additionally the background information from the reference sections.  File: manual.info, Node: apis-php-mysqlnd-memcache.quickstart.configuration, Next: apis-php-mysqlnd-memcache.quickstart.usage, Prev: apis-php-mysqlnd-memcache.quickstart, Up: apis-php-mysqlnd-memcache.quickstart 21.9.6.5 Setup .............. Copyright 1997-2012 the PHP Documentation Group. The plugin is implemented as a PHP extension. See also the *Note installation instructions: apis-php-mysqlnd-memcache.installation. to install this extension. Compile or configure the PHP MySQL extension (API) (mysqli, See section "apis-php-ref.pdo-mysql" in the online manual, mysql). That extension must use the See section "apis-php-mysqli" in the online manual library as because mysqlnd_memcache is a plugin for the mysqlnd library. For additional information, refer to the mysqlnd_memcache installation instructions (http://www.php.net/memcached.installation). Then, load this extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_memcache.enable. ; On Windows the filename is php_mysqnd_memcache.dll ; Load the extension extension=mysqlnd_memcache.so ; Enable it mysqlnd_memcache.enable=1 Follow the instructions given in the MySQL Reference Manual on installing the Memcache plugins (http://dev.mysql.com/doc/en/ha-memcached.html) for the MySQL server. Activate the plugins and configure Memcache access for SQL tables. The examples in this quickguide assume that the following table exists, and that Memcache is configured with access to it. CREATE TABLE test( id CHAR(16), f1 VARCHAR(255), f2 VARCHAR(255), f3 VARCHAR(255), flags INT NOT NULL, cas_column INT, expire_time_column INT, PRIMARY KEY(id) ) ENGINE=InnoDB; INSERT INTO test (id, f1, f2, f3) VALUES (1, 'Hello', 'World', '!'); INSERT INTO test (id, f1, f2, f3) VALUES (2, 'Lady', 'and', 'the tramp'); 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 ( 'plugin_test', 'test', 'test', 'id', 'f1,f2,f3', 'flags', 'cas_column', 'expire_time_column', 'PRIMARY KEY');  File: manual.info, Node: apis-php-mysqlnd-memcache.quickstart.usage, Prev: apis-php-mysqlnd-memcache.quickstart.configuration, Up: apis-php-mysqlnd-memcache.quickstart 21.9.6.6 Usage .............. Copyright 1997-2012 the PHP Documentation Group. After associating a MySQL connection with a Memcache connection using `mysqnd_memcache_set' (http://www.php.net/mysqnd_memcache_set) the plugin attempts to transparently replace SQL `SELECT' statements by a memcache access. For that purpose the plugin monitors all SQL statements executed and tries to match the statement string against MYSQLND_MEMCACHE_DEFAULT_REGEXP . In case of a match, the mysqlnd memcache plugin checks whether the `SELECT' is accessing only columns of a mapped table and the `WHERE' clause is limited to a single key lookup. In case of the example SQL table, the plugin will use the Memcache interface of the MySQL server to fetch results for a SQL query like `SELECT f1, f2, f3 WHERE id = n'. addServer("host", 11211); mysqlnd_memcache_set($mysqli, $memc); /* This is a query which queries table test using id as key in the WHERE part and is accessing fields f1, f2 and f3. Therefore, mysqlnd_memcache will intercept it and route it via memcache. */ $result = $mysqli->query("SELECT f1, f2, f3 FROM test WHERE id = 1"); while ($row = $result->fetch_row()) { print_r($row); } /* This is a query which queries table test but using f1 in the WHERE clause. Therefore, mysqlnd_memcache can't intercept it. This will be executed using the MySQL protocol */ $mysqli->query("SELECT id FROM test WHERE f1 = 'Lady'"); while ($row = $result->fetch_row()) { print_r($row); } ?> The above example will output: array( [f1] => Hello [f2] => World [f3] => ! ) array( [id] => 2 )  File: manual.info, Node: apis-php-mysqlnd-memcache.setup, Next: apis-php-mysqlnd-memcache.constants, Prev: apis-php-mysqlnd-memcache.quickstart, Up: apis-php-book.mysqlnd-memcache 21.9.6.7 Installing/Configuring ............................... * Menu: * apis-php-mysqlnd-memcache.requirements:: Requirements * apis-php-mysqlnd-memcache.installation:: Installation * apis-php-mysqlnd-memcache.configuration:: Runtime Configuration Copyright 1997-2012 the PHP Documentation Group.  File: manual.info, Node: apis-php-mysqlnd-memcache.requirements, Next: apis-php-mysqlnd-memcache.installation, Prev: apis-php-mysqlnd-memcache.setup, Up: apis-php-mysqlnd-memcache.setup 21.9.6.8 Requirements ..................... Copyright 1997-2012 the PHP Documentation Group. PHP: this extension requires PHP 5.4+, version PHP 5.4.4 or never. The required PHP extensions are PCRE (http://www.php.net/ref.pcre) (enabled by default), and the memcached (http://www.php.net/book.memcached) extension version 2.0.x. The `mysqlnd_memcache' Memcache plugin supports all PHP applications and all available PHP MySQL extensions (mysqli, mysql, See section "apis-php-ref.pdo-mysql" in the online manual). The PHP MySQL extension must be configured with See section "apis-php-mysqli" in the online manual support. For accessing `InnoDB' tables, this PHP extension requires `MySQL Server 5.6.6' or newer with the InnoDB Memcache Daemon Plugin enabled. For accessing `MySQL Cluster NDB' tables, this PHP extension requires `MySQL Cluster 7.2' or newer with the NDB Memcache API nodes enabled.  File: manual.info, Node: apis-php-mysqlnd-memcache.installation, Next: apis-php-mysqlnd-memcache.configuration, Prev: apis-php-mysqlnd-memcache.requirements, Up: apis-php-mysqlnd-memcache.setup 21.9.6.9 Installation ..................... Copyright 1997-2012 the PHP Documentation Group. This PECL (http://pecl.php.net/) extension is not bundled with PHP. Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions (http://www.php.net/install.pecl). Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/mysqlnd_memcache (http://pecl.php.net/package/mysqlnd_memcache) A DLL for this PECL extension is currently unavailable. See also the building on Windows (http://www.php.net/install.windows.building) section.  File: manual.info, Node: apis-php-mysqlnd-memcache.configuration, Prev: apis-php-mysqlnd-memcache.installation, Up: apis-php-mysqlnd-memcache.setup 21.9.6.10 Runtime Configuration ............................... Copyright 1997-2012 the PHP Documentation Group. The behaviour of these functions is affected by settings in `php.ini'. *Mysqlnd_memcache Configure Options* Name Default Changeable Changelog mysqlnd_memcache.enable1 PHP_INI_SYSTEM Available since 1.0.0 Here's a short explanation of the configuration directives. 1. mysqlnd_memcache.enable integer Enables or disables the plugin. If disabled, the extension will not plug into See section "apis-php-mysqli" in the online manual to proxy internal See section "apis-php-mysqli" in the online manual C API calls. *Note*: This option is mainly used by developers to build this extension statically into PHP. General users are encouraged to build this extension as a shared object, and to unload it completely when it is not needed.  File: manual.info, Node: apis-php-mysqlnd-memcache.constants, Next: apis-php-ref.mysqlnd-memcache, Prev: apis-php-mysqlnd-memcache.setup, Up: apis-php-book.mysqlnd-memcache 21.9.6.11 Predefined Constants .............................. Copyright 1997-2012 the PHP Documentation Group. The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime. _MySQL Memcache Plugin related_ 1. MYSQLND_MEMCACHE_DEFAULT_REGEXP (string) Default regular expression (PCRE style) used for matching `SELECT' statements that will be mapped into a MySQL Memcache Plugin access point, if possible. It is also possible to use *Note `mysqlnd_memcache_set': apis-php-function.mysqlnd-memcache-set, but the default approach is using this regular expression for pattern matching. _Assorted_ The version number of this plugin can be obtained by using MYSQLND_MEMCACHE_VERSION or MYSQLND_MEMCACHE_VERSION_ID . MYSQLND_MEMCACHE_VERSION is the string representation of the numerical version number MYSQLND_MEMCACHE_VERSION_ID , which is an integer such as 10000. Developers can calculate the version number as follows. Unknown PHP API feature. Version (part) Example Major*10000 1*10000 = 10000 Minor*100 0*100 = 0 Patch 0 = 0 MYSQLND_MEMCACHE_VERSION_ID 10000 1. MYSQLND_MEMCACHE_VERSION (string) Plugin version string, for example, `1.0.0-alpha'. 2. MYSQLND_MEMCACHE_VERSION_ID (integer) Plugin version number, for example, 10000.  File: manual.info, Node: apis-php-ref.mysqlnd-memcache, Next: apis-php-mysqlnd-memcache.changes, Prev: apis-php-mysqlnd-memcache.constants, Up: apis-php-book.mysqlnd-memcache 21.9.6.12 Mysqlnd_memcache Functions .................................... * Menu: * apis-php-function.mysqlnd-memcache-get-config:: `mysqlnd_memcache_get_config' * apis-php-function.mysqlnd-memcache-set:: `mysqlnd_memcache_set' Copyright 1997-2012 the PHP Documentation Group.  File: manual.info, Node: apis-php-function.mysqlnd-memcache-get-config, Next: apis-php-function.mysqlnd-memcache-set, Prev: apis-php-ref.mysqlnd-memcache, Up: apis-php-ref.mysqlnd-memcache 21.9.6.13 `mysqlnd_memcache_get_config' ....................................... Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_memcache_get_config' Returns information about the plugin configuration *Description* array mysqlnd_memcache_get_config mixedconnection This function returns an array of all mysqlnd_memcache related configuration information that is attached to the MySQL connection. This includes MySQL, the Memcache object provided via *Note `mysqlnd_memcache_set': apis-php-function.mysqlnd-memcache-set, and the table mapping configuration that was automatically collected from the MySQL Server. *Parameters* 1. connection A handle to a MySQL Server using one of the MySQL API extensions for PHP, which are See section "apis-php-ref.pdo-mysql" in the online manual, See section "apis-php-mysqli" in the online manual or See section "apis-php-mysql" in the online manual. *Return Values* An array of mysqlnd_memcache configuration information on success, otherwise FALSE . The returned array has these elements: **Note `mysqlnd_memcache_get_config': apis-php-function.mysqlnd-memcache-get-config. array structure* Array Key Description memcached Instance of Memcached associated to this MySQL connection by *Note `mysqlnd_memcache_set': apis-php-function.mysqlnd-memcache-set. You can use this to change settings of the memcache connection, or directly by querying the server on this connection. pattern The PCRE regular expression used to match the SQL query sent to the server. Queries matching this pattern will be further analyzed to decide whether the query can be intercepted and sent via the memcache interface or whether the query is sent using the general MySQL protocol to the server. The pattern is either the default pattern (`MYSQLND_MEMCACHE_DEFAULT_REGEXP') or it is set via *Note `mysqlnd_memcache_set': apis-php-function.mysqlnd-memcache-set. mappings An associative array with a list of all configured containers as they were discovered by this plugin. The key for these elements is the name of the container in the MySQL configuration. The value is described below. The contents of this field is created by querying the MySQL Server during association to MySQL and a memcache connection using *Note `mysqlnd_memcache_set': apis-php-function.mysqlnd-memcache-set. mapping_query An SQL query used during *Note `mysqlnd_memcache_set': apis-php-function.mysqlnd-memcache-set. to identify the available containers and mappings. The result of that query is provided in the mappings element. *Mapping entry structure* Array Key Description prefix A prefix used while accessing data via memcache. With the MySQL InnoDB Memcache Deamon plugin, this usually begins with @@ and ends with a configurable separator. This prefix is placed in front of the key value while using the memcache protocol. schema_name Name of the schema (database) which contains the table being accessed. table_name Name of the table which contains the data accessible via memcache protocol. id_field_name Name of the database field (column) with the id used as key when accessing the table via memcache. Often this is the database field having a primary key. separator The separator used to split the different field values. This is needed as memcache only provides access to a single value while MySQL can map multiple columns to this value. *Note*: The separator, which can be set in the MySQL Server configuration, should not be part of any value retrieved via memcache because proper mapping can't be guaranteed. fields An array with the name of all fields available for this mapping. *Examples* addServer("host", 11211); mysqlnd_memcache_set($mysqli, $memc); var_dump(mysqlnd_memcache_get_config($mysqli)); ?> The above example will output: array(4) { ["memcached"]=> object(Memcached)#2 (0) { } ["pattern"]=> string(125) "/^\s*SELECT\s*(.+?)\s*FROM\s*`?([a-z0-9_]+)`?\s*WHERE\s*`?([a-z0-9_]+)`?\s*=\s*(?(?=["'])["']([^"']*)["']|([0-9e\.]*))\s*$/is" ["mappings"]=> array(1) { ["mymem_test"]=> array(6) { ["prefix"]=> string(13) "@@mymem_test." ["schema_name"]=> string(4) "test" ["table_name"]=> string(10) "mymem_test" ["id_field_name"]=> string(2) "id" ["separator"]=> string(1) "|" ["fields"]=> array(3) { [0]=> string(2) "f1" [1]=> string(2) "f2" [2]=> string(2) "f3" } } } ["mapping_query"]=> string(209) " SELECT c.name, CONCAT('@@', c.name, (SELECT value FROM innodb_memcache.config_options WHERE name = 'table_map_delimiter')) AS key_prefix, c.db_schema, c.db_table, c.key_columns, c.value_columns, (SELECT value FROM innodb_memcache.config_options WHERE name = 'separator') AS sep FROM innodb_memcache.containers c" } *See Also* *Note `mysqlnd_memcache_set': apis-php-function.mysqlnd-memcache-set.  File: manual.info, Node: apis-php-function.mysqlnd-memcache-set, Prev: apis-php-function.mysqlnd-memcache-get-config, Up: apis-php-ref.mysqlnd-memcache 21.9.6.14 `mysqlnd_memcache_set' ................................ Copyright 1997-2012 the PHP Documentation Group. * `mysqlnd_memcache_set' Associate a MySQL connection with a Memcache connection *Description* bool mysqlnd_memcache_set mixedmysql_connection Memcachedmemcache_connection stringpattern callbackcallback Associate mysql_connection with memcache_connection using pattern as a PCRE regular expression, and callback as a notification callback or to unset the association of mysql_connection. While associating a MySQL connection with a Memcache connection, this function will query the MySQL Server for its configuration. It will automatically detect whether the server is configured to use the InnoDB Memcache Daemon Plugin or MySQL Cluster NDB Memcache support. It will also query the server to automatically identify exported tables and other configuration options. The results of this automatic configuration can be retrieved using *Note `mysqlnd_memcache_get_config': apis-php-function.mysqlnd-memcache-get-config. *Parameters* 1. mysql_connection A handle to a MySQL Server using one of the MySQL API extensions for PHP, which are See section "apis-php-ref.pdo-mysql" in the online manual, See section "apis-php-mysqli" in the online manual or See section "apis-php-mysql" in the online manual. 2. memcache_connection A Memcached (http://www.php.net/book.memcached) instance with a connection to the MySQL Memcache Daemon plugin. If this parameter is omitted, then mysql_connection will be unassociated from any memcache connection. And if a previous association exists, then it will be replaced. 3. pattern A regular expression in Perl Compatible Regular Expression (http://www.php.net/book.pcre) syntax used to identify potential Memcache-queries. The query should have three sub patterns. The first subpattern contains the requested field list, the second the name of the ID column from the query and the third the requested value. If this parameter is omitted or os set to NULL , then a default pattern will be used. 4. callback A callback which will be used whenever a query is being sent to MySQL. The callback will receive a single boolean parameter telling if a query was sent via Memcache. *Return Values* TRUE if the association or disassociation is successful, otherwise FALSE if there is an error. *Examples* addServer("host", 11211); mysqlnd_memcache_set($mysqli, $memc, NULL, 'var_dump'); /* This query will be intercepted and executed via Memcache protocol */ echo "Sending query for id via Memcache: "; $mysqli->query("SELECT f1, f2, f3 FROM test WHERE id = 1"); /* f1 is not configured as valid key field, this won't be sent via Memcache */ echo "Sending query for f1 via Memcache: "; $mysqli->query("SELECT id FROM test WHERE f1 = 1"); mysqlnd_memcache_set($mysqli); /* Now the regular MySQL protocol will be used */ echo "var_dump won't be invoked: "; $mysqli->query("SELECT f1, f2, f3 WHERE id = 1"); ?> The above example will output: Sending query for id via Memcache: bool(true) Sending query for f1 via Memcache: bool(false) var_dump won't be invoked: *See Also* *Note `mysqlnd_memcache_get_config': apis-php-function.mysqlnd-memcache-get-config.  File: manual.info, Node: apis-php-mysqlnd-memcache.changes, Prev: apis-php-ref.mysqlnd-memcache, Up: apis-php-book.mysqlnd-memcache 21.9.6.15 Change History ........................ * Menu: * apis-php-mysqlnd-memcache.changes-one-o:: PECL/mysqlnd_memcache 1.0 series Copyright 1997-2012 the PHP Documentation Group. This change history is a high level summary of selected changes that may impact applications and/or break backwards compatibility. See also the `CHANGES' file in the source distribution for a complete list of changes.  File: manual.info, Node: apis-php-mysqlnd-memcache.changes-one-o, Prev: apis-php-mysqlnd-memcache.changes, Up: apis-php-mysqlnd-memcache.changes 21.9.6.16 PECL/mysqlnd_memcache 1.0 series .......................................... Copyright 1997-2012 the PHP Documentation Group. 1.0.0-alpha * Release date: TBD * Motto/theme: Basic mapping of SQL SELECT to a MySQL Memcache plugin access. The initial release does map basic SQL SELECT statements to a MySQL Memcache plugin access. This bares potential performance benefits as the direct key-value access to MySQL storage using the Memcache protocol is usually faster than using SQL access.  File: manual.info, Node: connector-php, Next: apis-php-problems, Prev: apis-php-book.mysqlnd-memcache, Up: apis-php 21.9.7 Connector/PHP -------------------- This documentation, and other publications, sometimes uses the term `Connector/PHP'. This term refers to the full set of MySQL related functionality in PHP, which includes the three APIs that are described above, along with the See section "apis-php-mysqli" in the online manual core library and all of its plugins.  File: manual.info, Node: apis-php-problems, Next: php-mysql-mysqli, Prev: connector-php, Up: apis-php 21.9.8 Common Problems with MySQL and PHP ----------------------------------------- * `Error: Maximum Execution Time Exceeded': This is a PHP limit; go into the `php.ini' file and set the maximum execution time up from 30 seconds to something higher, as needed. It is also not a bad idea to double the RAM allowed per script to 16MB instead of 8MB. * `Fatal error: Call to unsupported or undefined function mysql_connect() in ...': This means that your PHP version isn't compiled with MySQL support. You can either compile a dynamic MySQL module and load it into PHP or recompile PHP with built-in MySQL support. This process is described in detail in the PHP manual. * `Error: Undefined reference to 'uncompress'': This means that the client library is compiled with support for a compressed client/server protocol. The fix is to add `-lz' last when linking with `-lmysqlclient'. * `Error: Client does not support authentication protocol': This is most often encountered when trying to use the older `mysql' extension with MySQL 4.1.1 and later. Possible solutions are: downgrade to MySQL 4.0; switch to PHP 5 and the newer `mysqli' extension; or configure the MySQL server with the `old_passwords' system variable set to 1. (See *Note old-client::, for more information.)  File: manual.info, Node: php-mysql-mysqli, Prev: apis-php-problems, Up: apis-php 21.9.9 Enabling Both `mysql' and `mysqli' in PHP ------------------------------------------------ If you're experiencing problems with enabling both the `mysql' and the `mysqli' extension when building PHP on Linux yourself, you should try the following procedure. 1. Configure PHP like this: ./configure --with-mysqli=/usr/bin/mysql_config --with-mysql=/usr 2. Edit the `Makefile' and search for a line that starts with `EXTRA_LIBS'. It might look like this (all on one line): EXTRA_LIBS = -lcrypt -lcrypt -lmysqlclient -lz -lresolv -lm -ldl -lnsl -lxml2 -lz -lm -lxml2 -lz -lm -lmysqlclient -lz -lcrypt -lnsl -lm -lxml2 -lz -lm -lcrypt -lxml2 -lz -lm -lcrypt Remove all duplicates, so that the line looks like this (all on one line): EXTRA_LIBS = -lcrypt -lcrypt -lmysqlclient -lz -lresolv -lm -ldl -lnsl -lxml2 3. Build and install PHP: make make install  File: manual.info, Node: apis-perl, Next: apis-python, Prev: apis-php, Up: connectors-apis 21.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 *Note perl-support::. * For an example of reading options from option files, see *Note multiple-server-clients::. * For secure coding tips, see *Note security-guidelines::. * For debugging tips, see *Note using-gdb-on-mysqld::. * For some Perl-specific environment variables, see *Note environment-variables::. * For considerations for running on Mac OS X, see *Note macosx-installation-server::. * For ways to quote string literals, see *Note 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 Web site, `http://dbi.perl.org/'. That site hosts a general DBI mailing list. Oracle Corporation hosts a list specifically about `DBD::mysql'; see *Note 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 Web site, `http://dbi.perl.org/'. For information that focuses specifically on using DBI with MySQL, see `MySQL and Perl for the Web' (Paul DuBois, New Riders, 2001). This book's Web site is `http://www.kitebird.com/mysql-perl/'.  File: manual.info, Node: apis-python, Next: apis-ruby, Prev: apis-perl, Up: connectors-apis 21.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 *Note connector-python:: for details on the Connector, as well as coding guidelines for Python applications and sample Python code.  File: manual.info, Node: apis-ruby, Next: apis-tcl, Prev: apis-python, Up: connectors-apis 21.12 MySQL Ruby APIs ===================== * Menu: * apis-ruby-mysqlruby:: The MySQL/Ruby API * apis-ruby-rubymysql:: The Ruby/MySQL API 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 *Note 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 *Note apis-ruby-rubymysql::. For background and syntax information about the Ruby language, see Ruby Programming Language (http://www.ruby-lang.org).  File: manual.info, Node: apis-ruby-mysqlruby, Next: apis-ruby-rubymysql, Prev: apis-ruby, Up: apis-ruby 21.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/).  File: manual.info, Node: apis-ruby-rubymysql, Prev: apis-ruby-mysqlruby, Up: apis-ruby 21.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).  File: manual.info, Node: apis-tcl, Next: apis-eiffel, Prev: apis-ruby, Up: connectors-apis 21.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/'.  File: manual.info, Node: apis-eiffel, Prev: apis-tcl, Up: connectors-apis 21.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'.  File: manual.info, Node: extending-mysql, Next: mysql-enterprise, Prev: connectors-apis, Up: Top 22 Extending MySQL ****************** * Menu: * mysql-internals:: MySQL Internals * plugin-api:: The MySQL Plugin API * adding-functions:: Adding New Functions to MySQL * porting:: Debugging and Porting MySQL  File: manual.info, Node: mysql-internals, Next: plugin-api, Prev: extending-mysql, Up: extending-mysql 22.1 MySQL Internals ==================== * Menu: * mysql-threads:: MySQL Threads * mysql-test-suite:: The MySQL Test Suite 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 *Note 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 *Note 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!  File: manual.info, Node: mysql-threads, Next: mysql-test-suite, Prev: mysql-internals, Up: mysql-internals 22.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 *Note 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 4 additional threads by default. Those are file I/O threads, controlled by the `innodb_file_io_threads' parameter. See *Note innodb-parameters::. * If *Note `mysqld': mysqld. is compiled with `-DUSE_ALARM_THREAD', a dedicated thread that handles alarms is created. This is only used on some systems where there are problems with `sigwait()' or if you want to use the `thr_alarm()' code in your application without a dedicated signal handling thread. * If the server is started with the `--flush_time=VAL' option, a dedicated thread is created to flush all tables every VAL seconds. * Each table for which *Note `INSERT DELAYED': insert-delayed. statements are issued gets its own thread. See *Note insert-delayed::. * If the event scheduler is active, there is one thread for the scheduler, and a thread for each event currently running. See *Note events-overview::. *Note `mysqladmin processlist': mysqladmin. only shows the connection, *Note `INSERT DELAYED': insert-delayed, replication, and event threads.  File: manual.info, Node: mysql-test-suite, Prev: mysql-threads, Up: mysql-internals 22.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 doesn't 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 *Note 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 *Note `mysqld': 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, NDB, and Instance Manager). 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 *Note mailing-lists::.  File: manual.info, Node: plugin-api, Next: adding-functions, Prev: mysql-internals, Up: extending-mysql 22.2 The MySQL Plugin API ========================= * Menu: * plugin-api-characteristics:: Plugin API Characteristics * plugin-api-components:: Plugin API Components * plugin-types:: Types of Plugins * writing-plugins:: Writing Plugins MySQL 5.1 and up 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 *Note `INSTALL PLUGIN': install-plugin. statement. This table is created as part of the MySQL installation process. (If you are upgrading from a version of MySQL older than 5.1, you should run the *Note `mysql_upgrade': mysql-upgrade. command to create this table. See *Note mysql-upgrade::.) 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 *Note server-plugin-loading::. * 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.  File: manual.info, Node: plugin-api-characteristics, Next: plugin-api-components, Prev: plugin-api, Up: plugin-api 22.2.1 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 *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. table or using the *Note `SHOW PLUGINS': 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 *Note `SHOW VARIABLES': show-variables. and *Note `SHOW STATUS': 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. 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.  File: manual.info, Node: plugin-api-components, Next: plugin-types, Prev: plugin-api-characteristics, Up: plugin-api 22.2.2 Plugin API Components ---------------------------- The server plugin implementation comprises several components. SQL statements: * *Note `INSTALL PLUGIN': install-plugin. registers a plugin in the `mysql.plugin' table and loads the plugin code. * *Note `UNINSTALL PLUGIN': 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. * *Note `SHOW PLUGINS': 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=PATH' option. *Note `mysql_config --plugindir': mysql-config. displays the default plugin directory path name. For additional information about plugin loading, see *Note server-plugin-loading::. Plugin-related tables: * The *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. table contains plugin information. * The `mysql.plugin' table lists each plugin that was installed with *Note `INSTALL PLUGIN': install-plugin. and is required for plugin use. For new MySQL installations, this table is created during the installation process. If you are upgrading from a version of MySQL older than 5.1, you should run *Note `mysql_upgrade': mysql-upgrade. to update your system tables and create the `plugin' table (see *Note mysql-upgrade::). Source files (the locations indicate where the files are found in MySQL source distributions): * 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. * In the `sql' directory, `sql_plugin.h' and `sql_plugin.cc' comprise the internal plugin implementation. 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.  File: manual.info, Node: plugin-types, Next: writing-plugins, Prev: plugin-api-components, Up: plugin-api 22.2.3 Types of Plugins ----------------------- * Menu: * storage-engine-plugins:: Storage Engine Plugins * full-text-plugins:: Full-Text Parser Plugins * daemon-plugins:: Daemon Plugins * information-schema-plugins:: `INFORMATION_SCHEMA' Plugins The plugin API enables creation of plugins that implement several capabilities: * Storage engines * Full-text parsers * Daemons * `INFORMATION_SCHEMA' tables The following sections provide an overview of these plugin types.  File: manual.info, Node: storage-engine-plugins, Next: full-text-plugins, Prev: plugin-types, Up: plugin-types 22.2.3.1 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 *Note 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).  File: manual.info, Node: full-text-plugins, Next: daemon-plugins, Prev: storage-engine-plugins, Up: plugin-types 22.2.3.2 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). For full-text processing, `parsing' means extracting words 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 *Note fulltext-search::. These properties include rules for determining how to extract words from text. The parser is influenced by certain system variables such as `ft_min_word_len' and `ft_max_word_len' that cause words shorter or longer to be excluded, and by the stopword list that identifies common words to be ignored. The plugin API 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 word accumulation). One reason to use a parser this way is that 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. In particular, this parsing will be affected by the `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 nonplaintext 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 my_parser ) ENGINE=MyISAM; Or you can add the index after the table has been created: ALTER TABLE t ADD FULLTEXT INDEX (doc) WITH PARSER my_parser; 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 *Note `DROP TABLE': drop-table. is still possible. For more information about full-text plugins, see *Note writing-full-text-plugins::.  File: manual.info, Node: daemon-plugins, Next: information-schema-plugins, Prev: full-text-plugins, Up: plugin-types 22.2.3.3 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 *Note writing-daemon-plugins::.  File: manual.info, Node: information-schema-plugins, Prev: daemon-plugins, Up: plugin-types 22.2.3.4 `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 *Note writing-information-schema-plugins::.  File: manual.info, Node: writing-plugins, Prev: plugin-types, Up: plugin-api 22.2.4 Writing Plugins ---------------------- * Menu: * writing-plugins-overview:: Overview of Plugin Writing * plugin-data-structures:: Plugin Data Structures * compiling-plugin-libraries:: Compiling and Installing Plugin Libraries * writing-full-text-plugins:: Writing Full-Text Parser Plugins * writing-daemon-plugins:: Writing Daemon Plugins * writing-information-schema-plugins:: Writing `INFORMATION_SCHEMA' 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 *Note `SHOW STATUS': show-status. and *Note `SHOW VARIABLES': show-variables. statements and the corresponding `INFORMATION_SCHEMA' tables. 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 *Note `mysqld': mysqld. dynamically (not statically). 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 *Note source-configuration-options::, and *Note compilation-problems::.  File: manual.info, Node: writing-plugins-overview, Next: plugin-data-structures, Prev: writing-plugins, Up: writing-plugins 22.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 #include #include 2. Set up the descriptor information for the plugin library file. This descriptor must contain the general plugin descriptor for each server plugin in the file. For more information, see *Note 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. 3. Write the plugin interface functions for each plugin. 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. 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 *Note compiling-plugin-libraries::. 6. Register the plugin with the server. For more information, see *Note server-plugin-loading::. 7. Test the plugin to verify that it works properly.  File: manual.info, Node: plugin-data-structures, Next: compiling-plugin-libraries, Prev: writing-plugins-overview, Up: writing-plugins 22.2.4.2 Plugin Data Structures ............................... * Menu: * server-plugin-descriptors:: Library and Plugin Descriptors * plugin-status-system-variables:: Plugin Status and System Variables A plugin library file includes descriptor information to indicate what plugins it contains. The plugin library 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.  File: manual.info, Node: server-plugin-descriptors, Next: plugin-status-system-variables, Prev: plugin-data-structures, Up: plugin-data-structures 22.2.4.3 Library and Plugin Descriptors ....................................... Every plugin library 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 */ }; 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 */ ... 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 *Note `INSTALL PLUGIN': install-plugin. and *Note `UNINSTALL PLUGIN': uninstall-plugin, or with the `--plugin-load' option. The name is also visible in the *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. table or the output from *Note `SHOW PLUGINS': 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 *Note `INSTALL PLUGIN': 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 *Note `UNINSTALL PLUGIN': 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 *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. 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 *Note `SHOW STATUS': 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 *Note 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. The `system_vars' member, if not `NULL', points to an array of `st_mysql_sys_var' structures that describe system variables. See *Note plugin-status-system-variables::. * `__reserved1': A placeholder for the future. Currently, it should be set to `NULL'. 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 } 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) \ int VERSION= MYSQL_PLUGIN_INTERFACE_VERSION; \ int PSIZE= sizeof(struct st_mysql_plugin); \ 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}} *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}} }; 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 } 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 } 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 } mysql_declare_plugin_end;  File: manual.info, Node: plugin-status-system-variables, Prev: server-plugin-descriptors, Up: plugin-data-structures 22.2.4.4 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; }; When the plugin is installed, the plugin name and the `name' value are joined with an underscore to form the name displayed by *Note `SHOW STATUS': show-status. 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 *Note `mysqld': 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 } 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) * 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 *Note `mysqld': 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.  File: manual.info, Node: compiling-plugin-libraries, Next: writing-full-text-plugins, Prev: plugin-data-structures, Up: writing-plugins 22.2.4.5 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 the GNU autotools, `libtool' 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 object file that has a name something like `somepluglib.so'. (The file name might have a different suffix on your system.) To use the autotools, you'll need to make a few changes to the configuration files at this point to enable the plugin to be compiled and installed. Assume that your MySQL distribution is installed at a base directory of `/usr/local/mysql' and that its header files are located in the `include' directory under the base directory. Edit `Makefile.am', which should look something like this: #Makefile.am example for a plugin pkgplugindir=$(libdir)/mysql/plugin INCLUDES= -I$(top_builddir)/include -I$(top_srcdir)/include #noinst_LTLIBRARIES= somepluglib.la pkgplugin_LTLIBRARIES= somepluglib.la somepluglib_la_SOURCES= plugin_example.c somepluglib_la_LDFLAGS= -module -rpath $(pkgplugindir) somepluglib_la_CFLAGS= -DMYSQL_DYNAMIC_PLUGIN *Note*: As mentioned in *Note server-plugin-descriptors::, be sure to specify `-DMYSQL_DYNAMIC_PLUGIN' as part of the compilation command when you build the plugin. The `somepluglib_la_CFLAGS' line takes care of this. Adjust the `INCLUDES' line to specify the path name to the installed MySQL header files. Edit it to look like this: INCLUDES= -I/usr/local/mysql/include Make sure that the `noinst_LTLIBRARIES' line is commented out or remove it. Make sure that the `pkglib_LTLIBRARIES' line is not commented out; it enables the `make install' command. Set up the files needed for the `configure' command, invoke it, and run `make': shell> autoreconf --force --install --symlink shell> ./configure --prefix=/usr/local/mysql shell> make The `--prefix' option to `configure' indicates the MySQL base directory under which the plugin should be installed. You can see what value to use for this option with *Note `SHOW VARIABLES': 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.  File: manual.info, Node: writing-full-text-plugins, Next: writing-daemon-plugins, Prev: compiling-plugin-libraries, Up: writing-plugins 22.2.4.6 Writing Full-Text Parser Plugins ......................................... A full-text parser server 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. #include `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 } mysql_declare_plugin_end; The `name' member (`simple_parser') indicates the name to use for references to the plugin in statements such as *Note `INSTALL PLUGIN': install-plugin. or *Note `UNINSTALL PLUGIN': uninstall-plugin. This is also the name displayed by *Note `SHOW PLUGINS': show-plugins. or *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. For more information, see *Note 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 version is specified using a symbol of the form `MYSQL_XXX_INTERFACE_VERSION' (such as (`MYSQL_FTPARSER_INTERFACE_VERSION' for full-text parser plugins) 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; *Note*: The definition shown is current as of MySQL 5.1.12. It is incompatible with versions of MySQL 5.1 older than 5.1.12. 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. Currently, 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 member was added in MySQL 5.1.12. 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. 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; bool wasign; bool trunc; /* These are parser state and must be removed. */ byte prev; byte *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 *Note 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. Plugins should not use the `prev' and `quot' members of the `MYSQL_FTPARSER_BOOLEAN_INFO' structure. 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 }; param->mysql_add_word(param, word, len, &bool_info); } 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[]= { {"static", (char *)"just a static text", SHOW_CHAR}, {"called", (char *)&number_of_calls, SHOW_LONG}, {0,0,0} }; When the plugin is installed, the plugin name and the `name' value are joined with an underscore to form the name displayed by *Note `SHOW STATUS': show-status. For the array just shown, the resulting status variable names are `simple_parser_static' and `simple_parser_called'. This convention means that you can easily display the variables for a plugin using its name: 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 object file, use the instructions in *Note compiling-plugin-libraries::. To use the library file, it must be installed 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 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 (changing the suffix as necessary): mysql> INSTALL PLUGIN simple_parser SONAME 'mypluglib.so'; For additional information about plugin loading, see *Note server-plugin-loading::. 8. To verify plugin installation, examine the *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. table or use the *Note `SHOW PLUGINS': show-plugins. statement. 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) Note how neither `case' nor `insensitive' match `case-insensitive' the way that they would for the built-in parser.  File: manual.info, Node: writing-daemon-plugins, Next: writing-information-schema-plugins, Prev: writing-full-text-plugins, Up: writing-plugins 22.2.4.7 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. #include `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 */ } mysql_declare_plugin_end; The `name' member (`daemon_example') indicates the name to use for references to the plugin in statements such as *Note `INSTALL PLUGIN': install-plugin. or *Note `UNINSTALL PLUGIN': uninstall-plugin. This is also the name displayed by *Note `SHOW PLUGINS': show-plugins. or *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. 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 object file, use the instructions in *Note compiling-plugin-libraries::. To use the library file, it must be installed 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 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 (change the suffix as necessary): mysql> INSTALL PLUGIN daemon_example SONAME 'libdaemon_example.so'; For additional information about plugin loading, see *Note server-plugin-loading::. To verify plugin installation, examine the *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. table or use the *Note `SHOW PLUGINS': show-plugins. statement. 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: mysql> UNINSTALL PLUGIN daemon_example;  File: manual.info, Node: writing-information-schema-plugins, Prev: writing-daemon-plugins, Up: writing-plugins 22.2.4.8 Writing `INFORMATION_SCHEMA' Plugins ............................................. This section describes how to write an `INFORMATION_SCHEMA' table server 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/innodb_plugin' 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. #include #include 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 */ } 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 *Note `INSTALL PLUGIN': install-plugin. or *Note `UNINSTALL PLUGIN': uninstall-plugin. This is also the name displayed by *Note `SHOW PLUGINS': show-plugins. or *Note `INFORMATION_SCHEMA.PLUGINS': plugins-table. 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 *Note 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, COND *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 object file, see the instructions in *Note compiling-plugin-libraries::. To use the library file, it must be installed 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;  File: manual.info, Node: adding-functions, Next: porting, Prev: plugin-api, Up: extending-mysql 22.3 Adding New Functions to MySQL ================================== * Menu: * udf-features:: Features of the User-Defined Function Interface * adding-udf:: Adding a New User-Defined Function * adding-native-function:: Adding a New Native Function 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 object files and then added to and removed from the server dynamically using the *Note `CREATE FUNCTION': create-function. and *Note `DROP FUNCTION': drop-function. statements. See *Note create-function-udf::. * You can add functions as native (built-in) MySQL functions. Native functions are compiled into the *Note `mysqld': 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 *Note 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 don't need to 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 *Note 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.c' file that is provided in MySQL source distributions.  File: manual.info, Node: udf-features, Next: adding-udf, Prev: adding-functions, Up: adding-functions 22.3.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.  File: manual.info, Node: adding-udf, Next: adding-native-function, Prev: udf-features, Up: adding-functions 22.3.2 Adding a New User-Defined Function ----------------------------------------- * Menu: * udf-calling:: UDF Calling Sequences for Simple Functions * udf-aggr-calling:: UDF Calling Sequences for Aggregate Functions * udf-arguments:: UDF Argument Processing * udf-return-values:: UDF Return Values and Error Handling * udf-compiling:: Compiling and Installing User-Defined Functions * udf-security:: User-Defined Function Security Precautions 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.c' 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 *Note source-configuration-options::, and *Note compilation-problems::. To be able to use UDFs, you must link *Note `mysqld': mysqld. dynamically. Don't configure MySQL using `--with-mysqld-ldflags=-all-static'. If you want to use a UDF that needs to access symbols from *Note `mysqld': mysqld. (for example, the `metaphone' function in `sql/udf_example.c' uses `default_charset_info'), you must link the program with `-rdynamic' (see `man dlopen'). If you plan to use UDFs, the rule of thumb is to configure MySQL with `--with-mysqld-ldflags=-rdynamic' unless you have a very good reason not to. 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 *Note 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. This table lists SQL function data types and corresponding C/C++ data types. SQL Type C/C++ Type `STRING' `char *' *Note `INTEGER': `long long' integer-types. *Note `REAL': `double' floating-point-types. It is also possible to declare a *Note `DECIMAL': fixed-point-types. 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 *Note `REAL': floating-point-types. 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()'.  File: manual.info, Node: udf-calling, Next: udf-aggr-calling, Prev: adding-udf, Up: adding-udf 22.3.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. *Note 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', *Note `INTEGER': integer-types, or *Note `REAL': floating-point-types. in the *Note `CREATE FUNCTION': 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 *Note `INTEGER': integer-types. functions: long long xxx(UDF_INIT *initid, UDF_ARGS *args, char *is_null, char *error); For *Note `REAL': floating-point-types. functions: double xxx(UDF_INIT *initid, UDF_ARGS *args, char *is_null, char *error); *Note `DECIMAL': fixed-point-types. 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 *Note `DECIMAL': fixed-point-types, *Note `FLOAT': floating-point-types, and *Note `DOUBLE': floating-point-types. data types. A `decimals' value of 31 is used for arguments in cases such as a *Note `FLOAT': floating-point-types. or *Note `DOUBLE': floating-point-types. column declared without an explicit number of decimals (for example, *Note `FLOAT': floating-point-types. 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 31 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.  File: manual.info, Node: udf-aggr-calling, Next: udf-arguments, Prev: udf-calling, Up: adding-udf 22.3.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. *Note 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.1, 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.1. * `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 *Note 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 *Note udf-return-values::. The `xxx_reset()' and `xxx_add()' functions handle their `UDF_ARGS' argument the same way as functions for nonaggregate UDFs. See *Note 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.  File: manual.info, Node: udf-arguments, Next: udf-return-values, Prev: udf-aggr-calling, Up: adding-udf 22.3.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 *Note `DECIMAL': fixed-point-types. 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.  File: manual.info, Node: udf-return-values, Next: udf-compiling, Prev: udf-arguments, Up: adding-udf 22.3.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 multi-byte 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 *Note 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.)  File: manual.info, Node: udf-compiling, Next: udf-security, Prev: udf-return-values, Up: adding-udf 22.3.2.5 Compiling and Installing User-Defined Functions ........................................................ 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.c' 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.c' 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 object file, using a command something like this: shell> gcc -shared -o udf_example.so udf_example.c If you are using `gcc' with `configure' and `libtool' (which is how MySQL is configured), you should be able to create `udf_example.so' with a simpler command: shell> make udf_example.la After you compile a shared object containing UDFs, you must install it and tell MySQL about it. Compiling a shared object from `udf_example.c' using `gcc' directly produces a file named `udf_example.so'. Compiling the shared object using `make' produces a file named something like `udf_example.so.0.0.0' in the `.libs' directory (the exact name may vary from platform to platform). 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. *Note*: This is a change in MySQL 5.1. For earlier versions of MySQL, the shared object can be located in any directory that is searched by your system's dynamic linker. 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 the development source for MySQL 5.1. See *Note 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.c' 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.c udf_example.def) TARGET_LINK_LIBRARIES(udf_example wsock32) 5. Create the VC project and solution files: cmake -G "" Invoking `cmake --help' shows you a list of valid Generators. 6. Create `udf_example.dll': devenv udf_example.sln /build Release After the shared object file has been installed, notify *Note `mysqld': mysqld. about the new functions with the following statements. If object 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'; To delete functions, use *Note `DROP FUNCTION': 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 *Note `CREATE FUNCTION': create-function. and *Note `DROP FUNCTION': 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 *Note `CREATE FUNCTION': create-function. to add a function that has previously been created. If you need to reinstall a function, you should remove it with *Note `DROP FUNCTION': drop-function. and then reinstall it with *Note `CREATE FUNCTION': create-function. You would need to do this, for example, if you recompile a new version of your function, so that *Note `mysqld': mysqld. gets the new version. Otherwise, the server continues to use the old version. An active function is one that has been loaded with *Note `CREATE FUNCTION': create-function. and not removed with *Note `DROP FUNCTION': drop-function. All active functions are reloaded each time the server starts, unless you start *Note `mysqld': mysqld. with the `--skip-grant-tables' option. In this case, UDF initialization is skipped and UDFs are unavailable.  File: manual.info, Node: udf-security, Prev: udf-compiling, Up: adding-udf 22.3.2.6 User-Defined Function Security Precautions ................................................... MySQL takes several measures to prevent misuse of user-defined functions. UDF object 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. *Note*: This is a change in MySQL 5.1. For earlier versions of MySQL, the shared object can be located in any directory that is searched by your system's dynamic linker. To use *Note `CREATE FUNCTION': create-function. or *Note `DROP FUNCTION': 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. *Note `mysqld': 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 object 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.  File: manual.info, Node: adding-native-function, Prev: adding-udf, Up: adding-functions 22.3.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. For MySQL 5.1, the first two steps apply only as of 5.1.13. For older versions, see the instructions in the corresponding section of the MySQL 5.0 manual. 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 can't 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!  File: manual.info, Node: porting, Prev: adding-functions, Up: extending-mysql 22.4 Debugging and Porting MySQL ================================ * Menu: * debugging-server:: Debugging a MySQL Server * debugging-client:: Debugging a MySQL Client * dbug-package:: The DBUG Package This section helps you port MySQL to other operating systems. Do check the list of currently supported operating systems first. See *Note general-installation-issues::. If you have created a new port of MySQL, please let us know so that we can list it here and on our Web site (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. Both the server and the client need a working C++ compiler. We use `gcc' on many platforms. Other compilers that are known to work are Sun Studio, HP-UX `aCC', IBM AIX `xlC_r'), Intel `ecc/icc'. With previous versions on the respective platforms, we also used Irix `cc' and Compaq `cxx'. *Important*: If you are trying to build MySQL 5.1 with `icc' on the IA64 platform, and need support for MySQL Cluster, you should first ensure that you are using `icc' version 9.1.043 or later. (For details, see Bug #21875.) To compile only the client, use `./configure --without-server'. If you want or need to change any `Makefile' or the `configure' script, you also need GNU Automake and Autoconf. See *Note installing-development-tree::. All steps needed to remake everything from the most basic files. /bin/rm */.deps/*.P /bin/rm -f config.cache aclocal autoheader aclocal automake autoconf ./configure --with-debug=full --prefix='your installation directory' # The makefiles generated above need GNU make 3.75 or newer. # (called gmake below) gmake clean all install init-db If you run into problems with a new port, you may have to do some debugging of MySQL! See *Note debugging-server::. *Note*: Before you start debugging *Note `mysqld': mysqld, first get the test programs `mysys/thr_alarm' and `mysys/thr_lock' to work. This ensures that your thread installation has even a remote chance to work!  File: manual.info, Node: debugging-server, Next: debugging-client, Prev: porting, Up: porting 22.4.1 Debugging a MySQL Server ------------------------------- * Menu: * compiling-for-debugging:: Compiling MySQL for Debugging * making-trace-files:: Creating Trace Files * making-windows-dumps:: Using `pdb' to create a Windows crashdump * using-gdb-on-mysqld:: Debugging `mysqld' under `gdb' * using-stack-trace:: Using a Stack Trace * using-log-files:: Using Server Logs to Find Causes of Errors in `mysqld' * reproducible-test-case:: Making a Test Case If You Experience Table Corruption If you are using some functionality that is very new in MySQL, you can try to run *Note `mysqld': mysqld. with the `--skip-new' (which disables all new, potentially unsafe functionality). See *Note crashing::. Binary distributions of MySQL server from Oracle include a specific debug binary, `mysqld-debug'. This is a build including the debugging information and is built in the same way as the debug build format described in *Note compiling-for-debugging::. You should use this build when debugging the MySQL server. If *Note `mysqld': mysqld. doesn't want to start, you should verify that you don't have any `my.cnf' files that interfere with your setup! You can check your `my.cnf' arguments with *Note `mysqld --print-defaults': mysqld. and avoid using them by starting with *Note `mysqld --no-defaults ...': mysqld. If *Note `mysqld': mysqld. starts to eat up CPU or memory or if it `hangs,' you can use *Note `mysqladmin processlist status': mysqladmin. to find out if someone is executing a query that takes a long time. It may be a good idea to run *Note `mysqladmin -i10 processlist status': mysqladmin. in some window if you are experiencing performance problems or problems when new clients can't connect. The command *Note `mysqladmin debug': mysqladmin. 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 haven't compiled MySQL for debugging! If the problem is that some tables are getting slower and slower you should try to optimize the table with *Note `OPTIMIZE TABLE': optimize-table. or *Note `myisamchk': myisamchk. See *Note server-administration::. You should also check the slow queries with *Note `EXPLAIN': explain. You should also read the OS-specific section in this manual for problems that may be unique to your environment. See *Note general-installation-issues::.  File: manual.info, Node: compiling-for-debugging, Next: making-trace-files, Prev: debugging-server, Up: debugging-server 22.4.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 `--with-debug' or the `--with-debug=full' option. You can check whether MySQL was compiled with debugging by doing: *Note `mysqld --help': mysqld. If the `--debug' flag is listed with the options then you have debugging enabled. *Note `mysqladmin ver': mysqladmin. also lists the *Note `mysqld': mysqld. version as *Note `mysql ... --debug': mysql. in this case. If you are using `gcc', the recommended `configure' line is: CC=gcc CFLAGS="-O2" CXX=gcc CXXFLAGS="-O2 -felide-constructors \ -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql \ --with-debug --with-extra-charsets=complex This avoids problems with the `libstdc++' library and with C++ exceptions (many compilers have problems with C++ exceptions in threaded code) and compile a MySQL version with support for all character sets. If you suspect a memory overrun error, you can configure MySQL with `--with-debug=full', which installs a memory allocation (`SAFEMALLOC') checker. However, running with `SAFEMALLOC' is quite slow, so if you get performance problems you should start *Note `mysqld': mysqld. with the `--skip-safemalloc' option. This disables the memory overrun checks for each call to `malloc()' and `free()'. If *Note `mysqld': mysqld. stops crashing when you compile it with `--with-debug', you probably have found a compiler bug or a timing bug within MySQL. In this case, you can try to add `-g' to the `CFLAGS' and `CXXFLAGS' variables above and not use `--with-debug'. If *Note `mysqld': 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 *Note `mysqld': mysqld. If they find something `unexpected,' an entry is written to `stderr', which *Note `mysqld_safe': 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 *Note mailing-lists::. If you believe that you have found a bug, please use the instructions at *Note bug-reports::. In the Windows MySQL distribution, `mysqld.exe' is by default compiled with support for trace files.  File: manual.info, Node: making-trace-files, Next: making-windows-dumps, Prev: compiling-for-debugging, Up: debugging-server 22.4.1.2 Creating Trace Files ............................. If the *Note `mysqld': mysqld. server doesn't start or if you can cause it to crash quickly, you can try to create a trace file to find the problem. To do this, you must have a *Note `mysqld': 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 *Note `mysqld-debug': mysqld. rather than *Note `mysqld': mysqld. as of MySQL 4.1.) Start the *Note `mysqld': mysqld. server with a trace log in `/tmp/mysqld.trace' on Unix or `C:\mysqld.trace' on Windows: shell> mysqld --debug On Windows, you should also use the `--standalone' flag to not start *Note `mysqld': 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 *Note `mysqld': mysqld. server with *Note `mysqladmin shutdown': mysqladmin. The trace file can become *very large*! To generate a smaller trace file, you can use debugging options something like this: *Note `mysqld --debug=d,info,error,query,general,where:O,/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 can't 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 *Note bug-reports::. The trace file is made with the *DBUG* package by Fred Fish. See *Note dbug-package::.  File: manual.info, Node: making-windows-dumps, Next: using-gdb-on-mysqld, Prev: making-trace-files, Up: debugging-server 22.4.1.3 Using `pdb' to create a Windows crashdump .................................................. Starting with MySQL 5.1.12 the Program Database files (extension `pdb') are included in the Noinstall distribution of MySQL. These files provide information for debugging your MySQL installation in the event of a problem. 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 Dr Watson, `WinDbg' and Visual Studio to debug *Note `mysqld': mysqld. 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). Dr Watson is installed with all Windows distributions, but if you have installed Windows development tools, Dr Watson may have been replaced with WinDbg, the debugger included with Visual Studio, or the debugging tools provided with Borland or Delphi. To generate a crash file using Dr Watson, follow these steps: 1. Start Dr Watson by running `drwtsn32.exe' interactively using the `-i' option: C:\> drwtsn32 -i 2. Set the `Log File Path' to the directory where you want to store trace files. 3. Make sure `Dump All Thread Contexts' and `Append To Existing Log File'. 4. Uncheck `Dump Symbol Table', `Visual Notification', `Sound Notification' and `Create Crash Dump File'. 5. Set the `Number of Instructions' to a suitable value to capture enough calls in the stacktrace. A value of at 25 should be enough. Note that the file generated can become very large.  File: manual.info, Node: using-gdb-on-mysqld, Next: using-stack-trace, Prev: making-windows-dumps, Up: debugging-server 22.4.1.4 Debugging `mysqld' under `gdb' ....................................... On most systems you can also start *Note `mysqld': mysqld. from `gdb' to get more information if *Note `mysqld': mysqld. crashes. With some older `gdb' versions on Linux you must use `run --one-thread' if you want to be able to debug *Note `mysqld': 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 *Note `mysqld': mysqld. under `gdb'. Some symptoms are: * *Note `mysqld': mysqld. hangs during startup (before it writes `ready for connections'). * *Note `mysqld': 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 *Note `mysqld': mysqld. under `gdb', you should disable the stack trace with `--skip-stack-trace' to be able to catch segfaults within `gdb'. In MySQL 4.0.14 and above you should use the `--gdb' option to *Note `mysqld': mysqld. This installs an interrupt handler for `SIGINT' (needed to stop *Note `mysqld': 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' doesn't free the memory for old threads. You can avoid this problem by starting *Note `mysqld': 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 *Note `mysqld': mysqld. dies with a SIGSEGV signal, you can start *Note `mysqld': mysqld. with the `--core-file' option. This core file can be used to make a backtrace that may help you find out why *Note `mysqld': mysqld. died: shell> gdb mysqld core gdb> backtrace full gdb> quit See *Note 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 *Note `mysqld': 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 *Note bug-reports::. If *Note `mysqld': mysqld. hangs, you can try to use some system tools like `strace' or `/usr/proc/bin/pstack' to examine where *Note `mysqld': 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.  File: manual.info, Node: using-stack-trace, Next: using-log-files, Prev: using-gdb-on-mysqld, Up: debugging-server 22.4.1.5 Using a Stack Trace ............................ On some operating systems, the error log contains a stack trace if *Note `mysqld': mysqld. dies unexpectedly. You can use this to find out where (and maybe why) *Note `mysqld': mysqld. died. See *Note error-log::. To get a stack trace, you must not compile *Note `mysqld': mysqld. with the `-fomit-frame-pointer' option to gcc. See *Note 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 *Note `resolve_stack_dump': resolve-stack-dump. utility to determine where *Note `mysqld': 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 *Note `mysqld': mysqld. server: shell> nm -n libexec/mysqld > /tmp/mysqld.sym If *Note `mysqld': 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 *Note `resolve_stack_dump': resolve-stack-dump. output using `c++filt': shell> resolve_stack_dump -s /tmp/mysqld.sym -n mysqld.stack | c++filt This prints out where *Note `mysqld': mysqld. died. If that does not help you find out why *Note `mysqld': 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 *Note `mysqld': mysqld. and preferably a test case so that we can repeat the problem! See *Note bug-reports::.  File: manual.info, Node: using-log-files, Next: reproducible-test-case, Prev: using-stack-trace, Up: debugging-server 22.4.1.6 Using Server Logs to Find Causes of Errors in `mysqld' ............................................................... Note that before starting *Note `mysqld': mysqld. with the general query log enabled, you should check all your tables with *Note `myisamchk': myisamchk. See *Note server-administration::. If *Note `mysqld': mysqld. dies or hangs, you should start *Note `mysqld': mysqld. with the general query log enabled. See *Note query-log::. When *Note `mysqld': mysqld. dies again, you can examine the end of the log file for the query that killed *Note `mysqld': 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 *Note `mysqld': mysqld, but if possible you should verify this by restarting *Note `mysqld': mysqld. and executing the found query from the *Note `mysql': mysql. command-line tools. If this works, you should also test all complicated queries that didn't complete. You can also try the command *Note `EXPLAIN': explain. on all *Note `SELECT': select. statements that takes a long time to ensure that *Note `mysqld': mysqld. is using indexes properly. See *Note explain::. You can find the queries that take a long time to execute by starting *Note `mysqld': mysqld. with the slow query log enabled. See *Note slow-query-log::. If you find the text `mysqld restarted' in the error log file (normally named `hostname.err') you probably have found a query that causes *Note `mysqld': mysqld. to fail. If this happens, you should check all your tables with *Note `myisamchk': myisamchk. (see *Note 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 doesn't help and you can't 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 *Note `mysqld': mysqld. with `--myisam-recover', 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 *Note `mysqld': mysqld. having died unexpectedly just before, then something is wrong and needs to be investigated further. See *Note server-options::. It is not a good sign if *Note `mysqld': mysqld. did die unexpectedly, but in this case, you should not investigate the `Checking table...' messages, but instead try to find out why *Note `mysqld': mysqld. died.  File: manual.info, Node: reproducible-test-case, Prev: using-log-files, Up: debugging-server 22.4.1.7 Making a Test Case If You Experience Table Corruption .............................................................. If you get corrupted tables or if *Note `mysqld': mysqld. always fails after some update commands, you can test whether this bug is reproducible by doing the following: * Take down the MySQL daemon (with *Note `mysqladmin shutdown': mysqladmin.). * Make a backup of the tables (to guard against the very unlikely case that the repair does something bad). * Check all tables with *Note `myisamchk -s database/*.MYI': myisamchk. Repair any wrong tables with *Note `myisamchk -r database/TABLE.MYI': myisamchk. * Make a second backup of the tables. * Remove (or move away) any old log files from the MySQL data directory if you need more space. * Start *Note `mysqld': mysqld. with the binary log enabled. If you want to find a query that crashes *Note `mysqld': mysqld, you should start the server with both the general query log enabled as well. See *Note query-log::, and *Note binary-log::. * When you have gotten a crashed table, stop the `mysqld server'. * Restore the backup. * Restart the *Note `mysqld': mysqld. server *without* the binary log enabled. * Re-execute the commands with *Note `mysqlbinlog binary-log-file | mysql': mysqlbinlog. The binary log is saved in the MySQL database directory with the name `hostname-bin.NNNNNN'. * If the tables are corrupted again or you can get *Note `mysqld': mysqld. to die with the above command, you have found reproducible bug that should be easy to fix! FTP the tables and the binary log to our bugs database using the instructions given in *Note bug-reports::. If you are a support customer, you can use the MySQL Customer Support Center `https://support.mysql.com/' to alert the MySQL team about the problem and have it fixed as soon as possible. You can also use the script *Note `mysql_find_rows': mysql-find-rows. to just execute some of the update statements if you want to narrow down the problem.  File: manual.info, Node: debugging-client, Next: dbug-package, Prev: debugging-server, Up: porting 22.4.2 Debugging a MySQL Client ------------------------------- To be able to debug a MySQL client with the integrated debug package, you should configure MySQL with `--with-debug' or `--with-debug=full'. See *Note 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 *Note `mysql': 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 *Note 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.  File: manual.info, Node: dbug-package, Prev: debugging-client, Up: porting 22.4.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 *Note 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, typically `d:t:i:o,PROGRAM_NAME.trace', the effect of which is: * `d': Enable output for all debug macros * `t': Trace function calls and exits * `i': Add PID to output lines * `o,PROGRAM_NAME.trace': Set the debug output file to `PROGRAM_NAME.trace' The default trace file is usually `/tmp/PROGRAM_NAME.trace' on Unix and `\PROGRAM_NAME.trace' on Windows. 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 *Note `mysqld': 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. (Mostly used with `safemalloc' to find memory leaks.) `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*: The `+' and `-' modifiers are not always handled correctly and can leave a flag value in an incorrect state. Verify your `debug'-setting sequence in advance or set it without using `+' or `-'.  File: manual.info, Node: mysql-enterprise, Next: workbench, Prev: extending-mysql, Up: Top 23 MySQL Enterprise Edition *************************** * Menu: * mysql-enterprise-monitor:: MySQL Enterprise Monitor * mysql-enterprise-backup:: MySQL Enterprise Backup * mysql-enterprise-security:: MySQL Enterprise Security * mysql-enterprise-audit:: MySQL Enterprise Audit * mysql-enterprise-thread-pool:: MySQL Enterprise Thread Pool 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/. * *Note MySQL Enterprise Monitor: mysql-enterprise-monitor. * *Note MySQL Enterprise Backup: mysql-enterprise-backup. * *Note MySQL Enterprise Security: mysql-enterprise-security. * *Note MySQL Enterprise Audit: mysql-enterprise-audit. * *Note MySQL Enterprise Thread Pool: mysql-enterprise-thread-pool.  File: manual.info, Node: mysql-enterprise-monitor, Next: mysql-enterprise-backup, Prev: mysql-enterprise, Up: mysql-enterprise 23.1 MySQL Enterprise Monitor ============================= 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 web site. 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 Agent for each monitored MySQL server. * 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 Agent_. The agent communicates with the MySQL server that it monitors, collecting variables, status and health information, and sending this information to the MySQL Enterprise Service Manager. If you have multiple MySQL servers, then you have multiple MySQL Enterprise Agent processes monitoring each MySQL server. The information collected by the agent about each MySQL server 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 Advisor_. 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 Dashboard, 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 Dashboard. The information supplied by the MySQL Enterprise 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 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.  File: manual.info, Node: mysql-enterprise-backup, Next: mysql-enterprise-security, Prev: mysql-enterprise-monitor, Up: mysql-enterprise 23.2 MySQL Enterprise Backup ============================ 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, web site, 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.  File: manual.info, Node: mysql-enterprise-security, Next: mysql-enterprise-audit, Prev: mysql-enterprise-backup, Up: mysql-enterprise 23.3 MySQL Enterprise Security ============================== 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. * 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 The PAM Authentication Plugin (http://dev.mysql.com/doc/refman/5.5/en/pam-authentication-plugin.html), and The Windows Native Authentication Plugin (http://dev.mysql.com/doc/refman/5.5/en/windows-authentication-plugin.html).  File: manual.info, Node: mysql-enterprise-audit, Next: mysql-enterprise-thread-pool, Prev: mysql-enterprise-security, Up: mysql-enterprise 23.4 MySQL Enterprise Audit =========================== 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 MySQL Enterprise Audit Log Plugin (http://dev.mysql.com/doc/refman/5.5/en/audit-log-plugin.html).  File: manual.info, Node: mysql-enterprise-thread-pool, Prev: mysql-enterprise-audit, Up: mysql-enterprise 23.5 MySQL Enterprise Thread Pool ================================= MySQL Enterprise Edition includes the MySQL 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 The Thread Pool Plugin (http://dev.mysql.com/doc/refman/5.5/en/thread-pool-plugin.html).  File: manual.info, Node: workbench, Next: mysql-for-excel, Prev: mysql-enterprise, Up: Top 24 MySQL Workbench ****************** MySQL Workbench provides a graphical tool for working with MySQL Servers and databases. MySQL Workbench fully supports MySQL Server versions 5.1 and above. It is also compatible with MySQL Server 5.0, but not every feature of 5.0 may be supported. It does not support MySQL Server versions 4.x. 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 three 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. This functionality replaces that previously provided by the MySQL Administrator standalone application. MySQL Workbench is available in two editions, the Community Edition and the Standard Edition. The Community Edition is available free of charge. The Standard Edition provides additional Enterprise features, such as database documentation generation, at low cost.  File: manual.info, Node: mysql-for-excel, Next: licenses-third-party, Prev: workbench, Up: Top 25 MySQL for Excel ****************** * Menu: * mysql-for-excel-install:: Installing and Configuring * mysql-for-excel-edit:: Edit MySQL Data in Excel * mysql-for-excel-import:: Import MySQL Data into Excel * mysql-for-excel-append:: Append Excel Data into MySQL * mysql-for-excel-export:: Export Excel Data into MySQL * mysql-for-excel-faq:: MySQL for Excel FAQ MySQL for Excel enables you to work with a MySQL database from within Microsoft Excel. MySQL data can be imported into Excel, Excel data can be exported into MySQL as a new table or appended to a current table, and MySQL for Excel enables you to edit the MySQL data directly from within Excel. Visit the MySQL for Excel forum (http://forums.mysql.com/list.php?172) for additional MySQL for Excel help and support. For release notes detailing the changes in each release of MySQL for Excel, see MySQL for Excel Release Notes (http://dev.mysql.com/doc/relnotes/mysql-for-excel/en/).  File: manual.info, Node: mysql-for-excel-install, Next: mysql-for-excel-edit, Prev: mysql-for-excel, Up: mysql-for-excel 25.1 Installing and Configuring =============================== MySQL for Excel is a product for Microsoft Windows, and it is installed with MySQL Installer. And typically you will not be required to install or configure additional tools to use MySQL for Excel. *Note*: To install, download and execute the MySQL Installer (http://dev.mysql.com/downloads/installer/). Select the MySQL for Excel product and then proceed with the installation. See the MySQL Installer manual (http://dev.mysql.com/doc/refman/5.5/en/mysql-installer.html) for additional details. * MySQL for Excel Requirements * The MySQL Installer installation process will check if these requirements are met, or notify you if further action is required before proceeding with the installation. * .NET Framework 4.0 (Client or Full Profile). * Microsoft Office Excel 2007 or greater, for Microsoft Windows. * Visual Studio Tools for Office 4.0, and MySQL Installer may install this for you. * An available MySQL Server connection. MySQL for Excel is loaded and executed by selecting the `Data' menu tab in Excel, and then choosing the "MySQL for Excel" Database icon. This opens a new Excel sidebar with the available MySQL for Excel options. The navigation bar with the MySQL for Excel icon is shown in the following screenshot: FIGURE GOES HERE: The MySQL for Excel navigation bar  File: manual.info, Node: mysql-for-excel-edit, Next: mysql-for-excel-import, Prev: mysql-for-excel-install, Up: mysql-for-excel 25.2 Edit MySQL Data in Excel ============================= MySQL for Excel enables you to load and edit MySQL data directly from Microsoft Excel. Changes are immediately committed if the `Auto-Commit' option is enabled, or done manually by pressing `Commit Changes'. *Note*: The `Edit MySQL Data' feature exists as of MySQL for Excel 1.1.0. The example below uses the `category' table of the example `sakila' database, but the screen will look the same for any table. Within MySQL for Excel, `Open a MySQL Connection', click the `sakila' schema, `Next', select the `category' table, click `Edit MySQL Data', then choose `Import' to import the data into a new Microsoft Excel worksheet for editing. FIGURE GOES HERE: Editing table data with MySQL for Excel The background color represents the status of each cell, and there are four distinct colors that are used while editing table data: *Background cell colors* Color Description White Default color for all cells. This is either the original data, or the data after `Refresh from DB' is clicked. Blue Cells that were committed with success. Green Cells that were modified but have not yet been committed. Red Cells that generated an error when a commit was attempted. An error dialog is also displayed while the commit is attempted. Yellow Cells that accept new data. Data entered here is inserted into the MySQL table. In our example, the blue "Drama" field was changed and then committed first, then the green "Gaming" field was changed but not committed, and then `Auto-Commit' was enabled before changing the "9" to a "10" in column 10, which generated an error because this commit would have added a duplicate value as primary key.  File: manual.info, Node: mysql-for-excel-import, Next: mysql-for-excel-append, Prev: mysql-for-excel-edit, Up: mysql-for-excel 25.3 Import MySQL Data into Excel ================================= Data can be imported from MySQL into a Microsoft Excel spreadsheet by using the `Import MySQL Data' option after selecting either a table, view, or procedure to import. * Choosing columns to import * By default, all columns are selected and will be imported. Specific columns may be selected (or unselected) using the standard Microsoft Windows method of either `Control' + `Mouse click' to toggle the selection of individual columns, or `Shift' + `Mouse click' to select a range of columns. The background color of a column shows the status of each column. The color white means that the column has been selected, and therefore it will be imported. Conversely, a gray background means that the column will not be imported. Right-clicking anywhere in the preview grid opens a context-menu with either a `Select None' or `Select All' option, depending on the current status. * Importing a table * The dialog while importing a table includes the following options: * `Include Column Names as Headers': Enabled by default, this inserts the column names at the top of the Microsoft Excel spreadsheet as a "headers" row. * `Limit to ___ Rows and Start with Row ___': Disabled by default, this limits the range of imported data. The `Limit to' option defaults to `1', and defines the number of rows to import. The `Start with Row' option defaults to `1' (the first row), and defines where the import begins. Each option has a maximum value of COUNT(rows) in the table. Importing a table displays a dialog similar to the following: FIGURE GOES HERE: Importing table data with MySQL for Excel * Importing a view or procedure * Importing a view or procedure displays a similar dialogue, but with the following options: * `Include Column Names as Headers': Enabled by default, this will insert the column names at the top of the Excel spreadsheet as a "headers" row. * `Import': Because a procedure might return multiple result sets, the import options include: * `Selected Result Set': Imports the selected tab sheet. This is the default behavior. * `All Result Sets - Arranged Horizontally': Imports all result sets into the Excel Worksheet horizontally, and inserts one empty column between each result set. * `All Result Sets - Arranged Vertically': Imports all result sets into the Excel Worksheet vertically, and inserts one empty row between each result set. For example, a dialogue like the following is displayed after importing a procedure and pressing the `Call' button to invoke the stored procedure: FIGURE GOES HERE: Importing called stored procedure data with MySQL for Excel  File: manual.info, Node: mysql-for-excel-append, Next: mysql-for-excel-export, Prev: mysql-for-excel-import, Up: mysql-for-excel 25.4 Append Excel Data into MySQL ================================= Data from a Microsoft Excel spreadsheet can be appended to a MySQL database table by using the `Append Excel MySQL Data to Table' option. * Column mappings * Mapping the Excel columns to the MySQL columns can be executed automatically (default), manually, or by using a stored mapping routine. An automatic mapping routine is the default, and can be can be tweaked if every column cannot be matched automatically. The following screenshot shows two columns of Excel data, and the preview dialog after choosing `Append Excel Data to Table': FIGURE GOES HERE: Appending Excel data to MySQL (Automatic mapping) * General mapping information * It is common to tweak the column mappings. A few notes about the manual mapping process: * Manual mapping is performed by dragging a column from the upper source grid (Excel spreadsheet) and dropping it into the lower target column MySQL table grid. Click anywhere within the column to initiate this dragging routine. * The color of the header field for each column defines the current mapping status of the column. The colors include: * Green: A source column is mapped to a target column. * Red: A target column is not mapped. * Gray: A source column is not mapped. * A source column may be mapped to multiple target columns, although this action generates a warning dialog. * Right-clicking a target column shows a context menu with options to either `Remove Column Mapping' for a single column, or to `Clear All Mappings' for all columns. Dragging a target column outside of the grid removes the mapping. * Mapping methods * The three mapping methods are described below: * `Automatic': The automatic mapping method attempts to match the Excel source column names with the MySQL target table column names. It is then possible to manually tweak the mapping afterwards. If the automatic process finds zero columns to match, then a simple 1 to 1 matching routine is attempted. Meaning, SourceColumn #1 to TargetColumn #1, SourceColumn #2 to TargetColumn #2, and so on. * `Manual': The source column names are manually dragged (matched) with the target column names. Manual dragging can also be performed after the `Automatic' method is selected. * `Stored': Manual mapping styles may be saved using the `Store Mapping' button, which will also prompt for a name and then save it using a "NAME (dbname.tablename)" naming scheme. The saved mapping style will then be available alongside the `Automatic' and `Manual' options. Stored mappings may be deleted or renamed within the `Advanced Options' dialog. * Advanced Options * There are several advanced options that are configured and stored between sessions for each Excel user. The dialog looks similar to: FIGURE GOES HERE: Appending Excel data to MySQL (Advanced Options) The advanced `Mapping Options': * `Perform an automatic mapping when dialog opens': Automatically attempt to map the target and source when the `Append Data' dialog is opened. This feature is enabled by default. * `Automatically store the column mapping for the given table': Stores each mapping routine after executing the `Append' operation. The mapping routine is saved using the "tablenameMapping (dbname.tablename)" format. This may also be performed manually using the `Store Mapping' button. It is enabled by default, and this feature was added in MySQL for Excel 1.1.0. * `Reload stored column mapping for the selected table automatically': If a stored mapping routine exists that matches all column names in the source grid with the target grid, then it is automatically be loaded. This is enabled by default, and this feature was added in MySQL for Excel 1.1.0. The advanced `Field Data Options': * `Use the first' 100 (default) Excel data rows to preview and calculate data types. This determines the number of rows that the preview displays, and the values that affect the automatic mapping feature. * `Use formatted values': The data from Excel is treated as `Text', `Double', or `Date'. This is enabled by default. When disabled, data is never treated as a `Date' type, so for example, this means that a date would be represented as a number. The `Stored Column Mappings' is a list of saved column mappings that were saved with with the "Automatically store the column mapping for the given table" feature, or manually with the `Store Mapping' option.  File: manual.info, Node: mysql-for-excel-export, Next: mysql-for-excel-faq, Prev: mysql-for-excel-append, Up: mysql-for-excel 25.5 Export Excel Data into MySQL ================================= Data from a Microsoft Excel spreadsheet can be exported to a new MySQL database table by using the `Export Excel Data to New Table' option. Exporting data looks like so: FIGURE GOES HERE: Exporting Excel data to MySQL * Advanced Export options * Several advanced options enables you to tweak the exported data. The advanced options dialog looks like so: FIGURE GOES HERE: Exporting Excel data to MySQL (Advanced options) * `Column Datatype Options': * Use the first 100 (default) Excel data rows to preview and calculate data types: This determines the number of rows that the preview displays, and the values that affect the automatic mapping feature. * Analyze and try to detect correct datatype based on column field contents: Attempts to analyze the data and determine the data type for the column. The column type is defined as `VARCHAR' if it contains multiple types. * Add additional buffer to `VARCHAR' length (round up to 12, 25, 45, 125, 255): When the data type is automatically detected and is set to `VARCHAR', then it calculates the maximum length for all rows within the column, and rounds up the maximum length to one of the defined lengths above. If disabled, then the `VARCHAR' length is set to the length of the longest entry in the Excel spreadsheet. * Automatically check the Index checkbox for Integer columns: If enabled (default), columns with an Integer data type will have the `Create Index' option enabled by default. * Automatically check the Allow Empty checkbox for columns without an index: If enabled (default), columns without the `Create Index' checkbox checked will automatically enable the `Allow Empty' configuration option. * `Field Data options': * Use formatted values: When enabled (default), the data from Excel is treated as `Text', `Double', or `Date'. When disabled, data is never treated as a `Date' type, so for example this means that a date would be represented as a number. * `Other options': * Remove columns that contain no data, otherwise flag them as "Excluded": If enabled, columns without data in Excel are removed and not shown in the preview panel. If disabled (default), these columns will exist but have the `Exclude Column' option checked. This option was added in MySQL for Excel 1.1.0.  File: manual.info, Node: mysql-for-excel-faq, Prev: mysql-for-excel-export, Up: mysql-for-excel 25.6 MySQL for Excel FAQ ======================== Frequently Asked Questions, with Answers. *Questions* * 26.6.1: I installed the MySQL for Excel plugin, but can't find it in Microsoft Excel. How do I start it? * 26.6.2: I click on `Edit Data' and after importing the table data into Excel, I can't sort or move columns around. How can I do that? * 26.6.3: When editing a MySQL table's data, the Excel worksheet where the data is dumped is protected. How can unprotect it? * 26.6.4: The MySQL Workbench connections that use SSH tunneling appear grayed out (disabled) in MySQL for Excel. How can I use a SSH connection? *Questions and Answers* *26.6.1: ** I installed the MySQL for Excel plugin, but can't find it in Microsoft Excel. How do I start it? * The MySQL for Excel plugin is automatically added to Microsoft Excel's data menu when it is installed. Look for the MySQL for Excel icon, by default it will be listed on the right side of the main menu. If it's not there, then you might have to reinstall the plugin. But before doing so, first check if it's listed under "Add/Remove Programs" in Microsoft Windows. If not, then it has not been installed. Next, check the Excel Add-Ins list. For Office 2007 this is found by clicking the Office logo in Excel (top left corner), click `Excel Options', then select `Add-Ins'. Is MySQL for Excel listed as a COM Add-in? If so, then consider filing a bug report (bugs.mysql.com), or attempt to reinstall the plugin. *26.6.2: ** I click on `Edit Data' and after importing the table data into Excel, I can't sort or move columns around. How can I do that? * In order to maintain the mapping of rows and columns in the Excel Worksheet against the rows and columns in the MySQL table, no alteration is permitted on the worksheet (i.e. sorting, deleting rows, deleting columns). If you need to alter the data there you can do that by right-clicking the `Edit Data' window and selecting `Exit Edit Mode'. *26.6.3: ** When editing a MySQL table's data, the Excel worksheet where the data is dumped is protected. How can unprotect it? * The Excel worksheet is protected to not allow alterations to the order of rows and columns. The password used for the protection is a GUID auto-generated at runtime so that the protection is not violated in any way. If you wish to unprotect the worksheet to manipulate your data, you can do that by right-clicking the `Edit Data' window and selecting `Exit Edit Mode'. *26.6.4: ** The MySQL Workbench connections that use SSH tunneling appear grayed out (disabled) in MySQL for Excel. How can I use a SSH connection? * This is a known limitation of MySQL for Excel. MySQL for Excel uses MySQL Connector/NET to connect and communicate with MySQL databases. Connector/NET does not have SSH support, so the behavior will change if Connector/NET supports it in the future.  File: manual.info, Node: licenses-third-party, Next: faqs, Prev: mysql-for-excel, Up: Top Appendix A Licenses for Third-Party Components ********************************************** * Menu: * license-ant-contrib:: Ant-Contrib License * license-antlr-3:: ANTLR 3 License * license-antlr-3-3:: ANTLR 3.3 License * license-boost:: Boost Library License * license-bouncy-castle-1-7:: Bouncy Castle 1.7 License * license-c3p0-0-91:: c3p0 JDBC Library License * license-django-151:: Django 1.5.1 License * license-dtoa:: `dtoa.c' License * license-libedit:: Editline Library (`libedit') License * license-findgtest-cmake:: `FindGTest.cmake' License * license-dbug:: Fred Fish's Dbug Library License * license-getarg:: `getarg' License * license-glib-proxy:: GLib License (for MySQL Proxy) * license-gnu-gpl-2-0:: GNU General Public License Version 2.0, June 1991 * license-gnu-lgpl-2-1:: GNU Lesser General Public License Version 2.1, February 1999 * license-gnu-libtool:: GNU Libtool License * license-gnu-readline:: GNU Readline License * license-google-io-rate-patch:: Google Controlling Master Thread I/O Rate Patch License * license-google-tcmalloc:: Google Perftools (TCMalloc utility) License * license-google-smp-patch:: Google SMP Patch License * license-jboss-common-jdbc-wrapper:: jboss-common-jdbc-wrapper.jar License * license-lib-sql:: `lib_sql.cc' License * license-libevent:: `libevent' License * license-libiconv-proxy:: Libiconv License * license-libintl:: `libintl' License * license-linux-pam:: Linux-PAM License * license-lpeg:: `LPeg' Library License * license-lua:: Lua (liblua) License * license-luafilesystem:: `LuaFileSystem' Library License * license-md5:: md5 (Message-Digest Algorithm 5) License * license-memcached:: `memcached' License * license-nt-servc:: nt_servc (Windows NT Service class library) License * license-openpam:: OpenPAM License * license-openssl-1-0:: OpenSSL v1.0 License * license-paramiko:: Paramiko License * license-pcre:: PCRE License * license-percona-io-threads-patch:: Percona Multiple I/O Threads Patch License * license-regex:: RegEX-Spencer Library License * license-us-secure-hash:: RFC 3174 - US Secure Hash Algorithm 1 (SHA1) License * license-libstring:: Richard A. O'Keefe String Library License * license-sha1-in-c:: SHA-1 in C License * license-slf4j:: Simple Logging Facade for Java (SLF4J) License * license-zlib:: `zlib' License * license-zlib-net:: ZLIB.NET License The following is a list of the libraries we have included with the MySQL Server source and components used to test MySQL. We are thankful to all individuals that have created these. Some of the components require that their licensing terms be included in the documentation of products that include them. Cross references to these licensing terms are given with the applicable items in the list. * Bjorn Benson For his safe_malloc (memory checker) package which is used in when you build MySQL using one of the `BUILD/compile-*-debug' scripts or by manually setting the `-DSAFEMALLOC' flag. * GroupLens Research Project The MySQL Quality Assurance team would like to acknowledge the use of the MovieLens Data Sets (10 million ratings and 100,000 tags for 10681 movies by 71567 users) to help test MySQL products and to thank the GroupLens Research Project at the University of Minnesota for making the data sets available. *MySQL 5.1* * *Note license-dtoa:: * *Note license-libedit:: * *Note license-findgtest-cmake:: * *Note license-dbug:: * *Note license-getarg:: * *Note license-gnu-gpl-2-0:: * *Note license-gnu-libtool:: * *Note license-gnu-readline:: * *Note license-google-io-rate-patch:: * *Note license-google-smp-patch:: * *Note license-lib-sql:: * *Note license-md5:: * *Note license-nt-servc:: * *Note license-percona-io-threads-patch:: * *Note license-regex:: * *Note license-us-secure-hash:: * *Note license-libstring:: * *Note license-zlib:: *MySQL Cluster 7.1* * *Note license-antlr-3:: * *Note license-dtoa:: * *Note license-libedit:: * *Note license-findgtest-cmake:: * *Note license-dbug:: * *Note license-getarg:: * *Note license-gnu-gpl-2-0:: * *Note license-gnu-lgpl-2-1:: * *Note license-gnu-libtool:: * *Note license-gnu-readline:: * *Note license-google-io-rate-patch:: * *Note license-google-tcmalloc:: * *Note license-google-smp-patch:: * *Note license-lib-sql:: * *Note license-libevent:: * *Note license-linux-pam:: * *Note license-md5:: * *Note license-memcached:: * *Note license-nt-servc:: * *Note license-openpam:: * *Note license-paramiko:: * *Note license-percona-io-threads-patch:: * *Note license-regex:: * *Note license-libstring:: * *Note license-sha1-in-c:: * *Note license-zlib:: *MySQL Connector/C 6.0* * *Note license-dbug:: * *Note license-regex:: * *Note license-us-secure-hash:: * *Note license-zlib:: *MySQL Connector/C 6.1* * *Note license-dtoa:: * *Note license-dbug:: * *Note license-gnu-gpl-2-0:: * *Note license-md5:: * *Note license-regex:: * *Note license-libstring:: * *Note license-sha1-in-c:: * *Note license-zlib:: *MySQL Connector/C++* * *Note license-boost:: * *Note license-openssl-1-0:: *MySQL Connector/J* * *Note license-ant-contrib:: * *Note license-c3p0-0-91:: * *Note license-gnu-lgpl-2-1:: * *Note license-jboss-common-jdbc-wrapper:: * *Note license-slf4j:: *MySQL Connector/Net 1.0-6.4* * *Note license-antlr-3-3:: * *Note license-us-secure-hash:: * *Note license-zlib:: * *Note license-zlib-net:: *MySQL Connector/Net 6.5-6.6* * *Note license-antlr-3-3:: * *Note license-zlib:: * *Note license-zlib-net:: *MySQL Connector/Net 6.7* * *Note license-antlr-3-3:: * *Note license-bouncy-castle-1-7:: * *Note license-zlib:: * *Note license-zlib-net:: *MySQL Connector/ODBC* * *Note license-gnu-libtool:: * *Note license-openssl-1-0:: *MySQL Connector/Python 1.1* * *Note license-django-151:: *MySQL Proxy* * *Note license-glib-proxy:: * *Note license-gnu-lgpl-2-1:: * *Note license-libevent:: * *Note license-libiconv-proxy:: * *Note license-libintl:: * *Note license-lpeg:: * *Note license-lua:: * *Note license-luafilesystem:: * *Note license-pcre::  File: manual.info, Node: license-ant-contrib, Next: license-antlr-3, Prev: licenses-third-party, Up: licenses-third-party A.1 Ant-Contrib License ======================= The following software may be included in this product up to version 5.1.26: Ant-Contrib Ant-Contrib Copyright (c) 2001-2003 Ant-Contrib project. All rights reserved. Licensed under the Apache 1.1 License Agreement, a copy of which is reproduced below. The Apache Software License, Version 1.1 Copyright (c) 2001-2003 Ant-Contrib project. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The end-user documentation included with the redistribution, if any, must include the following acknowlegement: "This product includes software developed by the Ant-Contrib project (http://sourceforge.net/projects/ant-contrib)." Alternately, this acknowlegement may appear in the software itself, if and wherever such third-party acknowlegements normally appear. 4. The name Ant-Contrib must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact ant-contrib-developers@lists.sourceforge.net. 5. Products derived from this software may not be called "Ant-Contrib" nor may "Ant-Contrib" appear in their names without prior written permission of the Ant-Contrib project. THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ANT-CONTRIB PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-antlr-3, Next: license-antlr-3-3, Prev: license-ant-contrib, Up: licenses-third-party A.2 ANTLR 3 License =================== The following software may be included in this product: ANTLR 3 ANTLR 3 License [The BSD License] Copyright (c) 2003-2007, Terence Parr All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-antlr-3-3, Next: license-boost, Prev: license-antlr-3, Up: licenses-third-party A.3 ANTLR 3.3 License ===================== The following software may be included in this product: ANTLR 3.3 ANTLR 3.3 License Copyright (c) 2010 Terence Parr All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-boost, Next: license-bouncy-castle-1-7, Prev: license-antlr-3-3, Up: licenses-third-party A.4 Boost Library License ========================= The following software may be included in this product: *Boost C++ Libraries* Use of any of this software is governed by the terms of the license below: Boost Software License - Version 1.0 - August 17th, 2003 Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following: The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.  File: manual.info, Node: license-bouncy-castle-1-7, Next: license-c3p0-0-91, Prev: license-boost, Up: licenses-third-party A.5 Bouncy Castle 1.7 License ============================= The following software may be included in this product: Bouncy Castle 1.7 Copyright (c) 2000 - 2011 The Legion Of The Bouncy Castle (http://www.bouncycastle.org) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.  File: manual.info, Node: license-c3p0-0-91, Next: license-django-151, Prev: license-bouncy-castle-1-7, Up: licenses-third-party A.6 c3p0 JDBC Library License ============================= You are receiving a copy of `c3p0-0.9.1-pre6.jar' in both source and object code in the following `/src/lib/c3p0-0.9.1-pre6.jar'. The terms of the Oracle license do NOT apply to `c3p0-0.9.1-pre6.jar'; it is licensed under the following license, separately from the Oracle programs you receive. If you do not wish to install this library, you may remove the file `/src/lib/c3p0-0.9.1-pre6.jar', but the Oracle program might not operate properly or at all without the library. This component is licensed under *Note license-gnu-lgpl-2-1::.  File: manual.info, Node: license-django-151, Next: license-dtoa, Prev: license-c3p0-0-91, Up: licenses-third-party A.7 Django 1.5.1 License ======================== The following software may be included in this product: Copyright (c) Django Software Foundation and individual contributors. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of Django nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-dtoa, Next: license-libedit, Prev: license-django-151, Up: licenses-third-party A.8 `dtoa.c' License ==================== The following software may be included in this product: `dtoa.c' The author of this software is David M. Gay. Copyright (c) 1991, 2000, 2001 by Lucent Technologies. Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software. THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENT MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.  File: manual.info, Node: license-libedit, Next: license-findgtest-cmake, Prev: license-dtoa, Up: licenses-third-party A.9 Editline Library (`libedit') License ======================================== The following software may be included in this product: Editline Library (libedit) Some files are: Copyright (c) 1992, 1993 The Regents of the University of California. All rights reserved. This code is derived from software contributed to Berkeley by Christos Zoulas of Cornell University. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Some files are: Copyright (c) 2001 The NetBSD Foundation, Inc. All rights reserved. This code is derived from software contributed to The NetBSD Foundation by Anthony Mallet. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Some files are: Copyright (c) 1997 The NetBSD Foundation, Inc. All rights reserved. This code is derived from software contributed to The NetBSD Foundation by Jaromir Dolecek. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Some files are: Copyright (c) 1998 Todd C. Miller Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND TODD C. MILLER DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL TODD C. MILLER BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.  File: manual.info, Node: license-findgtest-cmake, Next: license-dbug, Prev: license-libedit, Up: licenses-third-party A.10 `FindGTest.cmake' License ============================== The following software may be included in this product: FindGTest.cmake helper script (part of CMake) Copyright 2009 Kitware, Inc. Copyright 2009 Philip Lowman Copyright 2009 Daniel Blezek Distributed under the OSI-approved BSD License (the "License"); see accompanying file Copyright.txt for details. This software is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the License for more information. ========================================================================== (To distributed this file outside of CMake, substitute the full License text for the above reference.) Thanks to Daniel Blezek for the GTEST_ADD_TESTS code Text of Copyright.txt mentioned above: CMake - Cross Platform Makefile Generator Copyright 2000-2009 Kitware, Inc., Insight Software Consortium All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the names of Kitware, Inc., the Insight Software Consortium, nor the names of their contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-dbug, Next: license-getarg, Prev: license-findgtest-cmake, Up: licenses-third-party A.11 Fred Fish's Dbug Library License ===================================== The following software may be included in this product: Fred Fish's Dbug Library N O T I C E Copyright Abandoned, 1987, Fred Fish This previously copyrighted work has been placed into the public domain by the author and may be freely used for any purpose, private or commercial. Because of the number of inquiries I was receiving about the use of this product in commercially developed works I have decided to simply make it public domain to further its unrestricted use. I specifically would be most happy to see this material become a part of the standard Unix distributions by AT&T and the Berkeley Computer Science Research Group, and a standard part of the GNU system from the Free Software Foundation. I would appreciate it, as a courtesy, if this notice is left in all copies and derivative works. Thank you. The author makes no warranty of any kind with respect to this product and explicitly disclaims any implied warranties of mer- chantability or fitness for any particular purpose. The dbug_analyze.c file is subject to the following notice: Copyright June 1987, Binayak Banerjee All rights reserved. This program may be freely distributed under the same terms and conditions as Fred Fish's Dbug package.  File: manual.info, Node: license-getarg, Next: license-glib-proxy, Prev: license-dbug, Up: licenses-third-party A.12 `getarg' License ===================== The following software may be included in this product: `getarg' Function (`getarg.h', `getarg.c' files) Copyright (c) 1997 - 2000 Kungliga Tekniska Ho"gskolan (Royal Institute of Technology, Stockholm, Sweden). All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the Institute nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-glib-proxy, Next: license-gnu-gpl-2-0, Prev: license-getarg, Up: licenses-third-party A.13 GLib License (for MySQL Proxy) =================================== The following software may be included in this product: GLib You are receiving a copy of the GLib library in both source and object code in the following [proxy install dir]/lib/ and [proxy install dir]/licenses/lgpl folders. The terms of the Oracle license do NOT apply to the GLib library; it is licensed under the following license, separately from the Oracle programs you receive. If you do not wish to install this library, you may create an "exclude" file and run tar with the X option, as in the following example, but the Oracle program might not operate properly or at all without the library: tar -xvfX where the exclude-file contains, e.g.: /lib/libglib-2.0.so.0.1600.6 /lib/libglib-2.0.so.0 ... Example: tar -xvfX mysql-proxy-0.8.1-solaris10-x86-64bit.tar.gz Exclude Exclude File: mysql-proxy-0.8.1-solaris10-x86-64bit/lib/libglib-2.0.so mysql-proxy-0.8.1-solaris10-x86-64bit/lib/libglib-2.0.so.0 mysql-proxy-0.8.1-solaris10-x86-64bit/lib/libglib-2.0.so.0.1600.6 mysql-proxy-0.8.1-solaris10-x86-64bit/lib/libgmodule-2.0.so mysql-proxy-0.8.1-solaris10-x86-64bit/lib/libgmodule-2.0.so.0 mysql-proxy-0.8.1-solaris10-x86-64bit/lib/libgmodule-2.0.so.0.1600.6 mysql-proxy-0.8.1-solaris10-x86-64bit/lib/libgthread-2.0.so mysql-proxy-0.8.1-solaris10-x86-64bit/lib/libgthread-2.0.so.0 mysql-proxy-0.8.1-solaris10-x86-64bit/lib/libgthread-2.0.so.0.1600.6 mysql-proxy-0.8.1-solaris10-x86-64bit/licenses/lgpl/glib-2.16.6.tar.gz This component is licensed under *Note license-gnu-lgpl-2-1::.  File: manual.info, Node: license-gnu-gpl-2-0, Next: license-gnu-lgpl-2-1, Prev: license-glib-proxy, Up: licenses-third-party A.14 GNU General Public License Version 2.0, June 1991 ====================================================== The following applies to all products licensed under the GNU General Public License, Version 2.0: You may not use the identified files except in compliance with the GNU General Public License, Version 2.0 (the "License.") You may obtain a copy of the License at http://www.gnu.org/licenses/gpl-2.0.txt. A copy of the license is also reproduced below. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) 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 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. This is free software, and you are welcome to redistribute it under certain conditions; type 'show c' for details. The hypothetical commands 'show w' and 'show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than 'show w' and 'show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program 'Gnomovision' (which makes passes at compilers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License.  File: manual.info, Node: license-gnu-lgpl-2-1, Next: license-gnu-libtool, Prev: license-gnu-gpl-2-0, Up: licenses-third-party A.15 GNU Lesser General Public License Version 2.1, February 1999 ================================================================= The following applies to all products licensed under the GNU Lesser General Public License, Version 2.1: You may not use the identified files except in compliance with the GNU Lesser General Public License, Version 2.1 (the "License"). You may obtain a copy of the License at http://www.gnu.org/licenses/lgpl-2.1.html. A copy of the license is also reproduced below. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999 Copyright (C) 1991, 1999 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the Lesser GPL. It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.] Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This license, the Lesser General Public License, applies to some specially designated software packages--typically libraries--of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below. When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things. To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it. For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link other code with the library, you must provide complete object files to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them these terms so they know their rights. We protect your rights with a two-step method: (1) we copyright the library, and (2) we offer you this license, which gives you legal permission to copy, distribute and/or modify the library. To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modified by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by others. Finally, software patents pose a constant threat to the existence of any free program. We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license. Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those libraries into non-free programs. When a program is linked with a library, whether statically or using a shared library, the combination of the two is legally speaking a combined work, a derivative of the original library. The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library. We call this license the "Lesser" General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances. For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that a free library does the same job as widely used non-free libraries. In this case, there is little to gain by limiting the free library to free software only, so we use the Lesser General Public License. In other cases, permission to use a particular library in non-free programs enables a greater number of people to use a large body of free software. For example, permission to use the GNU C Library in non-free programs enables many more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating system. Although the Lesser General Public License is Less protective of the users' freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library. The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, whereas the latter must be combined with the library in order to run. GNU LESSER GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called "this License"). Each licensee is addressed as "you". A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) The modified work must itself be a software library. b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. This option is useful when you wish to copy part of the code of the Library into a program that is not a library. 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. 6. As an exception to the Sections above, you may also combine or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with. c) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. d) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. e) Verify that the user has already received a copy of these materials or that you have already sent this user a copy. For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute. 7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things: a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it. 10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License. 11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Libraries If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License). To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library 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 Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Also add information on how to contact you by electronic and paper mail. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. , 1 April 1990 Ty Coon, President of Vice That's all there is to it!  File: manual.info, Node: license-gnu-libtool, Next: license-gnu-readline, Prev: license-gnu-lgpl-2-1, Up: licenses-third-party A.16 GNU Libtool License ======================== The following software may be included in this product: GNU Libtool (The GNU Portable Library Tool) If you are receiving a copy of the Oracle software in source code, you are also receiving a copy of two files (ltmain.sh and ltdl.h) generated by the GNU Libtool in source code. If you received the Oracle software under a license other than a commercial (non-GPL) license, then the terms of the Oracle license do NOT apply to these files from GNU Libtool; they are licensed under the following licenses, separately from the Oracle programs you receive. Oracle elects to use GNU General Public License version 2 (GPL) for any software where a choice of GPL or GNU Lesser/Library General Public License (LGPL) license versions are made available with the language indicating that GPL/LGPL or any later version may be used, or where a choice of which version of the GPL/LGPL is applied is unspecified. From GNU Libtool: ltmain.sh - Provide generalized library-building support services. NOTE: Changing this file will not affect anything until you rerun configure. Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. Originally by Gordon Matzigkeit, 1996 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 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. As a special exception to the GNU General Public License, if you distribute this file as part of a program that contains a configuration script generated by Autoconf, you may include it under the same distribution terms that you use for the rest of that program. This component is licensed under *Note license-gnu-gpl-2-0::  File: manual.info, Node: license-gnu-readline, Next: license-google-io-rate-patch, Prev: license-gnu-libtool, Up: licenses-third-party A.17 GNU Readline License ========================= The following software may be included in this product: GNU Readline Library GNU Readline Library With respect to MySQL Server/Cluster software licensed under GNU General Public License, you are receiving a copy of the GNU Readline Library in source code. The terms of any Oracle license that might accompany the Oracle programs do NOT apply to the GNU Readline Library; it is licensed under the following license, separately from the Oracle programs you receive. Oracle elects to use GNU General Public License version 2 (GPL) for any software where a choice of GPL license versions are made available with the language indicating that GPLv2 or any later version may be used, or where a choice of which version of the GPL is applied is unspecified. This component is licensed under *Note license-gnu-gpl-2-0::  File: manual.info, Node: license-google-io-rate-patch, Next: license-google-tcmalloc, Prev: license-gnu-readline, Up: licenses-third-party A.18 Google Controlling Master Thread I/O Rate Patch License ============================================================ The following software may be included in this product: Google Controlling master thread I/O rate patch Copyright (c) 2009, Google Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the Google Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-google-tcmalloc, Next: license-google-smp-patch, Prev: license-google-io-rate-patch, Up: licenses-third-party A.19 Google Perftools (TCMalloc utility) License ================================================ The following software may be included in this product: Google Perftools (TCMalloc utility) Copyright (c) 1998-2006, Google Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Google Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-google-smp-patch, Next: license-jboss-common-jdbc-wrapper, Prev: license-google-tcmalloc, Up: licenses-third-party A.20 Google SMP Patch License ============================= The following software may be included in this product: Google SMP Patch Google SMP patch Copyright (c) 2008, Google Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the Google Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-jboss-common-jdbc-wrapper, Next: license-lib-sql, Prev: license-google-smp-patch, Up: licenses-third-party A.21 jboss-common-jdbc-wrapper.jar License ========================================== You are receiving a copy of `jboss-common-jdbc-wrapper.jar' in both source and object code in the following `/src/lib/jboss-common-jdbc-wrapper.jar'. The terms of the Oracle license do NOT apply to `jboss-common-jdbc-wrapper.jar'; it is licensed under the following license, separately from the Oracle programs you receive. If you do not wish to install this library, you may remove the file `/src/lib/jboss-common-jdbc-wrapper.jar', but the Oracle program might not operate properly or at all without the library. This component is licensed under *Note license-gnu-lgpl-2-1::.  File: manual.info, Node: license-lib-sql, Next: license-libevent, Prev: license-jboss-common-jdbc-wrapper, Up: licenses-third-party A.22 `lib_sql.cc' License ========================= The following software may be included in this product: `lib_sql.cc' Copyright (c) 2000 SWsoft company This material is provided "as is", with absolutely no warranty expressed or implied. Any use is at your own risk. Permission to use or copy this software for any purpose is hereby granted without fee, provided the above notices are retained on all copies. Permission to modify the code and to distribute modified code is granted, provided the above notices are retained, and a notice that the code was modified is included with the above copyright notice. This code was modified by the MySQL team.  File: manual.info, Node: license-libevent, Next: license-libiconv-proxy, Prev: license-lib-sql, Up: licenses-third-party A.23 `libevent' License ======================= The following software may be included in this product: libevent Copyright (c) 2000-2007 Niels Provos All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE == Parts developed by Adam Langley == == log.c Based on err.c, which was adapted from OpenBSD libc *err*warncode. Copyright (c) 2005 Nick Mathewson Copyright (c) 2000 Dug Song Copyright (c) 1993 The Regents of the University of California. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. == == min_heap.h Copyright (c) 2006 Maxim Yegorushkin All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. == == win32.c Copyright 2000-2002 Niels Provos Copyright 2003 Michael A. Davis All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ==  File: manual.info, Node: license-libiconv-proxy, Next: license-libintl, Prev: license-libevent, Up: licenses-third-party A.24 Libiconv License ===================== The following software may be included in this product: Libiconv You are receiving a copy of the GNU LIBICONV Library. The terms of the Oracle license do NOT apply to the GNU LIBICONV Library; it is licensed under the following license, separately from the Oracle programs you receive. If you do not wish to install this program, you may delete [agent install dir]/lib/libiconv.* and [agent install dir]/licenses/lgpl/iconv files. This component is licensed under *Note license-gnu-lgpl-2-1::.  File: manual.info, Node: license-libintl, Next: license-linux-pam, Prev: license-libiconv-proxy, Up: licenses-third-party A.25 `libintl' License ====================== The following software may be included in this product: libintl Copyright (C) 1994 X Consortium Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of the X Consortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium. FSF changes to this file are in the public domain. . Copyright 1996-2007 Free Software Foundation, Inc. Taken from GNU libtool, 2001 Originally by Gordon Matzigkeit , 1996 This file is free software; the Free Software Foundation gives unlimited permission to copy and/or distribute it, with or without modifications, as long as this notice is preserved. . You are receiving a copy of the libintl library. The terms of the Oracle license do NOT apply to the libintl library; it is licensed under the following license, separately from the Oracle programs you receive. If you do not wish to install this program, you may create an "exclude" file and run tar with the X option. This component is licensed under *Note license-gnu-lgpl-2-1::.  File: manual.info, Node: license-linux-pam, Next: license-lpeg, Prev: license-libintl, Up: licenses-third-party A.26 Linux-PAM License ====================== The following software may be included in this product: Linux-PAM (pam-devel, Pluggable authentication modules for Linux) Copyright Theodore Ts'o, 1996. All rights reserved. (For the avoidance of doubt, Oracle uses and distributes this component under the terms below and elects not to do so under the GPL even though the GPL is referenced as an option below.) Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, and the entire permission notice in its entirety, including the disclaimer of warranties. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. ALTERNATIVELY, this product may be distributed under the terms of the GNU Public License, in which case the provisions of the GPL are required INSTEAD OF the above restrictions. (This clause is necessary due to a potential bad interaction between the GPL and the restrictions contained in a BSD-style copyright.) THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-lpeg, Next: license-lua, Prev: license-linux-pam, Up: licenses-third-party A.27 `LPeg' Library License =========================== The following software may be included in this product: LPeg Use of any of this software is governed by the terms of the license below: Copyright (C) 2008 Lua.org, PUC-Rio. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.  File: manual.info, Node: license-lua, Next: license-luafilesystem, Prev: license-lpeg, Up: licenses-third-party A.28 Lua (liblua) License ========================= The following software may be included in this product: Lua (liblua) Copyright (C) 1994-2008 Lua.org, PUC-Rio. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.  File: manual.info, Node: license-luafilesystem, Next: license-md5, Prev: license-lua, Up: licenses-third-party A.29 `LuaFileSystem' Library License ==================================== The following software may be included in this product: LuaFileSystem Copyright (C) 2003 Kepler Project. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.  File: manual.info, Node: license-md5, Next: license-memcached, Prev: license-luafilesystem, Up: licenses-third-party A.30 md5 (Message-Digest Algorithm 5) License ============================================= The following software may be included in this product: md5 (Message-Digest Algorithm 5) This code implements the MD5 message-digest algorithm. The algorithm is due to Ron Rivest. This code was written by Colin Plumb in 1993, no copyright is claimed. This code is in the public domain; do with it what you wish. Equivalent code is available from RSA Data Security, Inc. This code has been tested against that, and is equivalent, except that you don't need to include two pages of legalese with every copy. The code has been modified by Mikael Ronstroem to handle calculating a hash value of a key that is always a multiple of 4 bytes long. Word 0 of the calculated 4-word hash value is returned as the hash value.  File: manual.info, Node: license-memcached, Next: license-nt-servc, Prev: license-md5, Up: licenses-third-party A.31 `memcached' License ======================== The following software may be included in this product: memcached Copyright (c) 2003, Danga Interactive, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the Danga Interactive nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-nt-servc, Next: license-openpam, Prev: license-memcached, Up: licenses-third-party A.32 nt_servc (Windows NT Service class library) License ======================================================== The following software may be included in this product: nt_servc (Windows NT Service class library) Windows NT Service class library Copyright Abandoned 1998 Irena Pancirov - Irnet Snc This file is public domain and comes with NO WARRANTY of any kind  File: manual.info, Node: license-openpam, Next: license-openssl-1-0, Prev: license-nt-servc, Up: licenses-third-party A.33 OpenPAM License ==================== The following software may be included in this product: OpenPAM Copyright (c) 2002-2003 Networks Associates Technology, Inc. Copyright (c) 2004-2007 Dag-Erling Sm/orgrav All rights reserved. This software was developed for the FreeBSD Project by ThinkSec AS and Network Associates Laboratories, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS research program. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-openssl-1-0, Next: license-paramiko, Prev: license-openpam, Up: licenses-third-party A.34 OpenSSL v1.0 License ========================= The following software may be included in this product: NOTE: Does not apply to GPL licensed server (OpenSSL is not shipped with it) OpenSSL v1.0 LICENSE ISSUES ============== The OpenSSL toolkit stays under a dual license, i.e. both the conditions of the OpenSSL License and the original SSLeay license apply to the toolkit. See below for the actual license texts. Actually both licenses are BSD-style Open Source licenses. In case of any license issues related to OpenSSL please contact openssl-core@openssl.org. OpenSSL License --------------- / ==================================================================== Copyright (c) 1998-2008 The OpenSSL Project. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: . 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (Link1 /)" . 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact openssl-core@openssl.org. 5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project. 6. Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (Link2 /)" . THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ==================================================================== This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com). Original SSLeay License ----------------------- / Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) All rights reserved. This package is an SSL implementation written by Eric Young (eay@cryptsoft.com). The implementation was written so as to conform with Netscapes SSL. This library is free for commercial and non-commercial use as long as the following conditions are aheared to. The following conditions apply to all code found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation included with this distribution is covered by the same copyright terms except that the holder is Tim Hudson (tjh@cryptsoft.com). Copyright remains Eric Young's, and as such any Copyright notices in the code are not to be removed. If this package is used in a product, Eric Young should be given attribution as the author of the parts of the library used. This can be in the form of a textual message at program startup or in documentation (online or textual) provided with the package. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgement: "This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)" The word 'cryptographic' can be left out if the routines from the library being used are not cryptographic related :-). 4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement: "This product includes software written by Tim Hudson (tjh@cryptsoft.com)" THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. The license and distribution terms for any publically available version or derivative of this code cannot be changed. i.e. this code cannot simply be copied and put under another distribution license [including the GNU Public License.]  File: manual.info, Node: license-paramiko, Next: license-pcre, Prev: license-openssl-1-0, Up: licenses-third-party A.35 Paramiko License ===================== The following software may be included in this product: Paramiko You are receiving a copy of Paramiko in both source and object code. The terms of the Oracle license do NOT apply to the Paramiko program; it is licensed under the following license, separately from the Oracle programs you receive. If you do not wish to install this program, you may delete the Paramiko folder and all its contents. This component is licensed under *Note license-gnu-lgpl-2-1::.  File: manual.info, Node: license-pcre, Next: license-percona-io-threads-patch, Prev: license-paramiko, Up: licenses-third-party A.36 PCRE License ================= The following software may be included in this product: PCRE (Perl Compatible Regular Expressions) Library PCRE LICENCE PCRE is a library of functions to support regular expressions whose syntax and semantics are as close as possible to those of the Perl 5 language. Release 7 of PCRE is distributed under the terms of the "BSD" licence, as specified below. The documentation for PCRE, supplied in the "doc" directory, is distributed under the same terms as the software itself. The basic library functions are written in C and are freestanding. Also included in the distribution is a set of C++ wrapper functions. THE BASIC LIBRARY FUNCTIONS --------------------------- Written by: Philip Hazel Email local part: ph10 Email domain: cam.ac.uk University of Cambridge Computing Service, Cambridge, England. Phone: +44 1223 334714. Copyright (c) 1997-2006 University of Cambridge All rights reserved. THE C++ WRAPPER FUNCTIONS ------------------------- Contributed by: Google Inc. Copyright (c) 2006, Google Inc. All rights reserved. THE "BSD" LICENCE ----------------- Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the University of Cambridge nor the name of Google Inc. nor the names of their contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. End  File: manual.info, Node: license-percona-io-threads-patch, Next: license-regex, Prev: license-pcre, Up: licenses-third-party A.37 Percona Multiple I/O Threads Patch License =============================================== The following software may be included in this product: Percona Multiple I/O threads patch Copyright (c) 2008, 2009 Percona Inc All rights reserved. Redistribution and use of this software in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Percona Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission of Percona Inc. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: license-regex, Next: license-us-secure-hash, Prev: license-percona-io-threads-patch, Up: licenses-third-party A.38 RegEX-Spencer Library License ================================== The following software may be included in this product: Henry Spencer's Regular-Expression Library (RegEX-Spencer) Copyright 1992, 1993, 1994 Henry Spencer. All rights reserved. This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California. Permission is granted to anyone to use this software for any purpose on any computer system, and to alter it and redistribute it, subject to the following restrictions: 1. The author is not responsible for the consequences of use of this software, no matter how awful, even if they arise from flaws in it. 2. The origin of this software must not be misrepresented, either by explicit claim or by omission. Since few users ever read sources, credits must appear in the documentation. 3. Altered versions must be plainly marked as such, and must not be misrepresented as being the original software. Since few users ever read sources, credits must appear in the documentation. 4. This notice may not be removed or altered.  File: manual.info, Node: license-us-secure-hash, Next: license-libstring, Prev: license-regex, Up: licenses-third-party A.39 RFC 3174 - US Secure Hash Algorithm 1 (SHA1) License ========================================================= The following software may be included in this product: RFC 3174 - US Secure Hash Algorithm 1 (SHA1) RFC 3174 - US Secure Hash Algorithm 1 (SHA1) Copyright (C) The Internet Society (2001). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society.  File: manual.info, Node: license-libstring, Next: license-sha1-in-c, Prev: license-us-secure-hash, Up: licenses-third-party A.40 Richard A. O'Keefe String Library License ============================================== The following software may be included in this product: Richard A. O'Keefe String Library The Richard O'Keefe String Library is subject to the following notice: These files are in the public domain. This includes getopt.c, which is the work of Henry Spencer, University of Toronto Zoology, who says of it "None of this software is derived from Bell software. I had no access to the source for Bell's versions at the time I wrote it. This software is hereby explicitly placed in the public domain. It may be used for any purpose on any machine by anyone." I would greatly prefer it if *my* material received no military use. The t_ctype.h file is subject to the following notice: Copyright (C) 1998, 1999 by Pruet Boonma, all rights reserved. Copyright (C) 1998 by Theppitak Karoonboonyanan, all rights reserved. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies. Smaphan Raruenrom and Pruet Boonma makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.  File: manual.info, Node: license-sha1-in-c, Next: license-slf4j, Prev: license-libstring, Up: licenses-third-party A.41 SHA-1 in C License ======================= The following software may be included in this product: SHA-1 in C SHA-1 in C By Steve Reid 100% Public Domain  File: manual.info, Node: license-slf4j, Next: license-zlib, Prev: license-sha1-in-c, Up: licenses-third-party A.42 Simple Logging Facade for Java (SLF4J) License =================================================== The following software may be included in this product: Simple Logging Facade for Java (SLF4J) Copyright (c) 2004-2008 QOS.ch All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.  File: manual.info, Node: license-zlib, Next: license-zlib-net, Prev: license-slf4j, Up: licenses-third-party A.43 `zlib' License =================== The following software may be included in this product: zlib Oracle gratefully acknowledges the contributions of Jean-loup Gailly and Mark Adler in creating the zlib general purpose compression library which is used in this product. zlib.h -- interface of the 'zlib' general purpose compression library Copyright (C) 1995-2004 Jean-loup Gailly and Mark Adler zlib.h -- interface of the 'zlib' general purpose compression library version 1.2.3, July 18th, 2005 Copyright (C) 1995-2005 Jean-loup Gailly and Mark Adler zlib.h -- interface of the 'zlib' general purpose compression library version 1.2.5, April 19th, 2010 Copyright (C) 1995-2010 Jean-loup Gailly and Mark Adler This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose,including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution. Jean-loup Gailly jloup@gzip.org Mark Adler madler@alumni.caltech.edu  File: manual.info, Node: license-zlib-net, Prev: license-zlib, Up: licenses-third-party A.44 ZLIB.NET License ===================== The following software may be included in this product: ZLIB.NET Copyright (c) 2006-2007, ComponentAce http://www.componentace.com All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of ComponentAce nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: manual.info, Node: faqs, Next: error-handling, Prev: licenses-third-party, Up: Top Appendix B MySQL 5.1 Frequently Asked Questions *********************************************** * Menu: * faqs-general:: MySQL 5.1 FAQ: General * faqs-storage-engines:: MySQL 5.1 FAQ: Storage Engines * faqs-sql-modes:: MySQL 5.1 FAQ: Server SQL Mode * faqs-stored-procs:: MySQL 5.1 FAQ: Stored Procedures and Functions * faqs-triggers:: MySQL 5.1 FAQ: Triggers * faqs-views:: MySQL 5.1 FAQ: Views * faqs-information-schema:: MySQL 5.1 FAQ: `INFORMATION_SCHEMA' * faqs-migration:: MySQL 5.1 FAQ: Migration * faqs-security:: MySQL 5.1 FAQ: Security * faqs-mysql-cluster:: MySQL 5.1 FAQ: MySQL Cluster * faqs-cjk:: MySQL 5.1 FAQ: MySQL Chinese, Japanese, and Korean Character Sets * faqs-connectors-apis:: MySQL 5.1 FAQ: Connectors & APIs * faqs-replication:: MySQL 5.1 FAQ: Replication  File: manual.info, Node: faqs-general, Next: faqs-storage-engines, Prev: faqs, Up: faqs B.1 MySQL 5.1 FAQ: General ========================== *Questions* * B.1.1: Which version of MySQL is production-ready (GA)? * B.1.2: What is the state of development (non-GA) versions? * B.1.3: Can MySQL 5.1 do subqueries? * B.1.4: Can MySQL 5.1 perform multiple-table inserts, updates, and deletes? * B.1.5: Does MySQL 5.1 have a Query Cache? Does it work on Server, Instance or Database? * B.1.6: Does MySQL 5.1 have Sequences? * B.1.7: Does MySQL 5.1 have a `NOW()' function with fractions of seconds? * B.1.8: Does MySQL 5.1 work with multi-core processors? * B.1.9: Why do I see multiple processes for `mysqld'? * B.1.10: Have there been there any improvements in error reporting when foreign keys fail? Does MySQL now report which column and reference failed? * B.1.11: Can MySQL 5.1 perform ACID transactions? *Questions and Answers* *B.1.1: ** Which version of MySQL is production-ready (GA)? * MySQL 5.6, MySQL 5.5, MySQL 5.1, and MySQL 5.0 are supported for production use. 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. MySQL 5.1 achieved General Availability (GA) status with MySQL 5.1.30, which was released for production use on 14 November 2008. MySQL 5.0 achieved General Availability (GA) status with MySQL 5.0.15, which was released for production use on 19 October 2005. Note that active development for MySQL 5.0 has ended. *B.1.2: ** 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 5.4 was a development series. Work on this series has ceased. MySQL 5.7 is being actively developed using the milestone release methodology described above. MySQL 6.0 was a development series. Work on this series has ceased. *B.1.3: ** Can MySQL 5.1 do subqueries? * Yes. See *Note subqueries::. *B.1.4: ** Can MySQL 5.1 perform multiple-table inserts, updates, and deletes? * Yes. For the syntax required to perform multiple-table updates, see *Note update::; for that required to perform multiple-table deletes, see *Note delete::. A multiple-table insert can be accomplished using a trigger whose `FOR EACH ROW' clause contains multiple *Note `INSERT': insert. statements within a `BEGIN ... END' block. See *Note triggers::. *B.1.5: ** Does MySQL 5.1 have a Query Cache? Does it work on Server, Instance or Database? * Yes. 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 *Note query-cache::. *B.1.6: ** Does MySQL 5.1 have Sequences? * No. However, MySQL has an `AUTO_INCREMENT' system, which in MySQL 5.1 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. *B.1.7: ** Does MySQL 5.1 have a `NOW()' function with fractions of seconds? * No. This is on the MySQL roadmap as a `rolling feature'. This means that it is not a flagship feature, but will be implemented, development time permitting. Specific customer demand may change this scheduling. However, MySQL does parse time strings with a fractional component. See *Note time::. *B.1.8: ** Does MySQL 5.1 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. *B.1.9: ** Why do I see multiple processes for `mysqld'? * When using LinuxThreads, you should see a minimum of three *Note `mysqld': 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. *B.1.10: ** Have there been there any improvements in error reporting when foreign keys fail? Does MySQL now report which column and reference failed? * The foreign key support in `InnoDB' has seen improvements in each major version of MySQL. Foreign key support generic to all storage engines is scheduled for MySQL 6.x; this should resolve any inadequacies in the current storage engine specific implementation. *B.1.11: ** Can MySQL 5.1 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 *Note `NDB': mysql-cluster. storage engine supports the `READ COMMITTED' transaction isolation level only.  File: manual.info, Node: faqs-storage-engines, Next: faqs-sql-modes, Prev: faqs-general, Up: faqs B.2 MySQL 5.1 FAQ: Storage Engines ================================== *Questions* * B.2.1: Where can I obtain complete documentation for MySQL storage engines and the pluggable storage engine architecture? * B.2.2: Are there any new storage engines in MySQL 5.1? * B.2.3: Have any storage engines been removed in MySQL 5.1? * B.2.4: What are the unique benefits of the `ARCHIVE' storage engine? * B.2.5: Do the new features in MySQL 5.1 apply to all storage engines? *Questions and Answers* *B.2.1: ** Where can I obtain complete documentation for MySQL storage engines and the pluggable storage engine architecture? * See *Note storage-engines::. That chapter contains information about all MySQL storage engines except for the *Note `NDB': mysql-cluster. storage engine used for MySQL Cluster; *Note `NDB': mysql-cluster. is covered in *Note mysql-cluster::. *B.2.2: ** Are there any new storage engines in MySQL 5.1? * Yes: * The `InnoDB Plugin' is available as an alternative to the built-in version of the `InnoDB' storage engine. It includes a number of features such as the Barracuda file format, table compression, and new configuration options for performance. See InnoDB Plugin 1.0 for MySQL 5.1 User's Guide (http://dev.mysql.com/doc/innodb-plugin/1.0/en/index.html) for details. As you upgrade to MySQL 5.5 and higher, these features become core features of the MySQL server, and `InnoDB' becomes the default storage engine for new tables. * There have been significant improvements in existing storage engines, in particular for the *Note `NDB': mysql-cluster. storage engine that forms the basis for MySQL Cluster. * The *Note `IBMDB2I': se-db2. storage engine is included in the IBM i5/OS (TAR packages) and IBM i5/OS (SAVF packages). *B.2.3: ** Have any storage engines been removed in MySQL 5.1? * Yes. MySQL 5.1 no longer supports the `BDB' storage engine. Any existing `BDB' tables should be converted to another storage engine before upgrading to MySQL 5.1. *B.2.4: ** What are the unique benefits of the `ARCHIVE' storage engine? * The `ARCHIVE' storage engine is ideally suited for storing large amounts of data without indexes; it has a very small footprint, and performs selects using table scans. See *Note archive-storage-engine::, for details. *B.2.5: ** Do the new features in MySQL 5.1 apply to all storage engines? * The general new features such as views, stored procedures, triggers, `INFORMATION_SCHEMA', precision math (*Note `DECIMAL': fixed-point-types. column type), and the *Note `BIT': bit-type. column type, apply to all storage engines. There are also additions and changes for specific storage engines.  File: manual.info, Node: faqs-sql-modes, Next: faqs-stored-procs, Prev: faqs-storage-engines, Up: faqs B.3 MySQL 5.1 FAQ: Server SQL Mode ================================== *Questions* * B.3.1: What are server SQL modes? * B.3.2: How many server SQL modes are there? * B.3.3: How do you determine the server SQL mode? * B.3.4: Is the mode dependent on the database or connection? * B.3.5: Can the rules for strict mode be extended? * B.3.6: Does strict mode impact performance? * B.3.7: What is the default server SQL mode when My SQL 5.1 is installed? *Questions and Answers* *B.3.1: ** 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 *Note server-sql-mode::. *B.3.2: ** How many server SQL modes are there? * Each mode can be independently switched on and off. See *Note server-sql-mode::, for a complete list of available modes. *B.3.3: ** How do you determine the server SQL mode? * You can set the default SQL mode (for *Note `mysqld': mysqld. startup) with the `--sql-mode' option. Using the statement *Note `SET [GLOBAL|SESSION] sql_mode='MODES'': set-statement, 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. *B.3.4: ** 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 *Note `SET [GLOBAL|SESSION] sql_mode='MODES'': set-statement. *B.3.5: ** 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 *Note server-sql-mode::, for more information. *B.3.6: ** 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. *B.3.7: ** What is the default server SQL mode when My SQL 5.1 is installed? * By default, no special modes are enabled. See *Note server-sql-mode::, for information about all available modes and MySQL's default behavior.  File: manual.info, Node: faqs-stored-procs, Next: faqs-triggers, Prev: faqs-sql-modes, Up: faqs B.4 MySQL 5.1 FAQ: Stored Procedures and Functions ================================================== *Questions* * B.4.1: Does MySQL 5.1 support stored procedures and functions? * B.4.2: Where can I find documentation for MySQL stored procedures and stored functions? * B.4.3: Is there a discussion forum for MySQL stored procedures? * B.4.4: Where can I find the ANSI SQL 2003 specification for stored procedures? * B.4.5: How do you manage stored routines? * B.4.6: Is there a way to view all stored procedures and stored functions in a given database? * B.4.7: Where are stored procedures stored? * B.4.8: Is it possible to group stored procedures or stored functions into packages? * B.4.9: Can a stored procedure call another stored procedure? * B.4.10: Can a stored procedure call a trigger? * B.4.11: Can a stored procedure access tables? * B.4.12: Do stored procedures have a statement for raising application errors? * B.4.13: Do stored procedures provide exception handling? * B.4.14: Can MySQL 5.1 stored routines return result sets? * B.4.15: Is `WITH RECOMPILE' supported for stored procedures? * B.4.16: Is there a MySQL equivalent to using `mod_plsql' as a gateway on Apache to talk directly to a stored procedure in the database? * B.4.17: Can I pass an array as input to a stored procedure? * B.4.18: Can I pass a cursor as an `IN' parameter to a stored procedure? * B.4.19: Can I return a cursor as an `OUT' parameter from a stored procedure? * B.4.20: Can I print out a variable's value within a stored routine for debugging purposes? * B.4.21: Can I commit or roll back transactions inside a stored procedure? * B.4.22: Do MySQL 5.1 stored procedures and functions work with replication? * B.4.23: Are stored procedures and functions created on a master server replicated to a slave? * B.4.24: How are actions that take place inside stored procedures and functions replicated? * B.4.25: Are there special security requirements for using stored procedures and functions together with replication? * B.4.26: What limitations exist for replicating stored procedure and function actions? * B.4.27: Do the preceding limitations affect MySQL's ability to do point-in-time recovery? * B.4.28: What is being done to correct the aforementioned limitations? *Questions and Answers* *B.4.1: ** Does MySQL 5.1 support stored procedures and functions? * Yes. MySQL 5.1 supports two types of stored routines--stored procedures and stored functions. *B.4.2: ** Where can I find documentation for MySQL stored procedures and stored functions? * See *Note stored-routines::. *B.4.3: ** 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). *B.4.4: ** 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--which give a comprehensive overview of the standard, including coverage of stored procedures. *B.4.5: ** 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 *Note `ROUTINES': routines-table. table in the `INFORMATION_SCHEMA' database (see *Note routines-table::). *B.4.6: ** 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 *Note `INFORMATION_SCHEMA.ROUTINES': routines-table. table: SELECT ROUTINE_TYPE, ROUTINE_NAME FROM INFORMATION_SCHEMA.ROUTINES WHERE ROUTINE_SCHEMA='DBNAME'; For more information, see *Note routines-table::. The body of a stored routine can be viewed using *Note `SHOW CREATE FUNCTION': show-create-function. (for a stored function) or *Note `SHOW CREATE PROCEDURE': show-create-procedure. (for a stored procedure). See *Note show-create-procedure::, for more information. *B.4.7: ** 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, use *Note `SHOW CREATE FUNCTION': show-create-function. to obtain information about stored functions, and *Note `SHOW CREATE PROCEDURE': show-create-procedure. to obtain information about stored procedures. See *Note show-create-procedure::, for more information about these statements. You can also query the *Note `ROUTINES': routines-table. table in the `INFORMATION_SCHEMA' database--see *Note routines-table::, for information about this table. *B.4.8: ** Is it possible to group stored procedures or stored functions into packages? * No. This is not supported in MySQL 5.1. *B.4.9: ** Can a stored procedure call another stored procedure? * Yes. *B.4.10: ** Can a stored procedure call a trigger? * A stored procedure can execute an SQL statement, such as an *Note `UPDATE': update, that causes a trigger to activate. *B.4.11: ** Can a stored procedure access tables? * Yes. A stored procedure can access one or more tables as required. *B.4.12: ** Do stored procedures have a statement for raising application errors? * Not in MySQL 5.1. The SQL standard `SIGNAL' and `RESIGNAL' statements are implemented in MySQL 5.5. *B.4.13: ** Do stored procedures provide exception handling? * MySQL implements *Note `HANDLER': handler. definitions according to the SQL standard. See *Note declare-handler::, for details. *B.4.14: ** Can MySQL 5.1 stored routines return result sets? * _Stored procedures_ can, but stored functions cannot. If you perform an ordinary *Note `SELECT': select. inside a stored procedure, the result set is returned directly to the client. You need to use the MySQL 4.1 (or above) client/server protocol for this to work. This means that--for instance--in PHP, you need to use the `mysqli' extension rather than the old `mysql' extension. *B.4.15: ** Is `WITH RECOMPILE' supported for stored procedures? * Not in MySQL 5.1. *B.4.16: ** 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.1. *B.4.17: ** Can I pass an array as input to a stored procedure? * Not in MySQL 5.1. *B.4.18: ** Can I pass a cursor as an `IN' parameter to a stored procedure? * In MySQL 5.1, cursors are available inside stored procedures only. *B.4.19: ** Can I return a cursor as an `OUT' parameter from a stored procedure? * In MySQL 5.1, cursors are available inside stored procedures only. However, if you do not open a cursor on a *Note `SELECT': select, the result will be sent directly to the client. You can also `SELECT INTO' variables. See *Note select::. *B.4.20: ** 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 *Note `SELECT': 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 instance--in PHP, you need to use the `mysqli' extension rather than the old `mysql' extension. *B.4.21: ** Can I commit or roll back transactions inside a stored procedure? * Yes. However, you cannot perform transactional operations within a stored function. *B.4.22: ** Do MySQL 5.1 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 *Note stored-programs-logging::. *B.4.23: ** 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. *B.4.24: ** 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. *B.4.25: ** 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. *B.4.26: ** 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. Note that 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. *B.4.27: ** Do the preceding limitations affect MySQL's ability to do point-in-time recovery? * The same limitations that affect replication do affect point-in-time recovery. *B.4.28: ** What is being done to correct the aforementioned limitations? * As of MySQL 5.1.5, 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. Beginning with MySQL 5.1.8, _mixed_ replication is also available (by starting the server with `--binlog-format=mixed'). This hybrid, `smart' form of replication `knows' whether statement-level replication can safely be used, or row-level replication is required. For additional information, see *Note replication-formats::.  File: manual.info, Node: faqs-triggers, Next: faqs-views, Prev: faqs-stored-procs, Up: faqs B.5 MySQL 5.1 FAQ: Triggers =========================== *Questions* * B.5.1: Where can I find the documentation for MySQL 5.1 triggers? * B.5.2: Is there a discussion forum for MySQL Triggers? * B.5.3: Does MySQL 5.1 have statement-level or row-level triggers? * B.5.4: Are there any default triggers? * B.5.5: How are triggers managed in MySQL? * B.5.6: Is there a way to view all triggers in a given database? * B.5.7: Where are triggers stored? * B.5.8: Can a trigger call a stored procedure? * B.5.9: Can triggers access tables? * B.5.10: Can a table have multiple triggers with the same trigger event and action time? * B.5.11: Can triggers call an external application through a UDF? * B.5.12: Is it possible for a trigger to update tables on a remote server? * B.5.13: Do triggers work with replication? * B.5.14: How are actions carried out through triggers on a master replicated to a slave? *Questions and Answers* *B.5.1: ** Where can I find the documentation for MySQL 5.1 triggers? * See *Note triggers::. *B.5.2: ** Is there a discussion forum for MySQL Triggers? * Yes. It is available at `http://forums.mysql.com/list.php?99'. *B.5.3: ** Does MySQL 5.1 have statement-level or row-level triggers? * In MySQL 5.1, all triggers are `FOR EACH ROW'--that is, the trigger is activated for each row that is inserted, updated, or deleted. MySQL 5.1 does not support triggers using `FOR EACH STATEMENT'. *B.5.4: ** Are there any default triggers? * Not explicitly. MySQL does have specific special behavior for some *Note `TIMESTAMP': datetime. columns, as well as for columns which are defined using `AUTO_INCREMENT'. *B.5.5: ** How are triggers managed in MySQL? * In MySQL 5.1, triggers can be created using the *Note `CREATE TRIGGER': create-trigger. statement, and dropped using *Note `DROP TRIGGER': drop-trigger. See *Note create-trigger::, and *Note drop-trigger::, for more about these statements. Information about triggers can be obtained by querying the *Note `INFORMATION_SCHEMA.TRIGGERS': triggers-table. table. See *Note triggers-table::. *B.5.6: ** 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 *Note `INFORMATION_SCHEMA.TRIGGERS': triggers-table. 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 *Note triggers-table::. You can also use the *Note `SHOW TRIGGERS': show-triggers. statement, which is specific to MySQL. See *Note show-triggers::. *B.5.7: ** Where are triggers stored? * Triggers for a table are currently stored in `.TRG' files, with one such file one per table. *B.5.8: ** Can a trigger call a stored procedure? * Yes. *B.5.9: ** 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. *B.5.10: ** Can a table have multiple triggers with the same trigger event and action time? * In MySQL 5.1, 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. This limitation is lifted in MySQL 5.7. *B.5.11: ** Can triggers call an external application through a UDF? * Yes. For example, a trigger could invoke the `sys_exec()' UDF. *B.5.12: ** 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 *Note federated-storage-engine::). *B.5.13: ** Do triggers work with replication? * Yes. However, the way in which they work depends whether you are using MySQL's `classic' statement-based replication available in all versions of MySQL, or the row-based replication format introduced in MySQL 5.1. 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 *Note replication-features-triggers::. *B.5.14: ** 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 *Note `INSERT': insert. statement is made to `EMP'. 2. The `AFTER' trigger on `EMP' activates. 3. The *Note `INSERT': insert. statement is written to the binary log. 4. The replication slave picks up the *Note `INSERT': 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 *Note replication-features-triggers::.  File: manual.info, Node: faqs-views, Next: faqs-information-schema, Prev: faqs-triggers, Up: faqs B.6 MySQL 5.1 FAQ: Views ======================== *Questions* * B.6.1: Where can I find documentation covering MySQL Views? * B.6.2: Is there a discussion forum for MySQL Views? * B.6.3: What happens to a view if an underlying table is dropped or renamed? * B.6.4: Does MySQL 5.1 have table snapshots? * B.6.5: Does MySQL 5.1 have materialized views? * B.6.6: Can you insert into views that are based on joins? *Questions and Answers* *B.6.1: ** Where can I find documentation covering MySQL Views? * See *Note views::. *B.6.2: ** Is there a discussion forum for MySQL Views? * Yes. See http://forums.mysql.com/list.php?100 (http://forums.mysql.com/list.php?100) *B.6.3: ** 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 *Note `CHECK TABLE': check-table. statement. (See *Note check-table::.) *B.6.4: ** Does MySQL 5.1 have table snapshots? * No. *B.6.5: ** Does MySQL 5.1 have materialized views? * No. *B.6.6: ** Can you insert into views that are based on joins? * It is possible, provided that your *Note `INSERT': 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.  File: manual.info, Node: faqs-information-schema, Next: faqs-migration, Prev: faqs-views, Up: faqs B.7 MySQL 5.1 FAQ: `INFORMATION_SCHEMA' ======================================= *Questions* * B.7.1: Where can I find documentation for the MySQL `INFORMATION_SCHEMA' database? * B.7.2: Is there a discussion forum for `INFORMATION_SCHEMA'? * B.7.3: Where can I find the ANSI SQL 2003 specification for `INFORMATION_SCHEMA'? * B.7.4: What is the difference between the Oracle Data Dictionary and MySQL's `INFORMATION_SCHEMA'? * B.7.5: Can I add to or otherwise modify the tables found in the `INFORMATION_SCHEMA' database? *Questions and Answers* *B.7.1: ** Where can I find documentation for the MySQL `INFORMATION_SCHEMA' database? * See *Note information-schema:: *B.7.2: ** Is there a discussion forum for `INFORMATION_SCHEMA'? * See http://forums.mysql.com/list.php?101 (http://forums.mysql.com/list.php?101). *B.7.3: ** 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--which give a comprehensive overview of the standard, including `INFORMATION_SCHEMA'. *B.7.4: ** What is the difference between the Oracle Data Dictionary and MySQL's `INFORMATION_SCHEMA'? * Both Oracle and MySQL provide metadata in tables. However, Oracle and MySQL use different table names and column names. MySQL's implementation is more similar to those found in DB2 and SQL Server, which also support `INFORMATION_SCHEMA' as defined in the SQL standard. *B.7.5: ** 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_.  File: manual.info, Node: faqs-migration, Next: faqs-security, Prev: faqs-information-schema, Up: faqs B.8 MySQL 5.1 FAQ: Migration ============================ *Questions* * B.8.1: Where can I find information on how to migrate from MySQL 5.0 to MySQL 5.1? * B.8.2: How has storage engine (table type) support changed in MySQL 5.1 from previous versions? *Questions and Answers* *B.8.1: ** Where can I find information on how to migrate from MySQL 5.0 to MySQL 5.1? * For detailed upgrade information, see *Note 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. *B.8.2: ** How has storage engine (table type) support changed in MySQL 5.1 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 *Note `VARCHAR': char. column type now retains trailing spaces in all storage engines. * `MEMORY' tables (formerly known as `HEAP' tables) can also contain *Note `VARCHAR': char. columns.  File: manual.info, Node: faqs-security, Next: faqs-mysql-cluster, Prev: faqs-migration, Up: faqs B.9 MySQL 5.1 FAQ: Security =========================== *Questions* * B.9.1: Where can I find documentation that addresses security issues for MySQL? * B.9.2: Does MySQL 5.1 have native support for SSL? * B.9.3: Is SSL support be built into MySQL binaries, or must I recompile the binary myself to enable it? * B.9.4: Does MySQL 5.1 have built-in authentication against LDAP directories? * B.9.5: Does MySQL 5.1 include support for Roles Based Access Control (RBAC)? *Questions and Answers* *B.9.1: ** Where can I find documentation that addresses security issues for MySQL? * The best place to start is *Note security::. Other portions of the MySQL Documentation which you may find useful with regard to specific security concerns include the following: * *Note security-guidelines::. * *Note security-against-attack::. * *Note resetting-permissions::. * *Note changing-mysql-user::. * *Note udf-security::. * *Note security-options::. * *Note load-data-local::. * *Note postinstallation::. * *Note ssl-basics::. *B.9.2: ** Does MySQL 5.1 have native support for SSL? * Most 5.1 binaries have support for SSL connections between the client and server. See *Note ssl-connections::. You can also tunnel a connection using SSH, if (for example) the client application does not support SSL connections. For an example, see *Note windows-and-ssh::. *B.9.3: ** Is SSL support be built into MySQL binaries, or must I recompile the binary myself to enable it? * Most 5.1 binaries have SSL enabled for client-server connections that are secured, authenticated, or both. See *Note ssl-connections::. *B.9.4: ** Does MySQL 5.1 have built-in authentication against LDAP directories? * Not at this time. *B.9.5: ** Does MySQL 5.1 include support for Roles Based Access Control (RBAC)? * Not at this time.  File: manual.info, Node: faqs-mysql-cluster, Next: faqs-cjk, Prev: faqs-security, Up: faqs B.10 MySQL 5.1 FAQ: MySQL Cluster ================================= In the following section, we answer questions that are frequently asked about MySQL Cluster and the *Note `NDBCLUSTER': mysql-cluster. storage engine. *Questions* * B.10.1: Which versions of the MySQL software support Cluster? Do I have to compile from source? * B.10.2: What happened to MySQL Cluster NDB 6.4? * B.10.3: What do `NDB' and `NDBCLUSTER' mean? * B.10.4: What is the difference between using MySQL Cluster _vs_ using MySQL Replication? * B.10.5: Do I need any special networking to run MySQL Cluster? How do computers in a cluster communicate? * B.10.6: How many computers do I need to run a MySQL Cluster, and why? * B.10.7: What do the different computers do in a MySQL Cluster? * B.10.8: When I run the `SHOW' command in the MySQL Cluster management client, I see a line of output that looks like this: id=2 @10.100.10.32 (Version: 5.6.13-ndb-7.3.3 Nodegroup: 0, Master) What is a `master node', and what does it do? How do I configure a node so that it is the master? * B.10.9: With which operating systems can I use MySQL Cluster? * B.10.10: What are the hardware requirements for running MySQL Cluster? * B.10.11: How much RAM do I need to use MySQL Cluster? Is it possible to use disk memory at all? * B.10.12: What file systems can I use with MySQL Cluster? What about network file systems or network shares? * B.10.13: Can I run MySQL Cluster nodes inside virtual machines (such as those created by VMWare, Parallels, or Xen)? * B.10.14: I am trying to populate a MySQL 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? * B.10.15: MySQL Cluster uses TCP/IP. Does this mean that I can run it over the Internet, with one or more nodes in remote locations? * B.10.16: Do I have to learn a new programming or query language to use MySQL Cluster? * B.10.17: What programming languages and APIs are supported by MySQL Cluster? * B.10.18: Does MySQL Cluster include any management tools? * B.10.19: How do I find out what an error or warning message means when using MySQL Cluster? * B.10.20: Is MySQL Cluster transaction-safe? What isolation levels are supported? * B.10.21: What storage engines are supported by MySQL Cluster? * B.10.22: In the event of a catastrophic failure--say, for instance, the whole city loses power _and_ my UPS fails--would I lose all my data? * B.10.23: Is it possible to use `FULLTEXT' indexes with MySQL Cluster? * B.10.24: Can I run multiple nodes on a single computer? * B.10.25: Can I add data nodes to a MySQL Cluster without restarting it? * B.10.26: Are there any limitations that I should be aware of when using MySQL Cluster? * B.10.27: Does MySQL Cluster support foreign keys? * B.10.28: How do I import an existing MySQL database into a MySQL Cluster? * B.10.29: How do MySQL Cluster nodes communicate with one another? * B.10.30: What is an _arbitrator_? * B.10.31: What data types are supported by MySQL Cluster? * B.10.32: How do I start and stop MySQL Cluster? * B.10.33: What happens to MySQL Cluster data when the MySQL Cluster is shut down? * B.10.34: Is it a good idea to have more than one management node for a MySQL Cluster? * B.10.35: Can I mix different kinds of hardware and operating systems in one MySQL Cluster? * B.10.36: Can I run two data nodes on a single host? Two SQL nodes? * B.10.37: Can I use host names with MySQL Cluster? * B.10.38: Does MySQL Cluster support IPv6? * B.10.39: How do I handle MySQL users in a MySQL Cluster having multiple MySQL servers? * B.10.40: How do I continue to send queries in the event that one of the SQL nodes fails? * B.10.41: How do I back up and restore a MySQL Cluster? * B.10.42: What is an `angel process'? *Questions and Answers* *B.10.1: ** Which versions of the MySQL software support Cluster? Do I have to compile from source? * MySQL Cluster is not supported in standard MySQL Server 5.1 releases. Instead, MySQL Cluster is provided as a separate product. Currently, the following MySQL Cluster release series are available for production use: * MySQL Cluster NDB 6.3 This series is still maintained and available for use but is not recommended for new deployments. The most recent MySQL Cluster NDB 6.3 release can be obtained from `http://dev.mysql.com/downloads/cluster/'. * MySQL Cluster NDB 7.0 This series is still available for use in production, although MySQL Cluster NDB 7.2 is recommended for new deployments. The most recent MySQL Cluster NDB 7.0 release can be obtained from `http://dev.mysql.com/downloads/cluster/'. * MySQL Cluster NDB 7.1 This series is a previous General Availability (GA) version of MySQL Cluster, still available for production, although we recommend that new deployments use MySQL Cluster NDB 7.3. The most recent MySQL Cluster NDB 7.1 release can be obtained from `http://dev.mysql.com/downloads/cluster/'. * MySQL Cluster NDB 7.2 This series is a General Availability (GA) version of MySQL Cluster, still available for production, although we recommend that new deployments use the latest MySQL Cluster NDB 7.3 release. The most recent MySQL Cluster NDB 7.2 release can be obtained from `http://dev.mysql.com/downloads/cluster/'. * MySQL Cluster NDB 7.3 This series is the latest Generally Available (GA) version of MySQL Cluster, based on version 7.3 of the *Note `NDB': mysql-cluster. storage engine and MySQL Server 5.6. New deployments should use the latest release in this series. The most recent MySQL Cluster NDB 7.3 release can be obtained from `http://dev.mysql.com/downloads/cluster/'. You should use MySQL Cluster NDB 7.2 or MySQL Cluster NDB 7.3 for any new deployments; if you are using an older version of MySQL Cluster, you should upgrade to one of these soon as possible. For an overview of improvements made in MySQL Cluster NDB 7.2, see MySQL Cluster Development in MySQL Cluster NDB 7.2 (http://dev.mysql.com/doc/refman/5.5/en/mysql-cluster-development-5-5-ndb-7-2.html); for information about improvements made in MySQL Cluster NDB 7.3, see MySQL Cluster Development in MySQL Cluster NDB 7.3 (http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-development-5-6-ndb-7-3.html). You can determine whether your MySQL Server has *Note `NDB': mysql-cluster. support using one of the statements `SHOW VARIABLES LIKE 'have_%'', *Note `SHOW ENGINES': show-engines, or *Note `SHOW PLUGINS': show-plugins. *B.10.2: ** What happened to MySQL Cluster NDB 6.4? * Because of the number and impact of new features introduced into MySQL Cluster following the General Availability of MySQL Cluster NDB 6.3, it was decided that the following release series represented a `major' new release series rather than a `minor' one, and should be known as MySQL Cluster 7.0. The earliest development versions of MySQL Cluster NDB 7.0 were originally designated `MySQL Cluster 6.4', and the first four releases in this series were identified as MySQL Cluster NDB 6.4.0 through NDB 6.4.3. MySQL Cluster NDB 7.0.4 was the fifth MySQL Cluster NDB 7.0 release; it was the successor to MySQL Cluster NDB 6.4.3. For more information about MySQL Cluster NDB 7.0, see *Note mysql-cluster-development-5-1-ndb-7-0::, and and `http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/mysql-cluster-news-7-0.html'. *B.10.3: ** What do `NDB' and `NDBCLUSTER' mean? * `NDB' stands for `*N*etwork *D*ata*b*ase'. *Note `NDB': mysql-cluster. and *Note `NDBCLUSTER': mysql-cluster. are both names for the storage engine that enables clustering support in MySQL. While our developers prefer *Note `NDB': mysql-cluster, either name is correct; both names appear in our documentation, and either name can be used in the `ENGINE' option of a *Note `CREATE TABLE': create-table. statement for creating a MySQL Cluster table. *B.10.4: ** What is the difference between using MySQL Cluster _vs_ 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 *Note `InnoDB': innodb-storage-engine. 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 MySQL 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_, MySQL Cluster is _synchronous_. Asynchronous replication for MySQL Cluster is available in MySQL 5.1 and later. _MySQL Cluster Replication_ (also sometimes known as `geo-replication') includes the capability to replicate both between two MySQL Clusters, and from a MySQL Cluster to a non-Cluster MySQL server. See *Note mysql-cluster-replication::. *B.10.5: ** Do I need any special networking to run MySQL Cluster? How do computers in a cluster communicate? * MySQL 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 MySQL Cluster include a typical 100-megabit Ethernet network or the equivalent. We recommend you use gigabit Ethernet whenever available. The faster SCI protocol is also supported, but requires special hardware. See *Note mysql-cluster-interconnects::, for more information about SCI. *B.10.6: ** How many computers do I need to run a MySQL Cluster, and why? * A minimum of three computers is required to run a viable cluster. However, the minimum _recommended_ number of computers in a MySQL 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. *B.10.7: ** What do the different computers do in a MySQL Cluster? * A MySQL 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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd.; the management client used to control MySQL Cluster is *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. See *Note mysql-cluster-programs-ndb-mgmd::, and *Note 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 *Note `NDB': mysql-cluster. data node process *Note `ndbd': mysql-cluster-programs-ndbd. For more information, see *Note mysql-cluster-programs-ndbd::. * SQL node This is simply an instance of MySQL Server (*Note `mysqld': mysqld.) that is built with support for the *Note `NDBCLUSTER': mysql-cluster. storage engine and started with the `--ndb-cluster' option to enable the engine and the `--ndb-connectstring' option to enable it to connect to a MySQL Cluster management server. For more about these options, see *Note 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 MySQL Cluster data; see MySQL Cluster API Overview: The NDB API (http://dev.mysql.com/doc/ndbapi/en/overview-ndb-api.html), for more information. *B.10.8: ** When I run the `SHOW' command in the MySQL Cluster management client, I see a line of output that looks like this: * id=2 @10.100.10.32 (Version: 5.6.13-ndb-7.3.3 Nodegroup: 0, Master) * What is a `master node', and what does it do? How do I configure a node so that it is the master? * 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 MySQL Cluster source code'. If you don't find that answer satisfactory, here's a longer and more technical version: A number of mechanisms in MySQL 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 be a `master'. There is no user-facing mechanism for influencing this selection, which is is completely automatic; the fact that it _is_ automatic is a key part of MySQL Cluster's internal architecture. When a node acts as a master for any of these mechanisms, it is usually the point of coordination for the activity, and the other nodes act as `servants', carrying out their parts of the activity as directed by the master. If the node acting as master fails, then the remaining nodes elect a new master. Tasks in progress that were being coordinated by the old master may either fail or be continued by the new master, depending on the actual mechanism involved. It is possible for some of these different mechanisms and protocols to have different master nodes, but in general the same master is chosen for all of them. The node indicated as the master in the output of `SHOW' in the management client is actually the `DICT' master (see The `DBDICT' Block (http://dev.mysql.com/doc/ndbapi/en/ndb-internals-kernel-blocks-dbdict.html), in the `MySQL Cluster API Developer Guide', for more information), responsible for coordinating DDL and metadata activity. MySQL Cluster is designed in such a way that the choice of master has no discernable effect outside the cluster itself. For example, the current master does not have significantly higher CPU or resource usage than the other data nodes, and failure of the master should not have a significantly different impact on the cluster than the failure of any other data node. *B.10.9: ** With which operating systems can I use MySQL Cluster? * MySQL Cluster is supported on most Unix-like operating systems. Beginning with MySQL Cluster NDB 7.1.3, MySQL Cluster is also supported in production on Microsoft Windows operating systems. For more detailed information concerning the level of support which is offered for MySQL Cluster on various operating system versions, operating system distributions, and hardware platforms, please refer to http://www.mysql.com/support/supportedplatforms/cluster.html. *B.10.10: ** What are the hardware requirements for running MySQL Cluster? * MySQL Cluster should run on any platform for which *Note `NDB': mysql-cluster.-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 MySQL 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 *Note mysql-cluster-interconnects::). *B.10.11: ** How much RAM do I need to use MySQL Cluster? Is it possible to use disk memory at all? * Formerly MySQL Cluster was in-memory only. MySQL 5.1 and later also provide the ability to store MySQL Cluster on disk. (Note that we have no plans to backport this capability to previous releases.) See *Note 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 *Note 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 *Note `NDBCLUSTER': mysql-cluster. 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. Note that creating MySQL 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 *Note `ndb_size.pl': mysql-cluster-programs-ndb-size-pl. utility which is available in recent MySQL 5.1 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 *Note `NDBCLUSTER': mysql-cluster. storage engine. For more information, see *Note mysql-cluster-programs-ndb-size-pl::. It is especially important to keep in mind that _every MySQL Cluster table must have a primary key_. The *Note `NDB': mysql-cluster. 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 MySQL Cluster data and indexes at any given time using the `REPORT MEMORYUSAGE' command in the *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. client; see *Note 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. *B.10.12: ** What file systems can I use with MySQL 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 MySQL Cluster. If you find that a given file system works particularly well (or not so especially well) with MySQL Cluster, we invite you to discuss your findings in the MySQL Cluster Forums (http://forums.mysql.com/list.php?25). For Windows, we recommend that you use `NTFS' file systems for MySQL Cluster, just as we do for standard MySQL. We do not test MySQL Cluster with `FAT' or `VFAT' file systems. Because of this, we do not recommend their use with MySQL or MySQL Cluster. MySQL 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 MySQL Cluster. This also applies to shared storage devices such as SANs. *B.10.13: ** Can I run MySQL Cluster nodes inside virtual machines (such as those created by VMWare, Parallels, or Xen)? * This is possible but not recommended for a production environment with MySQL Cluster versions prior to MySQL Cluster NDB 7.2. For deployment in virtualized environments, you should use MySQL Cluster NDB 7.2 or later. *B.10.14: ** I am trying to populate a MySQL 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 *Note `NDB': mysql-cluster. 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 MySQL Cluster data and indexes. In some cases it is possible to get `Table is full' errors in MySQL client applications even when *Note `ndb_mgm -e "ALL REPORT MEMORYUSAGE"': mysql-cluster-programs-ndb-mgm. shows significant free `DataMemory'. You can force *Note `NDB': mysql-cluster. to create extra partitions for MySQL Cluster tables and thus have more memory available for hash indexes by using the `MAX_ROWS' option for *Note `CREATE TABLE': 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. In MySQL Cluster NDB 7.1 and later, the addition of the `MinFreePct' parameter helps 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 *Note `NDB': mysql-cluster. tables or data. *B.10.15: ** MySQL 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 MySQL 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 a MySQL 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 *Note mysql-cluster-security::. *B.10.16: ** Do I have to learn a new programming or query language to use MySQL 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 a MySQL Cluster--see *Note mysql-cluster-config-file::, for information about these. A few simple commands are used in the MySQL Cluster management client (*Note `ndb_mgm': mysql-cluster-programs-ndb-mgm.) for tasks such as starting and stopping cluster nodes. See *Note mysql-cluster-mgm-client-commands::. *B.10.17: ** What programming languages and APIs are supported by MySQL Cluster? * MySQL Cluster 5.1 and later support 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. MySQL Cluster applications written using these APIs behave similarly to other MySQL applications; they transmit SQL statements to a MySQL Server (in the case of MySQL Cluster, an SQL node), and receive responses containing rows of data. For more information about these APIs, see *Note connectors-apis::. MySQL Cluster 5.1 and later also support application programming using the NDB API, which provides a low-level C++ interface to MySQL 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 *Note `NDBCLUSTER': mysql-cluster. 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. MySQL Cluster NDB 7.1 and later also support Java application programming using ClusterJ, which supports a domain object model of data using sessions and transactions. See Java and MySQL Cluster (http://dev.mysql.com/doc/ndbapi/en/mccj-overview-java.html), for more information. *B.10.18: ** Does MySQL Cluster include any management tools? * MySQL Cluster includes a command line client for performing basic management functions. See *Note mysql-cluster-programs-ndb-mgm::, and *Note mysql-cluster-mgm-client-commands::. MySQL Cluster NDB 7.0 and later is also supported by MySQL Cluster Manager, a separate product providing an advanced command line interface that can automate many MySQL Cluster management tasks such as rolling restarts and configuration changes. For more information about MySQL Cluster Manager, see MySQL(tm) Cluster Manager 1.2.4 User Manual (http://dev.mysql.com/doc/cluster-manager/en/index.html). *B.10.19: ** How do I find out what an error or warning message means when using MySQL Cluster? * There are two ways in which this can be done: * From within the *Note `mysql': mysql. client, use `SHOW ERRORS' or `SHOW WARNINGS' immediately upon being notified of the error or warning condition. * From a system shell prompt, use *Note `perror --ndb ERROR_CODE': perror. *B.10.20: ** Is MySQL Cluster transaction-safe? What isolation levels are supported? * _Yes_. For tables created with the *Note `NDB': mysql-cluster. storage engine, transactions are supported. Currently, MySQL Cluster supports only the `READ COMMITTED' transaction isolation level. *B.10.21: ** What storage engines are supported by MySQL Cluster? * Clustering with MySQL is supported only by the *Note `NDB': mysql-cluster. storage engine. That is, in order for a table to be shared between nodes in a MySQL 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 *Note `InnoDB': innodb-storage-engine. or *Note `MyISAM': myisam-storage-engine.) on a MySQL server being used with a MySQL Cluster, but since these tables do not use *Note `NDB': mysql-cluster, they do not participate in clustering; each such table is strictly local to the individual MySQL server instance on which it is created. *B.10.22: ** In the event of a catastrophic failure--say, for instance, 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.) *B.10.23: ** Is it possible to use `FULLTEXT' indexes with MySQL Cluster? * `FULLTEXT' indexing is currently not supported by any MySQL storage engine other than *Note `MyISAM': myisam-storage-engine. *B.10.24: ** 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 MySQL 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 *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. and *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm. processes. It is acceptable to run multiple cluster data nodes on a single host that has multiple CPUs, cores, or both. MySQL Cluster NDB 7.0 and later also provide a multi-threaded version of the data node binary intended for use on such systems. For more information, see *Note 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. *B.10.25: ** Can I add data nodes to a MySQL Cluster without restarting it? * In MySQL Cluster NDB 7.0 and later, it is possible to add new data nodes to a running MySQL Cluster without taking it offline. For more information, see *Note mysql-cluster-online-add-node::. For other types of MySQL Cluster nodes, a rolling restart is all that is required (see *Note mysql-cluster-rolling-restart::). (In MySQL Cluster NDB 6.3 and earlier releases, it was not possible to add new data nodes without shutting down and restarting the MySQL Cluster.) *B.10.26: ** Are there any limitations that I should be aware of when using MySQL Cluster? * Limitations on *Note `NDB': mysql-cluster. tables in MySQL NDB 6.3, MySQL Cluster NDB 7.0, and MySQL Cluster NDB 7.1 include the following: * Temporary tables are not supported; a *Note `CREATE TEMPORARY TABLE': create-table. statement using `ENGINE=NDB' or `ENGINE=NDBCLUSTER' fails with an error. * The only types of user-defined partitioning supported for *Note `NDBCLUSTER': mysql-cluster. 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 *Note spatial-extensions::. * Prior to MySQL Cluster NDB 6.3.19, the *Note `NDBCLUSTER': mysql-cluster. storage engine did not support partial transactions or partial rollbacks of transactions. Beginning with MySQL Cluster NDB 6.3.19, this limitation has been removed, and the behavior of *Note `NDBCLUSTER': mysql-cluster. is now in line with that of other transactional storage engines (such as *Note `InnoDB': innodb-storage-engine.) that can roll back individual statements. * Prior to MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, the maximum number of attributes allowed per table was 128; beginning with MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, this limit is increased to 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. * Previous to MySL Cluster NDB 7.0, the maximum size for a table row was 8 kilobytes, not counting *Note `BLOB': blob. values. MySQL Cluster NDB 7.0 and later support a maximum row length of 14 KB (also not including `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. * The *Note `NDBCLUSTER': mysql-cluster. engine does not support foreign key constraints. As with *Note `MyISAM': myisam-storage-engine. tables, if these are specified in a *Note `CREATE TABLE': create-table. or *Note `ALTER TABLE': alter-table. statement, they are ignored. For a complete listing of limitations in MySQL Cluster, see *Note mysql-cluster-limitations::. See also *Note mysql-cluster-limitations-resolved::. *B.10.27: ** Does MySQL Cluster support foreign keys? * MySQL Cluster NDB 7.1 and earlier MySQL Cluster releases do not support foreign key contraints, and ignore foreign keys in *Note `CREATE TABLE': create-table. statements (similarly to how *Note `MyISAM': myisam-storage-engine. treats foreign key syntax). Foreign key support comparable to that found in the *Note `InnoDB': innodb-storage-engine. storage engine is provided by *Note `NDB': mysql-cluster. beginning with MySQL Cluster NDB 7.3. Applications requiring foreign support key should use MySQL Cluster NDB 7.3 or later. *B.10.28: ** How do I import an existing MySQL database into a MySQL Cluster? * You can import databases into MySQL 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 *Note `NDB': mysql-cluster. 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 *Note `NDBCLUSTER': mysql-cluster. using one or more *Note `ALTER TABLE': alter-table. statement. However, the definition of the table must be compatible with the *Note `NDBCLUSTER': mysql-cluster. storage engine prior to making the conversion. In MySQL 5.1, an additional workaround is also required; see *Note mysql-cluster-limitations::, for details. *B.10.29: ** How do MySQL 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 *Note mysql-cluster-interconnects::, for more about using SCI as a transport mechanism for MySQL Cluster. *B.10.30: ** 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. In MySQL Cluster NDB 7.0.7 and later, you can also use the `ArbitrationRank' configuration parameter to control the arbitrator selection process. For more information about these parameters, see *Note 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. *B.10.31: ** What data types are supported by MySQL Cluster? * MySQL Cluster supports all of the usual MySQL data types, including those associated with MySQL's spatial extensions; however, the *Note `NDB': mysql-cluster. storage engine does not support spatial indexes. (Spatial indexes are supported only by *Note `MyISAM': myisam-storage-engine.; see *Note spatial-extensions::, for more information.) In addition, there are some differences with regard to indexes when used with *Note `NDB': mysql-cluster. tables. *Note*: MySQL 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 *Note `VARCHAR(255)': char. 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 *Note mysql-cluster-limitations::, for more information about these issues. *B.10.32: ** How do I start and stop MySQL Cluster? * It is necessary to start each node in the cluster separately, in the following order: 1. Start the management node, using the *Note `ndb_mgmd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-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 *Note `mysqld_safe': mysqld-safe. Each MySQL Server must be started with the `--ndbcluster' and `--ndb-connectstring' options. These options cause mysqld to enable *Note `NDBCLUSTER': mysql-cluster. 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 *Note `NDB': mysql-cluster. management client *Note `ndb_mgm': mysql-cluster-programs-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 *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm, *Note `ndb_mgm': mysql-cluster-programs-ndb-mgm, and any *Note `ndbd': mysql-cluster-programs-ndbd. processes to terminate gracefully. MySQL servers running as SQL nodes can be stopped using *Note `mysqladmin shutdown': mysqladmin. For more information, see *Note mysql-cluster-mgm-client-commands::, and *Note mysql-cluster-install-shutdown-restart::. *B.10.33: ** What happens to MySQL Cluster data when the MySQL 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. *B.10.34: ** Is it a good idea to have more than one management node for a MySQL 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 *Note mysql-cluster-config-file::, for information on how to configure MySQL Cluster management nodes. *B.10.35: ** Can I mix different kinds of hardware and operating systems in one MySQL Cluster? * Yes, as long as all machines and operating systems have the same `endianness' (all big-endian or all little-endian). We are working to overcome this limitation in a future MySQL Cluster release. It is also possible to use software from different MySQL Cluster releases on different nodes. However, we support this only as part of a rolling upgrade procedure (see *Note mysql-cluster-rolling-restart::). *B.10.36: ** 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 *Note `mysqld': mysqld. must use a different TCP/IP port. However, in MySQL 5.1, running more than one cluster node of a given type per machine is generally not encouraged or supported for production use. We also advise against running data nodes and SQL nodes together on the same host, since the *Note `ndbd': mysql-cluster-programs-ndbd. and *Note `mysqld': mysqld. processes may compete for memory. *B.10.37: ** Can I use host names with MySQL 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. *B.10.38: ** Does MySQL Cluster support IPv6? * MySQL Cluster NDB 7.0 and later support IPv6 for connections between SQL nodes (MySQL servers). However, connections between all other types of nodes must use IPv4. In practical terms, this means that you can use IPv6 for replication between MySQL Clusters, but connections between nodes in the same MySQL Cluster must use IPv4. For more information, see *Note mysql-cluster-replication-issues::. *B.10.39: ** How do I handle MySQL users in a MySQL Cluster having multiple MySQL servers? * MySQL user accounts and privileges are _not_ automatically propagated between different MySQL servers accessing the same MySQL Cluster. Therefore, you must make sure that these are copied between the SQL nodes yourself. You can do this manually, or automate the task with scripts. *Warning*: Do not attempt to work around this issue by converting the MySQL system tables to use the *Note `NDBCLUSTER': mysql-cluster. storage engine. Only the *Note `MyISAM': myisam-storage-engine. storage engine is supported for these tables. *B.10.40: ** How do I continue to send queries in the event that one of the SQL nodes fails? * MySQL Cluster does not provide any sort of automatic failover between SQL nodes. Your application must be prepared to handlethe loss of SQL nodes and to fail over between them. *B.10.41: ** How do I back up and restore a MySQL Cluster? * You can use the NDB native backup and restore functionality in the MySQL Cluster management client and the *Note `ndb_restore': mysql-cluster-programs-ndb-restore. program. See *Note mysql-cluster-backup::, and *Note mysql-cluster-programs-ndb-restore::. You can also use the traditional functionality provided for this purpose in *Note `mysqldump': mysqldump. and the MySQL server. See *Note mysqldump::, for more information. *B.10.42: ** 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 *Note `ndbd': mysql-cluster-programs-ndbd, you can see that there are actually 2 processes running by that name, as shown here (we omit the output from *Note `ndb_mgmd': mysql-cluster-programs-ndb-mgmd. and *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-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 *Note `ndbd': mysql-cluster-programs-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 *Note mysql-cluster-params-ndbd::), the angel process tries to restart the primary data node process.  File: manual.info, Node: faqs-cjk, Next: faqs-connectors-apis, Prev: faqs-mysql-cluster, Up: faqs B.11 MySQL 5.1 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. *Questions* * B.11.1: What CJK character sets are available in MySQL? * B.11.2: I have inserted CJK characters into my table. Why does *Note `SELECT': select. display them as `?' characters? * B.11.3: What problems should I be aware of when working with the Big5 Chinese character set? * B.11.4: Why do Japanese character set conversions fail? * B.11.5: What should I do if I want to convert SJIS `81CA' to `cp932'? * B.11.6: How does MySQL represent the Yen (`¥') sign? * B.11.7: Does MySQL plan to make a separate character set where `5C' is the Yen sign, as at least one other major DBMS does? * B.11.8: Of what issues should I be aware when working with Korean character sets in MySQL? * B.11.9: Why do I get `Incorrect string value' error messages? * B.11.10: Why does my GUI front end or browser not display CJK characters correctly in my application using Access, PHP, or another API? * B.11.11: I've upgraded to MySQL 5.1. How can I revert to behavior like that in MySQL 4.0 with regard to character sets? * B.11.12: Why do some `LIKE' and `FULLTEXT' searches with CJK characters fail? * B.11.13: How do I know whether character X is available in all character sets? * B.11.14: Why do CJK strings sort incorrectly in Unicode? (I) * B.11.15: Why do CJK strings sort incorrectly in Unicode? (II) * B.11.16: Why are my supplementary characters rejected by MySQL? * B.11.17: Shouldn't it be `CJKV'? * B.11.18: Does MySQL allow CJK characters to be used in database and table names? * B.11.19: Where can I find translations of the MySQL Manual into Chinese, Japanese, and Korean? * B.11.20: Where can I get help with CJK and related issues in MySQL? *Questions and Answers* *B.11.1: ** What CJK character sets are available in MySQL? * The list of CJK character sets may vary depending on your MySQL version. For example, the `eucjpms' character set was not supported prior to MySQL 5.0.3. However, since the name of the applicable language appears in the `DESCRIPTION' column for every entry in the *Note `INFORMATION_SCHEMA.CHARACTER_SETS': character-sets-table. 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 '%Chinese%' -> 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 | | gb2312 | GB2312 Simplified Chinese | | gbk | GBK Simplified Chinese | | sjis | Shift-JIS Japanese | | ujis | EUC-JP Japanese | +--------------------+---------------------------+ 8 rows in set (0.01 sec) (See *Note character-sets-table::, for more information.) MySQL supports the two common 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' and `gbk'. 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 doesn't work. (See Bug #16072 for an example). 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. * For a complete listing of the `gb2312' characters, ordered according to the `gb2312_chinese_ci' collation: gb2312 (http://www.collation-charts.org/mysql60/by-charset.html#gb2312) * MySQL's `gbk' 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'. * For MySQL's listing of `gbk' characters, see gbk (http://www.collation-charts.org/mysql60/by-charset.html#gbk). *B.11.2: ** I have inserted CJK characters into my table. Why does *Note `SELECT': select. display them as `?' characters? * This problem is usually due to a setting in MySQL that doesn't 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 possible--that is, when you select LITERAL (or _INTRODUCER HEXADECIMAL-VALUE), 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 `ペ', then the round trip has 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 *Note `mysql': mysql. client program (on Windows: *Note `mysql.exe': mysql.) to accomplish this task. If *Note `mysql': mysql. displays correctly but your application doesn't, then your problem is probably due to system settings. To find out what your settings are, use the *Note `SHOW VARIABLES': 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/ | +--------------------------+----------------------------------------+ 8 rows in set (0.03 sec) 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 and a default for MySQL). 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 your underlying computer is, then try changing to a common character set for the country that you're in (`euckr' = Korea; `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. There is a simple statement which changes all three at once: `SET NAMES'. 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. *B.11.3: ** 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). MySQL's `big5' is in reality Microsoft code page 950, which is very similar to the original `big5' character set. We changed to this character set starting with MySQL version 4.1.16 / 5.0.16 (as a result of Bug #12476). For example, the following statements work in current versions of MySQL, but not in old versions: mysql> CREATE TABLE big5 (BIG5 CHAR(1) CHARACTER SET BIG5); Query OK, 0 rows affected (0.13 sec) mysql> INSERT INTO big5 VALUES (0xf9dc); Query OK, 1 row affected (0.00 sec) mysql> SELECT * FROM big5; +------+ | big5 | +------+ | 嫺 | +------+ 1 row in set (0.02 sec) 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. *B.11.4: ** 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. *B.11.5: ** What should I do if I want to convert SJIS `81CA' to `cp932'? * Our answer is: `?'. There are serious complaints about this: many people would prefer a `loose' conversion, so that `81CA (NOT SIGN)' in `sjis' becomes `81CA (FULLWIDTH NOT SIGN)' in `cp932'. We are considering a change to this behavior. *B.11.6: ** 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), and 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 (`\')_. *B.11.7: ** Does MySQL plan to make a separate character set where `5C' is the Yen sign, as at least one other major DBMS does? * This is one possible solution to the Yen sign issue; however, this will not happen in MySQL 5.1 or 6.0. *B.11.8: ** 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 | +-------+----------+ 1 row in set (0.00 sec) MySQL's graphic Korean chart is here: euckr (http://www.collation-charts.org/mysql60/by-charset.html#euckr). *B.11.9: ** Why do I get `Incorrect string value' error messages? * For illustration, we'll 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); Query OK, 0 rows affected (0.05 sec) We'll try to place the rare character `汌' in both columns. mysql> INSERT INTO ch VALUES ('A汌B','A汌B'); Query OK, 1 row affected, 1 warning (0.00 sec) Ah, there is 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 1 row in set (0.00 sec) 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 | +-------+--------------+--------+-------------+ 1 row in set (0.00 sec) Several things need explanation here: 1. The fact that it is a `warning' rather than an `error' is characteristic of MySQL. We like to try to do what we can, to get the best fit, rather than give up. 2. The `汌' character is not in the `gb2312' character set. We described that problem earlier. 3. If you are using an old version of MySQL, you will probably see a different message. 4. With `sql_mode=TRADITIONAL', there would be an error message, rather than a warning. *B.11.10: ** Why does my GUI front end or browser not display CJK characters correctly in my application using Access, PHP, or another API? * Obtain a direct connection to the server using the *Note `mysql': mysql. client (Windows: *Note `mysql.exe': mysql.), and try the same query there. If *Note `mysql': mysql. responds correctly, then the trouble may be that your application interface requires initialization. Use *Note `mysql': mysql. to tell you what character set or sets it uses with the statement `SHOW VARIABLES LIKE 'char%';'. If you are using Access, then you are most likely connecting with Connector/ODBC. In this case, you should check *Note connector-odbc-configuration::. If, for instance, you use `big5', you would enter `SET NAMES 'big5''. (Note that no `;' is required in this case). 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, then you must specify the character set in the connection string. See *Note connector-net-programming-connecting::, for more information. If you are using PHP, try this: In this case, we used `SET NAMES' to change `character_set_client' and `character_set_connection' and `character_set_results'. We encourage the use of the newer `mysqli' extension, rather than `mysql'. Using `mysqli', the previous example could be rewritten as shown here: query("SET NAMES 'utf8'"); ?> Another issue often encountered in PHP applications has to do with assumptions made by the browser. Sometimes adding or changing a `' tag suffices to correct the problem: for example, to insure that the user agent interprets page content as `UTF-8', you should include `' in the `' of the HTML page. If you are using Connector/J, see *Note connector-j-reference-charsets::. *B.11.11: ** I've upgraded to MySQL 5.1. 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 *Note 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 *Note `mysqld': mysqld. with `--character-set-server=utf8'. However, some of our Asian customers have said that they prefer the MySQL 4.0 behavior. To make it possible to retain this behavior, we added a *Note `mysqld': mysqld. switch, `--character-set-client-handshake', which can be turned off with `--skip-character-set-client-handshake'. If you start *Note `mysqld': 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 current settings can be seen by viewing the output of *Note `SHOW VARIABLES': 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/ | +--------------------------+----------------------------------------+ 8 rows in set (0.01 sec) Now stop the client, and then stop the server using *Note `mysqladmin': 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 current 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/ | +--------------------------+----------------------------------------+ 8 rows in set (0.01 sec) As you can see by comparing the differing results from *Note `SHOW VARIABLES': show-variables, the server ignores the client's initial settings if the `--skip-character-set-client-handshake' is used. *B.11.12: ** Why do some `LIKE' and `FULLTEXT' searches with CJK characters fail? * There is a very simple problem with `LIKE' searches on *Note `BINARY': binary-varbinary. and *Note `BLOB': blob. columns: we need to know the end of a character. With multi-byte 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 | +-------------------------+---------------------------+ 1 row in set (0.00 sec) If we don't know where the first character ends, then we don't know where the second character begins, in which case even very simple searches such as `LIKE '_A%'' fail. The solution is to use a regular CJK character set in the first place, or to convert to a CJK character set before comparing. This is one reason why MySQL cannot allow encodings of nonexistent characters. If it is not strict about rejecting bad input, then it has no way of knowing where characters end. For `FULLTEXT' searches, we need to 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. *B.11.13: ** 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. This stored procedure accepts a `UCS-2' Unicode character, converts it to all 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 is a conversion problem, UPDATE will produce a warning. */ 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// The input can be any single `ucs2' character, or it can be the code point 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 point value is `0x30da'. If we use this value as the argument to `p_convert()', the result is as shown here: mysql> CALL p_convert(0x30da)// +------+--------+------+-------+---------+-------+--------+------+------+------+ | ucs2 | utf8 | big5 | cp932 | eucjpms | euckr | gb2312 | gbk | sjis | ujis | +------+--------+------+-------+---------+-------+--------+------+------+------+ | 30DA | E3839A | C772 | 8379 | A5DA | ABDA | A5DA | A5DA | 8379 | A5DA | +------+--------+------+-------+---------+-------+--------+------+------+------+ 1 row in set (0.04 sec) Since none of the column values is `3F'--that is, the question mark character (`?')--we know that every conversion worked. *B.11.14: ** Why do CJK strings sort incorrectly in Unicode? (I) * 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 read correctly the standard table of weights for the Unicode Collation Algorithm. MySQL uses the table found at `http://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt'. This is not the first table you will find by navigating from the `unicode.org' home page, because MySQL uses the older 4.0.0 `allkeys' table, rather than the more recent 4.1.0 table. (The newer `'520'' collations in MySQL 5.6 use the 5.2 `allkeys' table.) This is because we are very wary about changing ordering which affects indexes, lest we 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 | +------+ | が | | か | +------+ 2 rows in set (0.00 sec) 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 | +------+-----------------------------+ 2 rows in set (0.03 sec) 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' isn't enough, of course: the person who submitted the bug was equally correct. We plan to add 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. *B.11.15: ** Why do CJK strings sort incorrectly in Unicode? (II) * If you are using Unicode (`ucs2' or `utf8'), and you know what the Unicode sort order is (see *Note faqs-cjk::), but MySQL still seems to sort your table incorrectly, then you should first verify the table character set: 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 1 row in set (0.00 sec) Since the character set appears to be correct, let's see what information the *Note `INFORMATION_SCHEMA.COLUMNS': columns-table. 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 | +-------------+--------------------+-----------------+ 1 row in set (0.01 sec) (See *Note 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 CHARSET', as shown here: mysql> SHOW CHARSET LIKE 'ucs2%'; +---------+---------------+-------------------+--------+ | Charset | Description | Default collation | Maxlen | +---------+---------------+-------------------+--------+ | ucs2 | UCS-2 Unicode | ucs2_general_ci | 2 | +---------+---------------+-------------------+--------+ 1 row in set (0.00 sec) For `ucs2' and `utf8', the default collation is `general'. To specify a Unicode collation, use `COLLATE ucs2_unicode_ci'. *B.11.16: ** Why are my supplementary characters rejected by MySQL? * Before MySQL 5.5.3, MySQL does not support supplementary characters--that is, characters which need more than 3 bytes--for `UTF-8'. We support only what Unicode calls the _Basic Multilingual Plane / Plane 0_. Only a few very rare Han characters are supplementary; support for them is uncommon. This has led to reports such as that found in Bug #12600, which we rejected as `not a bug'. With `utf8', we must truncate an input string when we encounter bytes that we don't understand. Otherwise, we wouldn't know how long the bad multi-byte 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 *Note `BLOB': blob. or *Note `BINARY': binary-varbinary, which perform no validity checking. As of MySQL 5.5.3, Unicode support is extended to include supplementary characters by means of additional Unicode character sets: `utf16', `utf32', and 4-byte `utf8mb4'. These character sets support supplementary Unicode characters outside the Basic Multilingual Plane (BMP). *B.11.17: ** Shouldn't it be `CJKV'? * No. The term `CJKV' (_Chinese Japanese Korean Vietnamese_) refers to Vietnamese character sets which contain Han (originally Chinese) characters. MySQL has no plan to support the old Vietnamese script using Han characters. MySQL does of course support the modern Vietnamese script with Western characters. As of MySQL 5.6, there are Vietnamese collations for Unicode character sets, as described in *Note charset-unicode-sets::. *B.11.18: ** Does MySQL allow CJK characters to be used in database and table names? * This issue is fixed in MySQL 5.1, by automatically rewriting the names of the corresponding directories and files. For example, if you create a database named `楮' on a server whose operating system does not support CJK in directory names, MySQL creates a directory named `@0w@00a5@00ae'. which is just a fancy way of encoding `E6A5AE'--that is, the Unicode hexadecimal representation for the `楮' character. However, if you run a *Note `SHOW DATABASES': show-databases. statement, you can see that the database is listed as `楮'. *B.11.19: ** Where can I find translations of the MySQL Manual into Chinese, Japanese, and Korean? * A Simplified Chinese version of the Manual, current for MySQL 5.1.12, can be found at `http://dev.mysql.com/doc/'. The Japanese translation of the MySQL 4.1 manual can be downloaded from `http://dev.mysql.com/doc/'. *B.11.20: ** 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 `http://dev.mysql.com/user-groups/'. * View feature requests relating to character set issues at `http://tinyurl.com/y6xcuf'. * Visit the MySQL Collation Unicode Forum. We are also in the process of adding foreign-language forums at `http://forums.mysql.com/'.  File: manual.info, Node: faqs-connectors-apis, Next: faqs-replication, Prev: faqs-cjk, Up: faqs B.12 MySQL 5.1 FAQ: Connectors & APIs ===================================== For common questions, issues, and answers relating to the MySQL Connectors and other APIs, see the following areas of the Manual: * *Note c-api-problems:: * *Note apis-php-problems:: * *Note connector-odbc-usagenotes:: * *Note connector-net-programming:: * *Note connector-j::  File: manual.info, Node: faqs-replication, Prev: faqs-connectors-apis, Up: faqs B.13 MySQL 5.1 FAQ: Replication =============================== In the following section, we provide answers to questions that are most frequently asked about MySQL Replication. *Questions* * B.13.1: Must the slave be connected to the master all the time? * B.13.2: Must I enable networking on my master and slave to enable replication? * B.13.3: 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? * B.13.4: How do I force the master to block updates until the slave catches up? * B.13.5: What issues should I be aware of when setting up two-way replication? * B.13.6: How can I use replication to improve performance of my system? * B.13.7: What should I do to prepare client code in my own applications to use performance-enhancing replication? * B.13.8: When and how much can MySQL replication improve the performance of my system? * B.13.9: How can I use replication to provide redundancy or high availability? * B.13.10: How do I tell whether a master server is using statement-based or row-based binary logging format? * B.13.11: How do I tell a slave to use row-based replication? * B.13.12: How do I prevent *Note `GRANT': grant. and *Note `REVOKE': revoke. statements from replicating to slave machines? * B.13.13: Does replication work on mixed operating systems (for example, the master runs on Linux while slaves run on Mac OS X and Windows)? * B.13.14: Does replication work on mixed hardware architectures (for example, the master runs on a 64-bit machine while slaves run on 32-bit machines)? *Questions and Answers* *B.13.1: ** 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. *B.13.2: ** 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. *B.13.3: ** 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 *Note `SHOW SLAVE STATUS': show-slave-status. See *Note 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 *Note `TIMESTAMP': datetime. is well replicated.) In the `Time' column in the output of *Note `SHOW PROCESSLIST': 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 *Note `SHOW PROCESSLIST': show-processlist. This is because the slave is executing statements that are one hour old. See *Note replication-implementation-details::. *B.13.4: ** 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 *Note `SHOW': 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 *Note `SELECT': 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; *B.13.5: ** 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. *B.13.6: ** 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. *B.13.7: ** 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, *Note replication-solutions-scaleout::. *B.13.8: ** 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. Note that 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? *B.13.9: ** 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 *Note replication-solutions-switch::. *B.13.10: ** 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, row-based logging is preferred but replication switches automatically to statement-based logging under certain conditions; for information about when this may occur, see *Note binary-log-mixed::. *B.13.11: ** How do I tell a slave to use row-based replication? * Slaves automatically know which format to use. *B.13.12: ** How do I prevent *Note `GRANT': grant. and *Note `REVOKE': 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. *B.13.13: ** Does replication work on mixed operating systems (for example, the master runs on Linux while slaves run on Mac OS X and Windows)? * Yes. *B.13.14: ** 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.  File: manual.info, Node: error-handling, Next: news, Prev: faqs, Up: Top Appendix C Errors, Error Codes, and Common Problems *************************************************** * Menu: * error-sources:: Sources of Error Information * error-types:: Types of Error Values * error-messages-server:: Server Error Codes and Messages * error-messages-client:: Client Error Codes and Messages * problems:: Problems and Common Errors 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.  File: manual.info, Node: error-sources, Next: error-types, Prev: error-handling, Up: error-handling C.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 *Note error-types::. These errors are returned from the server side; see *Note error-messages-server::. * Errors can occur on the client side, usually involving problems communicating with the server; see *Note error-messages-client::. * SQL statement warning and error information is available through the *Note `SHOW WARNINGS': show-warnings. and *Note `SHOW ERRORS': 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. * *Note `SHOW SLAVE STATUS': show-slave-status. statement output includes information about replication errors occurring on the slave side. * *Note `SHOW ENGINE INNODB STATUS': show-engine. statement output includes information about the most recent foreign key error if a *Note `CREATE TABLE': create-table. statement for an *Note `InnoDB': innodb-storage-engine. table fails. * The *Note `perror': perror. program provides information from the command line about error numbers. See *Note perror::. Descriptions of server and client errors are provided later in this Appendix. For information about errors related to *Note `InnoDB': innodb-storage-engine, see *Note innodb-error-handling::.  File: manual.info, Node: error-types, Next: error-messages-server, Prev: error-sources, Up: error-handling C.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 *Note `mysql_errno()': mysql-errno. * SQLSTATE value: Call *Note `mysql_sqlstate()': mysql-sqlstate. * Error message: Call *Note `mysql_error()': mysql-error. For prepared statements, the corresponding error functions are *Note `mysql_stmt_errno()': mysql-stmt-errno, *Note `mysql_stmt_sqlstate()': mysql-stmt-sqlstate, and *Note `mysql_stmt_error()': mysql-stmt-error. All error functions are described in *Note c-api::. The number of errors, warnings, and notes for the previous statement can be obtained by calling *Note `mysql_warning_count()': mysql-warning-count. See *Note 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.  File: manual.info, Node: error-messages-server, Next: error-messages-client, Prev: error-types, Up: error-handling C.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 *Note `mysql': 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.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.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.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 * Error: `1001' SQLSTATE: `HY000' (`ER_NISAMCHK') Message: isamchk * Error: `1002' SQLSTATE: `HY000' (`ER_NO') Message: NO * Error: `1003' SQLSTATE: `HY000' (`ER_YES') Message: YES * Error: `1004' SQLSTATE: `HY000' (`ER_CANT_CREATE_FILE') Message: Can't create file '%s' (errno: %d) * Error: `1005' SQLSTATE: `HY000' (`ER_CANT_CREATE_TABLE') Message: Can't create table '%s' (errno: %d) * 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 * 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) * Error: `1012' SQLSTATE: `HY000' (`ER_CANT_FIND_SYSTEM_REC') Message: Can't read record in system table * Error: `1013' SQLSTATE: `HY000' (`ER_CANT_GET_STAT') Message: Can't get status of '%s' (errno: %d) * Error: `1014' SQLSTATE: `HY000' (`ER_CANT_GET_WD') Message: Can't get working directory (errno: %d) * Error: `1015' SQLSTATE: `HY000' (`ER_CANT_LOCK') Message: Can't lock file (errno: %d) * Error: `1016' SQLSTATE: `HY000' (`ER_CANT_OPEN_FILE') Message: Can't open file: '%s' (errno: %d) * Error: `1017' SQLSTATE: `HY000' (`ER_FILE_NOT_FOUND') Message: Can't find file: '%s' (errno: %d) * Error: `1018' SQLSTATE: `HY000' (`ER_CANT_READ_DIR') Message: Can't read dir of '%s' (errno: %d) * Error: `1019' SQLSTATE: `HY000' (`ER_CANT_SET_WD') Message: Can't change dir to '%s' (errno: %d) * 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... * 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) * Error: `1024' SQLSTATE: `HY000' (`ER_ERROR_ON_READ') Message: Error reading file '%s' (errno: %d) * Error: `1025' SQLSTATE: `HY000' (`ER_ERROR_ON_RENAME') Message: Error on rename of '%s' to '%s' (errno: %d) * Error: `1026' SQLSTATE: `HY000' (`ER_ERROR_ON_WRITE') Message: Error writing file '%s' (errno: %d) * 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 * 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; increase server sort buffer size * Error: `1039' SQLSTATE: `HY000' (`ER_UNEXPECTED_EOF') Message: Unexpected EOF found when reading file '%s' (errno: %d) * 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 * 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 From 5.1.20: 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 * 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 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 * 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. 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 -O 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_DELAYED_CANT_CHANGE_LOCK') Message: Delayed insert thread couldn't get requested lock for table %s * Error: `1151' SQLSTATE: `HY000' (`ER_TOO_MANY_DELAYED_THREADS') 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_DELAYED_INSERT_TABLE_LOCKED') 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 %ld 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 * Error: `1206' SQLSTATE: `HY000' (`ER_LOCK_TABLE_FULL') Message: The total number of locks exceeds the lock table size * 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 * 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 * Error: `1217' SQLSTATE: `23000' (`ER_ROW_IS_REFERENCED') Message: Cannot delete or update a parent row: a foreign key constraint fails * 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 the %s privilege 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: %d line(s) were 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 table engine '%s' * Error: `1287' SQLSTATE: `HY000' (`ER_UNUSED_1') Message: '%s' is deprecated; use '%s' instead `ER_UNUSED_1' was introduced in 5.1.9, removed after 5.1.19. * 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. This option will be removed in MySQL 5.6. * 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. This option will be removed in MySQL 5.6. * 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 * 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 * 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 column '%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 -O 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) `ER_SP_PROC_TABLE_CORRUPT' was introduced in 5.1.4. * Error: `1458' SQLSTATE: `42000' (`ER_SP_WRONG_NAME') Message: Incorrect routine name '%s' `ER_SP_WRONG_NAME' was introduced in 5.1.7. * Error: `1459' SQLSTATE: `HY000' (`ER_TABLE_NEEDS_UPGRADE') Message: Table upgrade required. Please do "REPAIR TABLE `%s`" or dump/reload to fix it! `ER_TABLE_NEEDS_UPGRADE' was introduced in 5.1.7. * Error: `1460' SQLSTATE: `42000' (`ER_SP_NO_AGGREGATE') Message: AGGREGATE is not supported for stored functions `ER_SP_NO_AGGREGATE' was introduced in 5.1.9. * Error: `1461' SQLSTATE: `42000' (`ER_MAX_PREPARED_STMT_COUNT_REACHED') Message: Can't create more than max_prepared_stmt_count statements (current value: %lu) `ER_MAX_PREPARED_STMT_COUNT_REACHED' was introduced in 5.1.11. * Error: `1462' SQLSTATE: `HY000' (`ER_VIEW_RECURSIVE') Message: `%s`.`%s` contains view recursion `ER_VIEW_RECURSIVE' was introduced in 5.1.11. * Error: `1463' SQLSTATE: `42000' (`ER_NON_GROUPING_FIELD_USED') Message: non-grouping field '%s' is used in %s clause `ER_NON_GROUPING_FIELD_USED' was introduced in 5.1.11. * Error: `1464' SQLSTATE: `HY000' (`ER_TABLE_CANT_HANDLE_SPKEYS') Message: The used table type doesn't support SPATIAL indexes `ER_TABLE_CANT_HANDLE_SPKEYS' was introduced in 5.1.11. * Error: `1465' SQLSTATE: `HY000' (`ER_NO_TRIGGERS_ON_SYSTEM_SCHEMA') Message: Triggers can not be created on system tables `ER_NO_TRIGGERS_ON_SYSTEM_SCHEMA' was introduced in 5.1.12. * Error: `1466' SQLSTATE: `HY000' (`ER_REMOVED_SPACES') Message: Leading spaces are removed from name '%s' `ER_REMOVED_SPACES' was introduced in 5.1.12. * Error: `1467' SQLSTATE: `HY000' (`ER_AUTOINC_READ_FAILED') Message: Failed to read auto-increment value from storage engine `ER_AUTOINC_READ_FAILED' was introduced in 5.1.12. * Error: `1468' SQLSTATE: `HY000' (`ER_USERNAME') Message: user name `ER_USERNAME' was introduced in 5.1.12. * Error: `1469' SQLSTATE: `HY000' (`ER_HOSTNAME') Message: host name `ER_HOSTNAME' was introduced in 5.1.12. * Error: `1470' SQLSTATE: `HY000' (`ER_WRONG_STRING_LENGTH') Message: String '%s' is too long for %s (should be no longer than %d) `ER_WRONG_STRING_LENGTH' was introduced in 5.1.12. * Error: `1471' SQLSTATE: `HY000' (`ER_NON_INSERTABLE_TABLE') Message: The target table %s of the %s is not insertable-into `ER_NON_INSERTABLE_TABLE' was introduced in 5.1.12. * Error: `1472' SQLSTATE: `HY000' (`ER_ADMIN_WRONG_MRG_TABLE') Message: Table '%s' is differently defined or of non-MyISAM type or doesn't exist `ER_ADMIN_WRONG_MRG_TABLE' was introduced in 5.1.20. * Error: `1473' SQLSTATE: `HY000' (`ER_TOO_HIGH_LEVEL_OF_NESTING_FOR_SELECT') Message: Too high level of nesting for select `ER_TOO_HIGH_LEVEL_OF_NESTING_FOR_SELECT' was introduced in 5.1.23. * Error: `1474' SQLSTATE: `HY000' (`ER_NAME_BECOMES_EMPTY') Message: Name '%s' has become " `ER_NAME_BECOMES_EMPTY' was introduced in 5.1.23. * 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 `ER_AMBIGUOUS_FIELD_TERM' was introduced in 5.1.23. * Error: `1476' SQLSTATE: `HY000' (`ER_FOREIGN_SERVER_EXISTS') Message: The foreign server, %s, you are trying to create already exists. `ER_FOREIGN_SERVER_EXISTS' was introduced in 5.1.15. * 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 `ER_FOREIGN_SERVER_DOESNT_EXIST' was introduced in 5.1.15. * Error: `1478' SQLSTATE: `HY000' (`ER_ILLEGAL_HA_CREATE_OPTION') Message: Table storage engine '%s' does not support the create option '%s' `ER_ILLEGAL_HA_CREATE_OPTION' was introduced in 5.1.7. * 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_CHAR_SET_IN_PART_FIELD_ERROR') Message: VARCHAR only allowed if binary collation for partition functions `ER_CHAR_SET_IN_PART_FIELD_ERROR' was removed after 5.1.5. * 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 `ER_PARTITION_SUBPART_MIX_ERROR' was introduced in 5.1.9. * 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_CONST_EXPR_IN_PARTITION_FUNC_ERROR') Message: Constant/Random expression in (sub)partitioning function is not allowed `ER_CONST_EXPR_IN_PARTITION_FUNC_ERROR' was removed after 5.1.42. In 5.1.43: `ER_CONST_EXPR_IN_PARTITION_FUNC_ERROR' was renamed to `ER_WRONG_EXPR_IN_PARTITION_FUNC_ERROR'. * 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 `ER_WRONG_EXPR_IN_PARTITION_FUNC_ERROR' was introduced in 5.1.43. In 5.1.43: `ER_CONST_EXPR_IN_PARTITION_FUNC_ERROR' was renamed to `ER_WRONG_EXPR_IN_PARTITION_FUNC_ERROR'. * 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_DROP_PARTITION_FAILURE') Message: Drop partition not supported in this version for this handler `ER_DROP_PARTITION_FAILURE' was removed after 5.1.5. * Error: `1496' SQLSTATE: `HY000' (`ER_PARTITION_ENTRY_ERROR') Message: Partitioning can not be used stand-alone in query * Error: `1497' SQLSTATE: `HY000' (`ER_DROP_PARTITION_WHEN_FK_DEFINED') Message: Cannot drop a partition when a foreign key constraint is defined on the table `ER_DROP_PARTITION_WHEN_FK_DEFINED' was removed after 5.1.5. * 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_TABLESPACE_OPTION_ONLY_ONCE') Message: It is not allowed to specify %s more than once `ER_TABLESPACE_OPTION_ONLY_ONCE' was introduced in 5.1.6, removed after 5.1.6. * 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_CREATE_TABLESPACE_FAILED') Message: Failed to create %s `ER_CREATE_TABLESPACE_FAILED' was introduced in 5.1.6, removed after 5.1.6. * Error: `1506' SQLSTATE: `HY000' (`ER_FOREIGN_KEY_ON_PARTITIONED') Message: Foreign key clause is not yet supported in conjunction with partitioning `ER_FOREIGN_KEY_ON_PARTITIONED' was introduced in 5.1.6. * Error: `1507' SQLSTATE: `HY000' (`ER_DROP_TABLESPACE_FAILED') Message: Failed to drop %s `ER_DROP_TABLESPACE_FAILED' was introduced in 5.1.6, removed after 5.1.6. * 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 `ER_REORG_HASH_ONLY_ON_SAME_NO' was introduced in 5.1.6. * Error: `1511' SQLSTATE: `HY000' (`ER_ALTER_TABLESPACE_FAILED') Message: Failed to alter: %s `ER_ALTER_TABLESPACE_FAILED' was introduced in 5.1.6, removed after 5.1.6. * 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 `ER_REORG_NO_PARAM_ERROR' was introduced in 5.1.6. * 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 `ER_NO_BINLOG_ERROR' was introduced in 5.1.6. * 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 `ER_PARTITION_FUNCTION_FAILURE' was introduced in 5.1.6. * Error: `1522' SQLSTATE: `HY000' (`ER_PART_STATE_ERROR') Message: Partition state cannot be defined from CREATE/ALTER TABLE `ER_PART_STATE_ERROR' was introduced in 5.1.6. * Error: `1523' SQLSTATE: `HY000' (`ER_LIMITED_PART_RANGE') Message: The %s handler only supports 32 bit integers in VALUES `ER_LIMITED_PART_RANGE' was introduced in 5.1.6. * Error: `1524' SQLSTATE: `HY000' (`ER_PLUGIN_IS_NOT_LOADED') Message: Plugin '%s' is not loaded * Error: `1525' SQLSTATE: `HY000' (`ER_EVENT_COL_COUNT_DOESNT_MATCH') Message: Column count of %s.%s is wrong. Table probably corrupted `ER_EVENT_COL_COUNT_DOESNT_MATCH' was introduced in 5.1.6, removed after 5.1.6. * Error: `1525' SQLSTATE: `HY000' (`ER_WRONG_VALUE') Message: Incorrect %s value: '%s' `ER_WRONG_VALUE' was introduced in 5.1.4. * Error: `1526' SQLSTATE: `HY000' (`ER_EVENT_CANNOT_LOAD_FROM_TABLE') Message: Cannot load from mysql.%s. Table probably corrupted. See error log. `ER_EVENT_CANNOT_LOAD_FROM_TABLE' was introduced in 5.1.6, removed after 5.1.7. * Error: `1526' SQLSTATE: `HY000' (`ER_NO_PARTITION_FOR_GIVEN_VALUE') Message: Table has no partition for value %s `ER_NO_PARTITION_FOR_GIVEN_VALUE' was introduced in 5.1.4. * Error: `1527' SQLSTATE: `HY000' (`ER_FILEGROUP_OPTION_ONLY_ONCE') Message: It is not allowed to specify %s more than once `ER_FILEGROUP_OPTION_ONLY_ONCE' was introduced in 5.1.7. * Error: `1528' SQLSTATE: `HY000' (`ER_CREATE_FILEGROUP_FAILED') Message: Failed to create %s `ER_CREATE_FILEGROUP_FAILED' was introduced in 5.1.7. * Error: `1529' SQLSTATE: `HY000' (`ER_DROP_FILEGROUP_FAILED') Message: Failed to drop %s `ER_DROP_FILEGROUP_FAILED' was introduced in 5.1.7. * Error: `1530' SQLSTATE: `HY000' (`ER_TABLESPACE_AUTO_EXTEND_ERROR') Message: The handler doesn't support autoextend of tablespaces `ER_TABLESPACE_AUTO_EXTEND_ERROR' was introduced in 5.1.6. * Error: `1531' SQLSTATE: `HY000' (`ER_WRONG_SIZE_NUMBER') Message: A size parameter was incorrectly specified, either number or on the form 10M `ER_WRONG_SIZE_NUMBER' was introduced in 5.1.6. * 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 `ER_SIZE_OVERFLOW_ERROR' was introduced in 5.1.6. * Error: `1533' SQLSTATE: `HY000' (`ER_ALTER_FILEGROUP_FAILED') Message: Failed to alter: %s `ER_ALTER_FILEGROUP_FAILED' was introduced in 5.1.7. * Error: `1534' SQLSTATE: `HY000' (`ER_BINLOG_ROW_LOGGING_FAILED') Message: Writing one row to the row-based binary log failed `ER_BINLOG_ROW_LOGGING_FAILED' was introduced in 5.1.5. * Error: `1535' SQLSTATE: `HY000' (`ER_BINLOG_ROW_WRONG_TABLE_DEF') Message: Table definition on master and slave does not match: %s `ER_BINLOG_ROW_WRONG_TABLE_DEF' was introduced in 5.1.5. * 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 `ER_BINLOG_ROW_RBR_TO_SBR' was introduced in 5.1.5. * Error: `1537' SQLSTATE: `HY000' (`ER_EVENT_ALREADY_EXISTS') Message: Event '%s' already exists `ER_EVENT_ALREADY_EXISTS' was introduced in 5.1.6. * Error: `1538' SQLSTATE: `HY000' (`ER_EVENT_STORE_FAILED') Message: Failed to store event %s. Error code %d from storage engine. `ER_EVENT_STORE_FAILED' was introduced in 5.1.6. * Error: `1539' SQLSTATE: `HY000' (`ER_EVENT_DOES_NOT_EXIST') Message: Unknown event '%s' `ER_EVENT_DOES_NOT_EXIST' was introduced in 5.1.6. * Error: `1540' SQLSTATE: `HY000' (`ER_WARN_DEPRECATED_STATEMENT') Message: The '%s' statement is deprecated and will be removed in MySQL %s. Please use client programs (e.g. %s) instead. `ER_WARN_DEPRECATED_STATEMENT' was introduced in 5.1.7, removed after 5.1.7. * Error: `1540' SQLSTATE: `HY000' (`ER_EVENT_CANT_ALTER') Message: Failed to alter event '%s' `ER_EVENT_CANT_ALTER' was introduced in 5.1.6. * Error: `1541' SQLSTATE: `HY000' (`ER_WARN_DEPRECATED') Message: The syntax '%s' is deprecated and will be removed in MySQL %s. Please use %s instead. `ER_WARN_DEPRECATED' was introduced in 5.1.9, removed after 5.1.9. * Error: `1541' SQLSTATE: `HY000' (`ER_EVENT_DROP_FAILED') Message: Failed to drop %s `ER_EVENT_DROP_FAILED' was introduced in 5.1.6. * Error: `1542' SQLSTATE: `HY000' (`ER_EVENT_INTERVAL_NOT_POSITIVE_OR_TOO_BIG') Message: INTERVAL is either not positive or too big `ER_EVENT_INTERVAL_NOT_POSITIVE_OR_TOO_BIG' was introduced in 5.1.6. * Error: `1543' SQLSTATE: `HY000' (`ER_EVENT_ENDS_BEFORE_STARTS') Message: ENDS is either invalid or before STARTS `ER_EVENT_ENDS_BEFORE_STARTS' was introduced in 5.1.6. * Error: `1544' SQLSTATE: `HY000' (`ER_EVENT_EXEC_TIME_IN_THE_PAST') Message: Event execution time is in the past. Event has been disabled `ER_EVENT_EXEC_TIME_IN_THE_PAST' was introduced in 5.1.6. * Error: `1545' SQLSTATE: `HY000' (`ER_EVENT_OPEN_TABLE_FAILED') Message: Failed to open mysql.event `ER_EVENT_OPEN_TABLE_FAILED' was introduced in 5.1.6. * Error: `1546' SQLSTATE: `HY000' (`ER_EVENT_NEITHER_M_EXPR_NOR_M_AT') Message: No datetime expression provided `ER_EVENT_NEITHER_M_EXPR_NOR_M_AT' was introduced in 5.1.6. * Error: `1547' SQLSTATE: `HY000' (`ER_COL_COUNT_DOESNT_MATCH_CORRUPTED') Message: Column count of mysql.%s is wrong. Expected %d, found %d. The table is probably corrupted `ER_COL_COUNT_DOESNT_MATCH_CORRUPTED' was introduced in 5.1.7. * Error: `1548' SQLSTATE: `HY000' (`ER_CANNOT_LOAD_FROM_TABLE') Message: Cannot load from mysql.%s. The table is probably corrupted `ER_CANNOT_LOAD_FROM_TABLE' was introduced in 5.1.9. * Error: `1549' SQLSTATE: `HY000' (`ER_EVENT_CANNOT_DELETE') Message: Failed to delete the event from mysql.event `ER_EVENT_CANNOT_DELETE' was introduced in 5.1.6. * Error: `1550' SQLSTATE: `HY000' (`ER_EVENT_COMPILE_ERROR') Message: Error during compilation of event's body `ER_EVENT_COMPILE_ERROR' was introduced in 5.1.6. * Error: `1551' SQLSTATE: `HY000' (`ER_EVENT_SAME_NAME') Message: Same old and new event name `ER_EVENT_SAME_NAME' was introduced in 5.1.6. * Error: `1552' SQLSTATE: `HY000' (`ER_EVENT_DATA_TOO_LONG') Message: Data for column '%s' too long `ER_EVENT_DATA_TOO_LONG' was introduced in 5.1.6. * Error: `1553' SQLSTATE: `HY000' (`ER_CANT_READ_LOCK_LOG_TABLE') Message: You can't use usual read lock with log tables. Try READ LOCAL instead `ER_CANT_READ_LOCK_LOG_TABLE' was introduced in 5.1.6, removed after 5.1.20. * Error: `1553' SQLSTATE: `HY000' (`ER_DROP_INDEX_FK') Message: Cannot drop index '%s': needed in a foreign key constraint `ER_DROP_INDEX_FK' was introduced in 5.1.6. * 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 `ER_WARN_DEPRECATED_SYNTAX_WITH_VER' was introduced in 5.1.20. * Error: `1555' SQLSTATE: `HY000' (`ER_CANT_WRITE_LOCK_LOG_TABLE') Message: You can't write-lock a log table. Only read access is possible `ER_CANT_WRITE_LOCK_LOG_TABLE' was introduced in 5.1.6. * Error: `1556' SQLSTATE: `HY000' (`ER_CANT_LOCK_LOG_TABLE') Message: You can't use locks with log tables. `ER_CANT_LOCK_LOG_TABLE' was introduced in 5.1.21. * Error: `1557' SQLSTATE: `23000' (`ER_FOREIGN_DUPLICATE_KEY') Message: Upholding foreign key constraints for table '%s', entry '%s', key %d would lead to a duplicate entry `ER_FOREIGN_DUPLICATE_KEY' was introduced in 5.1.7. * 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. `ER_COL_COUNT_DOESNT_MATCH_PLEASE_UPDATE' was introduced in 5.1.7. * 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 `ER_TEMP_TABLE_PREVENTS_SWITCH_OUT_OF_RBR' was introduced in 5.1.9. * Error: `1560' SQLSTATE: `HY000' (`ER_STORED_FUNCTION_PREVENTS_SWITCH_BINLOG_FORMAT') Message: Cannot change the binary logging format inside a stored function or trigger `ER_STORED_FUNCTION_PREVENTS_SWITCH_BINLOG_FORMAT' was introduced in 5.1.9. * 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 `ER_NDB_CANT_SWITCH_BINLOG_FORMAT' was introduced in 5.1.9. * Error: `1562' SQLSTATE: `HY000' (`ER_PARTITION_NO_TEMPORARY') Message: Cannot create temporary table with partitions `ER_PARTITION_NO_TEMPORARY' was introduced in 5.1.9. * Error: `1563' SQLSTATE: `HY000' (`ER_PARTITION_CONST_DOMAIN_ERROR') Message: Partition constant is out of partition function domain `ER_PARTITION_CONST_DOMAIN_ERROR' was introduced in 5.1.12. * Error: `1564' SQLSTATE: `HY000' (`ER_PARTITION_FUNCTION_IS_NOT_ALLOWED') Message: This partition function is not allowed `ER_PARTITION_FUNCTION_IS_NOT_ALLOWED' was introduced in 5.1.12. * Error: `1565' SQLSTATE: `HY000' (`ER_DDL_LOG_ERROR') Message: Error in DDL log `ER_DDL_LOG_ERROR' was introduced in 5.1.11. * Error: `1566' SQLSTATE: `HY000' (`ER_NULL_IN_VALUES_LESS_THAN') Message: Not allowed to use NULL value in VALUES LESS THAN `ER_NULL_IN_VALUES_LESS_THAN' was introduced in 5.1.11. * Error: `1567' SQLSTATE: `HY000' (`ER_EVENT_RECURSIVITY_FORBIDDEN') Message: Recursivity of EVENT DDL statements is forbidden when body is present `ER_EVENT_RECURSIVITY_FORBIDDEN' was introduced in 5.1.12, removed after 5.1.17. * Error: `1567' SQLSTATE: `HY000' (`ER_WRONG_PARTITION_NAME') Message: Incorrect partition name `ER_WRONG_PARTITION_NAME' was introduced in 5.1.11. * Error: `1568' SQLSTATE: `25001' (`ER_CANT_CHANGE_TX_ISOLATION') Message: Transaction isolation level can't be changed while a transaction is in progress `ER_CANT_CHANGE_TX_ISOLATION' was introduced in 5.1.7. * Error: `1569' SQLSTATE: `HY000' (`ER_DUP_ENTRY_AUTOINCREMENT_CASE') Message: ALTER TABLE causes auto_increment resequencing, resulting in duplicate entry '%s' for key '%s' `ER_DUP_ENTRY_AUTOINCREMENT_CASE' was introduced in 5.1.12. * Error: `1570' SQLSTATE: `HY000' (`ER_EVENT_MODIFY_QUEUE_ERROR') Message: Internal scheduler error %d `ER_EVENT_MODIFY_QUEUE_ERROR' was introduced in 5.1.11. * Error: `1571' SQLSTATE: `HY000' (`ER_EVENT_SET_VAR_ERROR') Message: Error during starting/stopping of the scheduler. Error code %u `ER_EVENT_SET_VAR_ERROR' was introduced in 5.1.11. * Error: `1572' SQLSTATE: `HY000' (`ER_PARTITION_MERGE_ERROR') Message: Engine cannot be used in partitioned tables `ER_PARTITION_MERGE_ERROR' was introduced in 5.1.12. * Error: `1573' SQLSTATE: `HY000' (`ER_CANT_ACTIVATE_LOG') Message: Cannot activate '%s' log `ER_CANT_ACTIVATE_LOG' was introduced in 5.1.12. * Error: `1574' SQLSTATE: `HY000' (`ER_RBR_NOT_AVAILABLE') Message: The server was not built with row-based replication `ER_RBR_NOT_AVAILABLE' was introduced in 5.1.12. * Error: `1575' SQLSTATE: `HY000' (`ER_BASE64_DECODE_ERROR') Message: Decoding of base64 string failed `ER_BASE64_DECODE_ERROR' was introduced in 5.1.12. * Error: `1576' SQLSTATE: `HY000' (`ER_EVENT_RECURSION_FORBIDDEN') Message: Recursion of EVENT DDL statements is forbidden when body is present `ER_EVENT_RECURSION_FORBIDDEN' was introduced in 5.1.18. * Error: `1577' SQLSTATE: `HY000' (`ER_EVENTS_DB_ERROR') Message: Cannot proceed because system tables used by Event Scheduler were found damaged at server start `ER_EVENTS_DB_ERROR' was introduced in 5.1.12. * Error: `1578' SQLSTATE: `HY000' (`ER_ONLY_INTEGERS_ALLOWED') Message: Only integers allowed as number here `ER_ONLY_INTEGERS_ALLOWED' was introduced in 5.1.12. * Error: `1579' SQLSTATE: `HY000' (`ER_UNSUPORTED_LOG_ENGINE') Message: This storage engine cannot be used for log tables" `ER_UNSUPORTED_LOG_ENGINE' was introduced in 5.1.12. * Error: `1580' SQLSTATE: `HY000' (`ER_BAD_LOG_STATEMENT') Message: You cannot '%s' a log table if logging is enabled `ER_BAD_LOG_STATEMENT' was introduced in 5.1.12. * 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' `ER_CANT_RENAME_LOG_TABLE' was introduced in 5.1.13. * Error: `1582' SQLSTATE: `42000' (`ER_WRONG_PARAMCOUNT_TO_NATIVE_FCT') Message: Incorrect parameter count in the call to native function '%s' `ER_WRONG_PARAMCOUNT_TO_NATIVE_FCT' was introduced in 5.1.13. * Error: `1583' SQLSTATE: `42000' (`ER_WRONG_PARAMETERS_TO_NATIVE_FCT') Message: Incorrect parameters in the call to native function '%s' `ER_WRONG_PARAMETERS_TO_NATIVE_FCT' was introduced in 5.1.13. * Error: `1584' SQLSTATE: `42000' (`ER_WRONG_PARAMETERS_TO_STORED_FCT') Message: Incorrect parameters in the call to stored function '%s' `ER_WRONG_PARAMETERS_TO_STORED_FCT' was introduced in 5.1.14. * Error: `1585' SQLSTATE: `HY000' (`ER_NATIVE_FCT_NAME_COLLISION') Message: This function '%s' has the same name as a native function `ER_NATIVE_FCT_NAME_COLLISION' was introduced in 5.1.14. * Error: `1586' SQLSTATE: `23000' (`ER_DUP_ENTRY_WITH_KEY_NAME') Message: Duplicate entry '%s' for key '%s' `ER_DUP_ENTRY_WITH_KEY_NAME' was introduced in 5.1.15. From 5.1.20: 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 `ER_BINLOG_PURGE_EMFILE' was introduced in 5.1.14. * 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. `ER_EVENT_CANNOT_CREATE_IN_THE_PAST' was introduced in 5.1.17. * 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 dropped immediately after creation. `ER_EVENT_CANNOT_ALTER_IN_THE_PAST' was introduced in 5.1.17. * Error: `1590' SQLSTATE: `HY000' (`ER_SLAVE_INCIDENT') Message: The incident %s occured on the master. Message: %s `ER_SLAVE_INCIDENT' was introduced in 5.1.18. * Error: `1591' SQLSTATE: `HY000' (`ER_NO_PARTITION_FOR_GIVEN_VALUE_SILENT') Message: Table has no partition for some existing values `ER_NO_PARTITION_FOR_GIVEN_VALUE_SILENT' was introduced in 5.1.18. * Error: `1592' SQLSTATE: `HY000' (`ER_BINLOG_UNSAFE_STATEMENT') Message: Statement may not be safe to log in statement format. `ER_BINLOG_UNSAFE_STATEMENT' was introduced in 5.1.20. * Error: `1593' SQLSTATE: `HY000' (`ER_SLAVE_FATAL_ERROR') Message: Fatal error: %s `ER_SLAVE_FATAL_ERROR' was introduced in 5.1.20. * Error: `1594' SQLSTATE: `HY000' (`ER_SLAVE_RELAY_LOG_READ_FAILURE') Message: Relay log read failure: %s `ER_SLAVE_RELAY_LOG_READ_FAILURE' was introduced in 5.1.20. * Error: `1595' SQLSTATE: `HY000' (`ER_SLAVE_RELAY_LOG_WRITE_FAILURE') Message: Relay log write failure: %s `ER_SLAVE_RELAY_LOG_WRITE_FAILURE' was introduced in 5.1.20. * Error: `1596' SQLSTATE: `HY000' (`ER_SLAVE_CREATE_EVENT_FAILURE') Message: Failed to create %s `ER_SLAVE_CREATE_EVENT_FAILURE' was introduced in 5.1.20. * Error: `1597' SQLSTATE: `HY000' (`ER_SLAVE_MASTER_COM_FAILURE') Message: Master command %s failed: %s `ER_SLAVE_MASTER_COM_FAILURE' was introduced in 5.1.20. * Error: `1598' SQLSTATE: `HY000' (`ER_BINLOG_LOGGING_IMPOSSIBLE') Message: Binary logging not possible. Message: %s `ER_BINLOG_LOGGING_IMPOSSIBLE' was introduced in 5.1.20. * Error: `1599' SQLSTATE: `HY000' (`ER_VIEW_NO_CREATION_CTX') Message: View `%s`.`%s` has no creation context `ER_VIEW_NO_CREATION_CTX' was introduced in 5.1.21. * Error: `1600' SQLSTATE: `HY000' (`ER_VIEW_INVALID_CREATION_CTX') Message: Creation context of view `%s`.`%s' is invalid `ER_VIEW_INVALID_CREATION_CTX' was introduced in 5.1.21. * Error: `1601' SQLSTATE: `HY000' (`ER_SR_INVALID_CREATION_CTX') Message: Creation context of stored routine `%s`.`%s` is invalid `ER_SR_INVALID_CREATION_CTX' was introduced in 5.1.21. * Error: `1602' SQLSTATE: `HY000' (`ER_TRG_CORRUPTED_FILE') Message: Corrupted TRG file for table `%s`.`%s` `ER_TRG_CORRUPTED_FILE' was introduced in 5.1.21. * Error: `1603' SQLSTATE: `HY000' (`ER_TRG_NO_CREATION_CTX') Message: Triggers for table `%s`.`%s` have no creation context `ER_TRG_NO_CREATION_CTX' was introduced in 5.1.21. * Error: `1604' SQLSTATE: `HY000' (`ER_TRG_INVALID_CREATION_CTX') Message: Trigger creation context of table `%s`.`%s` is invalid `ER_TRG_INVALID_CREATION_CTX' was introduced in 5.1.21. * Error: `1605' SQLSTATE: `HY000' (`ER_EVENT_INVALID_CREATION_CTX') Message: Creation context of event `%s`.`%s` is invalid `ER_EVENT_INVALID_CREATION_CTX' was introduced in 5.1.21. * Error: `1606' SQLSTATE: `HY000' (`ER_TRG_CANT_OPEN_TABLE') Message: Cannot open table for trigger `%s`.`%s` `ER_TRG_CANT_OPEN_TABLE' was introduced in 5.1.21. * Error: `1607' SQLSTATE: `HY000' (`ER_CANT_CREATE_SROUTINE') Message: Cannot create stored routine `%s`. Check warnings `ER_CANT_CREATE_SROUTINE' was introduced in 5.1.23. * Error: `1608' SQLSTATE: `HY000' (`ER_SLAVE_AMBIGOUS_EXEC_MODE') Message: Ambiguous slave modes combination. %s `ER_SLAVE_AMBIGOUS_EXEC_MODE' was introduced in 5.1.24. * 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. `ER_NO_FORMAT_DESCRIPTION_EVENT_BEFORE_BINLOG_STATEMENT' was introduced in 5.1.24. * Error: `1610' SQLSTATE: `HY000' (`ER_SLAVE_CORRUPT_EVENT') Message: Corrupted replication event was detected `ER_SLAVE_CORRUPT_EVENT' was introduced in 5.1.24. * Error: `1611' SQLSTATE: `HY000' (`ER_LOAD_DATA_INVALID_COLUMN') Message: Invalid column reference (%s) in LOAD DATA `ER_LOAD_DATA_INVALID_COLUMN' was introduced in 5.1.24. * Error: `1612' SQLSTATE: `HY000' (`ER_LOG_PURGE_NO_FILE') Message: Being purged log %s was not found `ER_LOG_PURGE_NO_FILE' was introduced in 5.1.24. * Error: `1613' SQLSTATE: `XA106' (`ER_XA_RBTIMEOUT') Message: XA_RBTIMEOUT: Transaction branch was rolled back: took too long `ER_XA_RBTIMEOUT' was introduced in 5.1.30. * Error: `1614' SQLSTATE: `XA102' (`ER_XA_RBDEADLOCK') Message: XA_RBDEADLOCK: Transaction branch was rolled back: deadlock was detected `ER_XA_RBDEADLOCK' was introduced in 5.1.30. * Error: `1615' SQLSTATE: `HY000' (`ER_NEED_REPREPARE') Message: Prepared statement needs to be re-prepared `ER_NEED_REPREPARE' was introduced in 5.1.25. * Error: `1616' SQLSTATE: `HY000' (`ER_DELAYED_NOT_SUPPORTED') Message: DELAYED option not supported for table '%s' `ER_DELAYED_NOT_SUPPORTED' was introduced in 5.1.28. * Error: `1617' SQLSTATE: `HY000' (`WARN_NO_MASTER_INFO') Message: The master info structure does not exist `WARN_NO_MASTER_INFO' was introduced in 5.1.31. * Error: `1618' SQLSTATE: `HY000' (`WARN_OPTION_IGNORED') Message: <%s> option ignored `WARN_OPTION_IGNORED' was introduced in 5.1.31. * Error: `1619' SQLSTATE: `HY000' (`WARN_PLUGIN_DELETE_BUILTIN') Message: Built-in plugins cannot be deleted `WARN_PLUGIN_DELETE_BUILTIN' was introduced in 5.1.31. * Error: `1620' SQLSTATE: `HY000' (`WARN_PLUGIN_BUSY') Message: Plugin is busy and will be uninstalled on shutdown `WARN_PLUGIN_BUSY' was introduced in 5.1.31. * Error: `1621' SQLSTATE: `HY000' (`ER_VARIABLE_IS_READONLY') Message: %s variable '%s' is read-only. Use SET %s to assign the value `ER_VARIABLE_IS_READONLY' was introduced in 5.1.31. * 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 `ER_WARN_ENGINE_TRANSACTION_ROLLBACK' was introduced in 5.1.33. * Error: `1623' SQLSTATE: `HY000' (`ER_SLAVE_HEARTBEAT_FAILURE') Message: Unexpected master's heartbeat data: %s `ER_SLAVE_HEARTBEAT_FAILURE' was introduced in 5.1.33. * Error: `1624' SQLSTATE: `HY000' (`ER_SLAVE_HEARTBEAT_VALUE_OUT_OF_RANGE') Message: The requested value for the heartbeat period %s %s `ER_SLAVE_HEARTBEAT_VALUE_OUT_OF_RANGE' was introduced in 5.1.33. * Error: `1625' SQLSTATE: `HY000' (`ER_NDB_REPLICATION_SCHEMA_ERROR') Message: Bad schema for mysql.ndb_replication table. Message: %s `ER_NDB_REPLICATION_SCHEMA_ERROR' was introduced in 5.1.33. * Error: `1626' SQLSTATE: `HY000' (`ER_CONFLICT_FN_PARSE_ERROR') Message: Error in parsing conflict function. Message: %s `ER_CONFLICT_FN_PARSE_ERROR' was introduced in 5.1.33. * Error: `1627' SQLSTATE: `HY000' (`ER_EXCEPTIONS_WRITE_ERROR') Message: Write to exceptions table failed. Message: %s" `ER_EXCEPTIONS_WRITE_ERROR' was introduced in 5.1.33. * Error: `1628' SQLSTATE: `HY000' (`ER_TOO_LONG_TABLE_COMMENT') Message: Comment for table '%s' is too long (max = %lu) `ER_TOO_LONG_TABLE_COMMENT' was introduced in 5.1.33. * Error: `1629' SQLSTATE: `HY000' (`ER_TOO_LONG_FIELD_COMMENT') Message: Comment for field '%s' is too long (max = %lu) `ER_TOO_LONG_FIELD_COMMENT' was introduced in 5.1.33. * 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 `ER_FUNC_INEXISTENT_NAME_COLLISION' was introduced in 5.1.36. * Error: `1631' SQLSTATE: `HY000' (`ER_DATABASE_NAME') Message: Database `ER_DATABASE_NAME' was introduced in 5.1.36. * Error: `1632' SQLSTATE: `HY000' (`ER_TABLE_NAME') Message: Table `ER_TABLE_NAME' was introduced in 5.1.36. * Error: `1633' SQLSTATE: `HY000' (`ER_PARTITION_NAME') Message: Partition `ER_PARTITION_NAME' was introduced in 5.1.36. * Error: `1634' SQLSTATE: `HY000' (`ER_SUBPARTITION_NAME') Message: Subpartition `ER_SUBPARTITION_NAME' was introduced in 5.1.36. * Error: `1635' SQLSTATE: `HY000' (`ER_TEMPORARY_NAME') Message: Temporary `ER_TEMPORARY_NAME' was introduced in 5.1.36. * Error: `1636' SQLSTATE: `HY000' (`ER_RENAMED_NAME') Message: Renamed `ER_RENAMED_NAME' was introduced in 5.1.36. * Error: `1637' SQLSTATE: `HY000' (`ER_TOO_MANY_CONCURRENT_TRXS') Message: Too many active concurrent transactions `ER_TOO_MANY_CONCURRENT_TRXS' was introduced in 5.1.38. * Error: `1638' SQLSTATE: `HY000' (`WARN_NON_ASCII_SEPARATOR_NOT_IMPLEMENTED') Message: Non-ASCII separator arguments are not fully supported `WARN_NON_ASCII_SEPARATOR_NOT_IMPLEMENTED' was introduced in 5.1.38. * Error: `1639' SQLSTATE: `HY000' (`ER_DEBUG_SYNC_TIMEOUT') Message: debug sync point wait timed out `ER_DEBUG_SYNC_TIMEOUT' was introduced in 5.1.40. * Error: `1640' SQLSTATE: `HY000' (`ER_DEBUG_SYNC_HIT_LIMIT') Message: debug sync point hit limit reached `ER_DEBUG_SYNC_HIT_LIMIT' was introduced in 5.1.40.  File: manual.info, Node: error-messages-client, Next: problems, Prev: error-messages-server, Up: error-handling C.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 * 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 * 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) * 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 `CR_SERVER_LOST_EXTENDED' was introduced in 5.1.14. * Error: `2056' (`CR_STMT_CLOSED') Message: Statement closed indirectly because of a preceeding %s() call `CR_STMT_CLOSED' was introduced in 5.1.18. * 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 `CR_NEW_STMT_METADATA' was introduced in 5.1.25.  File: manual.info, Node: problems, Prev: error-messages-client, Up: error-handling C.5 Problems and Common Errors ============================== * Menu: * what-is-crashing:: How to Determine What Is Causing a Problem * common-errors:: Common Errors When Using MySQL Programs * installation-issues:: Installation-Related Issues * administration-issues:: Administration-Related Issues * query-issues:: Query-Related Issues * optimizer-issues:: Optimizer-Related Issues * table-definition-issues:: Table Definition-Related Issues * bugs:: Known Issues in MySQL 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.  File: manual.info, Node: what-is-crashing, Next: common-errors, Prev: problems, Up: problems C.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 *Note 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 *Note `mysqld': mysqld. server is causing problems, can you get any response from it with *Note `mysqladmin -u root ping': mysqladmin. or *Note `mysqladmin -u root processlist': mysqladmin.? * What does a client program say when you try to connect to the MySQL server? (Try with *Note `mysql': 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 *Note bug-reports::.  File: manual.info, Node: common-errors, Next: installation-issues, Prev: what-is-crashing, Up: problems C.5.2 Common Errors When Using MySQL Programs --------------------------------------------- * Menu: * error-access-denied:: `Access denied' * can-not-connect-to-server:: `Can't connect to [local] MySQL server' * error-lost-connection:: `Lost connection to MySQL server' * old-client:: `Client does not support authentication protocol' * password-too-long:: Password Fails When Entered Interactively * blocked-host:: `Host 'HOST_NAME' is blocked' * too-many-connections:: `Too many connections' * out-of-memory:: `Out of memory' * gone-away:: `MySQL server has gone away' * packet-too-large:: Packet Too Large * communication-errors:: Communication Errors and Aborted Connections * full-table:: `The table is full' * cannot-create:: `Can't create/write to file' * commands-out-of-sync:: `Commands out of sync' * ignoring-user:: `Ignoring user' * cannot-find-table:: `Table 'TBL_NAME' doesn't exist' * cannot-initialize-character-set:: `Can't initialize character set' * not-enough-file-handles:: `'FILE' Not Found' and Similar Errors * table-corruption:: Table-Corruption Issues 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.  File: manual.info, Node: error-access-denied, Next: can-not-connect-to-server, Prev: common-errors, Up: common-errors C.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 *Note privilege-system::, and *Note access-denied::.  File: manual.info, Node: can-not-connect-to-server, Next: error-lost-connection, Prev: error-access-denied, Up: common-errors C.5.2.2 `Can't connect to [local] MySQL server' ............................................... * Menu: * can-not-connect-to-server-on-windows:: `Connection to MySQL Server Failing on Windows' A MySQL client on Unix can connect to the *Note `mysqld': 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 *Note `mysqld': 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 *Note `mysqld': 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 *Note starting-server::. If a *Note `mysqld': 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 *Note `mysqladmin': 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 the Windows XP personal 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: * *Note `mysqld': mysqld. is not running on the local host. Check your operating system's process list to ensure the *Note `mysqld': 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: *Note can-not-connect-to-server-on-windows::. * Someone has removed the Unix socket file that *Note `mysqld': 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 *Note `mysqladmin version': mysqladmin. to check whether the Unix socket file that *Note `mysqladmin': 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 *Note problems-with-mysql-sock::. * You have started the *Note `mysqld': 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 *Note problems-with-mysql-sock::. * You are using Linux and one server thread has died (dumped core). In this case, you must kill the other *Note `mysqld': mysqld. threads (for example, with *Note `kill': kill. or with the *Note `mysql_zap': mysql-zap. script) before you can restart the MySQL server. See *Note 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 *Note `mysqld': 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 *Note `mysqladmin -h localhost variables': mysqladmin. 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.  File: manual.info, Node: can-not-connect-to-server-on-windows, Prev: can-not-connect-to-server, Up: can-not-connect-to-server C.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 the registry 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 0 (zero) and 300 (decimal). 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.  File: manual.info, Node: error-lost-connection, Next: old-client, Prev: can-not-connect-to-server, Up: common-errors C.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 *Note `BLOB': 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'.  File: manual.info, Node: old-client, Next: password-too-long, Prev: error-lost-connection, Up: common-errors C.5.2.5 `Client does not support authentication protocol' ......................................................... The current implementation of the authentication protocol uses a password hashing algorithm that is incompatible with that used by older (pre-4.1) clients. Attempts to connect to a 4.1 or newer server with an older client may fail with the following message: shell> mysql Client does not support authentication protocol requested by server; consider upgrading MySQL client To deal with this problem, the preferred solution is to upgrade all client programs to use a 4.1.1 or newer client library. If that is not possible, use one of the following approaches: * To connect to the server with a pre-4.1 client program, use an account that still has a pre-4.1-style password. * Reset the password to pre-4.1 style for each user that needs to use a pre-4.1 client program. This can be done using the *Note `SET PASSWORD': set-password. statement and the `OLD_PASSWORD()' function: mysql> SET PASSWORD FOR -> 'SOME_USER'@'SOME_HOST' = OLD_PASSWORD('NEWPWD'); Substitute the password you want to use for `NEWPWD' in the preceding example. MySQL cannot tell you what the original password was, so you'll need to pick a new one. * Tell the server to use the older password hashing algorithm by default: 1. Start *Note `mysqld': mysqld. with the `old_passwords' system variable set to 1. 2. Assign an old-format password to each account that has had its password updated to the longer 4.1 format. You can identify these accounts with the following query: mysql> SELECT Host, User, Password FROM mysql.user -> WHERE LENGTH(Password) > 16; For each account record displayed by the query, use the `Host' and `User' values and assign a password using one of the methods described previously. The `Client does not support authentication protocol' error also can occur if multiple versions of MySQL are installed but client programs are dynamically linked and link to an older library. Make sure that clients use the most recent library version with which they are compatible. The procedure to do this will depend on your system. *Note*: The `mysql' extension does not support the authentication protocol in MySQL 4.1.1 and higher. This is true regardless of the PHP version being used. If you wish to use the `mysql' extension with MySQL 4.1 or newer, you may need to follow one of the options discussed above for configuring MySQL to work with old clients. The `mysqli' extension (stands for "MySQL, Improved"; added in PHP 5) is compatible with the improved password hashing employed in MySQL 4.1 and higher, and no special configuration of MySQL need be done to use this MySQL client library. For more information about the `mysqli' extension, see `http://php.net/mysqli'. For additional background on password hashing and authentication, see *Note password-hashing::.  File: manual.info, Node: password-too-long, Next: blocked-host, Prev: old-client, Up: common-errors C.5.2.6 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.  File: manual.info, Node: blocked-host, Next: too-many-connections, Prev: password-too-long, Up: common-errors C.5.2.7 `Host 'HOST_NAME' is blocked' ..................................... If the following error occurs, it means that *Note `mysqld': 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 *Note server-system-variables::.) After `max_connect_errors' failed requests without a successful connection, *Note `mysqld': 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 *Note `FLUSH HOSTS': flush. statement or execute a *Note `mysqladmin flush-hosts': mysqladmin. command. By default, *Note `mysqld': mysqld. blocks a host after 10 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.  File: manual.info, Node: too-many-connections, Next: out-of-memory, Prev: blocked-host, Up: common-errors C.5.2.8 `Too many connections' .............................. If you get a `Too many connections' error when you try to connect to the *Note `mysqld': 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. Beginning with MySQL 5.1.15, its 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. *Note `mysqld': 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 *Note `SHOW PROCESSLIST': show-processlist. to diagnose problems even if the maximum number of unprivileged clients are connected. See *Note show-processlist::. The maximum number of connections MySQL can support 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 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 *Note linux-installation::, for how to raise the operating system limit on how many handles can be used by MySQL.  File: manual.info, Node: out-of-memory, Next: gone-away, Prev: too-many-connections, Up: common-errors C.5.2.9 `Out of memory' ....................... If you issue a query using the *Note `mysql': mysql. client program and receive an error like the following one, it means that *Note `mysql': 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 *Note `mysql': mysql. with the `--quick' option. This causes it to use the *Note `mysql_use_result()': 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).  File: manual.info, Node: gone-away, Next: packet-too-large, Prev: out-of-memory, Up: common-errors C.5.2.10 `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). This table lists `MySQL server has gone away' error codes and provides a description of each. 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 *Note `mysqld': mysqld. See *Note 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 *Note `KILL': kill. statement or a *Note `mysqladmin kill': mysqladmin. 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: *Note `mysql_options(..., MYSQL_OPT_READ_TIMEOUT,...)': mysql-options. or *Note `mysql_options(..., MYSQL_OPT_WRITE_TIMEOUT,...)': mysql-options. 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. Prior to MySQL 5.1.8, even if the `reconnect' flag in the `MYSQL' structure is equal to 1, MySQL does not automatically reconnect and re-issue the query as it doesn't know if the server did get the original query or not. The solution to this is to either do a *Note `mysql_ping()': 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 *Note `mysqld': 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 *Note `mysqld': 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 *Note `BLOB': blob. columns), you can increase the query limit by setting the server's `max_allowed_packet' variable, which has a default value of 1MB. You may also need to increase the maximum packet size on the client end. More information on setting the packet size is given in *Note packet-too-large::. An *Note `INSERT': insert. or *Note `REPLACE': 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 *Note `INSERT': insert. or *Note `REPLACE': replace. * You also get a lost connection if you are sending a packet 16MB or larger if your client is older than 4.0.8 and your server is 4.0.8 and above, or the other way around. * 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 *Note `mysqladmin version': mysqladmin. and examining the server's uptime. If the client connection was broken because *Note `mysqld': 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 *Note crashing::. You can get more information about the lost connections by starting *Note `mysqld': mysqld. with the `--log-warnings=2' option. This logs some of the disconnected errors in the `hostname.err' file. See *Note 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 *Note crashing::. * If a specific query kills *Note `mysqld': mysqld. and the tables involved were checked with *Note `CHECK TABLE': check-table. before you ran the query, can you provide a reproducible test case? See *Note porting::. * What is the value of the `wait_timeout' system variable in the MySQL server? (*Note `mysqladmin variables': mysqladmin. gives you the value of this variable.) * Have you tried to run *Note `mysqld': mysqld. with the general query log enabled to determine whether the problem query appears in the log? (See *Note query-log::.) See also *Note communication-errors::, and *Note bug-reports::.  File: manual.info, Node: packet-too-large, Next: communication-errors, Prev: gone-away, Up: common-errors C.5.2.11 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.1 server or client is 1GB. When a MySQL client or the *Note `mysqld': 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 *Note `mysql': mysql. client program, its default `max_allowed_packet' variable is 16MB. To set a larger value, start *Note `mysql': 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 1MB. You can increase this if the server needs to handle big queries (for example, if you are working with big *Note `BLOB': 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, *Note `mysqld': mysqld. allocates more memory only when you issue a long query or when *Note `mysqld': 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 *Note `BLOB': blob. values but have not given *Note `mysqld': 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 *Note `mysqld_safe': mysqld-safe. script and restarting *Note `mysqld': mysqld.  File: manual.info, Node: communication-errors, Next: full-table, Prev: packet-too-large, Up: common-errors C.5.2.12 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 *Note error-log::. * The general query log. See *Note query-log::. * The `Aborted_XXX' status variables. See *Note server-status-variables::. If you start the server with the `--log-warnings' option, you might find messages like this in your error log: 010301 14:38:23 Aborted connection 854 to db: 'users' user: 'josh' 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 *Note `mysql_close()': 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 *Note server-system-variables::. * The client program ended abruptly in the middle of a data transfer. 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 does not have privileges to connect to a database. * A client uses an incorrect password. * A connection packet does not contain the right information. * It takes more than `connect_timeout' seconds to get a connect packet. See *Note server-system-variables::. If these kinds of things happen, it might indicate that someone is trying to break into your server! Messages for these types of problems are logged to the general query log if it is enabled. Other reasons for problems with aborted clients or aborted connections: * The `max_allowed_packet' variable value is too small or queries require more memory than you have allocated for *Note `mysqld': mysqld. See *Note packet-too-large::. * Use of Ethernet protocol with Linux, both half and full duplex. Many 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 *Note gone-away::.  File: manual.info, Node: full-table, Next: cannot-create, Prev: communication-errors, Up: common-errors C.5.2.13 `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 *Note table-size-limit::. This error can occur sometimes for MySQL Cluster tables even when there appears to be more than sufficient data memory available. See the documentation for the `DataMemory' MySQL Cluster data node configuration parameter, as well as *Note mysql-cluster-nodes-groups::, for more information.  File: manual.info, Node: cannot-create, Next: commands-out-of-sync, Prev: full-table, Up: common-errors C.5.2.14 `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 *Note `mysqld': 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 *Note 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 *Note `perror': 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  File: manual.info, Node: commands-out-of-sync, Next: ignoring-user, Prev: cannot-create, Up: common-errors C.5.2.15 `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 *Note `mysql_use_result()': mysql-use-result. and try to execute a new query before you have called *Note `mysql_free_result()': mysql-free-result. It can also happen if you try to execute two queries that return data without calling *Note `mysql_use_result()': mysql-use-result. or *Note `mysql_store_result()': mysql-store-result. in between.  File: manual.info, Node: ignoring-user, Next: cannot-find-table, Prev: commands-out-of-sync, Up: common-errors C.5.2.16 `Ignoring user' ........................ If you get the following error, it means that when *Note `mysqld': 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 *Note `mysqld': mysqld. with an old `user' table. You can check this by executing *Note `mysqlshow mysql user': mysqlshow. to see whether the `Password' column is shorter than 16 characters. If so, you can correct this condition by running the `scripts/add_long_password' script. * 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 *Note `mysql': 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('NEWPWD') -> WHERE User='SOME_USER' AND Host='SOME_HOST';  File: manual.info, Node: cannot-find-table, Next: cannot-initialize-character-set, Prev: ignoring-user, Up: common-errors C.5.2.17 `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 *Note `SHOW TABLES': show-tables. See *Note show::.  File: manual.info, Node: cannot-initialize-character-set, Next: not-enough-file-handles, Prev: cannot-find-table, Up: common-errors C.5.2.18 `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 multi-byte 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 `configure' with the `--with-charset=CHARSET_NAME' or `--with-extra-charsets=CHARSET_NAME' option. See *Note source-configuration-options::. All standard MySQL binaries are compiled with `--with-extra-charsets=complex' or (for Windows) `--with-extra-charsets=complex', which enables support for all multi-byte character sets. See *Note source-configuration-options::. * The character set is a simple character set that is not compiled into *Note `mysqld': 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 *Note 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.  File: manual.info, Node: not-enough-file-handles, Next: table-corruption, Prev: cannot-initialize-character-set, Up: common-errors C.5.2.19 `'FILE' Not Found' and Similar Errors .............................................. If you get `ERROR '...' not found (errno: 23)', `Can't open file: ... (errno: 24)', or any other error with `errno 23' or `errno 24' from MySQL, it means that you haven't allocated enough file descriptors for the MySQL server. You can use the *Note `perror': 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 *Note `mysqld': mysqld. is trying to keep open too many files simultaneously. You can either tell *Note `mysqld': mysqld. not to open so many files at once or increase the number of file descriptors available to *Note `mysqld': mysqld. To tell *Note `mysqld': 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 *Note 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 *Note `mysqld': mysqld, you can use the `--open-files-limit' option to *Note `mysqld_safe': mysqld-safe. or set the `open_files_limit' system variable. See *Note server-system-variables::. The easiest way to set these values is to add an option to your option file. See *Note option-files::. If you have an old version of *Note `mysqld': mysqld. that does not support setting the open files limit, you can edit the *Note `mysqld_safe': 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 *Note `mysqld': 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 *Note `mysqld_safe': mysqld-safe. or *Note `mysqld': 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 *Note `mysqld_safe': mysqld-safe. using `sh'.  File: manual.info, Node: table-corruption, Prev: not-enough-file-handles, Up: common-errors C.5.2.20 Table-Corruption Issues ................................ If you have started *Note `mysqld': mysqld. with `--myisam-recover', 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 *Note `mysqld': mysqld. having died unexpectedly just before, then something is wrong and needs to be investigated further. See also *Note server-options::, and *Note reproducible-test-case::.  File: manual.info, Node: installation-issues, Next: administration-issues, Prev: common-errors, Up: problems C.5.3 Installation-Related Issues --------------------------------- * Menu: * file-permissions:: Problems with File Permissions  File: manual.info, Node: file-permissions, Prev: installation-issues, Up: installation-issues C.5.3.1 Problems with File Permissions ...................................... If you have problems with file permissions, the `UMASK' environment variable might be set incorrectly when *Note `mysqld': 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' value is `0660'. You can change this behavior by starting *Note `mysqld_safe': 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 `0700'. You can modify this behavior by setting the `UMASK_DIR' variable. If you set its value, new directories are created with the combined `UMASK' and `UMASK_DIR' values. For example, if you want to give group access to all new directories, you can do this: shell> UMASK_DIR=504 # = 770 in octal shell> export UMASK_DIR shell> mysqld_safe & MySQL assumes that the value for `UMASK' or `UMASK_DIR' is in octal if it starts with a zero. See *Note environment-variables::.  File: manual.info, Node: administration-issues, Next: query-issues, Prev: installation-issues, Up: problems C.5.4 Administration-Related Issues ----------------------------------- * Menu: * resetting-permissions:: How to Reset the Root Password * crashing:: What to Do If MySQL Keeps Crashing * full-disk:: How MySQL Handles a Full Disk * temporary-files:: Where MySQL Stores Temporary Files * problems-with-mysql-sock:: How to Protect or Change the MySQL Unix Socket File * timezone-problems:: Time Zone Problems  File: manual.info, Node: resetting-permissions, Next: crashing, Prev: administration-issues, Up: administration-issues C.5.4.1 How to Reset the Root Password ...................................... * Menu: * resetting-permissions-windows:: Resetting the Root Password: Windows Systems * resetting-permissions-unix:: Resetting the Root Password: Unix Systems * resetting-permissions-generic:: Resetting the Root Password: Generic Instructions If you have never set 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 passwords, see *Note default-privileges::. If you know the `root' password, but want to change it, see *Note set-password::. If you set a `root' password previously, but have forgotten it, you can set a new password. The following sections provide instructions for Windows and Unix systems, as well as generic instructions that apply to any system.  File: manual.info, Node: resetting-permissions-windows, Next: resetting-permissions-unix, Prev: resetting-permissions, Up: resetting-permissions C.5.4.2 Resetting the Root Password: Windows Systems .................................................... On Windows, use the following procedure to reset the password for all MySQL `root' accounts: 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 following statements. Replace the password with the password that you want to use. UPDATE mysql.user SET Password=PASSWORD('MyNewPass') WHERE User='root'; FLUSH PRIVILEGES; Write the *Note `UPDATE': update. and *Note `FLUSH': flush. statements each on a single line. The *Note `UPDATE': update. statement resets the password for all `root' accounts, and the *Note `FLUSH': flush. statement tells the server to reload the grant tables into memory so that it notices the password change. 4. Save the file. For this example, the file will be named `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:\> C:\mysql\bin\mysqld --init-file=C:\\mysql-init.txt If you installed MySQL to a location other than `C:\mysql', adjust the command accordingly. The server executes the contents of the file named by the `--init-file' option at startup, changing each `root' account password. You can also add the `--console' option to the command if you want server output to appear in the console window rather than in a log file. If you installed MySQL using the MySQL Installation Wizard, you may need to specify a `--defaults-file' option: C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqld.exe" --defaults-file="C:\\Program Files\\MySQL\\MySQL Server 5.1\\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, then restart it in normal mode again. 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.  File: manual.info, Node: resetting-permissions-unix, Next: resetting-permissions-generic, Prev: resetting-permissions-windows, Up: resetting-permissions C.5.4.3 Resetting the Root Password: Unix Systems ................................................. On Unix, use the following procedure to reset the password for all MySQL `root' accounts. The instructions assume that you will start the server so that it runs using the Unix login account that you normally use for running the server. 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 *Note `mysqld': 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 *Note `mysqld': mysqld. server runs as (for example, `mysql'). 2. 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. You can stop the MySQL server by sending a normal `kill' (not `kill -9') to the *Note `mysqld': mysqld. process, using the 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 following statements. Replace the password with the password that you want to use. UPDATE mysql.user SET Password=PASSWORD('MyNewPass') WHERE User='root'; FLUSH PRIVILEGES; Write the *Note `UPDATE': update. and *Note `FLUSH': flush. statements each on a single line. The *Note `UPDATE': update. statement resets the password for all `root' accounts, and the *Note `FLUSH': flush. statement tells the server to reload the grant tables into memory so that it notices the password change. 4. Save the file. For this example, the file will be named `/home/me/mysql-init'. The file contains the password, so it should not be saved 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_safe --init-file=/home/me/mysql-init & The server executes the contents of the file named by the `--init-file' option at startup, changing each `root' account password. 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.  File: manual.info, Node: resetting-permissions-generic, Prev: resetting-permissions-unix, Up: resetting-permissions C.5.4.4 Resetting the Root Password: Generic Instructions ......................................................... The preceding sections provide password-resetting instructions for Windows and Unix systems. Alternatively, on any platform, you can set the new password using the *Note `mysql': mysql. client (but this approach is less secure): 1. Stop *Note `mysqld': mysqld. and restart it with the `--skip-grant-tables' option. This enables anyone to connect without a password and with all privileges. 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 *Note `mysqld': mysqld. server with this command: shell> mysql 3. Issue the following statements in the *Note `mysql': mysql. client. Replace the password with the password that you want to use. mysql> UPDATE mysql.user SET Password=PASSWORD('MyNewPass') -> WHERE User='root'; mysql> FLUSH PRIVILEGES; The *Note `FLUSH': flush. statement tells the server to reload the grant tables into memory so that it notices the password change. You should now be able to connect to the MySQL server as `root' using the new password. Stop the server, then restart it normally (without the `--skip-grant-tables' and `--skip-networking' options).  File: manual.info, Node: crashing, Next: full-disk, Prev: resetting-permissions, Up: administration-issues C.5.4.5 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 *Note `mysqld': mysqld. server dies or whether your problem has to do with your client. You can check how long your *Note `mysqld': mysqld. server has been up by executing *Note `mysqladmin version': mysqladmin. If *Note `mysqld': mysqld. has died and restarted, you may find the reason by looking in the server's error log. See *Note error-log::. On some systems, you can find in the error log a stack trace of where *Note `mysqld': mysqld. died that you can resolve with the `resolve_stack_dump' program. See *Note 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 *Note `mysqld': 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 *Note `mysqld': 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 *Note `mysqld': 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 *Note `mysqld': mysqld. without locking the table properly. * You are running many *Note `mysqld': 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 *Note `mysqld': 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 *Note `ALTER TABLE': 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. Please try the following things: * Stop the *Note `mysqld': mysqld. server with *Note `mysqladmin shutdown': mysqladmin, run *Note `myisamchk --silent --force */*.MYI': myisamchk. from the data directory to check all `MyISAM' tables, and restart *Note `mysqld': mysqld. This ensures that you are running from a clean state. See *Note server-administration::. * Start *Note `mysqld': mysqld. with the general query log enabled (see *Note 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 *Note 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 been able to locate the bug and should submit a bug report for it. See *Note bug-reports::. * Try to make a test case that we can use to repeat the problem. See *Note porting::. * Try running the tests in the `mysql-test' directory and the MySQL benchmarks. See *Note mysql-test-suite::. They should test MySQL rather well. You can also add code to the benchmarks that simulates your application. The benchmarks can be found in the `sql-bench' directory in a source distribution or, for a binary distribution, in the `sql-bench' directory under your MySQL installation directory. * Try the `fork_big.pl' script. (It is located in the `tests' directory of source distributions.) * If you configure MySQL for debugging, it is much easier to gather information about possible errors if something goes wrong. Configuring MySQL for debugging causes a safe memory allocator to be included that can find some errors. It also provides a lot of output about what is happening. Reconfigure MySQL with the `--with-debug' or `--with-debug=full' option to `configure' and then recompile. See *Note porting::. * Make sure that you have applied the latest patches for your operating system. * Use the `--skip-external-locking' option to *Note `mysqld': mysqld. On some systems, the `lockd' lock manager does not work properly; the `--skip-external-locking' option tells *Note `mysqld': mysqld. not to use external locking. (This means that you cannot run two *Note `mysqld': mysqld. servers on the same data directory and that you must be careful if you use *Note `myisamchk': myisamchk. Nevertheless, it may be instructive to try the option as a test.) * Have you tried *Note `mysqladmin -u root processlist': mysqladmin. when *Note `mysqld': mysqld. appears to be running but not responding? Sometimes *Note `mysqld': mysqld. is not comatose even though you might think so. The problem may be that all connections are in use, or there may be some internal lock problem. *Note `mysqladmin -u root processlist': mysqladmin. 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 *Note `mysqladmin -i 5 status': mysqladmin. or *Note `mysqladmin -i 5 -r status': mysqladmin. in a separate window to produce statistics while you run your other queries. * Try the following: 1. Start *Note `mysqld': mysqld. from `gdb' (or another debugger). See *Note 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 *Note `mysqld': 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 *Note bug-reports::. Be even more detailed than usual. Because MySQL works for many people, it may be that the crash results 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 *Note `VARCHAR': char. columns (not *Note `BLOB': blob. or *Note `TEXT': blob. columns), you can try to change all *Note `VARCHAR': char. to *Note `CHAR': char. with *Note `ALTER TABLE': 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. * Do not rule out your server hardware when diagnosing problems. Defective hardware can be the cause of data corruption. Particular attention should be paid to your memory and disk subsystems when troubleshooting hardware.  File: manual.info, Node: full-disk, Next: temporary-files, Prev: crashing, Up: administration-issues C.5.4.6 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, you can take the following actions: * To continue, you only have to free enough disk space to insert all records. * To abort the thread, you must use *Note `mysqladmin kill': mysqladmin. 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 *Note `REPAIR TABLE': repair-table. or *Note `OPTIMIZE TABLE': optimize-table. or when the indexes are created in a batch after *Note `LOAD DATA INFILE': load-data. or after an *Note `ALTER TABLE': 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 *Note `ALTER TABLE': alter-table, the old table is left unchanged.  File: manual.info, Node: temporary-files, Next: problems-with-mysql-sock, Prev: full-disk, Up: administration-issues C.5.4.7 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, Netware and OS2, 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 `--tmpdir' option to *Note `mysqld': mysqld. to specify a directory in a file system where you have enough space. In MySQL 5.1, 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, NetWare, and OS/2. *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 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 *Note `LOAD DATA INFILE': load-data. operations. If files in the temporary file directory are lost when the server restarts, replication fails. MySQL arranges that temporary files are removed if *Note `mysqld': 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 *Note `mysqld': 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 *Note `SELECT': select. queries, MySQL also creates temporary SQL tables. These are not hidden and have names of the form `SQL_*'. *Note `ALTER TABLE': alter-table. creates a temporary table in the same directory as the original table.  File: manual.info, Node: problems-with-mysql-sock, Next: timezone-problems, Prev: temporary-files, Up: administration-issues C.5.4.8 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 *Note option-files::. * Specify a `--socket' option on the command line to *Note `mysqld_safe': 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 `--with-unix-socket-path' option when you run `configure'. See *Note 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  File: manual.info, Node: timezone-problems, Prev: problems-with-mysql-sock, Up: administration-issues C.5.4.9 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 *Note `mysqld_safe': mysqld-safe. or *Note `mysql.server': mysql-server. See *Note environment-variables::. You can set the time zone for the server with the `--timezone=TIMEZONE_NAME' option to *Note `mysqld_safe': mysqld-safe. You can also set it by setting the `TZ' environment variable before you start *Note `mysqld': mysqld. The permissible values for `--timezone' or `TZ' are system dependent. Consult your operating system documentation to see what values are acceptable.  File: manual.info, Node: query-issues, Next: optimizer-issues, Prev: administration-issues, Up: problems C.5.5 Query-Related Issues -------------------------- * Menu: * case-sensitivity:: Case Sensitivity in String Searches * using-date:: Problems Using `DATE' Columns * problems-with-null:: Problems with `NULL' Values * problems-with-alias:: Problems with Column Aliases * nontransactional-tables:: Rollback Failure for Nontransactional Tables * deleting-from-related-tables:: Deleting Rows from Related Tables * no-matching-rows:: Solving Problems with No Matching Rows * problems-with-float:: Problems with Floating-Point Values  File: manual.info, Node: case-sensitivity, Next: using-date, Prev: query-issues, Up: query-issues C.5.5.1 Case Sensitivity in String Searches ........................................... For nonbinary strings (*Note `CHAR': char, *Note `VARCHAR': char, *Note `TEXT': blob.), string searches use the collation of the comparison operands. For binary strings (*Note `BINARY': binary-varbinary, *Note `VARBINARY': binary-varbinary, *Note `BLOB': 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 *Note 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 and encryption functions, which return binary strings as a general rule: string: mysql> SELECT COLLATION(ENCRYPT('x')), COLLATION(SHA1('x')); +-------------------------+----------------------+ | COLLATION(ENCRYPT('x')) | COLLATION(SHA1('x')) | +-------------------------+----------------------+ | binary | binary | +-------------------------+----------------------+  File: manual.info, Node: using-date, Next: problems-with-null, Prev: case-sensitivity, Up: query-issues C.5.5.2 Problems Using `DATE' Columns ..................................... The format of a *Note `DATE': datetime. value is `'YYYY-MM-DD''. According to standard SQL, no other format is permitted. You should use this format in *Note `UPDATE': update. expressions and in the `WHERE' clause of *Note `SELECT': 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 *Note `DATE': datetime, *Note `DATETIME': datetime, or *Note `TIMESTAMP': datetime. 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 *Note `DATE': datetime, *Note `TIME': time, *Note `DATETIME': datetime, or *Note `TIMESTAMP': datetime. 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 *Note `DATE': datetime, *Note `TIME': time, *Note `DATETIME': datetime, or *Note `TIMESTAMP': datetime. 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 *Note `DATE': datetime. 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 *Note `DATE': datetime. column and you know only part of the date. To disallow zero month or day parts in dates, enable the `NO_ZERO_IN_DATE' SQL 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 *Note `DATE': datetime. column cannot be converted to any reasonable value, MySQL stores `'0000-00-00''. To disallow `'0000-00-00'', enable the `NO_ZERO_DATE' SQL 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"'.  File: manual.info, Node: problems-with-null, Next: problems-with-alias, Prev: using-date, Up: query-issues C.5.5.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 *Note 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 *Note `LOAD DATA INFILE': load-data, 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 *Note 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 *Note `TIMESTAMP': datetime. 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.  File: manual.info, Node: problems-with-alias, Next: nontransactional-tables, Prev: problems-with-null, Up: query-issues C.5.5.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';  File: manual.info, Node: nontransactional-tables, Next: deleting-from-related-tables, Prev: problems-with-alias, Up: query-issues C.5.5.5 Rollback Failure for Nontransactional Tables .................................................... If you receive the following message when trying to perform a *Note `ROLLBACK': commit, 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 *Note `ROLLBACK': commit. 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 *Note `mysqld': mysqld. server (or that was disabled with a startup option). If *Note `mysqld': 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 *Note show-table-status::, and *Note show-create-table::. You can check which storage engines your *Note `mysqld': mysqld. server supports by using this statement: SHOW ENGINES; You can also use the following statement, and check the value of the variable that is associated with the storage engine in which you are interested: SHOW VARIABLES LIKE 'have_%'; For example, to determine whether the `InnoDB' storage engine is available, check the value of the `have_innodb' variable. See *Note show-engines::, and *Note show-variables::.  File: manual.info, Node: deleting-from-related-tables, Next: no-matching-rows, Prev: nontransactional-tables, Up: query-issues C.5.5.6 Deleting Rows from Related Tables ......................................... If the total length of the *Note `DELETE': 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 *Note `DELETE': delete. statements. You probably get the fastest *Note `DELETE': 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.  File: manual.info, Node: no-matching-rows, Next: problems-with-float, Prev: deleting-from-related-tables, Up: query-issues C.5.5.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 *Note `EXPLAIN': explain. to check whether you can find something that is obviously wrong. See *Note 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 *Note `SELECT': 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 *Note `FLOAT': floating-point-types. or *Note `DOUBLE': floating-point-types. 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 *Note `FLOAT': floating-point-types. to a *Note `DOUBLE': floating-point-types. fixes this. See *Note 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 *Note `mysqldump --quick db_name TBL_NAME_1 ... TBL_NAME_N > query.sql': mysqldump. Open the file in an editor, remove some insert lines (if there are more than needed to demonstrate the problem), and add your *Note `SELECT': 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 *Note bug-reports::.  File: manual.info, Node: problems-with-float, Prev: no-matching-rows, Up: query-issues C.5.5.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 *Note `FLOAT': floating-point-types. and *Note `DOUBLE': floating-point-types. data types are subject to these issues. For *Note `DECIMAL': fixed-point-types. columns, MySQL performs operations with a precision of 65 decimal digits, which should solve most common inaccuracy problems. The following example uses *Note `DOUBLE': floating-point-types. 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 *Note `DECIMAL': fixed-point-types. rather than *Note `DOUBLE': floating-point-types, the result of the *Note `SELECT': 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 *Note `mysqldump': mysqldump. on the master and reloading the dump file into the slave, tables containing floating-point columns might differ between the two hosts.  File: manual.info, Node: optimizer-issues, Next: table-definition-issues, Prev: query-issues, Up: problems C.5.6 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 *Note `EXPLAIN': explain. statement to get information about how MySQL processes a query. To use it, just add the keyword *Note `EXPLAIN': explain. to the front of your *Note `SELECT': select. statement: mysql> EXPLAIN SELECT * FROM t1, t2 WHERE t1.i = t2.i; *Note `EXPLAIN': explain. is discussed in more detail in *Note explain::. * Use `ANALYZE TABLE TBL_NAME' to update the key distributions for the scanned table. See *Note 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 *Note index-hints::. * Global and table-level `STRAIGHT_JOIN'. See *Note select::. * You can tune global or thread-specific system variables. For example, start *Note `mysqld': 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 *Note server-system-variables::.  File: manual.info, Node: table-definition-issues, Next: bugs, Prev: optimizer-issues, Up: problems C.5.7 Table Definition-Related Issues ------------------------------------- * Menu: * alter-table-problems:: Problems with `ALTER TABLE' * temporary-table-problems:: `TEMPORARY' Table Problems  File: manual.info, Node: alter-table-problems, Next: temporary-table-problems, Prev: table-definition-issues, Up: table-definition-issues C.5.7.1 Problems with `ALTER TABLE' ................................... If you get a duplicate-key error when using *Note `ALTER TABLE': 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 *Note `REPAIR TABLE': repair-table. on the table. If *Note `ALTER TABLE': alter-table. dies with the following error, the problem may be that MySQL crashed during an earlier *Note `ALTER TABLE': 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.) *Note `ALTER TABLE': 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 *Note `ALTER TABLE': alter-table. on a transactional table or if you are using Windows or OS/2, *Note `ALTER TABLE': alter-table. unlocks the table if you had done a *Note `LOCK TABLE': lock-tables. on it. This is done because `InnoDB' and these operating systems cannot drop a table that is in use.  File: manual.info, Node: temporary-table-problems, Prev: alter-table-problems, Up: table-definition-issues C.5.7.2 `TEMPORARY' Table Problems .................................. The following list indicates limitations on the use of `TEMPORARY' tables: * A `TEMPORARY' table can only be of type `MEMORY', `MyISAM', `MERGE', or `InnoDB'. Temporary tables are not supported for MySQL Cluster. * You cannot refer to a `TEMPORARY' table more than once in the same query. For example, the following does not work: mysql> SELECT * FROM temp_table, temp_table AS t2; ERROR 1137: Can't reopen table: 'temp_table' This 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. * The *Note `SHOW TABLES': show-tables. statement does not list `TEMPORARY' tables. * You cannot use `RENAME' to rename a `TEMPORARY' table. However, you can use *Note `ALTER TABLE': alter-table. instead: mysql> ALTER TABLE orig_name RENAME new_name; * There are known issues in using temporary tables with replication. See *Note replication-features::, for more information.  File: manual.info, Node: bugs, Prev: table-definition-issues, Up: problems C.5.8 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 *Note general-installation-issues::, and *Note 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. * *Note `REPLACE': replace. (and *Note `LOAD DATA': load-data. with the *Note `REPLACE': 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. * If one user has a long-running transaction and another user drops a table that is updated in the transaction, there is small chance that the binary log may contain the *Note `DROP TABLE': drop-table. statement before the table is used in the transaction itself. * 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. * *Note `FLUSH TABLES WITH READ LOCK': flush. does not block *Note `COMMIT': commit. if the server is running without binary logging, which may cause a problem (of consistency between tables) when doing a full backup. * *Note `ANALYZE TABLE': analyze-table, *Note `OPTIMIZE TABLE': optimize-table, and *Note `REPAIR TABLE': repair-table. may cause problems on tables for which you are using *Note `INSERT DELAYED': insert-delayed. * Performing `LOCK TABLE ...' and `FLUSH TABLES ...' does not guarantee that there isn't a half-finished transaction in progress on the table. * 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: * *Note `CREATE TABLE ... SELECT': create-table-select. or *Note `INSERT ... SELECT': insert-select. statements that insert zero or `NULL' values into an `AUTO_INCREMENT' column. * *Note `DELETE': delete. if you are deleting rows from a table that has foreign keys with `ON DELETE CASCADE' properties. * *Note `REPLACE ... SELECT': replace, `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 *Note `INSERT ... SELECT': insert-select. with no `ORDER BY', the *Note `SELECT': 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 *Note 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.) * *Note `mysqlbinlog': mysqlbinlog. does not delete temporary files left after a *Note `LOAD DATA INFILE': load-data. statement. See *Note mysqlbinlog::. * `RENAME' does not work with `TEMPORARY' tables or tables used in a `MERGE' table. * Due to the way table format (`.frm') files are stored, you cannot use character 255 (`CHAR(255)') in table names, column names, or enumerations. * 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'. * Only the first `max_sort_length' bytes are used when comparing data values. This means that values cannot reliably be used in `GROUP BY', `ORDER BY' or `DISTINCT' if they are not distinct in 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 *Note `BIGINT': integer-types. or *Note `DOUBLE': floating-point-types. (both are normally 64 bits long). Which precision you get depends on the function. The general rule is that bit functions are performed with *Note `BIGINT': integer-types. precision, `IF()' and `ELT()' with *Note `BIGINT': integer-types. or *Note `DOUBLE': floating-point-types. precision, and the rest with *Note `DOUBLE': floating-point-types. 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 *Note `ENUM': enum. and *Note `SET': set. columns in one table. * In `MIN()', `MAX()', and other aggregate functions, MySQL currently compares *Note `ENUM': enum. and *Note `SET': set. columns by their string value rather than by the string's relative position in the set. * In an *Note `UPDATE': 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, using MySQL Server 3.23.x, 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 *Note `ALTER TABLE': 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 *Note `ALTER TABLE': alter-table. puts `UNIQUE' indexes before normal indexes to be able to detect duplicate keys as early as possible.  File: manual.info, Node: news, Next: restrictions, Prev: error-handling, Up: Top Appendix D MySQL Release Notes ****************************** Release notes for MySQL Server and associated products are no longer published in the MySQL Reference Manual. Instead, see these release notes documents: * MySQL 5.1 Release Notes (http://dev.mysql.com/doc/relnotes/mysql/5.1/en/) * MySQL Cluster 7.1 Release Notes (http://dev.mysql.com/doc/relnotes/mysql-cluster/7.1/en/) * MySQL Connector/ODBC Release Notes (http://dev.mysql.com/doc/relnotes/connector-odbc/en/) * MySQL Connector/Net Release Notes (http://dev.mysql.com/doc/relnotes/connector-net/en/) (includes MySQL Visual Studio Plugin release notes) * MySQL Connector/J Release Notes (http://dev.mysql.com/doc/relnotes/connector-j/en/) * MySQL Connector/C++ Release Notes (http://dev.mysql.com/doc/relnotes/connector-cpp/en/) * MySQL Proxy Release Notes (http://dev.mysql.com/doc/relnotes/mysql-proxy/en/) * MySQL for Excel Release Notes (http://dev.mysql.com/doc/relnotes/mysql-for-excel/en/)  File: manual.info, Node: restrictions, Prev: news, Up: Top Appendix E Restrictions and Limits ********************************** * Menu: * stored-program-restrictions:: Restrictions on Stored Programs * cursor-restrictions:: Restrictions on Server-Side Cursors * subquery-restrictions:: Restrictions on Subqueries * view-restrictions:: Restrictions on Views * xa-restrictions:: Restrictions on XA Transactions * charset-restrictions:: Restrictions on Character Sets * limits:: Limits in MySQL The discussion here describes restrictions that apply to the use of MySQL features such as subqueries or views.  File: manual.info, Node: stored-program-restrictions, Next: cursor-restrictions, Prev: restrictions, Up: restrictions E.1 Restrictions on Stored Programs =================================== These restrictions apply to the features described in *Note 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 *Note `DO': 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 *Note `LOCK TABLES': lock-tables. and *Note `UNLOCK TABLES': lock-tables. * *Note `ALTER VIEW': alter-view. (Before MySQL 5.1.21, this restriction is enforced only for stored functions.) * *Note `LOAD DATA': load-data. and `LOAD TABLE'. * SQL prepared statements (*Note `PREPARE': prepare, *Note `EXECUTE': execute, *Note `DEALLOCATE PREPARE': 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 *Note sql-syntax-prepared-statements::. * 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 *Note prepare::. * Inserts cannot be delayed. *Note `INSERT DELAYED': insert-delayed. syntax is accepted, but the statement is handled as a normal *Note `INSERT': insert. * Within all stored programs (stored procedures and functions, triggers, and events), the parser treats *Note `BEGIN [WORK]': commit. as the beginning of a *Note `BEGIN ... END': begin-end. block. To begin a transaction in this context, use *Note `START TRANSACTION': commit. 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 *Note `FLUSH': 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 *Note `SELECT': select. statements that do not have an `INTO VAR_LIST' clause and other statements such as *Note `SHOW': show, *Note `EXPLAIN': explain, and *Note `CHECK TABLE': check-table. A function can process a result set either with *Note `SELECT ... INTO VAR_LIST': select-into. or by using a cursor and *Note `FETCH': fetch. statements. See *Note select-into::, and *Note cursors::. * *Note `FLUSH': 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. * 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 *Note replication-features-triggers::. * The *Note `RETURN': return. statement is not permitted in triggers, which cannot return a value. To exit a trigger immediately, use the *Note `LEAVE': leave. statement. * Triggers are not permitted on tables in the `mysql' database. * 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. * Restrictions on Calling Stored Procedures * Before MySQL 5.1.4, *Note `CALL': call. statements cannot be prepared, meaning that stored procedures cannot be called from dynamic SQL. This is true both for server-side prepared statements and for SQL prepared statements. * 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 *Note 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. * Introspection Considerations * `INFORMATION_SCHEMA' does not have a `PARAMETERS' table until MySQL 5.5; this table enables stored routines or client applications to determine the names, types, and default values of parameters for stored routines. For releases without this `INFORMATION_SCHEMA.PARAMETERS' table, to examine these types of metadata, you must use workarounds such as parsing the output of `SHOW CREATE' statements or the `param_list' column of the `mysql.proc' table. `param_list' contents can be processed from within a stored routine, unlike the output from *Note `SHOW': show. * 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 *Note stored-programs-logging::. * Event Scheduler Restrictions * The following limitations are specific to the Event Scheduler: * In MySQL 5.1.6 only, any table referenced in an event's action statement must be fully qualified with the name of the schema in which it occurs (that is, as `SCHEMA_NAME.TABLE_NAME'). * Beginning with MySQL 5.1.8, event names are handled in case-insensitive fashion. For example, this means that you cannot have two events in the same database (and--prior to MySQL 5.1.12--with the same definer) with the names `anEvent' and `AnEvent'. *Important*: If you have events created in MySQL 5.1.7 or earlier which are assigned to the same database and have the same definer, and whose names differ only with respect to lettercase, then you must rename these events to respect case-sensitive handling before upgrading to MySQL 5.1.8 or later. * 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) * 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 *Note `INFORMATION_SCHEMA.EVENTS': events-table. 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 *Note `SHOW STATUS': show-status. However, such counts _are_ updated in the global scope. (Bug #16422) * Prior to MySQL 5.1.12, you could not view another user's events in the *Note `INFORMATION_SCHEMA.EVENTS': events-table. table. In other words, any query made against this table was treated as though it contained the condition `DEFINER = CURRENT_USER()' in the `WHERE' clause. * Events do not support times later than the end of the Unix Epoch; this is approximately the beginning of the year 2038. Prior to MySQL 5.1.8, handling in scheduled events of dates later than this was buggy; starting with MySQL 5.1.8, such dates are specifically not permitted by the Event Scheduler. (Bug #16396) * In MySQL 5.1.6, *Note `INFORMATION_SCHEMA.EVENTS': events-table. shows `NULL' in the `SQL_MODE' column. Beginning with MySQL 5.1.7, the `SQL_MODE' displayed is that in effect when the event was created. * In MySQL 5.1.6, the only way to drop or alter an event created by a user who was not the definer of that event was by manipulation of the `mysql.event' system table by the MySQL `root' user or by another user with privileges on this table. Beginning with MySQL 5.1.7, *Note `DROP USER': drop-user. drops all events for which that user was the definer; also beginning with MySQL 5.1.7 *Note `DROP SCHEMA': drop-database. drops all events associated with the dropped schema. * References to stored functions, user-defined functions, and tables in the `ON SCHEDULE' clauses of *Note `CREATE EVENT': create-event. and *Note `ALTER EVENT': alter-event. statements are not supported. Beginning with MySQL 5.1.13, these sorts of references are not permitted. (See Bug #22830 for more information.) * Generally speaking, statements that are not permitted in stored routines or in SQL prepared statements are also not permitted in the body of an event. For more information, see *Note sql-syntax-prepared-statements::. * When upgrading to MySQL 5.1.18 or 5.1.19 from a previous MySQL version where scheduled events were in use, the upgrade utilities *Note `mysql_upgrade': mysql-upgrade. and *Note `mysql_fix_privilege_tables': mysql-fix-privilege-tables. do not accommodate changes in system tables relating to the Event Scheduler. This issue was fixed in MySQL 5.1.20 (see Bug #28521). Stored routines and triggers in MySQL Cluster Stored procedures, stored functions, and triggers are all supported by tables using the *Note `NDB': mysql-cluster. 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 *Note `NDB': mysql-cluster. storage engine, and are not copied between Cluster nodes. Any stored routine or trigger that interacts with MySQL Cluster tables must be re-created by running the appropriate *Note `CREATE PROCEDURE': create-procedure, *Note `CREATE FUNCTION': create-function, or *Note `CREATE TRIGGER': 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 *Note `NDB': mysql-cluster. storage engine. _Altering the system tables in the `mysql' database is not supported_ and is very likely to produce undesirable results.  File: manual.info, Node: cursor-restrictions, Next: subquery-restrictions, Prev: stored-program-restrictions, Up: restrictions E.2 Restrictions on Server-Side Cursors ======================================= Server-side cursors are implemented in the C API using the *Note `mysql_stmt_attr_set()': 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. Note that 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 *Note 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 *Note `CHECK TABLE': check-table, `HANDLER READ', and *Note `SHOW BINLOG EVENTS': show-binlog-events.  File: manual.info, Node: subquery-restrictions, Next: view-restrictions, Prev: cursor-restrictions, Up: restrictions E.3 Restrictions on Subqueries ============================== * In MySQL 5.1 before 5.1.16, if you compare a `NULL' value to a subquery using `ALL', `ANY', or `SOME', and the subquery returns an empty result, the comparison might evaluate to the nonstandard result of `NULL' rather than to `TRUE' or `FALSE'. As of 5.1.16, the comparison evaluates to `TRUE' or `FALSE' except for subqueries inside `IS NULL', such as this: SELECT ... WHERE NULL IN (SELECT ...) IS NULL As of 5.1.32, the `IS NULL' limitation is removed and the comparison evaluates to `TRUE' or `FALSE'. * Subquery optimization for `IN' is not as effective as for the `=' operator or for the `IN(VALUE_LIST)' operator. A typical case for poor `IN' subquery performance is when the subquery returns a small number of rows but the outer query returns a large number of rows to be compared to the subquery result. The problem is that, for a statement that uses an `IN' subquery, the optimizer rewrites it as a correlated subquery. Consider the following statement that uses an uncorrelated subquery: SELECT ... FROM t1 WHERE t1.a IN (SELECT b FROM t2); The optimizer rewrites the statement to a correlated subquery: SELECT ... FROM t1 WHERE EXISTS (SELECT 1 FROM t2 WHERE t2.b = t1.a); If the inner and outer queries return M and N rows, respectively, the execution time becomes on the order of O(MxN), rather than O(M+N) as it would be for an uncorrelated subquery. An implication is that an `IN' subquery can be much slower than a query written using an `IN(VALUE_LIST)' operator that lists the same values that the subquery would return. * 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 you are using a subquery for the modified table in the `FROM' clause. Example: UPDATE t ... WHERE col = (SELECT * FROM (SELECT ... FROM t...) AS _t ...); Here the result from the subquery in the `FROM' clause is stored 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'. * Prior to MySQL 5.1.12, row constructors were not well optimized; of the following two equivalent expressions, only the second could be optimized: (col1, col2, ...) = (val1, val2, ...) col1 = val1 AND col2 = val2 AND ... In MySQL 5.1.12 and later, all row equalities are converted into conjunctions of equalities between row elements, and handled by the optimizer in the same way. (Bug #16081) * Subqueries in the `FROM' clause cannot be correlated subqueries. They are materialized in whole (evaluated to produce a result set) before evaluating the outer query, so they cannot be evaluated per row of the outer query. * 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' * The optimizer is more mature for joins than for subqueries, so in many cases a statement that uses a subquery can be executed more efficiently if you rewrite it as a join. An exception occurs for the case where an `IN' subquery can be rewritten as a *Note `SELECT DISTINCT': select. join. Example: SELECT col FROM t1 WHERE id_col IN (SELECT id_col2 FROM t2 WHERE CONDITION); That statement can be rewritten as follows: SELECT DISTINCT col FROM t1, t2 WHERE t1.id_col = t2.id_col AND CONDITION; But in this case, the join requires an extra `DISTINCT' operation and is not more efficient than the 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 indeterminate 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.  File: manual.info, Node: view-restrictions, Next: xa-restrictions, Prev: subquery-restrictions, Up: restrictions E.4 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). 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 *Note 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 *Note `DROP TABLE': drop-table. or *Note `ALTER TABLE': 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. *Note `CHECK TABLE': check-table. can be used to check for views that have been invalidated by `DROP' or `ALTER' operations. A view definition is `frozen' by certain statements: * If a statement prepared by *Note `PREPARE': prepare. refers to a view, the view definition seen each time the statement is executed later will be the definition of the view at the time it was prepared. This is true even if the view definition is changed after the statement is prepared and before it is executed. Example: CREATE VIEW v AS SELECT RAND(); PREPARE s FROM 'SELECT * FROM v'; ALTER VIEW v AS SELECT NOW(); EXECUTE s; The result returned by the *Note `EXECUTE': execute. statement is a random number, not the current date and time. * If a statement in a stored routine refers to a view, the view definition seen by the statement are its definition the first time that statement is executed. For example, this means that if the statement is executed in a loop, further iterations of the statement see the same view definition, even if the definition is changed later in the loop. Example: CREATE VIEW v AS SELECT 1; delimiter // CREATE PROCEDURE p () BEGIN DECLARE i INT DEFAULT 0; WHILE i < 5 DO SELECT * FROM v; SET i = i + 1; ALTER VIEW v AS SELECT 2; END WHILE; END; // delimiter ; CALL p(); When the procedure `p()' is called, the *Note `SELECT': select. returns 1 each time through the loop, even though the view definition is changed within the loop. As of MySQL 5.1.21, *Note `ALTER VIEW': alter-view. is prohibited within stored routines, so this restriction does not apply. With regard to view updatability, the overall goal for views is that if any view is theoretically updatable, it should be updatable in practice. This includes views that have *Note `UNION': union. in their definition. Currently, not all views that are theoretically updatable can be updated. The initial view implementation was deliberately written this way to get usable, updatable views into MySQL as quickly as possible. Many theoretically updatable views can be updated now, but limitations still exist: * Updatable views with subqueries anywhere other than in the `WHERE' clause. Some views that have subqueries in the *Note `SELECT': select. list may be updatable. * You cannot use *Note `UPDATE': update. to update more than one underlying table of a view that is defined as a join. * You cannot use *Note `DELETE': delete. to update a view that is defined as a join. 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 *Note `SHOW CREATE VIEW': 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 *Note `mysqldump': 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. *Note `SHOW CREATE VIEW': 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. As of MySQL 5.1.23, aliases for column names in *Note `CREATE VIEW': 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 *Note `SHOW CREATE VIEW': 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 *Note `mysqldump': mysqldump. cannot be loaded into servers that enforce the column-length restriction. A workaround for either problem is the 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 *Note `DROP VIEW': drop-view. and *Note `CREATE VIEW': create-view, or replace the definition with *Note `CREATE OR REPLACE VIEW': create-view. For problems that occur when reloading view definitions in dump files, another workaround is to edit the dump file to modify its *Note `CREATE VIEW': create-view. statements. However, this does not change the original view definitions, which may cause problems for subsequent dump operations.  File: manual.info, Node: xa-restrictions, Next: charset-restrictions, Prev: view-restrictions, Up: restrictions E.5 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 *Note `XA START': xa-statements, the `JOIN' and `RESUME' clauses are not supported. For *Note `XA END': xa-statements, 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. If an XA transaction has reached the `PREPARED' state and the MySQL server is killed (for example, with *Note `kill -9': kill. on Unix) or shuts down abnormally, the transaction can be continued after the server restarts. However, if the client reconnects and commits the transaction, the transaction will be absent from the binary log even though it has been committed. This means the data and the binary log have gone out of synchrony. An implication is that XA cannot be used safely together with replication. It is possible that the server will roll back a pending XA transaction, even one that has reached the `PREPARED' state. This happens if a client connection terminates and the server continues to run, or if clients are connected and the server shuts down gracefully. (In the latter case, the server marks each connection to be terminated, and then rolls back the `PREPARED' XA transaction associated with it.) It should be possible to commit or roll back a `PREPARED' XA transaction, but this cannot be done without changes to the binary logging mechanism.  File: manual.info, Node: charset-restrictions, Next: limits, Prev: xa-restrictions, Up: restrictions E.6 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' character sets has the following restrictions: * It cannot be used as a client character set, which means that it does not work for `SET NAMES' or `SET CHARACTER SET'. (See *Note charset-connection::.) * It is currently not possible to use *Note `LOAD DATA INFILE': load-data. to load data files that use this character set. * `FULLTEXT' indexes cannot be created on a column that this character set. However, you can perform `IN BOOLEAN MODE' searches on the column without an index. * The use of `ENCRYPT()' with this character set 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 multi-byte safe and may produce unexpected results with multi-byte 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.  File: manual.info, Node: limits, Prev: charset-restrictions, Up: restrictions E.7 Limits in MySQL =================== * Menu: * joins-limits:: Limits of Joins * database-count-limit:: Limits on Number of Databases and Tables * table-size-limit:: Limits on Table Size * column-count-limit:: Limits on Table Column Count and Row Size * limits-frm-file:: Limits Imposed by `.frm' File Structure * limits-windows:: Windows Platform Limitations This section lists current limits in MySQL 5.1.  File: manual.info, Node: joins-limits, Next: database-count-limit, Prev: limits, Up: limits E.7.1 Limits of Joins --------------------- The maximum number of tables that can be referenced in a single join is 61. This also applies to the number of tables that can be referenced in the definition of a view.  File: manual.info, Node: database-count-limit, Next: table-size-limit, Prev: joins-limits, Up: limits E.7.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.  File: manual.info, Node: table-size-limit, Next: column-count-limit, Prev: database-count-limit, Up: limits E.7.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. The following table lists some examples of operating system file-size limits. This is only a rough guide and is not intended to be definitive. For the most up-to-date information, be sure to check the documentation specific to your operating system. This table lists examples of operating system file-size limits. Operating System File-size Limit Win32 w/ FAT/FAT32 2GB/4GB Win32 w/ NTFS 2TB (possibly larger) Linux 2.2-Intel 32-bit 2GB (LFS: 4GB) Linux 2.4+ (using ext3 file system) 4TB Solaris 9/10 16TB Mac OS X w/ HFS+ 2TB NetWare w/NSS file 8TB system Windows users, please note that FAT and VFAT (FAT32) are _not_ considered suitable for production use with MySQL. Use NTFS instead. On Linux 2.2, you can get `MyISAM' tables larger than 2GB in size by using the Large File Support (LFS) patch for the ext2 file system. Most current Linux distributions are based on kernel 2.4 or higher and include all the required LFS patches. On Linux 2.4, patches also exist for ReiserFS to get support for big files (up to 2TB). With JFS and XFS, petabyte and larger files are possible on Linux. For a detailed overview about LFS in Linux, have a look at Andreas Jaeger's `Large File Support in Linux' page at `http://www.suse.de/~aj/linux_lfs.html'. If you do encounter a full-table error, there are several reasons why it might have occurred: * The disk might be full. * The `InnoDB' storage engine maintains `InnoDB' tables within a tablespace that can be created from several files. This enables a table to exceed the maximum individual file size. The tablespace can include raw disk partitions, which permits extremely large tables. The maximum tablespace size is 64TB. If you are using `InnoDB' tables and run out of room in the `InnoDB' tablespace. In this case, the solution is to extend the `InnoDB' tablespace. See *Note innodb-data-log-reconfiguration::. * 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 *Note `CREATE TABLE': create-table. statement supports `AVG_ROW_LENGTH' and `MAX_ROWS' options. See *Note 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 *Note `ALTER TABLE': alter-table. to increase a table's maximum permissible size. See *Note alter-table::. ALTER TABLE TBL_NAME MAX_ROWS=1000000000 AVG_ROW_LENGTH=NNN; You have to specify `AVG_ROW_LENGTH' only for tables with *Note `BLOB': blob. or *Note `TEXT': blob. 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 *Note `myisamchk -dv /path/to/table-index-file': myisamchk. See *Note show::, or *Note 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 *Note `myisampack': myisampack. to compress it. *Note `myisampack': myisampack. usually compresses a table by at least 50%, so you can have, in effect, much bigger tables. *Note `myisampack': myisampack. also can merge multiple tables into a single table. See *Note 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 *Note merge-storage-engine::. * You are using the *Note `NDB': mysql-cluster. storage engine, in which case you need to increase the values for the `DataMemory' and `IndexMemory' configuration parameters in your `config.ini' file. See *Note mysql-cluster-params-ndbd::. * 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 *Note server-system-variables::.  File: manual.info, Node: column-count-limit, Next: limits-frm-file, Prev: table-size-limit, Up: limits E.7.4 Limits on Table Column Count and Row Size ----------------------------------------------- There is a hard limit of 4096 columns per table, but the effective maximum may be less for a given table. The exact limit depends on several interacting factors. * Every table (regardless of storage engine) has a maximum row size of 65,535 bytes. Storage engines may place additional constraints on this limit, reducing the effective maximum row size. The maximum row size constrains the number (and possibly size) of columns because the total length of all columns cannot exceed this size. For example, `utf8' characters require up to three bytes per character, so for a *Note `CHAR(255) CHARACTER SET utf8': char. column, the server must allocate 255 x 3 = 765 bytes per value. Consequently, a table cannot contain more than 65,535 / 765 = 85 such columns. Storage for variable-length columns includes length bytes, which are assessed against the row size. For example, a *Note `VARCHAR(255) CHARACTER SET utf8': char. column takes two bytes to store the length of the value, so each value can take up to 767 bytes. *Note `BLOB': blob. and *Note `TEXT': blob. columns count from one to four plus eight bytes each toward the row-size limit because their contents are stored separately from the rest of the row. Declaring columns `NULL' can reduce the maximum number of columns permitted. For *Note `MyISAM': myisam-storage-engine. 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 maximum row length in bytes can be calculated as follows: 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. For information about *Note `MyISAM': myisam-storage-engine. table formats, see *Note myisam-table-formats::. For *Note `InnoDB': innodb-storage-engine. tables, storage size is the same for `NULL' and `NOT NULL' columns, so the preceding calculations do not apply. The following 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 = MyISAM CHARACTER SET latin1; Query OK, 0 rows affected (0.02 sec) The following statement to create table `t2' fails because the columns are `NULL' and *Note `MyISAM': myisam-storage-engine. requires additional space that causes the row size to exceed 65,535 bytes: mysql> CREATE TABLE t2 -> (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. You have to change some columns to TEXT or BLOBs The following statement to create table `t3' 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 t3 -> (c1 VARCHAR(65535) NOT 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. You have to change some columns to TEXT or BLOBs Reducing the column length to 65,533 or less permits the statement to succeed. * Individual storage engines might impose additional restrictions that limit table column count. Examples: * *Note `InnoDB': innodb-storage-engine. permits up to 1000 columns. * *Note `InnoDB': innodb-storage-engine. restricts row size to something less than half a database page (approximately 8000 bytes), not including *Note `VARBINARY': binary-varbinary, *Note `VARCHAR': char, *Note `BLOB': blob, or *Note `TEXT': blob. columns. * Different *Note `InnoDB': innodb-storage-engine. storage formats (`COMPRESSED', `REDUNDANT') use different amounts of page header and trailer data, which affects the amount of storage available for rows. * 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. For more information, see *Note limits-frm-file::.  File: manual.info, Node: limits-frm-file, Next: limits-windows, Prev: column-count-limit, Up: limits E.7.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 *Note `ENUM': enum. and *Note `SET': set. columns. In this context, `int' does not mean `integer.' It means `interval,' a term that refers collectively to *Note `ENUM': enum. and *Note `SET': set. columns. * `int_count' is the number of unique *Note `ENUM': enum. and *Note `SET': 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 *Note `ENUM': enum. or *Note `SET': set. columns, or use of column comments. * A table can have no more than 255 unique *Note `ENUM': enum. and *Note `SET': 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 *Note `ENUM': enum. and *Note `SET': set. definitions counts toward the 64KB limit, so although the theoretical limit on number of elements in a given *Note `ENUM': enum. column is 65,535, the practical limit is less than 3000.  File: manual.info, Node: limits-windows, Prev: limits-frm-file, Up: limits E.7.6 Windows Platform Limitations ---------------------------------- The following limitations apply to use of MySQL on the Windows platform: * *Number of file descriptors* The number of open file descriptors on Windows is limited to a maximum of 2048, which may limit the ability to open a large number of tables simultaneously. This limit is due not to Windows but to C runtime library compatibility functions used to open files on Windows that use the POSIX compatibility layer. This limitation will also cause problems if you try to set `open_files_limit' to a value greater than the 2048 file limit. * *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. Note that 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'. * *Concurrent reads* MySQL depends on the `pread()' and `pwrite()' system calls to be able to mix *Note `INSERT': insert. and *Note `SELECT': select. Currently, we use mutexes to emulate `pread()' and `pwrite()'. We intend to replace the file level interface with a virtual interface in the future so that we can use the `readfile()'/`writefile()' interface to get more speed. The current implementation limits the number of open files that MySQL 5.1 can use to 2,048, which means that you cannot run as many concurrent threads on Windows as on Unix. This problem is fixed in MySQL 5.5. * *Blocking read* Before MySQL 5.1.41, MySQL uses a blocking read for each connection. That has the following implications if named-pipe connections are enabled: * A connection is not disconnected automatically after eight hours, as happens with the Unix version of MySQL. * If a connection hangs, it is not possible to break it without killing MySQL. * *Note `mysqladmin kill': mysqladmin. does not work on a sleeping connection. * *Note `mysqladmin shutdown': mysqladmin. cannot abort as long as there are sleeping connections. * **Note `DROP DATABASE': 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 *Note 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 *Note `LOAD DATA INFILE': load-data. * *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 *Note `LOAD DATA INFILE': load-data. or *Note `SELECT ... INTO OUTFILE': select-into, 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. [index] * Menu: * ! (logical NOT): logical-operators. (line 29) * != (not equal): comparison-operators. (line 91) * ": identifiers. (line 20) * #mysql50 identifier prefix <1>: identifier-mapping. (line 96) * #mysql50 identifier prefix: identifiers. (line 108) * %: arithmetic-functions. (line 118) * % (modulo): mathematical-functions. (line 301) * % (wildcard character): string-literals. (line 77) * & (bitwise AND): bit-functions. (line 29) * && (logical AND): logical-operators. (line 48) * () (parentheses): operator-precedence. (line 48) * (Control+Z) \Z <1>: load-data. (line 435) * (Control+Z) \Z: string-literals. (line 75) * * (multiplication): arithmetic-functions. (line 83) * + (addition): arithmetic-functions. (line 55) * - (subtraction): arithmetic-functions. (line 62) * - (unary minus): arithmetic-functions. (line 69) * -? option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 88) * -c option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 114) * -c option (ndb_mgmd) (OBSOLETE): mysql-cluster-programs-ndb-mgmd. (line 215) * -d option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 122) * -d option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 268) * -disable option prefix: option-modifiers. (line 6) * -e option (ndb_mgm): mysql-cluster-programs-ndb-mgm. (line 48) * -enable option prefix: option-modifiers. (line 6) * -f option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 215) * -l option (ndbinfo_select_all): mysql-cluster-programs-ndbinfo-select-all. (line 103) * -loose option prefix: option-modifiers. (line 6) * -maximum option prefix: option-modifiers. (line 6) * -n option (ndbd): mysql-cluster-programs-ndbd. (line 307) * -n option (ndbmtd): mysql-cluster-programs-ndbd. (line 307) * -p option: password-security-user. (line 17) * -P option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 386) * -password option: password-security-user. (line 17) * -skip option prefix: option-modifiers. (line 6) * -V option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 222) * .my.cnf file <1>: access-denied. (line 101) * .my.cnf file <2>: password-security-user. (line 56) * .my.cnf file <3>: multiple-server-clients. (line 34) * .my.cnf file <4>: option-files. (line 6) * .my.cnf file: connecting. (line 224) * .mysql_history file <1>: password-security-user. (line 88) * .mysql_history file: mysql-logging. (line 6) * .NET, and ODBC: connector-odbc-examples-programming-net. (line 11) * .pid (process ID) file: myisam-maintenance-schedule. (line 17) * / (division): arithmetic-functions. (line 92) * /etc/passwd <1>: select-into. (line 47) * /etc/passwd: security-against-attack. (line 84) * := (assignment operator): assignment-operators. (line 15) * := (assignment): user-variables. (line 6) * < (less than): comparison-operators. (line 109) * << (left shift) <1>: bit-functions. (line 51) * << (left shift): calculating-days. (line 6) * <= (less than or equal): comparison-operators. (line 102) * <=> (equal to): comparison-operators. (line 79) * <> (not equal): comparison-operators. (line 91) * = (assignment operator): assignment-operators. (line 70) * = (assignment): user-variables. (line 6) * = (equal): comparison-operators. (line 64) * > (greater than): comparison-operators. (line 123) * >= (greater than or equal): comparison-operators. (line 116) * >> (right shift): bit-functions. (line 63) * [api] (MySQL Cluster): mysql-cluster-params-api. (line 6) * [computer] (MySQL Cluster): mysql-cluster-params-other. (line 6) * [mgm] (MySQL Cluster): mysql-cluster-params-mgmd. (line 6) * [mysqld] (MySQL Cluster): mysql-cluster-params-api. (line 6) * [ndb_mgmd] (MySQL Cluster): mysql-cluster-params-mgmd. (line 6) * [ndbd default] (MySQL Cluster): mysql-cluster-params-ndbd. (line 6) * [ndbd] (MySQL Cluster): mysql-cluster-params-ndbd. (line 6) * [sci] (MySQL Cluster): mysql-cluster-params-other. (line 6) * [shm] (MySQL Cluster): mysql-cluster-params-other. (line 6) * [tcp] (MySQL Cluster): mysql-cluster-params-other. (line 6) * \" (double quote): string-literals. (line 70) * \' (single quote): string-literals. (line 69) * \. (mysql client command) <1>: mysql-batch-commands. (line 6) * \. (mysql client command): batch-mode. (line 90) * \0 (ASCII NUL) <1>: load-data. (line 430) * \0 (ASCII NUL): string-literals. (line 68) * \\ (escape): string-literals. (line 76) * \b (backspace) <1>: load-data. (line 431) * \b (backspace): string-literals. (line 71) * \n (linefeed) <1>: load-data. (line 432) * \n (linefeed): string-literals. (line 72) * \n (newline) <1>: load-data. (line 432) * \n (newline): string-literals. (line 72) * \N (NULL): load-data. (line 436) * \r (carriage return) <1>: load-data. (line 433) * \r (carriage return): string-literals. (line 73) * \t (tab) <1>: load-data. (line 434) * \t (tab): string-literals. (line 74) * \Z (Control+Z) ASCII 26 <1>: load-data. (line 435) * \Z (Control+Z) ASCII 26: string-literals. (line 75) * ^ (bitwise XOR): bit-functions. (line 38) * _ (wildcard character): string-literals. (line 78) * _rowid: create-table. (line 472) * `: identifiers. (line 20) * abort-slave-event-count option, mysqld: replication-options-slave. (line 134) * aborted clients: communication-errors. (line 6) * aborted connection: communication-errors. (line 6) * ABS(): mathematical-functions. (line 52) * access control: connection-access. (line 6) * access denied errors: error-access-denied. (line 6) * access privileges: privilege-system. (line 16) * account names: account-names. (line 6) * accounts, adding privileges: adding-users. (line 6) * accounts, anonymous user: default-privileges. (line 6) * accounts, root: default-privileges. (line 6) * ACID <1>: innodb-storage-engine. (line 22) * ACID: ansi-diff-transactions. (line 6) * ACLs: privilege-system. (line 16) * ACOS(): mathematical-functions. (line 64) * activating plugins: server-plugin-loading. (line 6) * Active Server Pages (ASP): connector-odbc-usagenotes-apptips-microsoft-asp. (line 6) * ActiveState Perl: activestate-perl. (line 6) * adaptive hash index: innodb-adaptive-hash. (line 6) * add-drop-database option, mysqldump: mysqldump. (line 354) * add-drop-table option, mysqldump: mysqldump. (line 363) * add-drop-trigger option, mysqldump: mysqldump. (line 368) * add-locks option, mysqldump: mysqldump. (line 380) * add-user option, mysqlmanager: instance-manager-command-options. (line 27) * ADDDATE(): date-and-time-functions. (line 146) * adding, character sets: adding-character-set. (line 12) * adding, native functions: adding-native-function. (line 6) * adding, new account privileges: adding-users. (line 6) * adding, new functions: adding-functions. (line 12) * adding, new user privileges: adding-users. (line 6) * adding, new users: unix-postinstallation. (line 371) * adding, user-defined functions: adding-udf. (line 15) * addition (+): arithmetic-functions. (line 55) * ADDTIME(): date-and-time-functions. (line 164) * addtodest option, mysqlhotcopy: mysqlhotcopy. (line 85) * administration of MySQL Cluster: mysql-cluster-programs-ndb-mgm. (line 6) * administration, server: mysqladmin. (line 6) * administrative programs: programs-overview. (line 165) * ADO.NET: connector-net-visual-studio-entity-framework. (line 6) * AES_DECRYPT(): encryption-functions. (line 91) * AES_ENCRYPT(): encryption-functions. (line 97) * After create, thread state: general-thread-states. (line 11) * age, calculating: date-calculations. (line 6) * alias names, case sensitivity: identifier-case-sensitivity. (line 6) * aliases, for expressions: group-by-extensions. (line 83) * aliases, for tables: select. (line 162) * aliases, in GROUP BY clauses: group-by-extensions. (line 83) * aliases, names: identifiers. (line 13) * aliases, on expressions: select. (line 108) * ALL <1>: all-subqueries. (line 6) * ALL: select. (line 348) * ALL join type, optimizer: explain-output. (line 385) * all-databases option, mysqlcheck: mysqlcheck. (line 204) * all-databases option, mysqldump: mysqldump. (line 387) * all-in-1 option, mysqlcheck: mysqlcheck. (line 210) * all-tablespaces option, mysqldump: mysqldump. (line 393) * allocating local table, thread state: delayed-insert-thread-states. (line 17) * allow-keywords option, mysqldump: mysqldump. (line 403) * allow-suspicious-udfs option, mysqld: server-options. (line 84) * ALLOW_INVALID_DATES SQL mode: server-sql-mode. (line 114) * allowold option, mysqlhotcopy: mysqlhotcopy. (line 90) * ALTER COLUMN: alter-table. (line 335) * ALTER DATABASE: alter-database. (line 6) * ALTER EVENT: alter-event. (line 6) * ALTER EVENT, and replication: replication-features-invoked. (line 49) * ALTER FUNCTION: alter-function. (line 6) * ALTER LOGFILE GROUP: alter-logfile-group. (line 6) * ALTER PROCEDURE: alter-procedure. (line 6) * ALTER SCHEMA: alter-database. (line 6) * ALTER SERVER: alter-server. (line 6) * ALTER TABLE <1>: alter-table-problems. (line 6) * ALTER TABLE: alter-table. (line 12) * ALTER TABLESPACE: alter-tablespace. (line 6) * ALTER VIEW: alter-view. (line 6) * altering, database: alter-database. (line 6) * altering, schema: alter-database. (line 6) * ANALYSE(), PROCEDURE: procedure-analyse. (line 8) * analyze option, myisamchk: myisamchk-other-options. (line 9) * analyze option, mysqlcheck: mysqlcheck. (line 216) * ANALYZE TABLE: analyze-table. (line 6) * ANALYZE TABLE, and partitioning: partitioning-maintenance. (line 6) * Analyzing, thread state: general-thread-states. (line 18) * AND, bitwise: bit-functions. (line 29) * AND, logical: logical-operators. (line 48) * angel-pid-file option, mysqlmanager: instance-manager-command-options. (line 32) * anonymous user <1>: request-access. (line 26) * anonymous user <2>: connection-access. (line 25) * anonymous user: default-privileges. (line 6) * ANSI mode, running: ansi-mode. (line 6) * ansi option, mysqld: server-options. (line 103) * ANSI SQL mode: server-sql-mode. (line 77) * ANSI_QUOTES SQL mode: server-sql-mode. (line 132) * answering questions, etiquette: mailing-list-use. (line 6) * ANY: any-in-some-subqueries. (line 6) * Apache: apache. (line 6) * API node (MySQL Cluster), defined: mysql-cluster-basics. (line 6) * API nodes: mysql-cluster-mysqld. (line 6) * APIs: connectors-apis. (line 23) * APIs, list of: packages. (line 6) * APIs, Perl: apis-perl. (line 6) * append option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 570) * apply_status table (OBSOLETE): mysql-cluster-replication-schema. (line 131) * approximate-value literals: precision-math. (line 14) * Arbitration: mysql-cluster-ndbd-definition. (line 2483) * ArbitrationDelay <1>: mysql-cluster-api-definition. (line 150) * ArbitrationDelay: mysql-cluster-mgm-definition. (line 217) * ArbitrationRank <1>: mysql-cluster-api-definition. (line 124) * ArbitrationRank: mysql-cluster-mgm-definition. (line 181) * ArbitrationTimeout: mysql-cluster-ndbd-definition. (line 2465) * arbitrator: faqs-mysql-cluster. (line 6) * arbitrator_validity_detail, ndbinfo table: mysql-cluster-ndbinfo-arbitrator-validity-detail. (line 6) * arbitrator_validity_summary, ndbinfo table: mysql-cluster-ndbinfo-arbitrator-validity-summary. (line 6) * ARCHIVE storage engine <1>: archive-storage-engine. (line 6) * ARCHIVE storage engine: storage-engines. (line 23) * Area() <1>: multipolygon-property-functions. (line 8) * Area(): polygon-property-functions. (line 8) * argument processing: udf-arguments. (line 6) * arithmetic expressions: arithmetic-functions. (line 55) * arithmetic functions: bit-functions. (line 6) * AS <1>: join. (line 6) * AS: select. (line 136) * AS/400: i5os-installation. (line 6) * AsBinary(): functions-to-convert-geometries-between-formats. (line 9) * ASCII(): string-functions. (line 105) * ASIN(): mathematical-functions. (line 76) * ASP.NET <1>: connector-net-programming-asp-provider. (line 6) * ASP.NET: connector-net-tutorials. (line 18) * assignment operator, :=: assignment-operators. (line 15) * assignment operator, =: assignment-operators. (line 70) * assignment operators: assignment-operators. (line 6) * AsText(): functions-to-convert-geometries-between-formats. (line 16) * asynchronous replication: mysql-cluster-replication. (line 20) * ATAN(): mathematical-functions. (line 99) * ATAN2(): mathematical-functions. (line 109) * attackers, security against: security-against-attack. (line 6) * attribute demotion, replication: replication-features-different-data-types. (line 6) * attribute promotion, ndb_restore: mysql-cluster-programs-ndb-restore. (line 275) * attribute promotion, replication: replication-features-different-data-types. (line 6) * auto-generate-sql option, mysqlslap: mysqlslap. (line 213) * auto-generate-sql-add-autoincrement option, mysqlslap: mysqlslap. (line 218) * auto-generate-sql-execute-number option, mysqlslap: mysqlslap. (line 223) * auto-generate-sql-guid-primary option, mysqlslap: mysqlslap. (line 228) * auto-generate-sql-load-type option, mysqlslap: mysqlslap. (line 233) * auto-generate-sql-secondary-indexes option, mysqlslap: mysqlslap. (line 241) * auto-generate-sql-unique-query-number option, mysqlslap: mysqlslap. (line 247) * auto-generate-sql-unique-write-number option, mysqlslap: mysqlslap. (line 255) * auto-generate-sql-write-number option, mysqlslap: mysqlslap. (line 261) * AUTO-INCREMENT, ODBC: connector-odbc-usagenotes-functionality-last-insert-id. (line 6) * auto-rehash option, mysql: mysql-command-options. (line 159) * auto-repair option, mysqlcheck: mysqlcheck. (line 220) * AUTO_INCREMENT <1>: numeric-types. (line 15) * AUTO_INCREMENT: example-auto-increment. (line 6) * AUTO_INCREMENT, and NULL values: problems-with-null. (line 71) * AUTO_INCREMENT, and replication: replication-features-auto-increment. (line 6) * auto_increment_increment system variable: replication-options-master. (line 26) * auto_increment_offset system variable: replication-options-master. (line 226) * autoclose option, mysqld_safe: mysqld-safe. (line 125) * autocommit session variable: server-system-variables. (line 590) * automatic_sp_privileges system variable: server-system-variables. (line 628) * AutoReconnect, API and SQL nodes: mysql-cluster-api-definition. (line 270) * AVG(): group-by-functions. (line 59) * AVG(DISTINCT): group-by-functions. (line 59) * B-tree indexes: innodb-physical-structure. (line 6) * back_log system variable: server-system-variables. (line 656) * backslash, escape character: string-literals. (line 6) * backspace (\b) <1>: load-data. (line 431) * backspace (\b): string-literals. (line 71) * backup identifiers, native backup and restore: mysql-cluster-backup-using-management-client. (line 105) * backup option, myisamchk: myisamchk-repair-options. (line 10) * backup option, myisampack: myisampack. (line 51) * BACKUP TABLE: backup-table. (line 6) * backup_path option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 393) * BackupDataBufferSize <1>: mysql-cluster-backup-configuration. (line 8) * BackupDataBufferSize: mysql-cluster-ndbd-definition. (line 2886) * BackupDataDir: mysql-cluster-ndbd-definition. (line 300) * backupid option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 348) * BackupLogBufferSize <1>: mysql-cluster-backup-configuration. (line 13) * BackupLogBufferSize: mysql-cluster-ndbd-definition. (line 2910) * BackupMaxWriteSize <1>: mysql-cluster-backup-configuration. (line 29) * BackupMaxWriteSize: mysql-cluster-ndbd-definition. (line 3005) * BackupMemory <1>: mysql-cluster-backup-configuration. (line 18) * BackupMemory: mysql-cluster-ndbd-definition. (line 2945) * BackupReportFrequency: mysql-cluster-ndbd-definition. (line 2967) * backups <1>: mysql-enterprise-backup. (line 6) * backups: backup-and-recovery. (line 15) * backups, database: backup-table. (line 6) * backups, databases and tables <1>: mysqlhotcopy. (line 6) * backups, databases and tables: mysqldump. (line 6) * backups, in MySQL Cluster <1>: mysql-cluster-backup-configuration. (line 6) * backups, in MySQL Cluster <2>: mysql-cluster-backup-using-management-client. (line 6) * backups, in MySQL Cluster <3>: mysql-cluster-backup-concepts. (line 6) * backups, in MySQL Cluster <4>: mysql-cluster-backup. (line 13) * backups, in MySQL Cluster: mysql-cluster-programs-ndb-restore. (line 6) * backups, in MySQL Cluster replication: mysql-cluster-replication-backups. (line 11) * backups, InnoDB: innodb-backup. (line 12) * backups, troubleshooting, in MySQL Cluster: mysql-cluster-backup-troubleshooting. (line 6) * backups, with mysqldump: using-mysqldump. (line 14) * BackupWriteSize <1>: mysql-cluster-backup-configuration. (line 24) * BackupWriteSize: mysql-cluster-ndbd-definition. (line 2988) * base64-output option, mysqlbinlog: mysqlbinlog. (line 178) * BaseCommandInterceptor class: connector-net-ref-mysqlclient-basecommandinterceptor. (line 6) * basedir option, mysql.server: mysql-server. (line 36) * basedir option, mysql_install_db: mysql-install-db. (line 56) * basedir option, mysql_upgrade: mysql-upgrade. (line 120) * basedir option, mysqld: server-options. (line 116) * basedir option, mysqld_safe: mysqld-safe. (line 137) * basedir system variable: server-system-variables. (line 688) * BaseExceptionInterceptor class: connector-net-ref-mysqlclient-baseexceptioninterceptor. (line 6) * batch mode: batch-mode. (line 6) * batch option, mysql: mysql-command-options. (line 173) * batch SQL files: mysql. (line 15) * BatchByteSize: mysql-cluster-api-definition. (line 164) * batched updates (MySQL Cluster Replication): mysql-cluster-replication-starting. (line 73) * BatchSize: mysql-cluster-api-definition. (line 186) * BatchSizePerLocalScan: mysql-cluster-ndbd-definition. (line 917) * Bazaar tree: installing-development-tree. (line 6) * BdMPolyFromText(): gis-wkt-functions. (line 59) * BdMPolyFromWKB(): gis-wkb-functions. (line 61) * BdPolyFromText(): gis-wkt-functions. (line 65) * BdPolyFromWKB(): gis-wkb-functions. (line 67) * BEGIN <1>: begin-end. (line 6) * BEGIN: commit. (line 6) * BEGIN, labels: statement-labels. (line 6) * BEGIN, XA transactions: xa-statements. (line 6) * BENCHMARK(): information-functions. (line 33) * benchmarks <1>: custom-benchmarks. (line 6) * benchmarks: mysql-benchmarks. (line 6) * BETWEEN ... AND: comparison-operators. (line 195) * big-tables option, mysqld: server-options. (line 136) * big5: faqs-cjk. (line 6) * big_tables session variable: server-system-variables. (line 709) * BIGINT data type: numeric-type-overview. (line 125) * BIN(): string-functions. (line 120) * BINARY: cast-functions. (line 13) * BINARY data type <1>: binary-varbinary. (line 6) * BINARY data type: string-type-overview. (line 151) * binary distributions, installing: binary-installation. (line 6) * binary log: binary-log. (line 13) * binary log, event groups: set-global-sql-slave-skip-counter. (line 6) * binary logging, and MySQL Cluster: mysql-cluster-limitations-exclusive-to-cluster. (line 22) * bind-address option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 96) * bind-address option, mysql: mysql-command-options. (line 183) * bind-address option, mysqladmin: mysqladmin. (line 303) * bind-address option, mysqlbinlog: mysqlbinlog. (line 226) * bind-address option, mysqlcheck: mysqlcheck. (line 225) * bind-address option, mysqld: server-options. (line 158) * bind-address option, mysqldump: mysqldump. (line 408) * bind-address option, mysqlimport: mysqlimport. (line 130) * bind-address option, mysqlmanager: instance-manager-command-options. (line 46) * bind-address option, mysqlshow: mysqlshow. (line 114) * BINLOG: binlog. (line 6) * Binlog Dump, thread command: thread-commands. (line 8) * BINLOG statement, mysqlbinlog output: mysqlbinlog-row-events. (line 6) * binlog-do-db option, mysqld: replication-options-binary-log. (line 198) * binlog-format option, mysqld: server-options. (line 203) * binlog-ignore-db option, mysqld: replication-options-binary-log. (line 323) * binlog-row-event-max-size option, mysqld: replication-options-binary-log. (line 20) * binlog_cache_size system variable: replication-options-binary-log. (line 438) * binlog_direct_non_transactional_updates system variable: replication-options-binary-log. (line 476) * binlog_format system variable: replication-options-binary-log. (line 530) * binlog_format, BLACKHOLE: replication-features-blackhole. (line 6) * binlog_index table (OBSOLETE): mysql-cluster-replication-schema. (line 6) * BIT data type: numeric-type-overview. (line 35) * bit functions: bit-functions. (line 6) * bit functions, example: calculating-days. (line 6) * BIT_AND(): group-by-functions. (line 70) * BIT_COUNT: calculating-days. (line 6) * BIT_COUNT(): bit-functions. (line 84) * BIT_LENGTH(): string-functions. (line 129) * BIT_OR: calculating-days. (line 6) * BIT_OR(): group-by-functions. (line 79) * BIT_XOR(): group-by-functions. (line 86) * BLACKHOLE storage engine <1>: blackhole-storage-engine. (line 6) * BLACKHOLE storage engine: storage-engines. (line 23) * BLACKHOLE, binlog_format: replication-features-blackhole. (line 6) * BLACKHOLE, replication: replication-features-blackhole. (line 6) * BLOB columns, default values: blob. (line 52) * BLOB columns, indexing <1>: create-table. (line 524) * BLOB columns, indexing: column-indexes. (line 15) * BLOB columns, with Connector/Net: connector-net-programming-blob. (line 12) * BLOB data type <1>: blob. (line 6) * BLOB data type: string-type-overview. (line 180) * BLOB, inserting binary data: string-literals. (line 141) * BLOB, size: storage-requirements. (line 190) * blob-info option, ndb_desc: mysql-cluster-programs-ndb-desc. (line 282) * Block Nested-Loop join algorithm: nested-loop-joins. (line 6) * block-search option, myisamchk: myisamchk-other-options. (line 18) * blocks, ndbinfo table: mysql-cluster-ndbinfo-blocks. (line 6) * BOOL data type: numeric-type-overview. (line 45) * BOOLEAN data type: numeric-type-overview. (line 45) * boolean options: option-modifiers. (line 6) * bootstrap option, mysqld: server-options. (line 280) * Borland applications: connector-odbc-usagenotes-apptips-borland. (line 12) * Boundary(): general-geometry-property-functions. (line 70) * brackets, square: data-types. (line 43) * brief option, mysqlaccess: mysqlaccess. (line 71) * buffer pool: innodb-buffer-pool. (line 6) * buffer sizes: innodb-buffer-pool. (line 6) * buffer sizes, client: connectors-apis. (line 23) * buffer sizes, mysqld server: server-parameters. (line 6) * Buffer(): spatial-operators. (line 11) * bugs database: bug-reports. (line 6) * bugs, known: bugs. (line 6) * bugs, MySQL Cluster, reporting: mysql-cluster-programs-ndb-error-reporter. (line 6) * bugs, reporting <1>: bug-reports. (line 6) * bugs, reporting: introduction. (line 69) * bugs.mysql.com: bug-reports. (line 6) * BuildIndexThreads: mysql-cluster-ndbd-definition. (line 3157) * building, client programs: c-api-building-clients. (line 6) * bulk loading, with Connector/Net: connector-net-programming-bulk-loader. (line 6) * bulk_insert_buffer_size system variable: server-system-variables. (line 724) * C API: connectors-apis. (line 23) * C API, data types: c-api. (line 28) * C API, example programs: c-api-example-programs. (line 6) * C API, functions: c-api-function-overview. (line 6) * C API, linking problems: c-api-building-clients. (line 79) * C prepared statement API, functions <1>: c-api-prepared-statement-function-overview. (line 6) * C prepared statement API, functions: c-api-prepared-statement-type-conversions. (line 6) * C prepared statement API, type codes: c-api-prepared-statement-type-codes. (line 6) * C# <1>: connector-net-ref. (line 11) * C#: connector-net-tutorials-intro. (line 14) * C++ Builder: connector-odbc-usagenotes-apptips-borland-cppbuilder. (line 6) * C++ compiler cannot create executables: compilation-problems. (line 62) * C++ compiler, gcc: source-configuration-options. (line 397) * C:\my.cnf file: multiple-server-clients. (line 34) * CACHE INDEX: cache-index. (line 6) * CACHE INDEX, and partitioning: partitioning-limitations. (line 400) * caches, clearing: flush. (line 6) * calculating, aggregate value for a set of rows: group-by-functions. (line 6) * calculating, cardinality: show-index. (line 42) * calculating, dates: date-calculations. (line 6) * calendar: mysql-calendar. (line 6) * CALL: call. (line 6) * calling sequences for aggregate functions, UDF: udf-aggr-calling. (line 6) * calling sequences for simple functions, UDF: udf-calling. (line 6) * can't create/write to file: cannot-create. (line 6) * cardinality: how-to-avoid-table-scan. (line 6) * carriage return (\r) <1>: load-data. (line 433) * carriage return (\r): string-literals. (line 73) * CASE <1>: case. (line 6) * CASE: control-flow-functions. (line 14) * case sensitivity, in access checking: grant-table-structure. (line 257) * case sensitivity, in identifiers: identifier-case-sensitivity. (line 6) * case sensitivity, in names: identifier-case-sensitivity. (line 6) * case sensitivity, in searches: case-sensitivity. (line 6) * case sensitivity, in string comparisons: string-comparison-functions. (line 17) * case sensitivity, of database names: extensions-to-ansi. (line 38) * case sensitivity, of replication filtering options: replication-rules. (line 56) * case sensitivity, of table names: extensions-to-ansi. (line 38) * CAST: cast-functions. (line 39) * cast functions: cast-functions. (line 6) * cast operators: cast-functions. (line 6) * casts <1>: cast-functions. (line 6) * casts <2>: comparison-operators. (line 38) * casts: type-conversion. (line 6) * CC environment variable <1>: environment-variables. (line 18) * CC environment variable <2>: compilation-problems. (line 88) * CC environment variable: source-configuration-options. (line 397) * cc1plus problems: compilation-problems. (line 37) * CEIL(): mathematical-functions. (line 121) * CEILING(): mathematical-functions. (line 125) * Centroid(): multipolygon-property-functions. (line 23) * certificate file: connector-net-connection-options. (line 6) * CFLAGS environment variable <1>: environment-variables. (line 18) * CFLAGS environment variable: compilation-problems. (line 88) * cflags option, mysql_config: mysql-config. (line 13) * CHANGE MASTER TO: change-master-to. (line 6) * CHANGE MASTER TO, in MySQL Cluster: mysql-cluster-replication-preparation. (line 37) * Change user, thread command: thread-commands. (line 13) * ChangeLog: news. (line 6) * changes to privileges: privilege-changes. (line 6) * changes, release notes: news. (line 6) * Changing master, thread state: slave-connection-thread-states. (line 9) * changing socket location: source-configuration-options. (line 377) * changing, column: alter-table. (line 335) * changing, field: alter-table. (line 335) * changing, socket location <1>: problems-with-mysql-sock. (line 26) * changing, socket location: automatic-start. (line 134) * changing, table <1>: alter-table-problems. (line 6) * changing, table: alter-table. (line 12) * CHAR data type <1>: string-types. (line 14) * CHAR data type: string-type-overview. (line 89) * CHAR VARYING data type: string-type-overview. (line 121) * CHAR(): string-functions. (line 136) * CHAR_LENGTH(): string-functions. (line 178) * CHARACTER data type: string-type-overview. (line 89) * character sets <1>: charset. (line 22) * character sets: source-configuration-options. (line 434) * character sets, adding: adding-character-set. (line 12) * character sets, and MySQL Cluster (replication): mysql-cluster-replication-issues. (line 67) * character sets, and replication: replication-features-charset. (line 6) * character sets, repertoire: charset-repertoire. (line 6) * character sets, restrictions: charset-restrictions. (line 6) * character sets, with Connector/J: connector-j-reference-charsets. (line 6) * character sets, with Connector/Net: connector-net-using-character-sets. (line 6) * CHARACTER VARYING data type: string-type-overview. (line 121) * character-set-client-handshake option, mysqld: server-options. (line 315) * character-set-filesystem option, mysqld: server-options. (line 332) * character-set-server option, mysqld: server-options. (line 353) * character-sets-dir option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 100) * character-sets-dir option, myisamchk: myisamchk-repair-options. (line 14) * character-sets-dir option, myisampack: myisampack. (line 56) * character-sets-dir option, mysql: mysql-command-options. (line 194) * character-sets-dir option, mysqladmin: mysqladmin. (line 314) * character-sets-dir option, mysqlbinlog: mysqlbinlog. (line 237) * character-sets-dir option, mysqlcheck: mysqlcheck. (line 236) * character-sets-dir option, mysqld: server-options. (line 296) * character-sets-dir option, mysqldump: mysqldump. (line 419) * character-sets-dir option, mysqlimport: mysqlimport. (line 141) * character-sets-dir option, mysqlshow: mysqlshow. (line 125) * CHARACTER_LENGTH(): string-functions. (line 185) * character_set_client system variable: server-system-variables. (line 758) * character_set_connection system variable: server-system-variables. (line 797) * character_set_database system variable: server-system-variables. (line 814) * character_set_filesystem system variable: server-system-variables. (line 854) * character_set_results system variable: server-system-variables. (line 884) * character_set_server system variable: server-system-variables. (line 900) * character_set_system system variable: server-system-variables. (line 918) * CHARACTER_SETS, INFORMATION_SCHEMA table: character-sets-table. (line 6) * character_sets_dir system variable: server-system-variables. (line 933) * characters, multi-byte: multi-byte-characters. (line 6) * charset command, mysql: mysql-commands. (line 61) * charset option, comp_err: comp-err. (line 29) * CHARSET(): information-functions. (line 79) * check option, myisamchk: myisamchk-check-options. (line 9) * check option, mysqlcheck: mysqlcheck. (line 241) * check options, myisamchk: myisamchk-check-options. (line 6) * CHECK TABLE: check-table. (line 6) * CHECK TABLE, and partitioning: partitioning-maintenance. (line 6) * check-only-changed option, myisamchk: myisamchk-check-options. (line 14) * check-only-changed option, mysqlcheck: mysqlcheck. (line 245) * check-orphans option, ndb_blob_tool: mysql-cluster-programs-ndb-blob-tool. (line 65) * check-password-file option, mysqlmanager: instance-manager-command-options. (line 50) * check-upgrade option, mysqlcheck: mysqlcheck. (line 250) * Checking master version, thread state: slave-io-thread-states. (line 20) * checking permissions, thread state: general-thread-states. (line 23) * checking privileges on cached query, thread state: query-cache-thread-states. (line 9) * checking query cache for query, thread state: query-cache-thread-states. (line 14) * Checking table, thread state: general-thread-states. (line 28) * checking, tables for errors: myisam-check. (line 6) * CHECKPOINT Events (MySQL Cluster): mysql-cluster-log-events. (line 39) * checkpoint option, mysqlhotcopy: mysqlhotcopy. (line 95) * Checksum: mysql-cluster-tcp-definition. (line 153) * Checksum (MySQL Cluster) <1>: mysql-cluster-sci-definition. (line 169) * Checksum (MySQL Cluster): mysql-cluster-shm-definition. (line 114) * checksum errors: solaris-installation. (line 11) * CHECKSUM TABLE: checksum-table. (line 6) * Chinese, Japanese, Korean character sets, frequently asked questions: faqs-cjk. (line 6) * choosing, a MySQL version: which-version. (line 18) * choosing, data types: choosing-types. (line 6) * chroot option, mysqld: server-options. (line 374) * chroot option, mysqlhotcopy: mysqlhotcopy. (line 100) * circular replication, in MySQL Cluster <1>: mysql-cluster-replication-conflict-resolution. (line 6) * circular replication, in MySQL Cluster <2>: mysql-cluster-replication-multi-master. (line 6) * circular replication, in MySQL Cluster: mysql-cluster-replication-issues. (line 74) * CJK (Chinese, Japanese, Korean), Access, PHP, etc.: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), availability of specific characters: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), big5: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), character sets available: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), characters displayed as question marks: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), CJKV: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), collations: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), conversion problems with Japanese character sets: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), data truncation: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), Database and table names: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), documentation in Chinese: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), documentation in Japanese: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), documentation in Korean: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), FAQ: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), gb2312, gbk: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), Japanese character sets: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), Korean character set: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), LIKE and FULLTEXT: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), MySQL 4.0 behavior: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), ORDER BY treatment: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), problems with Access, PHP, etc.: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), problems with Big5 character sets (Chinese): faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), problems with data truncation: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), problems with euckr character set (Korean): faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), problems with GB character sets (Chinese): faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), problems with LIKE and FULLTEXT: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), problems with Yen sign (Japanese): faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), rejected characters: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), sort order problems: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), sorting problems: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), testing availability of characters: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), Unicode collations: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), Vietnamese: faqs-cjk. (line 6) * CJK (Chinese, Japanese, Korean), Yen sign: faqs-cjk. (line 6) * clean-password-file option, mysqlmanager: instance-manager-command-options. (line 55) * cleaning up, thread state: general-thread-states. (line 32) * clear command, mysql: mysql-commands. (line 70) * clearing, caches: flush. (line 6) * Clearing, thread state: event-scheduler-thread-states. (line 10) * client connection threads: connection-threads. (line 6) * client programs: programs-overview. (line 124) * client programs, building: c-api-building-clients. (line 6) * client tools: connectors-apis. (line 23) * clients, debugging: debugging-client. (line 6) * clients, threaded: c-api-threaded-clients. (line 6) * CLOSE: close. (line 6) * Close stmt, thread command: thread-commands. (line 17) * closing tables, thread state: general-thread-states. (line 37) * closing, tables: table-cache. (line 6) * cluster database (OBSOLETE): mysql-cluster-replication-schema. (line 6) * cluster logs <1>: mysql-cluster-logging-management-commands. (line 6) * cluster logs: mysql-cluster-event-reports. (line 12) * cluster.binlog_index table (OBSOLETE): mysql-cluster-replication-schema. (line 6) * cluster_operations, ndbinfo table: mysql-cluster-ndbinfo-cluster-operations. (line 6) * cluster_replication database (OBSOLETE): mysql-cluster-replication-schema. (line 6) * cluster_transactions, ndbinfo table: mysql-cluster-ndbinfo-cluster-transactions. (line 6) * clustered index, InnoDB: innodb-index-types. (line 6) * Clustering: mysql-cluster. (line 16) * CLUSTERLOG commands (MySQL Cluster): mysql-cluster-logging-management-commands. (line 12) * CLUSTERLOG STATISTICS command (MySQL Cluster): mysql-cluster-log-statistics. (line 6) * CMake: windows-source-build. (line 6) * COALESCE(): comparison-operators. (line 227) * COERCIBILITY(): information-functions. (line 90) * ColdFusion: connector-odbc-usagenotes-apptips-coldfusion. (line 6) * collating, strings: string-collating. (line 6) * COLLATION(): information-functions. (line 119) * collation, adding: adding-collation. (line 13) * collation, INFORMATION_SCHEMA: charset-collation-information-schema. (line 6) * collation, modifying: adding-collation. (line 59) * collation, names: charset-collation-names. (line 6) * collation-server option, mysqld: server-options. (line 394) * COLLATION_CHARACTER_SET_APPLICABILITY, INFORMATION_SCHEMA table: collation-character-set-applicability-table. (line 6) * collation_connection system variable: server-system-variables. (line 951) * collation_database system variable: server-system-variables. (line 966) * collation_server system variable: server-system-variables. (line 1006) * COLLATIONS, INFORMATION_SCHEMA table: collations-table. (line 6) * column alias, problems: problems-with-alias. (line 6) * column alias, quoting <1>: problems-with-alias. (line 6) * column alias, quoting: identifiers. (line 81) * column comments: create-table. (line 379) * Column Editor: connector-net-visual-studio-editing-tables-column-editor. (line 6) * column format: create-table. (line 384) * column names, case sensitivity: identifier-case-sensitivity. (line 6) * column storage: create-table. (line 404) * column, changing: alter-table. (line 335) * column, types: data-types. (line 31) * column-names option, mysql: mysql-command-options. (line 199) * column-type-info option, mysql: mysql-command-options. (line 203) * COLUMN_PRIVILEGES, INFORMATION_SCHEMA table: column-privileges-table. (line 6) * columns option, mysqlimport: mysqlimport. (line 146) * columns per table, maximum: column-count-limit. (line 6) * columns, displaying: mysqlshow. (line 6) * columns, indexes: column-indexes. (line 6) * COLUMNS, INFORMATION_SCHEMA table: columns-table. (line 6) * columns, names: identifiers. (line 13) * columns, other types: other-vendor-data-types. (line 6) * columns, selecting: selecting-columns. (line 6) * columns, storage requirements: storage-requirements. (line 6) * comma-separated values data, reading <1>: select-into. (line 117) * comma-separated values data, reading: load-data. (line 327) * command options (MySQL Cluster), mysqld: mysql-cluster-program-options-mysqld. (line 6) * command options (MySQL Cluster), ndb_mgm: mysql-cluster-programs-ndb-mgm. (line 27) * command options (MySQL Cluster), ndb_mgmd: mysql-cluster-programs-ndb-mgmd. (line 12) * command options (MySQL Cluster), ndbd: mysql-cluster-programs-ndbd. (line 17) * command options (MySQL Cluster), ndbinfo_select_all: mysql-cluster-programs-ndbinfo-select-all. (line 59) * command options, mysql: mysql-command-options. (line 6) * command options, mysqladmin: mysqladmin. (line 213) * command options, mysqld: server-options. (line 6) * command syntax: manual-conventions. (line 120) * command-line history, mysql: mysql-logging. (line 6) * command-line options (MySQL Cluster): mysql-cluster-program-options-common. (line 6) * command-line tool: mysql. (line 15) * commands out of sync: commands-out-of-sync. (line 6) * commands, for binary distribution: binary-installation. (line 78) * comment syntax: comments. (line 6) * comments option, mysql: mysql-command-options. (line 209) * comments option, mysqldump: mysqldump. (line 424) * comments, adding: comments. (line 6) * comments, starting: ansi-diff-comments. (line 6) * COMMIT <1>: commit. (line 6) * COMMIT: ansi-diff-transactions. (line 6) * commit option, mysqlaccess: mysqlaccess. (line 75) * commit option, mysqlslap: mysqlslap. (line 266) * COMMIT, XA transactions: xa-statements. (line 6) * Committing events to binlog, thread state: mysql-cluster-thread-states. (line 6) * comp_err <1>: comp-err. (line 6) * comp_err: programs-overview. (line 68) * comp_err, charset option: comp-err. (line 29) * comp_err, debug option: comp-err. (line 34) * comp_err, debug-info option: comp-err. (line 39) * comp_err, header_file option: comp-err. (line 43) * comp_err, help option: comp-err. (line 25) * comp_err, in_file option: comp-err. (line 47) * comp_err, name_file option: comp-err. (line 52) * comp_err, out_dir option: comp-err. (line 56) * comp_err, out_file option: comp-err. (line 61) * comp_err, statefile option: comp-err. (line 65) * comp_err, version option: comp-err. (line 70) * compact option, mysqldump: mysqldump. (line 431) * comparison operators: comparison-operators. (line 6) * compatibility, between MySQL versions: upgrading-from-previous-series. (line 6) * compatibility, with mSQL: regexp. (line 32) * compatibility, with ODBC <1>: join. (line 147) * compatibility, with ODBC <2>: create-table. (line 301) * compatibility, with ODBC <3>: comparison-operators. (line 153) * compatibility, with ODBC <4>: type-conversion. (line 44) * compatibility, with ODBC <5>: numeric-type-overview. (line 255) * compatibility, with ODBC <6>: identifier-qualifiers. (line 48) * compatibility, with ODBC: server-system-variables. (line 5117) * compatibility, with Oracle <1>: explain. (line 53) * compatibility, with Oracle <2>: alter-table. (line 299) * compatibility, with Oracle <3>: group-by-functions. (line 240) * compatibility, with Oracle: extensions-to-ansi. (line 99) * compatibility, with PostgreSQL: extensions-to-ansi. (line 193) * compatibility, with standard SQL: compatibility. (line 15) * compatible option, mysqldump: mysqldump. (line 446) * compiler, C++ gcc: source-configuration-options. (line 397) * compiling clients, on Unix: c-api-building-clients. (line 11) * compiling clients, on Windows: c-api-building-clients. (line 48) * compiling, optimizing: system-optimization. (line 6) * compiling, problems: compilation-problems. (line 6) * compiling, speed: compile-and-link-options. (line 6) * compiling, statically: source-configuration-options. (line 389) * compiling, user-defined functions: udf-compiling. (line 6) * complete-insert option, mysqldump: mysqldump. (line 466) * completion_type system variable: server-system-variables. (line 1024) * composite partitioning: partitioning-subpartitions. (line 26) * compound statements: sql-syntax-compound-statements. (line 16) * compress option, mysql: mysql-command-options. (line 216) * compress option, mysqladmin: mysqladmin. (line 319) * compress option, mysqlcheck: mysqlcheck. (line 258) * compress option, mysqldump: mysqldump. (line 471) * compress option, mysqlimport: mysqlimport. (line 152) * compress option, mysqlshow: mysqlshow. (line 130) * compress option, mysqlslap: mysqlslap. (line 271) * COMPRESS(): encryption-functions. (line 143) * compressed tables <1>: compressed-format. (line 6) * compressed tables: myisampack. (line 6) * CompressedBackup: mysql-cluster-ndbd-definition. (line 1681) * CompressedLCP: mysql-cluster-ndbd-definition. (line 1707) * compression, with Connector/Net network traffic: connector-net-connection-options. (line 6) * CONCAT(): string-functions. (line 189) * CONCAT_WS(): string-functions. (line 216) * concatenation, string <1>: string-functions. (line 189) * concatenation, string: string-literals. (line 12) * concurrency: innodb-storage-engine. (line 22) * concurrency option, mysqlslap: mysqlslap. (line 276) * concurrency, of commits: innodb-parameters. (line 532) * concurrency, of threads: innodb-parameters. (line 1963) * concurrency, tickets: innodb-parameters. (line 558) * concurrent inserts <1>: concurrent-inserts. (line 6) * concurrent inserts: internal-locking. (line 68) * concurrent_insert system variable: server-system-variables. (line 1073) * conditions <1>: show-warnings. (line 6) * conditions: show-errors. (line 6) * Conditions: declare-condition. (line 6) * config-cache option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 152) * config-file option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 215) * config-file option, my_print_defaults: my-print-defaults. (line 29) * config-file option, mysqld_multi: mysqld-multi. (line 100) * config-file option, ndb_config: mysql-cluster-programs-ndb-config. (line 165) * config.cache: compilation-problems. (line 14) * config.cache file: compilation-problems. (line 6) * config.ini (MySQL Cluster) <1>: mysql-cluster-programs-ndb-mgmd. (line 582) * config.ini (MySQL Cluster) <2>: mysql-cluster-config-example. (line 6) * config.ini (MySQL Cluster) <3>: mysql-cluster-config-file. (line 22) * config.ini (MySQL Cluster): mysql-cluster-install-configuration. (line 6) * config_from_node option, ndb_config: mysql-cluster-programs-ndb-config. (line 107) * config_params, ndbinfo table: mysql-cluster-ndbinfo-config-params. (line 6) * configdir option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 134) * configinfo option, ndb_config: mysql-cluster-programs-ndb-config. (line 382) * configuration files: access-denied. (line 101) * configuration options: source-configuration-options. (line 6) * configuration, MySQL Cluster: mysql-cluster-params-overview. (line 13) * configure option, -with-low-memory: compilation-problems. (line 37) * configure script: source-configuration-options. (line 6) * configure, disable-grant-options option: source-configuration-options. (line 537) * configure, enable-community-features option: source-configuration-options. (line 544) * configure, enable-debug-sync option: source-configuration-options. (line 492) * configure, enable-profiling option: source-configuration-options. (line 550) * configure, enable-thread-safe-client option: source-configuration-options. (line 512) * configure, localstatedir option: source-configuration-options. (line 349) * configure, prefix option: source-configuration-options. (line 349) * configure, running after prior invocation: compilation-problems. (line 14) * configure, with-big-tables option: source-configuration-options. (line 527) * configure, with-charset option: source-configuration-options. (line 434) * configure, with-client-ldflags option: source-configuration-options. (line 389) * configure, with-collation option: source-configuration-options. (line 434) * configure, with-debug option: source-configuration-options. (line 476) * configure, with-embedded-server option: source-configuration-options. (line 346) * configure, with-extra-charsets option: source-configuration-options. (line 434) * configure, with-tcp-port option: source-configuration-options. (line 370) * configure, with-unix-socket-path option: source-configuration-options. (line 377) * configure, with-zlib-dir option: source-configuration-options. (line 518) * configure, without-server option: source-configuration-options. (line 332) * configuring backups, in MySQL Cluster: mysql-cluster-backup-configuration. (line 6) * configuring MySQL Cluster <1>: mysql-cluster-mysqld. (line 49) * configuring MySQL Cluster <2>: mysql-cluster-programs-ndb-mgmd. (line 582) * configuring MySQL Cluster <3>: mysql-cluster-configuration. (line 14) * configuring MySQL Cluster: mysql-cluster-installation. (line 16) * Configuring MySQL Cluster (concepts): mysql-cluster-basics. (line 6) * conflict resolution, and ndb_replication system table: mysql-cluster-replication-conflict-resolution. (line 160) * conflict resolution, enabling: mysql-cluster-replication-conflict-resolution. (line 152) * conflict resolution, in MySQL Cluster Replication: mysql-cluster-replication-conflict-resolution. (line 6) * conflict resolution, mysqld startup options: mysql-cluster-replication-conflict-resolution. (line 94) * connect command, mysql: mysql-commands. (line 75) * Connect Out, thread command: thread-commands. (line 25) * Connect, thread command: thread-commands. (line 21) * connect-delay option (ndbd): mysql-cluster-programs-ndbd. (line 411) * connect-delay option (ndbmtd): mysql-cluster-programs-ndbd. (line 411) * connect-retries option (ndbd): mysql-cluster-programs-ndbd. (line 388) * connect-retries option (ndbmtd): mysql-cluster-programs-ndbd. (line 388) * connect-string option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 114) * connect_timeout system variable: server-system-variables. (line 1113) * connect_timeout variable <1>: mysqladmin. (line 447) * connect_timeout variable: mysql-command-options. (line 614) * ConnectCheckIntervalDelay: mysql-cluster-ndbd-definition. (line 2025) * Connecting to master, thread state: slave-io-thread-states. (line 16) * connecting, remotely with SSH: windows-and-ssh. (line 6) * connecting, through Connector/Net: connector-net-programming-connecting. (line 6) * connecting, through JDBC and Connector/J: connector-j-reference-configuration-properties. (line 10) * connecting, through Visual Studio: connector-net-visual-studio-making-a-connection. (line 6) * connecting, to the server <1>: connecting. (line 6) * connecting, to the server: connecting-disconnecting. (line 6) * connecting, verification: connection-access. (line 6) * CONNECTION Events (MySQL Cluster): mysql-cluster-log-events. (line 20) * connection pooling <1>: connector-j-usagenotes-glassfish-config. (line 11) * connection pooling <2>: connector-j-usagenotes-spring-config-connpooling. (line 6) * connection pooling <3>: connector-j-usagenotes-j2ee-concepts-connection-pooling. (line 6) * connection pooling <4>: connector-net-connection-options. (line 6) * connection pooling: connector-net-programming-connection-pooling. (line 6) * connection string <1>: connector-net-connection-options. (line 6) * connection string <2>: connector-net-programming-connecting-connection-string. (line 12) * connection string: mysql-cluster-connection-strings. (line 6) * connection, aborted: communication-errors. (line 6) * CONNECTION_ID(): information-functions. (line 128) * connections option, ndb_config: mysql-cluster-programs-ndb-config. (line 288) * Connector/C <1>: connector-c. (line 14) * Connector/C: connectors-apis. (line 23) * Connector/C++ <1>: connector-cpp. (line 20) * Connector/C++: connectors-apis. (line 23) * Connector/J <1>: connector-j. (line 26) * Connector/J: connectors-apis. (line 23) * Connector/J, known issues: connector-j-usagenotes-known-issues-limitations. (line 6) * Connector/J, limitations: connector-j-usagenotes-known-issues-limitations. (line 6) * Connector/J, reporting problems: connector-j-support-bug-report. (line 6) * Connector/J, troubleshooting: connector-j-usagenotes-troubleshooting. (line 6) * Connector/Net <1>: connector-net. (line 20) * Connector/Net: connectors-apis. (line 23) * Connector/Net, reporting problems: connector-net-support. (line 11) * Connector/ODBC <1>: connector-odbc. (line 17) * Connector/ODBC: connectors-apis. (line 23) * Connector/ODBC, reporting problems: connector-odbc-support. (line 12) * Connector/ODBC, with Borland applications: connector-odbc-usagenotes-apptips-borland. (line 12) * Connector/Python <1>: connector-python. (line 17) * Connector/Python: connectors-apis. (line 23) * Connectors: connectors-apis. (line 23) * consistent reads: innodb-consistent-read. (line 6) * console option, mysqld: server-options. (line 413) * const table, optimizer <1>: select. (line 372) * const table, optimizer: explain-output. (line 240) * constant table: where-optimizations. (line 50) * constraints: constraints. (line 13) * constraints, foreign keys: create-table-foreign-keys. (line 6) * CONSTRAINTS, INFORMATION_SCHEMA table: table-constraints-table. (line 6) * Contains(): functions-that-test-spatial-relationships-between-geometries. (line 17) * contributing companies, list of: supporters. (line 6) * contributors, list of: contributors. (line 6) * control flow functions: control-flow-functions. (line 6) * CONV(): mathematical-functions. (line 138) * conventions, syntax: manual-conventions. (line 8) * conventions, typographical: manual-conventions. (line 8) * CONVERT: cast-functions. (line 45) * CONVERT TO: alter-table. (line 504) * CONVERT_TZ(): date-and-time-functions. (line 174) * converting HEAP to MyISAM, thread state: general-thread-states. (line 44) * ConvexHull(): spatial-operators. (line 16) * copy option, mysqlaccess: mysqlaccess. (line 82) * copy to tmp table, thread state: general-thread-states. (line 49) * copying databases: copying-databases. (line 6) * copying tables <1>: create-table-select. (line 6) * copying tables: create-table. (line 1320) * Copying to group table, thread state: general-thread-states. (line 55) * Copying to tmp table on disk, thread state: general-thread-states. (line 64) * Copying to tmp table, thread state: general-thread-states. (line 60) * core-file option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 136) * core-file option, mysqld: server-options. (line 429) * core-file-size option, mysqld_safe: mysqld-safe. (line 141) * correct-checksum option, myisamchk: myisamchk-repair-options. (line 19) * correlated subqueries: correlated-subqueries. (line 6) * COS(): mathematical-functions. (line 158) * COT(): mathematical-functions. (line 165) * count option, myisam_ftdump: myisam-ftdump. (line 62) * count option, mysqladmin: mysqladmin. (line 324) * count option, mysqlshow: mysqlshow. (line 135) * COUNT(): group-by-functions. (line 93) * COUNT(DISTINCT): group-by-functions. (line 123) * counters, ndbinfo table: mysql-cluster-ndbinfo-counters. (line 6) * counting, table rows: counting-rows. (line 6) * CR_SERVER_GONE_ERROR: gone-away. (line 6) * CR_SERVER_LOST_ERROR: gone-away. (line 6) * crash: debugging-server. (line 16) * crash, recovery: myisam-crash-recovery. (line 6) * crash, repeated: crashing. (line 6) * crash, replication: replication-features-shutdowns. (line 6) * crash-me: mysql-benchmarks. (line 43) * crash-me program <1>: mysql-benchmarks. (line 6) * crash-me program: portability. (line 6) * CrashOnCorruptedTuple: mysql-cluster-ndbd-definition. (line 1601) * CRC32(): mathematical-functions. (line 174) * CREATE ... IF NOT EXISTS, and replication: replication-features-create-if-not-exists. (line 6) * CREATE DATABASE: create-database. (line 6) * Create DB, thread command: thread-commands. (line 29) * CREATE EVENT: create-event. (line 6) * CREATE EVENT, and replication: replication-features-invoked. (line 49) * CREATE FUNCTION <1>: create-function-udf. (line 6) * CREATE FUNCTION: create-procedure. (line 6) * CREATE INDEX: create-index. (line 6) * CREATE LOGFILE GROUP: create-logfile-group. (line 6) * CREATE NODEGROUP command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 209) * create option, mysqlslap: mysqlslap. (line 281) * CREATE PROCEDURE: create-procedure. (line 6) * CREATE SCHEMA: create-database. (line 6) * CREATE SERVER: create-server. (line 6) * CREATE TABLE: create-table. (line 12) * CREATE TABLE ... SELECT, and replication: replication-features-create-select. (line 6) * CREATE TABLE, DIRECTORY options, and replication: replication-features-directory. (line 6) * CREATE TABLESPACE: create-tablespace. (line 6) * CREATE TRIGGER: create-trigger. (line 6) * CREATE USER: create-user. (line 6) * CREATE VIEW: create-view. (line 6) * create-options option, mysqldump: mysqldump. (line 476) * create-schema option, mysqlslap: mysqlslap. (line 286) * Creating delayed handler, thread state: delayed-insert-thread-states. (line 22) * Creating index, thread state: general-thread-states. (line 72) * Creating sort index, thread state: general-thread-states. (line 77) * Creating table from master dump, thread state: slave-connection-thread-states. (line 14) * creating table, thread state: general-thread-states. (line 82) * Creating tmp table, thread state: general-thread-states. (line 87) * creating user accounts: create-user. (line 6) * creating, bug reports: bug-reports. (line 6) * creating, database: create-database. (line 6) * creating, databases: database-use. (line 13) * creating, default startup options: option-files. (line 6) * creating, function: create-function-udf. (line 6) * creating, schema: create-database. (line 6) * creating, tables: creating-tables. (line 6) * CROSS JOIN: join. (line 6) * Crosses(): functions-that-test-spatial-relationships-between-geometries. (line 22) * Crystal Reports: connector-net-programming-crystal. (line 12) * CSV data, reading <1>: select-into. (line 117) * CSV data, reading: load-data. (line 327) * csv option, mysqlslap: mysqlslap. (line 297) * CSV storage engine <1>: csv-storage-engine. (line 11) * CSV storage engine: storage-engines. (line 23) * CURDATE(): date-and-time-functions. (line 203) * CURRENT_DATE: date-and-time-functions. (line 214) * CURRENT_TIME: date-and-time-functions. (line 218) * CURRENT_TIMESTAMP: date-and-time-functions. (line 222) * CURRENT_USER(): information-functions. (line 137) * Cursors: cursors. (line 13) * CURTIME(): date-and-time-functions. (line 227) * CXX environment variable <1>: environment-variables. (line 18) * CXX environment variable <2>: compilation-problems. (line 65) * CXX environment variable: source-configuration-options. (line 397) * CXXFLAGS environment variable <1>: environment-variables. (line 18) * CXXFLAGS environment variable: compilation-problems. (line 88) * daemon option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 268) * daemon plugins: daemon-plugins. (line 6) * Daemon, thread command: thread-commands. (line 33) * DATA DIRECTORY, and replication: replication-features-directory. (line 6) * data node (MySQL Cluster), defined: mysql-cluster-basics. (line 6) * data nodes (MySQL Cluster) <1>: mysql-cluster-programs-ndbmtd. (line 6) * data nodes (MySQL Cluster): mysql-cluster-programs-ndbd. (line 6) * Data truncation with CJK characters: faqs-cjk. (line 6) * data type, BIGINT: numeric-type-overview. (line 125) * data type, BINARY <1>: binary-varbinary. (line 6) * data type, BINARY: string-type-overview. (line 151) * data type, BIT: numeric-type-overview. (line 35) * data type, BLOB <1>: blob. (line 6) * data type, BLOB: string-type-overview. (line 180) * data type, BOOL <1>: other-vendor-data-types. (line 6) * data type, BOOL: numeric-type-overview. (line 45) * data type, BOOLEAN <1>: other-vendor-data-types. (line 6) * data type, BOOLEAN: numeric-type-overview. (line 45) * data type, CHAR <1>: string-types. (line 14) * data type, CHAR: string-type-overview. (line 89) * data type, CHAR VARYING: string-type-overview. (line 121) * data type, CHARACTER: string-type-overview. (line 89) * data type, CHARACTER VARYING: string-type-overview. (line 121) * data type, DATE <1>: datetime. (line 6) * data type, DATE: date-and-time-type-overview. (line 16) * data type, DATETIME <1>: datetime. (line 6) * data type, DATETIME: date-and-time-type-overview. (line 23) * data type, DEC: numeric-type-overview. (line 186) * data type, DECIMAL <1>: precision-math. (line 14) * data type, DECIMAL: numeric-type-overview. (line 170) * data type, DOUBLE: numeric-type-overview. (line 214) * data type, DOUBLE PRECISION: numeric-type-overview. (line 231) * data type, ENUM <1>: enum. (line 6) * data type, ENUM: string-type-overview. (line 242) * data type, FIXED: numeric-type-overview. (line 186) * data type, FLOAT: numeric-type-overview. (line 194) * data type, GEOMETRY: mysql-spatial-datatypes. (line 6) * data type, GEOMETRYCOLLECTION: mysql-spatial-datatypes. (line 6) * data type, INT: numeric-type-overview. (line 116) * data type, INTEGER: numeric-type-overview. (line 121) * data type, LINESTRING: mysql-spatial-datatypes. (line 6) * data type, LONG: blob. (line 6) * data type, LONGBLOB: string-type-overview. (line 220) * data type, LONGTEXT: string-type-overview. (line 230) * data type, MEDIUMBLOB: string-type-overview. (line 204) * data type, MEDIUMINT: numeric-type-overview. (line 111) * data type, MEDIUMTEXT: string-type-overview. (line 211) * data type, MULTILINESTRING: mysql-spatial-datatypes. (line 6) * data type, MULTIPOINT: mysql-spatial-datatypes. (line 6) * data type, MULTIPOLYGON: mysql-spatial-datatypes. (line 6) * data type, NATIONAL CHAR: string-type-overview. (line 89) * data type, NATIONAL VARCHAR: string-type-overview. (line 121) * data type, NCHAR: string-type-overview. (line 89) * data type, NUMERIC: numeric-type-overview. (line 186) * data type, NVARCHAR: string-type-overview. (line 121) * data type, POINT: mysql-spatial-datatypes. (line 6) * data type, POLYGON: mysql-spatial-datatypes. (line 6) * data type, REAL: numeric-type-overview. (line 231) * data type, SET <1>: set. (line 6) * data type, SET: string-type-overview. (line 257) * data type, SMALLINT: numeric-type-overview. (line 106) * data type, TEXT <1>: blob. (line 6) * data type, TEXT: string-type-overview. (line 191) * data type, TIME <1>: time. (line 6) * data type, TIME: date-and-time-type-overview. (line 62) * data type, TIMESTAMP <1>: datetime. (line 6) * data type, TIMESTAMP: date-and-time-type-overview. (line 31) * data type, TINYBLOB: string-type-overview. (line 165) * data type, TINYINT: numeric-type-overview. (line 40) * data type, TINYTEXT: string-type-overview. (line 171) * data type, VARBINARY <1>: binary-varbinary. (line 6) * data type, VARBINARY: string-type-overview. (line 158) * data type, VARCHAR <1>: string-types. (line 14) * data type, VARCHAR: string-type-overview. (line 121) * data type, VARCHARACTER: string-type-overview. (line 121) * data type, YEAR <1>: year. (line 6) * data type, YEAR: date-and-time-type-overview. (line 69) * data types: data-types. (line 31) * data types, C API: c-api. (line 28) * data types, overview: data-type-overview. (line 12) * data, importing <1>: mysqlimport. (line 6) * data, importing: mysql-batch-commands. (line 6) * data, loading into tables: loading-tables. (line 6) * data, retrieving: retrieving-data. (line 18) * data, size: data-size. (line 6) * data-file-length option, myisamchk: myisamchk-repair-options. (line 23) * Database information, obtaining: show. (line 51) * database metadata: information-schema. (line 36) * database names, case sensitivity <1>: identifier-case-sensitivity. (line 6) * database names, case sensitivity: extensions-to-ansi. (line 38) * database option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 122) * database option, mysql: mysql-command-options. (line 221) * database option, mysqlbinlog: mysqlbinlog. (line 242) * database option, ndb_blob_tool: mysql-cluster-programs-ndb-blob-tool. (line 79) * database option, ndb_desc: mysql-cluster-programs-ndb-desc. (line 293) * database option, ndb_show_tables: mysql-cluster-programs-ndb-show-tables. (line 50) * DATABASE(): information-functions. (line 206) * database, altering: alter-database. (line 6) * database, creating: create-database. (line 6) * database, deleting: drop-database. (line 6) * databases option, mysqlcheck: mysqlcheck. (line 263) * databases option, mysqldump: mysqldump. (line 481) * databases, backups: backup-and-recovery. (line 15) * databases, copying: copying-databases. (line 6) * databases, creating: database-use. (line 13) * databases, defined: what-is-mysql. (line 25) * databases, displaying: mysqlshow. (line 6) * databases, dumping <1>: mysqlhotcopy. (line 6) * databases, dumping: mysqldump. (line 6) * databases, information about: getting-information. (line 6) * databases, names: identifiers. (line 13) * databases, replicating: replication. (line 13) * databases, selecting: creating-database. (line 6) * databases, symbolic links: symbolic-links-to-databases. (line 6) * databases, using: database-use. (line 13) * DataDir <1>: mysql-cluster-ndbd-definition. (line 259) * DataDir: mysql-cluster-mgm-definition. (line 231) * datadir option, mysql.server: mysql-server. (line 40) * datadir option, mysql_install_db: mysql-install-db. (line 60) * datadir option, mysql_upgrade: mysql-upgrade. (line 125) * datadir option, mysqld: server-options. (line 458) * datadir option, mysqld_safe: mysqld-safe. (line 146) * datadir system variable: server-system-variables. (line 1146) * DataJunction: connector-odbc-usagenotes-apptips-datajunction. (line 6) * DataMemory <1>: mysql-cluster-config-lcp-params. (line 6) * DataMemory: mysql-cluster-ndbd-definition. (line 330) * DATE: using-date. (line 6) * date and time functions: date-and-time-functions. (line 6) * Date and Time types: date-and-time-types. (line 17) * date calculations: date-calculations. (line 6) * DATE columns, problems: using-date. (line 6) * DATE columns, with Connector/Net: connector-net-programming-datetime. (line 14) * DATE data type <1>: datetime. (line 6) * DATE data type: date-and-time-type-overview. (line 16) * date literals: date-and-time-literals. (line 6) * date types: storage-requirements. (line 130) * date values, problems: datetime. (line 53) * DATE(): date-and-time-functions. (line 239) * DATE_ADD(): date-and-time-functions. (line 258) * date_format system variable: server-system-variables. (line 1166) * DATE_FORMAT(): date-and-time-functions. (line 418) * DATE_SUB(): date-and-time-functions. (line 258) * DATEDIFF(): date-and-time-functions. (line 246) * dates, used with partitioning: partitioning-types. (line 49) * dates, used with partitioning (examples) <1>: partitioning-pruning. (line 71) * dates, used with partitioning (examples) <2>: partitioning-subpartitions. (line 42) * dates, used with partitioning (examples) <3>: partitioning-hash. (line 49) * dates, used with partitioning (examples): partitioning-range. (line 127) * DATETIME data type <1>: datetime. (line 6) * DATETIME data type: date-and-time-type-overview. (line 23) * datetime_format system variable: server-system-variables. (line 1170) * DAY(): date-and-time-functions. (line 507) * DAYNAME(): date-and-time-functions. (line 511) * DAYOFMONTH(): date-and-time-functions. (line 520) * DAYOFWEEK(): date-and-time-functions. (line 529) * DAYOFYEAR(): date-and-time-functions. (line 538) * db option, mysqlaccess: mysqlaccess. (line 86) * db table, sorting: request-access. (line 51) * DB2 SQL mode: server-sql-mode. (line 524) * DBI interface: apis-perl. (line 6) * DBI->quote: string-literals. (line 141) * DBI->trace: using-gdb-on-mysqld. (line 89) * DBI/DBD interface: apis-perl. (line 6) * DBI_TRACE environment variable <1>: using-gdb-on-mysqld. (line 89) * DBI_TRACE environment variable: environment-variables. (line 18) * DBI_USER environment variable: environment-variables. (line 18) * DBUG package: dbug-package. (line 6) * DCL <1>: revoke. (line 6) * DCL: grant. (line 6) * DEALLOCATE PREPARE <1>: deallocate-prepare. (line 6) * DEALLOCATE PREPARE: sql-syntax-prepared-statements. (line 13) * debug option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 160) * debug option, comp_err: comp-err. (line 34) * debug option, make_win_bin_dist: make-win-bin-dist. (line 36) * debug option, my_print_defaults: my-print-defaults. (line 35) * debug option, myisamchk: myisamchk-general-options. (line 21) * debug option, myisampack: myisampack. (line 61) * debug option, mysql: mysql-command-options. (line 225) * debug option, mysqlaccess: mysqlaccess. (line 90) * debug option, mysqladmin: mysqladmin. (line 329) * debug option, mysqlbinlog: mysqlbinlog. (line 332) * debug option, mysqlcheck: mysqlcheck. (line 271) * debug option, mysqld: server-options. (line 477) * debug option, mysqldump: mysqldump. (line 490) * debug option, mysqldumpslow: mysqldumpslow. (line 53) * debug option, mysqlhotcopy: mysqlhotcopy. (line 106) * debug option, mysqlimport: mysqlimport. (line 157) * debug option, mysqlmanager: instance-manager-command-options. (line 60) * debug option, mysqlshow: mysqlshow. (line 140) * debug option, mysqlslap: mysqlslap. (line 303) * debug system variable: server-system-variables. (line 1174) * Debug, thread command: thread-commands. (line 38) * debug-check option, mysql: mysql-command-options. (line 230) * debug-check option, mysql_upgrade: mysql-upgrade. (line 130) * debug-check option, mysqladmin: mysqladmin. (line 335) * debug-check option, mysqlbinlog: mysqlbinlog. (line 338) * debug-check option, mysqlcheck: mysqlcheck. (line 276) * debug-check option, mysqldump: mysqldump. (line 496) * debug-check option, mysqlimport: mysqlimport. (line 162) * debug-check option, mysqlshow: mysqlshow. (line 145) * debug-check option, mysqlslap: mysqlslap. (line 309) * debug-info option, comp_err: comp-err. (line 39) * debug-info option, mysql: mysql-command-options. (line 235) * debug-info option, mysql_upgrade: mysql-upgrade. (line 135) * debug-info option, mysqladmin: mysqladmin. (line 340) * debug-info option, mysqlbinlog: mysqlbinlog. (line 343) * debug-info option, mysqlcheck: mysqlcheck. (line 281) * debug-info option, mysqldump: mysqldump. (line 501) * debug-info option, mysqlimport: mysqlimport. (line 167) * debug-info option, mysqlshow: mysqlshow. (line 150) * debug-info option, mysqlslap: mysqlslap. (line 314) * debug-sync-timeout option, mysqld: server-options. (line 512) * debug_sync system variable: server-system-variables. (line 1227) * debugging support: source-configuration-options. (line 6) * debugging, client: debugging-client. (line 6) * debugging, server: debugging-server. (line 16) * DEC data type: numeric-type-overview. (line 186) * decimal arithmetic: precision-math. (line 14) * DECIMAL data type <1>: precision-math. (line 14) * DECIMAL data type: numeric-type-overview. (line 170) * decimal point: data-types. (line 39) * DECLARE: declare. (line 6) * DECODE(): encryption-functions. (line 176) * decode_bits myisamchk variable: myisamchk-general-options. (line 53) * default host name: connecting. (line 6) * default installation location: installation-layouts. (line 6) * default options: option-files. (line 6) * DEFAULT value clause <1>: create-table. (line 325) * DEFAULT value clause: data-type-defaults. (line 6) * default values <1>: insert. (line 70) * default values <2>: create-table. (line 325) * default values <3>: data-type-defaults. (line 6) * default values: design-limitations. (line 20) * default values, BLOB and TEXT columns: blob. (line 52) * default values, explicit: data-type-defaults. (line 6) * default values, implicit: data-type-defaults. (line 6) * default values, suppression: constraint-invalid-data. (line 6) * DEFAULT(): miscellaneous-functions. (line 29) * DEFAULT, constraint: constraint-invalid-data. (line 6) * default, privileges: default-privileges. (line 6) * default-character-set option, mysql: mysql-command-options. (line 243) * default-character-set option, mysqladmin: mysqladmin. (line 345) * default-character-set option, mysqlcheck: mysqlcheck. (line 286) * default-character-set option, mysqld: server-options. (line 540) * default-character-set option, mysqldump: mysqldump. (line 506) * default-character-set option, mysqlimport: mysqlimport. (line 172) * default-character-set option, mysqlshow: mysqlshow. (line 155) * default-collation option, mysqld: server-options. (line 559) * default-mysqld-path option, mysqlmanager: instance-manager-command-options. (line 65) * default-storage-engine option, mysqld: server-options. (line 576) * default-table-type option, mysqld: server-options. (line 596) * default-time-zone option, mysqld: server-options. (line 613) * default_week_format system variable: server-system-variables. (line 1266) * DefaultHashMapSize <1>: mysql-cluster-api-definition. (line 327) * DefaultHashMapSize: mysql-cluster-ndbd-definition. (line 1009) * DefaultOperationRedoProblemAction, API and SQL nodes: mysql-cluster-api-definition. (line 296) * defaults, embedded: libmysqld-options. (line 6) * defaults-extra-file option: option-file-options. (line 21) * defaults-extra-file option, my_print_defaults: my-print-defaults. (line 41) * defaults-extra-file option, mysqld_multi: mysqld-multi. (line 68) * defaults-extra-file option, mysqld_safe: mysqld-safe. (line 150) * defaults-file option: option-file-options. (line 28) * defaults-file option, my_print_defaults: my-print-defaults. (line 31) * defaults-file option, mysqld_multi: mysqld-multi. (line 66) * defaults-file option, mysqld_safe: mysqld-safe. (line 157) * defaults-file option, mysqlmanager: instance-manager-command-options. (line 74) * defaults-group-suffix option: option-file-options. (line 34) * defaults-group-suffix option, my_print_defaults: my-print-defaults. (line 48) * DEGREES(): mathematical-functions. (line 186) * delay option (ndbinfo_select_all): mysql-cluster-programs-ndbinfo-select-all. (line 87) * delay-key-write option, mysqld <1>: myisam-start. (line 42) * delay-key-write option, mysqld: server-options. (line 629) * delay_key_write system variable: server-system-variables. (line 1288) * DELAYED: insert-delayed. (line 6) * Delayed insert, thread command: thread-commands. (line 42) * delayed inserts, thread states: delayed-insert-thread-states. (line 6) * DELAYED, when ignored: insert. (line 226) * delayed-insert option, mysqldump: mysqldump. (line 517) * delayed_insert_limit: insert-delayed. (line 123) * delayed_insert_limit system variable: server-system-variables. (line 1337) * delayed_insert_timeout system variable: server-system-variables. (line 1369) * delayed_queue_size system variable: server-system-variables. (line 1389) * DELETE: delete. (line 6) * delete option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 137) * delete option, mysqlimport: mysqlimport. (line 181) * DELETE, and MySQL Cluster: mysql-cluster-limitations-limits. (line 9) * delete-master-logs option, mysqldump: mysqldump. (line 522) * delete-orphans option, ndb_blob_tool: mysql-cluster-programs-ndb-blob-tool. (line 94) * deleting from main table, thread state: general-thread-states. (line 94) * deleting from reference tables, thread state: general-thread-states. (line 100) * deleting, database: drop-database. (line 6) * deleting, foreign key <1>: create-table-foreign-keys. (line 210) * deleting, foreign key: alter-table. (line 468) * deleting, function: drop-function-udf. (line 6) * deleting, index <1>: drop-index. (line 6) * deleting, index: alter-table. (line 342) * deleting, primary key: alter-table. (line 357) * deleting, rows: deleting-from-related-tables. (line 6) * deleting, schema: drop-database. (line 6) * deleting, table: drop-table. (line 6) * deleting, user <1>: drop-user. (line 6) * deleting, user: removing-users. (line 6) * deleting, users <1>: drop-user. (line 6) * deleting, users: removing-users. (line 6) * deletion, mysql.sock: problems-with-mysql-sock. (line 6) * delimiter command, mysql: mysql-commands. (line 82) * delimiter option, mysql: mysql-command-options. (line 257) * delimiter option, mysqlslap: mysqlslap. (line 319) * delimiter option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 109) * Delphi: connector-odbc-usagenotes-apptips-borland-delphi. (line 6) * derived tables: from-clause-subqueries. (line 6) * des-key-file option, mysqld: server-options. (line 662) * DES_DECRYPT(): encryption-functions. (line 181) * DES_ENCRYPT(): encryption-functions. (line 202) * DESC: describe. (line 6) * descending option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 94) * DESCRIBE <1>: describe. (line 6) * DESCRIBE: getting-information. (line 6) * description option, myisamchk: myisamchk-other-options. (line 22) * design, issues: bugs. (line 6) * design, limitations: design-limitations. (line 6) * detach option, mysqlslap: mysqlslap. (line 324) * development of MySQL Cluster: mysql-cluster-development. (line 16) * development source tree: installing-development-tree. (line 6) * Difference(): spatial-operators. (line 21) * digits: data-types. (line 39) * Dimension(): general-geometry-property-functions. (line 9) * directory structure, default: installation-layouts. (line 6) * dirty page: innodb-parameters. (line 253) * disable named command, mysql: mysql-command-options. (line 262) * disable-grant-options option, configure: source-configuration-options. (line 537) * disable-indexes option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 891) * disable-keys option, mysqldump: mysqldump. (line 529) * disable-log-bin option, mysqlbinlog: mysqlbinlog. (line 348) * DISCARD TABLESPACE <1>: innodb-multiple-tablespaces. (line 168) * DISCARD TABLESPACE: alter-table. (line 479) * discard_or_import_tablespace, thread state: general-thread-states. (line 105) * disconnect-slave-event-count option, mysqld: replication-options-slave. (line 161) * disconnecting, from the server: connecting-disconnecting. (line 6) * Disjoint(): functions-that-test-spatial-relationships-between-geometries. (line 40) * Disk Data tables (MySQL Cluster): mysql-cluster-disk-data. (line 12) * disk full: full-disk. (line 6) * disk option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 116) * disk performance: disk-issues. (line 6) * DiskCheckpointSpeed: mysql-cluster-ndbd-definition. (line 2307) * DiskCheckpointSpeedInRestart: mysql-cluster-ndbd-definition. (line 2327) * DiskIOThreadPool: mysql-cluster-ndbd-definition. (line 3490) * Diskless: mysql-cluster-ndbd-definition. (line 1617) * diskpagebuffer, ndbinfo table: mysql-cluster-ndbinfo-diskpagebuffer. (line 6) * DiskPageBufferMemory: mysql-cluster-ndbd-definition. (line 3435) * disks, splitting data across: windows-symbolic-links. (line 6) * DiskSyncSize: mysql-cluster-ndbd-definition. (line 2283) * display size: data-types. (line 33) * display triggers: show-triggers. (line 6) * display width: data-types. (line 33) * displaying, database information: mysqlshow. (line 6) * displaying, information, Cardinality: show-index. (line 42) * displaying, information, Collation: show-index. (line 37) * displaying, information, SHOW <1>: show-tables. (line 6) * displaying, information, SHOW <2>: show-open-tables. (line 6) * displaying, information, SHOW <3>: show-index. (line 6) * displaying, information, SHOW <4>: show-columns. (line 6) * displaying, information, SHOW: show. (line 51) * displaying, table status: show-table-status. (line 6) * DISTINCT <1>: select. (line 348) * DISTINCT <2>: distinct-optimization. (line 6) * DISTINCT: selecting-columns. (line 43) * DISTINCT, AVG(): group-by-functions. (line 59) * DISTINCT, COUNT(): group-by-functions. (line 123) * DISTINCT, MAX(): group-by-functions. (line 192) * DISTINCT, MIN(): group-by-functions. (line 212) * DISTINCT, SUM(): group-by-functions. (line 263) * DISTINCTROW: select. (line 348) * distributed privileges (MySQL Cluster): mysql-cluster-privilege-distribution. (line 6) * distributed privileges (MySQL Cluster), and NDB API applications: mysql-cluster-privilege-distribution. (line 194) * DIV: arithmetic-functions. (line 108) * div_precision_increment system variable: server-system-variables. (line 1421) * division (/): arithmetic-functions. (line 92) * DNS: host-cache. (line 6) * DO: do. (line 6) * DocBook XML, documentation source format: manual-info. (line 33) * Documentation, in Chinese: faqs-cjk. (line 6) * Documentation, in Japanese: faqs-cjk. (line 6) * Documentation, in Korean: faqs-cjk. (line 6) * Documenters, list of: documenters-translators. (line 6) * dont_ignore_systab_0 option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 611) * DOUBLE data type: numeric-type-overview. (line 214) * DOUBLE PRECISION data type: numeric-type-overview. (line 231) * double quote (\"): string-literals. (line 70) * downgrades, MySQL Cluster <1>: mysql-cluster-rolling-restart. (line 6) * downgrades, MySQL Cluster: mysql-cluster-upgrade-downgrade. (line 12) * downgrading <1>: downgrading. (line 11) * downgrading: upgrading-downgrading. (line 14) * downloading: getting-mysql. (line 6) * DROP ... IF EXISTS, and replication: replication-features-drop-if-exists. (line 6) * DROP DATABASE: drop-database. (line 6) * Drop DB, thread command: thread-commands. (line 46) * DROP EVENT: drop-event. (line 6) * DROP FOREIGN KEY <1>: create-table-foreign-keys. (line 210) * DROP FOREIGN KEY: alter-table. (line 468) * DROP FUNCTION <1>: drop-function-udf. (line 6) * DROP FUNCTION: drop-procedure. (line 6) * DROP INDEX <1>: drop-index. (line 6) * DROP INDEX: alter-table. (line 342) * DROP LOGFILE GROUP: drop-logfile-group. (line 6) * DROP NODEGROUP command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 232) * DROP PREPARE: deallocate-prepare. (line 6) * DROP PRIMARY KEY: alter-table. (line 357) * DROP PROCEDURE: drop-procedure. (line 6) * DROP SCHEMA: drop-database. (line 6) * DROP SERVER: drop-server. (line 6) * DROP TABLE: drop-table. (line 6) * DROP TABLE, and MySQL Cluster: mysql-cluster-limitations-limits. (line 9) * DROP TABLESPACE: drop-tablespace. (line 6) * DROP TRIGGER: drop-trigger. (line 6) * DROP USER: drop-user. (line 6) * DROP VIEW: drop-view. (line 6) * drop-user option, mysqlmanager: instance-manager-command-options. (line 86) * dropping, user <1>: drop-user. (line 6) * dropping, user: removing-users. (line 6) * dryrun option, mysqlhotcopy: mysqlhotcopy. (line 110) * DTrace, and memcached: ha-memcached-using-dtrace. (line 6) * DTrace, and MySQL Connector/C++: connector-cpp-debug-tracing. (line 6) * DUAL: select. (line 67) * dump option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 167) * dump option, myisam_ftdump: myisam-ftdump. (line 66) * dump-date option, mysqldump: mysqldump. (line 539) * dump-file option, ndb_blob_tool: mysql-cluster-programs-ndb-blob-tool. (line 108) * DUMPFILE: select-into. (line 125) * dumping, databases and tables <1>: mysqlhotcopy. (line 6) * dumping, databases and tables: mysqldump. (line 6) * dynamic table characteristics: dynamic-format. (line 6) * edit command, mysql: mysql-commands. (line 117) * edit-user option, mysqlmanager: instance-manager-command-options. (line 91) * EF 5: connector-net-entityframework50. (line 6) * ego command, mysql: mysql-commands. (line 126) * Eiffel Wrapper: apis-eiffel. (line 6) * ELT(): string-functions. (line 233) * email lists: mailing-lists. (line 10) * embedded MySQL server library: libmysqld. (line 13) * embedded option, make_win_bin_dist: make-win-bin-dist. (line 41) * embedded option, mysql_config: mysql-config. (line 26) * enable-community-features option, configure: source-configuration-options. (line 544) * enable-debug-sync option, configure: source-configuration-options. (line 492) * enable-named-pipe option, mysqld: server-options. (line 677) * enable-profiling option, configure: source-configuration-options. (line 550) * enable-pstack option, mysqld: server-options. (line 694) * enable-thread-safe-client option, configure: source-configuration-options. (line 512) * ENCODE(): encryption-functions. (line 253) * ENCRYPT(): encryption-functions. (line 268) * encryption: ssl-basics. (line 18) * encryption functions: encryption-functions. (line 6) * END: begin-end. (line 6) * end, thread state: general-thread-states. (line 110) * EndPoint(): linestring-property-functions. (line 10) * engine option, mysqlslap: mysqlslap. (line 330) * engine_condition_pushdown system variable: server-system-variables. (line 1462) * ENGINES, INFORMATION_SCHEMA table: engines-table. (line 6) * ENTER SINGLE USER MODE command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 176) * entering, queries: entering-queries. (line 6) * enterprise components, MySQL Enterprise Audit: mysql-enterprise-audit. (line 6) * enterprise components, MySQL Enterprise Backup: mysql-enterprise-backup. (line 6) * enterprise components, MySQL Enterprise Monitor: mysql-enterprise-monitor. (line 6) * enterprise components, MySQL Enterprise Security: mysql-enterprise-security. (line 6) * enterprise components, MySQL Thread Pool: mysql-enterprise-thread-pool. (line 6) * ENUM data type <1>: enum. (line 6) * ENUM data type: string-type-overview. (line 242) * ENUM, size: storage-requirements. (line 245) * Envelope(): general-geometry-property-functions. (line 22) * environment variable, CC <1>: environment-variables. (line 18) * environment variable, CC <2>: compilation-problems. (line 88) * environment variable, CC: source-configuration-options. (line 397) * environment variable, CFLAGS <1>: environment-variables. (line 18) * environment variable, CFLAGS: compilation-problems. (line 88) * environment variable, CXX <1>: environment-variables. (line 18) * environment variable, CXX <2>: compilation-problems. (line 65) * environment variable, CXX: source-configuration-options. (line 397) * environment variable, CXXFLAGS <1>: environment-variables. (line 18) * environment variable, CXXFLAGS: compilation-problems. (line 88) * environment variable, DBI_TRACE <1>: using-gdb-on-mysqld. (line 89) * environment variable, DBI_TRACE: environment-variables. (line 18) * environment variable, DBI_USER: environment-variables. (line 18) * environment variable, HOME <1>: mysql-logging. (line 6) * environment variable, HOME: environment-variables. (line 18) * environment variable, LD_LIBRARY_PATH: perl-support-problems. (line 20) * environment variable, LD_RUN_PATH <1>: perl-support-problems. (line 20) * environment variable, LD_RUN_PATH <2>: environment-variables. (line 18) * environment variable, LD_RUN_PATH: solaris-installation-source. (line 97) * environment variable, MYSQL_DEBUG <1>: debugging-client. (line 10) * environment variable, MYSQL_DEBUG <2>: programs-overview. (line 304) * environment variable, MYSQL_DEBUG: environment-variables. (line 18) * environment variable, MYSQL_GROUP_SUFFIX: environment-variables. (line 18) * environment variable, MYSQL_HISTFILE <1>: mysql-logging. (line 6) * environment variable, MYSQL_HISTFILE: environment-variables. (line 18) * environment variable, MYSQL_HOME: environment-variables. (line 18) * environment variable, MYSQL_HOST <1>: connecting. (line 235) * environment variable, MYSQL_HOST: environment-variables. (line 18) * environment variable, MYSQL_PS1: environment-variables. (line 18) * environment variable, MYSQL_PWD <1>: connecting. (line 235) * environment variable, MYSQL_PWD <2>: programs-overview. (line 304) * environment variable, MYSQL_PWD: environment-variables. (line 18) * environment variable, MYSQL_TCP_PORT <1>: multiple-server-clients. (line 27) * environment variable, MYSQL_TCP_PORT <2>: multiple-unix-servers. (line 68) * environment variable, MYSQL_TCP_PORT <3>: programs-overview. (line 304) * environment variable, MYSQL_TCP_PORT: environment-variables. (line 18) * environment variable, MYSQL_UNIX_PORT <1>: multiple-server-clients. (line 27) * environment variable, MYSQL_UNIX_PORT <2>: multiple-unix-servers. (line 68) * environment variable, MYSQL_UNIX_PORT <3>: programs-overview. (line 304) * environment variable, MYSQL_UNIX_PORT <4>: environment-variables. (line 18) * environment variable, MYSQL_UNIX_PORT: mysql-install-db-problems. (line 84) * environment variable, PATH <1>: invoking-programs. (line 48) * environment variable, PATH <2>: environment-variables. (line 18) * environment variable, PATH: unix-postinstallation. (line 68) * environment variable, TMPDIR <1>: temporary-files. (line 6) * environment variable, TMPDIR <2>: programs-overview. (line 304) * environment variable, TMPDIR <3>: environment-variables. (line 18) * environment variable, TMPDIR: mysql-install-db-problems. (line 84) * environment variable, TZ <1>: timezone-problems. (line 6) * environment variable, TZ: environment-variables. (line 18) * environment variable, UMASK <1>: file-permissions. (line 6) * environment variable, UMASK: environment-variables. (line 18) * environment variable, UMASK_DIR <1>: file-permissions. (line 20) * environment variable, UMASK_DIR: environment-variables. (line 18) * environment variable, USER <1>: connecting. (line 235) * environment variable, USER: environment-variables. (line 18) * environment variables <1>: access-denied. (line 101) * environment variables <2>: setting-environment-variables. (line 6) * environment variables: programs-overview. (line 301) * environment variables, CXX: compilation-problems. (line 75) * environment variables, list of: environment-variables. (line 6) * eq_ref join type, optimizer: explain-output. (line 257) * equal (=): comparison-operators. (line 64) * Equals(): functions-that-test-spatial-relationships-between-geometries. (line 45) * ER_ABORTING_CONNECTION: connector-j-reference-error-sqlstates. (line 6) * ER_ACCESS_DENIED_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_BAD_FIELD_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_BAD_HOST_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_BAD_TABLE_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_BLOB_CANT_HAVE_DEFAULT: connector-j-reference-error-sqlstates. (line 6) * ER_BLOB_KEY_WITHOUT_LENGTH: connector-j-reference-error-sqlstates. (line 6) * ER_BLOB_USED_AS_KEY: connector-j-reference-error-sqlstates. (line 6) * ER_BLOBS_AND_NO_TERMINATED: connector-j-reference-error-sqlstates. (line 6) * ER_CANT_DO_THIS_DURING_AN_TRANSACTION: connector-j-reference-error-sqlstates. (line 6) * ER_CANT_DROP_FIELD_OR_KEY: connector-j-reference-error-sqlstates. (line 6) * ER_CANT_REMOVE_ALL_FIELDS: connector-j-reference-error-sqlstates. (line 6) * ER_CANT_USE_OPTION_HERE: connector-j-reference-error-sqlstates. (line 6) * ER_CHECK_NO_SUCH_TABLE: connector-j-reference-error-sqlstates. (line 6) * ER_CHECK_NOT_IMPLEMENTED: connector-j-reference-error-sqlstates. (line 6) * ER_COLLATION_CHARSET_MISMATCH: connector-j-reference-error-sqlstates. (line 6) * ER_COLUMNACCESS_DENIED_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_CON_COUNT_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_CONNECT_TO_MASTER: connector-j-reference-error-sqlstates. (line 6) * ER_DBACCESS_DENIED_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_DERIVED_MUST_HAVE_ALIAS: connector-j-reference-error-sqlstates. (line 6) * ER_DUP_ENTRY: connector-j-reference-error-sqlstates. (line 6) * ER_DUP_FIELDNAME: connector-j-reference-error-sqlstates. (line 6) * ER_DUP_KEY: connector-j-reference-error-sqlstates. (line 6) * ER_DUP_KEYNAME: connector-j-reference-error-sqlstates. (line 6) * ER_DUP_UNIQUE: connector-j-reference-error-sqlstates. (line 6) * ER_EMPTY_QUERY: connector-j-reference-error-sqlstates. (line 6) * ER_FIELD_SPECIFIED_TWICE: connector-j-reference-error-sqlstates. (line 6) * ER_FORCING_CLOSE: connector-j-reference-error-sqlstates. (line 6) * ER_GRANT_WRONG_HOST_OR_USER: connector-j-reference-error-sqlstates. (line 6) * ER_HANDSHAKE_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_HOST_IS_BLOCKED: connector-j-reference-error-sqlstates. (line 6) * ER_HOST_NOT_PRIVILEGED: connector-j-reference-error-sqlstates. (line 6) * ER_ILLEGAL_GRANT_FOR_TABLE: connector-j-reference-error-sqlstates. (line 6) * ER_ILLEGAL_REFERENCE: connector-j-reference-error-sqlstates. (line 6) * ER_INVALID_DEFAULT: connector-j-reference-error-sqlstates. (line 6) * ER_INVALID_USE_OF_NULL: connector-j-reference-error-sqlstates. (line 6) * ER_IPSOCK_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_KEY_COLUMN_DOES_NOT_EXITS: connector-j-reference-error-sqlstates. (line 6) * ER_LOCK_DEADLOCK: connector-j-reference-error-sqlstates. (line 6) * ER_LOCK_WAIT_TIMEOUT: connector-j-reference-error-sqlstates. (line 6) * ER_MASTER_NET_READ: connector-j-reference-error-sqlstates. (line 6) * ER_MASTER_NET_WRITE: connector-j-reference-error-sqlstates. (line 6) * ER_MIX_OF_GROUP_FUNC_AND_FIELDS: connector-j-reference-error-sqlstates. (line 6) * ER_MULTIPLE_PRI_KEY: connector-j-reference-error-sqlstates. (line 6) * ER_NET_ERROR_ON_WRITE: connector-j-reference-error-sqlstates. (line 6) * ER_NET_FCNTL_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_NET_PACKET_TOO_LARGE: connector-j-reference-error-sqlstates. (line 6) * ER_NET_PACKETS_OUT_OF_ORDER: connector-j-reference-error-sqlstates. (line 6) * ER_NET_READ_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_NET_READ_ERROR_FROM_PIPE: connector-j-reference-error-sqlstates. (line 6) * ER_NET_READ_INTERRUPTED: connector-j-reference-error-sqlstates. (line 6) * ER_NET_UNCOMPRESS_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_NET_WRITE_INTERRUPTED: connector-j-reference-error-sqlstates. (line 6) * ER_NEW_ABORTING_CONNECTION: connector-j-reference-error-sqlstates. (line 6) * ER_NO_DEFAULT: connector-j-reference-error-sqlstates. (line 6) * ER_NO_PERMISSION_TO_CREATE_USER: connector-j-reference-error-sqlstates. (line 6) * ER_NO_REFERENCED_ROW: connector-j-reference-error-sqlstates. (line 6) * ER_NO_SUCH_INDEX: connector-j-reference-error-sqlstates. (line 6) * ER_NO_SUCH_TABLE: connector-j-reference-error-sqlstates. (line 6) * ER_NON_UNIQ_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_NONEXISTING_GRANT: connector-j-reference-error-sqlstates. (line 6) * ER_NONEXISTING_TABLE_GRANT: connector-j-reference-error-sqlstates. (line 6) * ER_NONUNIQ_TABLE: connector-j-reference-error-sqlstates. (line 6) * ER_NOT_ALLOWED_COMMAND: connector-j-reference-error-sqlstates. (line 6) * ER_NOT_SUPPORTED_AUTH_MODE: connector-j-reference-error-sqlstates. (line 6) * ER_NOT_SUPPORTED_YET: connector-j-reference-error-sqlstates. (line 6) * ER_NULL_COLUMN_IN_INDEX: connector-j-reference-error-sqlstates. (line 6) * ER_OPERAND_COLUMNS: connector-j-reference-error-sqlstates. (line 6) * ER_OUT_OF_SORTMEMORY: connector-j-reference-error-sqlstates. (line 6) * ER_OUTOFMEMORY: connector-j-reference-error-sqlstates. (line 6) * ER_PARSE_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_PASSWORD_ANONYMOUS_USER: connector-j-reference-error-sqlstates. (line 6) * ER_PASSWORD_NO_MATCH: connector-j-reference-error-sqlstates. (line 6) * ER_PASSWORD_NOT_ALLOWED: connector-j-reference-error-sqlstates. (line 6) * ER_PRIMARY_CANT_HAVE_NULL: connector-j-reference-error-sqlstates. (line 6) * ER_READ_ONLY_TRANSACTION: connector-j-reference-error-sqlstates. (line 6) * ER_REGEXP_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_REQUIRES_PRIMARY_KEY: connector-j-reference-error-sqlstates. (line 6) * ER_ROW_IS_REFERENCED: connector-j-reference-error-sqlstates. (line 6) * ER_SELECT_REDUCED: connector-j-reference-error-sqlstates. (line 6) * ER_SERVER_SHUTDOWN: connector-j-reference-error-sqlstates. (line 6) * ER_SPATIAL_CANT_HAVE_NULL: connector-j-reference-error-sqlstates. (line 6) * ER_SUBQUERY_NO_1_ROW: connector-j-reference-error-sqlstates. (line 6) * ER_SYNTAX_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_TABLE_CANT_HANDLE_AUTO_INCREMENT: connector-j-reference-error-sqlstates. (line 6) * ER_TABLE_CANT_HANDLE_BLOB: connector-j-reference-error-sqlstates. (line 6) * ER_TABLE_EXISTS_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_TABLE_MUST_HAVE_COLUMNS: connector-j-reference-error-sqlstates. (line 6) * ER_TABLEACCESS_DENIED_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_TABLENAME_NOT_ALLOWED_HERE: connector-j-reference-error-sqlstates. (line 6) * ER_TOO_BIG_FIELDLENGTH: connector-j-reference-error-sqlstates. (line 6) * ER_TOO_BIG_ROWSIZE: connector-j-reference-error-sqlstates. (line 6) * ER_TOO_BIG_SELECT: connector-j-reference-error-sqlstates. (line 6) * ER_TOO_LONG_IDENT: connector-j-reference-error-sqlstates. (line 6) * ER_TOO_LONG_KEY: connector-j-reference-error-sqlstates. (line 6) * ER_TOO_LONG_STRING: connector-j-reference-error-sqlstates. (line 6) * ER_TOO_MANY_KEY_PARTS: connector-j-reference-error-sqlstates. (line 6) * ER_TOO_MANY_KEYS: connector-j-reference-error-sqlstates. (line 6) * ER_TOO_MANY_ROWS: connector-j-reference-error-sqlstates. (line 6) * ER_TOO_MANY_USER_CONNECTIONS: connector-j-reference-error-sqlstates. (line 6) * ER_UNKNOWN_CHARACTER_SET: connector-j-reference-error-sqlstates. (line 6) * ER_UNKNOWN_COM_ERROR: connector-j-reference-error-sqlstates. (line 6) * ER_UNKNOWN_PROCEDURE: connector-j-reference-error-sqlstates. (line 6) * ER_UNKNOWN_STORAGE_ENGINE: connector-j-reference-error-sqlstates. (line 6) * ER_UNKNOWN_TABLE: connector-j-reference-error-sqlstates. (line 6) * ER_UNSUPPORTED_EXTENSION: connector-j-reference-error-sqlstates. (line 6) * ER_USER_LIMIT_REACHED: connector-j-reference-error-sqlstates. (line 6) * ER_WARN_DATA_OUT_OF_RANGE: connector-j-reference-error-sqlstates. (line 6) * ER_WARN_DATA_TRUNCATED: connector-j-reference-error-sqlstates. (line 6) * ER_WARN_NULL_TO_NOTNULL: connector-j-reference-error-sqlstates. (line 6) * ER_WARN_TOO_FEW_RECORDS: connector-j-reference-error-sqlstates. (line 6) * ER_WARN_TOO_MANY_RECORDS: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_AUTO_KEY: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_COLUMN_NAME: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_DB_NAME: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_FIELD_SPEC: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_FIELD_TERMINATORS: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_FIELD_WITH_GROUP: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_FK_DEF: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_GROUP_FIELD: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_KEY_COLUMN: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_NAME_FOR_CATALOG: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_NAME_FOR_INDEX: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_NUMBER_OF_COLUMNS_IN_SELECT: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_OUTER_JOIN: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_PARAMCOUNT_TO_PROCEDURE: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_SUM_SELECT: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_TABLE_NAME: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_TYPE_FOR_VAR: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_VALUE_COUNT: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_VALUE_COUNT_ON_ROW: connector-j-reference-error-sqlstates. (line 6) * ER_WRONG_VALUE_FOR_VAR: connector-j-reference-error-sqlstates. (line 6) * Errcode: perror. (line 6) * errno: perror. (line 6) * error codes: connector-j-reference-error-sqlstates. (line 6) * ERROR Events (MySQL Cluster): mysql-cluster-log-events. (line 219) * error logs (MySQL Cluster): mysql-cluster-programs-ndbd. (line 442) * error messages, can't find file: file-permissions. (line 6) * error messages, displaying: perror. (line 6) * error messages, languages: error-message-language. (line 6) * Error, thread command: thread-commands. (line 50) * error_count session variable: server-system-variables. (line 1497) * ERROR_FOR_DIVISION_BY_ZERO SQL mode: server-sql-mode. (line 140) * errors, access denied: error-access-denied. (line 6) * errors, and replication: replication-features-slaveerrors. (line 6) * errors, checking tables for: myisam-check. (line 6) * errors, common: problems. (line 17) * errors, directory checksum: solaris-installation. (line 11) * errors, handling for UDFs: udf-return-values. (line 6) * errors, in subqueries: subquery-errors. (line 6) * errors, known: bugs. (line 6) * errors, linking: c-api-building-clients. (line 79) * errors, list of: common-errors. (line 28) * errors, lost connection: error-lost-connection. (line 6) * errors, reporting: bug-reports. (line 6) * errors, sources of information: error-sources. (line 6) * escape (\\): string-literals. (line 76) * escape sequences, option files: option-files. (line 172) * escape sequences, strings: string-literals. (line 6) * estimating, query performance: estimating-performance. (line 6) * event groups: set-global-sql-slave-skip-counter. (line 6) * event log format (MySQL Cluster): mysql-cluster-log-events. (line 6) * event logs (MySQL Cluster) <1>: mysql-cluster-logging-management-commands. (line 6) * event logs (MySQL Cluster): mysql-cluster-event-reports. (line 12) * Event Scheduler: events. (line 15) * event scheduler: stored-programs-views. (line 16) * Event Scheduler, altering events: alter-event. (line 6) * Event Scheduler, and MySQL privileges: events-privileges. (line 6) * Event Scheduler, and mysqladmin debug: events-status-info. (line 6) * Event Scheduler, and replication: replication-features-invoked. (line 6) * Event Scheduler, and SHOW PROCESSLIST: events-configuration. (line 29) * Event Scheduler, concepts: events-overview. (line 6) * Event Scheduler, creating events: create-event. (line 6) * Event Scheduler, dropping events: drop-event. (line 6) * Event Scheduler, enabling and disabling: events-configuration. (line 12) * Event Scheduler, event metadata: events-metadata. (line 6) * Event Scheduler, obtaining status information <1>: events-status-info. (line 6) * Event Scheduler, obtaining status information: show-scheduler-status. (line 6) * Event Scheduler, SQL statements: events-syntax. (line 6) * Event Scheduler, starting and stopping: events-configuration. (line 12) * event scheduler, thread states: event-scheduler-thread-states. (line 6) * Event Scheduler, time representation: events-metadata. (line 21) * event severity levels (MySQL Cluster): mysql-cluster-logging-management-commands. (line 62) * event types (MySQL Cluster) <1>: mysql-cluster-log-events. (line 20) * event types (MySQL Cluster): mysql-cluster-event-reports. (line 49) * event, restrictions: stored-program-restrictions. (line 6) * event-scheduler option, mysqld: server-options. (line 730) * event_scheduler system variable: server-system-variables. (line 1503) * events <1>: events. (line 15) * events: stored-programs-views. (line 16) * events option, mysqldump: mysqldump. (line 553) * events, altering: alter-event. (line 6) * events, creating: create-event. (line 6) * events, dropping: drop-event. (line 6) * EVENTS, INFORMATION_SCHEMA table <1>: events-table. (line 6) * EVENTS, INFORMATION_SCHEMA table: events-privileges. (line 71) * events, metadata: events-metadata. (line 6) * events, status variables: events-privileges. (line 184) * exact-value literals: precision-math. (line 14) * example option, mysqld_multi: mysqld-multi. (line 114) * example programs, C API: c-api-example-programs. (line 6) * EXAMPLE storage engine <1>: example-storage-engine. (line 6) * EXAMPLE storage engine: storage-engines. (line 23) * examples, compressed tables: myisampack. (line 122) * examples, myisamchk output: myisamchk-table-info. (line 6) * examples, queries: examples. (line 18) * exclude-databases option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 749) * exclude-missing-columns option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 873) * exclude-tables option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 760) * exe-suffix option, make_win_bin_dist: make-win-bin-dist. (line 46) * EXECUTE <1>: execute. (line 6) * EXECUTE: sql-syntax-prepared-statements. (line 13) * execute option (ndb_mgm): mysql-cluster-programs-ndb-mgm. (line 48) * execute option, mysql: mysql-command-options. (line 270) * Execute, thread command: thread-commands. (line 52) * ExecuteNonQuery method: connector-net-tutorials-sql-command. (line 6) * ExecuteOnComputer <1>: mysql-cluster-api-definition. (line 90) * ExecuteOnComputer <2>: mysql-cluster-ndbd-definition. (line 108) * ExecuteOnComputer: mysql-cluster-mgm-definition. (line 81) * ExecuteReader method: connector-net-tutorials-sql-command. (line 6) * ExecuteScalar method: connector-net-tutorials-sql-command. (line 6) * executing SQL statements from text files <1>: mysql-batch-commands. (line 6) * executing SQL statements from text files: batch-mode. (line 6) * executing, thread state: general-thread-states. (line 117) * Execution of init_command, thread state: general-thread-states. (line 121) * execution threads (MySQL Cluster): mysql-cluster-ndbd-definition. (line 3244) * EXISTS, with subqueries: exists-and-not-exists-subqueries. (line 6) * EXIT command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 194) * exit command, mysql: mysql-commands. (line 131) * EXIT SINGLE USER MODE command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 184) * exit-info option, mysqld: server-options. (line 756) * EXP(): mathematical-functions. (line 195) * expire_logs_days system variable: server-system-variables. (line 1531) * EXPLAIN <1>: explain. (line 6) * EXPLAIN: using-explain. (line 6) * EXPLAIN PARTITIONS: partitioning-info. (line 6) * EXPLAIN used with partitioned tables: partitioning-info. (line 6) * explicit default values: data-type-defaults. (line 6) * EXPORT_SET(): string-functions. (line 245) * expression aliases <1>: select. (line 108) * expression aliases: group-by-extensions. (line 83) * expression syntax: expressions. (line 6) * expressions, extended: pattern-matching. (line 6) * extend-check option, myisamchk <1>: myisamchk-repair-options. (line 28) * extend-check option, myisamchk: myisamchk-check-options. (line 18) * extended option, mysqlcheck: mysqlcheck. (line 291) * extended-insert option, mysqldump: mysqldump. (line 558) * extensions, to standard SQL: compatibility. (line 15) * ExteriorRing(): polygon-property-functions. (line 21) * external locking <1>: general-thread-states. (line 316) * external locking <2>: external-locking. (line 6) * external locking <3>: myisam-crash-recovery. (line 6) * external locking <4>: server-system-variables. (line 4869) * external locking: server-options. (line 773) * external-locking option, mysqld: server-options. (line 773) * extra-file option, my_print_defaults: my-print-defaults. (line 43) * extra-node-info option, ndb_desc: mysql-cluster-programs-ndb-desc. (line 297) * extra-partition-info option, ndb_desc: mysql-cluster-programs-ndb-desc. (line 311) * EXTRACT(): date-and-time-functions. (line 545) * extracting, dates: date-calculations. (line 6) * ExtractValue(): xml-functions. (line 150) * ExtraSendBufferMemory, API nodes: mysql-cluster-api-definition. (line 199) * ExtraSendBufferMemory, data nodes: mysql-cluster-ndbd-definition. (line 3856) * ExtraSendBufferMemory, management nodes: mysql-cluster-mgm-definition. (line 268) * failover, in MySQL Cluster replication: mysql-cluster-replication-failover. (line 6) * failover, Java clients <1>: connector-j-reference-configuration-properties. (line 77) * failover, Java clients: mysql-cluster-basics. (line 116) * FALSE <1>: boolean-literals. (line 6) * FALSE: number-literals. (line 6) * FALSE, testing for: comparison-operators. (line 130) * FAQs, Connector/ODBC: connector-odbc-usagenotes. (line 12) * fast option, myisamchk: myisamchk-check-options. (line 35) * fast option, mysqlcheck: mysqlcheck. (line 300) * fatal signal 11: compilation-problems. (line 37) * features of MySQL: features. (line 6) * FEDERATED storage engine <1>: federated-storage-engine. (line 13) * FEDERATED storage engine: storage-engines. (line 23) * FETCH: fetch. (line 6) * Fetch, thread command: thread-commands. (line 56) * Field List, thread command: thread-commands. (line 61) * FIELD(): string-functions. (line 263) * field, changing: alter-table. (line 335) * fields option, ndb_config: mysql-cluster-programs-ndb-config. (line 342) * fields-enclosed-by option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 495) * fields-enclosed-by option, mysqldump <1>: mysqlimport. (line 187) * fields-enclosed-by option, mysqldump: mysqldump. (line 566) * fields-escaped-by option, mysqldump <1>: mysqlimport. (line 191) * fields-escaped-by option, mysqldump: mysqldump. (line 570) * fields-optionally-enclosed-by option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 510) * fields-optionally-enclosed-by option, mysqldump <1>: mysqlimport. (line 189) * fields-optionally-enclosed-by option, mysqldump: mysqldump. (line 568) * fields-terminated-by option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 527) * fields-terminated-by option, mysqldump <1>: mysqlimport. (line 185) * fields-terminated-by option, mysqldump: mysqldump. (line 564) * FILE: string-functions. (line 384) * files, binary log: binary-log. (line 13) * files, config.cache: compilation-problems. (line 6) * files, error messages: error-message-language. (line 6) * files, general query log: query-log. (line 6) * FILES, INFORMATION_SCHEMA table: files-table. (line 6) * files, log <1>: log-file-maintenance. (line 6) * files, log: source-configuration-options. (line 6) * files, my.cnf: replication-features. (line 45) * files, not found message: file-permissions. (line 6) * files, permissions: file-permissions. (line 6) * files, repairing: myisamchk-repair-options. (line 6) * files, script: batch-mode. (line 6) * files, size limits: table-size-limit. (line 6) * files, slow query log: slow-query-log. (line 6) * files, text <1>: mysqlimport. (line 6) * files, text: mysql-batch-commands. (line 6) * files, tmp: mysql-install-db-problems. (line 70) * filesort optimization: order-by-optimization. (line 125) * FileSystemPath: mysql-cluster-ndbd-definition. (line 274) * FileSystemPathDataFiles: mysql-cluster-ndbd-definition. (line 3582) * FileSystemPathDD: mysql-cluster-ndbd-definition. (line 3547) * FileSystemPathUndoFiles: mysql-cluster-ndbd-definition. (line 3612) * FIND_IN_SET(): string-functions. (line 282) * Finished reading one binlog; switching to next binlog, thread state: master-thread-states. (line 17) * firewalls (software), and MySQL Cluster: mysql-cluster-security-networking-issues. (line 98) * first-slave option, mysqldump: mysqldump. (line 576) * fix-db-names option, mysqlcheck: mysqlcheck. (line 304) * fix-table-names option, mysqlcheck: mysqlcheck. (line 310) * FIXED data type: numeric-type-overview. (line 186) * fixed-point arithmetic: precision-math. (line 14) * FLOAT data type: numeric-type-overview. (line 194) * floating-point number: numeric-type-overview. (line 241) * floating-point values, and replication: replication-features-floatvalues. (line 6) * floats: number-literals. (line 6) * FLOOR(): mathematical-functions. (line 208) * FLUSH: flush. (line 6) * flush option, mysqld: server-options. (line 798) * flush system variable: server-system-variables. (line 1558) * flush tables: mysqladmin. (line 187) * FLUSH, and replication: replication-features-flush. (line 6) * flush-logs option, mysqldump: mysqldump. (line 581) * flush-privileges option, mysqldump: mysqldump. (line 593) * flush_time system variable: server-system-variables. (line 1581) * Flushing tables, thread state: general-thread-states. (line 132) * flushlog option, mysqlhotcopy: mysqlhotcopy. (line 114) * FOR UPDATE: select. (line 336) * FORCE INDEX <1>: optimizer-issues. (line 27) * FORCE INDEX: index-hints. (line 6) * FORCE KEY: index-hints. (line 6) * force option, myisamchk <1>: myisamchk-repair-options. (line 40) * force option, myisamchk: myisamchk-check-options. (line 39) * force option, myisampack: myisampack. (line 66) * force option, mysql: mysql-command-options. (line 277) * force option, mysql_convert_table_format: mysql-convert-table-format. (line 28) * force option, mysql_install_db: mysql-install-db. (line 64) * force option, mysql_upgrade: mysql-upgrade. (line 140) * force option, mysqladmin: mysqladmin. (line 350) * force option, mysqlcheck: mysqlcheck. (line 316) * force option, mysqldump: mysqldump. (line 601) * force option, mysqlimport: mysqlimport. (line 196) * force-if-open option, mysqlbinlog: mysqlbinlog. (line 362) * force-read option, mysqlbinlog: mysqlbinlog. (line 367) * foreign key constraints: create-table-foreign-keys. (line 6) * foreign key constraints, InnoDB: innodb-foreign-key-constraints. (line 6) * foreign key constraints, restrictions: innodb-foreign-key-constraints. (line 6) * foreign key, constraint <1>: constraint-foreign-key. (line 6) * foreign key, constraint: constraint-primary-key. (line 6) * foreign key, deleting <1>: create-table-foreign-keys. (line 210) * foreign key, deleting: alter-table. (line 468) * foreign keys <1>: connector-net-visual-studio-editing-tables-foreign-keys. (line 6) * foreign keys <2>: alter-table. (line 438) * foreign keys <3>: example-foreign-keys. (line 6) * foreign keys: ansi-diff-foreign-keys. (line 6) * foreign_key_checks session variable: server-system-variables. (line 1603) * FORMAT(): string-functions. (line 297) * Forums: forums. (line 6) * FOUND_ROWS(): information-functions. (line 220) * FragmentLogFileSize: mysql-cluster-ndbd-definition. (line 1120) * FreeBSD troubleshooting: compilation-problems. (line 136) * freeing items, thread state: general-thread-states. (line 126) * frequently-asked questions about MySQL Cluster: faqs-mysql-cluster. (line 6) * FROM: select. (line 136) * FROM_DAYS(): date-and-time-functions. (line 561) * FROM_UNIXTIME(): date-and-time-functions. (line 572) * ft_boolean_syntax system variable: server-system-variables. (line 1624) * ft_max_word_len myisamchk variable: myisamchk-general-options. (line 53) * ft_max_word_len system variable: server-system-variables. (line 1663) * ft_min_word_len myisamchk variable: myisamchk-general-options. (line 53) * ft_min_word_len system variable: server-system-variables. (line 1687) * ft_query_expansion_limit system variable: server-system-variables. (line 1712) * ft_stopword_file myisamchk variable: myisamchk-general-options. (line 53) * ft_stopword_file system variable: server-system-variables. (line 1733) * full disk: full-disk. (line 6) * full-text parser plugins: full-text-plugins. (line 6) * full-text search: fulltext-search. (line 16) * FULLTEXT: fulltext-search. (line 16) * FULLTEXT initialization, thread state: general-thread-states. (line 137) * fulltext join type, optimizer: explain-output. (line 300) * fulltext, stopword list: fulltext-fine-tuning. (line 40) * function names, parsing: function-resolution. (line 6) * function names, resolving ambiguity: function-resolution. (line 6) * function, creating: create-function-udf. (line 6) * function, deleting: drop-function-udf. (line 6) * functions: functions. (line 27) * functions, and replication: replication-features-functions. (line 6) * functions, arithmetic: bit-functions. (line 6) * functions, bit: bit-functions. (line 6) * functions, C API: c-api-function-overview. (line 6) * functions, C prepared statement API <1>: c-api-prepared-statement-function-overview. (line 6) * functions, C prepared statement API: c-api-prepared-statement-type-conversions. (line 6) * functions, cast: cast-functions. (line 6) * functions, control flow: control-flow-functions. (line 6) * functions, date and time: date-and-time-functions. (line 6) * functions, encryption: encryption-functions. (line 6) * functions, for SELECT and WHERE clauses: functions. (line 27) * functions, GROUP BY: group-by-functions. (line 6) * functions, grouping: operator-precedence. (line 48) * functions, information: information-functions. (line 6) * functions, mathematical: mathematical-functions. (line 52) * functions, miscellaneous: miscellaneous-functions. (line 6) * functions, native, adding: adding-native-function. (line 6) * functions, new: adding-functions. (line 12) * functions, stored: stored-routines. (line 13) * functions, string: string-functions. (line 11) * functions, string comparison: string-comparison-functions. (line 6) * functions, user-defined <1>: adding-functions. (line 12) * functions, user-defined <2>: drop-function-udf. (line 6) * functions, user-defined: create-function-udf. (line 6) * functions, user-defined, adding: adding-udf. (line 15) * gap event: mysql-cluster-replication-issues. (line 35) * gap lock, InnoDB <1>: innodb-next-key-locking. (line 6) * gap lock, InnoDB <2>: innodb-record-level-locks. (line 6) * gap lock, InnoDB <3>: innodb-transaction-model. (line 74) * gap lock, InnoDB: innodb-parameters. (line 1122) * gb2312, gbk: faqs-cjk. (line 6) * gcc: source-configuration-options. (line 397) * gci option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 126) * GCP Stop errors (MySQL Cluster): mysql-cluster-ndbd-definition. (line 3784) * gdb option, mysqld: server-options. (line 819) * gdb, using: using-gdb-on-mysqld. (line 6) * general information: introduction. (line 18) * General Public License: what-is-mysql. (line 54) * general query log: query-log. (line 6) * general-log option, mysqld: server-options. (line 835) * general_log system variable: server-system-variables. (line 1764) * general_log_file system variable: server-system-variables. (line 1789) * geographic feature: gis-introduction. (line 27) * GeomCollFromText(): gis-wkt-functions. (line 14) * GeomCollFromWKB(): gis-wkb-functions. (line 17) * geometry: gis-introduction. (line 40) * GEOMETRY data type: mysql-spatial-datatypes. (line 6) * GEOMETRYCOLLECTION data type: mysql-spatial-datatypes. (line 6) * GeometryCollection(): gis-mysql-specific-functions. (line 31) * GeometryCollectionFromText(): gis-wkt-functions. (line 14) * GeometryCollectionFromWKB(): gis-wkb-functions. (line 17) * GeometryFromText(): gis-wkt-functions. (line 20) * GeometryFromWKB(): gis-wkb-functions. (line 23) * GeometryN(): geometrycollection-property-functions. (line 8) * GeometryType(): general-geometry-property-functions. (line 38) * GeomFromText() <1>: functions-to-convert-geometries-between-formats. (line 29) * GeomFromText(): gis-wkt-functions. (line 20) * GeomFromWKB() <1>: functions-to-convert-geometries-between-formats. (line 36) * GeomFromWKB(): gis-wkb-functions. (line 23) * geospatial feature: gis-introduction. (line 37) * GET_FORMAT(): date-and-time-functions. (line 600) * GET_LOCK(): miscellaneous-functions. (line 42) * getting MySQL: getting-mysql. (line 6) * GIS <1>: gis-introduction. (line 6) * GIS: spatial-extensions. (line 16) * Glassfish application server: connector-j-usagenotes-glassfish-config. (line 11) * GLength() <1>: multilinestring-property-functions. (line 8) * GLength(): linestring-property-functions. (line 23) * global privileges <1>: revoke. (line 6) * global privileges: grant. (line 6) * GLOBAL_STATUS, INFORMATION_SCHEMA table: status-table. (line 6) * GLOBAL_VARIABLES, INFORMATION_SCHEMA table: variables-table. (line 6) * globalization: globalization. (line 16) * go command, mysql: mysql-commands. (line 135) * got handler lock, thread state: delayed-insert-thread-states. (line 26) * got old table, thread state: delayed-insert-thread-states. (line 32) * GRANT: grant. (line 6) * GRANT statement: adding-users. (line 6) * grant table distribution (MySQL Cluster): mysql-cluster-privilege-distribution. (line 6) * grant tables, re-creating: mysql-install-db-problems. (line 104) * grant tables, sorting <1>: request-access. (line 51) * grant tables, sorting: connection-access. (line 126) * grant tables, structure: grant-table-structure. (line 6) * grant tables, upgrading: mysql-fix-privilege-tables. (line 6) * granting, privileges: grant. (line 6) * GRANTS: show-grants. (line 6) * greater than (>): comparison-operators. (line 123) * greater than or equal (>=): comparison-operators. (line 116) * greatest timestamp wins (conflict resolution): mysql-cluster-replication-conflict-resolution. (line 279) * greatest timestamp, delete wins (conflict resolution): mysql-cluster-replication-conflict-resolution. (line 305) * GREATEST(): comparison-operators. (line 237) * GROUP BY: group-by-optimization. (line 11) * GROUP BY functions: group-by-functions. (line 6) * GROUP BY, aliases in: group-by-extensions. (line 83) * GROUP BY, extensions to standard SQL <1>: select. (line 206) * GROUP BY, extensions to standard SQL: group-by-extensions. (line 6) * GROUP_CONCAT(): group-by-functions. (line 137) * group_concat_max_len system variable: server-system-variables. (line 1813) * grouping, expressions: operator-precedence. (line 48) * HANDLER: handler. (line 6) * Handlers: declare-handler. (line 6) * handling, errors: udf-return-values. (line 6) * Has read all relay log; waiting for the slave I/O thread to update it, thread state: slave-sql-thread-states. (line 18) * Has sent all binlog to slave; waiting for binlog to be updated, thread state: master-thread-states. (line 22) * hash partitioning: partitioning-hash. (line 10) * hash partitions, managing: partitioning-management-hash-key. (line 6) * hash partitions, splitting and merging: partitioning-management-hash-key. (line 6) * have_archive system variable: server-system-variables. (line 1843) * have_blackhole_engine system variable: server-system-variables. (line 1848) * have_community_features system variable: server-system-variables. (line 1859) * have_compress system variable: server-system-variables. (line 1853) * have_crypt system variable: server-system-variables. (line 1868) * have_csv system variable: server-system-variables. (line 1873) * have_dynamic_loading system variable: server-system-variables. (line 1882) * have_example_engine system variable: server-system-variables. (line 1887) * have_federated_engine system variable: server-system-variables. (line 1892) * have_geometry system variable: server-system-variables. (line 1897) * have_innodb system variable: server-system-variables. (line 1901) * have_isam system variable: server-system-variables. (line 1909) * have_merge_engine system variable: server-system-variables. (line 1915) * have_openssl system variable: server-system-variables. (line 1921) * have_partitioning system variable: server-system-variables. (line 1926) * have_query_cache system variable: server-system-variables. (line 1935) * have_raid system variable: server-system-variables. (line 1959) * have_row_based_replication system variable: server-system-variables. (line 1940) * have_rtree_keys system variable: server-system-variables. (line 1965) * have_ssl system variable: server-system-variables. (line 1970) * have_symlink system variable: server-system-variables. (line 1980) * HAVING: select. (line 220) * header option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 99) * header_file option, comp_err: comp-err. (line 43) * HEAP storage engine <1>: memory-storage-engine. (line 6) * HEAP storage engine: storage-engines. (line 23) * HeartbeatIntervalDbApi: mysql-cluster-ndbd-definition. (line 1897) * HeartbeatIntervalDbDb: mysql-cluster-ndbd-definition. (line 1869) * HeartbeatOrder: mysql-cluster-ndbd-definition. (line 1923) * HeartbeatThreadPriority <1>: mysql-cluster-api-definition. (line 215) * HeartbeatThreadPriority: mysql-cluster-mgm-definition. (line 250) * HELP command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 34) * help command, mysql: mysql-commands. (line 51) * help option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 88) * help option, comp_err: comp-err. (line 25) * help option, my_print_defaults: my-print-defaults. (line 25) * help option, myisam_ftdump: myisam-ftdump. (line 58) * HELP option, myisamchk: myisamchk-general-options. (line 16) * help option, myisamchk: myisamchk-general-options. (line 11) * help option, myisampack: myisampack. (line 47) * help option, mysql: mysql-command-options. (line 155) * help option, mysql_convert_table_format: mysql-convert-table-format. (line 24) * help option, mysql_find_rows: mysql-find-rows. (line 31) * help option, mysql_setpermission: mysql-setpermission. (line 29) * help option, mysql_upgrade: mysql-upgrade. (line 116) * help option, mysql_waitpid: mysql-waitpid. (line 27) * help option, mysqlaccess: mysqlaccess. (line 67) * help option, mysqladmin: mysqladmin. (line 299) * help option, mysqlbinlog: mysqlbinlog. (line 174) * help option, mysqlcheck: mysqlcheck. (line 200) * help option, mysqld: server-options. (line 72) * help option, mysqld_multi: mysqld-multi. (line 96) * help option, mysqld_safe: mysqld-safe. (line 121) * help option, mysqldump: mysqldump. (line 350) * help option, mysqldumpslow: mysqldumpslow. (line 45) * help option, mysqlhotcopy: mysqlhotcopy. (line 81) * help option, mysqlimport: mysqlimport. (line 126) * help option, mysqlmanager: instance-manager-command-options. (line 23) * help option, mysqlshow: mysqlshow. (line 110) * help option, mysqlslap: mysqlslap. (line 209) * help option, perror: perror. (line 40) * help option, resolve_stack_dump: resolve-stack-dump. (line 21) * help option, resolveip: resolveip. (line 15) * HELP statement: help. (line 6) * hex option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 543) * HEX() <1>: mathematical-functions. (line 227) * HEX(): string-functions. (line 310) * hex-blob option, mysqldump: mysqldump. (line 619) * hexadecimal literals: hexadecimal-literals. (line 6) * hexdump option, mysqlbinlog: mysqlbinlog. (line 374) * HIGH_NOT_PRECEDENCE SQL mode: server-sql-mode. (line 153) * HIGH_PRIORITY: select. (line 355) * hints: extensions-to-ansi. (line 6) * hints, index <1>: index-hints. (line 6) * hints, index: select. (line 144) * history of MySQL: history. (line 6) * HOME environment variable <1>: mysql-logging. (line 6) * HOME environment variable: environment-variables. (line 18) * host name caching: host-cache. (line 6) * host name resolution: host-cache. (line 6) * host name, default: connecting. (line 6) * host option: connecting. (line 129) * host option, mysql: mysql-command-options. (line 281) * host option, mysql_convert_table_format: mysql-convert-table-format. (line 32) * host option, mysql_setpermission: mysql-setpermission. (line 33) * host option, mysqlaccess: mysqlaccess. (line 94) * host option, mysqladmin: mysqladmin. (line 355) * host option, mysqlbinlog: mysqlbinlog. (line 380) * host option, mysqlcheck: mysqlcheck. (line 320) * host option, mysqldump: mysqldump. (line 614) * host option, mysqlhotcopy: mysqlhotcopy. (line 118) * host option, mysqlimport: mysqlimport. (line 202) * host option, mysqlshow: mysqlshow. (line 160) * host option, mysqlslap: mysqlslap. (line 334) * host option, ndb_config: mysql-cluster-programs-ndb-config. (line 225) * host table: request-access. (line 148) * host table, sorting: request-access. (line 51) * Host*SciId* parameters: mysql-cluster-sci-definition. (line 48) * host.frm, problems finding: unix-postinstallation. (line 216) * HostName <1>: mysql-cluster-api-definition. (line 102) * HostName <2>: mysql-cluster-ndbd-definition. (line 120) * HostName: mysql-cluster-mgm-definition. (line 105) * HostName (MySQL Cluster): mysql-cluster-security-networking-issues. (line 40) * hostname system variable: server-system-variables. (line 1988) * HostName1 <1>: mysql-cluster-sci-definition. (line 98) * HostName1 <2>: mysql-cluster-shm-definition. (line 47) * HostName1: mysql-cluster-tcp-definition. (line 61) * HostName2 <1>: mysql-cluster-sci-definition. (line 108) * HostName2 <2>: mysql-cluster-shm-definition. (line 57) * HostName2: mysql-cluster-tcp-definition. (line 71) * HOUR(): date-and-time-functions. (line 640) * howto option, mysqlaccess: mysqlaccess. (line 98) * html option, mysql: mysql-command-options. (line 285) * i-am-a-dummy option, mysql: mysql-command-options. (line 469) * i5/OS: i5os-installation. (line 6) * IBM i5/OS: i5os-installation. (line 6) * IBMDB2I storage engine: storage-engines. (line 23) * icc, and MySQL Cluster support>: porting. (line 32) * icc, MySQL builds: compiler-characteristics. (line 6) * Id <1>: mysql-cluster-api-definition. (line 26) * Id <2>: mysql-cluster-ndbd-definition. (line 64) * Id: mysql-cluster-mgm-definition. (line 16) * id option, ndb_config: mysql-cluster-programs-ndb-config. (line 254) * ID, unique: getting-unique-id. (line 6) * identifiers: identifiers. (line 13) * identifiers, case sensitivity: identifier-case-sensitivity. (line 6) * identifiers, quoting: identifiers. (line 20) * identity session variable: server-system-variables. (line 2004) * IF: if. (line 6) * IF(): control-flow-functions. (line 48) * IFNULL(): control-flow-functions. (line 86) * IGNORE INDEX: index-hints. (line 6) * IGNORE KEY: index-hints. (line 6) * ignore option, mysqlimport: mysqlimport. (line 207) * IGNORE, with partitioned tables: insert. (line 264) * ignore-builtin-innodb option, mysqld: innodb-parameters. (line 135) * ignore-lines option, mysqlimport: mysqlimport. (line 211) * ignore-spaces option, mysql: mysql-command-options. (line 289) * ignore-table option, mysqldump: mysqldump. (line 626) * ignore_builtin_innodb system variable: innodb-parameters. (line 214) * IGNORE_SPACE SQL mode: server-sql-mode. (line 168) * implicit default values: data-type-defaults. (line 6) * IMPORT TABLESPACE <1>: innodb-multiple-tablespaces. (line 168) * IMPORT TABLESPACE: alter-table. (line 479) * importing, data <1>: mysqlimport. (line 6) * importing, data: mysql-batch-commands. (line 6) * IN <1>: any-in-some-subqueries. (line 6) * IN: comparison-operators. (line 252) * in_file option, comp_err: comp-err. (line 47) * include option, mysql_config: mysql-config. (line 22) * include-databases option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 670) * include-tables option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 681) * increasing with replication, speed: replication. (line 13) * incremental recovery: point-in-time-recovery. (line 11) * incremental recovery, using MySQL Cluster replication: mysql-cluster-replication-pitr. (line 6) * INDEX DIRECTORY, and replication: replication-features-directory. (line 6) * index hints <1>: index-hints. (line 6) * index hints: select. (line 144) * index join type, optimizer: explain-output. (line 366) * index, deleting <1>: drop-index. (line 6) * index, deleting: alter-table. (line 342) * index, rebuilding: rebuilding-tables. (line 6) * index-record lock, InnoDB <1>: innodb-next-key-locking. (line 6) * index-record lock, InnoDB <2>: innodb-record-level-locks. (line 6) * index-record lock, InnoDB <3>: innodb-transaction-model. (line 74) * index-record lock, InnoDB: innodb-parameters. (line 1122) * index_merge join type, optimizer: explain-output. (line 317) * index_subquery join type, optimizer: explain-output. (line 335) * indexes: create-index. (line 6) * indexes, and BLOB columns <1>: create-table. (line 524) * indexes, and BLOB columns: column-indexes. (line 15) * indexes, and IS NULL: mysql-indexes. (line 137) * indexes, and LIKE: mysql-indexes. (line 111) * indexes, and NULL values: create-table. (line 503) * indexes, and TEXT columns <1>: create-table. (line 524) * indexes, and TEXT columns: column-indexes. (line 15) * indexes, assigning to key cache: cache-index. (line 6) * indexes, block size: server-system-variables. (line 2204) * indexes, columns: column-indexes. (line 6) * indexes, leftmost prefix of <1>: mysql-indexes. (line 88) * indexes, leftmost prefix of: multiple-column-indexes. (line 83) * indexes, multi-column: multiple-column-indexes. (line 6) * indexes, multiple-part: create-index. (line 6) * indexes, names: identifiers. (line 13) * indexes, use of: mysql-indexes. (line 6) * Indexes/Keys dialog: connector-net-visual-studio-editing-tables-indexes. (line 6) * IndexMemory <1>: mysql-cluster-config-lcp-params. (line 6) * IndexMemory: mysql-cluster-ndbd-definition. (line 453) * INET_ATON(): miscellaneous-functions. (line 102) * INET_NTOA(): miscellaneous-functions. (line 128) * INFO Events (MySQL Cluster): mysql-cluster-log-events. (line 237) * information functions: information-functions. (line 6) * information option, myisamchk: myisamchk-check-options. (line 45) * INFORMATION_SCHEMA: information-schema. (line 36) * INFORMATION_SCHEMA plugins: information-schema-plugins. (line 6) * INFORMATION_SCHEMA, and security issues: mysql-cluster-security-mysql-privileges. (line 117) * INFORMATION_SCHEMA, collation and searching: charset-collation-information-schema. (line 6) * INFORMATION_SCHEMA.ENGINES table, and MySQL Cluster: mysql-cluster-sql-statements. (line 35) * INFORMATION_SCHEMA.GLOBAL_STATUS table, and MySQL Cluster: mysql-cluster-sql-statements. (line 159) * INFORMATION_SCHEMA.GLOBAL_VARIABLES table, and MySQL Cluster: mysql-cluster-sql-statements. (line 84) * Init DB, thread command: thread-commands. (line 65) * init, thread state: general-thread-states. (line 142) * init-file option, mysqld: server-options. (line 857) * init_connect system variable: server-system-variables. (line 2011) * init_file system variable: server-system-variables. (line 2051) * init_slave system variable: replication-options-slave. (line 1380) * InitFragmentLogFiles: mysql-cluster-ndbd-definition. (line 1143) * initial option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 303) * initial option (ndbd): mysql-cluster-programs-ndbd. (line 173) * initial option (ndbmtd): mysql-cluster-programs-ndbd. (line 173) * initial-start option (ndbd): mysql-cluster-programs-ndbd. (line 233) * initial-start option (ndbmtd): mysql-cluster-programs-ndbd. (line 233) * Initialized, thread state: event-scheduler-thread-states. (line 15) * InitialLogFileGroup: mysql-cluster-ndbd-definition. (line 3651) * InitialNoOfOpenFiles: mysql-cluster-ndbd-definition. (line 1191) * InitialTablespace: mysql-cluster-ndbd-definition. (line 3722) * INNER JOIN: join. (line 6) * innochecksum <1>: innochecksum. (line 6) * innochecksum: programs-overview. (line 165) * InnoDB: innodb-storage-engine. (line 22) * InnoDB buffer pool: innodb-buffer-pool. (line 6) * innodb option, mysqld: innodb-parameters. (line 172) * InnoDB storage engine <1>: innodb-storage-engine. (line 22) * InnoDB storage engine: storage-engines. (line 23) * InnoDB tables: ansi-diff-transactions. (line 6) * InnoDB, adaptive hash index: innodb-adaptive-hash. (line 6) * InnoDB, and application feature requirements: mysql-cluster-ndb-innodb-usage. (line 6) * InnoDB, applications supported: mysql-cluster-ndb-innodb-workloads. (line 6) * InnoDB, auto-increment columns: innodb-auto-increment-handling. (line 11) * InnoDB, autocommit mode <1>: innodb-implicit-commit. (line 6) * InnoDB, autocommit mode: innodb-transactions-with-different-apis. (line 6) * InnoDB, availability: mysql-cluster-compared. (line 36) * InnoDB, backups: innodb-backup. (line 12) * InnoDB, clustered index: innodb-index-types. (line 6) * InnoDB, compared to MySQL Cluster <1>: mysql-cluster-ndb-innodb-usage. (line 6) * InnoDB, compared to MySQL Cluster <2>: mysql-cluster-ndb-innodb-workloads. (line 6) * InnoDB, compared to MySQL Cluster <3>: mysql-cluster-ndb-innodb-engines. (line 6) * InnoDB, compared to MySQL Cluster: mysql-cluster-compared. (line 12) * InnoDB, configuration parameters: innodb-parameters. (line 6) * InnoDB, configuring data files and memory allocation: innodb-configuration. (line 14) * InnoDB, consistent reads: innodb-consistent-read. (line 6) * InnoDB, crash recovery: innodb-recovery. (line 6) * InnoDB, data files: innodb-data-log-reconfiguration. (line 6) * InnoDB, deadlock detection: innodb-deadlock-detection. (line 6) * InnoDB, foreign key constraints: innodb-foreign-key-constraints. (line 6) * InnoDB, gap lock <1>: innodb-next-key-locking. (line 6) * InnoDB, gap lock <2>: innodb-record-level-locks. (line 6) * InnoDB, gap lock <3>: innodb-transaction-model. (line 74) * InnoDB, gap lock: innodb-parameters. (line 1122) * InnoDB, index-record lock <1>: innodb-next-key-locking. (line 6) * InnoDB, index-record lock <2>: innodb-record-level-locks. (line 6) * InnoDB, index-record lock <3>: innodb-transaction-model. (line 74) * InnoDB, index-record lock: innodb-parameters. (line 1122) * InnoDB, indexes: innodb-table-and-index. (line 14) * InnoDB, insert buffering: innodb-insert-buffering. (line 6) * InnoDB, limits and restrictions: innodb-restrictions. (line 6) * InnoDB, lock modes: innodb-lock-modes. (line 6) * InnoDB, locking: innodb-transaction-model. (line 18) * InnoDB, locking reads: innodb-locking-reads. (line 6) * InnoDB, log files: innodb-data-log-reconfiguration. (line 6) * InnoDB, migrating tables: innodb-migration. (line 6) * InnoDB, Monitors <1>: innodb-troubleshooting-datadict. (line 61) * InnoDB, Monitors <2>: innodb-troubleshooting. (line 26) * InnoDB, Monitors <3>: innodb-monitors. (line 12) * InnoDB, Monitors <4>: innodb-file-space. (line 48) * InnoDB, Monitors: innodb-backup. (line 120) * InnoDB, multi-versioning: innodb-multi-versioning. (line 6) * InnoDB, next-key lock <1>: innodb-next-key-locking. (line 6) * InnoDB, next-key lock <2>: innodb-record-level-locks. (line 6) * InnoDB, next-key lock <3>: innodb-transaction-model. (line 74) * InnoDB, next-key lock: innodb-parameters. (line 1122) * InnoDB, NFS <1>: innodb-restrictions. (line 16) * InnoDB, NFS: innodb-configuration. (line 73) * InnoDB, page size <1>: innodb-restrictions. (line 75) * InnoDB, page size: innodb-physical-structure. (line 6) * InnoDB, raw partitions: innodb-raw-devices. (line 6) * InnoDB, record-level locks <1>: innodb-next-key-locking. (line 6) * InnoDB, record-level locks <2>: innodb-record-level-locks. (line 6) * InnoDB, record-level locks <3>: innodb-transaction-model. (line 74) * InnoDB, record-level locks: innodb-parameters. (line 1122) * InnoDB, replication: innodb-and-mysql-replication. (line 6) * InnoDB, row structure: innodb-physical-record. (line 6) * InnoDB, secondary index: innodb-index-types. (line 6) * InnoDB, semi-consistent read: innodb-parameters. (line 1122) * InnoDB, Solaris 10 x86_64 issues: solaris-installation. (line 11) * InnoDB, system variables: innodb-parameters. (line 6) * InnoDB, tables <1>: innodb-table-and-index. (line 14) * InnoDB, tables: using-innodb-tables. (line 14) * InnoDB, tables, converting from other storage engines: converting-tables-to-innodb. (line 6) * InnoDB, transaction model: innodb-transaction-model. (line 18) * InnoDB, troubleshooting, data dictionary problems: innodb-troubleshooting-datadict. (line 6) * InnoDB, troubleshooting, deadlocks: innodb-deadlock-detection. (line 6) * InnoDB, troubleshooting, InnoDB error codes: innodb-error-codes. (line 6) * InnoDB, troubleshooting, OS error codes: operating-system-error-codes. (line 6) * InnoDB, troubleshooting, recovery problems: forcing-innodb-recovery. (line 6) * InnoDB, troubleshooting, SQL errors: innodb-error-handling. (line 11) * innodb-status-file option, mysqld: innodb-parameters. (line 186) * innodb_adaptive_flushing system variable: innodb-parameters. (line 236) * innodb_adaptive_hash_index system variable: innodb-parameters. (line 262) * innodb_additional_mem_pool_size system variable: innodb-parameters. (line 288) * innodb_autoextend_increment system variable: innodb-parameters. (line 319) * innodb_buffer_pool_size system variable: innodb-parameters. (line 413) * innodb_change_buffering system variable: innodb-parameters. (line 483) * innodb_checksums system variable: innodb-parameters. (line 509) * innodb_commit_concurrency system variable: innodb-parameters. (line 532) * innodb_concurrency_tickets system variable: innodb-parameters. (line 558) * innodb_data_file_path system variable: innodb-parameters. (line 587) * innodb_data_home_dir system variable: innodb-parameters. (line 618) * innodb_doublewrite system variable: innodb-parameters. (line 641) * innodb_fast_shutdown system variable: innodb-parameters. (line 663) * innodb_file_format system variable: innodb-parameters. (line 692) * innodb_file_format_check system variable: innodb-parameters. (line 717) * innodb_file_per_table system variable: innodb-parameters. (line 777) * innodb_flush_log_at_trx_commit system variable: innodb-parameters. (line 805) * innodb_flush_method system variable: innodb-parameters. (line 865) * innodb_force_recovery system variable: innodb-parameters. (line 938) * innodb_io_capacity system variable: innodb-parameters. (line 974) * innodb_locks_unsafe_for_binlog system variable: innodb-parameters. (line 1106) * innodb_log_buffer_size system variable: innodb-parameters. (line 1305) * innodb_log_file_size system variable: innodb-parameters. (line 1332) * innodb_log_files_in_group system variable: innodb-parameters. (line 1362) * innodb_log_group_home_dir system variable: innodb-parameters. (line 1384) * innodb_max_dirty_pages_pct system variable: innodb-parameters. (line 1406) * innodb_max_purge_lag system variable: innodb-parameters. (line 1430) * innodb_mirrored_log_groups system variable: innodb-parameters. (line 1479) * innodb_old_blocks_pct system variable: innodb-parameters. (line 1483) * innodb_old_blocks_time system variable: innodb-parameters. (line 1517) * innodb_open_files system variable: innodb-parameters. (line 1552) * innodb_random_read_ahead system variable: innodb-parameters. (line 1580) * innodb_read_ahead_threshold system variable: innodb-parameters. (line 1609) * innodb_read_io_threads system variable: innodb-parameters. (line 1643) * innodb_replication_delay system variable: innodb-parameters. (line 1676) * innodb_rollback_on_timeout system variable: innodb-parameters. (line 1700) * innodb_spin_wait_delay system variable: innodb-parameters. (line 1725) * innodb_stats_method system variable: innodb-parameters. (line 1753) * innodb_stats_on_metadata system variable: innodb-parameters. (line 1788) * innodb_stats_sample_pages system variable: innodb-parameters. (line 1821) * innodb_strict_mode system variable: innodb-parameters. (line 1849) * innodb_support_xa system variable: innodb-parameters. (line 1875) * innodb_sync_spin_loops system variable: innodb-parameters. (line 1916) * innodb_table_locks system variable: innodb-parameters. (line 1939) * innodb_thread_concurrency system variable: innodb-parameters. (line 1963) * innodb_thread_sleep_delay system variable: innodb-parameters. (line 2006) * innodb_use_sys_malloc system variable: innodb-parameters. (line 2060) * innodb_version system variable: innodb-parameters. (line 2083) * innodb_write_io_threads system variable: innodb-parameters. (line 2092) * INSERT <1>: insert. (line 12) * INSERT: insert-speed. (line 6) * INSERT ... SELECT: insert-select. (line 6) * insert buffering: innodb-insert-buffering. (line 6) * INSERT DELAYED: insert-delayed. (line 6) * INSERT statement, grant privileges: adding-users. (line 117) * INSERT(): string-functions. (line 328) * insert, thread state: delayed-insert-thread-states. (line 72) * insert-ignore option, mysqldump: mysqldump. (line 633) * insert_id session variable: server-system-variables. (line 2087) * insertable views, insertable: view-updatability. (line 6) * inserting, speed of: insert-speed. (line 6) * inserts, concurrent <1>: concurrent-inserts. (line 6) * inserts, concurrent: internal-locking. (line 68) * install option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 605) * install option (ndbd): mysql-cluster-programs-ndbd. (line 329) * install option (ndbmtd): mysql-cluster-programs-ndbd. (line 329) * install option, mysqld: server-options. (line 885) * install option, mysqlmanager: instance-manager-command-options. (line 97) * INSTALL PLUGIN: install-plugin. (line 6) * install-manual option, mysqld: server-options. (line 902) * installation layouts: installation-layouts. (line 6) * installation overview: source-installation. (line 19) * installing MySQL Cluster: mysql-cluster-installation. (line 16) * installing MySQL Cluster, Linux: mysql-cluster-install-linux. (line 12) * installing MySQL Cluster, Linux binary release: mysql-cluster-install-linux-binary. (line 6) * installing MySQL Cluster, Linux RPM: mysql-cluster-install-linux-rpm. (line 6) * installing MySQL Cluster, Linux source release: mysql-cluster-install-linux-source. (line 6) * installing MySQL Cluster, Windows: mysql-cluster-install-windows. (line 13) * installing MySQL Cluster, Windows binary release: mysql-cluster-install-windows-binary. (line 6) * installing MySQL Cluster, Windows source: mysql-cluster-install-windows-source. (line 6) * installing plugins <1>: install-plugin. (line 6) * installing plugins: server-plugin-loading. (line 6) * installing, binary distribution: binary-installation. (line 6) * installing, installing on HP-UX: hpux-installation. (line 11) * installing, installing on IBM-AIX: aix-installation. (line 10) * installing, Linux RPM packages: linux-installation-rpm. (line 6) * installing, Mac OS X DMG packages: macosx-installation. (line 14) * installing, overview: installing. (line 24) * installing, Perl: perl-support. (line 12) * installing, Perl on Windows: activestate-perl. (line 6) * installing, Solaris PKG packages: solaris-installation. (line 11) * installing, source distribution: source-installation. (line 19) * installing, user-defined functions: udf-compiling. (line 6) * INSTR(): string-functions. (line 346) * INT data type: numeric-type-overview. (line 116) * integer arithmetic: precision-math. (line 14) * INTEGER data type: numeric-type-overview. (line 121) * integers: number-literals. (line 6) * interactive option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 286) * interactive_timeout system variable: server-system-variables. (line 2093) * interceptors <1>: connector-net-connection-options. (line 6) * interceptors: connector-net-interceptors. (line 6) * InteriorRingN(): polygon-property-functions. (line 35) * internal compiler errors: compilation-problems. (line 37) * internal locking: internal-locking. (line 6) * internals: mysql-internals. (line 11) * internationalization: globalization. (line 16) * Internet Relay Chat: irc. (line 6) * Intersection(): spatial-operators. (line 26) * Intersects(): functions-that-test-spatial-relationships-between-geometries. (line 49) * INTERVAL(): comparison-operators. (line 312) * INTO, SELECT: select-into. (line 6) * introducer, string literal <1>: charset-literal. (line 11) * introducer, string literal: string-literals. (line 33) * invalid data, constraint: constraint-invalid-data. (line 6) * invalidating query cache entries, thread state: query-cache-thread-states. (line 19) * IPv6 addresses, for JDBC URLs: connector-j-reference-configuration-properties. (line 37) * IRC: irc. (line 6) * IS boolean_value: comparison-operators. (line 130) * IS NOT boolean_value: comparison-operators. (line 138) * IS NOT NULL: comparison-operators. (line 188) * IS NULL <1>: comparison-operators. (line 146) * IS NULL: is-null-optimization. (line 6) * IS NULL, and indexes: mysql-indexes. (line 137) * IS_FREE_LOCK(): miscellaneous-functions. (line 138) * IS_USED_LOCK(): miscellaneous-functions. (line 149) * IsClosed() <1>: multilinestring-property-functions. (line 25) * IsClosed(): linestring-property-functions. (line 39) * IsEmpty(): general-geometry-property-functions. (line 75) * ISNULL(): comparison-operators. (line 295) * isolation level: innodb-transaction-model. (line 18) * ISOLATION LEVEL: set-transaction. (line 6) * IsSimple(): general-geometry-property-functions. (line 82) * ITERATE: iterate. (line 6) * iterations option, mysqlslap: mysqlslap. (line 338) * J2EE, connection pooling: connector-j-usagenotes-j2ee-concepts-connection-pooling. (line 6) * J2EE, load balancing: connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections. (line 6) * Japanese character sets, conversion: faqs-cjk. (line 6) * Japanese, Korean, Chinese character sets, frequently asked questions: faqs-cjk. (line 6) * JBoss application server: connector-j-usagenotes-jboss. (line 6) * JDBC: connectors-apis. (line 23) * JDBC, and MySQL data types: connector-j-reference-type-conversions. (line 6) * JDBC, background information for Connector/J: connector-j-usagenotes-basic. (line 13) * JDBC, character sets: connector-j-reference-charsets. (line 6) * JDBC, CLASSPATH: connector-j-installing-classpath. (line 6) * JDBC, code examples: connector-j-examples. (line 6) * JDBC, compatibility: connector-j-reference-implementation-notes. (line 6) * JDBC, configuration properties: connector-j-reference-configuration-properties. (line 10) * JDBC, driver for MySQL: connector-j-overview. (line 6) * JDBC, SQLState codes: connector-j-reference-error-sqlstates. (line 6) * JDBC, troubleshooting <1>: connector-j-usagenotes-known-issues-limitations. (line 6) * JDBC, troubleshooting <2>: connector-j-usagenotes-troubleshooting. (line 6) * JDBC, troubleshooting: connector-j-installing-upgrading-issues. (line 6) * JDBC, versions supported: connector-j-versions. (line 11) * jdbc:mysql:loadbalance://: mysql-cluster-basics. (line 116) * JOIN: join. (line 6) * join algorithm, Block Nested-Loop: nested-loop-joins. (line 6) * join algorithm, Nested-Loop: nested-loop-joins. (line 6) * join option, myisampack: myisampack. (line 78) * join type, ALL: explain-output. (line 385) * join type, const: explain-output. (line 240) * join type, eq_ref: explain-output. (line 257) * join type, fulltext: explain-output. (line 300) * join type, index: explain-output. (line 366) * join type, index_merge: explain-output. (line 317) * join type, index_subquery: explain-output. (line 335) * join type, range: explain-output. (line 343) * join type, ref: explain-output. (line 278) * join type, ref_or_null: explain-output. (line 304) * join type, system: explain-output. (line 235) * join type, unique_subquery: explain-output. (line 325) * join, nested-loop algorithm: nested-join-optimization. (line 167) * join_buffer_size system variable: server-system-variables. (line 2117) * keep_files_on_create system variable: server-system-variables. (line 2170) * keepold option, mysqlhotcopy: mysqlhotcopy. (line 124) * key cache, assigning indexes to: cache-index. (line 6) * Key cache, MyISAM: myisam-key-cache. (line 15) * key partitioning: partitioning-key. (line 6) * key partitions, managing: partitioning-management-hash-key. (line 6) * key partitions, splitting and merging: partitioning-management-hash-key. (line 6) * key space, MyISAM: key-space. (line 6) * key_buffer_size myisamchk variable: myisamchk-general-options. (line 53) * key_buffer_size system variable: server-system-variables. (line 2204) * key_cache_age_threshold system variable: server-system-variables. (line 2306) * key_cache_block_size system variable: server-system-variables. (line 2339) * key_cache_division_limit system variable: server-system-variables. (line 2361) * KEY_COLUMN_USAGE, INFORMATION_SCHEMA table: key-column-usage-table. (line 6) * keys: column-indexes. (line 6) * keys option, mysqlshow: mysqlshow. (line 164) * keys, foreign <1>: example-foreign-keys. (line 6) * keys, foreign: ansi-diff-foreign-keys. (line 6) * keys, multi-column: multiple-column-indexes. (line 6) * keys, searching on two: searching-on-two-keys. (line 6) * keys-used option, myisamchk: myisamchk-repair-options. (line 45) * keywords: reserved-words. (line 6) * KILL: kill. (line 6) * Kill, thread command: thread-commands. (line 69) * Killed, thread state: general-thread-states. (line 158) * Killing slave, thread state: slave-connection-thread-states. (line 21) * known errors: bugs. (line 6) * known issues, Connector/J: connector-j-usagenotes-known-issues-limitations. (line 6) * Korean: faqs-cjk. (line 6) * Korean, Chinese, Japanese character sets, frequently asked questions: faqs-cjk. (line 6) * labels, stored program block: statement-labels. (line 6) * language option, mysqld: server-options. (line 920) * language support, error messages: error-message-language. (line 6) * language system variable: server-system-variables. (line 2384) * large page support: large-page-support. (line 6) * large tables, and MySQL Cluster: create-table. (line 864) * large tables, creating in NDB: create-table. (line 864) * large-pages option, mysqld: server-options. (line 943) * large_files_support system variable: server-system-variables. (line 2405) * large_page_size system variable: server-system-variables. (line 2437) * large_pages system variable: server-system-variables. (line 2417) * last row, unique ID: getting-unique-id. (line 6) * LAST_DAY(): date-and-time-functions. (line 652) * last_insert_id session variable: server-system-variables. (line 2455) * LAST_INSERT_ID() <1>: insert. (line 206) * LAST_INSERT_ID(): information-functions. (line 304) * LAST_INSERT_ID(), and replication: replication-features-auto-increment. (line 6) * LAST_INSERT_ID(), and stored routines: stored-routines-last-insert-id. (line 6) * LAST_INSERT_ID(), and triggers: stored-routines-last-insert-id. (line 6) * LAST_INSERT_ID(), locking considerations: ansi-diff-transactions. (line 159) * layout of installation: installation-layouts. (line 6) * lc_time_names system variable: server-system-variables. (line 2463) * LCASE(): string-functions. (line 360) * LD_LIBRARY_PATH environment variable: perl-support-problems. (line 20) * LD_RUN_PATH environment variable <1>: perl-support-problems. (line 20) * LD_RUN_PATH environment variable <2>: environment-variables. (line 18) * LD_RUN_PATH environment variable: solaris-installation-source. (line 97) * ldata option, mysql_install_db: mysql-install-db. (line 60) * LDML syntax: ldml-rules. (line 6) * LEAST(): comparison-operators. (line 326) * LEAVE: leave. (line 6) * ledir option, mysqld_safe: mysqld-safe. (line 163) * LEFT JOIN <1>: join. (line 6) * LEFT JOIN: left-join-optimization. (line 6) * LEFT OUTER JOIN: join. (line 6) * LEFT(): string-functions. (line 364) * leftmost prefix of indexes <1>: mysql-indexes. (line 88) * leftmost prefix of indexes: multiple-column-indexes. (line 83) * legal names: identifiers. (line 13) * length option, myisam_ftdump: myisam-ftdump. (line 70) * LENGTH(): string-functions. (line 374) * less than (<): comparison-operators. (line 109) * less than or equal (<=): comparison-operators. (line 102) * libmysqlclient library: connectors-apis. (line 23) * libmysqlclient.a: connector-cpp-apps-linux-netbeans. (line 6) * libmysqlcppconn-static.a: connector-cpp-apps-linux-netbeans. (line 6) * libmysqlcppconn.so: connector-cpp-apps-linux-netbeans. (line 6) * libmysqld: libmysqld. (line 13) * libmysqld library: connectors-apis. (line 23) * libmysqld, options: libmysqld-options. (line 6) * libmysqld-libs option, mysql_config: mysql-config. (line 26) * library, libmysqlclient: connectors-apis. (line 23) * library, libmysqld: connectors-apis. (line 23) * libs option, mysql_config: mysql-config. (line 31) * libs_r option, mysql_config: mysql-config. (line 36) * license system variable: server-system-variables. (line 2486) * LIKE: string-comparison-functions. (line 20) * LIKE, and indexes: mysql-indexes. (line 111) * LIKE, and wildcards: mysql-indexes. (line 111) * LIMIT <1>: select. (line 277) * LIMIT <2>: information-functions. (line 220) * LIMIT: limit-optimization. (line 6) * LIMIT, and replication: replication-features-limit. (line 6) * limitations of MySQL Cluster: mysql-cluster-limitations. (line 20) * limitations, Connector/J: connector-j-usagenotes-known-issues-limitations. (line 6) * limitations, design: design-limitations. (line 6) * limitations, MySQL Limitations: limits. (line 15) * limitations, replication: replication-features. (line 45) * limits, file-size: table-size-limit. (line 6) * limits, InnoDB: innodb-restrictions. (line 6) * limits, MySQL Limits, limits in MySQL: limits. (line 15) * line-numbers option, mysql: mysql-command-options. (line 295) * linear hash partitioning: partitioning-linear-hash. (line 6) * linear key partitioning: partitioning-key. (line 109) * linefeed (\n) <1>: load-data. (line 432) * linefeed (\n): string-literals. (line 72) * LineFromText(): gis-wkt-functions. (line 25) * LineFromWKB(): gis-wkb-functions. (line 28) * lines-terminated-by option, mysqldump <1>: mysqlimport. (line 215) * lines-terminated-by option, mysqldump: mysqldump. (line 638) * LINESTRING data type: mysql-spatial-datatypes. (line 6) * LineString(): gis-mysql-specific-functions. (line 35) * LineStringFromText(): gis-wkt-functions. (line 25) * LineStringFromWKB(): gis-wkb-functions. (line 28) * linking: c-api-building-clients. (line 6) * linking, errors: c-api-building-clients. (line 79) * linking, problems: c-api-building-clients. (line 79) * linking, speed: compile-and-link-options. (line 6) * links, symbolic: symbolic-links. (line 12) * LINQ: connector-net-tutorials-entity-framework-databinding-linq-entities. (line 6) * list partitioning: partitioning-list. (line 6) * list partitions, adding and dropping: partitioning-management-range-list. (line 6) * list partitions, managing: partitioning-management-range-list. (line 6) * list-users option, mysqlmanager: instance-manager-command-options. (line 102) * literals: literals. (line 16) * LN(): mathematical-functions. (line 234) * load balancing, with Connector/J <1>: connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections. (line 6) * load balancing, with Connector/J: connector-j-reference-replication-connection. (line 6) * LOAD DATA FROM MASTER: load-data-from-master. (line 6) * LOAD DATA INFILE <1>: problems-with-null. (line 51) * LOAD DATA INFILE <2>: connector-net-programming-bulk-loader. (line 6) * LOAD DATA INFILE: load-data. (line 6) * LOAD DATA, and replication: replication-features-load-data. (line 6) * load emulation: mysqlslap. (line 6) * LOAD INDEX INTO CACHE, and partitioning: partitioning-limitations. (line 400) * LOAD TABLE FROM MASTER: load-table-from-master. (line 6) * LOAD_FILE(): string-functions. (line 384) * loading, tables: loading-tables. (line 6) * local checkpoints (MySQL Cluster): mysql-cluster-config-lcp-params. (line 6) * local option, mysqlimport: mysqlimport. (line 224) * local-infile option, mysql: mysql-command-options. (line 300) * local-load option, mysqlbinlog: mysqlbinlog. (line 384) * local_infile system variable: server-system-variables. (line 2501) * localhost, special treatment of: connecting. (line 75) * localization: globalization. (line 16) * localstatedir option, configure: source-configuration-options. (line 349) * LOCALTIME: date-and-time-functions. (line 667) * LOCALTIMESTAMP: date-and-time-functions. (line 671) * LOCATE(): string-functions. (line 405) * LOCK IN SHARE MODE: select. (line 336) * Lock Monitor, InnoDB: innodb-monitors. (line 12) * lock option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 75) * LOCK TABLES: lock-tables. (line 12) * lock-all-tables option, mysqldump: mysqldump. (line 644) * lock-directory option, mysqlslap: mysqlslap. (line 342) * lock-tables option, mysqldump: mysqldump. (line 651) * lock-tables option, mysqlimport: mysqlimport. (line 228) * Locked, thread state: general-thread-states. (line 167) * locked_in_memory system variable: server-system-variables. (line 2518) * LockExecuteThreadToCPU: mysql-cluster-ndbd-definition. (line 3045) * locking: system-optimization. (line 24) * locking methods: internal-locking. (line 6) * locking, external <1>: general-thread-states. (line 316) * locking, external <2>: external-locking. (line 6) * locking, external <3>: myisam-crash-recovery. (line 6) * locking, external <4>: server-system-variables. (line 4869) * locking, external: server-options. (line 773) * locking, internal: internal-locking. (line 6) * locking, row-level <1>: internal-locking. (line 6) * locking, row-level: ansi-diff-transactions. (line 166) * locking, table-level: internal-locking. (line 6) * LockMaintThreadsToCPU: mysql-cluster-ndbd-definition. (line 3086) * LockPagesInMainMemory: mysql-cluster-ndbd-definition. (line 1510) * log files: source-configuration-options. (line 6) * log files (MySQL Cluster): mysql-cluster-programs-ndbd. (line 433) * log files (MySQL Cluster), ndbmtd: mysql-cluster-programs-ndbmtd. (line 67) * log files, maintaining: log-file-maintenance. (line 6) * log option, mysqld: server-options. (line 973) * log option, mysqld_multi: mysqld-multi. (line 118) * log option, mysqlmanager: instance-manager-command-options. (line 107) * log system variable: server-system-variables. (line 2530) * LOG(): mathematical-functions. (line 248) * log-bin option, mysqld: replication-options-binary-log. (line 51) * log-bin-index option, mysqld: replication-options-binary-log. (line 81) * log-bin-trust-function-creators option, mysqld: replication-options-binary-log. (line 97) * log-bin-use-v1-row-events option, mysqld: replication-options-binary-log. (line 125) * log-error option, mysqld: server-options. (line 1007) * log-error option, mysqld_safe: mysqld-safe. (line 169) * log-error option, mysqldump: mysqldump. (line 665) * log-isam option, mysqld: server-options. (line 1028) * log-long-format option, mysqld: server-options. (line 1043) * log-name option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 350) * log-output option, mysqld: server-options. (line 1062) * log-queries-not-using-indexes option, mysqld: server-options. (line 1105) * log-short-format option, mysqld <1>: replication-options-binary-log. (line 175) * log-short-format option, mysqld: server-options. (line 1128) * log-slave-updates option, mysqld: replication-options-slave. (line 176) * log-slow-admin-statements option, mysqld: server-options. (line 1143) * log-slow-queries option, mysqld: server-options. (line 1162) * log-slow-slave-statements option, mysqld: replication-options-slave. (line 226) * log-tc option, mysqld: server-options. (line 1197) * log-tc-size option, mysqld: server-options. (line 1216) * log-warnings option, mysqld <1>: replication-options-slave. (line 245) * log-warnings option, mysqld: server-options. (line 1239) * LOG10(): mathematical-functions. (line 288) * LOG2(): mathematical-functions. (line 275) * log_bin system variable: replication-options-binary-log. (line 653) * log_bin_trust_function_creators system variable: server-system-variables. (line 2556) * log_bin_use_v1_row_events system variable: replication-options-binary-log. (line 670) * log_error system variable: server-system-variables. (line 2585) * log_output system variable: server-system-variables. (line 2604) * log_queries_not_using_indexes system variable: server-system-variables. (line 2635) * log_slave_updates system variable: replication-options-binary-log. (line 720) * log_slow_queries system variable: server-system-variables. (line 2655) * log_warnings system variable: server-system-variables. (line 2680) * logbuffers, ndbinfo table: mysql-cluster-ndbinfo-logbuffers. (line 6) * LogDestination: mysql-cluster-mgm-definition. (line 120) * logging commands (MySQL Cluster): mysql-cluster-logging-management-commands. (line 6) * logging slow query, thread state: general-thread-states. (line 171) * logging, passwords: password-logging. (line 6) * logical operators: logical-operators. (line 6) * login, thread state: general-thread-states. (line 180) * LogLevelCheckpoint: mysql-cluster-ndbd-definition. (line 2715) * LogLevelCongestion: mysql-cluster-ndbd-definition. (line 2771) * LogLevelConnection: mysql-cluster-ndbd-definition. (line 2742) * LogLevelError: mysql-cluster-ndbd-definition. (line 2756) * LogLevelInfo: mysql-cluster-ndbd-definition. (line 2786) * LogLevelNodeRestart: mysql-cluster-ndbd-definition. (line 2729) * LogLevelShutdown: mysql-cluster-ndbd-definition. (line 2686) * LogLevelStartup: mysql-cluster-ndbd-definition. (line 2672) * LogLevelStatistic: mysql-cluster-ndbd-definition. (line 2700) * logs, and TIMESTAMP: upgrading-from-previous-series. (line 758) * logs, flushing: server-logs. (line 37) * logs, server: server-logs. (line 15) * logspaces, ndbinfo table: mysql-cluster-ndbinfo-logspaces. (line 6) * LONG data type: blob. (line 6) * Long Data, thread command: thread-commands. (line 73) * long_query_time system variable: server-system-variables. (line 2717) * LONGBLOB data type: string-type-overview. (line 220) * LongMessageBuffer: mysql-cluster-ndbd-definition. (line 933) * LONGTEXT data type: string-type-overview. (line 230) * LOOP: loop. (line 6) * LOOP, labels: statement-labels. (line 6) * loops option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 321) * loops option (ndbinfo_select_all): mysql-cluster-programs-ndbinfo-select-all. (line 103) * loops option, ndb_show_tables: mysql-cluster-programs-ndb-show-tables. (line 54) * lossy-conversions option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 305) * lost connection errors: error-lost-connection. (line 6) * low-priority option, mysqlimport: mysqlimport. (line 233) * low-priority-updates option, mysqld: server-options. (line 1287) * low_priority_updates system variable: server-system-variables. (line 2751) * LOWER(): string-functions. (line 422) * lower_case_file_system system variable: server-system-variables. (line 2776) * lower_case_table_names system variable: server-system-variables. (line 2794) * LPAD(): string-functions. (line 446) * LTRIM(): string-functions. (line 457) * Lua: mysql-proxy. (line 15) * Mac OS X: connector-odbc. (line 17) * Mac OS X, installation: macosx-installation. (line 14) * mailing lists: mailing-lists. (line 10) * mailing lists, archive location: mailing-lists. (line 10) * mailing lists, guidelines: mailing-list-use. (line 6) * main features of MySQL: features. (line 6) * maintaining, log files: log-file-maintenance. (line 6) * maintaining, tables: myisam-maintenance-schedule. (line 6) * maintenance, tables: mysqlcheck. (line 6) * make_binary_distribution: programs-overview. (line 74) * MAKE_SET(): string-functions. (line 466) * make_win_bin_dist <1>: make-win-bin-dist. (line 6) * make_win_bin_dist: programs-overview. (line 80) * make_win_bin_dist, debug option: make-win-bin-dist. (line 36) * make_win_bin_dist, embedded option: make-win-bin-dist. (line 41) * make_win_bin_dist, exe-suffix option: make-win-bin-dist. (line 46) * make_win_bin_dist, no-debug option: make-win-bin-dist. (line 52) * make_win_bin_dist, no-embedded option: make-win-bin-dist. (line 56) * make_win_bin_dist, only-debug option: make-win-bin-dist. (line 60) * MAKEDATE(): date-and-time-functions. (line 675) * MAKETIME(): date-and-time-functions. (line 687) * Making temp file, thread state: slave-sql-thread-states. (line 25) * malicious SQL statements, and MySQL Cluster: mysql-cluster-security-mysql-privileges. (line 86) * manage keys, thread state: general-thread-states. (line 185) * management client (MySQL Cluster): mysql-cluster-programs-ndb-mgm. (line 6) * management node (MySQL Cluster), defined: mysql-cluster-basics. (line 6) * management nodes (MySQL Cluster): mysql-cluster-programs-ndb-mgmd. (line 6) * managing MySQL Cluster: mysql-cluster-management. (line 24) * managing MySQL Cluster processes: mysql-cluster-programs. (line 34) * manual, available formats: manual-info. (line 33) * manual, online location: manual-info. (line 6) * manual, syntax conventions: manual-conventions. (line 8) * manual, typographical conventions: manual-conventions. (line 8) * master-connect-retry option, mysqld: replication-options-slave. (line 286) * master-data option, mysqldump: mysqldump. (line 670) * master-host option, mysqld: replication-options-slave. (line 345) * master-info-file option, mysqld: replication-options-slave. (line 364) * master-password option, mysqld: replication-options-slave. (line 382) * master-port option, mysqld: replication-options-slave. (line 402) * master-retry-count option, mysqld: replication-options-slave. (line 422) * master-ssl option, mysqld: replication-options-slave. (line 453) * master-ssl-ca option, mysqld: replication-options-slave. (line 453) * master-ssl-capath option, mysqld: replication-options-slave. (line 453) * master-ssl-cert option, mysqld: replication-options-slave. (line 453) * master-ssl-cipher option, mysqld: replication-options-slave. (line 453) * master-ssl-key option, mysqld: replication-options-slave. (line 453) * master-user option, mysqld: replication-options-slave. (line 468) * MASTER_POS_WAIT() <1>: master-pos-wait. (line 6) * MASTER_POS_WAIT(): miscellaneous-functions. (line 159) * MATCH ... AGAINST(): fulltext-search. (line 16) * matching, patterns: pattern-matching. (line 6) * math: precision-math. (line 14) * mathematical functions: mathematical-functions. (line 52) * MAX(): group-by-functions. (line 192) * MAX(DISTINCT): group-by-functions. (line 192) * max-binlog-dump-events option, mysqld: replication-options-binary-log. (line 401) * max-record-length option, myisamchk: myisamchk-repair-options. (line 61) * max-relay-log-size option, mysqld: replication-options-slave. (line 490) * max_allowed_packet system variable: server-system-variables. (line 2842) * max_allowed_packet variable: mysql-command-options. (line 619) * max_allowed_packet, and replication: replication-features-max-allowed-packet. (line 6) * max_binlog_cache_size system variable: replication-options-binary-log. (line 741) * max_binlog_size system variable: replication-options-binary-log. (line 795) * max_connect_errors system variable: server-system-variables. (line 2889) * max_connections system variable: server-system-variables. (line 2926) * MAX_CONNECTIONS_PER_HOUR: user-resources. (line 6) * max_delayed_threads system variable: server-system-variables. (line 2969) * max_error_count system variable: server-system-variables. (line 2999) * max_heap_table_size system variable: server-system-variables. (line 3022) * max_insert_delayed_threads system variable: server-system-variables. (line 3069) * max_join_size system variable: server-system-variables. (line 3084) * max_join_size variable: mysql-command-options. (line 624) * max_length_for_sort_data system variable: server-system-variables. (line 3123) * max_long_data_size system variable: server-system-variables. (line 3145) * max_prepared_stmt_count system variable: server-system-variables. (line 3173) * MAX_QUERIES_PER_HOUR: user-resources. (line 6) * max_relay_log_size system variable: server-system-variables. (line 3205) * MAX_ROWS, and DataMemory (MySQL Cluster): mysql-cluster-ndbd-definition. (line 373) * MAX_ROWS, and MySQL Cluster <1>: partitioning-overview. (line 139) * MAX_ROWS, and MySQL Cluster: create-table. (line 864) * MAX_ROWS, and NDB: create-table. (line 864) * max_seeks_for_key system variable: server-system-variables. (line 3234) * max_sort_length system variable: server-system-variables. (line 3269) * max_sp_recursion_depth system variable: server-system-variables. (line 3292) * max_tmp_tables system variable: server-system-variables. (line 3320) * MAX_UPDATES_PER_HOUR: user-resources. (line 6) * MAX_USER_CONNECTIONS: user-resources. (line 6) * max_user_connections system variable: server-system-variables. (line 3324) * max_write_lock_count system variable: server-system-variables. (line 3363) * MaxAllocate: mysql-cluster-ndbd-definition. (line 984) * MaxBufferedEpochBytes: mysql-cluster-ndbd-definition. (line 2183) * MaxBufferedEpochs: mysql-cluster-ndbd-definition. (line 2156) * MAXDB SQL mode: server-sql-mode. (line 529) * MaxDMLOperationsPerTransaction: mysql-cluster-ndbd-definition. (line 753) * maximum memory used: mysqladmin. (line 202) * maximums, maximum columns per table: column-count-limit. (line 6) * maximums, maximum number of databases: database-count-limit. (line 6) * maximums, maximum number of tables: database-count-limit. (line 6) * maximums, maximum row size: column-count-limit. (line 6) * maximums, maximum tables per join: joins-limits. (line 6) * maximums, table size: table-size-limit. (line 6) * MaxLCPStartDelay: mysql-cluster-ndbd-definition. (line 1220) * MaxNoOfAttributes: mysql-cluster-ndbd-definition. (line 1264) * MaxNoOfConcurrentIndexOperations: mysql-cluster-ndbd-definition. (line 785) * MaxNoOfConcurrentOperations: mysql-cluster-ndbd-definition. (line 665) * MaxNoOfConcurrentScans: mysql-cluster-ndbd-definition. (line 869) * MaxNoOfConcurrentSubOperations: mysql-cluster-ndbd-definition. (line 1484) * MaxNoOfConcurrentTransactions: mysql-cluster-ndbd-definition. (line 606) * MaxNoOfExecutionThreads, ndbmtd: mysql-cluster-ndbd-definition. (line 3244) * MaxNoOfFiredTriggers: mysql-cluster-ndbd-definition. (line 809) * MaxNoOfIndexes: mysql-cluster-ndbd-definition. (line 1421) * MaxNoOfLocalOperations: mysql-cluster-ndbd-definition. (line 737) * MaxNoOfLocalScans: mysql-cluster-ndbd-definition. (line 900) * MaxNoOfOpenFiles: mysql-cluster-ndbd-definition. (line 1173) * MaxNoOfOrderedIndexes: mysql-cluster-ndbd-definition. (line 1352) * MaxNoOfSavedMessages: mysql-cluster-ndbd-definition. (line 1205) * MaxNoOfSubscribers: mysql-cluster-ndbd-definition. (line 1453) * MaxNoOfSubscriptions: mysql-cluster-ndbd-definition. (line 1432) * MaxNoOfTables: mysql-cluster-ndbd-definition. (line 1315) * MaxNoOfTriggers: mysql-cluster-ndbd-definition. (line 1399) * MaxNoOfUniqueHashIndexes: mysql-cluster-ndbd-definition. (line 1376) * MaxParallelScansPerFragment: mysql-cluster-ndbd-definition. (line 960) * MaxScanBatchSize: mysql-cluster-api-definition. (line 233) * MaxStartFailRetries: mysql-cluster-ndbd-definition. (line 4000) * MBR: relations-on-geometry-mbr. (line 6) * MBRContains(): relations-on-geometry-mbr. (line 10) * MBRDisjoint(): relations-on-geometry-mbr. (line 25) * MBREqual(): relations-on-geometry-mbr. (line 30) * MBRIntersects(): relations-on-geometry-mbr. (line 35) * MBROverlaps(): relations-on-geometry-mbr. (line 40) * MBRTouches(): relations-on-geometry-mbr. (line 48) * MBRWithin(): relations-on-geometry-mbr. (line 56) * MD5(): encryption-functions. (line 289) * medium trust: connector-net-medium-trust. (line 12) * medium-check option, myisamchk: myisamchk-check-options. (line 49) * medium-check option, mysqlcheck: mysqlcheck. (line 324) * MEDIUMBLOB data type: string-type-overview. (line 204) * MEDIUMINT data type: numeric-type-overview. (line 111) * MEDIUMTEXT data type: string-type-overview. (line 211) * membership, ndbinfo table: mysql-cluster-ndbinfo-membership. (line 6) * memlock option, mysqld: server-options. (line 1346) * MEMORY storage engine <1>: memory-storage-engine. (line 6) * MEMORY storage engine: storage-engines. (line 23) * MEMORY storage engine, and replication: replication-features-memory. (line 6) * memory usage, myisamchk: myisamchk-memory. (line 6) * memory use <1>: memory-use. (line 6) * memory use: mysqladmin. (line 196) * memory use, in MySQL Cluster: mysql-cluster-limitations-limits. (line 9) * memoryusage, ndbinfo table: mysql-cluster-ndbinfo-memoryusage. (line 6) * MemReportFrequency: mysql-cluster-ndbd-definition. (line 2800) * MERGE storage engine <1>: merge-storage-engine. (line 11) * MERGE storage engine: storage-engines. (line 23) * MERGE tables, defined: merge-storage-engine. (line 11) * metadata, database: information-schema. (line 36) * metadata, stored routines: stored-routines-metadata. (line 6) * metadata, triggers: trigger-metadata. (line 6) * metadata, views: view-metadata. (line 6) * method option, mysqlhotcopy: mysqlhotcopy. (line 128) * methods, locking: internal-locking. (line 6) * mgmd (MySQL Cluster), defined: mysql-cluster-basics. (line 6) * MICROSECOND(): date-and-time-functions. (line 695) * Microsoft Access: connector-odbc-usagenotes-apptips-microsoft-access. (line 6) * Microsoft ADO <1>: connector-net-visual-studio-entity-framework. (line 6) * Microsoft ADO: connector-odbc-usagenotes-apptips-microsoft-ado. (line 6) * Microsoft Excel: connector-odbc-usagenotes-apptips-microsoft-excel. (line 6) * Microsoft Visual Basic: connector-odbc-usagenotes-apptips-microsoft-visualbasic. (line 6) * Microsoft Visual InterDev: connector-odbc-usagenotes-apptips-microsoft-visualinterdev. (line 6) * Microsoft Visual Studio: connector-net-visual-studio. (line 23) * MID(): string-functions. (line 483) * MIN(): group-by-functions. (line 212) * MIN(DISTINCT): group-by-functions. (line 212) * min-examined-row-limit option, mysqld: server-options. (line 1313) * min_examined_row_limit system variable: server-system-variables. (line 3392) * MinFreePct: mysql-cluster-ndbd-definition. (line 373) * Minimum Bounding Rectangle: relations-on-geometry-mbr. (line 6) * minus, unary (-): arithmetic-functions. (line 69) * MINUTE(): date-and-time-functions. (line 705) * mirror sites: getting-mysql. (line 6) * miscellaneous functions: miscellaneous-functions. (line 6) * mixed statements (Replication): replication-features-transactions. (line 38) * MLineFromText(): gis-wkt-functions. (line 30) * MLineFromWKB(): gis-wkb-functions. (line 33) * MOD (modulo): mathematical-functions. (line 301) * MOD(): mathematical-functions. (line 301) * modes, batch: batch-mode. (line 6) * modulo (%): mathematical-functions. (line 301) * modulo (MOD): mathematical-functions. (line 301) * monitor, terminal: tutorial. (line 16) * monitoring: mysql-enterprise-monitor. (line 6) * monitoring, threads: thread-information. (line 19) * monitoring-interval option, mysqlmanager: instance-manager-command-options. (line 125) * Monitors, InnoDB <1>: innodb-troubleshooting-datadict. (line 61) * Monitors, InnoDB <2>: innodb-troubleshooting. (line 26) * Monitors, InnoDB <3>: innodb-monitors. (line 12) * Monitors, InnoDB <4>: innodb-file-space. (line 48) * Monitors, InnoDB: innodb-backup. (line 120) * Mono: connector-net. (line 20) * MONTH(): date-and-time-functions. (line 712) * MONTHNAME(): date-and-time-functions. (line 721) * MPointFromText(): gis-wkt-functions. (line 35) * MPointFromWKB(): gis-wkb-functions. (line 38) * MPolyFromText(): gis-wkt-functions. (line 40) * MPolyFromWKB(): gis-wkb-functions. (line 43) * mSQL compatibility: regexp. (line 32) * msql2mysql: msql2mysql. (line 6) * MSSQL SQL mode: server-sql-mode. (line 535) * multi mysqld: mysqld-multi. (line 6) * multi-byte character sets: cannot-initialize-character-set. (line 6) * multi-byte character sets, and MySQL Cluster (replication): mysql-cluster-replication-issues. (line 67) * multi-byte characters: multi-byte-characters. (line 6) * multi-column indexes: multiple-column-indexes. (line 6) * multi-master replication, in MySQL Cluster <1>: mysql-cluster-replication-conflict-resolution. (line 6) * multi-master replication, in MySQL Cluster: mysql-cluster-replication-multi-master. (line 6) * MULTILINESTRING data type: mysql-spatial-datatypes. (line 6) * MultiLineString(): gis-mysql-specific-functions. (line 41) * MultiLineStringFromText(): gis-wkt-functions. (line 30) * MultiLineStringFromWKB(): gis-wkb-functions. (line 33) * multiple servers: multiple-servers. (line 13) * multiple-part index: create-index. (line 6) * multiplication (*): arithmetic-functions. (line 83) * MULTIPOINT data type: mysql-spatial-datatypes. (line 6) * MultiPoint(): gis-mysql-specific-functions. (line 46) * MultiPointFromText(): gis-wkt-functions. (line 35) * MultiPointFromWKB(): gis-wkb-functions. (line 38) * MULTIPOLYGON data type: mysql-spatial-datatypes. (line 6) * MultiPolygon(): gis-mysql-specific-functions. (line 51) * MultiPolygonFromText(): gis-wkt-functions. (line 40) * MultiPolygonFromWKB(): gis-wkb-functions. (line 43) * MVCC (multi-version concurrency control): innodb-multi-versioning. (line 6) * My, derivation: history. (line 6) * my.cnf file: replication-features. (line 45) * my.cnf, and MySQL Cluster <1>: mysql-cluster-config-example. (line 6) * my.cnf, and MySQL Cluster <2>: mysql-cluster-config-file. (line 22) * my.cnf, and MySQL Cluster: mysql-cluster-install-configuration. (line 6) * my.cnf, in MySQL Cluster: mysql-cluster-mysqld. (line 49) * my_bool C type: c-api-data-structures. (line 64) * my_bool values, printing: c-api-data-structures. (line 64) * my_init(): my-init. (line 6) * my_print_defaults <1>: my-print-defaults. (line 6) * my_print_defaults: programs-overview. (line 267) * my_print_defaults, config-file option: my-print-defaults. (line 29) * my_print_defaults, debug option: my-print-defaults. (line 35) * my_print_defaults, defaults-extra-file option: my-print-defaults. (line 41) * my_print_defaults, defaults-file option: my-print-defaults. (line 31) * my_print_defaults, defaults-group-suffix option: my-print-defaults. (line 48) * my_print_defaults, extra-file option: my-print-defaults. (line 43) * my_print_defaults, help option: my-print-defaults. (line 25) * my_print_defaults, no-defaults option: my-print-defaults. (line 53) * my_print_defaults, verbose option: my-print-defaults. (line 57) * my_print_defaults, version option: my-print-defaults. (line 61) * my_ulonglong C type: c-api-data-structures. (line 50) * my_ulonglong values, printing: c-api-data-structures. (line 50) * mycnf option, ndb_config: mysql-cluster-programs-ndb-config. (line 183) * mycnf option, ndb_mgmd: mysql-cluster-programs-ndb-mgmd. (line 255) * MyISAM key cache: myisam-key-cache. (line 15) * MyISAM storage engine <1>: myisam-storage-engine. (line 13) * MyISAM storage engine: storage-engines. (line 23) * MyISAM, compressed tables <1>: compressed-format. (line 6) * MyISAM, compressed tables: myisampack. (line 6) * MyISAM, converting tables to InnoDB: converting-tables-to-innodb. (line 6) * myisam-block-size option, mysqld: server-options. (line 1395) * myisam-recover option, mysqld <1>: myisam-start. (line 38) * myisam-recover option, mysqld: server-options. (line 1412) * myisam_block_size myisamchk variable: myisamchk-general-options. (line 53) * myisam_data_pointer_size system variable: server-system-variables. (line 3423) * myisam_ftdump <1>: myisam-ftdump. (line 6) * myisam_ftdump: programs-overview. (line 170) * myisam_ftdump, count option: myisam-ftdump. (line 62) * myisam_ftdump, dump option: myisam-ftdump. (line 66) * myisam_ftdump, help option: myisam-ftdump. (line 58) * myisam_ftdump, length option: myisam-ftdump. (line 70) * myisam_ftdump, stats option: myisam-ftdump. (line 74) * myisam_ftdump, verbose option: myisam-ftdump. (line 79) * myisam_max_sort_file_size system variable: server-system-variables. (line 3446) * myisam_mmap_size system variable: server-system-variables. (line 3480) * myisam_recover_options system variable: server-system-variables. (line 3513) * myisam_repair_threads system variable: server-system-variables. (line 3525) * myisam_sort_buffer_size myisamchk variable: myisamchk-general-options. (line 53) * myisam_sort_buffer_size system variable: server-system-variables. (line 3560) * myisam_stats_method system variable: server-system-variables. (line 3599) * myisam_use_mmap system variable: server-system-variables. (line 3635) * myisamchk <1>: myisamchk. (line 15) * myisamchk: programs-overview. (line 175) * myisamchk, analyze option: myisamchk-other-options. (line 9) * myisamchk, backup option: myisamchk-repair-options. (line 10) * myisamchk, block-search option: myisamchk-other-options. (line 18) * myisamchk, character-sets-dir option: myisamchk-repair-options. (line 14) * myisamchk, check option: myisamchk-check-options. (line 9) * myisamchk, check-only-changed option: myisamchk-check-options. (line 14) * myisamchk, correct-checksum option: myisamchk-repair-options. (line 19) * myisamchk, data-file-length option: myisamchk-repair-options. (line 23) * myisamchk, debug option: myisamchk-general-options. (line 21) * myisamchk, description option: myisamchk-other-options. (line 22) * myisamchk, example output: myisamchk-table-info. (line 6) * myisamchk, extend-check option <1>: myisamchk-repair-options. (line 28) * myisamchk, extend-check option: myisamchk-check-options. (line 18) * myisamchk, fast option: myisamchk-check-options. (line 35) * myisamchk, force option <1>: myisamchk-repair-options. (line 40) * myisamchk, force option: myisamchk-check-options. (line 39) * myisamchk, HELP option: myisamchk-general-options. (line 16) * myisamchk, help option: myisamchk-general-options. (line 11) * myisamchk, information option: myisamchk-check-options. (line 45) * myisamchk, keys-used option: myisamchk-repair-options. (line 45) * myisamchk, max-record-length option: myisamchk-repair-options. (line 61) * myisamchk, medium-check option: myisamchk-check-options. (line 49) * myisamchk, no-symlinks option: myisamchk-repair-options. (line 54) * myisamchk, options: myisamchk-general-options. (line 6) * myisamchk, parallel-recover option: myisamchk-repair-options. (line 66) * myisamchk, quick option: myisamchk-repair-options. (line 72) * myisamchk, read-only option: myisamchk-check-options. (line 55) * myisamchk, recover option: myisamchk-repair-options. (line 79) * myisamchk, safe-recover option: myisamchk-repair-options. (line 92) * myisamchk, set-auto-increment[ option: myisamchk-other-options. (line 28) * myisamchk, set-character-set option: myisamchk-repair-options. (line 105) * myisamchk, set-collation option: myisamchk-repair-options. (line 110) * myisamchk, silent option: myisamchk-general-options. (line 27) * myisamchk, sort-index option: myisamchk-other-options. (line 36) * myisamchk, sort-records option: myisamchk-other-options. (line 41) * myisamchk, sort-recover option: myisamchk-repair-options. (line 116) * myisamchk, tmpdir option: myisamchk-repair-options. (line 121) * myisamchk, unpack option: myisamchk-repair-options. (line 131) * myisamchk, update-state option: myisamchk-check-options. (line 62) * myisamchk, verbose option: myisamchk-general-options. (line 32) * myisamchk, version option: myisamchk-general-options. (line 38) * myisamchk, wait option: myisamchk-general-options. (line 42) * myisamlog <1>: myisamlog. (line 6) * myisamlog: programs-overview. (line 180) * myisampack <1>: compressed-format. (line 6) * myisampack <2>: silent-column-changes. (line 70) * myisampack <3>: myisampack. (line 6) * myisampack: programs-overview. (line 185) * myisampack, backup option: myisampack. (line 51) * myisampack, character-sets-dir option: myisampack. (line 56) * myisampack, debug option: myisampack. (line 61) * myisampack, force option: myisampack. (line 66) * myisampack, help option: myisampack. (line 47) * myisampack, join option: myisampack. (line 78) * myisampack, silent option: myisampack. (line 93) * myisampack, test option: myisampack. (line 97) * myisampack, tmpdir option: myisampack. (line 101) * myisampack, verbose option: myisampack. (line 106) * myisampack, version option: myisampack. (line 111) * myisampack, wait option: myisampack. (line 115) * MyODBC: connector-odbc. (line 17) * mysql <1>: mysql. (line 15) * mysql: programs-overview. (line 124) * mysql \. (command for reading from text files) <1>: mysql-batch-commands. (line 6) * mysql \. (command for reading from text files): batch-mode. (line 90) * MySQL binary distribution: which-version. (line 18) * MYSQL C type: c-api-data-structures. (line 10) * MySQL Cluster: mysql-cluster. (line 16) * MySQL Cluster Disk Data: mysql-cluster-disk-data. (line 12) * MySQL Cluster Disk Data, creating log file groups: mysql-cluster-disk-data-objects. (line 63) * MySQL Cluster Disk Data, creating tables: mysql-cluster-disk-data-objects. (line 43) * MySQL Cluster Disk Data, creating tablespaces: mysql-cluster-disk-data-objects. (line 127) * MySQL Cluster Disk Data, dropping Disk Data objects: mysql-cluster-disk-data-objects. (line 253) * MySQL Cluster Disk Data, storage requirements: mysql-cluster-disk-data-storage-requirements. (line 6) * MySQL Cluster How-To: mysql-cluster-installation. (line 16) * MySQL Cluster in MySQL 5.1: mysql-cluster-development. (line 16) * MySQL Cluster limitations: mysql-cluster-limitations. (line 20) * MySQL Cluster limitations, and differences from standard MySQL limits: mysql-cluster-limitations-limits. (line 6) * MySQL Cluster limitations, autodiscovery: mysql-cluster-limitations-resolved. (line 53) * MySQL Cluster limitations, binary logging: mysql-cluster-limitations-exclusive-to-cluster. (line 22) * MySQL Cluster limitations, character sets: mysql-cluster-limitations-resolved. (line 84) * MySQL Cluster limitations, CREATE TABLE statements: mysql-cluster-limitations-resolved. (line 133) * MySQL Cluster limitations, database objects: mysql-cluster-limitations-database-objects. (line 6) * MySQL Cluster limitations, Disk Data storage: mysql-cluster-limitations-disk-data. (line 6) * MySQL Cluster limitations, error handling and reporting: mysql-cluster-limitations-error-handling. (line 6) * MySQL Cluster limitations, geometry data types: mysql-cluster-limitations-syntax. (line 86) * MySQL Cluster limitations, implementation: mysql-cluster-limitations-exclusive-to-cluster. (line 6) * MySQL Cluster limitations, imposed by configuration: mysql-cluster-limitations-limits. (line 39) * MySQL Cluster limitations, INSERT IGNORE, UPDATE IGNORE, and REPLACE statements: mysql-cluster-limitations-resolved. (line 139) * MySQL Cluster limitations, memory usage and transaction handling: mysql-cluster-limitations-transactions. (line 109) * MySQL Cluster limitations, multiple data nodes <1>: mysql-cluster-limitations-resolved. (line 108) * MySQL Cluster limitations, multiple data nodes: mysql-cluster-development-5-1-ndb-6-2. (line 140) * MySQL Cluster limitations, multiple management servers <1>: mysql-cluster-limitations-resolved. (line 94) * MySQL Cluster limitations, multiple management servers: mysql-cluster-limitations-multiple-nodes. (line 29) * MySQL Cluster limitations, multiple MySQL servers: mysql-cluster-limitations-multiple-nodes. (line 8) * MySQL Cluster limitations, partitioning: mysql-cluster-limitations-syntax. (line 106) * MySQL Cluster limitations, performance: mysql-cluster-limitations-performance. (line 6) * MySQL Cluster limitations, replication <1>: mysql-cluster-limitations-resolved. (line 35) * MySQL Cluster limitations, replication: mysql-cluster-limitations-syntax. (line 160) * MySQL Cluster limitations, resolved in current version from previous versions: mysql-cluster-limitations-resolved. (line 6) * MySQL Cluster limitations, syntax: mysql-cluster-limitations-syntax. (line 6) * MySQL Cluster limitations, transactions: mysql-cluster-limitations-transactions. (line 6) * MySQL Cluster limitations, unsupported features: mysql-cluster-limitations-unsupported. (line 6) * MySQL Cluster Manager, and ndb_mgm: mysql-cluster-mgm-client-commands. (line 17) * MySQL Cluster NDB 6.x: mysql-cluster-development. (line 16) * MySQL Cluster NDB 7.x: mysql-cluster-development. (line 16) * MySQL Cluster processes: mysql-cluster-programs. (line 34) * MySQL Cluster programs: mysql-cluster-programs. (line 34) * MySQL Cluster replication: mysql-cluster-replication. (line 20) * MySQL Cluster replication, and -initial option: mysql-cluster-replication-issues. (line 204) * MySQL Cluster replication, and auto_increment* variables: mysql-cluster-replication-issues. (line 215) * MySQL Cluster replication, and circular replication: mysql-cluster-replication-issues. (line 74) * MySQL Cluster replication, and multi-byte character sets: mysql-cluster-replication-issues. (line 67) * MySQL Cluster Replication, and NDB API _slave status variables: mysql-cluster-replication. (line 63) * MySQL Cluster replication, and primary key: mysql-cluster-replication-issues. (line 139) * MySQL Cluster replication, and single point of failure: mysql-cluster-replication-two-channels. (line 6) * MySQL Cluster replication, and unique keys: mysql-cluster-replication-issues. (line 150) * MySQL Cluster replication, backups: mysql-cluster-replication-backups. (line 11) * MySQL Cluster replication, circular replication: mysql-cluster-replication-multi-master. (line 6) * MySQL Cluster replication, concepts <1>: mysql-cluster-replication-general. (line 6) * MySQL Cluster replication, concepts: mysql-cluster-replication-abbreviations. (line 6) * MySQL Cluster replication, conflict resolution: mysql-cluster-replication-conflict-resolution. (line 6) * MySQL Cluster replication, failover <1>: mysql-cluster-replication-failover. (line 6) * MySQL Cluster replication, failover: mysql-cluster-replication-two-channels. (line 6) * MySQL Cluster replication, gap event: mysql-cluster-replication-issues. (line 35) * MySQL Cluster replication, known issues: mysql-cluster-replication-issues. (line 6) * MySQL Cluster replication, loss of connection: mysql-cluster-replication-issues. (line 12) * MySQL Cluster replication, multi-master replication: mysql-cluster-replication-multi-master. (line 6) * MySQL Cluster replication, point-in-time recovery: mysql-cluster-replication-pitr. (line 6) * MySQL Cluster replication, preparing: mysql-cluster-replication-preparation. (line 6) * MySQL Cluster replication, requirements: mysql-cluster-replication-general. (line 6) * MySQL Cluster replication, reset-slave.pl backup automation script: mysql-cluster-replication-auto-sync. (line 11) * MySQL Cluster replication, restoring from backup: mysql-cluster-replication-backups. (line 11) * MySQL Cluster replication, starting: mysql-cluster-replication-starting. (line 6) * MySQL Cluster replication, storage engines other than NDB on slave: mysql-cluster-replication-issues. (line 259) * MySQL Cluster replication, synchronization of master and slave: mysql-cluster-replication-auto-sync. (line 6) * MySQL Cluster replication, system tables used: mysql-cluster-replication-schema. (line 6) * MySQL Cluster, "quick" configuration: mysql-cluster-quick. (line 6) * MySQL Cluster, administration <1>: mysql-cluster-log-statistics. (line 6) * MySQL Cluster, administration <2>: mysql-cluster-mgm-client-commands. (line 6) * MySQL Cluster, administration <3>: mysql-cluster-program-options-common. (line 6) * MySQL Cluster, administration <4>: mysql-cluster-programs-ndb-mgm. (line 6) * MySQL Cluster, administration <5>: mysql-cluster-programs-ndb-mgmd. (line 12) * MySQL Cluster, administration <6>: mysql-cluster-programs-ndbd. (line 17) * MySQL Cluster, administration: mysql-cluster-program-options-mysqld. (line 6) * MySQL Cluster, and application feature requirements: mysql-cluster-ndb-innodb-usage. (line 6) * MySQL Cluster, and character sets: mysql-cluster-replication-issues. (line 67) * MySQL Cluster, and DNS: mysql-cluster-installation. (line 61) * MySQL Cluster, and INFORMATION_SCHEMA: mysql-cluster-security-mysql-privileges. (line 117) * MySQL Cluster, and IP addressing: mysql-cluster-installation. (line 61) * MySQL Cluster, and MySQL privileges: mysql-cluster-security-mysql-privileges. (line 6) * MySQL Cluster, and MySQL root user <1>: mysql-cluster-security-mysql-security-procedures. (line 50) * MySQL Cluster, and MySQL root user: mysql-cluster-security-mysql-privileges. (line 51) * MySQL Cluster, and networking: mysql-cluster-overview-requirements. (line 6) * MySQL Cluster, and transactions <1>: faqs-mysql-cluster. (line 6) * MySQL Cluster, and transactions: mysql-cluster-ndbd-definition. (line 424) * MySQL Cluster, and virtual machines: faqs-mysql-cluster. (line 6) * MySQL Cluster, API node <1>: mysql-cluster-api-definition. (line 6) * MySQL Cluster, API node: mysql-cluster-basics. (line 6) * MySQL Cluster, applications supported: mysql-cluster-ndb-innodb-workloads. (line 6) * MySQL Cluster, arbitrator: faqs-mysql-cluster. (line 6) * MySQL Cluster, availability: mysql-cluster-compared. (line 36) * MySQL Cluster, available platforms: mysql-cluster. (line 72) * MySQL Cluster, backups <1>: mysql-cluster-backup-troubleshooting. (line 6) * MySQL Cluster, backups <2>: mysql-cluster-backup-configuration. (line 6) * MySQL Cluster, backups <3>: mysql-cluster-backup-using-management-client. (line 6) * MySQL Cluster, backups <4>: mysql-cluster-backup-concepts. (line 6) * MySQL Cluster, backups <5>: mysql-cluster-backup. (line 13) * MySQL Cluster, backups: mysql-cluster-programs-ndb-restore. (line 6) * MySQL Cluster, benchmarks: mysql-cluster-interconnects-performance. (line 6) * MySQL Cluster, CHECKPOINT Events: mysql-cluster-log-events. (line 39) * MySQL Cluster, cluster logs <1>: mysql-cluster-logging-management-commands. (line 6) * MySQL Cluster, cluster logs: mysql-cluster-event-reports. (line 12) * MySQL Cluster, CLUSTERLOG commands: mysql-cluster-logging-management-commands. (line 12) * MySQL Cluster, CLUSTERLOG STATISTICS command: mysql-cluster-log-statistics. (line 6) * MySQL Cluster, commands <1>: mysql-cluster-mgm-client-commands. (line 6) * MySQL Cluster, commands <2>: mysql-cluster-programs-ndb-mgm. (line 27) * MySQL Cluster, commands <3>: mysql-cluster-programs-ndb-mgmd. (line 12) * MySQL Cluster, commands <4>: mysql-cluster-programs-ndbd. (line 17) * MySQL Cluster, commands: mysql-cluster-program-options-mysqld. (line 6) * MySQL Cluster, compared to InnoDB <1>: mysql-cluster-ndb-innodb-usage. (line 6) * MySQL Cluster, compared to InnoDB <2>: mysql-cluster-ndb-innodb-workloads. (line 6) * MySQL Cluster, compared to InnoDB <3>: mysql-cluster-ndb-innodb-engines. (line 6) * MySQL Cluster, compared to InnoDB: mysql-cluster-compared. (line 12) * MySQL Cluster, compared to standalone MySQL Server <1>: mysql-cluster-ndb-innodb-usage. (line 6) * MySQL Cluster, compared to standalone MySQL Server <2>: mysql-cluster-ndb-innodb-workloads. (line 6) * MySQL Cluster, compared to standalone MySQL Server <3>: mysql-cluster-ndb-innodb-engines. (line 6) * MySQL Cluster, compared to standalone MySQL Server: mysql-cluster-compared. (line 12) * MySQL Cluster, compiling with icc: porting. (line 32) * MySQL Cluster, concepts: mysql-cluster-basics. (line 6) * MySQL Cluster, configuration <1>: mysql-cluster-mysqld. (line 49) * MySQL Cluster, configuration <2>: mysql-cluster-programs-ndb-mgmd. (line 582) * MySQL Cluster, configuration <3>: mysql-cluster-config-lcp-params. (line 6) * MySQL Cluster, configuration <4>: mysql-cluster-api-definition. (line 6) * MySQL Cluster, configuration <5>: mysql-cluster-ndbd-definition. (line 6) * MySQL Cluster, configuration <6>: mysql-cluster-mgm-definition. (line 6) * MySQL Cluster, configuration <7>: mysql-cluster-computer-definition. (line 6) * MySQL Cluster, configuration <8>: mysql-cluster-quick. (line 6) * MySQL Cluster, configuration <9>: mysql-cluster-configuration. (line 14) * MySQL Cluster, configuration: mysql-cluster-installation. (line 16) * MySQL Cluster, configuration (example): mysql-cluster-config-example. (line 6) * MySQL Cluster, configuration changes: mysql-cluster-rolling-restart. (line 20) * MySQL Cluster, configuration files <1>: mysql-cluster-config-file. (line 22) * MySQL Cluster, configuration files: mysql-cluster-install-configuration. (line 6) * MySQL Cluster, configuration parameters <1>: mysql-cluster-params-other. (line 6) * MySQL Cluster, configuration parameters <2>: mysql-cluster-params-api. (line 6) * MySQL Cluster, configuration parameters <3>: mysql-cluster-params-mgmd. (line 6) * MySQL Cluster, configuration parameters <4>: mysql-cluster-params-ndbd. (line 6) * MySQL Cluster, configuration parameters: mysql-cluster-params-overview. (line 13) * MySQL Cluster, configuring: mysql-cluster-backup-configuration. (line 6) * MySQL Cluster, CONNECTION Events: mysql-cluster-log-events. (line 20) * MySQL Cluster, connection string: mysql-cluster-connection-strings. (line 6) * MySQL Cluster, CREATE NODEGROUP command: mysql-cluster-mgm-client-commands. (line 209) * MySQL Cluster, creating large tables: create-table. (line 864) * MySQL Cluster, data node <1>: mysql-cluster-ndbd-definition. (line 6) * MySQL Cluster, data node: mysql-cluster-basics. (line 6) * MySQL Cluster, data nodes <1>: mysql-cluster-programs-ndbmtd. (line 6) * MySQL Cluster, data nodes: mysql-cluster-programs-ndbd. (line 6) * MySQL Cluster, data types supported: faqs-mysql-cluster. (line 6) * MySQL Cluster, defining node hosts: mysql-cluster-computer-definition. (line 6) * MySQL Cluster, direct connections between nodes: mysql-cluster-tcp-definition-direct. (line 6) * MySQL Cluster, Disk Data tables: mysql-cluster-disk-data. (line 12) * MySQL Cluster, DROP NODEGROUP command: mysql-cluster-mgm-client-commands. (line 232) * MySQL Cluster, ENTER SINGLE USER MODE command: mysql-cluster-mgm-client-commands. (line 176) * MySQL Cluster, ERROR Events: mysql-cluster-log-events. (line 219) * MySQL Cluster, error logs: mysql-cluster-programs-ndbd. (line 442) * MySQL Cluster, error messages: faqs-mysql-cluster. (line 6) * MySQL Cluster, event log format: mysql-cluster-log-events. (line 6) * MySQL Cluster, event logging thresholds: mysql-cluster-logging-management-commands. (line 38) * MySQL Cluster, event logs <1>: mysql-cluster-logging-management-commands. (line 6) * MySQL Cluster, event logs: mysql-cluster-event-reports. (line 12) * MySQL Cluster, event severity levels: mysql-cluster-logging-management-commands. (line 62) * MySQL Cluster, event types <1>: mysql-cluster-log-events. (line 20) * MySQL Cluster, event types: mysql-cluster-event-reports. (line 49) * MySQL Cluster, execution threads: mysql-cluster-ndbd-definition. (line 3244) * MySQL Cluster, EXIT command: mysql-cluster-mgm-client-commands. (line 194) * MySQL Cluster, EXIT SINGLE USER MODE command: mysql-cluster-mgm-client-commands. (line 184) * MySQL Cluster, FAQ: faqs-mysql-cluster. (line 6) * MySQL Cluster, features added in MySQL 5.1: mysql-cluster-development-5-1. (line 6) * MySQL Cluster, GCP Stop errors: mysql-cluster-ndbd-definition. (line 3784) * MySQL Cluster, general description: mysql-cluster-overview. (line 15) * MySQL Cluster, hardware requirements: faqs-mysql-cluster. (line 6) * MySQL Cluster, HELP command: mysql-cluster-mgm-client-commands. (line 34) * MySQL Cluster, HostName parameter, and security: mysql-cluster-security-networking-issues. (line 40) * MySQL Cluster, how to obtain: faqs-mysql-cluster. (line 6) * MySQL Cluster, importing existing tables: faqs-mysql-cluster. (line 6) * MySQL Cluster, INFO Events: mysql-cluster-log-events. (line 237) * MySQL Cluster, information sources: mysql-cluster. (line 215) * MySQL Cluster, insecurity of communication protocols: mysql-cluster-security-networking-issues. (line 12) * MySQL Cluster, installation: mysql-cluster-installation. (line 16) * MySQL Cluster, installation (Linux): mysql-cluster-install-linux. (line 12) * MySQL Cluster, installation (Windows): mysql-cluster-install-windows. (line 13) * MySQL Cluster, installing binary (Windows): mysql-cluster-install-windows-binary. (line 6) * MySQL Cluster, installing binary release (Linux): mysql-cluster-install-linux-binary. (line 6) * MySQL Cluster, installing from source (Linux): mysql-cluster-install-linux-source. (line 6) * MySQL Cluster, installing from source (Windows): mysql-cluster-install-windows-source. (line 6) * MySQL Cluster, installing RPM (Linux): mysql-cluster-install-linux-rpm. (line 6) * MySQL Cluster, interconnects: mysql-cluster-interconnects. (line 11) * MySQL Cluster, Java clients: mysql-cluster-basics. (line 116) * MySQL Cluster, log files <1>: mysql-cluster-programs-ndbmtd. (line 67) * MySQL Cluster, log files: mysql-cluster-programs-ndbd. (line 433) * MySQL Cluster, logging commands: mysql-cluster-logging-management-commands. (line 6) * MySQL Cluster, management client (ndb_mgm): mysql-cluster-programs-ndb-mgm. (line 6) * MySQL Cluster, management commands: mysql-cluster-log-statistics. (line 6) * MySQL Cluster, management node <1>: mysql-cluster-mgm-definition. (line 6) * MySQL Cluster, management node: mysql-cluster-basics. (line 6) * MySQL Cluster, management nodes: mysql-cluster-programs-ndb-mgmd. (line 6) * MySQL Cluster, managing: mysql-cluster-management. (line 24) * MySQL Cluster, master node: faqs-mysql-cluster. (line 6) * MySQL Cluster, MAX_ROWS: create-table. (line 864) * MySQL Cluster, memory requirements: faqs-mysql-cluster. (line 6) * MySQL Cluster, memory usage and recovery <1>: mysql-cluster-rolling-restart. (line 64) * MySQL Cluster, memory usage and recovery: mysql-cluster-limitations-limits. (line 9) * MySQL Cluster, mgm: mysql-cluster-program-options-common. (line 6) * MySQL Cluster, mgm client: mysql-cluster-mgm-client-commands. (line 6) * MySQL Cluster, mgm management client: mysql-cluster-log-statistics. (line 6) * MySQL Cluster, mgm process: mysql-cluster-programs-ndb-mgm. (line 27) * MySQL Cluster, mgmd: mysql-cluster-program-options-common. (line 6) * MySQL Cluster, mgmd process: mysql-cluster-programs-ndb-mgmd. (line 12) * MySQL Cluster, monitoring: mysql-cluster-ndb-api-statistics. (line 6) * MySQL Cluster, multiple management servers: mysql-cluster-rolling-restart. (line 174) * MySQL Cluster, mysqld options and variables for: mysql-cluster-options-variables. (line 13) * MySQL Cluster, mysqld process <1>: mysql-cluster-mysqld. (line 6) * MySQL Cluster, mysqld process: mysql-cluster-program-options-mysqld. (line 6) * MySQL Cluster, ndb_mgm <1>: mysql-cluster-programs-ndb-mgm. (line 6) * MySQL Cluster, ndb_mgm: mysql-cluster-install-first-start. (line 34) * MySQL Cluster, ndb_mgmd process: mysql-cluster-programs-ndb-mgmd. (line 6) * MySQL Cluster, ndb_size.pl (utility): faqs-mysql-cluster. (line 6) * MySQL Cluster, ndbd <1>: mysql-cluster-program-options-common. (line 6) * MySQL Cluster, ndbd: mysql-cluster-programs-ndbd. (line 6) * MySQL Cluster, ndbd process <1>: mysql-cluster-log-statistics. (line 164) * MySQL Cluster, ndbd process: mysql-cluster-programs-ndbd. (line 17) * MySQL Cluster, ndbinfo_select_all: mysql-cluster-programs-ndbinfo-select-all. (line 6) * MySQL Cluster, ndbmtd: mysql-cluster-programs-ndbmtd. (line 6) * MySQL Cluster, network configuration, and security: mysql-cluster-security-networking-issues. (line 59) * MySQL Cluster, network transporters <1>: mysql-cluster-sci-sockets. (line 6) * MySQL Cluster, network transporters: mysql-cluster-interconnects. (line 11) * MySQL Cluster, networking <1>: mysql-cluster-sci-definition. (line 6) * MySQL Cluster, networking <2>: mysql-cluster-shm-definition. (line 6) * MySQL Cluster, networking: mysql-cluster-tcp-definition-direct. (line 6) * MySQL Cluster, networking requirements: faqs-mysql-cluster. (line 6) * MySQL Cluster, node failure (single user mode): mysql-cluster-single-user-mode. (line 52) * MySQL Cluster, node identifiers <1>: mysql-cluster-sci-definition. (line 26) * MySQL Cluster, node identifiers: mysql-cluster-shm-definition. (line 25) * MySQL Cluster, node logs: mysql-cluster-event-reports. (line 12) * MySQL Cluster, node types: faqs-mysql-cluster. (line 6) * MySQL Cluster, NODERESTART Events: mysql-cluster-log-events. (line 103) * MySQL Cluster, nodes and node groups: mysql-cluster-nodes-groups. (line 6) * MySQL Cluster, nodes and types: mysql-cluster-basics. (line 6) * MySQL Cluster, number of computers required: faqs-mysql-cluster. (line 6) * MySQL Cluster, partitioning support: mysql-cluster-limitations-syntax. (line 106) * MySQL Cluster, partitions: mysql-cluster-nodes-groups. (line 6) * MySQL Cluster, performance: mysql-cluster-interconnects-performance. (line 6) * MySQL Cluster, performing queries: mysql-cluster-install-example-data. (line 6) * MySQL Cluster, platforms supported: faqs-mysql-cluster. (line 6) * MySQL Cluster, preparing for replication: mysql-cluster-replication-preparation. (line 6) * MySQL Cluster, process management: mysql-cluster-programs. (line 34) * MySQL Cluster, QUIT command: mysql-cluster-mgm-client-commands. (line 194) * MySQL Cluster, replicas: mysql-cluster-nodes-groups. (line 6) * MySQL Cluster, replication: mysql-cluster-replication. (line 20) * MySQL Cluster, REPORT command: mysql-cluster-mgm-client-commands. (line 140) * MySQL Cluster, requirements: mysql-cluster-overview-requirements. (line 6) * MySQL Cluster, resetting: mysql-cluster-rolling-restart. (line 38) * MySQL Cluster, RESTART command: mysql-cluster-mgm-client-commands. (line 101) * MySQL Cluster, restarting: mysql-cluster-install-shutdown-restart. (line 6) * MySQL Cluster, restoring backups: mysql-cluster-programs-ndb-restore. (line 6) * MySQL Cluster, roles of computers: faqs-mysql-cluster. (line 6) * MySQL Cluster, rolling restarts (multiple management servers): mysql-cluster-rolling-restart. (line 174) * MySQL Cluster, runtime statistics: mysql-cluster-log-statistics. (line 6) * MySQL Cluster, SCI (Scalable Coherent Interface) <1>: mysql-cluster-sci-sockets. (line 6) * MySQL Cluster, SCI (Scalable Coherent Interface): mysql-cluster-sci-definition. (line 6) * MySQL Cluster, security <1>: faqs-mysql-cluster. (line 6) * MySQL Cluster, security: mysql-cluster-security. (line 12) * MySQL Cluster, security procedures: mysql-cluster-security-mysql-security-procedures. (line 6) * MySQL Cluster, security, and firewalls: mysql-cluster-security-networking-issues. (line 98) * MySQL Cluster, security, and HostName parameter: mysql-cluster-security-networking-issues. (line 40) * MySQL Cluster, security, and network configuration: mysql-cluster-security-networking-issues. (line 59) * MySQL Cluster, security, and network ports: mysql-cluster-security-networking-issues. (line 186) * MySQL Cluster, security, and remote administration: mysql-cluster-security-networking-issues. (line 193) * MySQL Cluster, security, networking: mysql-cluster-security-networking-issues. (line 6) * MySQL Cluster, shared memory transport: mysql-cluster-shm-definition. (line 6) * MySQL Cluster, SHOW command: mysql-cluster-mgm-client-commands. (line 38) * MySQL Cluster, SHUTDOWN command: mysql-cluster-mgm-client-commands. (line 200) * MySQL Cluster, shutting down: mysql-cluster-install-shutdown-restart. (line 6) * MySQL Cluster, single user mode <1>: mysql-cluster-single-user-mode. (line 6) * MySQL Cluster, single user mode: mysql-cluster-mgm-client-commands. (line 176) * MySQL Cluster, SQL node <1>: mysql-cluster-api-definition. (line 6) * MySQL Cluster, SQL node: mysql-cluster-basics. (line 6) * MySQL Cluster, SQL nodes: mysql-cluster-mysqld. (line 6) * MySQL Cluster, SQL statements: faqs-mysql-cluster. (line 6) * MySQL Cluster, SQL statements for monitoring: mysql-cluster-sql-statements. (line 6) * MySQL Cluster, START BACKUP command: mysql-cluster-replication-backups. (line 40) * MySQL Cluster, START command: mysql-cluster-mgm-client-commands. (line 57) * MySQL Cluster, start phases (summary): mysql-cluster-start-phases. (line 6) * MySQL Cluster, starting: mysql-cluster-quick. (line 6) * MySQL Cluster, starting and stopping: faqs-mysql-cluster. (line 6) * MySQL Cluster, starting nodes <1>: mysql-cluster-install-first-start. (line 6) * MySQL Cluster, starting nodes: mysql-cluster-install-windows-initial-start. (line 6) * MySQL Cluster, starting or restarting: mysql-cluster-start-phases. (line 6) * MySQL Cluster, STARTUP Events: mysql-cluster-log-events. (line 62) * MySQL Cluster, STATISTICS Events: mysql-cluster-log-events. (line 191) * MySQL Cluster, STATUS command: mysql-cluster-mgm-client-commands. (line 131) * MySQL Cluster, status variables: mysql-cluster-status-variables. (line 6) * MySQL Cluster, STOP command: mysql-cluster-mgm-client-commands. (line 72) * MySQL Cluster, storage requirements: storage-requirements. (line 35) * MySQL Cluster, Table is full errors: faqs-mysql-cluster. (line 6) * MySQL Cluster, thread states: mysql-cluster-thread-states. (line 6) * MySQL Cluster, trace files: mysql-cluster-programs-ndbd. (line 474) * MySQL Cluster, transaction handling: mysql-cluster-limitations-transactions. (line 109) * MySQL Cluster, transporters, Scalable Coherent Interface (SCI): mysql-cluster-sci-definition. (line 6) * MySQL Cluster, transporters, shared memory (SHM): mysql-cluster-shm-definition. (line 6) * MySQL Cluster, transporters, TCP/IP: mysql-cluster-tcp-definition-direct. (line 6) * MySQL Cluster, troubleshooting backups: mysql-cluster-backup-troubleshooting. (line 6) * MySQL Cluster, upgrades and downgrades <1>: mysql-cluster-rolling-restart. (line 6) * MySQL Cluster, upgrades and downgrades: mysql-cluster-upgrade-downgrade. (line 12) * MySQL Cluster, using tables and data: mysql-cluster-install-example-data. (line 6) * MySQL Cluster, vs replication: faqs-mysql-cluster. (line 6) * mysql command options: mysql-command-options. (line 6) * mysql commands, list of: mysql-commands. (line 11) * MySQL Dolphin name: history. (line 6) * MySQL Enterprise Audit: mysql-enterprise-audit. (line 6) * MySQL Enterprise Backup: mysql-enterprise-backup. (line 6) * MySQL Enterprise Monitor: mysql-enterprise-monitor. (line 6) * MySQL Enterprise Security: mysql-enterprise-security. (line 6) * MySQL Enterprise Thread Pool: mysql-enterprise-thread-pool. (line 6) * MySQL history: history. (line 6) * mysql history file: mysql-logging. (line 6) * MySQL Instance Manager: instance-manager. (line 16) * MySQL mailing lists: mailing-lists. (line 10) * MySQL name: history. (line 6) * MySQL Notifier: windows-notifier. (line 10) * MySQL privileges, and MySQL Cluster: mysql-cluster-security-mysql-privileges. (line 10) * mysql prompt command: mysql-commands. (line 291) * MySQL server, mysqld <1>: mysqld-server. (line 20) * MySQL server, mysqld: mysqld. (line 6) * mysql source (command for reading from text files) <1>: mysql-batch-commands. (line 6) * mysql source (command for reading from text files): batch-mode. (line 90) * MySQL source distribution: which-version. (line 18) * MySQL storage engines: storage-engines. (line 23) * MySQL system tables, and MySQL Cluster: mysql-cluster-security-mysql-privileges. (line 23) * MySQL system tables, and replication: replication-features-mysqldb. (line 6) * MySQL version: getting-mysql. (line 6) * mysql, auto-rehash option: mysql-command-options. (line 159) * mysql, batch option: mysql-command-options. (line 173) * mysql, bind-address option: mysql-command-options. (line 183) * mysql, character-sets-dir option: mysql-command-options. (line 194) * mysql, charset command: mysql-commands. (line 61) * mysql, clear command: mysql-commands. (line 70) * mysql, column-names option: mysql-command-options. (line 199) * mysql, column-type-info option: mysql-command-options. (line 203) * mysql, comments option: mysql-command-options. (line 209) * mysql, compress option: mysql-command-options. (line 216) * mysql, connect command: mysql-commands. (line 75) * mysql, database option: mysql-command-options. (line 221) * mysql, debug option: mysql-command-options. (line 225) * mysql, debug-check option: mysql-command-options. (line 230) * mysql, debug-info option: mysql-command-options. (line 235) * mysql, default-character-set option: mysql-command-options. (line 243) * MySQL, defined: what-is-mysql. (line 6) * mysql, delimiter command: mysql-commands. (line 82) * mysql, delimiter option: mysql-command-options. (line 257) * mysql, disable named commands: mysql-command-options. (line 262) * mysql, edit command: mysql-commands. (line 117) * mysql, ego command: mysql-commands. (line 126) * mysql, execute option: mysql-command-options. (line 270) * mysql, exit command: mysql-commands. (line 131) * mysql, force option: mysql-command-options. (line 277) * mysql, go command: mysql-commands. (line 135) * mysql, help command: mysql-commands. (line 51) * mysql, help option: mysql-command-options. (line 155) * mysql, host option: mysql-command-options. (line 281) * mysql, html option: mysql-command-options. (line 285) * mysql, i-am-a-dummy option: mysql-command-options. (line 469) * mysql, ignore-spaces option: mysql-command-options. (line 289) * MySQL, introduction: what-is-mysql. (line 6) * mysql, line-numbers option: mysql-command-options. (line 295) * mysql, local-infile option: mysql-command-options. (line 300) * mysql, named-commands option: mysql-command-options. (line 308) * mysql, no-auto-rehash option: mysql-command-options. (line 315) * mysql, no-beep option: mysql-command-options. (line 320) * mysql, no-named-commands option: mysql-command-options. (line 324) * mysql, no-pager option: mysql-command-options. (line 329) * mysql, no-tee option: mysql-command-options. (line 334) * mysql, nopager command: mysql-commands. (line 139) * mysql, notee command: mysql-commands. (line 145) * mysql, nowarning command: mysql-commands. (line 150) * mysql, one-database option: mysql-command-options. (line 339) * mysql, pager command: mysql-commands. (line 154) * mysql, pager option: mysql-command-options. (line 382) * mysql, password option: mysql-command-options. (line 391) * mysql, pipe option: mysql-command-options. (line 403) * mysql, port option: mysql-command-options. (line 408) * mysql, print command: mysql-commands. (line 176) * mysql, prompt command: mysql-commands. (line 180) * mysql, prompt option: mysql-command-options. (line 412) * MySQL, pronunciation: what-is-mysql. (line 107) * mysql, protocol option: mysql-command-options. (line 418) * mysql, quick option: mysql-command-options. (line 425) * mysql, quit command: mysql-commands. (line 189) * mysql, raw option: mysql-command-options. (line 431) * mysql, reconnect option: mysql-command-options. (line 462) * mysql, rehash command: mysql-commands. (line 193) * mysql, safe-updates option: mysql-command-options. (line 469) * mysql, secure-auth option: mysql-command-options. (line 477) * mysql, show-warnings option: mysql-command-options. (line 483) * mysql, sigint-ignore option: mysql-command-options. (line 488) * mysql, silent option: mysql-command-options. (line 493) * mysql, skip-column-names option: mysql-command-options. (line 502) * mysql, skip-line-numbers option: mysql-command-options. (line 506) * mysql, socket option: mysql-command-options. (line 511) * mysql, source command: mysql-commands. (line 199) * mysql, SSL options: mysql-command-options. (line 516) * mysql, status command: mysql-commands. (line 204) * mysql, system command: mysql-commands. (line 211) * mysql, table option: mysql-command-options. (line 522) * mysql, tee command: mysql-commands. (line 217) * mysql, tee option: mysql-command-options. (line 528) * mysql, unbuffered option: mysql-command-options. (line 534) * MySQL, upgrading: mysql-upgrade. (line 6) * mysql, use command: mysql-commands. (line 231) * mysql, user option: mysql-command-options. (line 538) * mysql, verbose option: mysql-command-options. (line 542) * mysql, version option: mysql-command-options. (line 549) * mysql, vertical option: mysql-command-options. (line 553) * mysql, wait option: mysql-command-options. (line 559) * mysql, warnings command: mysql-commands. (line 235) * mysql, xml option: mysql-command-options. (line 564) * MySql.Data class: connector-net-ref. (line 11) * MySql.Data.dll library <1>: connector-net-installation-unix. (line 6) * MySql.Data.dll library: connector-net-installation-binary-windows-zip. (line 6) * mysql.data.ef.dll library: connector-net-visual-studio. (line 23) * MySql.Data.MySqlClient.Replication: connector-net-ref-replication. (line 13) * MySql.Data.MySqlClient.Replication namespace: connector-net-ref-replication. (line 13) * mysql.event table: events-privileges. (line 145) * mysql.ndb_binlog_index table: mysql-cluster-replication-schema. (line 6) * mysql.server <1>: mysql-server. (line 6) * mysql.server: programs-overview. (line 50) * mysql.server, basedir option: mysql-server. (line 36) * mysql.server, datadir option: mysql-server. (line 40) * mysql.server, pid-file option: mysql-server. (line 44) * mysql.server, service-startup-timeout option: mysql-server. (line 49) * mysql.server, use-manager option: mysql-server. (line 63) * mysql.server, use-mysqld_safe option: mysql-server. (line 58) * mysql.server, user option: mysql-server. (line 67) * mysql.sock, changing location of: source-configuration-options. (line 377) * mysql.sock, protection: problems-with-mysql-sock. (line 6) * mysql.visualstudio.dll library: connector-net-visual-studio. (line 23) * MYSQL323 SQL mode: server-sql-mode. (line 540) * MYSQL40 SQL mode: server-sql-mode. (line 544) * mysql_affected_rows(): mysql-affected-rows. (line 6) * mysql_autocommit(): mysql-autocommit. (line 6) * MYSQL_BIND C type: c-api-prepared-statement-data-structures. (line 51) * mysql_change_user(): mysql-change-user. (line 6) * mysql_character_set_name(): mysql-character-set-name. (line 6) * mysql_close(): mysql-close. (line 6) * mysql_cluster_move_privileges: mysql-cluster-privilege-distribution. (line 54) * mysql_cluster_privileges_are_distributed: mysql-cluster-privilege-distribution. (line 83) * mysql_commit(): mysql-commit. (line 6) * mysql_config: mysql-config. (line 6) * mysql_config, cflags option: mysql-config. (line 13) * mysql_config, embedded option: mysql-config. (line 26) * mysql_config, include option: mysql-config. (line 22) * mysql_config, libmysqld-libs option: mysql-config. (line 26) * mysql_config, libs option: mysql-config. (line 31) * mysql_config, libs_r option: mysql-config. (line 36) * mysql_config, plugindir option: mysql-config. (line 41) * mysql_config, port option: mysql-config. (line 46) * mysql_config, socket option: mysql-config. (line 50) * mysql_config, version option: mysql-config. (line 54) * mysql_connect(): mysql-connect. (line 6) * mysql_convert_table_format <1>: mysql-convert-table-format. (line 6) * mysql_convert_table_format: programs-overview. (line 221) * mysql_convert_table_format, force option: mysql-convert-table-format. (line 28) * mysql_convert_table_format, help option: mysql-convert-table-format. (line 24) * mysql_convert_table_format, host option: mysql-convert-table-format. (line 32) * mysql_convert_table_format, password option: mysql-convert-table-format. (line 36) * mysql_convert_table_format, port option: mysql-convert-table-format. (line 46) * mysql_convert_table_format, socket option: mysql-convert-table-format. (line 50) * mysql_convert_table_format, type option: mysql-convert-table-format. (line 54) * mysql_convert_table_format, user option: mysql-convert-table-format. (line 59) * mysql_convert_table_format, verbose option: mysql-convert-table-format. (line 63) * mysql_convert_table_format, version option: mysql-convert-table-format. (line 67) * mysql_create_db(): mysql-create-db. (line 6) * mysql_data_seek(): mysql-data-seek. (line 6) * MYSQL_DEBUG environment variable <1>: debugging-client. (line 10) * MYSQL_DEBUG environment variable <2>: programs-overview. (line 304) * MYSQL_DEBUG environment variable: environment-variables. (line 18) * mysql_debug(): mysql-debug. (line 6) * mysql_drop_db(): mysql-drop-db. (line 6) * mysql_dump_debug_info(): mysql-dump-debug-info. (line 6) * mysql_eof(): mysql-eof. (line 6) * mysql_errno(): mysql-errno. (line 6) * mysql_error(): mysql-error. (line 6) * mysql_escape_string(): mysql-escape-string. (line 6) * mysql_fetch_field(): mysql-fetch-field. (line 6) * mysql_fetch_field_direct(): mysql-fetch-field-direct. (line 6) * mysql_fetch_fields(): mysql-fetch-fields. (line 6) * mysql_fetch_lengths(): mysql-fetch-lengths. (line 6) * mysql_fetch_row(): mysql-fetch-row. (line 6) * MYSQL_FIELD C type: c-api-data-structures. (line 34) * mysql_field_count() <1>: mysql-num-fields. (line 6) * mysql_field_count(): mysql-field-count. (line 6) * MYSQL_FIELD_OFFSET C type: c-api-data-structures. (line 44) * mysql_field_seek(): mysql-field-seek. (line 6) * mysql_field_tell(): mysql-field-tell. (line 6) * mysql_find_rows <1>: mysql-find-rows. (line 6) * mysql_find_rows: programs-overview. (line 226) * mysql_find_rows, help option: mysql-find-rows. (line 31) * mysql_find_rows, regexp option: mysql-find-rows. (line 35) * mysql_find_rows, rows option: mysql-find-rows. (line 39) * mysql_find_rows, skip-use-db option: mysql-find-rows. (line 43) * mysql_find_rows, start_row option: mysql-find-rows. (line 47) * mysql_fix_extensions <1>: mysql-fix-extensions. (line 6) * mysql_fix_extensions: programs-overview. (line 232) * mysql_fix_privilege_tables <1>: mysql-fix-privilege-tables. (line 6) * mysql_fix_privilege_tables: programs-overview. (line 86) * mysql_free_result(): mysql-free-result. (line 6) * mysql_get_character_set_info(): mysql-get-character-set-info. (line 6) * mysql_get_client_info(): mysql-get-client-info. (line 6) * mysql_get_client_version(): mysql-get-client-version. (line 6) * mysql_get_host_info(): mysql-get-host-info. (line 6) * mysql_get_proto_info(): mysql-get-proto-info. (line 6) * mysql_get_server_info(): mysql-get-server-info. (line 6) * mysql_get_server_version(): mysql-get-server-version. (line 6) * mysql_get_ssl_cipher(): mysql-get-ssl-cipher. (line 6) * MYSQL_GROUP_SUFFIX environment variable: environment-variables. (line 18) * mysql_hex_string(): mysql-hex-string. (line 6) * MYSQL_HISTFILE environment variable <1>: mysql-logging. (line 6) * MYSQL_HISTFILE environment variable: environment-variables. (line 18) * MYSQL_HOME environment variable: environment-variables. (line 18) * MYSQL_HOST environment variable <1>: connecting. (line 235) * MYSQL_HOST environment variable: environment-variables. (line 18) * mysql_info() <1>: mysql-info. (line 6) * mysql_info() <2>: update. (line 86) * mysql_info() <3>: load-data. (line 702) * mysql_info() <4>: insert. (line 202) * mysql_info(): alter-table. (line 568) * mysql_init(): mysql-init. (line 6) * mysql_insert_id() <1>: mysql-insert-id. (line 6) * mysql_insert_id() <2>: insert. (line 206) * mysql_insert_id(): ansi-diff-transactions. (line 159) * mysql_install_db <1>: mysql-install-db. (line 6) * mysql_install_db <2>: programs-overview. (line 95) * mysql_install_db: mysql-install-db-problems. (line 6) * mysql_install_db, basedir option: mysql-install-db. (line 56) * mysql_install_db, datadir option: mysql-install-db. (line 60) * mysql_install_db, force option: mysql-install-db. (line 64) * mysql_install_db, ldata option: mysql-install-db. (line 60) * mysql_install_db, rpm option: mysql-install-db. (line 70) * mysql_install_db, skip-name-resolve option: mysql-install-db. (line 76) * mysql_install_db, srcdir option: mysql-install-db. (line 81) * mysql_install_db, user option: mysql-install-db. (line 88) * mysql_install_db, verbose option: mysql-install-db. (line 97) * mysql_install_db, windows option: mysql-install-db. (line 101) * mysql_kill(): mysql-kill. (line 6) * mysql_library_end(): mysql-library-end. (line 6) * mysql_library_init(): mysql-library-init. (line 6) * mysql_list_dbs(): mysql-list-dbs. (line 6) * mysql_list_fields(): mysql-list-fields. (line 6) * mysql_list_processes(): mysql-list-processes. (line 6) * mysql_list_tables(): mysql-list-tables. (line 6) * mysql_more_results(): mysql-more-results. (line 6) * mysql_next_result(): mysql-next-result. (line 6) * mysql_num_fields(): mysql-num-fields. (line 6) * mysql_num_rows(): mysql-num-rows. (line 6) * mysql_options(): mysql-options. (line 6) * mysql_ping(): mysql-ping. (line 6) * MYSQL_PS1 environment variable: environment-variables. (line 18) * MYSQL_PWD environment variable <1>: connecting. (line 235) * MYSQL_PWD environment variable <2>: programs-overview. (line 304) * MYSQL_PWD environment variable: environment-variables. (line 18) * mysql_query() <1>: c-api-problems. (line 12) * mysql_query(): mysql-query. (line 6) * mysql_real_connect(): mysql-real-connect. (line 6) * mysql_real_escape_string() <1>: mysql-real-escape-string. (line 6) * mysql_real_escape_string() <2>: string-functions. (line 535) * mysql_real_escape_string(): string-literals. (line 141) * mysql_real_query(): mysql-real-query. (line 6) * mysql_refresh(): mysql-refresh. (line 6) * mysql_reload(): mysql-reload. (line 6) * MYSQL_RES C type: c-api-data-structures. (line 17) * mysql_rollback(): mysql-rollback. (line 6) * MYSQL_ROW C type: c-api-data-structures. (line 25) * mysql_row_seek(): mysql-row-seek. (line 6) * mysql_row_tell(): mysql-row-tell. (line 6) * mysql_secure_installation <1>: mysql-secure-installation. (line 6) * mysql_secure_installation: programs-overview. (line 103) * mysql_select_db(): mysql-select-db. (line 6) * mysql_server_end(): mysql-server-end. (line 6) * mysql_server_init(): mysql-server-init. (line 6) * mysql_set_character_set(): mysql-set-character-set. (line 6) * mysql_set_local_infile_default(): mysql-set-local-infile-default. (line 6) * mysql_set_server_option(): mysql-set-server-option. (line 6) * mysql_setpermission <1>: mysql-setpermission. (line 6) * mysql_setpermission: programs-overview. (line 239) * mysql_setpermission, help option: mysql-setpermission. (line 29) * mysql_setpermission, host option: mysql-setpermission. (line 33) * mysql_setpermission, password option: mysql-setpermission. (line 37) * mysql_setpermission, port option: mysql-setpermission. (line 47) * mysql_setpermission, socket option: mysql-setpermission. (line 51) * mysql_setpermission, user option: mysql-setpermission. (line 55) * mysql_shutdown(): mysql-shutdown. (line 6) * mysql_sqlstate(): mysql-sqlstate. (line 6) * mysql_ssl_set(): mysql-ssl-set. (line 6) * mysql_stat(): mysql-stat. (line 6) * MYSQL_STMT C type: c-api-prepared-statement-data-structures. (line 34) * mysql_stmt_affected_rows(): mysql-stmt-affected-rows. (line 6) * mysql_stmt_attr_get(): mysql-stmt-attr-get. (line 6) * mysql_stmt_attr_set(): mysql-stmt-attr-set. (line 6) * mysql_stmt_bind_param(): mysql-stmt-bind-param. (line 6) * mysql_stmt_bind_result(): mysql-stmt-bind-result. (line 6) * mysql_stmt_close(): mysql-stmt-close. (line 6) * mysql_stmt_data_seek(): mysql-stmt-data-seek. (line 6) * mysql_stmt_errno(): mysql-stmt-errno. (line 6) * mysql_stmt_error(): mysql-stmt-error. (line 6) * mysql_stmt_execute(): mysql-stmt-execute. (line 6) * mysql_stmt_fetch(): mysql-stmt-fetch. (line 6) * mysql_stmt_fetch_column(): mysql-stmt-fetch-column. (line 6) * mysql_stmt_field_count(): mysql-stmt-field-count. (line 6) * mysql_stmt_free_result(): mysql-stmt-free-result. (line 6) * mysql_stmt_init(): mysql-stmt-init. (line 6) * mysql_stmt_insert_id(): mysql-stmt-insert-id. (line 6) * mysql_stmt_num_rows(): mysql-stmt-num-rows. (line 6) * mysql_stmt_param_count(): mysql-stmt-param-count. (line 6) * mysql_stmt_param_metadata(): mysql-stmt-param-metadata. (line 6) * mysql_stmt_prepare(): mysql-stmt-prepare. (line 6) * mysql_stmt_reset(): mysql-stmt-reset. (line 6) * mysql_stmt_result_metadata: mysql-stmt-result-metadata. (line 6) * mysql_stmt_row_seek(): mysql-stmt-row-seek. (line 6) * mysql_stmt_row_tell(): mysql-stmt-row-tell. (line 6) * mysql_stmt_send_long_data(): mysql-stmt-send-long-data. (line 6) * mysql_stmt_sqlstate(): mysql-stmt-sqlstate. (line 6) * mysql_stmt_store_result(): mysql-stmt-store-result. (line 6) * mysql_store_result() <1>: c-api-problems. (line 12) * mysql_store_result(): mysql-store-result. (line 6) * MYSQL_TCP_PORT environment variable <1>: multiple-server-clients. (line 27) * MYSQL_TCP_PORT environment variable <2>: multiple-unix-servers. (line 68) * MYSQL_TCP_PORT environment variable <3>: programs-overview. (line 304) * MYSQL_TCP_PORT environment variable: environment-variables. (line 18) * mysql_thread_end(): mysql-thread-end. (line 6) * mysql_thread_id(): mysql-thread-id. (line 6) * mysql_thread_init(): mysql-thread-init. (line 6) * mysql_thread_safe(): mysql-thread-safe. (line 6) * MYSQL_TIME C type: c-api-prepared-statement-data-structures. (line 245) * mysql_tzinfo_to_sql <1>: mysql-tzinfo-to-sql. (line 6) * mysql_tzinfo_to_sql: programs-overview. (line 108) * MYSQL_UNIX_PORT environment variable <1>: multiple-server-clients. (line 27) * MYSQL_UNIX_PORT environment variable <2>: multiple-unix-servers. (line 68) * MYSQL_UNIX_PORT environment variable <3>: programs-overview. (line 304) * MYSQL_UNIX_PORT environment variable <4>: environment-variables. (line 18) * MYSQL_UNIX_PORT environment variable: mysql-install-db-problems. (line 84) * mysql_upgrade <1>: access-denied. (line 83) * mysql_upgrade <2>: mysql-upgrade. (line 6) * mysql_upgrade: programs-overview. (line 115) * mysql_upgrade, basedir option: mysql-upgrade. (line 120) * mysql_upgrade, datadir option: mysql-upgrade. (line 125) * mysql_upgrade, debug-check option: mysql-upgrade. (line 130) * mysql_upgrade, debug-info option: mysql-upgrade. (line 135) * mysql_upgrade, force option: mysql-upgrade. (line 140) * mysql_upgrade, help option: mysql-upgrade. (line 116) * mysql_upgrade, mysql_upgrade_info file: mysql-upgrade. (line 88) * mysql_upgrade, tmpdir option: mysql-upgrade. (line 147) * mysql_upgrade, user option: mysql-upgrade. (line 152) * mysql_upgrade, verbose option: mysql-upgrade. (line 157) * mysql_upgrade, write-binlog option: mysql-upgrade. (line 161) * mysql_upgrade_info file, mysql_upgrade: mysql-upgrade. (line 88) * mysql_use_result(): mysql-use-result. (line 6) * mysql_waitpid <1>: mysql-waitpid. (line 6) * mysql_waitpid: programs-overview. (line 244) * mysql_waitpid, help option: mysql-waitpid. (line 27) * mysql_waitpid, verbose option: mysql-waitpid. (line 31) * mysql_waitpid, version option: mysql-waitpid. (line 36) * mysql_warning_count(): mysql-warning-count. (line 6) * mysql_zap <1>: mysql-zap. (line 6) * mysql_zap: programs-overview. (line 249) * mysqlaccess <1>: mysqlaccess. (line 6) * mysqlaccess: programs-overview. (line 190) * mysqlaccess, brief option: mysqlaccess. (line 71) * mysqlaccess, commit option: mysqlaccess. (line 75) * mysqlaccess, copy option: mysqlaccess. (line 82) * mysqlaccess, db option: mysqlaccess. (line 86) * mysqlaccess, debug option: mysqlaccess. (line 90) * mysqlaccess, help option: mysqlaccess. (line 67) * mysqlaccess, host option: mysqlaccess. (line 94) * mysqlaccess, howto option: mysqlaccess. (line 98) * mysqlaccess, old_server option: mysqlaccess. (line 103) * mysqlaccess, password option: mysqlaccess. (line 108) * mysqlaccess, plan option: mysqlaccess. (line 117) * mysqlaccess, preview option: mysqlaccess. (line 121) * mysqlaccess, relnotes option: mysqlaccess. (line 126) * mysqlaccess, rhost option: mysqlaccess. (line 130) * mysqlaccess, rollback option: mysqlaccess. (line 134) * mysqlaccess, spassword option: mysqlaccess. (line 138) * mysqlaccess, superuser option: mysqlaccess. (line 148) * mysqlaccess, table option: mysqlaccess. (line 152) * mysqlaccess, user option: mysqlaccess. (line 156) * mysqlaccess, version option: mysqlaccess. (line 160) * mysqladmin <1>: kill. (line 6) * mysqladmin <2>: flush. (line 6) * mysqladmin <3>: show-variables. (line 9) * mysqladmin <4>: show-status. (line 9) * mysqladmin <5>: drop-database. (line 54) * mysqladmin <6>: create-database. (line 42) * mysqladmin <7>: mysqladmin. (line 6) * mysqladmin: programs-overview. (line 129) * mysqladmin command options: mysqladmin. (line 213) * mysqladmin option, mysqld_multi: mysqld-multi. (line 123) * mysqladmin, bind-address option: mysqladmin. (line 303) * mysqladmin, character-sets-dir option: mysqladmin. (line 314) * mysqladmin, compress option: mysqladmin. (line 319) * mysqladmin, count option: mysqladmin. (line 324) * mysqladmin, debug option: mysqladmin. (line 329) * mysqladmin, debug-check option: mysqladmin. (line 335) * mysqladmin, debug-info option: mysqladmin. (line 340) * mysqladmin, default-character-set option: mysqladmin. (line 345) * mysqladmin, force option: mysqladmin. (line 350) * mysqladmin, help option: mysqladmin. (line 299) * mysqladmin, host option: mysqladmin. (line 355) * mysqladmin, no-beep option: mysqladmin. (line 359) * mysqladmin, password option: mysqladmin. (line 365) * mysqladmin, pipe option: mysqladmin. (line 377) * mysqladmin, port option: mysqladmin. (line 382) * mysqladmin, protocol option: mysqladmin. (line 386) * mysqladmin, relative option: mysqladmin. (line 393) * mysqladmin, silent option: mysqladmin. (line 399) * mysqladmin, sleep option: mysqladmin. (line 403) * mysqladmin, socket option: mysqladmin. (line 410) * mysqladmin, SSL options: mysqladmin. (line 415) * mysqladmin, user option: mysqladmin. (line 421) * mysqladmin, verbose option: mysqladmin. (line 425) * mysqladmin, version option: mysqladmin. (line 429) * mysqladmin, vertical option: mysqladmin. (line 433) * mysqladmin, wait option: mysqladmin. (line 438) * mysqlbinlog <1>: mysqlbinlog. (line 11) * mysqlbinlog: programs-overview. (line 195) * mysqlbinlog, base64-output option: mysqlbinlog. (line 178) * mysqlbinlog, bind-address option: mysqlbinlog. (line 226) * mysqlbinlog, character-sets-dir option: mysqlbinlog. (line 237) * mysqlbinlog, database option: mysqlbinlog. (line 242) * mysqlbinlog, debug option: mysqlbinlog. (line 332) * mysqlbinlog, debug-check option: mysqlbinlog. (line 338) * mysqlbinlog, debug-info option: mysqlbinlog. (line 343) * mysqlbinlog, disable-log-bin option: mysqlbinlog. (line 348) * mysqlbinlog, force-if-open option: mysqlbinlog. (line 362) * mysqlbinlog, force-read option: mysqlbinlog. (line 367) * mysqlbinlog, help option: mysqlbinlog. (line 174) * mysqlbinlog, hexdump option: mysqlbinlog. (line 374) * mysqlbinlog, host option: mysqlbinlog. (line 380) * mysqlbinlog, local-load option: mysqlbinlog. (line 384) * mysqlbinlog, offset option: mysqlbinlog. (line 394) * mysqlbinlog, password option: mysqlbinlog. (line 398) * mysqlbinlog, port option: mysqlbinlog. (line 410) * mysqlbinlog, position option: mysqlbinlog. (line 414) * mysqlbinlog, protocol option: mysqlbinlog. (line 419) * mysqlbinlog, read-from-remote-server option: mysqlbinlog. (line 426) * mysqlbinlog, result-file option: mysqlbinlog. (line 437) * mysqlbinlog, server-id option: mysqlbinlog. (line 441) * mysqlbinlog, server-id-bits option: mysqlbinlog. (line 446) * mysqlbinlog, set-charset option: mysqlbinlog. (line 460) * mysqlbinlog, short-form option: mysqlbinlog. (line 466) * mysqlbinlog, socket option: mysqlbinlog. (line 472) * mysqlbinlog, start-datetime option: mysqlbinlog. (line 477) * mysqlbinlog, start-position option: mysqlbinlog. (line 491) * mysqlbinlog, stop-datetime option: mysqlbinlog. (line 500) * mysqlbinlog, stop-position option: mysqlbinlog. (line 510) * mysqlbinlog, to-last-log option: mysqlbinlog. (line 519) * mysqlbinlog, user option: mysqlbinlog. (line 527) * mysqlbinlog, verbose option: mysqlbinlog. (line 531) * mysqlbinlog, version option: mysqlbinlog. (line 542) * mysqlbug: mysqlbug. (line 6) * MySqlBulkLoader class: connector-net-programming-bulk-loader. (line 6) * mysqlcheck <1>: mysqlcheck. (line 6) * mysqlcheck: programs-overview. (line 137) * mysqlcheck, all-databases option: mysqlcheck. (line 204) * mysqlcheck, all-in-1 option: mysqlcheck. (line 210) * mysqlcheck, analyze option: mysqlcheck. (line 216) * mysqlcheck, auto-repair option: mysqlcheck. (line 220) * mysqlcheck, bind-address option: mysqlcheck. (line 225) * mysqlcheck, character-sets-dir option: mysqlcheck. (line 236) * mysqlcheck, check option: mysqlcheck. (line 241) * mysqlcheck, check-only-changed option: mysqlcheck. (line 245) * mysqlcheck, check-upgrade option: mysqlcheck. (line 250) * mysqlcheck, compress option: mysqlcheck. (line 258) * mysqlcheck, databases option: mysqlcheck. (line 263) * mysqlcheck, debug option: mysqlcheck. (line 271) * mysqlcheck, debug-check option: mysqlcheck. (line 276) * mysqlcheck, debug-info option: mysqlcheck. (line 281) * mysqlcheck, default-character-set option: mysqlcheck. (line 286) * mysqlcheck, extended option: mysqlcheck. (line 291) * mysqlcheck, fast option: mysqlcheck. (line 300) * mysqlcheck, fix-db-names option: mysqlcheck. (line 304) * mysqlcheck, fix-table-names option: mysqlcheck. (line 310) * mysqlcheck, force option: mysqlcheck. (line 316) * mysqlcheck, help option: mysqlcheck. (line 200) * mysqlcheck, host option: mysqlcheck. (line 320) * mysqlcheck, medium-check option: mysqlcheck. (line 324) * mysqlcheck, optimize option: mysqlcheck. (line 330) * mysqlcheck, password option: mysqlcheck. (line 334) * mysqlcheck, pipe option: mysqlcheck. (line 346) * mysqlcheck, port option: mysqlcheck. (line 351) * mysqlcheck, protocol option: mysqlcheck. (line 355) * mysqlcheck, quick option: mysqlcheck. (line 362) * mysqlcheck, repair option: mysqlcheck. (line 371) * mysqlcheck, silent option: mysqlcheck. (line 376) * mysqlcheck, socket option: mysqlcheck. (line 380) * mysqlcheck, SSL options: mysqlcheck. (line 385) * mysqlcheck, tables option: mysqlcheck. (line 391) * mysqlcheck, use-frm option: mysqlcheck. (line 396) * mysqlcheck, user option: mysqlcheck. (line 402) * mysqlcheck, verbose option: mysqlcheck. (line 406) * mysqlcheck, version option: mysqlcheck. (line 411) * mysqlcheck, write-binlog option: mysqlcheck. (line 415) * MySqlClient namespace: connector-net-ref-mysqlclient. (line 17) * MySQLCommand class: connector-net-programming-mysqlcommand. (line 6) * MySqlCommand class: connector-net-tutorials-sql-command. (line 6) * mysqlcppconn-static.lib: connector-cpp-apps-windows-visual-studio. (line 6) * mysqlcppconn.dll: connector-cpp-apps-windows-visual-studio. (line 6) * mysqld: programs-overview. (line 38) * mysqld (MySQL Cluster): mysql-cluster-programs. (line 34) * mysqld option, mysqld_multi: mysqld-multi. (line 128) * mysqld option, mysqld_safe: mysqld-safe. (line 173) * mysqld options: server-parameters. (line 11) * mysqld options and variables, MySQL Cluster: mysql-cluster-options-variables. (line 13) * mysqld server, buffer sizes: server-parameters. (line 6) * mysqld, abort-slave-event-count option: replication-options-slave. (line 134) * mysqld, allow-suspicious-udfs option: server-options. (line 84) * mysqld, ansi option: server-options. (line 103) * mysqld, as MySQL Cluster process <1>: mysql-cluster-mysqld. (line 6) * mysqld, as MySQL Cluster process: mysql-cluster-program-options-mysqld. (line 6) * mysqld, basedir option: server-options. (line 116) * mysqld, big-tables option: server-options. (line 136) * mysqld, bind-address option: server-options. (line 158) * mysqld, binlog-do-db option: replication-options-binary-log. (line 198) * mysqld, binlog-format option: server-options. (line 203) * mysqld, binlog-ignore-db option: replication-options-binary-log. (line 323) * mysqld, binlog-row-event-max-size option: replication-options-binary-log. (line 20) * mysqld, bootstrap option: server-options. (line 280) * mysqld, character-set-client-handshake option: server-options. (line 315) * mysqld, character-set-filesystem option: server-options. (line 332) * mysqld, character-set-server option: server-options. (line 353) * mysqld, character-sets-dir option: server-options. (line 296) * mysqld, chroot option: server-options. (line 374) * mysqld, collation-server option: server-options. (line 394) * mysqld, command options: server-options. (line 6) * mysqld, console option: server-options. (line 413) * mysqld, core-file option: server-options. (line 429) * mysqld, datadir option: server-options. (line 458) * mysqld, debug option: server-options. (line 477) * mysqld, debug-sync-timeout option: server-options. (line 512) * mysqld, default-character-set option: server-options. (line 540) * mysqld, default-collation option: server-options. (line 559) * mysqld, default-storage-engine option: server-options. (line 576) * mysqld, default-table-type option: server-options. (line 596) * mysqld, default-time-zone option: server-options. (line 613) * mysqld, delay-key-write option <1>: myisam-start. (line 42) * mysqld, delay-key-write option: server-options. (line 629) * mysqld, des-key-file option: server-options. (line 662) * mysqld, disconnect-slave-event-count option: replication-options-slave. (line 161) * mysqld, enable-named-pipe option: server-options. (line 677) * mysqld, enable-pstack option: server-options. (line 694) * mysqld, event-scheduler option: server-options. (line 730) * mysqld, exit-info option: server-options. (line 756) * mysqld, external-locking option: server-options. (line 773) * mysqld, flush option: server-options. (line 798) * mysqld, gdb option: server-options. (line 819) * mysqld, general-log option: server-options. (line 835) * mysqld, help option: server-options. (line 72) * mysqld, ignore-builtin-innodb option: innodb-parameters. (line 135) * mysqld, init-file option: server-options. (line 857) * mysqld, innodb option: innodb-parameters. (line 172) * mysqld, innodb-status-file option: innodb-parameters. (line 186) * mysqld, install option: server-options. (line 885) * mysqld, install-manual option: server-options. (line 902) * mysqld, language option: server-options. (line 920) * mysqld, large-pages option: server-options. (line 943) * mysqld, log option: server-options. (line 973) * mysqld, log-bin option: replication-options-binary-log. (line 51) * mysqld, log-bin-index option: replication-options-binary-log. (line 81) * mysqld, log-bin-trust-function-creators option: replication-options-binary-log. (line 97) * mysqld, log-bin-use-v1-row-events option: replication-options-binary-log. (line 125) * mysqld, log-error option: server-options. (line 1007) * mysqld, log-isam option: server-options. (line 1028) * mysqld, log-long-format option: server-options. (line 1043) * mysqld, log-output option: server-options. (line 1062) * mysqld, log-queries-not-using-indexes option: server-options. (line 1105) * mysqld, log-short-format option <1>: replication-options-binary-log. (line 175) * mysqld, log-short-format option: server-options. (line 1128) * mysqld, log-slave-updates option: replication-options-slave. (line 176) * mysqld, log-slow-admin-statements option: server-options. (line 1143) * mysqld, log-slow-queries option: server-options. (line 1162) * mysqld, log-slow-slave-statements option: replication-options-slave. (line 226) * mysqld, log-tc option: server-options. (line 1197) * mysqld, log-tc-size option: server-options. (line 1216) * mysqld, log-warnings option <1>: replication-options-slave. (line 245) * mysqld, log-warnings option: server-options. (line 1239) * mysqld, low-priority-updates option: server-options. (line 1287) * mysqld, master-connect-retry option: replication-options-slave. (line 286) * mysqld, master-host option: replication-options-slave. (line 345) * mysqld, master-info-file option: replication-options-slave. (line 364) * mysqld, master-password option: replication-options-slave. (line 382) * mysqld, master-port option: replication-options-slave. (line 402) * mysqld, master-retry-count option: replication-options-slave. (line 422) * mysqld, master-ssl option: replication-options-slave. (line 453) * mysqld, master-ssl-ca option: replication-options-slave. (line 453) * mysqld, master-ssl-capath option: replication-options-slave. (line 453) * mysqld, master-ssl-cert option: replication-options-slave. (line 453) * mysqld, master-ssl-cipher option: replication-options-slave. (line 453) * mysqld, master-ssl-key option: replication-options-slave. (line 453) * mysqld, master-user option: replication-options-slave. (line 468) * mysqld, max-binlog-dump-events option: replication-options-binary-log. (line 401) * mysqld, max-relay-log-size option: replication-options-slave. (line 490) * mysqld, memlock option: server-options. (line 1346) * mysqld, min-examined-row-limit option: server-options. (line 1313) * mysqld, myisam-block-size option: server-options. (line 1395) * mysqld, myisam-recover option <1>: myisam-start. (line 38) * mysqld, myisam-recover option: server-options. (line 1412) * mysqld, MySQL server <1>: mysqld-server. (line 20) * mysqld, MySQL server: mysqld. (line 6) * mysqld, ndb-batch-size option: mysql-cluster-program-options-mysqld. (line 23) * mysqld, ndb-blob-read-batch-bytes option: mysql-cluster-program-options-mysqld. (line 111) * mysqld, ndb-blob-write-batch-bytes option: mysql-cluster-program-options-mysqld. (line 154) * mysqld, ndb-cluster-connection-pool option: mysql-cluster-program-options-mysqld. (line 45) * mysqld, ndb-connectstring option: mysql-cluster-program-options-mysqld. (line 198) * mysqld, ndb-log-apply-status: mysql-cluster-program-options-mysqld. (line 308) * mysqld, ndb-log-empty-epochs: mysql-cluster-program-options-mysqld. (line 461) * mysqld, ndb-log-orig: mysql-cluster-program-options-mysqld. (line 348) * mysqld, ndb-log-transaction-id: mysql-cluster-program-options-mysqld. (line 374) * mysqld, ndb-nodeid: mysql-cluster-program-options-mysqld. (line 408) * mysqld, ndbcluster option: mysql-cluster-program-options-mysqld. (line 288) * mysqld, old-alter-table option: server-options. (line 1465) * mysqld, old-style-user-limits option: server-options. (line 1490) * mysqld, one-thread option: server-options. (line 1507) * mysqld, open-files-limit option: server-options. (line 1522) * mysqld, partition option: server-options. (line 1555) * mysqld, pid-file option: server-options. (line 1571) * mysqld, plugin option prefix: server-options. (line 1593) * mysqld, plugin-load option: server-options. (line 1618) * mysqld, port option: server-options. (line 1675) * mysqld, port-open-timeout option: server-options. (line 1698) * mysqld, read-only option: replication-options-slave. (line 512) * mysqld, relay-log option: replication-options-slave. (line 534) * mysqld, relay-log-index option: replication-options-slave. (line 583) * mysqld, relay-log-info-file option: replication-options-slave. (line 618) * mysqld, relay-log-purge option: replication-options-slave. (line 636) * mysqld, relay-log-space-limit option: replication-options-slave. (line 657) * mysqld, remove option: server-options. (line 1718) * mysqld, replicate-do-db option: replication-options-slave. (line 702) * mysqld, replicate-do-table option: replication-options-slave. (line 888) * mysqld, replicate-ignore-db option: replication-options-slave. (line 818) * mysqld, replicate-ignore-table option: replication-options-slave. (line 910) * mysqld, replicate-rewrite-db option: replication-options-slave. (line 933) * mysqld, replicate-same-server-id option: replication-options-slave. (line 982) * mysqld, replicate-wild-do-table option: replication-options-slave. (line 1006) * mysqld, replicate-wild-ignore-table option: replication-options-slave. (line 1053) * mysqld, report-host option: replication-options-slave. (line 1079) * mysqld, report-password option: replication-options-slave. (line 1104) * mysqld, report-port option: replication-options-slave. (line 1129) * mysqld, report-user option: replication-options-slave. (line 1153) * mysqld, role in MySQL Cluster: mysql-cluster-basics. (line 6) * mysqld, safe-mode option: server-options. (line 1729) * mysqld, safe-show-database option: server-options. (line 1740) * mysqld, safe-user-create option: server-options. (line 1762) * mysqld, secure-auth option: server-options. (line 1787) * mysqld, secure-file-priv option: server-options. (line 1815) * mysqld, server-id option: replication-options. (line 21) * mysqld, server-id-bits option: mysql-cluster-program-options-mysqld. (line 501) * mysqld, shared-memory option: server-options. (line 1838) * mysqld, shared-memory-base-name option: server-options. (line 1851) * mysqld, show-slave-auth-info option: replication-options-slave. (line 1178) * mysqld, skip-concurrent-insert option: server-options. (line 1865) * mysqld, skip-event-scheduler option: server-options. (line 1871) * mysqld, skip-grant-tables option: server-options. (line 1885) * mysqld, skip-host-cache option: server-options. (line 1909) * mysqld, skip-innodb option <1>: innodb-parameters. (line 207) * mysqld, skip-innodb option: server-options. (line 1915) * mysqld, skip-merge option: server-options. (line 1922) * mysqld, skip-name-resolve option: server-options. (line 1927) * mysqld, skip-ndbcluster option: mysql-cluster-program-options-mysqld. (line 549) * mysqld, skip-networking option: server-options. (line 1934) * mysqld, skip-partition option: server-options. (line 1942) * mysqld, skip-safemalloc option: server-options. (line 2009) * mysqld, skip-show-database option: server-options. (line 2023) * mysqld, skip-slave-start option: replication-options-slave. (line 1195) * mysqld, skip-stack-trace option: server-options. (line 2039) * mysqld, skip-symbolic-links option: server-options. (line 1985) * mysqld, skip-thread-priority option: server-options. (line 2052) * mysqld, slave-load-tmpdir option: replication-options-slave. (line 1231) * mysqld, slave-max-allowed-packet: replication-options-slave. (line 311) * mysqld, slave-net-timeout option: replication-options-slave. (line 1268) * mysqld, slave-skip-errors option: replication-options-slave. (line 1295) * mysqld, slave_compressed_protocol option: replication-options-slave. (line 1211) * mysqld, slow-query-log option: server-options. (line 2073) * mysqld, socket option: server-options. (line 2096) * mysqld, sporadic-binlog-dump-fail option: replication-options-binary-log. (line 416) * mysqld, sql-mode option: server-options. (line 2122) * mysqld, SSL options: server-options. (line 1967) * mysqld, standalone option: server-options. (line 1973) * mysqld, starting: changing-mysql-user. (line 6) * mysqld, symbolic-links option: server-options. (line 1985) * mysqld, sysdate-is-now option: server-options. (line 2170) * mysqld, tc-heuristic-recover option: server-options. (line 2193) * mysqld, temp-pool option: server-options. (line 2209) * mysqld, tmpdir option: server-options. (line 2252) * mysqld, transaction-isolation option: server-options. (line 2229) * mysqld, user option: server-options. (line 2285) * mysqld, verbose option: server-options. (line 2320) * mysqld, version option: server-options. (line 2324) * mysqld-safe-compatible option, mysqlmanager: instance-manager-command-options. (line 153) * mysqld-version option, mysqld_safe: mysqld-safe. (line 182) * mysqld_multi <1>: mysqld-multi. (line 6) * mysqld_multi: programs-overview. (line 58) * mysqld_multi, config-file option: mysqld-multi. (line 100) * mysqld_multi, defaults-extra-file option: mysqld-multi. (line 68) * mysqld_multi, defaults-file option: mysqld-multi. (line 66) * mysqld_multi, example option: mysqld-multi. (line 114) * mysqld_multi, help option: mysqld-multi. (line 96) * mysqld_multi, log option: mysqld-multi. (line 118) * mysqld_multi, mysqladmin option: mysqld-multi. (line 123) * mysqld_multi, mysqld option: mysqld-multi. (line 128) * mysqld_multi, no-defaults option: mysqld-multi. (line 64) * mysqld_multi, no-log option: mysqld-multi. (line 144) * mysqld_multi, password option: mysqld-multi. (line 149) * mysqld_multi, silent option: mysqld-multi. (line 155) * mysqld_multi, tcp-ip option: mysqld-multi. (line 159) * mysqld_multi, user option: mysqld-multi. (line 167) * mysqld_multi, verbose option: mysqld-multi. (line 172) * mysqld_multi, version option: mysqld-multi. (line 176) * mysqld_safe <1>: mysqld-safe. (line 6) * mysqld_safe: programs-overview. (line 45) * mysqld_safe, autoclose option: mysqld-safe. (line 125) * mysqld_safe, basedir option: mysqld-safe. (line 137) * mysqld_safe, core-file-size option: mysqld-safe. (line 141) * mysqld_safe, datadir option: mysqld-safe. (line 146) * mysqld_safe, defaults-extra-file option: mysqld-safe. (line 150) * mysqld_safe, defaults-file option: mysqld-safe. (line 157) * mysqld_safe, help option: mysqld-safe. (line 121) * mysqld_safe, ledir option: mysqld-safe. (line 163) * mysqld_safe, log-error option: mysqld-safe. (line 169) * mysqld_safe, mysqld option: mysqld-safe. (line 173) * mysqld_safe, mysqld-version option: mysqld-safe. (line 182) * mysqld_safe, nice option: mysqld-safe. (line 193) * mysqld_safe, no-defaults option: mysqld-safe. (line 198) * mysqld_safe, open-files-limit option: mysqld-safe. (line 203) * mysqld_safe, pid-file option: mysqld-safe. (line 210) * mysqld_safe, port option: mysqld-safe. (line 214) * mysqld_safe, skip-kill-mysqld option: mysqld-safe. (line 220) * mysqld_safe, skip-syslog option: mysqld-safe. (line 230) * mysqld_safe, socket option: mysqld-safe. (line 225) * mysqld_safe, syslog option: mysqld-safe. (line 230) * mysqld_safe, syslog-tag option: mysqld-safe. (line 240) * mysqld_safe, timezone option: mysqld-safe. (line 249) * mysqld_safe, user option: mysqld-safe. (line 255) * mysqldump <1>: mysqldump. (line 6) * mysqldump <2>: programs-overview. (line 142) * mysqldump: copying-databases. (line 45) * mysqldump, add-drop-database option: mysqldump. (line 354) * mysqldump, add-drop-table option: mysqldump. (line 363) * mysqldump, add-drop-trigger option: mysqldump. (line 368) * mysqldump, add-locks option: mysqldump. (line 380) * mysqldump, all-databases option: mysqldump. (line 387) * mysqldump, all-tablespaces option: mysqldump. (line 393) * mysqldump, allow-keywords option: mysqldump. (line 403) * mysqldump, bind-address option: mysqldump. (line 408) * mysqldump, character-sets-dir option: mysqldump. (line 419) * mysqldump, comments option: mysqldump. (line 424) * mysqldump, compact option: mysqldump. (line 431) * mysqldump, compatible option: mysqldump. (line 446) * mysqldump, complete-insert option: mysqldump. (line 466) * mysqldump, compress option: mysqldump. (line 471) * mysqldump, create-options option: mysqldump. (line 476) * mysqldump, databases option: mysqldump. (line 481) * mysqldump, debug option: mysqldump. (line 490) * mysqldump, debug-check option: mysqldump. (line 496) * mysqldump, debug-info option: mysqldump. (line 501) * mysqldump, default-character-set option: mysqldump. (line 506) * mysqldump, delayed-insert option: mysqldump. (line 517) * mysqldump, delete-master-logs option: mysqldump. (line 522) * mysqldump, disable-keys option: mysqldump. (line 529) * mysqldump, dump-date option: mysqldump. (line 539) * mysqldump, events option: mysqldump. (line 553) * mysqldump, extended-insert option: mysqldump. (line 558) * mysqldump, fields-enclosed-by option <1>: mysqlimport. (line 187) * mysqldump, fields-enclosed-by option: mysqldump. (line 566) * mysqldump, fields-escaped-by option <1>: mysqlimport. (line 191) * mysqldump, fields-escaped-by option: mysqldump. (line 570) * mysqldump, fields-optionally-enclosed-by option <1>: mysqlimport. (line 189) * mysqldump, fields-optionally-enclosed-by option: mysqldump. (line 568) * mysqldump, fields-terminated-by option <1>: mysqlimport. (line 185) * mysqldump, fields-terminated-by option: mysqldump. (line 564) * mysqldump, first-slave option: mysqldump. (line 576) * mysqldump, flush-logs option: mysqldump. (line 581) * mysqldump, flush-privileges option: mysqldump. (line 593) * mysqldump, force option: mysqldump. (line 601) * mysqldump, help option: mysqldump. (line 350) * mysqldump, hex-blob option: mysqldump. (line 619) * mysqldump, host option: mysqldump. (line 614) * mysqldump, ignore-table option: mysqldump. (line 626) * mysqldump, insert-ignore option: mysqldump. (line 633) * mysqldump, lines-terminated-by option <1>: mysqlimport. (line 215) * mysqldump, lines-terminated-by option: mysqldump. (line 638) * mysqldump, lock-all-tables option: mysqldump. (line 644) * mysqldump, lock-tables option: mysqldump. (line 651) * mysqldump, log-error option: mysqldump. (line 665) * mysqldump, master-data option: mysqldump. (line 670) * mysqldump, no-autocommit option: mysqldump. (line 746) * mysqldump, no-create-db option: mysqldump. (line 752) * mysqldump, no-create-info option: mysqldump. (line 758) * mysqldump, no-data option: mysqldump. (line 770) * mysqldump, no-set-names option: mysqldump. (line 778) * mysqldump, no-tablespaces option: mysqldump. (line 782) * mysqldump, opt option: mysqldump. (line 791) * mysqldump, order-by-primary option: mysqldump. (line 805) * mysqldump, password option: mysqldump. (line 812) * mysqldump, pipe option: mysqldump. (line 824) * mysqldump, port option: mysqldump. (line 829) * mysqldump, problems <1>: view-restrictions. (line 111) * mysqldump, problems: mysqldump. (line 1196) * mysqldump, protocol option: mysqldump. (line 833) * mysqldump, quick option: mysqldump. (line 840) * mysqldump, quote-names option: mysqldump. (line 847) * mysqldump, replace option: mysqldump. (line 856) * mysqldump, result-file option: mysqldump. (line 862) * mysqldump, routines option: mysqldump. (line 870) * mysqldump, set-charset option: mysqldump. (line 900) * mysqldump, single-transaction option: mysqldump. (line 906) * mysqldump, skip-comments option: mysqldump. (line 945) * mysqldump, skip-opt option: mysqldump. (line 949) * mysqldump, socket option: mysqldump. (line 953) * mysqldump, SSL options: mysqldump. (line 958) * mysqldump, tab option: mysqldump. (line 964) * mysqldump, tables option: mysqldump. (line 993) * mysqldump, triggers option: mysqldump. (line 999) * mysqldump, tz-utc option: mysqldump. (line 1004) * mysqldump, user option: mysqldump. (line 1018) * mysqldump, using for backups: using-mysqldump. (line 14) * mysqldump, verbose option: mysqldump. (line 1022) * mysqldump, version option: mysqldump. (line 1026) * mysqldump, views <1>: view-restrictions. (line 111) * mysqldump, views: mysqldump. (line 1196) * mysqldump, where option: mysqldump. (line 1030) * mysqldump, workarounds <1>: view-restrictions. (line 111) * mysqldump, workarounds: mysqldump. (line 1196) * mysqldump, xml option: mysqldump. (line 1042) * mysqldumpslow <1>: mysqldumpslow. (line 6) * mysqldumpslow: programs-overview. (line 201) * mysqldumpslow, debug option: mysqldumpslow. (line 53) * mysqldumpslow, help option: mysqldumpslow. (line 45) * mysqldumpslow, verbose option: mysqldumpslow. (line 103) * mysqlhotcopy <1>: mysqlhotcopy. (line 6) * mysqlhotcopy: programs-overview. (line 206) * mysqlhotcopy, addtodest option: mysqlhotcopy. (line 85) * mysqlhotcopy, allowold option: mysqlhotcopy. (line 90) * mysqlhotcopy, checkpoint option: mysqlhotcopy. (line 95) * mysqlhotcopy, chroot option: mysqlhotcopy. (line 100) * mysqlhotcopy, debug option: mysqlhotcopy. (line 106) * mysqlhotcopy, dryrun option: mysqlhotcopy. (line 110) * mysqlhotcopy, flushlog option: mysqlhotcopy. (line 114) * mysqlhotcopy, help option: mysqlhotcopy. (line 81) * mysqlhotcopy, host option: mysqlhotcopy. (line 118) * mysqlhotcopy, keepold option: mysqlhotcopy. (line 124) * mysqlhotcopy, method option: mysqlhotcopy. (line 128) * mysqlhotcopy, noindices option: mysqlhotcopy. (line 132) * mysqlhotcopy, password option: mysqlhotcopy. (line 139) * mysqlhotcopy, port option: mysqlhotcopy. (line 149) * mysqlhotcopy, quiet option: mysqlhotcopy. (line 153) * mysqlhotcopy, record_log_pos option: mysqlhotcopy. (line 157) * mysqlhotcopy, regexp option: mysqlhotcopy. (line 162) * mysqlhotcopy, resetmaster option: mysqlhotcopy. (line 167) * mysqlhotcopy, resetslave option: mysqlhotcopy. (line 171) * mysqlhotcopy, socket option: mysqlhotcopy. (line 175) * mysqlhotcopy, suffix option: mysqlhotcopy. (line 179) * mysqlhotcopy, tmpdir option: mysqlhotcopy. (line 183) * mysqlhotcopy, user option: mysqlhotcopy. (line 187) * mysqlimport <1>: load-data. (line 33) * mysqlimport <2>: mysqlimport. (line 6) * mysqlimport <3>: programs-overview. (line 147) * mysqlimport: copying-databases. (line 45) * mysqlimport, bind-address option: mysqlimport. (line 130) * mysqlimport, character-sets-dir option: mysqlimport. (line 141) * mysqlimport, columns option: mysqlimport. (line 146) * mysqlimport, compress option: mysqlimport. (line 152) * mysqlimport, debug option: mysqlimport. (line 157) * mysqlimport, debug-check option: mysqlimport. (line 162) * mysqlimport, debug-info option: mysqlimport. (line 167) * mysqlimport, default-character-set option: mysqlimport. (line 172) * mysqlimport, delete option: mysqlimport. (line 181) * mysqlimport, force option: mysqlimport. (line 196) * mysqlimport, help option: mysqlimport. (line 126) * mysqlimport, host option: mysqlimport. (line 202) * mysqlimport, ignore option: mysqlimport. (line 207) * mysqlimport, ignore-lines option: mysqlimport. (line 211) * mysqlimport, local option: mysqlimport. (line 224) * mysqlimport, lock-tables option: mysqlimport. (line 228) * mysqlimport, low-priority option: mysqlimport. (line 233) * mysqlimport, password option: mysqlimport. (line 239) * mysqlimport, pipe option: mysqlimport. (line 251) * mysqlimport, port option: mysqlimport. (line 256) * mysqlimport, protocol option: mysqlimport. (line 260) * mysqlimport, replace option: mysqlimport. (line 267) * mysqlimport, silent option: mysqlimport. (line 277) * mysqlimport, socket option: mysqlimport. (line 281) * mysqlimport, SSL options: mysqlimport. (line 286) * mysqlimport, use-threads option: mysqlimport. (line 296) * mysqlimport, user option: mysqlimport. (line 292) * mysqlimport, verbose option: mysqlimport. (line 301) * mysqlimport, version option: mysqlimport. (line 305) * mysqlmanager <1>: instance-manager. (line 16) * mysqlmanager: programs-overview. (line 211) * mysqlmanager, add-user option: instance-manager-command-options. (line 27) * mysqlmanager, angel-pid-file option: instance-manager-command-options. (line 32) * mysqlmanager, bind-address option: instance-manager-command-options. (line 46) * mysqlmanager, check-password-file option: instance-manager-command-options. (line 50) * mysqlmanager, clean-password-file option: instance-manager-command-options. (line 55) * mysqlmanager, debug option: instance-manager-command-options. (line 60) * mysqlmanager, default-mysqld-path option: instance-manager-command-options. (line 65) * mysqlmanager, defaults-file option: instance-manager-command-options. (line 74) * mysqlmanager, drop-user option: instance-manager-command-options. (line 86) * mysqlmanager, edit-user option: instance-manager-command-options. (line 91) * mysqlmanager, help option: instance-manager-command-options. (line 23) * mysqlmanager, install option: instance-manager-command-options. (line 97) * mysqlmanager, list-users option: instance-manager-command-options. (line 102) * mysqlmanager, log option: instance-manager-command-options. (line 107) * mysqlmanager, monitoring-interval option: instance-manager-command-options. (line 125) * mysqlmanager, mysqld-safe-compatible option: instance-manager-command-options. (line 153) * mysqlmanager, password option: instance-manager-command-options. (line 159) * mysqlmanager, password-file option: instance-manager-command-options. (line 167) * mysqlmanager, pid-file option: instance-manager-command-options. (line 175) * mysqlmanager, port option: instance-manager-command-options. (line 182) * mysqlmanager, print-defaults option: instance-manager-command-options. (line 187) * mysqlmanager, print-password-line option: instance-manager-command-options. (line 192) * mysqlmanager, remove option: instance-manager-command-options. (line 200) * mysqlmanager, run-as-service option: instance-manager-command-options. (line 206) * mysqlmanager, socket option: instance-manager-command-options. (line 212) * mysqlmanager, standalone option: instance-manager-command-options. (line 218) * mysqlmanager, user option: instance-manager-command-options. (line 224) * mysqlmanager, username option: instance-manager-command-options. (line 235) * mysqlmanager, version option: instance-manager-command-options. (line 240) * mysqlmanager, wait-timeout option: instance-manager-command-options. (line 244) * mysqlshow <1>: mysqlshow. (line 6) * mysqlshow: programs-overview. (line 152) * mysqlshow, bind-address option: mysqlshow. (line 114) * mysqlshow, character-sets-dir option: mysqlshow. (line 125) * mysqlshow, compress option: mysqlshow. (line 130) * mysqlshow, count option: mysqlshow. (line 135) * mysqlshow, debug option: mysqlshow. (line 140) * mysqlshow, debug-check option: mysqlshow. (line 145) * mysqlshow, debug-info option: mysqlshow. (line 150) * mysqlshow, default-character-set option: mysqlshow. (line 155) * mysqlshow, help option: mysqlshow. (line 110) * mysqlshow, host option: mysqlshow. (line 160) * mysqlshow, keys option: mysqlshow. (line 164) * mysqlshow, password option: mysqlshow. (line 168) * mysqlshow, pipe option: mysqlshow. (line 180) * mysqlshow, port option: mysqlshow. (line 185) * mysqlshow, protocol option: mysqlshow. (line 189) * mysqlshow, show-table-type option: mysqlshow. (line 196) * mysqlshow, socket option: mysqlshow. (line 201) * mysqlshow, SSL options: mysqlshow. (line 206) * mysqlshow, status option: mysqlshow. (line 212) * mysqlshow, user option: mysqlshow. (line 216) * mysqlshow, verbose option: mysqlshow. (line 220) * mysqlshow, version option: mysqlshow. (line 226) * mysqlslap <1>: mysqlslap. (line 6) * mysqlslap: programs-overview. (line 157) * mysqlslap, auto-generate-sql option: mysqlslap. (line 213) * mysqlslap, auto-generate-sql-add-autoincrement option: mysqlslap. (line 218) * mysqlslap, auto-generate-sql-execute-number option: mysqlslap. (line 223) * mysqlslap, auto-generate-sql-guid-primary option: mysqlslap. (line 228) * mysqlslap, auto-generate-sql-load-type option: mysqlslap. (line 233) * mysqlslap, auto-generate-sql-secondary-indexes option: mysqlslap. (line 241) * mysqlslap, auto-generate-sql-unique-query-number option: mysqlslap. (line 247) * mysqlslap, auto-generate-sql-unique-write-number option: mysqlslap. (line 255) * mysqlslap, auto-generate-sql-write-number option: mysqlslap. (line 261) * mysqlslap, commit option: mysqlslap. (line 266) * mysqlslap, compress option: mysqlslap. (line 271) * mysqlslap, concurrency option: mysqlslap. (line 276) * mysqlslap, create option: mysqlslap. (line 281) * mysqlslap, create-schema option: mysqlslap. (line 286) * mysqlslap, csv option: mysqlslap. (line 297) * mysqlslap, debug option: mysqlslap. (line 303) * mysqlslap, debug-check option: mysqlslap. (line 309) * mysqlslap, debug-info option: mysqlslap. (line 314) * mysqlslap, delimiter option: mysqlslap. (line 319) * mysqlslap, detach option: mysqlslap. (line 324) * mysqlslap, engine option: mysqlslap. (line 330) * mysqlslap, help option: mysqlslap. (line 209) * mysqlslap, host option: mysqlslap. (line 334) * mysqlslap, iterations option: mysqlslap. (line 338) * mysqlslap, lock-directory option: mysqlslap. (line 342) * mysqlslap, no-drop option: mysqlslap. (line 347) * mysqlslap, number-char-cols option: mysqlslap. (line 352) * mysqlslap, number-int-cols option: mysqlslap. (line 357) * mysqlslap, number-of-queries option: mysqlslap. (line 362) * mysqlslap, only-print option: mysqlslap. (line 375) * mysqlslap, password option: mysqlslap. (line 381) * mysqlslap, pipe option: mysqlslap. (line 393) * mysqlslap, port option: mysqlslap. (line 398) * mysqlslap, post-query option: mysqlslap. (line 402) * mysqlslap, post-system option: mysqlslap. (line 414) * mysqlslap, pre-query option: mysqlslap. (line 420) * mysqlslap, pre-system option: mysqlslap. (line 426) * mysqlslap, preserve-schema option: mysqlslap. (line 432) * mysqlslap, protocol option: mysqlslap. (line 439) * mysqlslap, query option: mysqlslap. (line 446) * mysqlslap, shared-memory-base-name option: mysqlslap. (line 408) * mysqlslap, silent option: mysqlslap. (line 451) * mysqlslap, slave option: mysqlslap. (line 455) * mysqlslap, socket option: mysqlslap. (line 462) * mysqlslap, SSL options: mysqlslap. (line 467) * mysqlslap, use-threads option: mysqlslap. (line 473) * mysqlslap, user option: mysqlslap. (line 480) * mysqlslap, verbose option: mysqlslap. (line 484) * mysqlslap, version option: mysqlslap. (line 490) * mysqltest, MySQL Test Suite: mysql-test-suite. (line 6) * NAME_CONST() <1>: stored-programs-logging. (line 345) * NAME_CONST(): miscellaneous-functions. (line 181) * name_file option, comp_err: comp-err. (line 52) * named pipes <1>: windows-testing. (line 6) * named pipes: windows-select-server. (line 45) * named-commands option, mysql: mysql-command-options. (line 308) * named_pipe system variable: server-system-variables. (line 3655) * names: identifiers. (line 13) * names, case sensitivity: identifier-case-sensitivity. (line 6) * names, variables: user-variables. (line 6) * naming, releases of MySQL: choosing-version. (line 56) * NATIONAL CHAR data type: string-type-overview. (line 89) * NATIONAL VARCHAR data type: string-type-overview. (line 121) * native backup and restore, backup identifiers: mysql-cluster-backup-using-management-client. (line 105) * native functions, adding: adding-native-function. (line 6) * native thread support: supported-os. (line 6) * NATURAL LEFT JOIN: join. (line 6) * NATURAL LEFT OUTER JOIN: join. (line 6) * NATURAL RIGHT JOIN: join. (line 6) * NATURAL RIGHT OUTER JOIN: join. (line 6) * NCHAR data type: string-type-overview. (line 89) * NDB: faqs-mysql-cluster. (line 6) * NDB API _slave status variables, and MySQL Cluster Replication: mysql-cluster-replication. (line 63) * NDB API counters (MySQL Cluster): mysql-cluster-ndb-api-statistics. (line 6) * NDB API counters (MySQL Cluster), scope: mysql-cluster-ndb-api-statistics. (line 234) * NDB API counters (MySQL Cluster), status variables associated with: mysql-cluster-ndb-api-statistics. (line 397) * NDB API counters (MySQL Cluster), types: mysql-cluster-ndb-api-statistics. (line 255) * NDB API, and distributed grant tables: mysql-cluster-privilege-distribution. (line 194) * NDB API, and distributed privileges: mysql-cluster-privilege-distribution. (line 194) * ndb option, perror: perror. (line 44) * NDB statistics variables (MySQL Cluster): mysql-cluster-ndb-api-statistics. (line 6) * NDB statistics variables (MySQL Cluster), scope: mysql-cluster-ndb-api-statistics. (line 234) * NDB statistics variables (MySQL Cluster), types: mysql-cluster-ndb-api-statistics. (line 255) * NDB statistics variables, and NDB API counters: mysql-cluster-ndb-api-statistics. (line 397) * NDB storage engine: mysql-cluster. (line 16) * NDB storage engine, FAQ: faqs-mysql-cluster. (line 6) * NDB tables, and MySQL root user: mysql-cluster-security-mysql-privileges. (line 51) * NDB utilities, security issues: mysql-cluster-security-mysql-security-procedures. (line 76) * NDB$MAX(): mysql-cluster-replication-conflict-resolution. (line 272) * NDB$MAX_DELETE_WIN(): mysql-cluster-replication-conflict-resolution. (line 291) * NDB$OLD: mysql-cluster-replication-conflict-resolution. (line 251) * NDB, creating large tables using: create-table. (line 864) * NDB, MAX_ROWS: create-table. (line 864) * ndb-batch-size option, mysqld: mysql-cluster-program-options-mysqld. (line 23) * ndb-blob-read-batch-bytes option, mysqld: mysql-cluster-program-options-mysqld. (line 111) * ndb-blob-write-batch-bytes option, mysqld: mysql-cluster-program-options-mysqld. (line 154) * ndb-cluster-connection-pool option, mysqld: mysql-cluster-program-options-mysqld. (line 45) * ndb-connectstring option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 114) * ndb-connectstring option, mysqld: mysql-cluster-program-options-mysqld. (line 198) * ndb-connectstring option, ndb_config: mysql-cluster-programs-ndb-config. (line 143) * ndb-deferred-constraints option (MySQL Cluster): mysql-cluster-program-options-mysqld. (line 214) * ndb-distribution option (MySQL Cluster): mysql-cluster-program-options-mysqld. (line 246) * ndb-log-apply-status option, mysqld: mysql-cluster-program-options-mysqld. (line 308) * ndb-log-empty-epochs option, mysqld: mysql-cluster-program-options-mysqld. (line 461) * ndb-log-orig option, mysqld: mysql-cluster-program-options-mysqld. (line 348) * ndb-log-transaction-id option, mysqld: mysql-cluster-program-options-mysqld. (line 374) * ndb-log-update-as-write (mysqld option): mysql-cluster-replication-conflict-resolution. (line 75) * ndb-mgmd-host option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 175) * ndb-mgmd-host option (MySQL Cluster): mysql-cluster-program-options-mysqld. (line 270) * ndb-nodegroup-map option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 620) * ndb-nodeid option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 193) * ndb-nodeid option, mysqld: mysql-cluster-program-options-mysqld. (line 408) * ndb-optimized-node-selection option (MySQL Cluster): mysql-cluster-program-options-common. (line 209) * ndb-shm option (MySQL Cluster programs; OBSOLETE): mysql-cluster-program-options-common. (line 239) * ndb_apply_status table (MySQL Cluster replication) <1>: mysql-cluster-replication-failover. (line 10) * ndb_apply_status table (MySQL Cluster replication): mysql-cluster-replication-schema. (line 131) * ndb_binlog_index table (MySQL Cluster replication) <1>: mysql-cluster-replication-failover. (line 18) * ndb_binlog_index table (MySQL Cluster replication): mysql-cluster-replication-schema. (line 6) * ndb_blob_tool <1>: mysql-cluster-programs-ndb-blob-tool. (line 6) * ndb_blob_tool: mysql-cluster-programs. (line 34) * ndb_blob_tool, check-orphans option: mysql-cluster-programs-ndb-blob-tool. (line 65) * ndb_blob_tool, database option: mysql-cluster-programs-ndb-blob-tool. (line 79) * ndb_blob_tool, delete-orphans option: mysql-cluster-programs-ndb-blob-tool. (line 94) * ndb_blob_tool, dump-file option: mysql-cluster-programs-ndb-blob-tool. (line 108) * ndb_blob_tool, verbose option: mysql-cluster-programs-ndb-blob-tool. (line 125) * ndb_config <1>: mysql-cluster-programs-ndb-config. (line 6) * ndb_config: mysql-cluster-programs. (line 34) * ndb_config, config-file option: mysql-cluster-programs-ndb-config. (line 165) * ndb_config, config_from_node option: mysql-cluster-programs-ndb-config. (line 107) * ndb_config, configinfo option: mysql-cluster-programs-ndb-config. (line 382) * ndb_config, connections option: mysql-cluster-programs-ndb-config. (line 288) * ndb_config, fields option: mysql-cluster-programs-ndb-config. (line 342) * ndb_config, host option: mysql-cluster-programs-ndb-config. (line 225) * ndb_config, id option: mysql-cluster-programs-ndb-config. (line 254) * ndb_config, mycnf option: mysql-cluster-programs-ndb-config. (line 183) * ndb_config, ndb-connectstring option: mysql-cluster-programs-ndb-config. (line 143) * ndb_config, nodeid option: mysql-cluster-programs-ndb-config. (line 256) * ndb_config, nodes option: mysql-cluster-programs-ndb-config. (line 271) * ndb_config, query option: mysql-cluster-programs-ndb-config. (line 196) * ndb_config, rows option: mysql-cluster-programs-ndb-config. (line 362) * ndb_config, system option: mysql-cluster-programs-ndb-config. (line 305) * ndb_config, type option: mysql-cluster-programs-ndb-config. (line 324) * ndb_config, usage option: mysql-cluster-programs-ndb-config. (line 95) * ndb_config, version option: mysql-cluster-programs-ndb-config. (line 132) * ndb_config, xml option: mysql-cluster-programs-ndb-config. (line 439) * ndb_cpcd <1>: mysql-cluster-programs-ndb-cpcd. (line 6) * ndb_cpcd: mysql-cluster-programs. (line 34) * ndb_delete_all <1>: mysql-cluster-programs-ndb-delete-all. (line 6) * ndb_delete_all: mysql-cluster-programs. (line 34) * ndb_delete_all, transactional option: mysql-cluster-programs-ndb-delete-all. (line 45) * ndb_desc <1>: mysql-cluster-programs-ndb-desc. (line 6) * ndb_desc: mysql-cluster-programs. (line 34) * ndb_desc, blob-info option: mysql-cluster-programs-ndb-desc. (line 282) * ndb_desc, database option: mysql-cluster-programs-ndb-desc. (line 293) * ndb_desc, extra-node-info option: mysql-cluster-programs-ndb-desc. (line 297) * ndb_desc, extra-partition-info option: mysql-cluster-programs-ndb-desc. (line 311) * ndb_desc, retries option: mysql-cluster-programs-ndb-desc. (line 315) * ndb_desc, table option: mysql-cluster-programs-ndb-desc. (line 320) * ndb_desc, unqualified option: mysql-cluster-programs-ndb-desc. (line 327) * ndb_dist_priv.sql: mysql-cluster-privilege-distribution. (line 11) * ndb_drop_index <1>: mysql-cluster-programs-ndb-drop-index. (line 6) * ndb_drop_index: mysql-cluster-programs. (line 34) * ndb_drop_table <1>: mysql-cluster-programs-ndb-drop-table. (line 6) * ndb_drop_table: mysql-cluster-programs. (line 34) * ndb_error_reporter <1>: mysql-cluster-programs-ndb-error-reporter. (line 6) * ndb_error_reporter: mysql-cluster-programs. (line 34) * ndb_index_stat <1>: mysql-cluster-programs-ndb-index-stat. (line 6) * ndb_index_stat: mysql-cluster-programs. (line 34) * ndb_log_empty_epochs system variable: mysql-cluster-system-variables. (line 1125) * ndb_log_transaction_id system variable: mysql-cluster-system-variables. (line 1099) * ndb_mgm <1>: mysql-cluster-programs-ndb-mgm. (line 6) * ndb_mgm: mysql-cluster-programs. (line 34) * ndb_mgm (MySQL Cluster management node client): mysql-cluster-install-first-start. (line 34) * ndb_mgm, using with MySQL Cluster Manager: mysql-cluster-mgm-client-commands. (line 17) * ndb_mgmd <1>: mysql-cluster-programs-ndb-mgmd. (line 6) * ndb_mgmd: mysql-cluster-programs. (line 34) * ndb_mgmd (MySQL Cluster process): mysql-cluster-programs-ndb-mgmd. (line 6) * ndb_mgmd (MySQL Cluster), defined: mysql-cluster-basics. (line 6) * ndb_mgmd, mycnf option: mysql-cluster-programs-ndb-mgmd. (line 255) * ndb_print_backup_file <1>: mysql-cluster-programs-ndb-print-backup-file. (line 6) * ndb_print_backup_file: mysql-cluster-programs. (line 34) * ndb_print_schema_file <1>: mysql-cluster-programs-ndb-print-schema-file. (line 6) * ndb_print_schema_file: mysql-cluster-programs. (line 34) * ndb_print_sys_file <1>: mysql-cluster-programs-ndb-print-sys-file. (line 6) * ndb_print_sys_file: mysql-cluster-programs. (line 34) * ndb_replication system table: mysql-cluster-replication-conflict-resolution. (line 160) * ndb_restore: mysql-cluster-programs-ndb-restore. (line 6) * ndb_restore, and circular replication: mysql-cluster-replication-multi-master. (line 78) * ndb_restore, append option: mysql-cluster-programs-ndb-restore. (line 570) * ndb_restore, attribute promotion: mysql-cluster-programs-ndb-restore. (line 275) * ndb_restore, backup_path option: mysql-cluster-programs-ndb-restore. (line 393) * ndb_restore, disable-indexes option: mysql-cluster-programs-ndb-restore. (line 891) * ndb_restore, dont_ignore_systab_0 option: mysql-cluster-programs-ndb-restore. (line 611) * ndb_restore, errors: mysql-cluster-programs-ndb-restore. (line 1004) * ndb_restore, exclude-databases option: mysql-cluster-programs-ndb-restore. (line 749) * ndb_restore, exclude-missing-columns option: mysql-cluster-programs-ndb-restore. (line 873) * ndb_restore, exclude-tables option: mysql-cluster-programs-ndb-restore. (line 760) * ndb_restore, fields-enclosed-by option: mysql-cluster-programs-ndb-restore. (line 495) * ndb_restore, fields-optionally-enclosed-by option: mysql-cluster-programs-ndb-restore. (line 510) * ndb_restore, fields-terminated-by option: mysql-cluster-programs-ndb-restore. (line 527) * ndb_restore, hex option: mysql-cluster-programs-ndb-restore. (line 543) * ndb_restore, include-databases option: mysql-cluster-programs-ndb-restore. (line 670) * ndb_restore, include-tables option: mysql-cluster-programs-ndb-restore. (line 681) * ndb_restore, lossy-conversions option: mysql-cluster-programs-ndb-restore. (line 305) * ndb_restore, ndb-nodegroup-map option: mysql-cluster-programs-ndb-restore. (line 620) * ndb_restore, no-binlog option: mysql-cluster-programs-ndb-restore. (line 626) * ndb_restore, no-restore-disk-objects option: mysql-cluster-programs-ndb-restore. (line 633) * ndb_restore, no-upgrade option: mysql-cluster-programs-ndb-restore. (line 454) * ndb_restore, parallelism option: mysql-cluster-programs-ndb-restore. (line 641) * ndb_restore, print option: mysql-cluster-programs-ndb-restore. (line 597) * ndb_restore, print_data option: mysql-cluster-programs-ndb-restore. (line 466) * ndb_restore, print_log option: mysql-cluster-programs-ndb-restore. (line 592) * ndb_restore, print_meta option: mysql-cluster-programs-ndb-restore. (line 587) * ndb_restore, progress-frequency option: mysql-cluster-programs-ndb-restore. (line 647) * ndb_restore, rebuild-indexes option: mysql-cluster-programs-ndb-restore. (line 907) * ndb_restore, restore-privilege-tables option: mysql-cluster-programs-ndb-restore. (line 382) * ndb_restore, rewrite-database option: mysql-cluster-programs-ndb-restore. (line 954) * ndb_restore, skip-broken-objects option: mysql-cluster-programs-ndb-restore. (line 920) * ndb_restore, skip-unknown-objects option: mysql-cluster-programs-ndb-restore. (line 937) * ndb_restore, tab option: mysql-cluster-programs-ndb-restore. (line 481) * ndb_restore, verbose option: mysql-cluster-programs-ndb-restore. (line 653) * ndb_schema table (MySQL Cluster replication): mysql-cluster-replication-schema. (line 193) * ndb_select_all <1>: mysql-cluster-programs-ndb-select-all. (line 6) * ndb_select_all: mysql-cluster-programs. (line 34) * ndb_select_all, database option: mysql-cluster-programs-ndb-select-all. (line 66) * ndb_select_all, delimiter option: mysql-cluster-programs-ndb-select-all. (line 109) * ndb_select_all, descending option: mysql-cluster-programs-ndb-select-all. (line 94) * ndb_select_all, disk option: mysql-cluster-programs-ndb-select-all. (line 116) * ndb_select_all, gci option: mysql-cluster-programs-ndb-select-all. (line 126) * ndb_select_all, header option: mysql-cluster-programs-ndb-select-all. (line 99) * ndb_select_all, lock option: mysql-cluster-programs-ndb-select-all. (line 75) * ndb_select_all, nodata option: mysql-cluster-programs-ndb-select-all. (line 137) * ndb_select_all, order option: mysql-cluster-programs-ndb-select-all. (line 88) * ndb_select_all, parallelism option: mysql-cluster-programs-ndb-select-all. (line 71) * ndb_select_all, rowid option: mysql-cluster-programs-ndb-select-all. (line 121) * ndb_select_all, tupscan option: mysql-cluster-programs-ndb-select-all. (line 133) * ndb_select_all, useHexFormat option: mysql-cluster-programs-ndb-select-all. (line 103) * ndb_select_count <1>: mysql-cluster-programs-ndb-select-count. (line 6) * ndb_select_count: mysql-cluster-programs. (line 34) * ndb_show_tables <1>: mysql-cluster-programs-ndb-show-tables. (line 6) * ndb_show_tables: mysql-cluster-programs. (line 34) * ndb_show_tables, database option: mysql-cluster-programs-ndb-show-tables. (line 50) * ndb_show_tables, loops option: mysql-cluster-programs-ndb-show-tables. (line 54) * ndb_show_tables, parsable option: mysql-cluster-programs-ndb-show-tables. (line 60) * ndb_show_tables, show-temp-status option: mysql-cluster-programs-ndb-show-tables. (line 65) * ndb_show_tables, type option: mysql-cluster-programs-ndb-show-tables. (line 69) * ndb_show_tables, unqualified option: mysql-cluster-programs-ndb-show-tables. (line 83) * ndb_size.pl <1>: mysql-cluster-programs-ndb-size-pl. (line 6) * ndb_size.pl: mysql-cluster-programs. (line 34) * ndb_size.pl (utility): faqs-mysql-cluster. (line 6) * ndb_waiter <1>: mysql-cluster-programs-ndb-waiter. (line 6) * ndb_waiter: mysql-cluster-programs. (line 34) * ndb_waiter, no-contact option: mysql-cluster-programs-ndb-waiter. (line 78) * ndb_waiter, not-started option: mysql-cluster-programs-ndb-waiter. (line 84) * ndb_waiter, nowait-nodes option: mysql-cluster-programs-ndb-waiter. (line 100) * ndb_waiter, single-user option: mysql-cluster-programs-ndb-waiter. (line 96) * ndb_waiter, timeout option: mysql-cluster-programs-ndb-waiter. (line 90) * ndb_waiter, wait-nodes option: mysql-cluster-programs-ndb-waiter. (line 114) * ndbcluster option, mysqld: mysql-cluster-program-options-mysqld. (line 288) * NDBCLUSTER storage engine: mysql-cluster. (line 16) * ndbd <1>: mysql-cluster-programs-ndbd. (line 6) * ndbd: mysql-cluster-programs. (line 34) * ndbd (MySQL Cluster), defined: mysql-cluster-basics. (line 6) * ndbd_redo_log_reader: mysql-cluster-programs-ndbd-redo-log-reader. (line 6) * ndbinfo database: mysql-cluster-ndbinfo. (line 29) * ndbinfo database, and query cache: mysql-cluster-ndbinfo. (line 183) * ndbinfo database, basic usage: mysql-cluster-ndbinfo. (line 232) * ndbinfo database, determining support for: mysql-cluster-ndbinfo. (line 37) * ndbinfo_select_all <1>: mysql-cluster-programs-ndbinfo-select-all. (line 6) * ndbinfo_select_all: mysql-cluster-programs. (line 34) * ndbmtd <1>: mysql-cluster-programs-ndbmtd. (line 6) * ndbmtd: mysql-cluster-programs. (line 34) * ndbmtd, configuration: mysql-cluster-ndbd-definition. (line 3313) * ndbmtd, MaxNoOfExecutionThreads: mysql-cluster-ndbd-definition. (line 3244) * ndbmtd, trace files: mysql-cluster-programs-ndbmtd. (line 67) * negative values: number-literals. (line 6) * nested queries: subqueries. (line 20) * nested-loop join algorithm: nested-join-optimization. (line 167) * Nested-Loop join algorithm: nested-loop-joins. (line 6) * net etiquette: mailing-list-use. (line 6) * net_buffer_length system variable: server-system-variables. (line 3672) * net_buffer_length variable: mysql-command-options. (line 629) * net_read_timeout system variable: server-system-variables. (line 3708) * net_retry_count system variable: server-system-variables. (line 3739) * net_write_timeout system variable: server-system-variables. (line 3778) * NetBeans: connector-cpp-apps-linux-netbeans. (line 6) * netmask notation, in account names: account-names. (line 89) * network ports, and MySQL Cluster: mysql-cluster-security-networking-issues. (line 186) * new features in MySQL 5.1: mysql-nutshell. (line 6) * new features in MySQL Cluster: mysql-cluster-development. (line 16) * new system variable: server-system-variables. (line 3806) * new users, adding: unix-postinstallation. (line 371) * newline (\n) <1>: load-data. (line 432) * newline (\n): string-literals. (line 72) * next-key lock, InnoDB <1>: innodb-next-key-locking. (line 6) * next-key lock, InnoDB <2>: innodb-record-level-locks. (line 6) * next-key lock, InnoDB <3>: innodb-transaction-model. (line 74) * next-key lock, InnoDB: innodb-parameters. (line 1122) * NFS, InnoDB <1>: innodb-restrictions. (line 16) * NFS, InnoDB: innodb-configuration. (line 73) * nice option, mysqld_safe: mysqld-safe. (line 193) * no matching rows: no-matching-rows. (line 6) * no-auto-rehash option, mysql: mysql-command-options. (line 315) * no-autocommit option, mysqldump: mysqldump. (line 746) * no-beep option, mysql: mysql-command-options. (line 320) * no-beep option, mysqladmin: mysqladmin. (line 359) * no-binlog option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 626) * no-contact option, ndb_waiter: mysql-cluster-programs-ndb-waiter. (line 78) * no-create-db option, mysqldump: mysqldump. (line 752) * no-create-info option, mysqldump: mysqldump. (line 758) * no-data option, mysqldump: mysqldump. (line 770) * no-debug option, make_win_bin_dist: make-win-bin-dist. (line 52) * no-defaults option: option-file-options. (line 43) * no-defaults option, my_print_defaults: my-print-defaults. (line 53) * no-defaults option, mysqld_multi: mysqld-multi. (line 64) * no-defaults option, mysqld_safe: mysqld-safe. (line 198) * no-drop option, mysqlslap: mysqlslap. (line 347) * no-embedded option, make_win_bin_dist: make-win-bin-dist. (line 56) * no-log option, mysqld_multi: mysqld-multi. (line 144) * no-named-commands option, mysql: mysql-command-options. (line 324) * no-nodeid-checks option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 121) * no-pager option, mysql: mysql-command-options. (line 329) * no-restore-disk-objects option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 633) * no-set-names option, mysqldump: mysqldump. (line 778) * no-symlinks option, myisamchk: myisamchk-repair-options. (line 54) * no-tablespaces option, mysqldump: mysqldump. (line 782) * no-tee option, mysql: mysql-command-options. (line 334) * no-upgrade option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 454) * NO_AUTO_CREATE_USER SQL mode: server-sql-mode. (line 193) * NO_AUTO_VALUE_ON_ZERO SQL mode: server-sql-mode. (line 199) * NO_BACKSLASH_ESCAPES SQL mode: server-sql-mode. (line 218) * NO_DIR_IN_CREATE SQL mode: server-sql-mode. (line 224) * NO_ENGINE_SUBSTITUTION SQL mode: server-sql-mode. (line 230) * NO_FIELD_OPTIONS SQL mode: server-sql-mode. (line 260) * NO_KEY_OPTIONS SQL mode: server-sql-mode. (line 266) * NO_TABLE_OPTIONS SQL mode: server-sql-mode. (line 272) * NO_UNSIGNED_SUBTRACTION SQL mode: server-sql-mode. (line 278) * NO_ZERO_DATE SQL mode: server-sql-mode. (line 325) * NO_ZERO_IN_DATE SQL mode: server-sql-mode. (line 331) * nodaemon option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 366) * nodata option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 137) * node groups (MySQL Cluster): mysql-cluster-nodes-groups. (line 6) * node logs (MySQL Cluster): mysql-cluster-event-reports. (line 12) * NodeGroup: mysql-cluster-ndbd-definition. (line 174) * NodeId <1>: mysql-cluster-api-definition. (line 58) * NodeId <2>: mysql-cluster-ndbd-definition. (line 86) * NodeId: mysql-cluster-mgm-definition. (line 48) * nodeid option, ndb_config: mysql-cluster-programs-ndb-config. (line 256) * NodeId1 <1>: mysql-cluster-sci-definition. (line 26) * NodeId1 <2>: mysql-cluster-shm-definition. (line 25) * NodeId1: mysql-cluster-tcp-definition. (line 37) * NodeId2 <1>: mysql-cluster-sci-definition. (line 35) * NodeId2 <2>: mysql-cluster-shm-definition. (line 34) * NodeId2: mysql-cluster-tcp-definition. (line 46) * NODERESTART Events (MySQL Cluster): mysql-cluster-log-events. (line 103) * nodes option, ndb_config: mysql-cluster-programs-ndb-config. (line 271) * nodes, ndbinfo table: mysql-cluster-ndbinfo-nodes. (line 6) * noindices option, mysqlhotcopy: mysqlhotcopy. (line 132) * nondelimited strings: date-and-time-literals. (line 120) * Nontransactional tables: nontransactional-tables. (line 6) * NoOfDiskPagesToDiskAfterRestartACC (DEPRECATED): mysql-cluster-ndbd-definition. (line 2384) * NoOfDiskPagesToDiskAfterRestartACC, calculating: mysql-cluster-config-lcp-params. (line 6) * NoOfDiskPagesToDiskAfterRestartTUP (DEPRECATED): mysql-cluster-ndbd-definition. (line 2343) * NoOfDiskPagesToDiskAfterRestartTUP, calculating: mysql-cluster-config-lcp-params. (line 6) * NoOfDiskPagesToDiskDuringRestartACC: mysql-cluster-ndbd-definition. (line 2438) * NoOfDiskPagesToDiskDuringRestartTUP: mysql-cluster-ndbd-definition. (line 2408) * NoOfFragmentLogFiles: mysql-cluster-ndbd-definition. (line 1067) * NoOfFragmentLogFiles, calculating: mysql-cluster-config-lcp-params. (line 6) * NoOfReplicas: mysql-cluster-ndbd-definition. (line 204) * nopager command, mysql: mysql-commands. (line 139) * nostart option (ndbd): mysql-cluster-programs-ndbd. (line 307) * nostart option (ndbmtd): mysql-cluster-programs-ndbd. (line 307) * NOT BETWEEN: comparison-operators. (line 223) * not equal (!=): comparison-operators. (line 91) * not equal (<>): comparison-operators. (line 91) * NOT EXISTS, with subqueries: exists-and-not-exists-subqueries. (line 6) * NOT IN: comparison-operators. (line 291) * NOT LIKE: string-comparison-functions. (line 164) * NOT NULL, constraint: constraint-invalid-data. (line 6) * NOT REGEXP: regexp. (line 28) * NOT, logical: logical-operators. (line 29) * not-started option, ndb_waiter: mysql-cluster-programs-ndb-waiter. (line 84) * notee command, mysql: mysql-commands. (line 145) * Notifier: windows-notifier. (line 10) * NOW(): date-and-time-functions. (line 730) * NOWAIT (START BACKUP command): mysql-cluster-backup-using-management-client. (line 42) * nowait-nodes option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 446) * nowait-nodes option (ndbd): mysql-cluster-programs-ndbd. (line 274) * nowait-nodes option (ndbmtd): mysql-cluster-programs-ndbd. (line 274) * nowait-nodes option, ndb_waiter: mysql-cluster-programs-ndb-waiter. (line 100) * nowarning command, mysql: mysql-commands. (line 150) * NUL <1>: load-data. (line 430) * NUL: string-literals. (line 68) * NULL <1>: problems-with-null. (line 6) * NULL: working-with-null. (line 6) * NULL value <1>: null-values. (line 6) * NULL value: working-with-null. (line 6) * NULL values, and AUTO_INCREMENT columns: problems-with-null. (line 71) * NULL values, and indexes: create-table. (line 503) * NULL values, and TIMESTAMP columns: problems-with-null. (line 71) * NULL values, vs. empty values: problems-with-null. (line 6) * NULL, ORDER BY <1>: select. (line 199) * NULL, ORDER BY: order-by-optimization. (line 106) * NULL, testing for null <1>: control-flow-functions. (line 86) * NULL, testing for null: comparison-operators. (line 79) * NULL, thread state: general-thread-states. (line 175) * NULLIF(): control-flow-functions. (line 120) * Numa: mysql-cluster-ndbd-definition. (line 3208) * number-char-cols option, mysqlslap: mysqlslap. (line 352) * number-int-cols option, mysqlslap: mysqlslap. (line 357) * number-of-queries option, mysqlslap: mysqlslap. (line 362) * numbers: number-literals. (line 6) * NUMERIC data type: numeric-type-overview. (line 186) * numeric precision: data-types. (line 33) * numeric scale: data-types. (line 39) * numeric types: storage-requirements. (line 83) * numeric-dump-file option, resolve_stack_dump: resolve-stack-dump. (line 25) * NumGeometries(): geometrycollection-property-functions. (line 21) * NumInteriorRings(): polygon-property-functions. (line 49) * NumPoints(): linestring-property-functions. (line 68) * NVARCHAR data type: string-type-overview. (line 121) * obtaining information about partitions: partitioning-info. (line 6) * OCT(): string-functions. (line 487) * OCTET_LENGTH(): string-functions. (line 496) * ODBC: connector-odbc. (line 17) * ODBC compatibility <1>: join. (line 147) * ODBC compatibility <2>: create-table. (line 301) * ODBC compatibility <3>: comparison-operators. (line 153) * ODBC compatibility <4>: type-conversion. (line 44) * ODBC compatibility <5>: numeric-type-overview. (line 255) * ODBC compatibility <6>: identifier-qualifiers. (line 48) * ODBC compatibility: server-system-variables. (line 5117) * ODBC.NET: connector-odbc-examples-programming-net. (line 11) * ODirect: mysql-cluster-ndbd-definition. (line 1645) * offset option, mysqlbinlog: mysqlbinlog. (line 394) * OLAP: group-by-modifiers. (line 6) * old system variable: server-system-variables. (line 3829) * old-alter-table option, mysqld: server-options. (line 1465) * old-style-user-limits option, mysqld: server-options. (line 1490) * old_alter_table system variable: server-system-variables. (line 3858) * OLD_PASSWORD(): encryption-functions. (line 305) * old_passwords system variable: server-system-variables. (line 3883) * old_server option, mysqlaccess: mysqlaccess. (line 103) * ON DUPLICATE KEY UPDATE: insert. (line 12) * one-database option, mysql: mysql-command-options. (line 339) * one-thread option, mysqld: server-options. (line 1507) * one_shot system variable: server-system-variables. (line 3915) * online location of manual: manual-info. (line 6) * online upgrades and downgrades (MySQL Cluster): mysql-cluster-rolling-restart. (line 6) * online upgrades and downgrades (MySQL Cluster), order of node updates: mysql-cluster-rolling-restart. (line 106) * only-debug option, make_win_bin_dist: make-win-bin-dist. (line 60) * only-print option, mysqlslap: mysqlslap. (line 375) * ONLY_FULL_GROUP_BY SQL mode: server-sql-mode. (line 340) * ONLY_FULL_GROUP_BY, SQL mode: group-by-extensions. (line 6) * OPEN: open. (line 6) * Open Source, defined: what-is-mysql. (line 54) * open tables <1>: table-cache. (line 6) * open tables: mysqladmin. (line 192) * open-files-limit option, mysqld: server-options. (line 1522) * open-files-limit option, mysqld_safe: mysqld-safe. (line 203) * open_files_limit system variable: server-system-variables. (line 3920) * open_files_limit variable: mysqlbinlog. (line 552) * OpenGIS: gis-introduction. (line 6) * Opening master dump table, thread state: slave-connection-thread-states. (line 25) * Opening mysql.ndb_apply_status, thread state: mysql-cluster-thread-states. (line 8) * Opening table, thread state: general-thread-states. (line 189) * Opening tables, thread state: general-thread-states. (line 189) * opening, tables: table-cache. (line 6) * opens: mysqladmin. (line 183) * OpenSSL <1>: configuring-for-ssl. (line 6) * OpenSSL: ssl-connections. (line 14) * operating systems, file-size limits: table-size-limit. (line 6) * operating systems, supported: supported-os. (line 6) * operations, arithmetic: arithmetic-functions. (line 55) * operators: functions. (line 27) * operators, assignment <1>: assignment-operators. (line 6) * operators, assignment: user-variables. (line 6) * operators, cast <1>: cast-functions. (line 6) * operators, cast: arithmetic-functions. (line 6) * operators, logical: logical-operators. (line 6) * operators, precedence: operator-precedence. (line 6) * opt option, mysqldump: mysqldump. (line 791) * optimization, subquery: subquery-optimization-with-exists. (line 6) * optimization, tips: miscellaneous-optimization-tips. (line 6) * optimizations <1>: index-merge-optimization. (line 12) * optimizations: where-optimizations. (line 6) * optimize option, mysqlcheck: mysqlcheck. (line 330) * OPTIMIZE TABLE: optimize-table. (line 6) * OPTIMIZE TABLE, and partitioning: partitioning-maintenance. (line 6) * optimizer, and replication: replication-features-optimizer. (line 6) * optimizer, controlling: controlling-optimizer. (line 11) * optimizer, query plan evaluation: controlling-query-plan-evaluation. (line 6) * optimizer, switchable optimizations: switchable-optimizations. (line 6) * optimizer_prune_level system variable: server-system-variables. (line 3945) * optimizer_search_depth system variable: server-system-variables. (line 3968) * optimizer_switch system variable <1>: switchable-optimizations. (line 6) * optimizer_switch system variable: server-system-variables. (line 3998) * optimizing, DISTINCT: distinct-optimization. (line 6) * optimizing, filesort: order-by-optimization. (line 125) * optimizing, GROUP BY: group-by-optimization. (line 11) * optimizing, LEFT JOIN: left-join-optimization. (line 6) * optimizing, LIMIT: limit-optimization. (line 6) * optimizing, tables: myisam-optimization. (line 6) * optimizing, thread state: general-thread-states. (line 198) * option files <1>: access-denied. (line 101) * option files: option-files. (line 6) * option files, escape sequences: option-files. (line 172) * option prefix, -disable: option-modifiers. (line 6) * option prefix, -enable: option-modifiers. (line 6) * option prefix, -loose: option-modifiers. (line 6) * option prefix, -maximum: option-modifiers. (line 6) * option prefix, -skip: option-modifiers. (line 6) * options, boolean: option-modifiers. (line 6) * options, command-line, mysql: mysql-command-options. (line 6) * options, command-line, mysqladmin: mysqladmin. (line 213) * options, configure: source-configuration-options. (line 6) * options, embedded server: libmysqld-options. (line 6) * options, libmysqld: libmysqld-options. (line 6) * options, myisamchk: myisamchk-general-options. (line 6) * options, provided by MySQL: tutorial. (line 16) * options, replication: replication-features. (line 45) * OR <1>: index-merge-optimization. (line 12) * OR: searching-on-two-keys. (line 6) * OR Index Merge optimization: index-merge-optimization. (line 12) * OR, bitwise: bit-functions. (line 20) * OR, logical: logical-operators. (line 65) * Oracle compatibility <1>: explain. (line 53) * Oracle compatibility <2>: alter-table. (line 299) * Oracle compatibility <3>: group-by-functions. (line 240) * Oracle compatibility: extensions-to-ansi. (line 99) * ORACLE SQL mode: server-sql-mode. (line 548) * ORD(): string-functions. (line 500) * ORDER BY <1>: select. (line 171) * ORDER BY <2>: alter-table. (line 384) * ORDER BY: sorting-rows. (line 6) * ORDER BY, NULL <1>: select. (line 199) * ORDER BY, NULL: order-by-optimization. (line 106) * order option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 88) * order-by-primary option, mysqldump: mysqldump. (line 805) * Out of resources error, and partitioned tables: partitioning-limitations. (line 224) * out-of-range handling: out-of-range-and-overflow. (line 6) * out_dir option, comp_err: comp-err. (line 56) * out_file option, comp_err: comp-err. (line 61) * OUTFILE: select-into. (line 47) * overflow handling: out-of-range-and-overflow. (line 6) * Overlaps(): functions-that-test-spatial-relationships-between-geometries. (line 53) * OverloadLimit <1>: mysql-cluster-sci-definition. (line 185) * OverloadLimit: mysql-cluster-tcp-definition. (line 86) * overview: introduction. (line 18) * packages, list of: packages. (line 6) * PAD_CHAR_TO_FULL_LENGTH SQL mode: server-sql-mode. (line 378) * page size, InnoDB <1>: innodb-restrictions. (line 75) * page size, InnoDB: innodb-physical-structure. (line 6) * pager command, mysql: mysql-commands. (line 154) * pager option, mysql: mysql-command-options. (line 382) * PAM authentication, with Connector/J: connector-j-using-pam. (line 6) * parallel-recover option, myisamchk: myisamchk-repair-options. (line 66) * parallelism option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 641) * parameters, server: server-parameters. (line 6) * parentheses ( and ): operator-precedence. (line 48) * parsable option, ndb_show_tables: mysql-cluster-programs-ndb-show-tables. (line 60) * partial trust: connector-net-medium-trust. (line 12) * partial updates, and replication: replication-features-slaveerrors. (line 6) * PARTITION: partitioning. (line 14) * partition management: partitioning-management. (line 13) * partition option, mysqld: server-options. (line 1555) * partition pruning: partitioning-pruning. (line 6) * partitioning: partitioning. (line 14) * partitioning information statements: partitioning-info. (line 6) * partitioning keys and primary keys: partitioning-limitations-partitioning-keys-unique-keys. (line 6) * partitioning keys and unique keys: partitioning-limitations-partitioning-keys-unique-keys. (line 6) * partitioning, advantages: partitioning-overview. (line 147) * partitioning, and dates: partitioning-types. (line 49) * partitioning, and foreign keys: partitioning-limitations. (line 249) * partitioning, and FULLTEXT indexes: partitioning-limitations. (line 275) * partitioning, and key cache: partitioning-limitations. (line 400) * partitioning, and query cache: partitioning-limitations. (line 393) * partitioning, and replication: replication-features-sql-mode. (line 6) * partitioning, and SQL mode <1>: partitioning-limitations. (line 49) * partitioning, and SQL mode: replication-features-sql-mode. (line 6) * partitioning, and subqueries: partitioning-limitations. (line 316) * partitioning, and temporary tables <1>: partitioning-limitations-partitioning-keys-unique-keys. (line 6) * partitioning, and temporary tables: partitioning-limitations. (line 286) * partitioning, by hash: partitioning-hash. (line 10) * partitioning, by key: partitioning-key. (line 6) * partitioning, by linear hash: partitioning-linear-hash. (line 6) * partitioning, by linear key: partitioning-key. (line 109) * partitioning, by list: partitioning-list. (line 6) * partitioning, by range: partitioning-range. (line 6) * partitioning, concepts: partitioning-overview. (line 6) * partitioning, data type of partitioning key: partitioning-limitations. (line 297) * partitioning, enabling: partitioning. (line 14) * partitioning, functions supported in partitioning expressions: partitioning-limitations-functions. (line 9) * partitioning, limitations: partitioning-limitations. (line 13) * Partitioning, maximum number of partitions: partitioning-limitations. (line 224) * partitioning, operators not permitted in partitioning expressions: partitioning-limitations. (line 30) * partitioning, operators supported in partitioning expressions: partitioning-limitations. (line 30) * partitioning, optimization <1>: partitioning-pruning. (line 6) * partitioning, optimization: partitioning-info. (line 62) * partitioning, resources: partitioning. (line 153) * partitioning, storage engines (limitations): partitioning-limitations-storage-engines. (line 6) * partitioning, subpartitioning: partitioning-limitations. (line 321) * partitioning, support: partitioning. (line 14) * partitioning, support in MySQL Cluster: mysql-cluster-limitations-syntax. (line 106) * partitioning, types: partitioning-types. (line 15) * partitions (MySQL Cluster): mysql-cluster-nodes-groups. (line 6) * partitions, adding and dropping: partitioning-management. (line 13) * partitions, analyzing: partitioning-maintenance. (line 6) * partitions, checking: partitioning-maintenance. (line 6) * PARTITIONS, INFORMATION_SCHEMA table: partitions-table. (line 6) * partitions, managing: partitioning-management. (line 13) * partitions, modifying: partitioning-management. (line 13) * partitions, optimizing: partitioning-maintenance. (line 6) * partitions, repairing: partitioning-maintenance. (line 6) * partitions, splitting and merging: partitioning-management. (line 13) * password encryption, reversibility of: encryption-functions. (line 356) * password option: connecting. (line 134) * password option, mysql: mysql-command-options. (line 391) * password option, mysql_convert_table_format: mysql-convert-table-format. (line 36) * password option, mysql_setpermission: mysql-setpermission. (line 37) * password option, mysqlaccess: mysqlaccess. (line 108) * password option, mysqladmin: mysqladmin. (line 365) * password option, mysqlbinlog: mysqlbinlog. (line 398) * password option, mysqlcheck: mysqlcheck. (line 334) * password option, mysqld_multi: mysqld-multi. (line 149) * password option, mysqldump: mysqldump. (line 812) * password option, mysqlhotcopy: mysqlhotcopy. (line 139) * password option, mysqlimport: mysqlimport. (line 239) * password option, mysqlmanager: instance-manager-command-options. (line 159) * password option, mysqlshow: mysqlshow. (line 168) * password option, mysqlslap: mysqlslap. (line 381) * PASSWORD() <1>: ignoring-user. (line 26) * PASSWORD() <2>: encryption-functions. (line 315) * PASSWORD() <3>: assigning-passwords. (line 6) * PASSWORD(): connection-access. (line 38) * password, root user: default-privileges. (line 6) * password-file option, mysqlmanager: instance-manager-command-options. (line 167) * passwords, administrator guidelines: password-security-admin. (line 6) * passwords, for users: user-names. (line 6) * passwords, forgotten: resetting-permissions. (line 12) * passwords, hashing: password-hashing. (line 6) * passwords, logging: password-logging. (line 6) * passwords, lost: resetting-permissions. (line 12) * passwords, resetting: resetting-permissions. (line 12) * passwords, security <1>: privilege-system. (line 16) * passwords, security: password-security. (line 14) * passwords, setting <1>: set-password. (line 6) * passwords, setting <2>: grant. (line 397) * passwords, setting: assigning-passwords. (line 6) * passwords, user guidelines: password-security-user. (line 6) * PATH environment variable <1>: invoking-programs. (line 48) * PATH environment variable <2>: environment-variables. (line 18) * PATH environment variable: unix-postinstallation. (line 68) * path name separators, Windows: option-files. (line 194) * pattern matching <1>: regexp. (line 6) * pattern matching: pattern-matching. (line 6) * PEP-249 specification for Python: connector-python. (line 17) * performance, benchmarks: custom-benchmarks. (line 6) * performance, disk I/O: disk-issues. (line 6) * performance, estimating: estimating-performance. (line 6) * performance, improving: data-size. (line 6) * PERIOD_ADD(): date-and-time-functions. (line 774) * PERIOD_DIFF(): date-and-time-functions. (line 783) * Perl API: apis-perl. (line 6) * Perl DBI/DBD, installation problems: perl-support-problems. (line 6) * Perl, installing: perl-support. (line 12) * Perl, installing on Windows: activestate-perl. (line 6) * permission checks, effect on speed: select-optimization. (line 25) * perror <1>: perror. (line 6) * perror: programs-overview. (line 279) * perror, -ndb option: faqs-mysql-cluster. (line 6) * perror, help option: perror. (line 40) * perror, ndb option: perror. (line 44) * perror, silent option: perror. (line 48) * perror, verbose option: perror. (line 52) * perror, version option: perror. (line 57) * phantom rows: innodb-next-key-locking. (line 6) * PHP API: apis-php. (line 18) * PI(): mathematical-functions. (line 325) * pid-file option, mysql.server: mysql-server. (line 44) * pid-file option, mysqld: server-options. (line 1571) * pid-file option, mysqld_safe: mysqld-safe. (line 210) * pid-file option, mysqlmanager: instance-manager-command-options. (line 175) * pid_file system variable: server-system-variables. (line 4038) * Ping, thread command: thread-commands. (line 78) * pipe option: connecting. (line 141) * pipe option, mysql <1>: mysqlcheck. (line 346) * pipe option, mysql: mysql-command-options. (line 403) * pipe option, mysqladmin: mysqladmin. (line 377) * pipe option, mysqldump: mysqldump. (line 824) * pipe option, mysqlimport: mysqlimport. (line 251) * pipe option, mysqlshow: mysqlshow. (line 180) * pipe option, mysqlslap: mysqlslap. (line 393) * PIPES_AS_CONCAT SQL mode: server-sql-mode. (line 416) * plan option, mysqlaccess: mysqlaccess. (line 117) * plugin API <1>: plugin-api. (line 13) * plugin API: server-plugins. (line 11) * plugin option prefix, mysqld: server-options. (line 1593) * plugin-load option, mysqld: server-options. (line 1618) * plugin_dir system variable: server-system-variables. (line 4057) * plugindir option, mysql_config: mysql-config. (line 41) * plugins, activating: server-plugin-loading. (line 6) * plugins, adding: plugin-api. (line 13) * plugins, daemon: daemon-plugins. (line 6) * plugins, full-text parser: full-text-plugins. (line 6) * plugins, INFORMATION_SCHEMA: information-schema-plugins. (line 6) * PLUGINS, INFORMATION_SCHEMA table: plugins-table. (line 6) * plugins, installing <1>: install-plugin. (line 6) * plugins, installing: server-plugin-loading. (line 6) * plugins, server: server-plugins. (line 11) * plugins, storage engine: storage-engine-plugins. (line 6) * plugins, uninstalling <1>: uninstall-plugin. (line 6) * plugins, uninstalling: server-plugin-loading. (line 6) * POINT data type: mysql-spatial-datatypes. (line 6) * Point(): gis-mysql-specific-functions. (line 56) * point-in-time recovery: point-in-time-recovery. (line 11) * point-in-time recovery, using MySQL Cluster replication: mysql-cluster-replication-pitr. (line 6) * PointFromText(): gis-wkt-functions. (line 45) * PointFromWKB(): gis-wkb-functions. (line 48) * PointN(): linestring-property-functions. (line 80) * PointOnSurface(): multipolygon-property-functions. (line 41) * PolyFromText(): gis-wkt-functions. (line 49) * PolyFromWKB(): gis-wkb-functions. (line 52) * POLYGON data type: mysql-spatial-datatypes. (line 6) * Polygon(): gis-mysql-specific-functions. (line 60) * PolygonFromText(): gis-wkt-functions. (line 49) * PolygonFromWKB(): gis-wkb-functions. (line 52) * pools (OBSOLETE), ndbinfo table: mysql-cluster-ndbinfo-pools. (line 6) * port option: connecting. (line 147) * port option, mysql: mysql-command-options. (line 408) * port option, mysql_config: mysql-config. (line 46) * port option, mysql_convert_table_format: mysql-convert-table-format. (line 46) * port option, mysql_setpermission: mysql-setpermission. (line 47) * port option, mysqladmin: mysqladmin. (line 382) * port option, mysqlbinlog: mysqlbinlog. (line 410) * port option, mysqlcheck: mysqlcheck. (line 351) * port option, mysqld: server-options. (line 1675) * port option, mysqld_safe: mysqld-safe. (line 214) * port option, mysqldump: mysqldump. (line 829) * port option, mysqlhotcopy: mysqlhotcopy. (line 149) * port option, mysqlimport: mysqlimport. (line 256) * port option, mysqlmanager: instance-manager-command-options. (line 182) * port option, mysqlshow: mysqlshow. (line 185) * port option, mysqlslap: mysqlslap. (line 398) * port system variable: server-system-variables. (line 4094) * port-open-timeout option, mysqld: server-options. (line 1698) * portability: portability. (line 6) * portability, types: other-vendor-data-types. (line 6) * porting, to other systems: porting. (line 12) * PortNumber: mysql-cluster-mgm-definition. (line 93) * PortNumber (OBSOLETE): mysql-cluster-tcp-definition. (line 169) * ports: security-guidelines. (line 6) * position option, mysqlbinlog: mysqlbinlog. (line 414) * POSITION(): string-functions. (line 516) * post-query option, mysqlslap: mysqlslap. (line 402) * post-system option, mysqlslap: mysqlslap. (line 414) * PostgreSQL compatibility: extensions-to-ansi. (line 193) * POSTGRESQL SQL mode: server-sql-mode. (line 554) * postinstall, multiple servers: multiple-servers. (line 13) * postinstallation, setup and testing: postinstallation. (line 11) * POW(): mathematical-functions. (line 336) * POWER(): mathematical-functions. (line 345) * pre-query option, mysqlslap: mysqlslap. (line 420) * pre-system option, mysqlslap: mysqlslap. (line 426) * precedence, operator: operator-precedence. (line 6) * precision math: precision-math. (line 14) * precision, arithmetic: precision-math. (line 14) * precision, numeric: data-types. (line 33) * prefix option, configure: source-configuration-options. (line 349) * preload_buffer_size system variable: server-system-variables. (line 4116) * PREPARE <1>: prepare. (line 6) * PREPARE: sql-syntax-prepared-statements. (line 13) * Prepare, thread command: thread-commands. (line 82) * PREPARE, XA transactions: xa-statements. (line 6) * prepared statements <1>: c-api-prepared-statements. (line 6) * prepared statements <2>: deallocate-prepare. (line 6) * prepared statements <3>: execute. (line 6) * prepared statements <4>: prepare. (line 6) * prepared statements: sql-syntax-prepared-statements. (line 13) * prepared statements, repreparation: statement-repreparation. (line 6) * prepared statements, with Connector/Net: connector-net-programming-prepared. (line 10) * prepared_stmt_count system variable: server-system-variables. (line 4138) * preparing, thread state: general-thread-states. (line 202) * preserve-schema option, mysqlslap: mysqlslap. (line 432) * preserve-trailing-spaces option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 331) * preview option, mysqlaccess: mysqlaccess. (line 121) * PRIMARY KEY <1>: create-table. (line 445) * PRIMARY KEY: alter-table. (line 364) * primary key, constraint: constraint-primary-key. (line 6) * primary key, deleting: alter-table. (line 357) * primary keys, and partitioning keys: partitioning-limitations-partitioning-keys-unique-keys. (line 6) * print command, mysql: mysql-commands. (line 176) * print option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 597) * print-defaults option: option-file-options. (line 49) * print-defaults option, mysqlmanager: instance-manager-command-options. (line 187) * print-full-config option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 386) * print-password-line option, mysqlmanager: instance-manager-command-options. (line 192) * print_data option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 466) * print_log option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 592) * print_meta option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 587) * privilege information, location: grant-table-structure. (line 6) * privilege system: privilege-system. (line 16) * privilege, changes: privilege-changes. (line 6) * privileges, access: privilege-system. (line 16) * privileges, adding: adding-users. (line 6) * privileges, and replication: replication-features-mysqldb. (line 6) * privileges, default: default-privileges. (line 6) * privileges, deleting <1>: drop-user. (line 6) * privileges, deleting: removing-users. (line 6) * privileges, display: show-grants. (line 6) * privileges, dropping <1>: drop-user. (line 6) * privileges, dropping: removing-users. (line 6) * privileges, granting: grant. (line 6) * privileges, revoking: revoke. (line 6) * problems, access denied errors: error-access-denied. (line 6) * problems, common errors: problems. (line 17) * problems, compiling: compilation-problems. (line 6) * problems, DATE columns: using-date. (line 6) * problems, date values: datetime. (line 53) * problems, installing on IBM-AIX: aix-installation. (line 10) * problems, installing on Solaris: solaris-installation. (line 11) * problems, installing Perl: perl-support-problems. (line 6) * problems, linking: c-api-building-clients. (line 79) * problems, lost connection errors: error-lost-connection. (line 6) * problems, ODBC: connector-odbc-support. (line 12) * problems, reporting <1>: bug-reports. (line 6) * problems, reporting: introduction. (line 69) * problems, starting the server: starting-server. (line 6) * problems, table locking: table-locking. (line 6) * problems, time zone: timezone-problems. (line 6) * PROCEDURE: select. (line 326) * PROCEDURE ANALYSE(): procedure-analyse. (line 8) * procedures, stored: stored-routines. (line 13) * process management (MySQL Cluster): mysql-cluster-programs. (line 34) * process support: supported-os. (line 6) * processes, display: show-processlist. (line 6) * Processing events from schema table, thread state: mysql-cluster-thread-states. (line 14) * Processing events, thread state: mysql-cluster-thread-states. (line 10) * processing, arguments: udf-arguments. (line 6) * PROCESSLIST: show-processlist. (line 6) * PROCESSLIST, INFORMATION_SCHEMA table: processlist-table. (line 6) * Processlist, thread command: thread-commands. (line 86) * profiling session variable: server-system-variables. (line 4158) * PROFILING, INFORMATION_SCHEMA table: profiling-table. (line 6) * profiling_history_size session variable: server-system-variables. (line 4166) * program options (MySQL Cluster): mysql-cluster-program-options-common. (line 6) * program variables, setting: program-variables. (line 6) * program-development utilities: programs-overview. (line 256) * programs, administrative: programs-overview. (line 165) * programs, client <1>: c-api-building-clients. (line 6) * programs, client: programs-overview. (line 124) * programs, crash-me: portability. (line 6) * programs, stored <1>: stored-programs-views. (line 16) * programs, stored: sql-syntax-compound-statements. (line 16) * programs, utility: programs-overview. (line 165) * progress-frequency option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 647) * promote-attributes option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 275) * prompt command, mysql: mysql-commands. (line 180) * prompt option, mysql: mysql-command-options. (line 412) * prompts, meanings: entering-queries. (line 134) * pronunciation, MySQL: what-is-mysql. (line 107) * protocol option: connecting. (line 152) * protocol option, mysql: mysql-command-options. (line 418) * protocol option, mysqladmin: mysqladmin. (line 386) * protocol option, mysqlbinlog: mysqlbinlog. (line 419) * protocol option, mysqlcheck: mysqlcheck. (line 355) * protocol option, mysqldump: mysqldump. (line 833) * protocol option, mysqlimport: mysqlimport. (line 260) * protocol option, mysqlshow: mysqlshow. (line 189) * protocol option, mysqlslap: mysqlslap. (line 439) * protocol_version system variable: server-system-variables. (line 4174) * Proxy: mysql-proxy. (line 15) * pseudo_thread_id system variable: server-system-variables. (line 4188) * PURGE BINARY LOGS: purge-binary-logs. (line 6) * PURGE MASTER LOGS: purge-binary-logs. (line 6) * PURGE STALE SESSIONS: mysql-cluster-start-phases. (line 84) * Purging old relay logs, thread state: general-thread-states. (line 206) * Python: connector-python. (line 17) * Python, third-party driver: apis-python. (line 6) * QUARTER(): date-and-time-functions. (line 792) * queries, entering: entering-queries. (line 6) * queries, estimating performance: estimating-performance. (line 6) * queries, examples: examples. (line 18) * queries, speed of: select-optimization. (line 25) * Query Cache: query-cache. (line 13) * query cache, and ndbinfo database tables: mysql-cluster-ndbinfo. (line 183) * query cache, and partitioned tables: partitioning-limitations. (line 393) * query cache, thread states: query-cache-thread-states. (line 6) * query end, thread state: general-thread-states. (line 210) * query option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 181) * query option, mysqlslap: mysqlslap. (line 446) * query option, ndb_config: mysql-cluster-programs-ndb-config. (line 196) * Query, thread command: thread-commands. (line 90) * query_alloc_block_size system variable: server-system-variables. (line 4202) * query_cache_limit system variable: server-system-variables. (line 4238) * query_cache_min_res_unit system variable: server-system-variables. (line 4267) * query_cache_size system variable: server-system-variables. (line 4299) * query_cache_type system variable: server-system-variables. (line 4337) * query_cache_wlock_invalidate system variable: server-system-variables. (line 4380) * query_prealloc_size system variable: server-system-variables. (line 4405) * questions: mysqladmin. (line 173) * questions, answering: mailing-list-use. (line 6) * Queueing master event to the relay log, thread state: slave-io-thread-states. (line 57) * quick option, myisamchk: myisamchk-repair-options. (line 72) * quick option, mysql: mysql-command-options. (line 425) * quick option, mysqlcheck: mysqlcheck. (line 362) * quick option, mysqldump: mysqldump. (line 840) * quiet option, mysqlhotcopy: mysqlhotcopy. (line 153) * QUIT command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 194) * quit command, mysql: mysql-commands. (line 189) * Quit, thread command: thread-commands. (line 94) * quotation marks, in strings: string-literals. (line 93) * QUOTE() <1>: mysql-real-escape-string. (line 17) * QUOTE() <2>: string-functions. (line 520) * QUOTE(): string-literals. (line 141) * quote-names option, mysqldump: mysqldump. (line 847) * quoting: string-literals. (line 141) * quoting binary data: string-literals. (line 131) * quoting of identifiers: identifiers. (line 20) * quoting, column alias <1>: problems-with-alias. (line 6) * quoting, column alias: identifiers. (line 81) * RADIANS(): mathematical-functions. (line 349) * RAND(): mathematical-functions. (line 357) * rand_seed1 session variable: server-system-variables. (line 4443) * rand_seed2 session variable: server-system-variables. (line 4457) * range join type, optimizer: explain-output. (line 343) * range partitioning: partitioning-range. (line 6) * range partitions, adding and dropping: partitioning-management-range-list. (line 6) * range partitions, managing: partitioning-management-range-list. (line 6) * range_alloc_block_size system variable: server-system-variables. (line 4461) * raw option, mysql: mysql-command-options. (line 431) * raw partitions: innodb-raw-devices. (line 6) * re-creating, grant tables: mysql-install-db-problems. (line 104) * READ COMMITTED, transaction isolation level: set-transaction. (line 115) * READ UNCOMMITTED, transaction isolation level: set-transaction. (line 141) * read-from-remote-server option, mysqlbinlog: mysqlbinlog. (line 426) * read-only option, myisamchk: myisamchk-check-options. (line 55) * read-only option, mysqld: replication-options-slave. (line 512) * read_buffer_size myisamchk variable: myisamchk-general-options. (line 53) * read_buffer_size system variable: server-system-variables. (line 4495) * read_only system variable: server-system-variables. (line 4542) * read_rnd_buffer_size system variable: server-system-variables. (line 4610) * Reading event from the relay log, thread state: slave-sql-thread-states. (line 13) * Reading from net, thread state: general-thread-states. (line 215) * Reading master dump table data, thread state: slave-connection-thread-states. (line 29) * REAL data type: numeric-type-overview. (line 231) * REAL_AS_FLOAT SQL mode: server-sql-mode. (line 421) * RealtimeScheduler: mysql-cluster-ndbd-definition. (line 3105) * rebuild-indexes option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 907) * Rebuilding the index on master dump table, thread state: slave-connection-thread-states. (line 33) * ReceiveBufferMemory: mysql-cluster-tcp-definition. (line 176) * reconfiguring: compilation-problems. (line 6) * reconnect option, mysql: mysql-command-options. (line 462) * Reconnecting after a failed binlog dump request, thread state: slave-io-thread-states. (line 45) * Reconnecting after a failed master event read, thread state: slave-io-thread-states. (line 70) * reconnection, automatic: auto-reconnect. (line 6) * record-level locks, InnoDB <1>: innodb-next-key-locking. (line 6) * record-level locks, InnoDB <2>: innodb-record-level-locks. (line 6) * record-level locks, InnoDB <3>: innodb-transaction-model. (line 74) * record-level locks, InnoDB: innodb-parameters. (line 1122) * record_log_pos option, mysqlhotcopy: mysqlhotcopy. (line 157) * recover option, myisamchk: myisamchk-repair-options. (line 79) * RECOVER, XA transactions: xa-statements. (line 6) * recovery, from crash: myisam-crash-recovery. (line 6) * recovery, incremental: point-in-time-recovery. (line 11) * recovery, point in time: point-in-time-recovery. (line 11) * redo log: innodb-data-log-reconfiguration. (line 6) * RedoBuffer: mysql-cluster-ndbd-definition. (line 2627) * RedoOverCommitCounter, data nodes: mysql-cluster-ndbd-definition. (line 3922) * RedoOverCommitLimit, data nodes: mysql-cluster-ndbd-definition. (line 3942) * reducing, data size: data-size. (line 6) * ref join type, optimizer: explain-output. (line 278) * ref_or_null: is-null-optimization. (line 6) * ref_or_null join type, optimizer: explain-output. (line 304) * references: alter-table. (line 438) * referential integrity: innodb-storage-engine. (line 22) * REFERENTIAL_CONSTRAINTS, INFORMATION_SCHEMA table: referential-constraints-table. (line 6) * Refresh, thread command: thread-commands. (line 98) * REGEXP: regexp. (line 32) * REGEXP operator: regexp. (line 6) * regexp option, mysql_find_rows: mysql-find-rows. (line 35) * regexp option, mysqlhotcopy: mysqlhotcopy. (line 162) * Register Slave, thread command: thread-commands. (line 103) * Registering slave on master, thread state: slave-io-thread-states. (line 25) * regular expression syntax: regexp. (line 6) * rehash command, mysql: mysql-commands. (line 193) * relational databases, defined: what-is-mysql. (line 54) * relative option, mysqladmin: mysqladmin. (line 393) * relay-log option, mysqld: replication-options-slave. (line 534) * relay-log-index option, mysqld: replication-options-slave. (line 583) * relay-log-info-file option, mysqld: replication-options-slave. (line 618) * relay-log-purge option, mysqld: replication-options-slave. (line 636) * relay-log-space-limit option, mysqld: replication-options-slave. (line 657) * relay_log system variable: replication-options-slave. (line 1408) * relay_log_index system variable: replication-options-slave. (line 1426) * relay_log_info_file system variable: replication-options-slave. (line 1446) * relay_log_purge system variable: server-system-variables. (line 4644) * relay_log_space_limit system variable: server-system-variables. (line 4663) * release notes: news. (line 6) * release numbers: which-version. (line 18) * RELEASE SAVEPOINT: savepoint. (line 6) * RELEASE_LOCK(): miscellaneous-functions. (line 200) * releases, naming scheme: choosing-version. (line 56) * releases, testing: choosing-version. (line 118) * releases, updating: many-versions. (line 6) * relnotes option, mysqlaccess: mysqlaccess. (line 126) * reload option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 406) * remote administration (MySQL Cluster), and security issues: mysql-cluster-security-networking-issues. (line 193) * remove option (ndb_mgmd): mysql-cluster-programs-ndb-mgmd. (line 641) * remove option (ndbd): mysql-cluster-programs-ndbd. (line 366) * remove option (ndbmtd): mysql-cluster-programs-ndbd. (line 366) * remove option, mysqld: server-options. (line 1718) * remove option, mysqlmanager: instance-manager-command-options. (line 200) * Removing duplicates, thread state: general-thread-states. (line 219) * removing tmp table, thread state: general-thread-states. (line 226) * RENAME DATABASE: rename-database. (line 6) * rename result table, thread state: general-thread-states. (line 236) * RENAME TABLE: rename-table. (line 6) * RENAME USER: rename-user. (line 6) * rename, thread state: general-thread-states. (line 232) * renaming user accounts: rename-user. (line 6) * Reopen tables, thread state: general-thread-states. (line 242) * Repair by sorting, thread state: general-thread-states. (line 248) * Repair done, thread state: general-thread-states. (line 252) * repair option, mysqlcheck: mysqlcheck. (line 371) * repair options, myisamchk: myisamchk-repair-options. (line 6) * REPAIR TABLE: repair-table. (line 6) * REPAIR TABLE, and partitioning: partitioning-maintenance. (line 6) * REPAIR TABLE, and replication <1>: replication-features-repair-table. (line 6) * REPAIR TABLE, and replication: repair-table. (line 135) * Repair with keycache, thread state: general-thread-states. (line 257) * repair, tables: mysqlcheck. (line 6) * repairing, tables: myisam-repair. (line 6) * REPEAT: repeat. (line 6) * REPEAT(): string-functions. (line 539) * REPEAT, labels: statement-labels. (line 6) * REPEATABLE READ, transaction isolation level: set-transaction. (line 93) * repertoire, character set: charset-repertoire. (line 6) * REPLACE: replace. (line 6) * replace: programs-overview. (line 284) * replace option, mysqldump: mysqldump. (line 856) * replace option, mysqlimport: mysqlimport. (line 267) * replace utility: replace-utility. (line 6) * REPLACE(): string-functions. (line 548) * replicas (MySQL Cluster): mysql-cluster-nodes-groups. (line 6) * replicate-do-db option, mysqld: replication-options-slave. (line 702) * replicate-do-table option, mysqld: replication-options-slave. (line 888) * replicate-ignore-db option, mysqld: replication-options-slave. (line 818) * replicate-ignore-table option, mysqld: replication-options-slave. (line 910) * replicate-rewrite-db option, mysqld: replication-options-slave. (line 933) * replicate-same-server-id option, mysqld: replication-options-slave. (line 982) * replicate-wild-do-table option, mysqld: replication-options-slave. (line 1006) * replicate-wild-ignore-table option, mysqld: replication-options-slave. (line 1053) * replication: replication. (line 13) * replication filtering options, and case sensitivity: replication-rules. (line 56) * replication formats, compared: replication-sbr-rbr. (line 6) * replication implementation: replication-implementation. (line 12) * replication limitations: replication-features. (line 45) * replication master, thread states: master-thread-states. (line 6) * replication masters, statements: replication-master-sql. (line 12) * replication options: replication-features. (line 45) * replication slave, thread states <1>: slave-connection-thread-states. (line 6) * replication slave, thread states <2>: slave-sql-thread-states. (line 6) * replication slave, thread states: slave-io-thread-states. (line 6) * replication slaves, statements: replication-slave-sql. (line 17) * replication, and AUTO_INCREMENT: replication-features-auto-increment. (line 6) * replication, and character sets: replication-features-charset. (line 6) * replication, and CREATE ... IF NOT EXISTS: replication-features-create-if-not-exists. (line 6) * replication, and CREATE TABLE ... SELECT: replication-features-create-select. (line 6) * replication, and DATA DIRECTORY: replication-features-directory. (line 6) * replication, and DROP ... IF EXISTS: replication-features-drop-if-exists. (line 6) * replication, and errors on slave: replication-features-slaveerrors. (line 6) * replication, and floating-point values: replication-features-floatvalues. (line 6) * replication, and FLUSH: replication-features-flush. (line 6) * replication, and functions: replication-features-functions. (line 6) * replication, and INDEX DIRECTORY: replication-features-directory. (line 6) * replication, and invoked features: replication-features-invoked. (line 6) * replication, and LAST_INSERT_ID(): replication-features-auto-increment. (line 6) * replication, and LIMIT: replication-features-limit. (line 6) * replication, and LOAD DATA: replication-features-load-data. (line 6) * replication, and max_allowed_packet: replication-features-max-allowed-packet. (line 6) * replication, and MEMORY tables: replication-features-memory. (line 6) * replication, and mysql (system) database: replication-features-mysqldb. (line 6) * replication, and partial updates: replication-features-slaveerrors. (line 6) * replication, and partitioning: replication-features-sql-mode. (line 6) * replication, and privileges: replication-features-mysqldb. (line 6) * replication, and query optimizer: replication-features-optimizer. (line 6) * replication, and REPAIR TABLE statement <1>: replication-features-repair-table. (line 6) * replication, and REPAIR TABLE statement: repair-table. (line 135) * replication, and reserved words: replication-features-reserved-words. (line 6) * replication, and scheduled events: replication-features-invoked. (line 6) * replication, and slow query log: replication-features-logging. (line 6) * replication, and SQL mode: replication-features-sql-mode. (line 6) * replication, and stored routines: replication-features-invoked. (line 6) * replication, and temporary tables: replication-features-temptables. (line 6) * replication, and time zones: replication-features-timezone. (line 6) * replication, and TIMESTAMP <1>: replication-features-timestamp. (line 6) * replication, and TIMESTAMP <2>: replication-features-auto-increment. (line 6) * replication, and TIMESTAMP: upgrading-from-previous-series. (line 758) * replication, and transactions <1>: replication-features-transactions. (line 6) * replication, and transactions: replication-features-timeout. (line 6) * replication, and triggers <1>: replication-features-triggers. (line 6) * replication, and triggers: replication-features-invoked. (line 6) * replication, and TRUNCATE TABLE: replication-features-truncate. (line 6) * replication, and variables: replication-features-variables. (line 6) * replication, and views: replication-features-views. (line 6) * replication, asynchronous: mysql-cluster-replication. (line 20) * replication, attribute demotion: replication-features-different-data-types. (line 6) * replication, attribute promotion: replication-features-different-data-types. (line 6) * replication, between MySQL server versions <1>: replication-features-timestamp. (line 6) * replication, between MySQL server versions: upgrading-from-previous-series. (line 758) * replication, BLACKHOLE: replication-features-blackhole. (line 6) * replication, circular: mysql-cluster-replication-issues. (line 74) * replication, crashes: replication-features-shutdowns. (line 6) * replication, in MySQL Cluster: mysql-cluster-replication. (line 20) * replication, row-based vs statement-based: replication-sbr-rbr. (line 6) * replication, safe and unsafe statements: replication-rbr-safe-unsafe. (line 6) * replication, shutdown and restart <1>: replication-features-temptables. (line 6) * replication, shutdown and restart: replication-features-shutdowns. (line 6) * replication, statements incompatible with STATEMENT format: replication-sbr-rbr. (line 38) * replication, timeouts: replication-features-timeout. (line 6) * replication, with differing tables on master and slave: replication-features-differing-tables. (line 11) * replication, with ZFS: ha-zfs-replication. (line 12) * ReplicationManager class: connector-net-ref-replication-replicationmanager. (line 10) * ReplicationRoundRobinServerGroup class: connector-net-ref-replication-replicationroundrobinservergroup. (line 10) * ReplicationServer class: connector-net-ref-replication-replicationserver. (line 10) * ReplicationServerGroup class: connector-net-ref-replication-replicationservergroup. (line 10) * REPORT command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 140) * report-host option, mysqld: replication-options-slave. (line 1079) * report-password option, mysqld: replication-options-slave. (line 1104) * report-port option, mysqld: replication-options-slave. (line 1129) * report-user option, mysqld: replication-options-slave. (line 1153) * report_host system variable: server-system-variables. (line 4691) * report_password system variable: server-system-variables. (line 4709) * report_port system variable: server-system-variables. (line 4728) * report_user system variable: server-system-variables. (line 4749) * reporting, bugs <1>: bug-reports. (line 6) * reporting, bugs: introduction. (line 69) * reporting, Connector/Net problems: connector-net-support. (line 11) * reporting, Connector/ODBC problems: connector-odbc-support. (line 12) * reporting, errors: bug-reports. (line 6) * reporting, problems: introduction. (line 69) * Requesting binlog dump, thread state: slave-io-thread-states. (line 30) * REQUIRE GRANT option: grant. (line 494) * reschedule, thread state: delayed-insert-thread-states. (line 76) * reserved words: reserved-words. (line 6) * reserved words, and replication: replication-features-reserved-words. (line 6) * ReservedSendBufferMemory: mysql-cluster-ndbd-definition. (line 3879) * RESET MASTER: reset-master. (line 6) * RESET SLAVE: reset-slave. (line 6) * Reset stmt, thread command: thread-commands. (line 107) * reset-slave.pl: mysql-cluster-replication-auto-sync. (line 11) * resetmaster option, mysqlhotcopy: mysqlhotcopy. (line 167) * resetslave option, mysqlhotcopy: mysqlhotcopy. (line 171) * resolve_stack_dump <1>: resolve-stack-dump. (line 6) * resolve_stack_dump: programs-overview. (line 272) * resolve_stack_dump, help option: resolve-stack-dump. (line 21) * resolve_stack_dump, numeric-dump-file option: resolve-stack-dump. (line 25) * resolve_stack_dump, symbols-file option: resolve-stack-dump. (line 29) * resolve_stack_dump, version option: resolve-stack-dump. (line 33) * resolveip <1>: resolveip. (line 6) * resolveip: programs-overview. (line 289) * resolveip, help option: resolveip. (line 15) * resolveip, silent option: resolveip. (line 19) * resolveip, version option: resolveip. (line 23) * resource limits, user accounts <1>: grant. (line 462) * resource limits, user accounts <2>: user-resources. (line 6) * resource limits, user accounts: server-system-variables. (line 3324) * resources, ndbinfo table: mysql-cluster-ndbinfo-resources. (line 6) * RESTART command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 101) * restarting, the server: unix-postinstallation. (line 263) * RestartOnErrorInsert: mysql-cluster-ndbd-definition. (line 1666) * RESTORE TABLE: restore-table. (line 6) * restore-privilege-tables option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 382) * restore_connect option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 202) * restore_data option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 368) * restore_epoch option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 360) * restore_meta option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 374) * restore_nodeid option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 224) * restore_skip-table-check option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 238) * restoring backups, in MySQL Cluster: mysql-cluster-programs-ndb-restore. (line 6) * restoring from backup, in MySQL Cluster replication: mysql-cluster-replication-backups. (line 11) * restrictions, character sets: charset-restrictions. (line 6) * restrictions, events: stored-program-restrictions. (line 6) * restrictions, InnoDB: innodb-restrictions. (line 6) * restrictions, server-side cursors: cursor-restrictions. (line 6) * restrictions, stored routines: stored-program-restrictions. (line 6) * restrictions, subqueries: subquery-restrictions. (line 6) * restrictions, triggers: stored-program-restrictions. (line 6) * restrictions, views: view-restrictions. (line 6) * restrictions, XA transactions: xa-restrictions. (line 6) * result-file option, mysqlbinlog: mysqlbinlog. (line 437) * result-file option, mysqldump: mysqldump. (line 862) * retries option, ndb_desc: mysql-cluster-programs-ndb-desc. (line 315) * retrieving, data from tables: retrieving-data. (line 18) * RETURN: return. (line 6) * return (\r) <1>: load-data. (line 433) * return (\r): string-literals. (line 73) * return values, UDFs: udf-return-values. (line 6) * REVERSE(): string-functions. (line 559) * REVOKE: revoke. (line 6) * revoking, privileges: revoke. (line 6) * rewrite-database option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 954) * rhost option, mysqlaccess: mysqlaccess. (line 130) * RIGHT JOIN: join. (line 6) * RIGHT OUTER JOIN: join. (line 6) * RIGHT(): string-functions. (line 568) * RLIKE: regexp. (line 32) * ROLLBACK <1>: commit. (line 6) * ROLLBACK: ansi-diff-transactions. (line 6) * rollback option, mysqlaccess: mysqlaccess. (line 134) * ROLLBACK TO SAVEPOINT: savepoint. (line 6) * ROLLBACK, XA transactions: xa-statements. (line 6) * Rolling back, thread state: general-thread-states. (line 262) * rolling restart (MySQL Cluster): mysql-cluster-rolling-restart. (line 6) * ROLLUP: group-by-modifiers. (line 6) * root password: default-privileges. (line 6) * root user: security-guidelines. (line 6) * root user, password resetting: resetting-permissions. (line 12) * ROUND(): mathematical-functions. (line 455) * rounding: precision-math. (line 14) * rounding errors: numeric-type-overview. (line 137) * routines option, mysqldump: mysqldump. (line 870) * ROUTINES, INFORMATION_SCHEMA table: routines-table. (line 6) * ROW: row-subqueries. (line 6) * row size, maximum: column-count-limit. (line 6) * row subqueries: row-subqueries. (line 6) * row-based replication, advantages: replication-sbr-rbr. (line 135) * row-based replication, disadvantages: replication-sbr-rbr. (line 178) * row-level locking: internal-locking. (line 6) * ROW_COUNT(): information-functions. (line 499) * rowid option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 121) * rows option, mysql_find_rows: mysql-find-rows. (line 39) * rows option, ndb_config: mysql-cluster-programs-ndb-config. (line 362) * rows, counting: counting-rows. (line 6) * rows, deleting: deleting-from-related-tables. (line 6) * rows, locking: ansi-diff-transactions. (line 166) * rows, matching problems: no-matching-rows. (line 6) * rows, selecting: selecting-rows. (line 6) * rows, sorting: sorting-rows. (line 6) * RPAD(): string-functions. (line 578) * RPM file: linux-installation-rpm. (line 6) * rpm option, mysql_install_db: mysql-install-db. (line 70) * RPM Package Manager: linux-installation-rpm. (line 6) * RTRIM(): string-functions. (line 591) * Ruby API: apis-ruby. (line 11) * run-as-service option, mysqlmanager: instance-manager-command-options. (line 206) * running configure after prior invocation: compilation-problems. (line 14) * running, ANSI mode: ansi-mode. (line 6) * running, batch mode: batch-mode. (line 6) * running, multiple servers: multiple-servers. (line 13) * running, queries: entering-queries. (line 6) * safe statement (replication), defined: replication-rbr-safe-unsafe. (line 6) * safe-mode option, mysqld: server-options. (line 1729) * safe-recover option, myisamchk: myisamchk-repair-options. (line 92) * safe-show-database option, mysqld: server-options. (line 1740) * safe-updates option: safe-updates. (line 6) * safe-updates option, mysql: mysql-command-options. (line 469) * safe-user-create option, mysqld: server-options. (line 1762) * Sakila: history. (line 6) * same value wins (conflict resolution): mysql-cluster-replication-conflict-resolution. (line 261) * SAVEPOINT: savepoint. (line 6) * Saving state, thread state: general-thread-states. (line 266) * scale, arithmetic: precision-math. (line 14) * scale, numeric: data-types. (line 39) * SchedulerExecutionTimer: mysql-cluster-ndbd-definition. (line 3123) * SchedulerSpinTimer: mysql-cluster-ndbd-definition. (line 3143) * SCHEMA(): information-functions. (line 556) * schema, altering: alter-database. (line 6) * schema, creating: create-database. (line 6) * schema, deleting: drop-database. (line 6) * SCHEMA_PRIVILEGES, INFORMATION_SCHEMA table: schema-privileges-table. (line 6) * SCHEMATA, INFORMATION_SCHEMA table: schemata-table. (line 6) * SCI (Scalable Coherent Interface) <1>: mysql-cluster-sci-sockets. (line 6) * SCI (Scalable Coherent Interface): mysql-cluster-sci-definition. (line 6) * script files: batch-mode. (line 6) * scripts <1>: mysqld-multi. (line 6) * scripts: mysqld-safe. (line 6) * scripts, mysql_install_db: mysql-install-db-problems. (line 6) * scripts, SQL: mysql. (line 15) * Searching rows for update, thread state: general-thread-states. (line 273) * searching, and case sensitivity: case-sensitivity. (line 6) * searching, full-text: fulltext-search. (line 16) * searching, MySQL Web pages: bug-reports. (line 6) * searching, two keys: searching-on-two-keys. (line 6) * SEC_TO_TIME(): date-and-time-functions. (line 806) * SECOND(): date-and-time-functions. (line 799) * secondary index, InnoDB: innodb-index-types. (line 6) * secure-auth option, mysql: mysql-command-options. (line 477) * secure-auth option, mysqld: server-options. (line 1787) * secure-file-priv option, mysqld: server-options. (line 1815) * secure_auth system variable: server-system-variables. (line 4767) * secure_file_priv system variable: server-system-variables. (line 4793) * securing a MySQL Cluster: mysql-cluster-security-mysql-security-procedures. (line 6) * security system: privilege-system. (line 16) * security, against attackers: security-against-attack. (line 6) * security, and malicious SQL statements: mysql-cluster-security-mysql-privileges. (line 86) * security, and NDB utilities: mysql-cluster-security-mysql-security-procedures. (line 76) * SELECT INTO TABLE: ansi-diff-select-into-table. (line 6) * SELECT speed: select-speed. (line 6) * SELECT, INTO: select-into. (line 6) * SELECT, LIMIT: select. (line 13) * SELECT, optimizing <1>: explain. (line 6) * SELECT, optimizing: using-explain. (line 6) * SELECT, Query Cache: query-cache. (line 13) * select_limit variable: mysql-command-options. (line 634) * selecting, databases: creating-database. (line 6) * semi-consistent read, InnoDB: innodb-parameters. (line 1122) * SendBufferMemory: mysql-cluster-tcp-definition. (line 106) * Sending binlog event to slave, thread state: master-thread-states. (line 11) * sending cached result to client, thread state: query-cache-thread-states. (line 24) * SendLimit: mysql-cluster-sci-definition. (line 142) * SendSignalId <1>: mysql-cluster-sci-definition. (line 155) * SendSignalId <2>: mysql-cluster-shm-definition. (line 99) * SendSignalId: mysql-cluster-tcp-definition. (line 138) * SEQUENCE: example-auto-increment. (line 6) * sequence emulation: information-functions. (line 461) * sequences: example-auto-increment. (line 6) * SERIAL: numeric-type-overview. (line 6) * SERIAL DEFAULT VALUE: data-type-defaults. (line 83) * SERIALIZABLE, transaction isolation level: set-transaction. (line 149) * server administration: mysqladmin. (line 6) * server plugins: server-plugins. (line 11) * server variables <1>: show-variables. (line 6) * server variables: server-system-variables. (line 6) * server, connecting <1>: connecting. (line 6) * server, connecting: connecting-disconnecting. (line 6) * server, debugging: debugging-server. (line 16) * server, disconnecting: connecting-disconnecting. (line 6) * server, logs: server-logs. (line 15) * server, restart: unix-postinstallation. (line 263) * server, shutdown: unix-postinstallation. (line 255) * server, signal handling: server-signal-response. (line 6) * server, starting: unix-postinstallation. (line 54) * server, starting and stopping: automatic-start. (line 6) * server, starting problems: starting-server. (line 6) * server-id option, mysqlbinlog: mysqlbinlog. (line 441) * server-id option, mysqld: replication-options. (line 21) * server-id-bits option, mysqlbinlog: mysqlbinlog. (line 446) * server-id-bits option, mysqld: mysql-cluster-program-options-mysqld. (line 501) * server-side cursor, restrictions: cursor-restrictions. (line 6) * server_id system variable: server-system-variables. (line 4817) * server_id_bits system variable: mysql-cluster-system-variables. (line 1148) * server_operations, ndbinfo table: mysql-cluster-ndbinfo-server-operations. (line 6) * server_transactions, ndbinfo table: mysql-cluster-ndbinfo-server-transactions. (line 6) * ServerPort: mysql-cluster-ndbd-definition. (line 135) * servers, multiple: multiple-servers. (line 13) * service-startup-timeout option, mysql.server: mysql-server. (line 49) * servlet: connector-j-usagenotes-glassfish-config-servlet. (line 6) * session variable, autocommit: server-system-variables. (line 590) * session variable, big_tables: server-system-variables. (line 709) * session variable, error_count: server-system-variables. (line 1497) * session variable, foreign_key_checks: server-system-variables. (line 1603) * session variable, identity: server-system-variables. (line 2004) * session variable, insert_id: server-system-variables. (line 2087) * session variable, last_insert_id: server-system-variables. (line 2455) * session variable, profiling: server-system-variables. (line 4158) * session variable, profiling_history_size: server-system-variables. (line 4166) * session variable, rand_seed1: server-system-variables. (line 4443) * session variable, rand_seed2: server-system-variables. (line 4457) * session variable, sql_auto_is_null: server-system-variables. (line 5117) * session variable, sql_big_selects: server-system-variables. (line 5150) * session variable, sql_buffer_result: server-system-variables. (line 5174) * session variable, sql_log_bin: server-system-variables. (line 5193) * session variable, sql_log_off: server-system-variables. (line 5209) * session variable, sql_log_update: server-system-variables. (line 5226) * session variable, sql_notes: server-system-variables. (line 5293) * session variable, sql_quote_show_create: server-system-variables. (line 5303) * session variable, sql_safe_updates: server-system-variables. (line 5312) * session variable, sql_warnings: server-system-variables. (line 5345) * session variable, timestamp: server-system-variables. (line 5808) * session variable, transaction_allow_batching: mysql-cluster-system-variables. (line 939) * session variable, unique_checks: server-system-variables. (line 6009) * session variable, warning_count: server-system-variables. (line 6155) * session variables, and replication: replication-features-variables. (line 6) * SESSION_STATUS, INFORMATION_SCHEMA table: status-table. (line 6) * SESSION_USER(): information-functions. (line 560) * SESSION_VARIABLES, INFORMATION_SCHEMA table: variables-table. (line 6) * SET: set-statement. (line 6) * SET data type <1>: set. (line 6) * SET data type: string-type-overview. (line 257) * SET GLOBAL sql_slave_skip_counter: set-global-sql-slave-skip-counter. (line 6) * SET OPTION: set-statement. (line 6) * Set option, thread command: thread-commands. (line 111) * SET PASSWORD: set-password. (line 6) * SET PASSWORD statement: assigning-passwords. (line 6) * SET sql_log_bin: set-sql-log-bin. (line 6) * SET statement, assignment operator: assignment-operators. (line 70) * SET TRANSACTION: set-transaction. (line 6) * SET, CHARACTER SET <1>: set-statement. (line 173) * SET, CHARACTER SET: charset-connection. (line 6) * SET, NAMES <1>: set-statement. (line 189) * SET, NAMES <2>: charset-applications. (line 6) * SET, NAMES: charset-connection. (line 6) * SET, ONE_SHOT: set-statement. (line 205) * SET, size: storage-requirements. (line 250) * set-auto-increment[ option, myisamchk: myisamchk-other-options. (line 28) * set-character-set option, myisamchk: myisamchk-repair-options. (line 105) * set-charset option, mysqlbinlog: mysqlbinlog. (line 460) * set-charset option, mysqldump: mysqldump. (line 900) * set-collation option, myisamchk: myisamchk-repair-options. (line 110) * setting passwords: set-password. (line 6) * setting program variables: program-variables. (line 6) * setting, passwords: assigning-passwords. (line 6) * setup, postinstallation: postinstallation. (line 11) * setup, thread state: general-thread-states. (line 287) * SHA(): encryption-functions. (line 376) * SHA1(): encryption-functions. (line 376) * shared memory transporter: mysql-cluster-shm-definition. (line 6) * shared-memory option, mysqld: server-options. (line 1838) * shared-memory-base-name option: connecting. (line 186) * shared-memory-base-name option, mysqld: server-options. (line 1851) * shared-memory-base-name option, mysqlslap: mysqlslap. (line 408) * shared_memory system variable: server-system-variables. (line 4841) * shared_memory_base_name system variable: server-system-variables. (line 4854) * SharedBufferSize: mysql-cluster-sci-definition. (line 123) * SharedGlobalMemory: mysql-cluster-ndbd-definition. (line 3461) * shell syntax: manual-conventions. (line 120) * ShmKey: mysql-cluster-shm-definition. (line 72) * ShmSize: mysql-cluster-shm-definition. (line 85) * short-form option, mysqlbinlog: mysqlbinlog. (line 466) * SHOW AUTHORS <1>: show-authors. (line 6) * SHOW AUTHORS: show. (line 51) * SHOW BINARY LOGS <1>: show-binary-logs. (line 6) * SHOW BINARY LOGS: show. (line 51) * SHOW BINLOG EVENTS <1>: show-binlog-events. (line 6) * SHOW BINLOG EVENTS: show. (line 51) * SHOW CHARACTER SET <1>: show-character-set. (line 6) * SHOW CHARACTER SET: show. (line 51) * SHOW COLLATION <1>: show-collation. (line 6) * SHOW COLLATION: show. (line 51) * SHOW COLUMNS <1>: show-columns. (line 6) * SHOW COLUMNS: show. (line 51) * SHOW command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 38) * SHOW CONTRIBUTORS <1>: show-contributors. (line 6) * SHOW CONTRIBUTORS: show. (line 51) * SHOW CREATE DATABASE <1>: show-create-database. (line 6) * SHOW CREATE DATABASE: show. (line 51) * SHOW CREATE EVENT: show. (line 51) * SHOW CREATE FUNCTION <1>: show-create-function. (line 6) * SHOW CREATE FUNCTION: show. (line 51) * SHOW CREATE PROCEDURE <1>: show-create-procedure. (line 6) * SHOW CREATE PROCEDURE: show. (line 51) * SHOW CREATE SCHEMA <1>: show-create-database. (line 6) * SHOW CREATE SCHEMA: show. (line 51) * SHOW CREATE TABLE <1>: show-create-table. (line 6) * SHOW CREATE TABLE: show. (line 51) * SHOW CREATE TRIGGER <1>: show-create-trigger. (line 6) * SHOW CREATE TRIGGER: show. (line 51) * SHOW CREATE VIEW <1>: show-create-view. (line 6) * SHOW CREATE VIEW: show. (line 51) * SHOW DATABASES <1>: show-databases. (line 6) * SHOW DATABASES: show. (line 51) * SHOW ENGINE <1>: show-engine. (line 6) * SHOW ENGINE: show. (line 51) * SHOW ENGINE INNODB STATUS: show-engine. (line 6) * SHOW ENGINE NDB STATUS <1>: mysql-cluster-sql-statements. (line 10) * SHOW ENGINE NDB STATUS: show-engine. (line 6) * SHOW ENGINE NDBCLUSTER STATUS <1>: mysql-cluster-sql-statements. (line 10) * SHOW ENGINE NDBCLUSTER STATUS: show-engine. (line 6) * SHOW ENGINE, and MySQL Cluster: mysql-cluster-sql-statements. (line 10) * SHOW ENGINES <1>: show-engines. (line 6) * SHOW ENGINES: show. (line 51) * SHOW ENGINES, and MySQL Cluster: mysql-cluster-sql-statements. (line 20) * SHOW ERRORS <1>: show-errors. (line 6) * SHOW ERRORS: show. (line 51) * SHOW ERRORS, and MySQL Cluster: faqs-mysql-cluster. (line 6) * SHOW EVENTS <1>: show-events. (line 6) * SHOW EVENTS: show. (line 51) * SHOW extensions: extended-show. (line 6) * SHOW FIELDS <1>: show-columns. (line 101) * SHOW FIELDS: show. (line 51) * SHOW FUNCTION CODE <1>: show-function-code. (line 6) * SHOW FUNCTION CODE: show. (line 51) * SHOW FUNCTION STATUS <1>: show-function-status. (line 6) * SHOW FUNCTION STATUS: show. (line 51) * SHOW GRANTS <1>: show-grants. (line 6) * SHOW GRANTS: show. (line 51) * SHOW INDEX <1>: show-index. (line 6) * SHOW INDEX: show. (line 51) * SHOW INNODB STATUS: show. (line 51) * SHOW KEYS <1>: show-index. (line 6) * SHOW KEYS: show. (line 51) * SHOW MASTER LOGS <1>: show-binary-logs. (line 6) * SHOW MASTER LOGS: show. (line 51) * SHOW MASTER STATUS <1>: show-master-status. (line 6) * SHOW MASTER STATUS: show. (line 51) * SHOW OPEN TABLES <1>: show-open-tables. (line 6) * SHOW OPEN TABLES: show. (line 51) * SHOW PLUGINS <1>: show-plugins. (line 6) * SHOW PLUGINS: show. (line 51) * SHOW PRIVILEGES <1>: show-privileges. (line 6) * SHOW PRIVILEGES: show. (line 51) * SHOW PROCEDURE CODE <1>: show-procedure-code. (line 6) * SHOW PROCEDURE CODE: show. (line 51) * SHOW PROCEDURE STATUS <1>: show-procedure-status. (line 6) * SHOW PROCEDURE STATUS: show. (line 51) * SHOW PROCESSLIST <1>: show-processlist. (line 6) * SHOW PROCESSLIST: show. (line 51) * SHOW PROFILE <1>: show-profile. (line 6) * SHOW PROFILE: show. (line 51) * SHOW PROFILES <1>: show-profiles. (line 6) * SHOW PROFILES <2>: show-profile. (line 6) * SHOW PROFILES: show. (line 51) * SHOW SCHEDULER STATUS <1>: events-status-info. (line 6) * SHOW SCHEDULER STATUS: show. (line 51) * SHOW SCHEMAS <1>: show-databases. (line 6) * SHOW SCHEMAS: show. (line 51) * SHOW SLAVE HOSTS <1>: show-slave-hosts. (line 6) * SHOW SLAVE HOSTS: show. (line 51) * SHOW SLAVE STATUS <1>: show-slave-status. (line 6) * SHOW SLAVE STATUS: show. (line 51) * SHOW STATUS: show. (line 51) * SHOW STATUS, and MySQL Cluster: mysql-cluster-sql-statements. (line 125) * SHOW STORAGE ENGINES: show-engines. (line 6) * SHOW TABLE STATUS: show. (line 51) * SHOW TABLE TYPES: show-engines. (line 6) * SHOW TABLES <1>: show-tables. (line 6) * SHOW TABLES: show. (line 51) * SHOW TRIGGERS <1>: show-triggers. (line 6) * SHOW TRIGGERS: show. (line 51) * SHOW VARIABLES: show. (line 51) * SHOW VARIABLES, and MySQL Cluster: mysql-cluster-sql-statements. (line 58) * SHOW WARNINGS <1>: show-warnings. (line 6) * SHOW WARNINGS: show. (line 51) * SHOW WARNINGS, and MySQL Cluster: faqs-mysql-cluster. (line 6) * SHOW with WHERE <1>: extended-show. (line 6) * SHOW with WHERE: information-schema. (line 36) * SHOW, in MySQL Cluster management client: mysql-cluster-quick. (line 145) * show-slave-auth-info option, mysqld: replication-options-slave. (line 1178) * show-table-type option, mysqlshow: mysqlshow. (line 196) * show-temp-status option, ndb_show_tables: mysql-cluster-programs-ndb-show-tables. (line 65) * show-warnings option, mysql: mysql-command-options. (line 483) * showing, database information: mysqlshow. (line 6) * SHUTDOWN command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 200) * Shutdown, thread command: thread-commands. (line 116) * shutdown_timeout variable: mysqladmin. (line 452) * shutting down, the server: unix-postinstallation. (line 255) * Shutting down, thread state: mysql-cluster-thread-states. (line 18) * sigint-ignore option, mysql: mysql-command-options. (line 488) * SIGN(): mathematical-functions. (line 519) * signals, server response: server-signal-response. (line 6) * SigNum: mysql-cluster-shm-definition. (line 131) * silent column changes: silent-column-changes. (line 6) * silent option, myisamchk: myisamchk-general-options. (line 27) * silent option, myisampack: myisampack. (line 93) * silent option, mysql: mysql-command-options. (line 493) * silent option, mysqladmin: mysqladmin. (line 399) * silent option, mysqlcheck: mysqlcheck. (line 376) * silent option, mysqld_multi: mysqld-multi. (line 155) * silent option, mysqlimport: mysqlimport. (line 277) * silent option, mysqlslap: mysqlslap. (line 451) * silent option, perror: perror. (line 48) * silent option, resolveip: resolveip. (line 19) * SIN(): mathematical-functions. (line 531) * single quote (\'): string-literals. (line 69) * single user mode (MySQL Cluster) <1>: mysql-cluster-single-user-mode. (line 6) * single user mode (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 176) * single user mode (MySQL Cluster), and ndb_restore: mysql-cluster-programs-ndb-restore. (line 19) * single-transaction option, mysqldump: mysqldump. (line 906) * single-user option, ndb_waiter: mysql-cluster-programs-ndb-waiter. (line 96) * size of tables: table-size-limit. (line 6) * sizes, display: data-types. (line 33) * skip-broken-objects option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 920) * skip-column-names option, mysql: mysql-command-options. (line 502) * skip-comments option, mysqldump: mysqldump. (line 945) * skip-concurrent-insert option, mysqld: server-options. (line 1865) * skip-event-scheduler option, mysqld: server-options. (line 1871) * skip-grant-tables option, mysqld: server-options. (line 1885) * skip-host-cache option, mysqld: server-options. (line 1909) * skip-innodb option, mysqld <1>: innodb-parameters. (line 207) * skip-innodb option, mysqld: server-options. (line 1915) * skip-kill-mysqld option, mysqld_safe: mysqld-safe. (line 220) * skip-line-numbers option, mysql: mysql-command-options. (line 506) * skip-merge option, mysqld: server-options. (line 1922) * skip-name-resolve option, mysql_install_db: mysql-install-db. (line 76) * skip-name-resolve option, mysqld: server-options. (line 1927) * skip-ndbcluster option, mysqld: mysql-cluster-program-options-mysqld. (line 549) * skip-networking option, mysqld: server-options. (line 1934) * skip-opt option, mysqldump: mysqldump. (line 949) * skip-partition option, mysqld: server-options. (line 1942) * skip-safemalloc option, mysqld: server-options. (line 2009) * skip-show-database option, mysqld: server-options. (line 2023) * skip-slave-start option, mysqld: replication-options-slave. (line 1195) * skip-ssl option: ssl-options. (line 38) * skip-stack-trace option, mysqld: server-options. (line 2039) * skip-symbolic-links option, mysqld: server-options. (line 1985) * skip-syslog option, mysqld_safe: mysqld-safe. (line 230) * skip-thread-priority option, mysqld: server-options. (line 2052) * skip-unknown-objects option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 937) * skip-use-db option, mysql_find_rows: mysql-find-rows. (line 43) * skip_external_locking system variable: server-system-variables. (line 4869) * skip_name_resolve system variable: server-system-variables. (line 4898) * skip_networking system variable: server-system-variables. (line 4923) * skip_show_database system variable: server-system-variables. (line 4942) * slave option, mysqlslap: mysqlslap. (line 455) * slave-load-tmpdir option, mysqld: replication-options-slave. (line 1231) * slave-max-allowed-packet (mysqld): replication-options-slave. (line 311) * slave-net-timeout option, mysqld: replication-options-slave. (line 1268) * slave-skip-errors option, mysqld: replication-options-slave. (line 1295) * slave_allow_batching: mysql-cluster-replication-starting. (line 90) * slave_compressed_protocol option, mysqld: replication-options-slave. (line 1211) * slave_compressed_protocol system variable: replication-options-slave. (line 1470) * slave_exec_mode system variable: replication-options-slave. (line 1489) * slave_load_tmpdir system variable: replication-options-slave. (line 1559) * slave_max_allowed_packet system variable: replication-options-slave. (line 1526) * slave_net_timeout system variable: replication-options-slave. (line 1579) * slave_skip_errors system variable: replication-options-slave. (line 1601) * slave_transaction_retries system variable: replication-options-slave. (line 1631) * slave_type_conversions system variable: replication-options-slave. (line 1667) * sleep option, mysqladmin: mysqladmin. (line 403) * SLEEP(): miscellaneous-functions. (line 216) * Sleep, thread command: thread-commands. (line 120) * slow queries: mysqladmin. (line 178) * slow query log: slow-query-log. (line 6) * slow query log, and replication: replication-features-logging. (line 6) * slow-query-log option, mysqld: server-options. (line 2073) * slow_launch_time system variable: server-system-variables. (line 4968) * slow_query_log system variable: server-system-variables. (line 4987) * slow_query_log_file system variable: server-system-variables. (line 5017) * SMALLINT data type: numeric-type-overview. (line 106) * SNAPSHOTEND (START BACKUP command): mysql-cluster-backup-using-management-client. (line 64) * SNAPSHOTSTART (START BACKUP command): mysql-cluster-backup-using-management-client. (line 64) * socket location, changing: source-configuration-options. (line 377) * socket option: connecting. (line 195) * socket option, mysql: mysql-command-options. (line 511) * socket option, mysql_config: mysql-config. (line 50) * socket option, mysql_convert_table_format: mysql-convert-table-format. (line 50) * socket option, mysql_setpermission: mysql-setpermission. (line 51) * socket option, mysqladmin: mysqladmin. (line 410) * socket option, mysqlbinlog: mysqlbinlog. (line 472) * socket option, mysqlcheck: mysqlcheck. (line 380) * socket option, mysqld: server-options. (line 2096) * socket option, mysqld_safe: mysqld-safe. (line 225) * socket option, mysqldump: mysqldump. (line 953) * socket option, mysqlhotcopy: mysqlhotcopy. (line 175) * socket option, mysqlimport: mysqlimport. (line 281) * socket option, mysqlmanager: instance-manager-command-options. (line 212) * socket option, mysqlshow: mysqlshow. (line 201) * socket option, mysqlslap: mysqlslap. (line 462) * socket system variable: server-system-variables. (line 5039) * Solaris installation problems: solaris-installation. (line 11) * Solaris troubleshooting: compilation-problems. (line 136) * Solaris x86_64 issues: innodb-tuning. (line 6) * Solaris, installation: solaris-installation. (line 11) * SOME: any-in-some-subqueries. (line 6) * sort-index option, myisamchk: myisamchk-other-options. (line 36) * sort-records option, myisamchk: myisamchk-other-options. (line 41) * sort-recover option, myisamchk: myisamchk-repair-options. (line 116) * sort_buffer_size myisamchk variable: myisamchk-general-options. (line 53) * sort_buffer_size system variable: server-system-variables. (line 5065) * sort_key_blocks myisamchk variable: myisamchk-general-options. (line 53) * Sorting for group, thread state: general-thread-states. (line 292) * Sorting for order, thread state: general-thread-states. (line 296) * Sorting index, thread state: general-thread-states. (line 300) * Sorting result, thread state: general-thread-states. (line 305) * sorting, data: sorting-rows. (line 6) * sorting, grant tables <1>: request-access. (line 51) * sorting, grant tables: connection-access. (line 126) * sorting, table rows: sorting-rows. (line 6) * SOUNDEX(): string-functions. (line 600) * SOUNDS LIKE: string-functions. (line 639) * source (mysql client command) <1>: mysql-batch-commands. (line 6) * source (mysql client command): batch-mode. (line 90) * source command, mysql: mysql-commands. (line 199) * source distribution, installing: source-installation. (line 19) * SPACE(): string-functions. (line 643) * spassword option, mysqlaccess: mysqlaccess. (line 138) * Spatial Extensions in MySQL: gis-introduction. (line 6) * speed, compiling: compile-and-link-options. (line 6) * speed, increasing with replication: replication. (line 13) * speed, inserting: insert-speed. (line 6) * speed, linking: compile-and-link-options. (line 6) * speed, of queries <1>: select-speed. (line 6) * speed, of queries: select-optimization. (line 25) * sporadic-binlog-dump-fail option, mysqld: replication-options-binary-log. (line 416) * Spring framework: connector-j-usagenotes-spring-config. (line 12) * SQL Editor: connector-net-sql-editor. (line 6) * SQL mode: server-sql-mode. (line 6) * SQL mode, ALLOW_INVALID_DATES: server-sql-mode. (line 114) * SQL mode, and partitioning <1>: partitioning-limitations. (line 49) * SQL mode, and partitioning: replication-features-sql-mode. (line 6) * SQL mode, and replication: replication-features-sql-mode. (line 6) * SQL mode, ANSI: server-sql-mode. (line 77) * SQL mode, ANSI_QUOTES: server-sql-mode. (line 132) * SQL mode, DB2: server-sql-mode. (line 524) * SQL mode, ERROR_FOR_DIVISION_BY_ZERO: server-sql-mode. (line 140) * SQL mode, HIGH_NOT_PRECEDENCE: server-sql-mode. (line 153) * SQL mode, IGNORE_SPACE: server-sql-mode. (line 168) * SQL mode, MAXDB: server-sql-mode. (line 529) * SQL mode, MSSQL: server-sql-mode. (line 535) * SQL mode, MYSQL323: server-sql-mode. (line 540) * SQL mode, MYSQL40: server-sql-mode. (line 544) * SQL mode, NO_AUTO_CREATE_USER: server-sql-mode. (line 193) * SQL mode, NO_AUTO_VALUE_ON_ZERO: server-sql-mode. (line 199) * SQL mode, NO_BACKSLASH_ESCAPES: server-sql-mode. (line 218) * SQL mode, NO_DIR_IN_CREATE: server-sql-mode. (line 224) * SQL mode, NO_ENGINE_SUBSTITUTION: server-sql-mode. (line 230) * SQL mode, NO_FIELD_OPTIONS: server-sql-mode. (line 260) * SQL mode, NO_KEY_OPTIONS: server-sql-mode. (line 266) * SQL mode, NO_TABLE_OPTIONS: server-sql-mode. (line 272) * SQL mode, NO_UNSIGNED_SUBTRACTION: server-sql-mode. (line 278) * SQL mode, NO_ZERO_DATE: server-sql-mode. (line 325) * SQL mode, NO_ZERO_IN_DATE: server-sql-mode. (line 331) * SQL mode, ONLY_FULL_GROUP_BY <1>: group-by-extensions. (line 6) * SQL mode, ONLY_FULL_GROUP_BY: server-sql-mode. (line 340) * SQL mode, ORACLE: server-sql-mode. (line 548) * SQL mode, PAD_CHAR_TO_FULL_LENGTH: server-sql-mode. (line 378) * SQL mode, PIPES_AS_CONCAT: server-sql-mode. (line 416) * SQL mode, POSTGRESQL: server-sql-mode. (line 554) * SQL mode, REAL_AS_FLOAT: server-sql-mode. (line 421) * SQL mode, strict: server-sql-mode. (line 107) * SQL mode, STRICT_ALL_TABLES: server-sql-mode. (line 428) * SQL mode, STRICT_TRANS_TABLES: server-sql-mode. (line 83) * SQL mode, TRADITIONAL: server-sql-mode. (line 91) * SQL node (MySQL Cluster), defined: mysql-cluster-basics. (line 6) * SQL nodes (MySQL Cluster): mysql-cluster-mysqld. (line 6) * SQL scripts: mysql. (line 15) * SQL statements relating to MySQL Cluster: mysql-cluster-sql-statements. (line 6) * SQL statements, replication masters: replication-master-sql. (line 12) * SQL statements, replication slaves: replication-slave-sql. (line 17) * SQL, defined: what-is-mysql. (line 54) * SQL-92, extensions to: compatibility. (line 15) * sql-mode option, mysqld: server-options. (line 2122) * sql_auto_is_null session variable: server-system-variables. (line 5117) * SQL_BIG_RESULT: select. (line 383) * sql_big_selects session variable: server-system-variables. (line 5150) * SQL_BUFFER_RESULT: select. (line 392) * sql_buffer_result session variable: server-system-variables. (line 5174) * SQL_CACHE <1>: select. (line 404) * SQL_CACHE: query-cache-in-select. (line 9) * SQL_CALC_FOUND_ROWS: select. (line 399) * sql_log_bin session variable: server-system-variables. (line 5193) * sql_log_off session variable: server-system-variables. (line 5209) * sql_log_update session variable: server-system-variables. (line 5226) * sql_mode system variable: server-system-variables. (line 5244) * SQL_NO_CACHE <1>: select. (line 404) * SQL_NO_CACHE: query-cache-in-select. (line 14) * sql_notes session variable: server-system-variables. (line 5293) * sql_quote_show_create session variable: server-system-variables. (line 5303) * sql_safe_updates session variable: server-system-variables. (line 5312) * sql_select_limit system variable: server-system-variables. (line 5321) * sql_slave_skip_counter: set-global-sql-slave-skip-counter. (line 6) * sql_slave_skip_counter system variable: replication-options-slave. (line 1702) * SQL_SMALL_RESULT: select. (line 383) * sql_warnings session variable: server-system-variables. (line 5345) * sql_yacc.cc problems: compilation-problems. (line 37) * SQLState error codes: connector-j-reference-error-sqlstates. (line 6) * SQRT(): mathematical-functions. (line 540) * square brackets: data-types. (line 43) * srcdir option, mysql_install_db: mysql-install-db. (line 81) * SRID(): general-geometry-property-functions. (line 51) * SSH: windows-and-ssh. (line 6) * SSL <1>: connector-j-reference-using-ssl. (line 6) * SSL <2>: connector-net-connection-options. (line 6) * SSL: ssl-connections. (line 14) * SSL certificates: connector-net-connection-options. (line 6) * ssl option: ssl-options. (line 38) * SSL options: connecting. (line 208) * SSL options, mysql: mysql-command-options. (line 516) * SSL options, mysqladmin: mysqladmin. (line 415) * SSL options, mysqlcheck: mysqlcheck. (line 385) * SSL options, mysqld: server-options. (line 1967) * SSL options, mysqldump: mysqldump. (line 958) * SSL options, mysqlimport: mysqlimport. (line 286) * SSL options, mysqlshow: mysqlshow. (line 206) * SSL options, mysqlslap: mysqlslap. (line 467) * SSL related options: grant. (line 494) * SSL, command options: ssl-options. (line 6) * SSL, configuring: configuring-for-ssl. (line 6) * SSL, establishing connections: using-ssl-connections. (line 6) * SSL, X509 Basics: ssl-basics. (line 6) * ssl-ca option: ssl-options. (line 79) * ssl-capath option: ssl-options. (line 92) * ssl-cert option: ssl-options. (line 116) * ssl-cipher option: ssl-options. (line 121) * ssl-key option: ssl-options. (line 140) * ssl-verify-server-cert option: ssl-options. (line 153) * ssl_ca system variable: server-system-variables. (line 5351) * ssl_capath system variable: server-system-variables. (line 5371) * ssl_cert system variable: server-system-variables. (line 5391) * ssl_cipher system variable: server-system-variables. (line 5411) * ssl_key system variable: server-system-variables. (line 5431) * standalone option, mysqld: server-options. (line 1973) * standalone option, mysqlmanager: instance-manager-command-options. (line 218) * Standard Monitor, InnoDB: innodb-monitors. (line 12) * Standard SQL, differences from <1>: grant. (line 613) * Standard SQL, differences from: differences-from-ansi. (line 14) * Standard SQL, extensions to <1>: extensions-to-ansi. (line 6) * Standard SQL, extensions to: compatibility. (line 15) * standards compatibility: compatibility. (line 15) * START BACKUP, NOWAIT: mysql-cluster-backup-using-management-client. (line 42) * START BACKUP, SNAPSHOTEND: mysql-cluster-backup-using-management-client. (line 64) * START BACKUP, SNAPSHOTSTART: mysql-cluster-backup-using-management-client. (line 64) * START BACKUP, syntax: mysql-cluster-backup-using-management-client. (line 10) * START BACKUP, WAIT COMPLETED: mysql-cluster-backup-using-management-client. (line 59) * START BACKUP, WAIT STARTED: mysql-cluster-backup-using-management-client. (line 51) * START command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 57) * START SLAVE: start-slave. (line 6) * START TRANSACTION: commit. (line 6) * START, XA transactions: xa-statements. (line 6) * start-datetime option, mysqlbinlog: mysqlbinlog. (line 477) * start-position option, mysqlbinlog: mysqlbinlog. (line 491) * start_row option, mysql_find_rows: mysql-find-rows. (line 47) * StartFailRetryDelay: mysql-cluster-ndbd-definition. (line 3978) * StartFailureTimeout: mysql-cluster-ndbd-definition. (line 1821) * Starting many servers: multiple-servers. (line 13) * starting slave, thread state: slave-connection-thread-states. (line 37) * starting, comments: ansi-diff-comments. (line 6) * starting, mysqld: changing-mysql-user. (line 6) * starting, the server: unix-postinstallation. (line 54) * starting, the server automatically: automatic-start. (line 6) * StartNoNodeGroupTimeout: mysql-cluster-ndbd-definition. (line 1842) * StartPartialTimeout: mysql-cluster-ndbd-definition. (line 1780) * StartPartitionedTimeout: mysql-cluster-ndbd-definition. (line 1801) * StartPoint(): linestring-property-functions. (line 93) * STARTUP Events (MySQL Cluster): mysql-cluster-log-events. (line 62) * startup options, default: option-files. (line 6) * startup parameters: server-parameters. (line 6) * startup parameters, mysql: mysql-command-options. (line 6) * startup parameters, mysqladmin: mysqladmin. (line 213) * startup parameters, tuning: system-optimization. (line 6) * StartupStatusReportFrequency: mysql-cluster-ndbd-definition. (line 2836) * statefile option, comp_err: comp-err. (line 65) * statement-based replication, advantages: replication-sbr-rbr. (line 24) * statement-based replication, disadvantages: replication-sbr-rbr. (line 36) * statement-based replication, unsafe statements: replication-sbr-rbr. (line 38) * statements, compound: sql-syntax-compound-statements. (line 16) * statements, GRANT: adding-users. (line 6) * statements, INSERT: adding-users. (line 117) * statements, replication masters: replication-master-sql. (line 12) * statements, replication slaves: replication-slave-sql. (line 17) * statically, compiling: source-configuration-options. (line 389) * STATISTICS Events (MySQL Cluster): mysql-cluster-log-events. (line 191) * STATISTICS, INFORMATION_SCHEMA table: statistics-table. (line 6) * Statistics, thread command: thread-commands. (line 124) * statistics, thread state: general-thread-states. (line 310) * stats option, myisam_ftdump: myisam-ftdump. (line 74) * stats_method myisamchk variable: myisamchk-general-options. (line 53) * STATUS command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 131) * status command, mysql: mysql-commands. (line 204) * status command, results: mysqladmin. (line 162) * status option, mysqlshow: mysqlshow. (line 212) * status variables <1>: show-status. (line 6) * status variables: server-status-variables. (line 6) * status variables, MySQL Cluster: mysql-cluster-status-variables. (line 6) * status, tables: show-table-status. (line 6) * STD(): group-by-functions. (line 232) * STDDEV(): group-by-functions. (line 240) * STDDEV_POP(): group-by-functions. (line 248) * STDDEV_SAMP(): group-by-functions. (line 256) * STOP command (MySQL Cluster): mysql-cluster-mgm-client-commands. (line 72) * STOP SLAVE: stop-slave. (line 6) * stop-datetime option, mysqlbinlog: mysqlbinlog. (line 500) * stop-position option, mysqlbinlog: mysqlbinlog. (line 510) * StopOnError: mysql-cluster-ndbd-definition. (line 1586) * stopping, the server: automatic-start. (line 6) * stopword list, user-defined: fulltext-fine-tuning. (line 40) * storage engine plugins: storage-engine-plugins. (line 6) * storage engine, ARCHIVE: archive-storage-engine. (line 6) * storage engine, InnoDB: innodb-storage-engine. (line 22) * storage engines, and application feature requirements: mysql-cluster-ndb-innodb-usage. (line 6) * storage engines, applications supported: mysql-cluster-ndb-innodb-workloads. (line 6) * storage engines, availability: mysql-cluster-compared. (line 36) * storage engines, choosing: storage-engines. (line 23) * storage engines, differences between NDB and InnoDB: mysql-cluster-ndb-innodb-engines. (line 6) * storage engines, usage scenarios: mysql-cluster-ndb-innodb-usage. (line 6) * storage nodes - see data nodes, ndbd: mysql-cluster-programs-ndbd. (line 6) * storage nodes - see data nodes, ndbd, ndbmtd: mysql-cluster-programs-ndbmtd. (line 6) * storage requirements, data type: storage-requirements. (line 6) * storage space, minimizing: data-size. (line 6) * storage_engine system variable: server-system-variables. (line 5450) * stored functions: stored-routines. (line 13) * stored functions, and INSERT DELAYED: insert. (line 230) * stored procedures: stored-routines. (line 13) * stored procedures, calling from Connector/Net: connector-net-tutorials-stored-procedures. (line 6) * stored procedures, editing with Visual Studio: connector-net-visual-studio-editing-stored-procedures-and-functions. (line 6) * stored procedures, with Connector/Net: connector-net-programming-stored. (line 10) * stored programs <1>: stored-programs-views. (line 16) * stored programs: sql-syntax-compound-statements. (line 16) * stored routines, and replication: replication-features-invoked. (line 6) * stored routines, LAST_INSERT_ID(): stored-routines-last-insert-id. (line 6) * stored routines, metadata: stored-routines-metadata. (line 6) * stored routines, restrictions: stored-program-restrictions. (line 6) * storing result in query cache, thread state: query-cache-thread-states. (line 29) * storing row into queue, thread state: delayed-insert-thread-states. (line 39) * STR_TO_DATE(): date-and-time-functions. (line 819) * STRAIGHT_JOIN <1>: explain. (line 81) * STRAIGHT_JOIN <2>: join. (line 6) * STRAIGHT_JOIN <3>: select. (line 366) * STRAIGHT_JOIN <4>: left-join-optimization. (line 38) * STRAIGHT_JOIN <5>: explain-output. (line 761) * STRAIGHT_JOIN: using-explain. (line 25) * STRCMP(): string-comparison-functions. (line 190) * strict SQL mode: server-sql-mode. (line 107) * STRICT_ALL_TABLES SQL mode: server-sql-mode. (line 428) * STRICT_TRANS_TABLES SQL mode: server-sql-mode. (line 83) * string collating: string-collating. (line 6) * string comparison functions: string-comparison-functions. (line 6) * string comparisons, case sensitivity: string-comparison-functions. (line 17) * string concatenation <1>: string-functions. (line 189) * string concatenation: string-literals. (line 12) * string functions: string-functions. (line 11) * string literal introducer <1>: charset-literal. (line 11) * string literal introducer: string-literals. (line 33) * string replacement, replace utility: replace-utility. (line 6) * string types <1>: storage-requirements. (line 145) * string types: string-types. (line 14) * StringMemory: mysql-cluster-ndbd-definition. (line 476) * strings, defined: string-literals. (line 6) * strings, escape sequences: string-literals. (line 6) * strings, nondelimited: date-and-time-literals. (line 120) * striping, defined: disk-issues. (line 27) * SUBDATE(): date-and-time-functions. (line 882) * SUBPARTITION BY KEY, known issues: partitioning-limitations. (line 325) * subpartitioning: partitioning-subpartitions. (line 6) * subpartitions: partitioning-subpartitions. (line 6) * subpartitions, known issues: partitioning-limitations. (line 321) * subqueries: subqueries. (line 20) * subqueries, correlated: correlated-subqueries. (line 6) * subqueries, errors: subquery-errors. (line 6) * subqueries, optimization: subquery-optimization-with-exists. (line 6) * subqueries, restrictions: subquery-restrictions. (line 6) * subqueries, rewriting as joins: rewriting-subqueries. (line 6) * subqueries, with ALL: all-subqueries. (line 6) * subqueries, with ANY, IN, SOME: any-in-some-subqueries. (line 6) * subqueries, with EXISTS: exists-and-not-exists-subqueries. (line 6) * subqueries, with NOT EXISTS: exists-and-not-exists-subqueries. (line 6) * subqueries, with ROW: row-subqueries. (line 6) * subquery: subqueries. (line 20) * subselects: subqueries. (line 20) * SUBSTR(): string-functions. (line 650) * SUBSTRING(): string-functions. (line 655) * SUBSTRING_INDEX(): string-functions. (line 688) * SUBTIME(): date-and-time-functions. (line 900) * subtraction (-): arithmetic-functions. (line 62) * suffix option, mysqlhotcopy: mysqlhotcopy. (line 179) * SUM(): group-by-functions. (line 263) * SUM(DISTINCT): group-by-functions. (line 263) * superuser: default-privileges. (line 6) * superuser option, mysqlaccess: mysqlaccess. (line 148) * support, for operating systems: supported-os. (line 6) * suppression, default values: constraint-invalid-data. (line 6) * symbolic links <1>: windows-symbolic-links. (line 6) * symbolic links: symbolic-links. (line 12) * symbolic-links option, mysqld: server-options. (line 1985) * symbols-file option, resolve_stack_dump: resolve-stack-dump. (line 29) * SymDifference(): spatial-operators. (line 31) * sync_binlog system variable: replication-options-binary-log. (line 827) * sync_frm system variable: server-system-variables. (line 5468) * synchronization of master and slave, in MySQL Cluster Replication: mysql-cluster-replication-auto-sync. (line 6) * Syncing ndb table schema operation and binlog, thread state: mysql-cluster-thread-states. (line 20) * syntax conventions: manual-conventions. (line 8) * syntax, regular expression: regexp. (line 6) * sys-check option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 263) * sys-create option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 218) * sys-create-if-not-exist option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 233) * sys-create-if-not-valid option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 248) * sys-drop option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 203) * sys-skip-events option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 292) * sys-skip-tables option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 278) * SYSDATE(): date-and-time-functions. (line 911) * sysdate-is-now option, mysqld: server-options. (line 2170) * syslog option, mysqld_safe: mysqld-safe. (line 230) * syslog-tag option, mysqld_safe: mysqld-safe. (line 240) * system command, mysql: mysql-commands. (line 211) * System lock, thread state: general-thread-states. (line 316) * system optimization: system-optimization. (line 6) * system option, ndb_config: mysql-cluster-programs-ndb-config. (line 305) * system table, optimizer <1>: select. (line 372) * system table, optimizer: explain-output. (line 235) * system variable, auto_increment_increment: replication-options-master. (line 26) * system variable, auto_increment_offset: replication-options-master. (line 226) * system variable, automatic_sp_privileges: server-system-variables. (line 628) * system variable, back_log: server-system-variables. (line 656) * system variable, basedir: server-system-variables. (line 688) * system variable, binlog_cache_size: replication-options-binary-log. (line 438) * system variable, binlog_direct_non_transactional_updates: replication-options-binary-log. (line 476) * system variable, binlog_format: replication-options-binary-log. (line 530) * system variable, bulk_insert_buffer_size: server-system-variables. (line 724) * system variable, character_set_client: server-system-variables. (line 758) * system variable, character_set_connection: server-system-variables. (line 797) * system variable, character_set_database: server-system-variables. (line 814) * system variable, character_set_filesystem: server-system-variables. (line 854) * system variable, character_set_results: server-system-variables. (line 884) * system variable, character_set_server: server-system-variables. (line 900) * system variable, character_set_system: server-system-variables. (line 918) * system variable, character_sets_dir: server-system-variables. (line 933) * system variable, collation_connection: server-system-variables. (line 951) * system variable, collation_database: server-system-variables. (line 966) * system variable, collation_server: server-system-variables. (line 1006) * system variable, completion_type: server-system-variables. (line 1024) * system variable, concurrent_insert: server-system-variables. (line 1073) * system variable, connect_timeout: server-system-variables. (line 1113) * system variable, datadir: server-system-variables. (line 1146) * system variable, date_format: server-system-variables. (line 1166) * system variable, datetime_format: server-system-variables. (line 1170) * system variable, debug: server-system-variables. (line 1174) * system variable, debug_sync: server-system-variables. (line 1227) * system variable, default_week_format: server-system-variables. (line 1266) * system variable, delay_key_write: server-system-variables. (line 1288) * system variable, delayed_insert_limit: server-system-variables. (line 1337) * system variable, delayed_insert_timeout: server-system-variables. (line 1369) * system variable, delayed_queue_size: server-system-variables. (line 1389) * system variable, div_precision_increment: server-system-variables. (line 1421) * system variable, engine_condition_pushdown: server-system-variables. (line 1462) * system variable, event_scheduler: server-system-variables. (line 1503) * system variable, expire_logs_days: server-system-variables. (line 1531) * system variable, flush: server-system-variables. (line 1558) * system variable, flush_time: server-system-variables. (line 1581) * system variable, ft_boolean_syntax: server-system-variables. (line 1624) * system variable, ft_max_word_len: server-system-variables. (line 1663) * system variable, ft_min_word_len: server-system-variables. (line 1687) * system variable, ft_query_expansion_limit: server-system-variables. (line 1712) * system variable, ft_stopword_file: server-system-variables. (line 1733) * system variable, general_log: server-system-variables. (line 1764) * system variable, general_log_file: server-system-variables. (line 1789) * system variable, group_concat_max_len: server-system-variables. (line 1813) * system variable, have_archive: server-system-variables. (line 1843) * system variable, have_blackhole_engine: server-system-variables. (line 1848) * system variable, have_community_features: server-system-variables. (line 1859) * system variable, have_compress: server-system-variables. (line 1853) * system variable, have_crypt: server-system-variables. (line 1868) * system variable, have_csv: server-system-variables. (line 1873) * system variable, have_dynamic_loading: server-system-variables. (line 1882) * system variable, have_example_engine: server-system-variables. (line 1887) * system variable, have_federated_engine: server-system-variables. (line 1892) * system variable, have_geometry: server-system-variables. (line 1897) * system variable, have_innodb: server-system-variables. (line 1901) * system variable, have_isam: server-system-variables. (line 1909) * system variable, have_merge_engine: server-system-variables. (line 1915) * system variable, have_openssl: server-system-variables. (line 1921) * system variable, have_partitioning: server-system-variables. (line 1926) * system variable, have_query_cache: server-system-variables. (line 1935) * system variable, have_raid: server-system-variables. (line 1959) * system variable, have_row_based_replication: server-system-variables. (line 1940) * system variable, have_rtree_keys: server-system-variables. (line 1965) * system variable, have_ssl: server-system-variables. (line 1970) * system variable, have_symlink: server-system-variables. (line 1980) * system variable, hostname: server-system-variables. (line 1988) * system variable, ignore_builtin_innodb: innodb-parameters. (line 214) * system variable, init_connect: server-system-variables. (line 2011) * system variable, init_file: server-system-variables. (line 2051) * system variable, init_slave: replication-options-slave. (line 1380) * system variable, innodb_adaptive_flushing: innodb-parameters. (line 236) * system variable, innodb_adaptive_hash_index: innodb-parameters. (line 262) * system variable, innodb_additional_mem_pool_size: innodb-parameters. (line 288) * system variable, innodb_autoextend_increment: innodb-parameters. (line 319) * system variable, innodb_buffer_pool_size: innodb-parameters. (line 413) * system variable, innodb_change_buffering: innodb-parameters. (line 483) * system variable, innodb_checksums: innodb-parameters. (line 509) * system variable, innodb_commit_concurrency: innodb-parameters. (line 532) * system variable, innodb_concurrency_tickets: innodb-parameters. (line 558) * system variable, innodb_data_file_path: innodb-parameters. (line 587) * system variable, innodb_data_home_dir: innodb-parameters. (line 618) * system variable, innodb_doublewrite: innodb-parameters. (line 641) * system variable, innodb_fast_shutdown: innodb-parameters. (line 663) * system variable, innodb_file_format: innodb-parameters. (line 692) * system variable, innodb_file_format_check: innodb-parameters. (line 717) * system variable, innodb_file_per_table: innodb-parameters. (line 777) * system variable, innodb_flush_log_at_trx_commit: innodb-parameters. (line 805) * system variable, innodb_flush_method: innodb-parameters. (line 865) * system variable, innodb_force_recovery: innodb-parameters. (line 938) * system variable, innodb_io_capacity: innodb-parameters. (line 974) * system variable, innodb_locks_unsafe_for_binlog: innodb-parameters. (line 1106) * system variable, innodb_log_buffer_size: innodb-parameters. (line 1305) * system variable, innodb_log_file_size: innodb-parameters. (line 1332) * system variable, innodb_log_files_in_group: innodb-parameters. (line 1362) * system variable, innodb_log_group_home_dir: innodb-parameters. (line 1384) * system variable, innodb_max_dirty_pages_pct: innodb-parameters. (line 1406) * system variable, innodb_max_purge_lag: innodb-parameters. (line 1430) * system variable, innodb_mirrored_log_groups: innodb-parameters. (line 1479) * system variable, innodb_old_blocks_pct: innodb-parameters. (line 1483) * system variable, innodb_old_blocks_time: innodb-parameters. (line 1517) * system variable, innodb_open_files: innodb-parameters. (line 1552) * system variable, innodb_read_ahead_threshold: innodb-parameters. (line 1609) * system variable, innodb_read_io_threads: innodb-parameters. (line 1643) * system variable, innodb_replication_delay: innodb-parameters. (line 1676) * system variable, innodb_rollback_on_timeout: innodb-parameters. (line 1700) * system variable, innodb_spin_wait_delay: innodb-parameters. (line 1725) * system variable, innodb_stats_method: innodb-parameters. (line 1753) * system variable, innodb_stats_on_metadata: innodb-parameters. (line 1788) * system variable, innodb_stats_sample_pages: innodb-parameters. (line 1821) * system variable, innodb_strict_mode: innodb-parameters. (line 1849) * system variable, innodb_support_xa: innodb-parameters. (line 1875) * system variable, innodb_sync_spin_loops: innodb-parameters. (line 1916) * system variable, innodb_table_locks: innodb-parameters. (line 1939) * system variable, innodb_thread_concurrency: innodb-parameters. (line 1963) * system variable, innodb_thread_sleep_delay: innodb-parameters. (line 2006) * system variable, innodb_use_sys_malloc: innodb-parameters. (line 2060) * system variable, innodb_version: innodb-parameters. (line 2083) * system variable, innodb_write_io_threads: innodb-parameters. (line 2092) * system variable, interactive_timeout: server-system-variables. (line 2093) * system variable, join_buffer_size: server-system-variables. (line 2117) * system variable, keep_files_on_create: server-system-variables. (line 2170) * system variable, key_buffer_size: server-system-variables. (line 2204) * system variable, key_cache_age_threshold: server-system-variables. (line 2306) * system variable, key_cache_block_size: server-system-variables. (line 2339) * system variable, key_cache_division_limit: server-system-variables. (line 2361) * system variable, language: server-system-variables. (line 2384) * system variable, large_files_support: server-system-variables. (line 2405) * system variable, large_page_size: server-system-variables. (line 2437) * system variable, large_pages: server-system-variables. (line 2417) * system variable, lc_time_names: server-system-variables. (line 2463) * system variable, license: server-system-variables. (line 2486) * system variable, local_infile: server-system-variables. (line 2501) * system variable, locked_in_memory: server-system-variables. (line 2518) * system variable, log: server-system-variables. (line 2530) * system variable, log_bin: replication-options-binary-log. (line 653) * system variable, log_bin_trust_function_creators: server-system-variables. (line 2556) * system variable, log_bin_use_v1_row_events: replication-options-binary-log. (line 670) * system variable, log_error: server-system-variables. (line 2585) * system variable, log_output: server-system-variables. (line 2604) * system variable, log_queries_not_using_indexes: server-system-variables. (line 2635) * system variable, log_slave_updates: replication-options-binary-log. (line 720) * system variable, log_slow_queries: server-system-variables. (line 2655) * system variable, log_warnings: server-system-variables. (line 2680) * system variable, long_query_time: server-system-variables. (line 2717) * system variable, low_priority_updates: server-system-variables. (line 2751) * system variable, lower_case_file_system: server-system-variables. (line 2776) * system variable, lower_case_table_names: server-system-variables. (line 2794) * system variable, max_allowed_packet: server-system-variables. (line 2842) * system variable, max_binlog_cache_size: replication-options-binary-log. (line 741) * system variable, max_binlog_size: replication-options-binary-log. (line 795) * system variable, max_connect_errors: server-system-variables. (line 2889) * system variable, max_connections: server-system-variables. (line 2926) * system variable, max_delayed_threads: server-system-variables. (line 2969) * system variable, max_error_count: server-system-variables. (line 2999) * system variable, max_heap_table_size: server-system-variables. (line 3022) * system variable, max_insert_delayed_threads: server-system-variables. (line 3069) * system variable, max_join_size: server-system-variables. (line 3084) * system variable, max_length_for_sort_data: server-system-variables. (line 3123) * system variable, max_long_data_size: server-system-variables. (line 3145) * system variable, max_prepared_stmt_count: server-system-variables. (line 3173) * system variable, max_relay_log_size: server-system-variables. (line 3205) * system variable, max_seeks_for_key: server-system-variables. (line 3234) * system variable, max_sort_length: server-system-variables. (line 3269) * system variable, max_sp_recursion_depth: server-system-variables. (line 3292) * system variable, max_tmp_tables: server-system-variables. (line 3320) * system variable, max_user_connections: server-system-variables. (line 3324) * system variable, max_write_lock_count: server-system-variables. (line 3363) * system variable, min_examined_row_limit: server-system-variables. (line 3392) * system variable, myisam_data_pointer_size: server-system-variables. (line 3423) * system variable, myisam_max_sort_file_size: server-system-variables. (line 3446) * system variable, myisam_mmap_size: server-system-variables. (line 3480) * system variable, myisam_recover_options: server-system-variables. (line 3513) * system variable, myisam_repair_threads: server-system-variables. (line 3525) * system variable, myisam_sort_buffer_size: server-system-variables. (line 3560) * system variable, myisam_stats_method: server-system-variables. (line 3599) * system variable, myisam_use_mmap: server-system-variables. (line 3635) * system variable, named_pipe: server-system-variables. (line 3655) * system variable, ndb_log_empty_epochs: mysql-cluster-system-variables. (line 1125) * system variable, ndb_log_transaction_id: mysql-cluster-system-variables. (line 1099) * system variable, net_buffer_length: server-system-variables. (line 3672) * system variable, net_read_timeout: server-system-variables. (line 3708) * system variable, net_retry_count: server-system-variables. (line 3739) * system variable, net_write_timeout: server-system-variables. (line 3778) * system variable, new: server-system-variables. (line 3806) * system variable, old: server-system-variables. (line 3829) * system variable, old_alter_table: server-system-variables. (line 3858) * system variable, old_passwords: server-system-variables. (line 3883) * system variable, one_shot: server-system-variables. (line 3915) * system variable, open_files_limit: server-system-variables. (line 3920) * system variable, optimizer_prune_level: server-system-variables. (line 3945) * system variable, optimizer_search_depth: server-system-variables. (line 3968) * system variable, optimizer_switch: server-system-variables. (line 3998) * system variable, pid_file: server-system-variables. (line 4038) * system variable, plugin_dir: server-system-variables. (line 4057) * system variable, port: server-system-variables. (line 4094) * system variable, preload_buffer_size: server-system-variables. (line 4116) * system variable, prepared_stmt_count: server-system-variables. (line 4138) * system variable, protocol_version: server-system-variables. (line 4174) * system variable, pseudo_thread_id: server-system-variables. (line 4188) * system variable, query_alloc_block_size: server-system-variables. (line 4202) * system variable, query_cache_limit: server-system-variables. (line 4238) * system variable, query_cache_min_res_unit: server-system-variables. (line 4267) * system variable, query_cache_size: server-system-variables. (line 4299) * system variable, query_cache_type: server-system-variables. (line 4337) * system variable, query_cache_wlock_invalidate: server-system-variables. (line 4380) * system variable, query_prealloc_size: server-system-variables. (line 4405) * system variable, range_alloc_block_size: server-system-variables. (line 4461) * system variable, read_buffer_size: server-system-variables. (line 4495) * system variable, read_only: server-system-variables. (line 4542) * system variable, read_rnd_buffer_size: server-system-variables. (line 4610) * system variable, relay_log: replication-options-slave. (line 1408) * system variable, relay_log_index: replication-options-slave. (line 1426) * system variable, relay_log_info_file: replication-options-slave. (line 1446) * system variable, relay_log_purge: server-system-variables. (line 4644) * system variable, relay_log_space_limit: server-system-variables. (line 4663) * system variable, report_host: server-system-variables. (line 4691) * system variable, report_password: server-system-variables. (line 4709) * system variable, report_port: server-system-variables. (line 4728) * system variable, report_user: server-system-variables. (line 4749) * system variable, secure_auth: server-system-variables. (line 4767) * system variable, secure_file_priv: server-system-variables. (line 4793) * system variable, server_id: server-system-variables. (line 4817) * system variable, server_id_bits: mysql-cluster-system-variables. (line 1148) * system variable, shared_memory: server-system-variables. (line 4841) * system variable, shared_memory_base_name: server-system-variables. (line 4854) * system variable, skip_external_locking: server-system-variables. (line 4869) * system variable, skip_name_resolve: server-system-variables. (line 4898) * system variable, skip_networking: server-system-variables. (line 4923) * system variable, skip_show_database: server-system-variables. (line 4942) * system variable, slave_compressed_protocol: replication-options-slave. (line 1470) * system variable, slave_exec_mode: replication-options-slave. (line 1489) * system variable, slave_load_tmpdir: replication-options-slave. (line 1559) * system variable, slave_max_allowed_packet: replication-options-slave. (line 1526) * system variable, slave_net_timeout: replication-options-slave. (line 1579) * system variable, slave_skip_errors: replication-options-slave. (line 1601) * system variable, slave_transaction_retries: replication-options-slave. (line 1631) * system variable, slave_type_conversions: replication-options-slave. (line 1667) * system variable, slow_launch_time: server-system-variables. (line 4968) * system variable, slow_query_log: server-system-variables. (line 4987) * system variable, slow_query_log_file: server-system-variables. (line 5017) * system variable, socket: server-system-variables. (line 5039) * system variable, sort_buffer_size: server-system-variables. (line 5065) * system variable, sql_mode: server-system-variables. (line 5244) * system variable, sql_select_limit: server-system-variables. (line 5321) * system variable, sql_slave_skip_counter: replication-options-slave. (line 1702) * system variable, ssl_ca: server-system-variables. (line 5351) * system variable, ssl_capath: server-system-variables. (line 5371) * system variable, ssl_cert: server-system-variables. (line 5391) * system variable, ssl_cipher: server-system-variables. (line 5411) * system variable, ssl_key: server-system-variables. (line 5431) * system variable, storage_engine: server-system-variables. (line 5450) * system variable, sync_binlog: replication-options-binary-log. (line 827) * system variable, sync_frm: server-system-variables. (line 5468) * system variable, system_time_zone: server-system-variables. (line 5489) * system variable, table_cache: server-system-variables. (line 5515) * system variable, table_definition_cache: server-system-variables. (line 5540) * system variable, table_lock_wait_timeout: server-system-variables. (line 5576) * system variable, table_open_cache: server-system-variables. (line 5596) * system variable, table_type: server-system-variables. (line 5623) * system variable, thread_cache_size: server-system-variables. (line 5640) * system variable, thread_concurrency: server-system-variables. (line 5673) * system variable, thread_handling: server-system-variables. (line 5697) * system variable, thread_stack: server-system-variables. (line 5722) * system variable, time_format: server-system-variables. (line 5760) * system variable, time_zone: server-system-variables. (line 5764) * system variable, timed_mutexes: server-system-variables. (line 5784) * system variable, tmp_table_size: server-system-variables. (line 5822) * system variable, tmpdir: server-system-variables. (line 5859) * system variable, transaction_alloc_block_size: server-system-variables. (line 5895) * system variable, transaction_prealloc_size: server-system-variables. (line 5930) * system variable, tx_isolation: server-system-variables. (line 5973) * system variable, updatable_views_with_limit: server-system-variables. (line 6033) * system variable, version: server-system-variables. (line 6065) * system variable, version_comment: server-system-variables. (line 6073) * system variable, version_compile_machine: server-system-variables. (line 6089) * system variable, version_compile_os: server-system-variables. (line 6103) * system variable, wait_timeout: server-system-variables. (line 6117) * system variables <1>: show-variables. (line 6) * system variables <2>: using-system-variables. (line 11) * system variables: server-system-variables. (line 6) * system variables, and replication: replication-features-variables. (line 6) * system, privilege: privilege-system. (line 16) * system, security: general-security-issues. (line 16) * system_time_zone system variable: server-system-variables. (line 5489) * SYSTEM_USER(): information-functions. (line 564) * tab (\t) <1>: load-data. (line 434) * tab (\t): string-literals. (line 74) * tab option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 481) * tab option, mysqldump: mysqldump. (line 964) * table aliases: select. (line 162) * table cache <1>: connector-net-programming-tablecaching. (line 6) * table cache: table-cache. (line 6) * table description, myisamchk: myisamchk-table-info. (line 6) * Table Designer: connector-net-visual-studio-editing-tables. (line 14) * Table Dump, thread command: thread-commands. (line 128) * table is full <1>: full-table. (line 6) * table is full: server-system-variables. (line 711) * Table is full errors (MySQL Cluster): mysql-cluster-ndbd-definition. (line 373) * Table is full errors, MySQL Cluster: faqs-mysql-cluster. (line 6) * Table lock, thread state: general-thread-states. (line 327) * Table Monitor, InnoDB <1>: innodb-troubleshooting-datadict. (line 61) * Table Monitor, InnoDB: innodb-monitors. (line 12) * table names, case sensitivity <1>: identifier-case-sensitivity. (line 6) * table names, case sensitivity: extensions-to-ansi. (line 38) * table option, mysql: mysql-command-options. (line 522) * table option, mysqlaccess: mysqlaccess. (line 152) * table option, ndb_desc: mysql-cluster-programs-ndb-desc. (line 320) * table scans, avoiding: how-to-avoid-table-scan. (line 6) * table type, choosing: storage-engines. (line 23) * table, changing <1>: alter-table-problems. (line 6) * table, changing: alter-table. (line 12) * table, deleting: drop-table. (line 6) * table, rebuilding: rebuilding-tables. (line 6) * table, repair: rebuilding-tables. (line 6) * table, row size: storage-requirements. (line 24) * table-level locking: internal-locking. (line 6) * table_cache system variable: server-system-variables. (line 5515) * table_definition_cache system variable: server-system-variables. (line 5540) * table_lock_wait_timeout system variable: server-system-variables. (line 5576) * table_open_cache: table-cache. (line 6) * table_open_cache system variable: server-system-variables. (line 5596) * TABLE_PRIVILEGES, INFORMATION_SCHEMA table: table-privileges-table. (line 6) * table_type system variable: server-system-variables. (line 5623) * TableDirect commands: connector-net-connection-options. (line 6) * tables option, mysqlcheck: mysqlcheck. (line 391) * tables option, mysqldump: mysqldump. (line 993) * tables, BLACKHOLE: blackhole-storage-engine. (line 6) * tables, checking: myisamchk-check-options. (line 6) * tables, closing: table-cache. (line 6) * tables, compressed: myisampack. (line 6) * tables, compressed format: compressed-format. (line 6) * tables, const: explain-output. (line 240) * tables, constant: where-optimizations. (line 50) * tables, copying <1>: create-table-select. (line 6) * tables, copying: create-table. (line 1320) * tables, counting rows: counting-rows. (line 6) * tables, creating: creating-tables. (line 6) * tables, CSV: csv-storage-engine. (line 11) * tables, defragment: dynamic-format. (line 16) * tables, defragmenting <1>: optimize-table. (line 6) * tables, defragmenting: myisam-maintenance-schedule. (line 38) * tables, deleting rows: deleting-from-related-tables. (line 6) * tables, displaying: mysqlshow. (line 6) * tables, displaying status: show-table-status. (line 6) * tables, dumping <1>: mysqlhotcopy. (line 6) * tables, dumping: mysqldump. (line 6) * tables, dynamic: dynamic-format. (line 6) * tables, error checking: myisam-check. (line 6) * tables, EXAMPLE: example-storage-engine. (line 6) * tables, FEDERATED: federated-storage-engine. (line 13) * tables, flush: mysqladmin. (line 187) * tables, fragmentation: optimize-table. (line 6) * tables, HEAP: memory-storage-engine. (line 6) * tables, host: request-access. (line 148) * tables, improving performance: data-size. (line 6) * tables, information: myisamchk-table-info. (line 6) * tables, information about: getting-information. (line 6) * TABLES, INFORMATION_SCHEMA table: tables-table. (line 6) * tables, InnoDB: innodb-storage-engine. (line 22) * tables, loading data: loading-tables. (line 6) * tables, maintenance: mysqlcheck. (line 6) * tables, maintenance schedule: myisam-maintenance-schedule. (line 6) * tables, maximum size: table-size-limit. (line 6) * tables, MEMORY: memory-storage-engine. (line 6) * tables, MERGE: merge-storage-engine. (line 11) * tables, merging: merge-storage-engine. (line 11) * tables, multiple: multiple-tables. (line 6) * tables, MyISAM: myisam-storage-engine. (line 13) * tables, names: identifiers. (line 13) * tables, open: table-cache. (line 6) * tables, opening: table-cache. (line 6) * tables, optimizing: myisam-optimization. (line 6) * tables, partitioning: merge-storage-engine. (line 11) * tables, repair: mysqlcheck. (line 6) * tables, repairing: myisam-repair. (line 6) * tables, retrieving data: retrieving-data. (line 18) * tables, selecting columns: selecting-columns. (line 6) * tables, selecting rows: selecting-rows. (line 6) * tables, sorting rows: sorting-rows. (line 6) * tables, symbolic links: symbolic-links-to-tables. (line 6) * tables, system: explain-output. (line 235) * tables, too many: creating-many-tables. (line 6) * tables, unique ID for last row: getting-unique-id. (line 6) * tables, updating: ansi-diff-transactions. (line 6) * Tablespace Monitor, InnoDB <1>: innodb-monitors. (line 12) * Tablespace Monitor, InnoDB <2>: innodb-file-space. (line 48) * Tablespace Monitor, InnoDB: innodb-backup. (line 120) * TAN(): mathematical-functions. (line 551) * tar, problems on Solaris: solaris-installation. (line 11) * tc-heuristic-recover option, mysqld: server-options. (line 2193) * Tcl API: apis-tcl. (line 6) * tcp-ip option, mysqld_multi: mysqld-multi. (line 159) * TCP/IP <1>: windows-testing. (line 6) * TCP/IP: windows-select-server. (line 45) * TCP_RCV_BUF_SIZE: mysql-cluster-tcp-definition. (line 194) * TCP_SND_BUF_SIZE: mysql-cluster-tcp-definition. (line 209) * tee command, mysql: mysql-commands. (line 217) * tee option, mysql: mysql-command-options. (line 528) * temp-pool option, mysqld: server-options. (line 2209) * temporary file, write access: mysql-install-db-problems. (line 70) * temporary files: temporary-files. (line 6) * temporary tables, and replication: replication-features-temptables. (line 6) * temporary tables, internal: internal-temporary-tables. (line 6) * temporary tables, problems: temporary-table-problems. (line 6) * terminal monitor, defined: tutorial. (line 16) * test option, myisampack: myisampack. (line 97) * testing mysqld, mysqltest: mysql-test-suite. (line 6) * testing, connection to the server: connection-access. (line 6) * testing, installation: unix-postinstallation. (line 54) * testing, of MySQL releases: choosing-version. (line 118) * testing, postinstallation: postinstallation. (line 11) * TEXT columns, default values: blob. (line 52) * TEXT columns, indexing <1>: create-table. (line 524) * TEXT columns, indexing: column-indexes. (line 15) * TEXT data type <1>: blob. (line 6) * TEXT data type: string-type-overview. (line 191) * text files, importing <1>: load-data. (line 6) * text files, importing <2>: mysqlimport. (line 6) * text files, importing: mysql-batch-commands. (line 6) * TEXT, size: storage-requirements. (line 190) * thread cache: connection-threads. (line 6) * thread command, Binlog Dump: thread-commands. (line 8) * thread command, Change user: thread-commands. (line 13) * thread command, Close stmt: thread-commands. (line 17) * thread command, Connect: thread-commands. (line 21) * thread command, Connect Out: thread-commands. (line 25) * thread command, Create DB: thread-commands. (line 29) * thread command, Daemon: thread-commands. (line 33) * thread command, Debug: thread-commands. (line 38) * thread command, Delayed insert: thread-commands. (line 42) * thread command, Drop DB: thread-commands. (line 46) * thread command, Error: thread-commands. (line 50) * thread command, Execute: thread-commands. (line 52) * thread command, Fetch: thread-commands. (line 56) * thread command, Field List: thread-commands. (line 61) * thread command, Init DB: thread-commands. (line 65) * thread command, Kill: thread-commands. (line 69) * thread command, Long Data: thread-commands. (line 73) * thread command, Ping: thread-commands. (line 78) * thread command, Prepare: thread-commands. (line 82) * thread command, Processlist: thread-commands. (line 86) * thread command, Query: thread-commands. (line 90) * thread command, Quit: thread-commands. (line 94) * thread command, Refresh: thread-commands. (line 98) * thread command, Register Slave: thread-commands. (line 103) * thread command, Reset stmt: thread-commands. (line 107) * thread command, Set option: thread-commands. (line 111) * thread command, Shutdown: thread-commands. (line 116) * thread command, Sleep: thread-commands. (line 120) * thread command, Statistics: thread-commands. (line 124) * thread command, Table Dump: thread-commands. (line 128) * thread command, Time: thread-commands. (line 132) * thread commands: thread-commands. (line 6) * thread state, After create: general-thread-states. (line 11) * thread state, allocating local table: delayed-insert-thread-states. (line 17) * thread state, Analyzing: general-thread-states. (line 18) * thread state, Changing master: slave-connection-thread-states. (line 9) * thread state, Checking master version: slave-io-thread-states. (line 20) * thread state, checking permissions: general-thread-states. (line 23) * thread state, checking privileges on cached query: query-cache-thread-states. (line 9) * thread state, checking query cache for query: query-cache-thread-states. (line 14) * thread state, Checking table: general-thread-states. (line 28) * thread state, cleaning up: general-thread-states. (line 32) * thread state, Clearing: event-scheduler-thread-states. (line 10) * thread state, closing tables: general-thread-states. (line 37) * thread state, Committing events to binlog: mysql-cluster-thread-states. (line 6) * thread state, Connecting to master: slave-io-thread-states. (line 16) * thread state, converting HEAP to MyISAM: general-thread-states. (line 44) * thread state, copy to tmp table: general-thread-states. (line 49) * thread state, Copying to group table: general-thread-states. (line 55) * thread state, Copying to tmp table: general-thread-states. (line 60) * thread state, Copying to tmp table on disk: general-thread-states. (line 64) * thread state, Creating delayed handler: delayed-insert-thread-states. (line 22) * thread state, Creating index: general-thread-states. (line 72) * thread state, Creating sort index: general-thread-states. (line 77) * thread state, creating table: general-thread-states. (line 82) * thread state, Creating table from master dump: slave-connection-thread-states. (line 14) * thread state, Creating tmp table: general-thread-states. (line 87) * thread state, deleting from main table: general-thread-states. (line 94) * thread state, deleting from reference tables: general-thread-states. (line 100) * thread state, discard_or_import_tablespace: general-thread-states. (line 105) * thread state, end: general-thread-states. (line 110) * thread state, executing: general-thread-states. (line 117) * thread state, Execution of init_command: general-thread-states. (line 121) * thread state, Finished reading one binlog; switching to next binlog: master-thread-states. (line 17) * thread state, Flushing tables: general-thread-states. (line 132) * thread state, freeing items: general-thread-states. (line 126) * thread state, FULLTEXT initialization: general-thread-states. (line 137) * thread state, got handler lock: delayed-insert-thread-states. (line 26) * thread state, got old table: delayed-insert-thread-states. (line 32) * thread state, Has read all relay log; waiting for the slave I/O thread to update it: slave-sql-thread-states. (line 18) * thread state, Has sent all binlog to slave; waiting for binlog to be updated: master-thread-states. (line 22) * thread state, init: general-thread-states. (line 142) * thread state, Initialized: event-scheduler-thread-states. (line 15) * thread state, insert: delayed-insert-thread-states. (line 72) * thread state, invalidating query cache entries: query-cache-thread-states. (line 19) * thread state, Killed: general-thread-states. (line 158) * thread state, Killing slave: slave-connection-thread-states. (line 21) * thread state, Locked: general-thread-states. (line 167) * thread state, logging slow query: general-thread-states. (line 171) * thread state, login: general-thread-states. (line 180) * thread state, Making temp file: slave-sql-thread-states. (line 25) * thread state, manage keys: general-thread-states. (line 185) * thread state, NULL: general-thread-states. (line 175) * thread state, Opening master dump table: slave-connection-thread-states. (line 25) * thread state, Opening mysql.ndb_apply_status: mysql-cluster-thread-states. (line 8) * thread state, Opening table: general-thread-states. (line 189) * thread state, Opening tables: general-thread-states. (line 189) * thread state, optimizing: general-thread-states. (line 198) * thread state, preparing: general-thread-states. (line 202) * thread state, Processing events: mysql-cluster-thread-states. (line 10) * thread state, Processing events from schema table: mysql-cluster-thread-states. (line 14) * thread state, Purging old relay logs: general-thread-states. (line 206) * thread state, query end: general-thread-states. (line 210) * thread state, Queueing master event to the relay log: slave-io-thread-states. (line 57) * thread state, Reading event from the relay log: slave-sql-thread-states. (line 13) * thread state, Reading from net: general-thread-states. (line 215) * thread state, Reading master dump table data: slave-connection-thread-states. (line 29) * thread state, Rebuilding the index on master dump table: slave-connection-thread-states. (line 33) * thread state, Reconnecting after a failed binlog dump request: slave-io-thread-states. (line 45) * thread state, Reconnecting after a failed master event read: slave-io-thread-states. (line 70) * thread state, Registering slave on master: slave-io-thread-states. (line 25) * thread state, Removing duplicates: general-thread-states. (line 219) * thread state, removing tmp table: general-thread-states. (line 226) * thread state, rename: general-thread-states. (line 232) * thread state, rename result table: general-thread-states. (line 236) * thread state, Reopen tables: general-thread-states. (line 242) * thread state, Repair by sorting: general-thread-states. (line 248) * thread state, Repair done: general-thread-states. (line 252) * thread state, Repair with keycache: general-thread-states. (line 257) * thread state, Requesting binlog dump: slave-io-thread-states. (line 30) * thread state, reschedule: delayed-insert-thread-states. (line 76) * thread state, Rolling back: general-thread-states. (line 262) * thread state, Saving state: general-thread-states. (line 266) * thread state, Searching rows for update: general-thread-states. (line 273) * thread state, Sending binlog event to slave: master-thread-states. (line 11) * thread state, sending cached result to client: query-cache-thread-states. (line 24) * thread state, setup: general-thread-states. (line 287) * thread state, Shutting down: mysql-cluster-thread-states. (line 18) * thread state, Sorting for group: general-thread-states. (line 292) * thread state, Sorting for order: general-thread-states. (line 296) * thread state, Sorting index: general-thread-states. (line 300) * thread state, Sorting result: general-thread-states. (line 305) * thread state, starting slave: slave-connection-thread-states. (line 37) * thread state, statistics: general-thread-states. (line 310) * thread state, storing result in query cache: query-cache-thread-states. (line 29) * thread state, storing row into queue: delayed-insert-thread-states. (line 39) * thread state, Syncing ndb table schema operation and binlog: mysql-cluster-thread-states. (line 20) * thread state, System lock: general-thread-states. (line 316) * thread state, Table lock: general-thread-states. (line 327) * thread state, update: general-thread-states. (line 333) * thread state, Updating: general-thread-states. (line 337) * thread state, updating main table: general-thread-states. (line 341) * thread state, updating reference tables: general-thread-states. (line 347) * thread state, upgrading lock: delayed-insert-thread-states. (line 81) * thread state, User lock: general-thread-states. (line 352) * thread state, User sleep: general-thread-states. (line 359) * thread state, waiting for delay_list: delayed-insert-thread-states. (line 44) * thread state, Waiting for event from ndbcluster: mysql-cluster-thread-states. (line 25) * thread state, Waiting for first event from ndbcluster: mysql-cluster-thread-states. (line 30) * thread state, waiting for handler insert: delayed-insert-thread-states. (line 51) * thread state, waiting for handler lock: delayed-insert-thread-states. (line 56) * thread state, waiting for handler open: delayed-insert-thread-states. (line 62) * thread state, Waiting for INSERT: delayed-insert-thread-states. (line 86) * thread state, Waiting for master to send event: slave-io-thread-states. (line 49) * thread state, Waiting for master update: slave-io-thread-states. (line 12) * thread state, Waiting for ndbcluster binlog update to reach current position: mysql-cluster-thread-states. (line 32) * thread state, Waiting for ndbcluster to start: mysql-cluster-thread-states. (line 34) * thread state, Waiting for next activation: event-scheduler-thread-states. (line 20) * thread state, Waiting for release of readlock: general-thread-states. (line 363) * thread state, Waiting for scheduler to stop: event-scheduler-thread-states. (line 25) * thread state, Waiting for schema epoch: mysql-cluster-thread-states. (line 36) * thread state, Waiting for slave mutex on exit <1>: slave-sql-thread-states. (line 31) * thread state, Waiting for slave mutex on exit: slave-io-thread-states. (line 84) * thread state, Waiting for table: general-thread-states. (line 369) * thread state, Waiting for tables: general-thread-states. (line 369) * thread state, Waiting for the next event in relay log: slave-sql-thread-states. (line 9) * thread state, Waiting for the slave SQL thread to free enough relay log space: slave-io-thread-states. (line 76) * thread state, Waiting on cond: general-thread-states. (line 383) * thread state, Waiting on empty queue: event-scheduler-thread-states. (line 30) * thread state, Waiting to finalize termination: master-thread-states. (line 29) * thread state, Waiting to get readlock: general-thread-states. (line 388) * thread state, Waiting to reconnect after a failed binlog dump request: slave-io-thread-states. (line 37) * thread state, Waiting to reconnect after a failed master event read: slave-io-thread-states. (line 62) * thread state, Writing to net: general-thread-states. (line 394) * thread states: thread-information. (line 19) * thread states, delayed inserts: delayed-insert-thread-states. (line 6) * thread states, event scheduler: event-scheduler-thread-states. (line 6) * thread states, general: general-thread-states. (line 6) * thread states, MySQL Cluster: mysql-cluster-thread-states. (line 6) * thread states, query cache: query-cache-thread-states. (line 6) * thread states, replication master: master-thread-states. (line 6) * thread states, replication slave <1>: slave-connection-thread-states. (line 6) * thread states, replication slave <2>: slave-sql-thread-states. (line 6) * thread states, replication slave: slave-io-thread-states. (line 6) * thread support: supported-os. (line 6) * thread_cache_size system variable: server-system-variables. (line 5640) * thread_concurrency system variable: server-system-variables. (line 5673) * thread_handling system variable: server-system-variables. (line 5697) * thread_stack system variable: server-system-variables. (line 5722) * threadblocks, ndbinfo table: mysql-cluster-ndbinfo-threadblocks. (line 6) * ThreadConfig: mysql-cluster-ndbd-definition. (line 3313) * threaded clients: c-api-threaded-clients. (line 6) * ThreadPool: mysql-cluster-ndbd-definition. (line 3490) * threads <1>: mysql-internals. (line 11) * threads <2>: show-processlist. (line 6) * threads: mysqladmin. (line 169) * threads, display: show-processlist. (line 6) * threads, monitoring <1>: processlist-table. (line 6) * threads, monitoring <2>: show-processlist. (line 6) * threads, monitoring: thread-information. (line 19) * threadstat, ndbinfo table: mysql-cluster-ndbinfo-threadstat. (line 6) * TIME columns, with Connector/Net: connector-net-programming-datetime. (line 14) * TIME data type <1>: time. (line 6) * TIME data type: date-and-time-type-overview. (line 62) * time literals: date-and-time-literals. (line 6) * time representation, Event Scheduler: events-metadata. (line 21) * time types: storage-requirements. (line 130) * time zone problems: timezone-problems. (line 6) * time zone tables: mysql-tzinfo-to-sql. (line 6) * time zones, and replication: replication-features-timezone. (line 6) * time zones, leap seconds: time-zone-leap-seconds. (line 6) * time zones, support: time-zone-support. (line 11) * time zones, upgrading: time-zone-upgrades. (line 6) * TIME(): date-and-time-functions. (line 958) * Time, thread command: thread-commands. (line 132) * time_format system variable: server-system-variables. (line 5760) * TIME_FORMAT(): date-and-time-functions. (line 1046) * TIME_TO_SEC(): date-and-time-functions. (line 1061) * time_zone system variable: server-system-variables. (line 5764) * TimeBetweenEpochs: mysql-cluster-ndbd-definition. (line 2101) * TimeBetweenEpochsTimeout: mysql-cluster-ndbd-definition. (line 2119) * TimeBetweenGlobalCheckpoints: mysql-cluster-ndbd-definition. (line 2070) * TimeBetweenInactiveTransactionAbortCheck: mysql-cluster-ndbd-definition. (line 2209) * TimeBetweenLocalCheckpoints: mysql-cluster-ndbd-definition. (line 2040) * TimeBetweenWatchDogCheck: mysql-cluster-ndbd-definition. (line 1740) * TimeBetweenWatchDogCheckInitial: mysql-cluster-ndbd-definition. (line 1762) * timed_mutexes system variable: server-system-variables. (line 5784) * TIMEDIFF(): date-and-time-functions. (line 972) * timeout <1>: insert-delayed. (line 128) * timeout <2>: miscellaneous-functions. (line 42) * timeout: server-system-variables. (line 1113) * timeout option, ndb_waiter: mysql-cluster-programs-ndb-waiter. (line 90) * timeout, connect_timeout variable <1>: mysqladmin. (line 447) * timeout, connect_timeout variable: mysql-command-options. (line 614) * timeout, shutdown_timeout variable: mysqladmin. (line 452) * timeouts (replication): replication-features-timeout. (line 6) * TIMESTAMP data type <1>: datetime. (line 6) * TIMESTAMP data type: date-and-time-type-overview. (line 31) * timestamp session variable: server-system-variables. (line 5808) * TIMESTAMP(): date-and-time-functions. (line 990) * TIMESTAMP, and logs: upgrading-from-previous-series. (line 758) * TIMESTAMP, and NULL values: problems-with-null. (line 71) * TIMESTAMP, and replication <1>: replication-features-timestamp. (line 6) * TIMESTAMP, and replication <2>: replication-features-auto-increment. (line 6) * TIMESTAMP, and replication: upgrading-from-previous-series. (line 758) * TIMESTAMP, initialization and updating: timestamp-initialization. (line 6) * TIMESTAMPADD(): date-and-time-functions. (line 1002) * TIMESTAMPDIFF(): date-and-time-functions. (line 1023) * timezone option, mysqld_safe: mysqld-safe. (line 249) * TINYBLOB data type: string-type-overview. (line 165) * TINYINT data type: numeric-type-overview. (line 40) * TINYTEXT data type: string-type-overview. (line 171) * tips, optimization: miscellaneous-optimization-tips. (line 6) * tmp_table_size system variable: server-system-variables. (line 5822) * TMPDIR environment variable <1>: temporary-files. (line 6) * TMPDIR environment variable <2>: programs-overview. (line 304) * TMPDIR environment variable <3>: environment-variables. (line 18) * TMPDIR environment variable: mysql-install-db-problems. (line 84) * tmpdir option, myisamchk: myisamchk-repair-options. (line 121) * tmpdir option, myisampack: myisampack. (line 101) * tmpdir option, mysql_upgrade: mysql-upgrade. (line 147) * tmpdir option, mysqld: server-options. (line 2252) * tmpdir option, mysqlhotcopy: mysqlhotcopy. (line 183) * tmpdir system variable: server-system-variables. (line 5859) * to-last-log option, mysqlbinlog: mysqlbinlog. (line 519) * TO_DAYS(): date-and-time-functions. (line 1070) * Tomcat application server: connector-j-usagenotes-tomcat. (line 6) * tools, command-line: mysql. (line 15) * tools, list of: tools-used-to-create-mysql. (line 6) * tools, mysqld_multi: mysqld-multi. (line 6) * tools, mysqld_safe: mysqld-safe. (line 6) * TotalSendBufferMemory, API and SQL nodes: mysql-cluster-api-definition. (line 250) * TotalSendBufferMemory, data nodes: mysql-cluster-ndbd-definition. (line 3865) * TotalSendBufferMemory, management nodes: mysql-cluster-mgm-definition. (line 284) * Touches(): functions-that-test-spatial-relationships-between-geometries. (line 60) * trace DBI method: using-gdb-on-mysqld. (line 89) * trace files (MySQL Cluster): mysql-cluster-programs-ndbd. (line 474) * trace files, ndbmtd: mysql-cluster-programs-ndbmtd. (line 67) * tracing, with Connector/Net: connector-net-programming-tracing. (line 11) * TRADITIONAL SQL mode: server-sql-mode. (line 91) * transaction isolation level: set-transaction. (line 6) * transaction isolation level, READ COMMITTED: set-transaction. (line 115) * transaction isolation level, READ UNCOMMITTED: set-transaction. (line 141) * transaction isolation level, REPEATABLE READ: set-transaction. (line 93) * transaction isolation level, SERIALIZABLE: set-transaction. (line 149) * transaction-isolation option, mysqld: server-options. (line 2229) * transaction-safe tables <1>: innodb-storage-engine. (line 22) * transaction-safe tables: ansi-diff-transactions. (line 6) * transaction_alloc_block_size system variable: server-system-variables. (line 5895) * transaction_allow_batching session variable (MySQL Cluster): mysql-cluster-system-variables. (line 939) * transaction_prealloc_size system variable: server-system-variables. (line 5930) * transactional option, ndb_delete_all: mysql-cluster-programs-ndb-delete-all. (line 45) * TransactionBufferMemory: mysql-cluster-ndbd-definition. (line 834) * TransactionDeadlockDetectionTimeout: mysql-cluster-ndbd-definition. (line 2244) * TransactionInactiveTimeout: mysql-cluster-ndbd-definition. (line 2226) * transactions: innodb-transaction-model. (line 18) * transactions, and replication <1>: replication-features-transactions. (line 6) * transactions, and replication: replication-features-timeout. (line 6) * transactions, isolation levels: innodb-transaction-model. (line 18) * transactions, support <1>: innodb-storage-engine. (line 22) * transactions, support: ansi-diff-transactions. (line 6) * Translators, list of: documenters-translators. (line 6) * transporters, ndbinfo table: mysql-cluster-ndbinfo-transporters. (line 6) * trigger, restrictions: stored-program-restrictions. (line 6) * triggers <1>: triggers. (line 11) * triggers <2>: stored-programs-views. (line 16) * triggers <3>: show-triggers. (line 6) * triggers <4>: drop-trigger. (line 6) * triggers: create-trigger. (line 6) * triggers option, mysqldump: mysqldump. (line 999) * triggers, and INSERT DELAYED: insert. (line 230) * triggers, and replication <1>: replication-features-triggers. (line 6) * triggers, and replication: replication-features-invoked. (line 6) * triggers, editing with Visual Studio: connector-net-visual-studio-editing-triggers. (line 6) * TRIGGERS, INFORMATION_SCHEMA table: triggers-table. (line 6) * triggers, LAST_INSERT_ID(): stored-routines-last-insert-id. (line 6) * triggers, metadata: trigger-metadata. (line 6) * TRIM(): string-functions. (line 704) * troubleshooting, Connector/J: connector-j-usagenotes-troubleshooting. (line 6) * troubleshooting, Connector/ODBC connection problems: connector-odbc-configuration-dsn-windows-problems. (line 6) * troubleshooting, FreeBSD: compilation-problems. (line 136) * troubleshooting, JDBC: connector-j-installing-upgrading-issues. (line 6) * troubleshooting, JDBC SQLState codes: connector-j-reference-error-sqlstates. (line 6) * troubleshooting, PHP: apis-php-problems. (line 6) * troubleshooting, Solaris: compilation-problems. (line 136) * troubleshooting, with MySQL Enterprise Monitor: mysql-enterprise-monitor. (line 6) * TRUE <1>: boolean-literals. (line 6) * TRUE: number-literals. (line 6) * TRUE, testing for: comparison-operators. (line 130) * TRUNCATE TABLE: truncate-table. (line 6) * TRUNCATE TABLE, and MySQL Cluster: mysql-cluster-limitations-limits. (line 9) * TRUNCATE TABLE, and replication: replication-features-truncate. (line 6) * TRUNCATE(): mathematical-functions. (line 560) * tupscan option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 133) * tutorial: tutorial. (line 16) * TwoPassInitialNodeRestartCopy: mysql-cluster-ndbd-definition. (line 3192) * tx_isolation system variable: server-system-variables. (line 5973) * type codes, C prepared statement API: c-api-prepared-statement-type-codes. (line 6) * type conversions <1>: comparison-operators. (line 38) * type conversions: type-conversion. (line 6) * type option, mysql_convert_table_format: mysql-convert-table-format. (line 54) * type option, ndb_config: mysql-cluster-programs-ndb-config. (line 324) * type option, ndb_show_tables: mysql-cluster-programs-ndb-show-tables. (line 69) * Types namespace: connector-net-ref-types. (line 12) * types, columns <1>: choosing-types. (line 6) * types, columns: data-types. (line 31) * types, data: data-types. (line 31) * types, date: storage-requirements. (line 130) * types, Date and Time: date-and-time-types. (line 17) * types, numeric: storage-requirements. (line 83) * types, of tables: storage-engines. (line 23) * types, portability: other-vendor-data-types. (line 6) * types, string: storage-requirements. (line 145) * types, strings: string-types. (line 14) * types, time: storage-requirements. (line 130) * typographical conventions: manual-conventions. (line 8) * TZ environment variable <1>: timezone-problems. (line 6) * TZ environment variable: environment-variables. (line 18) * tz-utc option, mysqldump: mysqldump. (line 1004) * UCASE(): string-functions. (line 723) * UCS-2: charset. (line 22) * ucs2 character set: charset-unicode-ucs2. (line 6) * UDFs <1>: drop-function-udf. (line 6) * UDFs: create-function-udf. (line 6) * UDFs, compiling: udf-compiling. (line 6) * UDFs, defined: adding-functions. (line 12) * UDFs, return values: udf-return-values. (line 6) * ulimit: not-enough-file-handles. (line 33) * UMASK environment variable <1>: file-permissions. (line 6) * UMASK environment variable: environment-variables. (line 18) * UMASK_DIR environment variable <1>: file-permissions. (line 20) * UMASK_DIR environment variable: environment-variables. (line 18) * unary minus (-): arithmetic-functions. (line 69) * unbuffered option, mysql: mysql-command-options. (line 534) * UNCOMPRESS(): encryption-functions. (line 394) * UNCOMPRESSED_LENGTH(): encryption-functions. (line 407) * UndoDataBuffer: mysql-cluster-ndbd-definition. (line 2589) * UndoIndexBuffer: mysql-cluster-ndbd-definition. (line 2546) * UNHEX(): string-functions. (line 727) * Unicode: charset. (line 22) * Unicode Collation Algorithm: charset-unicode-sets. (line 71) * Unicode, with Connector/J: connector-j-reference-charsets. (line 6) * UNINSTALL PLUGIN: uninstall-plugin. (line 6) * uninstalling plugins <1>: uninstall-plugin. (line 6) * uninstalling plugins: server-plugin-loading. (line 6) * UNION <1>: union. (line 6) * UNION: searching-on-two-keys. (line 6) * Union(): spatial-operators. (line 36) * UNIQUE: alter-table. (line 364) * unique ID: getting-unique-id. (line 6) * unique key, constraint: constraint-primary-key. (line 6) * unique keys, and partitioning keys: partitioning-limitations-partitioning-keys-unique-keys. (line 6) * unique_checks session variable: server-system-variables. (line 6009) * unique_subquery join type, optimizer: explain-output. (line 325) * Unix <1>: connector-net. (line 20) * Unix: connector-odbc. (line 17) * Unix, compiling clients on: c-api-building-clients. (line 11) * UNIX_TIMESTAMP(): date-and-time-functions. (line 1127) * UNKNOWN, testing for: comparison-operators. (line 130) * unloading, tables: retrieving-data. (line 18) * UNLOCK TABLES: lock-tables. (line 12) * unnamed views: from-clause-subqueries. (line 6) * unpack option, myisamchk: myisamchk-repair-options. (line 131) * unqualified option, ndb_desc: mysql-cluster-programs-ndb-desc. (line 327) * unqualified option, ndb_show_tables: mysql-cluster-programs-ndb-show-tables. (line 83) * unsafe statement (replication), defined: replication-rbr-safe-unsafe. (line 6) * unsafe statements (replication): replication-rbr-safe-unsafe. (line 40) * UNSIGNED <1>: numeric-types. (line 15) * UNSIGNED: numeric-type-overview. (line 6) * UNTIL: repeat. (line 6) * updatable views: view-updatability. (line 6) * updatable_views_with_limit system variable: server-system-variables. (line 6033) * UPDATE <1>: update. (line 6) * UPDATE: ansi-diff-update. (line 6) * update option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 152) * update, thread state: general-thread-states. (line 333) * update-state option, myisamchk: myisamchk-check-options. (line 62) * UpdateXML(): xml-functions. (line 278) * updating main table, thread state: general-thread-states. (line 341) * updating reference tables, thread state: general-thread-states. (line 347) * updating, releases of MySQL: many-versions. (line 6) * updating, tables: ansi-diff-transactions. (line 6) * Updating, thread state: general-thread-states. (line 337) * upgrades and downgrades (MySQL Cluster), compatibility between versions: mysql-cluster-upgrade-downgrade. (line 12) * upgrades, MySQL Cluster <1>: mysql-cluster-rolling-restart. (line 6) * upgrades, MySQL Cluster: mysql-cluster-upgrade-downgrade. (line 12) * upgrading <1>: upgrading. (line 10) * upgrading: upgrading-downgrading. (line 14) * upgrading lock, thread state: delayed-insert-thread-states. (line 81) * upgrading MySQL: mysql-upgrade. (line 6) * upgrading, different architecture: copying-databases. (line 6) * upgrading, grant tables: mysql-fix-privilege-tables. (line 6) * upgrading, to ¤t-series;: upgrading-from-previous-series. (line 6) * UPPER(): string-functions. (line 770) * uptime: mysqladmin. (line 165) * URLs for downloading MySQL: getting-mysql. (line 6) * usage option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 88) * usage option, ndb_config: mysql-cluster-programs-ndb-config. (line 95) * USE: use. (line 6) * use command, mysql: mysql-commands. (line 231) * USE INDEX: index-hints. (line 6) * USE KEY: index-hints. (line 6) * use-frm option, mysqlcheck: mysqlcheck. (line 396) * use-manager option, mysql.server: mysql-server. (line 63) * use-mysqld_safe option, mysql.server: mysql-server. (line 58) * use-threads option, mysqlimport: mysqlimport. (line 296) * use-threads option, mysqlslap: mysqlslap. (line 473) * useConfigs connection properties: connector-j-useconfigs. (line 6) * useHexFormat option, ndb_select_all: mysql-cluster-programs-ndb-select-all. (line 103) * user accounts, creating: create-user. (line 6) * user accounts, renaming: rename-user. (line 6) * user accounts, resource limits <1>: grant. (line 462) * user accounts, resource limits <2>: user-resources. (line 6) * user accounts, resource limits: server-system-variables. (line 3324) * USER environment variable <1>: connecting. (line 235) * USER environment variable: environment-variables. (line 18) * User lock, thread state: general-thread-states. (line 352) * user names, and passwords: user-names. (line 6) * user option: connecting. (line 214) * user option, mysql: mysql-command-options. (line 538) * user option, mysql.server: mysql-server. (line 67) * user option, mysql_convert_table_format: mysql-convert-table-format. (line 59) * user option, mysql_install_db: mysql-install-db. (line 88) * user option, mysql_setpermission: mysql-setpermission. (line 55) * user option, mysql_upgrade: mysql-upgrade. (line 152) * user option, mysqlaccess: mysqlaccess. (line 156) * user option, mysqladmin: mysqladmin. (line 421) * user option, mysqlbinlog: mysqlbinlog. (line 527) * user option, mysqlcheck: mysqlcheck. (line 402) * user option, mysqld: server-options. (line 2285) * user option, mysqld_multi: mysqld-multi. (line 167) * user option, mysqld_safe: mysqld-safe. (line 255) * user option, mysqldump: mysqldump. (line 1018) * user option, mysqlhotcopy: mysqlhotcopy. (line 187) * user option, mysqlimport: mysqlimport. (line 292) * user option, mysqlmanager: instance-manager-command-options. (line 224) * user option, mysqlshow: mysqlshow. (line 216) * user option, mysqlslap: mysqlslap. (line 480) * user privileges, adding: adding-users. (line 6) * user privileges, deleting <1>: drop-user. (line 6) * user privileges, deleting: removing-users. (line 6) * user privileges, dropping <1>: drop-user. (line 6) * user privileges, dropping: removing-users. (line 6) * User sleep, thread state: general-thread-states. (line 359) * user table, sorting: connection-access. (line 126) * user variables: user-variables. (line 6) * user variables, and replication: replication-features-variables. (line 6) * USER(): information-functions. (line 568) * User-defined functions <1>: drop-function-udf. (line 6) * User-defined functions: create-function-udf. (line 6) * user-defined functions, adding <1>: adding-udf. (line 15) * user-defined functions, adding: adding-functions. (line 12) * user-defined functions, editing with Visual Studio: connector-net-visual-studio-editing-user-defined-functions-udf. (line 6) * USER_PRIVILEGES, INFORMATION_SCHEMA table: user-privileges-table. (line 6) * username option, mysqlmanager: instance-manager-command-options. (line 235) * users, adding: unix-postinstallation. (line 371) * users, deleting <1>: drop-user. (line 6) * users, deleting: removing-users. (line 6) * users, root: default-privileges. (line 6) * using multiple disks to start data: windows-symbolic-links. (line 6) * using MySQL Cluster programs: mysql-cluster-programs. (line 34) * UTC_DATE(): date-and-time-functions. (line 1185) * UTC_TIME(): date-and-time-functions. (line 1194) * UTC_TIMESTAMP(): date-and-time-functions. (line 1203) * UTF-8: charset. (line 22) * utf8 character set: charset-unicode-utf8. (line 6) * utilities, program-development: programs-overview. (line 256) * utility programs: programs-overview. (line 165) * UUID(): miscellaneous-functions. (line 226) * UUID_SHORT(): miscellaneous-functions. (line 275) * valid numbers, examples: number-literals. (line 6) * VALUES(): miscellaneous-functions. (line 310) * VAR_POP(): group-by-functions. (line 271) * VAR_SAMP(): group-by-functions. (line 280) * VARBINARY data type <1>: binary-varbinary. (line 6) * VARBINARY data type: string-type-overview. (line 158) * VARCHAR data type <1>: string-types. (line 14) * VARCHAR data type: string-type-overview. (line 121) * VARCHAR, size: storage-requirements. (line 190) * VARCHARACTER data type: string-type-overview. (line 121) * variables, and replication: replication-features-variables. (line 6) * variables, environment: programs-overview. (line 301) * variables, mysqld: server-parameters. (line 11) * variables, server: show-variables. (line 6) * variables, status <1>: show-status. (line 6) * variables, status: server-status-variables. (line 6) * variables, system <1>: show-variables. (line 6) * variables, system <2>: using-system-variables. (line 11) * variables, system: server-system-variables. (line 6) * variables, user: user-variables. (line 6) * VARIANCE(): group-by-functions. (line 287) * verbose option (ndb_index_stat): mysql-cluster-programs-ndb-index-stat. (line 306) * verbose option (ndb_restore): mysql-cluster-programs-ndb-restore. (line 653) * verbose option, my_print_defaults: my-print-defaults. (line 57) * verbose option, myisam_ftdump: myisam-ftdump. (line 79) * verbose option, myisamchk: myisamchk-general-options. (line 32) * verbose option, myisampack: myisampack. (line 106) * verbose option, mysql: mysql-command-options. (line 542) * verbose option, mysql_convert_table_format: mysql-convert-table-format. (line 63) * verbose option, mysql_install_db: mysql-install-db. (line 97) * verbose option, mysql_upgrade: mysql-upgrade. (line 157) * verbose option, mysql_waitpid: mysql-waitpid. (line 31) * verbose option, mysqladmin: mysqladmin. (line 425) * verbose option, mysqlbinlog: mysqlbinlog. (line 531) * verbose option, mysqlcheck: mysqlcheck. (line 406) * verbose option, mysqld: server-options. (line 2320) * verbose option, mysqld_multi: mysqld-multi. (line 172) * verbose option, mysqldump: mysqldump. (line 1022) * verbose option, mysqldumpslow: mysqldumpslow. (line 103) * verbose option, mysqlimport: mysqlimport. (line 301) * verbose option, mysqlshow: mysqlshow. (line 220) * verbose option, mysqlslap: mysqlslap. (line 484) * verbose option, ndb_blob_tool: mysql-cluster-programs-ndb-blob-tool. (line 125) * verbose option, perror: perror. (line 52) * version option (MySQL Cluster programs): mysql-cluster-program-options-common. (line 222) * version option, comp_err: comp-err. (line 70) * version option, my_print_defaults: my-print-defaults. (line 61) * version option, myisamchk: myisamchk-general-options. (line 38) * version option, myisampack: myisampack. (line 111) * version option, mysql: mysql-command-options. (line 549) * version option, mysql_config: mysql-config. (line 54) * version option, mysql_convert_table_format: mysql-convert-table-format. (line 67) * version option, mysql_waitpid: mysql-waitpid. (line 36) * version option, mysqlaccess: mysqlaccess. (line 160) * version option, mysqladmin: mysqladmin. (line 429) * version option, mysqlbinlog: mysqlbinlog. (line 542) * version option, mysqlcheck: mysqlcheck. (line 411) * version option, mysqld: server-options. (line 2324) * version option, mysqld_multi: mysqld-multi. (line 176) * version option, mysqldump: mysqldump. (line 1026) * version option, mysqlimport: mysqlimport. (line 305) * version option, mysqlmanager: instance-manager-command-options. (line 240) * version option, mysqlshow: mysqlshow. (line 226) * version option, mysqlslap: mysqlslap. (line 490) * version option, ndb_config: mysql-cluster-programs-ndb-config. (line 132) * version option, perror: perror. (line 57) * version option, resolve_stack_dump: resolve-stack-dump. (line 33) * version option, resolveip: resolveip. (line 23) * version system variable: server-system-variables. (line 6065) * VERSION(): information-functions. (line 585) * version, choosing: which-version. (line 18) * version, latest: getting-mysql. (line 6) * version_comment system variable: server-system-variables. (line 6073) * version_compile_machine system variable: server-system-variables. (line 6089) * version_compile_os system variable: server-system-variables. (line 6103) * vertical option, mysql: mysql-command-options. (line 553) * vertical option, mysqladmin: mysqladmin. (line 433) * Vietnamese: faqs-cjk. (line 6) * view, restrictions: view-restrictions. (line 6) * views <1>: views. (line 13) * views <2>: stored-programs-views. (line 16) * views: create-view. (line 6) * views, algorithms: view-algorithms. (line 6) * views, and replication: replication-features-views. (line 6) * VIEWS, INFORMATION_SCHEMA table: views-table. (line 6) * Views, limitations: view-restrictions. (line 111) * views, metadata: view-metadata. (line 6) * Views, privileges: view-restrictions. (line 111) * Views, problems: view-restrictions. (line 111) * views, updatable <1>: view-updatability. (line 6) * views, updatable: create-view. (line 6) * virtual memory, problems while compiling: compilation-problems. (line 37) * Vision: connector-odbc-usagenotes-apptips-vision. (line 6) * Visual Objects: connector-odbc-usagenotes-apptips-microsoft-visualobjects. (line 6) * Visual Studio <1>: connector-net-visual-studio. (line 23) * Visual Studio <2>: connector-net. (line 20) * Visual Studio: windows-source-build. (line 6) * WAIT COMPLETED (START BACKUP command): mysql-cluster-backup-using-management-client. (line 59) * wait option, myisamchk: myisamchk-general-options. (line 42) * wait option, myisampack: myisampack. (line 115) * wait option, mysql: mysql-command-options. (line 559) * wait option, mysqladmin: mysqladmin. (line 438) * WAIT STARTED (START BACKUP command): mysql-cluster-backup-using-management-client. (line 51) * wait-nodes option, ndb_waiter: mysql-cluster-programs-ndb-waiter. (line 114) * wait-timeout option, mysqlmanager: instance-manager-command-options. (line 244) * wait_timeout system variable: server-system-variables. (line 6117) * waiting for delay_list, thread state: delayed-insert-thread-states. (line 44) * Waiting for event from ndbcluster, thread state: mysql-cluster-thread-states. (line 25) * Waiting for first event from ndbcluster, thread state: mysql-cluster-thread-states. (line 30) * waiting for handler insert, thread state: delayed-insert-thread-states. (line 51) * waiting for handler lock, thread state: delayed-insert-thread-states. (line 56) * waiting for handler open, thread state: delayed-insert-thread-states. (line 62) * Waiting for INSERT, thread state: delayed-insert-thread-states. (line 86) * Waiting for master to send event, thread state: slave-io-thread-states. (line 49) * Waiting for master update, thread state: slave-io-thread-states. (line 12) * Waiting for ndbcluster binlog update to reach current position, thread state: mysql-cluster-thread-states. (line 32) * Waiting for ndbcluster to start, thread state: mysql-cluster-thread-states. (line 34) * Waiting for next activation, thread state: event-scheduler-thread-states. (line 20) * Waiting for release of readlock, thread state: general-thread-states. (line 363) * Waiting for scheduler to stop, thread state: event-scheduler-thread-states. (line 25) * Waiting for schema epoch, thread state: mysql-cluster-thread-states. (line 36) * Waiting for slave mutex on exit, thread state <1>: slave-sql-thread-states. (line 31) * Waiting for slave mutex on exit, thread state: slave-io-thread-states. (line 84) * Waiting for table, thread state: general-thread-states. (line 369) * Waiting for tables, thread state: general-thread-states. (line 369) * Waiting for the next event in relay log, thread state: slave-sql-thread-states. (line 9) * Waiting for the slave SQL thread to free enough relay log space, thread state: slave-io-thread-states. (line 76) * Waiting on cond, thread state: general-thread-states. (line 383) * Waiting on empty queue, thread state: event-scheduler-thread-states. (line 30) * Waiting to finalize termination, thread state: master-thread-states. (line 29) * Waiting to get readlock, thread state: general-thread-states. (line 388) * Waiting to reconnect after a failed binlog dump request, thread state: slave-io-thread-states. (line 37) * Waiting to reconnect after a failed master event read, thread state: slave-io-thread-states. (line 62) * warning_count session variable: server-system-variables. (line 6155) * warnings command, mysql: mysql-commands. (line 235) * Website Configuration Tool: connector-net-website-config. (line 6) * WEEK(): date-and-time-functions. (line 1212) * WEEKDAY(): date-and-time-functions. (line 1275) * WEEKOFYEAR(): date-and-time-functions. (line 1285) * Well-Known Binary format: gis-wkb-format. (line 6) * Well-Known Text format: gis-wkt-format. (line 6) * WHERE: where-optimizations. (line 6) * where option, mysqldump: mysqldump. (line 1030) * WHERE, with SHOW <1>: extended-show. (line 6) * WHERE, with SHOW: information-schema. (line 36) * WHILE: while. (line 6) * WHILE, labels: statement-labels. (line 6) * widths, display: data-types. (line 33) * Wildcard character (%): string-literals. (line 77) * Wildcard character (_): string-literals. (line 78) * wildcards, and LIKE: mysql-indexes. (line 111) * wildcards, in account names: account-names. (line 72) * wildcards, in mysql.columns_priv table: request-access. (line 59) * wildcards, in mysql.db table: request-access. (line 26) * wildcards, in mysql.host table: request-access. (line 26) * wildcards, in mysql.procs_priv table: request-access. (line 59) * wildcards, in mysql.tables_priv table: request-access. (line 59) * Windows <1>: connector-net. (line 20) * Windows: connector-odbc. (line 17) * Windows Failover Clustering: ha-wfc. (line 6) * windows option, mysql_install_db: mysql-install-db. (line 101) * Windows Server Failover Clustering: ha-wfc. (line 6) * Windows, compiling clients on: c-api-building-clients. (line 48) * Windows, MySQL limitations <1>: limits-windows. (line 6) * Windows, MySQL limitations: limits-frm-file. (line 6) * Windows, path name separators: option-files. (line 194) * Windows, upgrading: windows-upgrading. (line 6) * with-big-tables option: source-configuration-options. (line 6) * with-big-tables option, configure: source-configuration-options. (line 527) * with-client-ldflags option, configure: source-configuration-options. (line 389) * with-debug option, configure: source-configuration-options. (line 476) * with-embedded-server option, configure: source-configuration-options. (line 346) * with-extra-charsets option, configure: source-configuration-options. (line 461) * with-tcp-port option, configure: source-configuration-options. (line 370) * with-unix-socket-path option, configure: source-configuration-options. (line 377) * with-zlib-dir option, configure: source-configuration-options. (line 518) * Within(): functions-that-test-spatial-relationships-between-geometries. (line 67) * without-server option: source-configuration-options. (line 6) * without-server option, configure: source-configuration-options. (line 332) * WKB format: gis-wkb-format. (line 6) * WKT format: gis-wkt-format. (line 6) * wrappers, Eiffel: apis-eiffel. (line 6) * write access, tmp: mysql-install-db-problems. (line 70) * write-binlog option, mysql_upgrade: mysql-upgrade. (line 161) * write-binlog option, mysqlcheck: mysqlcheck. (line 415) * write_buffer_size myisamchk variable: myisamchk-general-options. (line 53) * Writing to net, thread state: general-thread-states. (line 394) * X(): point-property-functions. (line 9) * X509/Certificate: ssl-basics. (line 30) * XA BEGIN: xa-statements. (line 6) * XA COMMIT: xa-statements. (line 6) * XA PREPARE: xa-statements. (line 6) * XA RECOVER: xa-statements. (line 6) * XA ROLLBACK: xa-statements. (line 6) * XA START: xa-statements. (line 6) * XA transactions: xa. (line 11) * XA transactions, restrictions: xa-restrictions. (line 6) * XA transactions, transaction identifiers: xa-statements. (line 6) * xid, XA transaction identifier: xa-statements. (line 6) * xml option, mysql: mysql-command-options. (line 564) * xml option, mysqldump: mysqldump. (line 1042) * xml option, ndb_config: mysql-cluster-programs-ndb-config. (line 439) * XOR, bitwise: bit-functions. (line 38) * XOR, logical: logical-operators. (line 84) * Y(): point-property-functions. (line 21) * yaSSL: configuring-for-ssl. (line 6) * YEAR data type <1>: year. (line 6) * YEAR data type: date-and-time-type-overview. (line 69) * YEAR(): date-and-time-functions. (line 1294) * YEARWEEK(): date-and-time-functions. (line 1302) * Yen sign (Japanese): faqs-cjk. (line 6) * ZEROFILL <1>: c-api-prepared-statement-problems. (line 13) * ZEROFILL <2>: numeric-types. (line 15) * ZEROFILL: numeric-type-overview. (line 6) * ZFS: ha-zfs-replication. (line 12) * | (bitwise OR): bit-functions. (line 20) * || (logical OR): logical-operators. (line 65) * ~ (invert bits): bit-functions. (line 75)  Tag Table: Node: Top167 Node: preface1943 Ref: legalnotice2988 Node: introduction8511 Node: manual-info11740 Node: manual-conventions14074 Node: what-is19204 Node: what-is-mysql19585 Node: features25009 Node: history34742 Node: mysql-nutshell35878 Node: development-history45238 Node: information-sources46698 Node: mailing-lists47307 Node: mailing-list-use52298 Node: forums53403 Node: irc53950 Node: mysql-enterprise-information54910 Node: bug-reports55700 Node: compatibility73657 Node: standards76353 Node: sql-mode76666 Node: ansi-mode77658 Node: extensions-to-ansi78855 Node: differences-from-ansi88769 Node: ansi-diff-select-into-table89916 Node: ansi-diff-update90822 Node: ansi-diff-transactions91411 Node: ansi-diff-foreign-keys100194 Node: ansi-diff-comments104974 Node: constraints107643 Node: constraint-primary-key109668 Node: constraint-foreign-key111037 Ref: constraint-foreign-key-deviations113896 Node: constraint-invalid-data116217 Node: constraint-enum122038 Node: credits124654 Node: contributors125186 Node: documenters-translators133996 Node: packages136413 Node: tools-used-to-create-mysql137614 Node: supporters138644 Node: installing139582 Node: general-installation-issues145486 Node: supported-os146569 Node: which-version150114 Node: choosing-version150864 Node: choosing-distribution-format157334 Node: many-versions160495 Node: getting-mysql162387 Node: verifying-package-integrity163032 Node: verifying-md5-checksum164193 Node: checking-gpg-signature166353 Node: checking-gpg-signature-windows173812 Ref: gnupg-kleopatra-home174500 Ref: gnupg-kleopatra-find-certificate174746 Ref: gnupg-kleopatra-change-trust175496 Ref: gnupg-kleopatra-decrypt-load176482 Ref: gnupg-kleopatra-decrypt-okay-sig176779 Ref: gnupg-kleopatra-decrypt-invalid-sig176952 Node: checking-rpm-signature177116 Node: installation-layouts178618 Node: compiler-characteristics179500 Node: binary-installation180094 Ref: binary-installation-layout182787 Ref: binary-installation-createsysuser185122 Ref: binary-installation-unpack186024 Ref: binary-installation-postinstall187443 Node: windows-installation187884 Node: windows-installation-layout194178 Node: windows-choosing-package197421 Ref: installer-windows-workflow-msi199669 Ref: installer-windows-workflow-zip199801 Node: windows-using-installer202306 Ref: installer-windows-workflow-installer203806 Node: windows-install-wizard205978 Node: mysql-install-wizard-starting208473 Node: mysql-install-wizard-install-type209229 Node: mysql-install-wizard-custom-install210757 Node: mysql-install-wizard-confirmation-dialog211818 Node: mysql-install-wizard-changes213142 Node: mysql-install-wizard-upgrading217103 Node: windows-installer-msi-quiet219431 Node: windows-installer-uninstalling221589 Node: windows-notifier223777 Ref: windows-notifier-server-instance227554 Ref: windows-notifier-actions228115 Ref: windows-notifier-options229543 Ref: windows-notifier-manage-services229764 Ref: windows-notifier-manage-instances229874 Ref: windows-notifier-add-services230332 Ref: windows-notifier-add-instances230424 Node: windows-notifier-installation230591 Ref: windows-notifier-installation-wmi232054 Ref: windows-notifier-installation-errors242151 Node: mysql-config-wizard243423 Ref: installer-windows-instance-workflow245626 Node: mysql-config-wizard-starting245690 Node: mysql-config-wizard-maintenance248841 Node: mysql-config-wizard-configuration-type250242 Node: mysql-config-wizard-server-type252068 Node: mysql-config-wizard-database-usage253805 Node: mysql-config-wizard-tablespace256058 Node: mysql-config-wizard-connections257222 Node: mysql-config-wizard-networking258738 Node: mysql-config-wizard-character-set260091 Node: mysql-config-wizard-service261363 Node: mysql-config-wizard-security263500 Node: mysql-config-wizard-confirmation266167 Node: mysql-config-wizard-cmdline267978 Node: windows-install-archive275421 Node: windows-extract-archive276774 Node: windows-create-option-file277959 Node: windows-select-server281395 Node: windows-server-first-start284156 Node: windows-start-command-line287813 Node: mysql-installation-windows-path290029 Node: windows-start-service292137 Node: windows-testing299273 Node: windows-troubleshooting301092 Node: windows-upgrading306628 Node: windows-postinstallation310029 Node: macosx-installation314592 Node: macosx-installation-notes317200 Node: macosx-installation-pkg321859 Ref: mysql-installation-layout-macosx323441 Node: macosx-installation-startupitem326424 Node: macosx-installation-prefpane328923 Node: macosx-installation-server332041 Node: linux-installation334566 Node: linux-installation-rpm336621 Ref: mysql-installation-layout-linuxrpm337387 Node: linux-installation-native347818 Node: solaris-installation360150 Node: solaris-installation-pkg363774 Node: solaris-installation-opensolaris366635 Node: aix-installation369764 Node: aix-installation-general370746 Node: hpux-installation371102 Node: hpux-installation-general372456 Node: hpux-installation-depot373496 Node: freebsd-installation375469 Node: i5os-installation377408 Ref: installation-i5os-notes388444 Node: source-installation389193 Node: source-installation-layout393332 Node: installing-source-distribution395125 Node: installing-development-tree401113 Node: source-configuration-options409678 Ref: option_configure_without-server431567 Ref: option_configure_with-embedded-server432283 Ref: option_configure_prefix432389 Ref: option_configure_with-tcp-port433406 Ref: option_configure_with-unix-socket-path433680 Ref: option_configure_with-client-ldflags434201 Ref: option_configure_with-charset436199 Ref: option_configure_with-collation436911 Ref: option_configure_with-extra-charsets437471 Ref: option_configure_with-debug438043 Ref: option_configure_enable-debug-sync438713 Ref: option_configure_enable-thread-safe-client439721 Ref: option_configure_with-zlib-dir440048 Ref: option_configure_with-big-tables440591 Ref: option_configure_disable-grant-options441075 Ref: option_configure_enable-community-features441445 Ref: option_configure_enable-profiling441793 Ref: option_configure_with-plugins442455 Node: compilation-problems444397 Ref: option_configure_with-low-memory445944 Node: compile-and-link-options452294 Node: windows-source-build454792 Node: solaris-installation-source468364 Node: aix-installation-source473019 Node: hpux-installation-source475646 Node: postinstallation476799 Node: unix-postinstallation478210 Node: mysql-install-db-problems495706 Node: automatic-start502699 Node: starting-server510547 Node: default-privileges518125 Node: upgrading-downgrading529691 Node: upgrading530237 Node: upgrading-from-previous-series537540 Node: downgrading585396 Node: downgrading-to-previous-series589504 Node: downgrading-from-enterprise591827 Node: checking-table-incompatibilities594229 Node: rebuilding-tables600577 Node: copying-databases605874 Node: environment-variables608872 Node: perl-support613536 Node: perl-installation615089 Node: activestate-perl617965 Node: perl-support-problems619130 Node: tutorial621816 Node: connecting-disconnecting623841 Node: entering-queries626580 Node: database-use635454 Node: creating-database638693 Node: creating-tables641113 Node: loading-tables645553 Node: retrieving-data649250 Node: selecting-all650458 Node: selecting-rows652677 Node: selecting-columns656479 Node: sorting-rows658627 Node: date-calculations661525 Node: working-with-null668532 Node: pattern-matching671178 Node: counting-rows678685 Node: multiple-tables683721 Node: getting-information689171 Node: batch-mode692225 Node: examples695450 Node: example-maximum-column697656 Node: example-maximum-row698013 Node: example-maximum-column-group699155 Node: example-maximum-column-group-row699694 Node: example-user-variables701413 Node: example-foreign-keys702506 Node: searching-on-two-keys706765 Node: calculating-days707713 Node: example-auto-increment708890 Node: apache714516 Node: programs715414 Node: programs-overview716503 Node: programs-using728484 Node: invoking-programs728900 Node: connecting732369 Ref: option_general_host738033 Ref: option_general_password738158 Ref: option_general_pipe738451 Ref: option_general_port738642 Ref: option_general_protocol738804 Ref: option_general_shared-memory-base-name740320 Ref: option_general_socket740660 Ref: option_general_user741390 Node: program-options742541 Node: command-line-options745678 Node: option-modifiers751051 Node: option-files753104 Node: option-file-options765742 Ref: option_general_defaults-extra-file766680 Ref: option_general_defaults-file766971 Ref: option_general_defaults-group-suffix767189 Ref: option_general_no-defaults767629 Ref: option_general_print-defaults767855 Node: program-variables767958 Node: option-defaults-equals771265 Node: setting-environment-variables778476 Node: programs-server781469 Node: mysqld782109 Node: mysqld-safe783553 Ref: option_mysqld_safe_help789737 Ref: option_mysqld_safe_autoclose789792 Ref: option_mysqld_safe_basedir790279 Ref: option_mysqld_safe_core-file-size790355 Ref: option_mysqld_safe_datadir790522 Ref: option_mysqld_safe_defaults-extra-file790584 Ref: option_mysqld_safe_defaults-file790876 Ref: option_mysqld_safe_ledir791065 Ref: option_mysqld_safe_log-error791252 Ref: option_mysqld_safe_mysqld791351 Ref: option_mysqld_safe_mysqld-version791779 Ref: option_mysqld_safe_nice792313 Ref: option_mysqld_safe_no-defaults792432 Ref: option_mysqld_safe_open-files-limit792561 Ref: option_mysqld_safe_pid-file792831 Ref: option_mysqld_safe_port792905 Ref: option_mysqld_safe_skip-kill-mysqld793123 Ref: option_mysqld_safe_socket793266 Ref: option_mysqld_safe_syslog793386 Ref: option_mysqld_safe_syslog-tag793784 Ref: option_mysqld_safe_timezone794174 Ref: option_mysqld_safe_user794377 Node: mysql-server799863 Ref: option_mysql_server_basedir801518 Ref: option_mysql_server_datadir801594 Ref: option_mysql_server_pid-file801662 Ref: option_mysql_server_service-startup-timeout801778 Ref: option_mysql_server_use-mysqld_safe802233 Ref: option_mysql_server_use-manager802351 Ref: option_mysql_server_user802422 Node: mysqld-multi802512 Ref: option_mysqld_multi_no-defaults805494 Ref: option_mysqld_multi_defaults-file805549 Ref: option_mysqld_multi_defaults-extra-file805619 Ref: option_mysqld_multi_help807056 Ref: option_mysqld_multi_config-file807111 Ref: option_mysqld_multi_example807782 Ref: option_mysqld_multi_log807837 Ref: option_mysqld_multi_mysqladmin807957 Ref: option_mysqld_multi_mysqld808071 Ref: option_mysqld_multi_no-log808782 Ref: option_mysqld_multi_password808915 Ref: option_mysqld_multi_silent809142 Ref: option_mysqld_multi_tcp-ip809197 Ref: option_mysqld_multi_user809551 Ref: option_mysqld_multi_verbose809676 Ref: option_mysqld_multi_version809718 Node: programs-installation815856 Node: comp-err816836 Ref: option_comp_err_help817827 Ref: option_comp_err_charset817888 Ref: option_comp_err_debug818003 Ref: option_comp_err_debug-info818190 Ref: option_comp_err_header_file818281 Ref: option_comp_err_in_file818404 Ref: option_comp_err_name_file818530 Ref: option_comp_err_out_dir818650 Ref: option_comp_err_out_file818767 Ref: option_comp_err_statefile818877 Ref: option_comp_err_version819004 Node: make-win-bin-dist819068 Ref: option_make_win_bin_dist_debug820478 Ref: option_make_win_bin_dist_embedded820575 Ref: option_make_win_bin_dist_exe-suffix820716 Ref: option_make_win_bin_dist_no-debug820902 Ref: option_make_win_bin_dist_no-embedded820984 Ref: option_make_win_bin_dist_only-debug821067 Node: mysqlbug821281 Node: mysql-fix-privilege-tables822685 Node: mysql-install-db825649 Ref: option_mysql_install_db_basedir828368 Ref: option_mysql_install_db_datadir828444 Ref: option_mysql_install_db_force828528 Ref: option_mysql_install_db_rpm828717 Ref: option_mysql_install_db_skip-name-resolve828877 Ref: option_mysql_install_db_srcdir829045 Ref: option_mysql_install_db_user829338 Ref: option_mysql_install_db_verbose829726 Ref: option_mysql_install_db_windows829817 Node: mysql-secure-installation829916 Node: mysql-tzinfo-to-sql831064 Node: mysql-upgrade833231 Ref: option_mysql_upgrade_help838660 Ref: option_mysql_upgrade_basedir838721 Ref: option_mysql_upgrade_datadir838866 Ref: option_mysql_upgrade_debug-check838997 Ref: option_mysql_upgrade_debug-info839128 Ref: option_mysql_upgrade_force839294 Ref: option_mysql_upgrade_tmpdir839530 Ref: option_mysql_upgrade_user839682 Ref: option_mysql_upgrade_verbose839827 Ref: option_mysql_upgrade_write-binlog839918 Node: programs-client840257 Node: mysql841070 Node: mysql-command-options843293 Ref: option_mysql_help851881 Ref: option_mysql_auto-rehash851942 Ref: option_mysql_batch852597 Ref: option_mysql_bind-address852972 Ref: option_mysql_character-sets-dir853403 Ref: option_mysql_column-names853534 Ref: option_mysql_column-type-info853595 Ref: option_mysql_comments853797 Ref: option_mysql_compress854039 Ref: option_mysql_database854169 Ref: option_mysql_debug854282 Ref: option_mysql_debug-check854470 Ref: option_mysql_debug-info854601 Ref: option_mysql_default-character-set854919 Ref: option_mysql_delimiter855527 Ref: option_mysql_disable-named-commands855640 Ref: option_mysql_execute856017 Ref: option_mysql_force856304 Ref: option_mysql_host856371 Ref: option_mysql_html856466 Ref: option_mysql_ignore-spaces856515 Ref: option_mysql_line-numbers856711 Ref: option_mysql_local-infile856818 Ref: option_mysql_named-commands857177 Ref: option_mysql_no-auto-rehash857476 Ref: option_mysql_no-beep857610 Ref: option_mysql_no-named-commands857672 Ref: option_mysql_no-pager857817 Ref: option_mysql_no-tee857948 Ref: option_mysql_one-database858071 Ref: option_mysql_pager859971 Ref: option_mysql_password860397 Ref: option_mysql_pipe860960 Ref: option_mysql_port861119 Ref: option_mysql_prompt861215 Ref: option_mysql_protocol861416 Ref: option_mysql_quick861729 Ref: option_mysql_raw861963 Ref: option_mysql_reconnect862919 Ref: option_mysql_safe-updates863162 Ref: option_mysql_secure-auth863550 Ref: option_mysql_show-warnings863732 Ref: option_mysql_sigint-ignore863885 Ref: option_mysql_silent863991 Ref: option_mysql_skip-column-names864321 Ref: option_mysql_skip-line-numbers864400 Ref: option_mysql_socket864558 Ref: option_mysql_ssl864715 Ref: option_mysql_table864909 Ref: option_mysql_tee865076 Ref: option_mysql_unbuffered865257 Ref: option_mysql_user865326 Ref: option_mysql_verbose865432 Ref: option_mysql_version865689 Ref: option_mysql_vertical865758 Ref: option_mysql_wait865974 Ref: option_mysql_xml866084 Ref: option_mysql_connect_timeout867722 Ref: option_mysql_max_allowed_packet867831 Ref: option_mysql_max_join_size867975 Ref: option_mysql_net_buffer_length868107 Ref: option_mysql_select_limit868224 Node: mysql-commands868366 Node: mysql-logging883540 Node: mysql-server-side-help885958 Node: mysql-batch-commands888880 Node: mysql-tips890701 Node: mysql-input-editing891191 Node: vertical-query-results893107 Node: safe-updates894356 Node: mysql-reconnect896161 Node: mysqladmin897829 Ref: command_mysqladmin_db_name898520 Ref: command_mysqladmin_debug898587 Ref: command_mysqladmin_drop898860 Ref: command_mysqladmin_extended-status898942 Ref: command_mysqladmin_flush-hosts899027 Ref: command_mysqladmin_flush-logs899095 Ref: command_mysqladmin_flush-privileges899137 Ref: command_mysqladmin_flush-status899213 Ref: command_mysqladmin_flush-tables899265 Ref: command_mysqladmin_flush-threads899311 Ref: command_mysqladmin_kill899364 Ref: command_mysqladmin_old-password899497 Ref: command_mysqladmin_password899689 Ref: command_mysqladmin_ping901095 Ref: command_mysqladmin_processlist901458 Ref: command_mysqladmin_reload901773 Ref: command_mysqladmin_refresh901820 Ref: command_mysqladmin_shutdown901890 Ref: command_mysqladmin_start-slave901931 Ref: command_mysqladmin_status901995 Ref: command_mysqladmin_stop-slave902056 Ref: command_mysqladmin_variables902118 Ref: command_mysqladmin_version902197 Ref: option_mysqladmin_help909064 Ref: option_mysqladmin_bind-address909125 Ref: option_mysqladmin_character-sets-dir909555 Ref: option_mysqladmin_compress909686 Ref: option_mysqladmin_count909816 Ref: option_mysqladmin_debug909952 Ref: option_mysqladmin_debug-check910150 Ref: option_mysqladmin_debug-info910281 Ref: option_mysqladmin_default-character-set910441 Ref: option_mysqladmin_force910580 Ref: option_mysqladmin_host910732 Ref: option_mysqladmin_no-beep910827 Ref: option_mysqladmin_password911015 Ref: option_mysqladmin_pipe911588 Ref: option_mysqladmin_port911747 Ref: option_mysqladmin_protocol911843 Ref: option_mysqladmin_relative912156 Ref: option_mysqladmin_silent912354 Ref: option_mysqladmin_sleep912451 Ref: option_mysqladmin_socket912742 Ref: option_mysqladmin_ssl912899 Ref: option_mysqladmin_user913093 Ref: option_mysqladmin_verbose913199 Ref: option_mysqladmin_version913296 Ref: option_mysqladmin_vertical913365 Ref: option_mysqladmin_wait913490 Ref: option_mysqladmin_connect_timeout913857 Ref: option_mysqladmin_shutdown_timeout913989 Node: mysqlcheck914117 Ref: option_mysqlcheck_help924451 Ref: option_mysqlcheck_all-databases924512 Ref: option_mysqlcheck_all-in-1924695 Ref: option_mysqlcheck_analyze924891 Ref: option_mysqlcheck_auto-repair924942 Ref: option_mysqlcheck_bind-address925098 Ref: option_mysqlcheck_character-sets-dir925528 Ref: option_mysqlcheck_check925659 Ref: option_mysqlcheck_check-only-changed925748 Ref: option_mysqlcheck_check-upgrade925891 Ref: option_mysqlcheck_compress926230 Ref: option_mysqlcheck_databases926354 Ref: option_mysqlcheck_debug926664 Ref: option_mysqlcheck_debug-check926835 Ref: option_mysqlcheck_debug-info926966 Ref: option_mysqlcheck_default-character-set927126 Ref: option_mysqlcheck_extended927265 Ref: option_mysqlcheck_fast927593 Ref: option_mysqlcheck_fix-db-names927675 Ref: option_mysqlcheck_fix-table-names927857 Ref: option_mysqlcheck_force928091 Ref: option_mysqlcheck_host928158 Ref: option_mysqlcheck_medium-check928253 Ref: option_mysqlcheck_optimize928439 Ref: option_mysqlcheck_password928492 Ref: option_mysqlcheck_pipe929065 Ref: option_mysqlcheck_port929224 Ref: option_mysqlcheck_protocol929320 Ref: option_mysqlcheck_quick929633 Ref: option_mysqlcheck_repair929960 Ref: option_mysqlcheck_silent930081 Ref: option_mysqlcheck_socket930151 Ref: option_mysqlcheck_ssl930308 Ref: option_mysqlcheck_tables930502 Ref: option_mysqlcheck_use-frm930643 Ref: option_mysqlcheck_user930839 Ref: option_mysqlcheck_verbose930945 Ref: option_mysqlcheck_version931060 Ref: option_mysqlcheck_write-binlog931129 Node: mysqldump931749 Ref: mysqldump-syntax933360 Ref: option_mysqldump_help950579 Ref: option_mysqldump_add-drop-database950640 Ref: option_mysqldump_add-drop-table951034 Ref: option_mysqldump_add-drop-trigger951179 Ref: option_mysqldump_add-locks951602 Ref: option_mysqldump_all-databases951849 Ref: option_mysqldump_all-tablespaces952031 Ref: option_mysqldump_allow-keywords952416 Ref: option_mysqldump_bind-address952566 Ref: option_mysqldump_character-sets-dir952994 Ref: option_mysqldump_comments953125 Ref: option_mysqldump_compact953368 Ref: option_mysqldump_compatible953972 Ref: option_mysqldump_complete-insert954888 Ref: option_mysqldump_compress955008 Ref: option_mysqldump_create-options955138 Ref: option_mysqldump_databases955271 Ref: option_mysqldump_debug955694 Ref: option_mysqldump_debug-check955897 Ref: option_mysqldump_debug-info956028 Ref: option_mysqldump_default-character-set956188 Ref: option_mysqldump_delayed-insert956612 Ref: option_mysqldump_delete-master-logs956756 Ref: option_mysqldump_disable-keys957035 Ref: option_mysqldump_dump-date957491 Ref: option_mysqldump_events958089 Ref: option_mysqldump_extended-insert958233 Ref: option_mysqldump_fields958454 Ref: option_mysqldump_first-slave958793 Ref: option_mysqldump_flush-logs958914 Ref: option_mysqldump_flush-privileges959554 Ref: option_mysqldump_force959922 Ref: option_mysqldump_host960517 Ref: option_mysqldump_hex-blob960654 Ref: option_mysqldump_ignore-table960942 Ref: option_mysqldump_insert-ignore961203 Ref: option_mysqldump_lines-terminated-by961335 Ref: option_mysqldump_lock-all-tables961555 Ref: option_mysqldump_lock-tables961812 Ref: option_mysqldump_log-error962484 Ref: option_mysqldump_master-data962660 Ref: option_mysqldump_no-autocommit965998 Ref: option_mysqldump_no-create-db966176 Ref: option_mysqldump_no-create-info966403 Ref: option_mysqldump_no-data966792 Ref: option_mysqldump_no-set-names967103 Ref: option_mysqldump_no-tablespaces967189 Ref: option_mysqldump_opt967474 Ref: option_mysqldump_order-by-primary968072 Ref: option_mysqldump_password968367 Ref: option_mysqldump_pipe968938 Ref: option_mysqldump_port969097 Ref: option_mysqldump_protocol969193 Ref: option_mysqldump_quick969506 Ref: option_mysqldump_quote-names969791 Ref: option_mysqldump_replace970214 Ref: option_mysqldump_result-file970379 Ref: option_mysqldump_routines970745 Ref: option_mysqldump_set-charset972272 Ref: option_mysqldump_single-transaction972464 Ref: option_mysqldump_skip-comments974472 Ref: option_mysqldump_skip-opt974552 Ref: option_mysqldump_socket974622 Ref: option_mysqldump_ssl974779 Ref: option_mysqldump_tab974973 Ref: option_mysqldump_tables976374 Ref: option_mysqldump_triggers976546 Ref: option_mysqldump_tz-utc976701 Ref: option_mysqldump_user977426 Ref: option_mysqldump_verbose977532 Ref: option_mysqldump_version977629 Ref: option_mysqldump_where977698 Ref: option_mysqldump_xml978054 Ref: option_mysqldump_max_allowed_packet981585 Ref: option_mysqldump_net_buffer_length981729 Node: mysqlimport984871 Ref: option_mysqlimport_help991629 Ref: option_mysqlimport_bind-address991690 Ref: option_mysqlimport_character-sets-dir992122 Ref: option_mysqlimport_columns992253 Ref: option_mysqlimport_compress992480 Ref: option_mysqlimport_debug992610 Ref: option_mysqlimport_debug-check992781 Ref: option_mysqlimport_debug-info992912 Ref: option_mysqlimport_default-character-set993072 Ref: option_mysqlimport_delete993382 Ref: option_mysqlimport_fields993460 Ref: option_mysqlimport_force993748 Ref: option_mysqlimport_host993985 Ref: option_mysqlimport_ignore994122 Ref: option_mysqlimport_ignore-lines994200 Ref: option_mysqlimport_lines-terminated-by994275 Ref: option_mysqlimport_local994715 Ref: option_mysqlimport_lock-tables994791 Ref: option_mysqlimport_low-priority994956 Ref: option_mysqlimport_password995151 Ref: option_mysqlimport_pipe995726 Ref: option_mysqlimport_port995885 Ref: option_mysqlimport_protocol995981 Ref: option_mysqlimport_replace996294 Ref: option_mysqlimport_silent996809 Ref: option_mysqlimport_socket996891 Ref: option_mysqlimport_ssl997048 Ref: option_mysqlimport_user997242 Ref: option_mysqlimport_use-threads997348 Ref: option_mysqlimport_verbose997462 Ref: option_mysqlimport_version997559 Node: mysqlshow998438 Ref: option_mysqlshow_help1004026 Ref: option_mysqlshow_bind-address1004087 Ref: option_mysqlshow_character-sets-dir1004515 Ref: option_mysqlshow_compress1004646 Ref: option_mysqlshow_count1004776 Ref: option_mysqlshow_debug1004881 Ref: option_mysqlshow_debug-check1005052 Ref: option_mysqlshow_debug-info1005183 Ref: option_mysqlshow_default-character-set1005343 Ref: option_mysqlshow_host1005482 Ref: option_mysqlshow_keys1005577 Ref: option_mysqlshow_password1005625 Ref: option_mysqlshow_pipe1006196 Ref: option_mysqlshow_port1006355 Ref: option_mysqlshow_protocol1006451 Ref: option_mysqlshow_show-table-type1006764 Ref: option_mysqlshow_socket1006930 Ref: option_mysqlshow_ssl1007087 Ref: option_mysqlshow_status1007281 Ref: option_mysqlshow_user1007355 Ref: option_mysqlshow_verbose1007461 Ref: option_mysqlshow_version1007646 Node: mysqlslap1007710 Ref: option_mysqlslap_help1019874 Ref: option_mysqlslap_auto-generate-sql1019935 Ref: option_mysqlslap_auto-generate-sql-add-autoincrement1020081 Ref: option_mysqlslap_auto-generate-sql-execute-number1020244 Ref: option_mysqlslap_auto-generate-sql-guid-primary1020392 Ref: option_mysqlslap_auto-generate-sql-load-type1020548 Ref: option_mysqlslap_auto-generate-sql-secondary-indexes1020897 Ref: option_mysqlslap_auto-generate-sql-unique-query-number1021106 Ref: option_mysqlslap_auto-generate-sql-unique-write-number1021495 Ref: option_mysqlslap_auto-generate-sql-write-number1021700 Ref: option_mysqlslap_commit1021862 Ref: option_mysqlslap_compress1022022 Ref: option_mysqlslap_concurrency1022152 Ref: option_mysqlslap_create1022282 Ref: option_mysqlslap_create-schema1022392 Ref: option_mysqlslap_csv1022717 Ref: option_mysqlslap_debug1022930 Ref: option_mysqlslap_debug-check1023127 Ref: option_mysqlslap_debug-info1023258 Ref: option_mysqlslap_delimiter1023424 Ref: option_mysqlslap_detach1023553 Ref: option_mysqlslap_engine1023744 Ref: option_mysqlslap_host1023845 Ref: option_mysqlslap_iterations1023940 Ref: option_mysqlslap_lock-directory1024016 Ref: option_mysqlslap_no-drop1024158 Ref: option_mysqlslap_number-char-cols1024322 Ref: option_mysqlslap_number-int-cols1024462 Ref: option_mysqlslap_number-of-queries1024606 Ref: option_mysqlslap_only-print1025161 Ref: option_mysqlslap_password1025334 Ref: option_mysqlslap_pipe1025905 Ref: option_mysqlslap_port1026064 Ref: option_mysqlslap_post-query1026160 Ref: option_mysqlslap_shared-memory-base-name1026381 Ref: option_mysqlslap_post-system1026615 Ref: option_mysqlslap_pre-query1026819 Ref: option_mysqlslap_pre-system1027033 Ref: option_mysqlslap_preserve-schema1027230 Ref: option_mysqlslap_protocol1027479 Ref: option_mysqlslap_query1027792 Ref: option_mysqlslap_silent1027934 Ref: option_mysqlslap_slave1027988 Ref: option_mysqlslap_socket1028264 Ref: option_mysqlslap_ssl1028421 Ref: option_mysqlslap_use-threads1028615 Ref: option_mysqlslap_user1028906 Ref: option_mysqlslap_verbose1029012 Ref: option_mysqlslap_version1029197 Node: programs-admin-utils1029261 Node: innochecksum1031030 Ref: option_innochecksum_count1032566 Ref: option_innochecksum_debug1032634 Ref: option_innochecksum_end1032696 Ref: option_innochecksum_page1032743 Ref: option_innochecksum_start1032794 Ref: option_innochecksum_verbose1032843 Node: myisam-ftdump1032917 Ref: option_myisam_ftdump_help1035286 Ref: option_myisam_ftdump_count1035352 Ref: option_myisam_ftdump_dump1035440 Ref: option_myisam_ftdump_length1035525 Ref: option_myisam_ftdump_stats1035587 Ref: option_myisam_ftdump_verbose1035719 Node: myisamchk1035806 Node: myisamchk-general-options1049042 Ref: option_myisamchk_help1049507 Ref: option_myisamchk_HELP1049615 Ref: option_myisamchk_debug1049721 Ref: option_myisamchk_silent1049914 Ref: option_myisamchk_verbose1050081 Ref: option_myisamchk_version1050287 Ref: option_myisamchk_wait1050356 Node: myisamchk-check-options1055192 Ref: option_myisamchk_check1055495 Ref: option_myisamchk_check-only-changed1055655 Ref: option_myisamchk_extend-check1055755 Ref: option_myisamchk_fast1056434 Ref: option_myisamchk_force1056515 Ref: option_myisamchk_information1056738 Ref: option_myisamchk_medium-check1056837 Ref: option_myisamchk_read-only1057026 Ref: option_myisamchk_update-state1057322 Node: myisamchk-repair-options1057709 Ref: option_myisamchk_backup1058097 Ref: option_myisamchk_character-sets-dir1058184 Ref: option_myisamchk_correct-checksum1058315 Ref: option_myisamchk_data-file-length1058397 Ref: option_myisamchk_keys-used1059042 Ref: option_myisamchk_no-symlinks1059488 Ref: option_myisamchk_max-record-length1059772 Ref: option_myisamchk_parallel-recover1059925 Ref: option_myisamchk_quick1060129 Ref: option_myisamchk_recover1060383 Ref: option_myisamchk_safe-recover1060961 Ref: option_myisamchk_set-character-set1061557 Ref: option_myisamchk_set-collation1061716 Ref: option_myisamchk_sort-recover1061893 Ref: option_myisamchk_tmpdir1062054 Ref: option_myisamchk_unpack1062558 Node: myisamchk-other-options1062651 Ref: option_myisamchk_analyze1062967 Ref: option_myisamchk_block-search1063386 Ref: option_myisamchk_description1063497 Ref: option_myisamchk_set-auto-increment1063710 Ref: option_myisamchk_sort-index1064079 Ref: option_myisamchk_sort-records1064232 Node: myisamchk-table-info1065222 Node: myisamchk-memory1079519 Node: myisamlog1082582 Ref: option_myisamlog_help1083429 Ref: option_myisamlog_files1083530 Ref: option_myisamlog_information1083592 Ref: option_myisamlog_offset1083652 Ref: option_myisamlog_path1083706 Ref: option_myisamlog_recovery1083757 Ref: option_myisamlog_record-position1083805 Ref: option_myisamlog_update1083900 Ref: option_myisamlog_verbose1083947 Ref: option_myisamlog_write1084105 Ref: option_myisamlog_version1084158 Node: myisampack1084200 Ref: option_myisampack_help1086181 Ref: option_myisampack_backup1086242 Ref: option_myisampack_character-sets-dir1086348 Ref: option_myisampack_debug1086479 Ref: option_myisampack_force1086650 Ref: option_myisampack_join1087283 Ref: option_myisampack_silent1087997 Ref: option_myisampack_test1088077 Ref: option_myisampack_tmpdir1088159 Ref: option_myisampack_verbose1088307 Ref: option_myisampack_version1088435 Ref: option_myisampack_wait1088504 Node: mysqlaccess1099634 Ref: option_mysqlaccess_help1102611 Ref: option_mysqlaccess_brief1102672 Ref: option_mysqlaccess_commit1102749 Ref: option_mysqlaccess_copy1103020 Ref: option_mysqlaccess_db1103096 Ref: option_mysqlaccess_debug1103165 Ref: option_mysqlaccess_host1103248 Ref: option_mysqlaccess_howto1103343 Ref: option_mysqlaccess_old_server1103448 Ref: option_mysqlaccess_password1103606 Ref: option_mysqlaccess_plan1103985 Ref: option_mysqlaccess_preview1104058 Ref: option_mysqlaccess_relnotes1104171 Ref: option_mysqlaccess_rhost1104224 Ref: option_mysqlaccess_rollback1104320 Ref: option_mysqlaccess_spassword1104406 Ref: option_mysqlaccess_superuser1104809 Ref: option_mysqlaccess_table1104917 Ref: option_mysqlaccess_user1104980 Ref: option_mysqlaccess_version1105075 Node: mysqlbinlog1105705 Ref: option_mysqlbinlog_help1114848 Ref: option_mysqlbinlog_base64-output1114909 Ref: option_mysqlbinlog_bind-address1117260 Ref: option_mysqlbinlog_character-sets-dir1117692 Ref: option_mysqlbinlog_database1117823 Ref: option_mysqlbinlog_debug1121851 Ref: option_mysqlbinlog_debug-check1122050 Ref: option_mysqlbinlog_debug-info1122181 Ref: option_mysqlbinlog_disable-log-bin1122341 Ref: option_mysqlbinlog_force-if-open1123006 Ref: option_mysqlbinlog_force-read1123160 Ref: option_mysqlbinlog_hexdump1123460 Ref: option_mysqlbinlog_host1123684 Ref: option_mysqlbinlog_local-load1123792 Ref: option_mysqlbinlog_offset1124087 Ref: option_mysqlbinlog_password1124158 Ref: option_mysqlbinlog_port1124733 Ref: option_mysqlbinlog_position1124844 Ref: option_mysqlbinlog_protocol1124959 Ref: option_mysqlbinlog_read-from-remote-server1125272 Ref: option_mysqlbinlog_result-file1125736 Ref: option_mysqlbinlog_server-id1125814 Ref: option_mysqlbinlog_server-id-bits1125969 Ref: option_mysqlbinlog_set-charset1126584 Ref: option_mysqlbinlog_short-form1126796 Ref: option_mysqlbinlog_socket1127013 Ref: option_mysqlbinlog_start-datetime1127170 Ref: option_mysqlbinlog_start-position1127781 Ref: option_mysqlbinlog_stop-datetime1128094 Ref: option_mysqlbinlog_stop-position1128504 Ref: option_mysqlbinlog_to-last-log1128806 Ref: option_mysqlbinlog_user1129133 Ref: option_mysqlbinlog_verbose1129244 Ref: option_mysqlbinlog_version1129651 Ref: option_mysqlbinlog_open_files_limit1129900 Node: mysqlbinlog-hexdump1133878 Node: mysqlbinlog-row-events1145077 Node: mysqldumpslow1154077 Ref: option_mysqldumpslow_help1155929 Ref: option_mysqldumpslow_abstract1155984 Ref: option_mysqldumpslow_debug1156059 Ref: option_mysqldumpslow_grep1156107 Ref: option_mysqldumpslow_host1156194 Ref: option_mysqldumpslow_instance1156347 Ref: option_mysqldumpslow_lock1156462 Ref: option_mysqldumpslow_abstract-numbers1156523 Ref: option_mysqldumpslow_reverse1156597 Ref: option_mysqldumpslow_sort1156639 Ref: option_mysqldumpslow_top1157090 Ref: option_mysqldumpslow_verbose1157158 Node: mysqlhotcopy1157758 Ref: option_mysqlhotcopy_help1161355 Ref: option_mysqlhotcopy_addtodest1161416 Ref: option_mysqlhotcopy_allowold1161519 Ref: option_mysqlhotcopy_checkpoint1161621 Ref: option_mysqlhotcopy_chroot1161753 Ref: option_mysqlhotcopy_debug1161962 Ref: option_mysqlhotcopy_dryrun1162006 Ref: option_mysqlhotcopy_flushlog1162076 Ref: option_mysqlhotcopy_host1162142 Ref: option_mysqlhotcopy_keepold1162367 Ref: option_mysqlhotcopy_method1162443 Ref: option_mysqlhotcopy_noindices1162542 Ref: option_mysqlhotcopy_password1162822 Ref: option_mysqlhotcopy_port1163219 Ref: option_mysqlhotcopy_quiet1163332 Ref: option_mysqlhotcopy_record_log_pos1163390 Ref: option_mysqlhotcopy_regexp1163529 Ref: option_mysqlhotcopy_resetmaster1163634 Ref: option_mysqlhotcopy_resetslave1163714 Ref: option_mysqlhotcopy_socket1163801 Ref: option_mysqlhotcopy_suffix1163901 Ref: option_mysqlhotcopy_tmpdir1163978 Ref: option_mysqlhotcopy_user1164055 Node: instance-manager1164389 Node: instance-manager-command-options1167266 Ref: option_mysqlmanager_help1168263 Ref: option_mysqlmanager_add-user1168324 Ref: option_mysqlmanager_angel-pid-file1168472 Ref: option_mysqlmanager_bind-address1169059 Ref: option_mysqlmanager_check-password-file1169119 Ref: option_mysqlmanager_clean-password-file1169258 Ref: option_mysqlmanager_debug1169378 Ref: option_mysqlmanager_default-mysqld-path1169558 Ref: option_mysqlmanager_defaults-file1169968 Ref: option_mysqlmanager_drop-user1170514 Ref: option_mysqlmanager_edit-user1170662 Ref: option_mysqlmanager_install1170838 Ref: option_mysqlmanager_list-users1170965 Ref: option_mysqlmanager_log1171074 Ref: option_mysqlmanager_monitoring-interval1171806 Ref: option_mysqlmanager_mysqld-safe-compatible1173094 Ref: option_mysqlmanager_password1173305 Ref: option_mysqlmanager_password-file1173658 Ref: option_mysqlmanager_pid-file1174012 Ref: option_mysqlmanager_port1174262 Ref: option_mysqlmanager_print-defaults1174425 Ref: option_mysqlmanager_print-password-line1174564 Ref: option_mysqlmanager_remove1174848 Ref: option_mysqlmanager_run-as-service1175019 Ref: option_mysqlmanager_socket1175243 Ref: option_mysqlmanager_standalone1175432 Ref: option_mysqlmanager_user1175622 Ref: option_mysqlmanager_username1176178 Ref: option_mysqlmanager_version1176358 Ref: option_mysqlmanager_wait-timeout1176427 Node: instance-manager-configuration-files1176703 Node: instance-manager-startup-process1180256 Node: instance-manager-security-passwords1185198 Node: instance-manager-security-monitoring1192253 Node: instance-manager-security1196011 Node: instance-manager-commands1196939 Node: mysql-convert-table-format1208060 Ref: option_mysql_convert_table_format_help1209049 Ref: option_mysql_convert_table_format_force1209104 Ref: option_mysql_convert_table_format_host1209158 Ref: option_mysql_convert_table_format_password1209237 Ref: option_mysql_convert_table_format_port1209630 Ref: option_mysql_convert_table_format_socket1209711 Ref: option_mysql_convert_table_format_type1209801 Ref: option_mysql_convert_table_format_user1209964 Ref: option_mysql_convert_table_format_verbose1210054 Ref: option_mysql_convert_table_format_version1210145 Node: mysql-find-rows1210203 Ref: option_mysql_find_rows_help1211481 Ref: option_mysql_find_rows_regexp1211553 Ref: option_mysql_find_rows_rows1211625 Ref: option_mysql_find_rows_skip-use-db1211682 Ref: option_mysql_find_rows_start_row1211766 Node: mysql-fix-extensions1211818 Node: mysql-setpermission1212770 Ref: option_mysql_setpermission_help1214027 Ref: option_mysql_setpermission_host1214082 Ref: option_mysql_setpermission_password1214161 Ref: option_mysql_setpermission_port1214554 Ref: option_mysql_setpermission_socket1214635 Ref: option_mysql_setpermission_user1214725 Node: mysql-waitpid1214810 Ref: option_mysql_waitpid_help1215892 Ref: option_mysql_waitpid_verbose1215959 Ref: option_mysql_waitpid_version1216087 Node: mysql-zap1216151 Ref: option_mysql_zap_help1217251 Ref: option_mysql_zap_force1217318 Ref: option_mysql_zap_test1217435 Node: programs-development1217523 Node: msql2mysql1219450 Node: mysql-config1220596 Ref: option_mysql_config_cflags1221120 Ref: option_mysql_config_include1221526 Ref: option_mysql_config_libmysqld-libs1221597 Ref: option_mysql_config_libs1221719 Ref: option_mysql_config_libs_r1221816 Ref: option_mysql_config_plugindir1221927 Ref: option_mysql_config_port1222070 Ref: option_mysql_config_socket1222156 Ref: option_mysql_config_version1222242 Node: my-print-defaults1223555 Ref: option_my_print_defaults_help1224585 Ref: option_my_print_defaults_config-file1224646 Ref: option_my_print_defaults_debug1224769 Ref: option_my_print_defaults_defaults-extra-file1224970 Ref: option_my_print_defaults_defaults-group-suffix1225164 Ref: option_my_print_defaults_no-defaults1225321 Ref: option_my_print_defaults_verbose1225380 Ref: option_my_print_defaults_version1225477 Node: resolve-stack-dump1225541 Ref: option_resolve_stack_dump_help1226390 Ref: option_resolve_stack_dump_numeric-dump-file1226451 Ref: option_resolve_stack_dump_symbols-file1226554 Ref: option_resolve_stack_dump_version1226638 Node: programs-miscellaneous1226756 Node: perror1227154 Ref: option_perror_help1228412 Ref: option_perror_ndb1228489 Ref: option_perror_silent1228566 Ref: option_perror_verbose1228639 Ref: option_perror_version1228749 Node: replace-utility1228813 Ref: option_replace_help1230349 Ref: option_replace_debug1230406 Ref: option_replace_silent1230455 Ref: option_replace_verbose1230532 Ref: option_replace_version1230616 Node: resolveip1230667 Ref: option_resolveip_help1231163 Ref: option_resolveip_silent1231240 Ref: option_resolveip_version1231304 Node: server-administration1231368 Node: mysqld-server1232181 Node: mysqld-option-tables1234187 Node: server-configuration-defaults1318441 Node: server-options1319869 Ref: option_mysqld_help1323201 Ref: option_mysqld_allow-suspicious-udfs1323540 Ref: option_mysqld_ansi1324340 Ref: option_mysqld_basedir1324764 Ref: option_mysqld_big-tables1325470 Ref: option_mysqld_bind-address1326351 Ref: option_mysqld_binlog-format1328428 Ref: option_mysqld_bootstrap1331664 Ref: option_mysqld_character-sets-dir1332180 Ref: option_mysqld_character-set-client-handshake1332869 Ref: option_mysqld_character-set-filesystem1333552 Ref: option_mysqld_character-set-server1334365 Ref: option_mysqld_chroot1335227 Ref: option_mysqld_collation-server1335996 Ref: option_mysqld_console1336680 Ref: option_mysqld_core-file1337180 Ref: option_mysqld_datadir1338559 Ref: option_mysqld_debug1339187 Ref: option_mysqld_debug-sync-timeout1340709 Ref: option_mysqld_default-character-set1341989 Ref: option_mysqld_default-collation1342721 Ref: option_mysqld_default-storage-engine1343343 Ref: option_mysqld_default-table-type1344090 Ref: option_mysqld_default-time-zone1344708 Ref: option_mysqld_delay-key-write1345334 Ref: option_mysqld_des-key-file1346725 Ref: option_mysqld_enable-locking1347071 Ref: option_mysqld_enable-named-pipe1347164 Ref: option_mysqld_enable-pstack1347877 Ref: option_mysqld_engine-condition-pushdown1348401 Ref: option_mysqld_event-scheduler1349202 Ref: option_mysqld_exit-info1350239 Ref: option_mysqld_external-locking1350858 Ref: option_mysqld_flush1351806 Ref: option_mysqld_gdb1352580 Ref: option_mysqld_general-log1353121 Ref: option_mysqld_init-file1353978 Ref: option_mysqld_install1354958 Ref: option_mysqld_install-manual1355497 Ref: option_mysqld_language1356113 Ref: option_mysqld_large-pages1357016 Ref: option_mysqld_log1358216 Ref: option_mysqld_log-error1359709 Ref: option_mysqld_log-isam1360484 Ref: option_mysqld_log-long-format1360946 Ref: option_mysqld_log-output1361755 Ref: option_mysqld_log-queries-not-using-indexes1363783 Ref: option_mysqld_log-short-format1364798 Ref: option_mysqld_log-slow-admin-statements1365287 Ref: option_mysqld_log-slow-queries1366120 Ref: option_mysqld_log-tc1367714 Ref: option_mysqld_log-tc-size1368445 Ref: option_mysqld_log-warnings1369292 Ref: option_mysqld_low-priority-updates1371554 Ref: option_mysqld_min-examined-row-limit1372715 Ref: option_mysqld_memlock1374049 Ref: option_mysqld_myisam-block-size1376028 Ref: option_mysqld_myisam-recover1376613 Ref: option_mysqld_old-alter-table1379062 Ref: option_mysqld_old-style-user-limits1380093 Ref: option_mysqld_one-thread1380743 Ref: option_mysqld_open-files-limit1381227 Ref: option_mysqld_partition1382656 Ref: option_mysqld_pid-file1383163 Ref: option_mysqld_plugin1384011 Ref: option_mysqld_plugin-load1385316 Ref: option_mysqld_port1387866 Ref: option_mysqld_port-open-timeout1388711 Ref: option_mysqld_remove1389560 Ref: option_mysqld_safe-mode1389904 Ref: option_mysqld_safe-show-database1390188 Ref: option_mysqld_safe-user-create1391076 Ref: option_mysqld_secure-auth1392127 Ref: option_mysqld_secure-file-priv1393298 Ref: option_mysqld_shared-memory1394156 Ref: option_mysqld_shared-memory-base-name1394540 Ref: option_mysqld_skip-concurrent-insert1395034 Ref: option_mysqld_skip-event-scheduler1395272 Ref: option_mysqld_skip-grant-tables1395785 Ref: option_mysqld_skip-host-cache1397023 Ref: option_mysqld_skip-merge1397524 Ref: option_mysqld_skip-name-resolve1397654 Ref: option_mysqld_skip-networking1397918 Ref: option_mysqld_skip-partition1398265 Ref: option_mysqld_ssl_xxxx1399405 Ref: option_mysqld_standalone1399603 Ref: option_mysqld_symbolic-links1399927 Ref: option_mysqld_skip-safemalloc1400962 Ref: option_mysqld_skip-show-database1401481 Ref: option_mysqld_skip-stack-trace1402092 Ref: option_mysqld_skip-thread-priority1402528 Ref: option_mysqld_slow-query-log1403377 Ref: option_mysqld_socket1404292 Ref: option_mysqld_sql-mode1405366 Ref: option_mysqld_sysdate-is-now1407264 Ref: option_mysqld_tc-heuristic-recover1408213 Ref: option_mysqld_temp-pool1408797 Ref: option_mysqld_transaction-isolation1409642 Ref: option_mysqld_tmpdir1410593 Ref: option_mysqld_user1412207 Ref: option_mysqld_verbose1413865 Ref: option_mysqld_version1413956 Node: server-system-variables1415038 Ref: sysvar_autocommit1453505 Ref: sysvar_automatic_sp_privileges1454983 Ref: sysvar_back_log1456203 Ref: sysvar_basedir1457659 Ref: sysvar_big_tables1458434 Ref: sysvar_bulk_insert_buffer_size1459021 Ref: sysvar_character_set_client1460523 Ref: sysvar_character_set_connection1462337 Ref: sysvar_character_set_database1462953 Ref: sysvar_character_set_filesystem1464570 Ref: sysvar_character_set_results1465986 Ref: sysvar_character_set_server1466534 Ref: sysvar_character_set_system1467165 Ref: sysvar_character_sets_dir1467654 Ref: sysvar_collation_connection1468296 Ref: sysvar_collation_database1468779 Ref: sysvar_collation_server1470376 Ref: sysvar_completion_type1470983 Ref: sysvar_concurrent_insert1473108 Ref: sysvar_connect_timeout1474707 Ref: sysvar_datadir1476032 Ref: sysvar_date_format1476695 Ref: sysvar_datetime_format1476747 Ref: sysvar_debug1476803 Ref: sysvar_debug_sync1478469 Ref: sysvar_default_week_format1480164 Ref: sysvar_delay_key_write1480985 Ref: sysvar_delayed_insert_limit1483039 Ref: sysvar_delayed_insert_timeout1484368 Ref: sysvar_delayed_queue_size1485132 Ref: sysvar_div_precision_increment1486462 Ref: sysvar_engine_condition_pushdown1487946 Ref: sysvar_error_count1489587 Ref: sysvar_event_scheduler1489761 Ref: sysvar_expire_logs_days1490884 Ref: sysvar_flush1491954 Ref: sysvar_flush_time1492852 Ref: sysvar_foreign_key_checks1493668 Ref: sysvar_ft_boolean_syntax1494624 Ref: sysvar_ft_max_word_len1496122 Ref: sysvar_ft_min_word_len1496894 Ref: sysvar_ft_query_expansion_limit1497709 Ref: sysvar_ft_stopword_file1498514 Ref: sysvar_general_log1499785 Ref: sysvar_general_log_file1500855 Ref: sysvar_group_concat_max_len1501816 Ref: sysvar_have_archive1503012 Ref: sysvar_have_blackhole_engine1503161 Ref: sysvar_have_compress1503321 Ref: sysvar_have_community_features1503511 Ref: sysvar_have_crypt1503853 Ref: sysvar_have_csv1504009 Ref: sysvar_have_dynamic_loading1504277 Ref: sysvar_have_example_engine1504442 Ref: sysvar_have_federated_engine1504598 Ref: sysvar_have_geometry1504758 Ref: sysvar_have_innodb1504849 Ref: sysvar_have_isam1505096 Ref: sysvar_have_merge_engine1505318 Ref: sysvar_have_openssl1505499 Ref: sysvar_have_partitioning1505666 Ref: sysvar_have_query_cache1505973 Ref: sysvar_have_row_based_replication1506082 Ref: sysvar_have_raid1506837 Ref: sysvar_have_rtree_keys1507059 Ref: sysvar_have_ssl1507205 Ref: sysvar_have_symlink1507592 Ref: sysvar_hostname1507940 Ref: sysvar_identity1508452 Ref: sysvar_init_connect1508692 Ref: sysvar_init_file1510420 Ref: sysvar_insert_id1511936 Ref: sysvar_interactive_timeout1512163 Ref: sysvar_join_buffer_size1513127 Ref: sysvar_keep_files_on_create1515655 Ref: sysvar_key_buffer_size1517151 Ref: sysvar_key_cache_age_threshold1522347 Ref: sysvar_key_cache_block_size1523745 Ref: sysvar_key_cache_division_limit1524580 Ref: sysvar_language1525554 Ref: sysvar_large_files_support1526302 Ref: sysvar_large_pages1526648 Ref: sysvar_large_page_size1527351 Ref: sysvar_last_insert_id1528010 Ref: sysvar_lc_time_names1528336 Ref: sysvar_license1529283 Ref: sysvar_local_infile1529716 Ref: sysvar_locked_in_memory1530314 Ref: sysvar_log1530640 Ref: sysvar_log_bin_trust_function_creators1531551 Ref: sysvar_log_error1533018 Ref: sysvar_log_output1533702 Ref: sysvar_log_queries_not_using_indexes1535055 Ref: sysvar_log_slow_queries1535849 Ref: sysvar_log_warnings1536787 Ref: sysvar_long_query_time1538359 Ref: sysvar_low_priority_updates1539972 Ref: sysvar_lower_case_file_system1541039 Ref: sysvar_lower_case_table_names1541785 Ref: sysvar_max_allowed_packet1544049 Ref: sysvar_max_connect_errors1546185 Ref: sysvar_max_connections1547890 Ref: sysvar_max_delayed_threads1549651 Ref: sysvar_max_error_count1550919 Ref: sysvar_max_heap_table_size1551807 Ref: sysvar_max_insert_delayed_threads1553898 Ref: sysvar_max_join_size1554407 Ref: sysvar_max_length_for_sort_data1556093 Ref: sysvar_max_long_data_size1556970 Ref: sysvar_max_prepared_stmt_count1558172 Ref: sysvar_max_relay_log_size1559680 Ref: sysvar_max_seeks_for_key1561016 Ref: sysvar_max_sort_length1562549 Ref: sysvar_max_sp_recursion_depth1563399 Ref: sysvar_max_tmp_tables1564571 Ref: sysvar_max_user_connections1564626 Ref: sysvar_max_write_lock_count1566221 Ref: sysvar_min_examined_row_limit1567387 Ref: sysvar_myisam_data_pointer_size1568666 Ref: sysvar_myisam_max_sort_file_size1569632 Ref: sysvar_myisam_mmap_size1571203 Ref: sysvar_myisam_recover_options1572590 Ref: sysvar_myisam_repair_threads1572935 Ref: sysvar_myisam_sort_buffer_size1574287 Ref: sysvar_myisam_stats_method1575968 Ref: sysvar_myisam_use_mmap1577550 Ref: sysvar_named_pipe1578269 Ref: sysvar_net_buffer_length1578808 Ref: sysvar_net_read_timeout1580344 Ref: sysvar_net_retry_count1581685 Ref: sysvar_net_write_timeout1583382 Ref: sysvar_new1584500 Ref: sysvar_old1585311 Ref: sysvar_old_alter_table1586473 Ref: sysvar_old_passwords1587506 Ref: sysvar_one_shot1588726 Ref: sysvar_open_files_limit1588869 Ref: sysvar_optimizer_prune_level1589920 Ref: sysvar_optimizer_search_depth1590913 Ref: sysvar_optimizer_switch1592320 Ref: sysvar_pid_file1594069 Ref: sysvar_plugin_dir1594718 Ref: sysvar_port1596249 Ref: sysvar_preload_buffer_size1597031 Ref: sysvar_prepared_stmt_count1597865 Ref: sysvar_profiling1598627 Ref: sysvar_profiling_history_size1598999 Ref: sysvar_protocol_version1599328 Ref: sysvar_pseudo_thread_id1599778 Ref: sysvar_query_alloc_block_size1600202 Ref: sysvar_query_cache_limit1601695 Ref: sysvar_query_cache_min_res_unit1602824 Ref: sysvar_query_cache_size1604173 Ref: sysvar_query_cache_type1605877 Ref: sysvar_query_cache_wlock_invalidate1607634 Ref: sysvar_query_prealloc_size1608788 Ref: sysvar_rand_seed11610417 Ref: sysvar_rand_seed21611108 Ref: sysvar_range_alloc_block_size1611172 Ref: sysvar_read_buffer_size1612518 Ref: sysvar_read_only1614324 Ref: sysvar_read_rnd_buffer_size1617673 Ref: sysvar_relay_log_purge1619137 Ref: sysvar_relay_log_space_limit1619842 Ref: sysvar_report_host1620949 Ref: sysvar_report_password1621553 Ref: sysvar_report_port1622250 Ref: sysvar_report_user1622976 Ref: sysvar_secure_auth1623575 Ref: sysvar_secure_file_priv1624579 Ref: sysvar_server_id1625490 Ref: sysvar_shared_memory1626417 Ref: sysvar_shared_memory_base_name1626776 Ref: sysvar_skip_external_locking1627325 Ref: sysvar_skip_name_resolve1628508 Ref: sysvar_skip_networking1629493 Ref: sysvar_skip_show_database1630260 Ref: sysvar_slow_launch_time1631516 Ref: sysvar_slow_query_log1632222 Ref: sysvar_slow_query_log_file1633478 Ref: sysvar_socket1634378 Ref: sysvar_sort_buffer_size1635384 Ref: sysvar_sql_auto_is_null1637863 Ref: sysvar_sql_big_selects1639227 Ref: sysvar_sql_buffer_result1640211 Ref: sysvar_sql_log_bin1640937 Ref: sysvar_sql_log_off1641467 Ref: sysvar_sql_log_update1642048 Ref: sysvar_sql_mode1642650 Ref: sysvar_sql_notes1644567 Ref: sysvar_sql_quote_show_create1645027 Ref: sysvar_sql_safe_updates1645462 Ref: sysvar_sql_select_limit1645888 Ref: sysvar_sql_warnings1646926 Ref: sysvar_ssl_ca1647161 Ref: sysvar_ssl_capath1647831 Ref: sysvar_ssl_cert1648553 Ref: sysvar_ssl_cipher1649264 Ref: sysvar_ssl_key1649960 Ref: sysvar_storage_engine1650615 Ref: sysvar_sync_frm1651248 Ref: sysvar_system_time_zone1651994 Ref: sysvar_table_cache1653094 Ref: sysvar_table_definition_cache1654028 Ref: sysvar_table_lock_wait_timeout1655594 Ref: sysvar_table_open_cache1656321 Ref: sysvar_table_type1657564 Ref: sysvar_thread_cache_size1658144 Ref: sysvar_thread_concurrency1659765 Ref: sysvar_thread_handling1660741 Ref: sysvar_thread_stack1661792 Ref: sysvar_time_format1663421 Ref: sysvar_time_zone1663473 Ref: sysvar_timed_mutexes1664239 Ref: sysvar_timestamp1665240 Ref: sysvar_tmp_table_size1665871 Ref: sysvar_tmpdir1667466 Ref: sysvar_transaction_alloc_block_size1669167 Ref: sysvar_transaction_prealloc_size1670622 Ref: sysvar_tx_isolation1672534 Ref: sysvar_unique_checks1673889 Ref: sysvar_updatable_views_with_limit1674893 Ref: sysvar_version1676219 Ref: sysvar_version_comment1676563 Ref: sysvar_version_compile_machine1677114 Ref: sysvar_version_compile_os1677578 Ref: sysvar_wait_timeout1678020 Ref: sysvar_warning_count1679600 Node: using-system-variables1679794 Node: structured-system-variables1692098 Node: dynamic-system-variables1697273 Node: server-status-variables1716199 Ref: statvar_Aborted_clients1749692 Ref: statvar_Aborted_connects1749876 Ref: statvar_Binlog_cache_disk_use1750010 Ref: statvar_Binlog_cache_use1750244 Ref: statvar_Bytes_received1750350 Ref: statvar_Bytes_sent1750427 Ref: statvar_Com_xxx1750494 Ref: statvar_Compression1752980 Ref: statvar_Connections1753112 Ref: statvar_Created_tmp_disk_tables1753219 Ref: statvar_Created_tmp_files1754186 Ref: statvar_Created_tmp_tables1754281 Ref: statvar_Delayed_errors1754873 Ref: statvar_Delayed_insert_threads1755043 Ref: statvar_Delayed_writes1755165 Ref: statvar_Flush_commands1755269 Ref: statvar_Handler_commit1755725 Ref: statvar_Handler_delete1755815 Ref: statvar_Handler_prepare1755906 Ref: statvar_Handler_read_first1756001 Ref: statvar_Handler_read_key1756265 Ref: statvar_Handler_read_next1756463 Ref: statvar_Handler_read_prev1756685 Ref: statvar_Handler_read_rnd1756850 Ref: statvar_Handler_read_rnd_next1757180 Ref: statvar_Handler_rollback1757503 Ref: statvar_Handler_savepoint1757617 Ref: statvar_Handler_savepoint_rollback1757716 Ref: statvar_Handler_update1757836 Ref: statvar_Handler_write1757917 Ref: statvar_Innodb_buffer_pool_pages_data1757997 Ref: statvar_Innodb_buffer_pool_pages_dirty1758096 Ref: statvar_Innodb_buffer_pool_pages_flushed1758179 Ref: statvar_Innodb_buffer_pool_pages_free1758274 Ref: statvar_Innodb_buffer_pool_pages_latched1758345 Ref: statvar_Innodb_buffer_pool_pages_misc1758724 Ref: statvar_Innodb_buffer_pool_pages_total1759069 Ref: statvar_Innodb_buffer_pool_read_ahead1759160 Ref: statvar_Innodb_buffer_pool_read_ahead_evicted1759372 Ref: statvar_Innodb_buffer_pool_read_ahead_rnd1759668 Ref: statvar_Innodb_buffer_pool_read_ahead_seq1759935 Ref: statvar_Innodb_buffer_pool_read_requests1760181 Ref: statvar_Innodb_buffer_pool_reads1760284 Ref: statvar_Innodb_buffer_pool_wait_free1760451 Ref: statvar_Innodb_buffer_pool_write_requests1760859 Ref: statvar_Innodb_data_fsyncs1760960 Ref: statvar_Innodb_data_pending_fsyncs1761037 Ref: statvar_Innodb_data_pending_reads1761131 Ref: statvar_Innodb_data_pending_writes1761209 Ref: statvar_Innodb_data_read1761289 Ref: statvar_Innodb_data_reads1761375 Ref: statvar_Innodb_data_writes1761440 Ref: statvar_Innodb_data_written1761507 Ref: statvar_Innodb_dblwr_pages_written1761587 Ref: statvar_Innodb_dblwr_writes1761733 Ref: statvar_Innodb_have_atomic_builtins1761864 Ref: statvar_Innodb_log_waits1762044 Ref: statvar_Innodb_log_write_requests1762199 Ref: statvar_Innodb_log_writes1762274 Ref: statvar_Innodb_os_log_fsyncs1762354 Ref: statvar_Innodb_os_log_pending_fsyncs1762443 Ref: statvar_Innodb_os_log_pending_writes1762540 Ref: statvar_Innodb_os_log_written1762623 Ref: statvar_Innodb_page_size1762705 Ref: statvar_Innodb_pages_created1762892 Ref: statvar_Innodb_pages_read1762957 Ref: statvar_Innodb_pages_written1763016 Ref: statvar_Innodb_row_lock_current_waits1763081 Ref: statvar_Innodb_row_lock_time1763178 Ref: statvar_Innodb_row_lock_time_avg1763276 Ref: statvar_Innodb_row_lock_time_max1763373 Ref: statvar_Innodb_row_lock_waits1763470 Ref: statvar_Innodb_rows_deleted1763560 Ref: statvar_Innodb_rows_inserted1763644 Ref: statvar_Innodb_rows_read1763730 Ref: statvar_Innodb_rows_updated1763808 Ref: statvar_Key_blocks_not_flushed1763890 Ref: statvar_Key_blocks_unused1764032 Ref: statvar_Key_blocks_used1764270 Ref: statvar_Key_read_requests1764471 Ref: statvar_Key_reads1764563 Ref: statvar_Key_write_requests1764814 Ref: statvar_Key_writes1764906 Ref: statvar_Last_query_cost1764986 Ref: statvar_Max_used_connections1765547 Ref: statvar_Not_flushed_delayed_rows1765685 Ref: statvar_Open_files1765822 Ref: statvar_Open_streams1766172 Ref: statvar_Open_table_definitions1766263 Ref: statvar_Open_tables1766381 Ref: statvar_Opened_files1766444 Ref: statvar_Opened_table_definitions1766709 Ref: statvar_Opened_tables1766845 Ref: statvar_Prepared_stmt_count1767003 Ref: statvar_Qcache_free_blocks1767226 Ref: statvar_Qcache_free_memory1767313 Ref: statvar_Qcache_hits1767394 Ref: statvar_Qcache_inserts1767453 Ref: statvar_Qcache_lowmem_prunes1767531 Ref: statvar_Qcache_not_cached1767656 Ref: statvar_Qcache_queries_in_cache1767796 Ref: statvar_Qcache_total_blocks1767888 Ref: statvar_Queries1767970 Ref: statvar_Questions1768257 Ref: statvar_Rpl_status1768661 Ref: statvar_Select_full_join1768800 Ref: statvar_Select_full_range_join1768999 Ref: statvar_Select_range1769104 Ref: statvar_Select_range_check1769266 Ref: statvar_Select_scan1769457 Ref: statvar_Slave_open_temp_tables1769545 Ref: statvar_Slave_retried_transactions1769789 Ref: statvar_Slave_running1769940 Ref: statvar_Slow_launch_threads1770143 Ref: statvar_Slow_queries1770269 Ref: statvar_Sort_merge_passes1770524 Ref: statvar_Sort_range1770741 Ref: statvar_Sort_rows1770816 Ref: statvar_Sort_scan1770868 Ref: statvar_Ssl_accept_renegotiates1770951 Ref: statvar_Ssl_accepts1771051 Ref: statvar_Ssl_callback_cache_hits1771118 Ref: statvar_Ssl_cipher1771192 Ref: statvar_Ssl_cipher_list1771274 Ref: statvar_Ssl_client_connects1771339 Ref: statvar_Ssl_connect_renegotiates1771438 Ref: statvar_Ssl_ctx_verify_depth1771569 Ref: statvar_Ssl_ctx_verify_mode1771694 Ref: statvar_Ssl_default_timeout1771764 Ref: statvar_Ssl_finished_accepts1771824 Ref: statvar_Ssl_finished_connects1771916 Ref: statvar_Ssl_session_cache_hits1772027 Ref: statvar_Ssl_session_cache_misses1772103 Ref: statvar_Ssl_session_cache_mode1772183 Ref: statvar_Ssl_session_cache_overflows1772249 Ref: statvar_Ssl_session_cache_size1772335 Ref: statvar_Ssl_session_cache_timeouts1772401 Ref: statvar_Ssl_sessions_reused1772485 Ref: statvar_Ssl_used_session_cache_entries1772573 Ref: statvar_Ssl_verify_depth1772665 Ref: statvar_Ssl_verify_mode1772753 Ref: statvar_Ssl_version1772839 Ref: statvar_Table_locks_immediate1772910 Ref: statvar_Table_locks_waited1773034 Ref: statvar_Tc_log_max_pages_used1773345 Ref: statvar_Tc_log_page_size1774191 Ref: statvar_Tc_log_page_waits1774471 Ref: statvar_Threads_cached1775040 Ref: statvar_Threads_connected1775113 Ref: statvar_Threads_created1775188 Ref: statvar_Threads_running1775446 Ref: statvar_Uptime1775522 Ref: statvar_Uptime_since_flush_status1775595 Node: server-sql-mode1775741 Ref: sql-mode-important1778707 Ref: sql-mode-full1780083 Ref: sqlmode_allow_invalid_dates1780167 Ref: sqlmode_ansi_quotes1781126 Ref: sqlmode_error_for_division_by_zero1781493 Ref: sqlmode_high_not_precedence1782102 Ref: sqlmode_ignore_space1782714 Ref: sqlmode_no_auto_create_user1783733 Ref: sqlmode_no_auto_value_on_zero1783935 Ref: sqlmode_no_backslash_escapes1784952 Ref: sqlmode_no_dir_in_create1785168 Ref: sqlmode_no_engine_substitution1785347 Ref: sqlmode_no_field_options1786758 Ref: sqlmode_no_key_options1786978 Ref: sqlmode_no_table_options1787195 Ref: sqlmode_no_unsigned_subtraction1787433 Ref: sqlmode_no_zero_date1789542 Ref: sqlmode_no_zero_in_date1789774 Ref: sqlmode_only_full_group_by1790177 Ref: sqlmode_pad_char_to_full_length1791694 Ref: sqlmode_pipes_as_concat1793102 Ref: sqlmode_real_as_float1793240 Ref: sqlmode_strict_all_tables1793496 Ref: sqlmode_strict_trans_tables1793639 Ref: sql-mode-combo1796620 Ref: sqlmode_ansi1796986 Ref: sqlmode_db21797837 Ref: sqlmode_maxdb1797983 Ref: sqlmode_mssql1798159 Ref: sqlmode_mysql3231798307 Ref: sqlmode_mysql401798388 Ref: sqlmode_oracle1798468 Ref: sqlmode_postgresql1798645 Ref: sqlmode_traditional1798798 Node: server-plugins1798976 Node: server-plugin-loading1799643 Ref: server-plugin-installing1800200 Ref: server-plugin-activating1804399 Ref: server-plugin-uninstalling1808003 Node: obtaining-plugin-information1808976 Node: server-side-help-support1811702 Node: server-signal-response1813380 Node: server-shutdown1815224 Node: server-logs1819572 Node: log-destinations1822433 Node: error-log1831741 Node: query-log1838599 Node: binary-log1843610 Node: binary-log-formats1857980 Node: binary-log-setting1860362 Node: binary-log-mixed1865946 Node: binary-log-mysql-database1876357 Node: slow-query-log1878109 Node: log-file-maintenance1884110 Node: multiple-servers1888734 Node: multiple-data-directories1893923 Node: multiple-windows-servers1897258 Node: multiple-windows-command-line-servers1898247 Node: multiple-windows-services1901367 Node: multiple-unix-servers1905719 Node: multiple-server-clients1909653 Node: security1912439 Node: general-security-issues1914395 Node: security-guidelines1915480 Node: password-security1920837 Node: password-security-user1921692 Node: password-security-admin1926580 Node: password-logging1927416 Node: password-hashing1928633 Node: application-password-use1946874 Node: security-against-attack1948337 Node: security-options1955532 Node: changing-mysql-user1957989 Node: load-data-local1960349 Node: secure-client-programming1963759 Node: privilege-system1968317 Node: privileges-provided1972907 Ref: priv_all1977416 Ref: priv_alter1977717 Ref: priv_alter-routine1978049 Ref: priv_create1978162 Ref: priv_create-routine1978243 Ref: priv_create-temporary-tables1978350 Ref: priv_create-user1979201 Ref: priv_create-view1979402 Ref: priv_delete1979491 Ref: priv_drop1979580 Ref: priv_event1980214 Ref: priv_execute1980370 Ref: priv_file1980473 Ref: priv_grant-option1981479 Ref: priv_index1981631 Ref: priv_insert1981896 Ref: priv_lock-tables1982179 Ref: priv_process1982459 Ref: priv_references1982869 Ref: priv_reload1982924 Ref: priv_replication-client1983739 Ref: priv_replication-slave1984027 Ref: priv_select1984306 Ref: priv_show-databases1985206 Ref: priv_show-view1985619 Ref: priv_shutdown1985716 Ref: priv_super1985869 Ref: priv_trigger1986906 Ref: priv_update1987190 Ref: priv_usage1987277 Node: grant-table-structure1989172 Node: account-names2003378 Node: connection-access2009992 Node: request-access2018488 Node: privilege-changes2027146 Node: access-denied2029459 Node: user-account-management2047926 Node: user-names2049184 Node: adding-users2055261 Node: removing-users2067256 Node: user-resources2067546 Node: assigning-passwords2075143 Node: ssl-connections2080409 Node: ssl-basics2082081 Node: configuring-for-ssl2084335 Node: using-ssl-connections2087722 Node: ssl-options2092006 Ref: option_general_ssl2094328 Ref: option_general_ssl-ca2096525 Ref: option_general_ssl-capath2097156 Ref: option_general_ssl-cert2098441 Ref: option_general_ssl-cipher2098607 Ref: option_general_ssl-key2099384 Ref: option_general_ssl-verify-server-cert2099970 Node: creating-ssl-certs2100510 Node: windows-and-ssh2114325 Node: account-activity-auditing2116072 Node: backup-and-recovery2121213 Node: backup-types2124369 Node: backup-methods2134408 Node: backup-strategy-example2141676 Node: backup-policy2145176 Node: recovery-from-backups2152696 Node: backup-strategy-summary2154728 Node: using-mysqldump2155774 Node: mysqldump-sql-format2157918 Node: reloading-sql-format-dumps2160976 Node: mysqldump-delimited-text2162284 Node: reloading-delimited-text-dumps2166552 Node: mysqldump-tips2168164 Node: mysqldump-copying-database2169052 Node: mysqldump-copying-to-other-server2169597 Node: mysqldump-stored-programs2170850 Node: mysqldump-definition-data-dumps2171720 Node: mysqldump-upgrade-testing2172740 Node: point-in-time-recovery2174096 Node: point-in-time-recovery-times2178850 Node: point-in-time-recovery-positions2180998 Node: myisam-table-maintenance2183350 Node: myisam-crash-recovery2186036 Node: myisam-check2189673 Node: myisam-repair2191526 Node: myisam-optimization2199224 Node: myisam-maintenance-schedule2200871 Node: optimization2203364 Node: optimize-overview2204509 Node: design-limitations2206314 Node: portability2208069 Node: mysql-benchmarks2212028 Node: custom-benchmarks2214428 Node: execution-plan-information2216566 Node: using-explain2217055 Node: explain-output2219248 Ref: explain-output-columns2220836 Ref: explain-output-column-table2221248 Ref: explain_id2221868 Ref: explain_select_type2222258 Ref: explain_table2224462 Ref: explain_partitions2224900 Ref: explain_type2225151 Ref: explain_possible_keys2225258 Ref: explain_key2226137 Ref: explain_key_len2227614 Ref: explain_ref2227903 Ref: explain_rows2228060 Ref: explain_filtered2228304 Ref: explain_extra2228731 Ref: explain-join-types2228912 Ref: jointype_system2229117 Ref: jointype_const2229238 Ref: jointype_eq_ref2229883 Ref: jointype_ref2230783 Ref: jointype_fulltext2231722 Ref: jointype_ref_or_null2231794 Ref: jointype_index_merge2232250 Ref: jointype_unique_subquery2232584 Ref: jointype_index_subquery2232891 Ref: jointype_range2233154 Ref: jointype_index2233947 Ref: jointype_all2234736 Ref: explain-extra-information2235129 Ref: explain-output-interpretation2244414 Node: explain-extended2251454 Node: estimating-performance2255236 Node: statement-optimization2257041 Node: select-optimization2257512 Node: select-speed2260406 Node: where-optimizations2262153 Node: range-optimization2266900 Node: range-access-single-part2267574 Node: range-access-multi-part2272048 Node: index-merge-optimization2277332 Node: index-merge-intersection2280192 Node: index-merge-union2281845 Node: index-merge-sort-union2282900 Node: condition-pushdown-optimization2283662 Node: is-null-optimization2288271 Node: left-join-optimization2290426 Node: nested-loop-joins2293411 Node: nested-join-optimization2297128 Node: outer-join-simplification2310862 Node: order-by-optimization2316629 Node: group-by-optimization2326108 Node: loose-index-scan2327692 Node: tight-index-scan2331405 Node: distinct-optimization2333519 Node: subquery-optimization-with-exists2335060 Node: limit-optimization2347624 Node: how-to-avoid-table-scan2349928 Node: non-select-optimization2351913 Node: insert-speed2352410 Node: update-speed2359142 Node: delete-speed2360041 Node: repair-table-speed2360762 Node: information-schema-optimization2365686 Node: miscellaneous-optimization-tips2381448 Node: controlling-optimizer2392389 Node: controlling-query-plan-evaluation2392894 Node: switchable-optimizations2395947 Node: optimization-indexes2399804 Node: column-indexes2400242 Node: multiple-column-indexes2402363 Node: mysql-indexes2406410 Node: myisam-index-statistics2415144 Node: buffering-caching2421290 Node: myisam-key-cache2421737 Node: shared-key-cache2425619 Node: multiple-key-caches2426446 Node: midpoint-insertion2431945 Node: index-preloading2434492 Node: key-cache-block-size2436301 Node: key-cache-restructuring2437224 Node: innodb-buffer-pool2438603 Node: query-cache2447036 Node: query-cache-operation2451384 Node: query-cache-in-select2457744 Node: query-cache-configuration2458732 Node: query-cache-status-and-maintenance2465240 Node: locking-issues2468083 Node: internal-locking2469072 Node: table-locking2476129 Node: concurrent-inserts2481401 Node: external-locking2484345 Node: optimizing-database-structure2488956 Node: data-size2489527 Node: procedure-analyse2494518 Node: table-cache2496102 Node: creating-many-tables2501593 Node: internal-temporary-tables2502275 Node: optimizing-the-server2505313 Node: system-optimization2506028 Node: server-parameters2508638 Node: connection-threads2525081 Node: memory-use2528343 Node: disk-issues2534190 Node: symbolic-links2538327 Node: symbolic-links-to-databases2539317 Node: symbolic-links-to-tables2540404 Node: windows-symbolic-links2544992 Node: large-page-support2547810 Node: host-cache2552504 Node: thread-information2556349 Node: thread-commands2559429 Node: general-thread-states2562013 Node: delayed-insert-thread-states2574756 Node: query-cache-thread-states2577798 Node: master-thread-states2578762 Node: slave-io-thread-states2580080 Node: slave-sql-thread-states2583385 Node: slave-connection-thread-states2584729 Node: mysql-cluster-thread-states2586106 Node: event-scheduler-thread-states2587188 Node: language-structure2588136 Node: literals2588948 Node: string-literals2589732 Ref: character-escape-sequences2592270 Node: number-literals2596660 Node: date-and-time-literals2597281 Ref: date-and-time-standard-sql-literals2598015 Ref: date-and-time-string-numeric-literals2598545 Node: hexadecimal-literals2604666 Node: boolean-literals2606288 Node: bit-field-literals2606651 Node: null-values2608222 Node: identifiers2608848 Node: identifier-qualifiers2614994 Node: identifier-case-sensitivity2617412 Node: identifier-mapping2624754 Node: function-resolution2632056 Node: reserved-words2642762 Ref: table-reserved-words-5.1.732645037 Ref: table-reserved-words-new-5.12649573 Node: user-variables2650100 Node: expressions2658117 Node: comments2662085 Node: globalization2664942 Node: charset2666032 Node: charset-general2668431 Node: charset-mysql2671122 Node: charset-syntax2676574 Node: charset-server2678273 Node: charset-database2680446 Node: charset-table2682929 Node: charset-column2684589 Node: charset-literal2687935 Node: charset-national2692700 Node: charset-examples2693757 Node: charset-compatibility2696052 Node: charset-connection2696388 Node: charset-applications2704225 Node: charset-errors2710092 Node: charset-collations2711661 Node: charset-collation-names2712504 Node: charset-collate2712993 Node: charset-collate-precedence2714329 Node: charset-collation-charset2714701 Node: charset-collation-expressions2715371 Node: charset-binary-collations2719460 Node: charset-binary-op2725250 Node: charset-collation-effect2727389 Node: charset-collation-information-schema2730674 Node: charset-repertoire2735700 Node: charset-operations2740647 Node: charset-result2741142 Node: charset-convert2744138 Node: charset-show2745624 Node: charset-unicode2750670 Node: charset-unicode-ucs22752988 Node: charset-unicode-utf82753747 Node: charset-metadata2755284 Node: charset-conversion2759458 Node: charset-charsets2763530 Node: charset-unicode-sets2767859 Node: charset-we-sets2773179 Node: charset-ce-sets2776925 Node: charset-se-me-sets2778516 Node: charset-baltic-sets2780118 Node: charset-cyrillic-sets2780944 Node: charset-asian-sets2782193 Node: charset-cp9322784632 Node: error-message-language2791440 Node: adding-character-set2793039 Node: character-arrays2800437 Node: string-collating2803605 Node: multi-byte-characters2804649 Node: adding-collation2805520 Node: charset-collation-implementations2808589 Node: adding-collation-choosing-id2812678 Node: adding-collation-simple-8bit2814923 Node: adding-collation-unicode-uca2818735 Node: ldml-collation-example2820230 Node: ldml-rules2826141 Node: charset-configuration2828653 Node: time-zone-support2831950 Node: time-zone-upgrades2839566 Node: time-zone-leap-seconds2845091 Node: locale-support2848679 Node: data-types2855670 Node: data-type-overview2857672 Node: numeric-type-overview2858007 Node: date-and-time-type-overview2868945 Node: string-type-overview2874001 Node: numeric-types2885963 Node: integer-types2888314 Node: fixed-point-types2889734 Node: floating-point-types2891754 Node: bit-type2893528 Node: numeric-type-attributes2894294 Node: out-of-range-and-overflow2897384 Node: date-and-time-types2901805 Node: datetime2907391 Node: time2912112 Node: year2914335 Node: migrating-to-year42916418 Node: timestamp-initialization2921564 Node: fractional-seconds2931714 Node: date-and-time-type-conversion2932579 Node: two-digit-years2935961 Node: string-types2937473 Node: char2938295 Node: binary-varbinary2944273 Node: blob2948352 Node: enum2953904 Ref: enum-using2954948 Ref: enum-indexes2955833 Ref: enum-literals2957583 Ref: enum-nulls2959690 Ref: enum-sorting2960612 Ref: enum-limits2961270 Node: set2962562 Node: data-type-defaults2968666 Node: storage-requirements2972384 Ref: data-types-storage-reqs-date-time2978415 Node: choosing-types2984842 Node: other-vendor-data-types2986058 Node: functions2988780 Node: func-op-summary-ref2992135 Node: type-conversion3011347 Node: non-typed-operators3016693 Node: operator-precedence3019470 Node: comparison-operators3021277 Ref: operator_equal3024232 Ref: operator_equal-to3024545 Ref: operator_not-equal3024963 Ref: operator_less-than-or-equal3025191 Ref: operator_less-than3025287 Ref: operator_greater-than-or-equal3025370 Ref: operator_greater-than3025467 Ref: operator_is3025553 Ref: operator_is-not3025781 Ref: operator_is-null3026030 Ref: operator_is-not-null3027847 Ref: operator_between3028013 Ref: operator_not-between3029311 Ref: function_coalesce3029409 Ref: function_greatest3029684 Ref: function_in3030155 Ref: function_not-in3031736 Ref: function_isnull3031824 Ref: function_interval3032336 Ref: function_least3032880 Node: logical-operators3034427 Ref: operator_not3035376 Ref: operator_and3035903 Ref: operator_or3036370 Ref: operator_xor3036957 Node: assignment-operators3037471 Ref: operator_assign-value3038010 Ref: operator_assign-equal3040071 Node: control-flow-functions3041822 Ref: operator_case3042278 Ref: function_if3043797 Ref: function_ifnull3045187 Ref: function_nullif3046555 Node: string-functions3046940 Ref: function_ascii3052439 Ref: function_bin3052876 Ref: function_bit-length3053161 Ref: function_char3053307 Ref: function_char-length3055245 Ref: function_character-length3055533 Ref: function_concat3055625 Ref: function_concat-ws3056605 Ref: function_elt3057388 Ref: function_export-set3057838 Ref: function_field3058744 Ref: function_find-in-set3059460 Ref: function_format3060185 Ref: function_hex3060644 Ref: function_insert3061405 Ref: function_instr3062139 Ref: function_lcase3062635 Ref: function_left3062699 Ref: function_length3062943 Ref: function_load-file3063281 Ref: function_locate3064202 Ref: function_lower3064879 Ref: function_lpad3065895 Ref: function_ltrim3066247 Ref: function_make-set3066449 Ref: function_mid3067134 Ref: function_oct3067228 Ref: function_octet-length3067510 Ref: function_ord3067589 Ref: function_position3068099 Ref: function_quote3068203 Ref: function_repeat3068947 Ref: function_replace3069235 Ref: function_reverse3069603 Ref: function_right3069805 Ref: function_rpad3070051 Ref: function_rtrim3070443 Ref: function_soundex3070647 Ref: operator_sounds-like3072210 Ref: function_space3072304 Ref: function_substr3072444 Ref: function_substring3072602 Ref: function_substring-index3074029 Ref: function_trim3074722 Ref: function_ucase3075431 Ref: function_unhex3075495 Ref: function_upper3077314 Node: string-comparison-functions3077935 Ref: operator_like3078703 Ref: operator_not-like3084427 Ref: function_strcmp3085493 Node: regexp3087287 Ref: operator_not-regexp3088398 Ref: operator_regexp3088500 Node: numeric-functions3102197 Node: arithmetic-functions3105245 Ref: operator_plus3107677 Ref: operator_minus3107757 Ref: operator_unary-minus3107841 Ref: operator_times3108217 Ref: operator_divide3108424 Ref: operator_div3108782 Ref: operator_mod3109071 Node: mathematical-functions3109269 Ref: function_abs3111882 Ref: function_acos3112135 Ref: function_asin3112474 Ref: function_atan3113293 Ref: function_atan23113533 Ref: function_ceil3113940 Ref: function_ceiling3114002 Ref: function_conv3114392 Ref: function_cos3115230 Ref: function_cot3115366 Ref: function_crc323115546 Ref: function_degrees3115949 Ref: function_exp3116166 Ref: function_floor3116560 Ref: function_ln3117431 Ref: function_log3117831 Ref: function_log23118680 Ref: function_log103119025 Ref: function_mod3119327 Ref: function_pi3119959 Ref: function_pow3120289 Ref: function_power3120481 Ref: function_radians3120538 Ref: function_rand3120746 Ref: function_round3124659 Ref: function_sign3127277 Ref: function_sin3127589 Ref: function_sqrt3127805 Ref: function_tan3128068 Ref: function_truncate3128297 Node: date-and-time-functions3129002 Ref: function_adddate3136374 Ref: function_addtime3137131 Ref: function_convert-tz3137543 Ref: function_curdate3138784 Ref: function_current-date3139108 Ref: function_current-time3139220 Ref: function_current-timestamp3139332 Ref: function_curtime3139465 Ref: function_date3139849 Ref: function_datediff3140027 Ref: function_date-add3140478 Ref: function_date-format3148003 Ref: function_date-sub3151950 Ref: function_day3152037 Ref: function_dayname3152103 Ref: function_dayofmonth3152407 Ref: function_dayofweek3152673 Ref: function_dayofyear3152925 Ref: function_extract3153095 Ref: function_from-days3153731 Ref: function_from-unixtime3154086 Ref: function_get-format3155417 Ref: function_hour3157386 Ref: function_last-day3157779 Ref: function_localtime3158290 Ref: function_localtimestamp3158386 Ref: function_makedate3158502 Ref: function_maketime3158948 Ref: function_microsecond3159151 Ref: function_minute3159479 Ref: function_month3159641 Ref: function_monthname3159912 Ref: function_now3160223 Ref: function_period-add3162358 Ref: function_period-diff3162631 Ref: function_quarter3162926 Ref: function_second3163093 Ref: function_sec-to-time3163244 Ref: function_str-to-date3163714 Ref: function_subdate3166476 Ref: function_subtime3167242 Ref: function_sysdate3167687 Ref: function_time3170019 Ref: function_timediff3170530 Ref: function_timestamp3171301 Ref: function_timestampadd3171821 Ref: function_timestampdiff3172750 Ref: function_time-format3173765 Ref: function_time-to-sec3174381 Ref: function_to-days3174615 Ref: function_unix-timestamp3176851 Ref: function_utc-date3179712 Ref: function_utc-time3180011 Ref: function_utc-timestamp3180316 Ref: function_week3180688 Ref: function_weekday3183484 Ref: function_weekofyear3183752 Ref: function_year3184031 Ref: function_yearweek3184219 Node: mysql-calendar3184790 Node: fulltext-search3186991 Ref: function_match3187627 Node: fulltext-natural-language3191205 Node: fulltext-boolean3202130 Node: fulltext-query-expansion3209254 Node: fulltext-stopwords3212401 Node: fulltext-restrictions3220881 Node: fulltext-fine-tuning3222768 Node: full-text-adding-collation3230513 Node: cast-functions3234876 Ref: operator_binary3235304 Ref: function_cast3236295 Ref: function_convert3236523 Node: xml-functions3242577 Ref: function_extractvalue3248835 Ref: function_updatexml3255000 Node: bit-functions3275699 Ref: operator_bitwise-or3276373 Ref: operator_bitwise-and3276508 Ref: operator_bitwise-xor3276644 Ref: operator_left-shift3276886 Ref: operator_right-shift3277247 Ref: operator_bitwise-invert3277609 Ref: function_bit-count3277747 Node: encryption-functions3277917 Ref: function_aes-decrypt3282174 Ref: function_aes-encrypt3282385 Ref: function_compress3284516 Ref: function_decode3286001 Ref: function_des-decrypt3286176 Ref: function_des-encrypt3287079 Ref: function_encode3289141 Ref: function_encrypt3289651 Ref: function_md53290493 Ref: function_old-password3291083 Ref: function_password3291544 Ref: function_sha13294077 Ref: function_uncompress3294903 Ref: function_uncompressed-length3295410 Node: information-functions3295635 Ref: function_benchmark3297265 Ref: function_charset3299708 Ref: function_coercibility3300014 Ref: function_collation3301110 Ref: function_connection-id3301356 Ref: function_current-user3301613 Ref: function_database3304202 Ref: function_found-rows3304726 Ref: function_last-insert-id3308799 Ref: function_row-count3317395 Ref: function_schema3319570 Ref: function_session-user3319639 Ref: function_system-user3319713 Ref: function_user3319785 Ref: function_version3320318 Node: miscellaneous-functions3320887 Ref: function_default3322350 Ref: function_get-lock3322751 Ref: function_inet-aton3325713 Ref: function_inet-ntoa3326765 Ref: function_is-free-lock3327093 Ref: function_is-used-lock3327567 Ref: function_master-pos-wait3327986 Ref: function_name-const3329175 Ref: function_release-lock3329850 Ref: function_sleep3330581 Ref: function_uuid3331001 Ref: function_uuid-short3333069 Ref: function_values3334179 Node: group-by-functions-and-modifiers3335049 Node: group-by-functions3335505 Ref: function_avg3338392 Ref: function_bit-and3338758 Ref: function_bit-or3339113 Ref: function_bit-xor3339341 Ref: function_count3339571 Ref: function_count-distinct3340819 Ref: function_group-concat3341334 Ref: function_max3343859 Ref: function_min3344735 Ref: function_std3345611 Ref: function_stddev3345864 Ref: function_stddev-pop3346139 Ref: function_stddev-samp3346416 Ref: function_sum3346603 Ref: function_var-pop3346866 Ref: function_var-samp3347210 Ref: function_variance3347406 Node: group-by-modifiers3347654 Node: group-by-extensions3356699 Node: spatial-extensions3360854 Node: gis-introduction3362746 Node: opengis-geometry-model3365051 Node: gis-geometry-class-hierarchy3366331 Node: gis-class-geometry3368977 Node: gis-class-point3372528 Node: gis-class-curve3373161 Node: gis-class-linestring3374008 Node: gis-class-surface3374695 Node: gis-class-polygon3375418 Node: gis-class-geometrycollection3376645 Node: gis-class-multipoint3377478 Node: gis-class-multicurve3378253 Node: gis-class-multilinestring3379215 Node: gis-class-multisurface3379654 Node: gis-class-multipolygon3380236 Node: supported-spatial-data-formats3381711 Node: gis-wkt-format3382395 Node: gis-wkb-format3384814 Node: creating-a-spatially-enabled-mysql-database3386565 Node: mysql-spatial-datatypes3387303 Node: creating-spatial-values3388291 Node: gis-wkt-functions3388969 Ref: function_geomcollfromtext3389621 Ref: function_geomfromtext3389796 Ref: function_linefromtext3389952 Ref: function_mlinefromtext3390102 Ref: function_mpointfromtext3390263 Ref: function_mpolyfromtext3390415 Ref: function_pointfromtext3390570 Ref: function_polyfromtext3390677 Ref: function_bdmpolyfromtext3391099 Ref: function_bdpolyfromtext3391295 Node: gis-wkb-functions3391480 Ref: function_geomcollfromwkb3392278 Ref: function_geomfromwkb3392451 Ref: function_linefromwkb3392605 Ref: function_mlinefromwkb3392753 Ref: function_mpointfromwkb3392912 Ref: function_mpolyfromwkb3393062 Ref: function_pointfromwkb3393215 Ref: function_polyfromwkb3393321 Ref: function_bdmpolyfromwkb3393729 Ref: function_bdpolyfromwkb3393924 Node: gis-mysql-specific-functions3394108 Ref: function_geometrycollection3395422 Ref: function_linestring3395502 Ref: function_multilinestring3395707 Ref: function_multipoint3395843 Ref: function_multipolygon3395959 Ref: function_point3396095 Ref: function_polygon3396165 Node: creating-spatial-columns3396428 Node: populating-spatial-columns3397396 Node: fetching-spatial-data3400344 Node: spatial-analysis-functions3401269 Node: functions-to-convert-geometries-between-formats3402709 Ref: function_asbinary3403115 Ref: function_astext3403302 Node: geometry-property-functions3404327 Node: general-geometry-property-functions3405435 Ref: function_dimension3405793 Ref: function_envelope3406367 Ref: function_geometrytype3407082 Ref: function_srid3407639 Ref: function_boundary3408384 Ref: function_isempty3408510 Ref: function_issimple3408732 Node: point-property-functions3409071 Ref: function_x3409400 Ref: function_y3409739 Node: linestring-property-functions3410073 Ref: function_endpoint3410478 Ref: function_glength3410948 Ref: function_isclosed3411503 Ref: function_numpoints3412612 Ref: function_pointn3413033 Ref: function_startpoint3413525 Node: multilinestring-property-functions3414007 Node: polygon-property-functions3415536 Ref: function_area3415831 Ref: function_exteriorring3416311 Ref: function_interiorringn3416873 Ref: function_numinteriorrings3417499 Node: multipolygon-property-functions3418024 Ref: function_centroid3418867 Node: geometrycollection-property-functions3419850 Ref: function_geometryn3420146 Ref: function_numgeometries3420700 Node: functions-that-create-new-geometries-from-existing-ones3421180 Node: functions-that-produce-new-geometries3421808 Node: spatial-operators3422480 Ref: function_buffer3422871 Ref: function_convexhull3423032 Ref: function_difference3423142 Ref: function_intersection3423274 Ref: function_symdifference3423411 Ref: function_union3423556 Node: functions-for-testing-spatial-relations-between-geometric-objects3423673 Node: relations-on-geometry-mbr3424394 Ref: function_mbrcontains3424994 Ref: function_mbrdisjoint3425700 Ref: function_mbrequal3425871 Ref: function_mbrintersects3426020 Ref: function_mbroverlaps3426171 Ref: function_mbrtouches3426515 Ref: function_mbrwithin3426863 Node: functions-that-test-spatial-relationships-between-geometries3427562 Ref: function_contains3428291 Ref: function_crosses3428441 Ref: function_disjoint3429068 Ref: function_equals3429194 Ref: function_intersects3429287 Ref: function_overlaps3429383 Ref: function_touches3429672 Ref: function_within3429966 Node: optimizing-spatial-analysis3430111 Node: creating-spatial-indexes3431710 Node: using-a-spatial-index3434237 Node: mysql-gis-conformance-and-compatibility3440900 Node: precision-math3441901 Node: precision-math-numbers3444370 Node: precision-math-decimal-changes3446062 Node: precision-math-expressions3450027 Node: precision-math-rounding3454920 Node: precision-math-examples3456930 Node: sql-syntax3465711 Node: sql-syntax-data-definition3466529 Node: alter-database3468692 Node: alter-event3472208 Node: alter-logfile-group3477148 Node: alter-function3481213 Node: alter-procedure3482369 Node: alter-server3483496 Node: alter-table3484369 Node: alter-table-partition-operations3511190 Node: alter-table-online-operations3524369 Ref: alter-table-online-limitations3530158 Node: alter-table-examples3536509 Node: alter-tablespace3542958 Node: alter-view3547000 Node: create-database3547982 Node: create-event3549947 Node: create-function3566285 Node: create-index3566788 Node: create-logfile-group3578473 Node: create-procedure3584384 Node: create-server3601941 Node: create-table3604923 Node: create-table-select3665221 Node: create-table-foreign-keys3674888 Node: silent-column-changes3690264 Node: create-tablespace3693341 Node: create-trigger3699970 Node: create-view3707795 Node: drop-database3723229 Node: drop-event3725356 Node: drop-function3726176 Node: drop-index3726659 Node: drop-logfile-group3728848 Node: drop-procedure3729870 Node: drop-server3730932 Node: drop-table3731765 Node: drop-tablespace3733681 Node: drop-trigger3734721 Node: drop-view3735938 Node: rename-database3736775 Node: rename-table3737645 Node: truncate-table3740011 Node: sql-syntax-data-manipulation3745233 Node: call3745950 Node: delete3751418 Node: do3763144 Node: handler3763644 Node: insert3768842 Node: insert-select3783610 Node: insert-delayed3787141 Node: insert-on-duplicate3795638 Node: load-data3799113 Node: replace3831018 Node: select3835029 Node: select-into3853993 Node: join3860770 Node: index-hints3881459 Node: union3887943 Node: subqueries3893769 Node: scalar-subqueries3897596 Node: comparisons-using-subqueries3899925 Node: any-in-some-subqueries3901469 Node: all-subqueries3903583 Node: row-subqueries3905286 Node: exists-and-not-exists-subqueries3907826 Node: correlated-subqueries3909904 Node: from-clause-subqueries3912042 Node: subquery-errors3918498 Node: optimizing-subqueries3921293 Node: rewriting-subqueries3925377 Node: update3927001 Node: sql-syntax-transactions3933716 Node: commit3934815 Node: cannot-roll-back3942762 Node: implicit-commit3943490 Node: savepoint3949102 Node: lock-tables3951446 Node: lock-tables-and-transactions3962425 Node: lock-tables-and-triggers3965615 Node: lock-tables-restrictions3967806 Node: set-transaction3971953 Ref: set-transaction-scope3972433 Ref: set-transaction-isolation-level3974503 Ref: isolevel_repeatable-read3975750 Ref: isolevel_read-committed3976967 Ref: isolevel_read-uncommitted3978079 Ref: isolevel_serializable3978422 Node: xa3979035 Node: xa-statements3984775 Node: xa-states3989007 Node: sql-syntax-replication3991985 Node: replication-master-sql3992537 Node: purge-binary-logs3993528 Node: reset-master3996740 Node: set-sql-log-bin3998833 Node: replication-slave-sql3999244 Node: change-master-to4000327 Node: load-data-from-master4012623 Node: load-table-from-master4015895 Node: master-pos-wait4017681 Node: reset-slave4018178 Node: set-global-sql-slave-skip-counter4020024 Node: start-slave4021471 Node: stop-slave4025588 Node: sql-syntax-prepared-statements4027448 Node: prepare4036489 Node: execute4039000 Node: deallocate-prepare4039958 Node: statement-repreparation4040535 Node: sql-syntax-compound-statements4042741 Node: begin-end4043922 Node: statement-labels4045724 Node: declare4047340 Node: stored-program-variables4048128 Node: declare-local-variable4049482 Node: local-variable-scope4050669 Node: flow-control-statements4053365 Node: case4054584 Node: if4057012 Node: iterate4059398 Node: leave4059787 Node: loop4060329 Node: repeat4061450 Node: return4062618 Node: while4063227 Node: cursors4063988 Node: close4065521 Node: declare-cursor4065958 Node: fetch4067067 Node: open4067911 Node: condition-handling4068146 Node: declare-condition4072058 Node: declare-handler4074024 Node: sql-syntax-server-administration4081163 Node: account-management-sql4081759 Node: create-user4082891 Node: drop-user4085283 Node: grant4086750 Ref: grant-privileges4089953 Ref: grant-global-privileges4095090 Ref: grant-database-privileges4095914 Ref: grant-table-privileges4096709 Ref: grant-column-privileges4097398 Ref: grant-routine-privileges4097886 Ref: grant-accounts-passwords4100057 Ref: grant-other-characteristics4104874 Ref: grant-mysql-vs-standard-sql4113445 Node: rename-user4115307 Node: revoke4116663 Node: set-password4119003 Node: table-maintenance-sql4123095 Node: analyze-table4123708 Node: backup-table4125829 Node: check-table4127403 Node: checksum-table4138332 Node: optimize-table4140147 Node: repair-table4146493 Node: restore-table4153680 Node: plugin-sql4155134 Node: create-function-udf4155635 Node: drop-function-udf4158761 Node: install-plugin4159740 Node: uninstall-plugin4164523 Node: set-statement4166292 Node: show4177208 Node: show-authors4182534 Node: show-binary-logs4182928 Node: show-binlog-events4183877 Node: show-character-set4185138 Node: show-collation4186435 Node: show-columns4189277 Node: show-contributors4194158 Node: show-create-database4194642 Node: show-create-event4195881 Node: show-create-function4198023 Node: show-create-procedure4198403 Node: show-create-table4200539 Node: show-create-trigger4201415 Node: show-create-view4203832 Node: show-databases4206565 Node: show-engine4207782 Ref: show-engine-ndb-status4212259 Node: show-engines4219342 Node: show-errors4223749 Node: show-events4224985 Node: show-function-code4230814 Node: show-function-status4231173 Node: show-grants4231573 Node: show-index4233646 Node: show-innodb-status4236007 Node: show-master-status4236409 Node: show-open-tables4237157 Node: show-plugins4238839 Node: show-privileges4241464 Node: show-procedure-code4242916 Node: show-procedure-status4245320 Node: show-processlist4247207 Node: show-profile4252271 Node: show-profiles4258999 Node: show-scheduler-status4259471 Node: show-slave-hosts4261392 Node: show-slave-status4262915 Node: show-status4277938 Node: show-table-status4281124 Node: show-tables4287185 Node: show-triggers4288328 Node: show-variables4291221 Node: show-warnings4296465 Node: other-administrative-sql4302747 Node: binlog4303252 Node: cache-index4303874 Node: flush4306306 Node: kill4314616 Node: load-index4317663 Node: reset4319738 Node: sql-syntax-utility4320760 Node: describe4321131 Node: explain4321527 Node: help4326005 Node: use4332302 Node: storage-engines4333231 Node: storage-engine-compare-transactions4347350 Node: storage-engines-other4349218 Node: storage-engine-setting4350021 Node: pluggable-storage-overview4352888 Node: pluggable-storage4355126 Node: pluggable-storage-common-layer4356908 Node: myisam-storage-engine4360251 Node: myisam-start4370757 Node: key-space4376139 Node: myisam-table-formats4377270 Node: static-format4378444 Node: dynamic-format4380849 Node: compressed-format4384065 Node: myisam-table-problems4386010 Node: corrupted-myisam-tables4386570 Node: myisam-table-close4388642 Node: innodb-storage-engine4391324 Node: innodb-configuration4401195 Node: replacing-builtin-innodb4415420 Node: innodb-multiple-tablespaces4420757 Node: innodb-raw-devices4430310 Node: innodb-init4432700 Node: error-creating-innodb4436027 Node: innodb-parameters4437562 Ref: option_mysqld_ignore-builtin-innodb4448272 Ref: option_mysqld_innodb4449768 Ref: option_mysqld_innodb-status-file4450396 Ref: sysvar_ignore_builtin_innodb4451350 Ref: sysvar_innodb_adaptive_flushing4452293 Ref: sysvar_innodb_adaptive_hash_index4453398 Ref: sysvar_innodb_additional_mem_pool_size4454609 Ref: sysvar_innodb_autoextend_increment4456030 Ref: sysvar_innodb_buffer_pool_awe_mem_mb4457228 Ref: sysvar_innodb_autoinc_lock_mode4458927 Ref: sysvar_innodb_buffer_pool_size4460159 Ref: sysvar_innodb_change_buffering4463340 Ref: sysvar_innodb_checksums4464474 Ref: sysvar_innodb_commit_concurrency4465417 Ref: sysvar_innodb_concurrency_tickets4466488 Ref: sysvar_innodb_data_file_path4467887 Ref: sysvar_innodb_data_home_dir4469410 Ref: sysvar_innodb_doublewrite4470387 Ref: sysvar_innodb_fast_shutdown4471279 Ref: sysvar_innodb_file_format4472625 Ref: sysvar_innodb_file_format_check4473646 Ref: sysvar_innodb_file_io_threads4475177 Ref: sysvar_innodb_file_per_table4476258 Ref: sysvar_innodb_flush_log_at_trx_commit4477522 Ref: sysvar_innodb_flush_method4480633 Ref: sysvar_innodb_force_recovery4484343 Ref: sysvar_innodb_io_capacity4485803 Ref: sysvar_innodb_lock_wait_timeout4489648 Ref: sysvar_innodb_locks_unsafe_for_binlog4492103 Ref: sysvar_innodb_log_arch_dir4501278 Ref: sysvar_innodb_log_archive4501375 Ref: sysvar_innodb_log_buffer_size4501471 Ref: sysvar_innodb_log_file_size4502679 Ref: sysvar_innodb_log_files_in_group4504051 Ref: sysvar_innodb_log_group_home_dir4504907 Ref: sysvar_innodb_max_dirty_pages_pct4505831 Ref: sysvar_innodb_max_purge_lag4506870 Ref: sysvar_innodb_mirrored_log_groups4509097 Ref: sysvar_innodb_old_blocks_pct4509154 Ref: sysvar_innodb_old_blocks_time4510591 Ref: sysvar_innodb_open_files4512198 Ref: sysvar_innodb_random_read_ahead4513324 Ref: sysvar_innodb_read_ahead_threshold4514656 Ref: sysvar_innodb_read_io_threads4516143 Ref: sysvar_innodb_replication_delay4517440 Ref: sysvar_innodb_rollback_on_timeout4518363 Ref: sysvar_innodb_spin_wait_delay4519436 Ref: sysvar_innodb_stats_method4520585 Ref: sysvar_innodb_stats_on_metadata4522198 Ref: sysvar_innodb_stats_sample_pages4523755 Ref: sysvar_innodb_strict_mode4524886 Ref: sysvar_innodb_support_xa4525944 Ref: sysvar_innodb_sync_spin_loops4527898 Ref: sysvar_innodb_table_locks4528815 Ref: sysvar_innodb_thread_concurrency4529822 Ref: sysvar_innodb_thread_sleep_delay4531884 Ref: sysvar_innodb_use_legacy_cardinality_algorithm4532660 Ref: sysvar_innodb_use_sys_malloc4534376 Ref: sysvar_innodb_version4535216 Ref: sysvar_innodb_write_io_threads4535520 Node: using-innodb-tables4538494 Node: innodb-transactions-with-different-apis4540599 Node: converting-tables-to-innodb4542826 Node: innodb-auto-increment-handling4545906 Node: innodb-auto-increment-traditional4547190 Node: innodb-auto-increment-configurable4551254 Node: innodb-foreign-key-constraints4567974 Node: innodb-and-mysql-replication4572277 Node: innodb-data-log-reconfiguration4577563 Node: innodb-backup4581686 Node: innodb-recovery4588395 Node: forcing-innodb-recovery4589784 Node: innodb-checkpoints4594176 Node: innodb-migration4595966 Node: innodb-transaction-model4598035 Node: innodb-lock-modes4602515 Node: innodb-consistent-read4608987 Node: innodb-locking-reads4615318 Node: innodb-record-level-locks4620535 Node: innodb-next-key-locking4626109 Node: innodb-locks-set4629416 Node: innodb-implicit-commit4639460 Node: innodb-deadlock-detection4640310 Node: innodb-deadlocks4642262 Node: innodb-multi-versioning4646708 Node: innodb-table-and-index4650352 Node: innodb-index-types4651425 Node: innodb-physical-structure4653928 Node: innodb-insert-buffering4655305 Node: innodb-adaptive-hash4657321 Node: innodb-physical-record4658452 Node: innodb-disk-management4664075 Node: innodb-disk-io4664492 Node: innodb-file-space4665980 Node: innodb-file-defragmenting4669572 Node: innodb-error-handling4671378 Node: innodb-error-codes4674464 Node: operating-system-error-codes4678268 Ref: operating-system-error-codes-linux4678604 Ref: operating-system-error-codes-windows4680394 Node: innodb-tuning-troubleshooting4684389 Node: innodb-tuning4684965 Node: innodb-monitors4693941 Node: innodb-standard-monitor4699844 Node: innodb-tablespace-monitor4713709 Node: innodb-table-monitor4719529 Node: innodb-troubleshooting4728908 Node: innodb-troubleshooting-datadict4730815 Node: innodb-restrictions4735497 Node: se-db24746291 Node: se-db2-installation4747969 Node: se-db2-configuration4748975 Ref: option_ibmdb2i_assume_exclusive_use4750566 Ref: option_ibmdb2i_async_enabled4751794 Ref: option_ibmdb2i_create_index_option4752811 Ref: option_ibmdb2i_compat_opt_time_as_duration4754006 Ref: option_ibmdb2i_system_trace_level4755292 Ref: ibmdb2i_compat_opt_allow_zero_date_vals4756670 Ref: ibmdb2i_propagate_default_col_vals4758363 Ref: ibmdb2i_compat_opt_year_as_int4759460 Ref: option_ibmdb2i_lob_alloc_size4760584 Ref: option_ibmdb2i_compat_opt_blob_cols4761755 Ref: option_ibmdb2i_max_read_buffer_size4763332 Ref: option_ibmdb2i_max_write_buffer_size4764446 Ref: option_ibmdb2i_rdb_name4765537 Ref: option_ibmdb2i_transaction_unsafe4766452 Node: se-db2-creating-tables4768327 Node: se-db2-creating-tables-identifiers4769497 Node: se-db2-creating-tables-indexnames4771878 Node: se-db2-data-type-mapping4773099 Node: se-db2-metadata4773719 Node: se-db2-transactions4775343 Node: se-db2-terms4780158 Node: se-db2-notes4782584 Node: se-db2-collations4787282 Node: se-db2-errors4791641 Node: merge-storage-engine4803641 Node: merge-table-advantages4810894 Node: merge-table-problems4814674 Node: memory-storage-engine4823768 Ref: memory-compared-cluster4826503 Node: example-storage-engine4838172 Node: federated-storage-engine4839524 Node: federated-description4840778 Ref: figure-se-federated-structure4842446 Node: federated-create4843722 Node: federated-create-connection4845900 Node: federated-create-server4848507 Node: federated-usagenotes4851964 Node: federated-storage-engine-resources4857539 Node: archive-storage-engine4857959 Node: csv-storage-engine4865656 Node: se-csv-repair4867818 Node: se-csv-limitations4870849 Node: blackhole-storage-engine4871515 Node: ha-overview4878103 Ref: figure_ha-cost-vs-nines4881919 Ref: ha-availability-comparison4882087 Node: ha-ovm-template4885798 Node: ha-drbd4888289 Ref: ha-drbd-overview4890124 Node: ha-wfc4892167 Ref: ha-wfc-overview4892905 Node: ha-vm4894654 Node: ha-vm-aws-setup4898207 Node: ha-vm-aws-instance4902158 Node: ha-vm-aws-deploy4904467 Node: ha-zfs-replication4908643 Node: ha-zfs-config4913380 Node: ha-zfs-mysql4916726 Node: ha-zfs-mysql-recovery4918256 Node: ha-memcached4920060 Ref: ha-memcached-fig-overview4922052 Node: ha-memcached-install4923436 Node: ha-memcached-using4926578 Node: ha-memcached-using-deployment4936811 Node: ha-memcached-using-namespaces4938995 Node: ha-memcached-using-expiry4940429 Node: ha-memcached-using-hashtypes4942682 Ref: ha-memcached-using-hashtypes-fig-selection4944648 Ref: ha-memcached-using-hashtypes-fig-addselect4947832 Node: ha-memcached-using-dtrace4951066 Node: ha-memcached-using-memory4959324 Ref: ha-memcached-fig-slabs4961565 Node: ha-memcached-using-threads4963446 Node: ha-memcached-using-logs4965250 Node: ha-memcached-interfaces4974481 Node: ha-memcached-operations4976257 Node: ha-memcached-mysql-frontend4979580 Ref: ha-memcached-fig-basicflow4981910 Node: ha-memcached-interfaces-libmemcached4983098 Node: ha-memcached-interfaces-libmemcached-base4987153 Node: ha-memcached-interfaces-libmemcached-servers4988323 Node: ha-memcached-interfaces-libmemcached-set4991557 Node: ha-memcached-interfaces-libmemcached-get4996769 Node: ha-memcached-interfaces-libmemcached-behaviors5001387 Node: ha-memcached-interfaces-libmemcached-utilities5005559 Node: ha-memcached-interfaces-perl5007405 Node: ha-memcached-interfaces-python5014224 Node: ha-memcached-interfaces-php5020683 Node: ha-memcached-interfaces-ruby5028958 Node: ha-memcached-interfaces-java5031874 Node: ha-memcached-interfaces-protocol5035981 Ref: ha-memcached-interfaces-protocol-responses5045488 Node: ha-memcached-stats5046990 Node: ha-memcached-stats-general5052838 Node: ha-memcached-stats-slabs5059007 Node: ha-memcached-stats-items5063600 Node: ha-memcached-stats-sizes5066205 Node: ha-memcached-stats-detail5067530 Node: ha-memcached-stats-memcached-tool5069721 Node: ha-memcached-faq5075559 Ref: qandaitem-16-6-5-1-15077413 Ref: qandaitem-16-6-5-1-25077640 Ref: qandaitem-16-6-5-1-35078558 Ref: qandaitem-16-6-5-1-45078828 Ref: qandaitem-16-6-5-1-55079510 Ref: qandaitem-16-6-5-1-65080312 Ref: qandaitem-16-6-5-1-75080816 Ref: qandaitem-16-6-5-1-85081558 Ref: qandaitem-16-6-5-1-95081890 Ref: qandaitem-16-6-5-1-105082457 Ref: qandaitem-16-6-5-1-115082990 Ref: qandaitem-16-6-5-1-125083680 Ref: qandaitem-16-6-5-1-135083909 Ref: qandaitem-16-6-5-1-145084240 Node: mysql-proxy5085793 Node: mysql-proxy-platforms5088622 Node: mysql-proxy-install5089662 Node: mysql-proxy-install-binary5090760 Node: mysql-proxy-install-source5092601 Node: mysql-proxy-install-cvs5094163 Node: mysql-proxy-configuration-windows5096039 Node: mysql-proxy-configuration5098114 Ref: option_mysql-proxy_help5103499 Ref: option_mysql-proxy_help-admin5103709 Ref: option_mysql-proxy_help-all5103894 Ref: option_mysql-proxy_help-proxy5104061 Ref: option_mysql-proxy_admin-address5104246 Ref: option_mysql-proxy_admin-lua-script5104765 Ref: option_mysql-proxy_admin-password5105288 Ref: option_mysql-proxy_admin-username5105904 Ref: option_mysql-proxy_basedir5106562 Ref: option_mysql-proxy_daemon5107218 Ref: option_mysql-proxy_defaults-file5107432 Ref: option_mysql-proxy_event-threads5107732 Ref: option_mysql-proxy_keepalive5108202 Ref: option_mysql-proxy_log-backtrace-on-crash5108787 Ref: option_mysql-proxy_log-file5109132 Ref: option_mysql-proxy_log-level5109676 Ref: option_mysql-proxy_log-use-syslog5110443 Ref: option_mysql-proxy_lua-cpath5110700 Ref: option_mysql-proxy_lua-path5111184 Ref: option_mysql-proxy_max-open-files5111629 Ref: option_mysql-proxy_no-proxy5112153 Ref: option_mysql-proxy_plugin-dir5112368 Ref: option_mysql-proxy_plugins5112853 Ref: option_mysql-proxy_proxy-address5113627 Ref: option_mysql-proxy_proxy-read-only-backend-addresses5114266 Ref: option_mysql-proxy_proxy-backend-addresses5115912 Ref: option_mysql-proxy_proxy-pool-no-change-user5117434 Ref: option_mysql-proxy_proxy-skip-profiling5117861 Ref: option_mysql-proxy_proxy-fix-bug-253715118198 Ref: option_mysql-proxy_proxy-lua-script5118898 Ref: option_mysql-proxy_pid-file5119816 Ref: option_mysql-proxy_user5120264 Ref: option_mysql-proxy_version5120661 Node: mysql-proxy-scripting5122202 Node: mysql-proxy-scripting-injection5127264 Node: mysql-proxy-scripting-structures5130109 Ref: mysql-proxy-scripting-structures-proxy5130851 Ref: mysql-proxy-scripting-structures-connection5131988 Ref: mysql-proxy-scripting-structures-backends5134452 Ref: mysql-proxy-scripting-structures-queries5135853 Ref: mysql-proxy-scripting-structures-response5138551 Ref: mysql-proxy-scripting-structures-resultset5141626 Ref: mysql-proxy-scripting-structures-return-states5143734 Ref: mysql-proxy-scripting-structures-packet-states5144705 Ref: mysql-proxy-scripting-structures-backend-states5145130 Ref: mysql-proxy-scripting-structures-command-constants5145901 Ref: mysql-proxy-scripting-structures-type-constants5147698 Node: mysql-proxy-scripting-connect-server5149127 Node: mysql-proxy-scripting-read-handshake5150629 Node: mysql-proxy-scripting-read-auth5152773 Node: mysql-proxy-scripting-read-auth-result5154215 Node: mysql-proxy-scripting-read-query5155851 Node: mysql-proxy-scripting-read-query-result5159265 Node: mysql-proxy-using5163955 Node: mysql-proxy-using-admin5166414 Node: mysql-proxy-faq5178906 Ref: qandaitem-16-7-6-1-15182930 Ref: qandaitem-16-7-6-1-25183369 Ref: qandaitem-16-7-6-1-35183580 Ref: qandaitem-16-7-6-1-45183767 Ref: qandaitem-16-7-6-1-55184047 Ref: qandaitem-16-7-6-1-65184296 Ref: qandaitem-16-7-6-1-75184536 Ref: qandaitem-16-7-6-1-85184710 Ref: qandaitem-16-7-6-1-95184939 Ref: qandaitem-16-7-6-1-105185055 Ref: qandaitem-16-7-6-1-115185305 Ref: qandaitem-16-7-6-1-125185623 Ref: qandaitem-16-7-6-1-135185898 Ref: qandaitem-16-7-6-1-145186122 Ref: qandaitem-16-7-6-1-155186369 Ref: qandaitem-16-7-6-1-165186589 Ref: qandaitem-16-7-6-1-175186820 Ref: qandaitem-16-7-6-1-185187025 Ref: qandaitem-16-7-6-1-195187202 Ref: qandaitem-16-7-6-1-205187395 Ref: qandaitem-16-7-6-1-215187740 Ref: qandaitem-16-7-6-1-225188107 Ref: qandaitem-16-7-6-1-235188441 Ref: qandaitem-16-7-6-1-245188686 Ref: qandaitem-16-7-6-1-255188991 Ref: qandaitem-16-7-6-1-265189253 Ref: qandaitem-16-7-6-1-275189435 Ref: qandaitem-16-7-6-1-285189718 Ref: qandaitem-16-7-6-1-295189843 Ref: qandaitem-16-7-6-1-305190153 Ref: qandaitem-16-7-6-1-315190378 Node: replication5190669 Node: replication-configuration5194965 Node: replication-howto5198764 Node: replication-howto-masterbaseconfig5203115 Node: replication-howto-slavebaseconfig5205164 Node: replication-howto-repuser5206699 Node: replication-howto-masterstatus5208425 Node: replication-howto-mysqldump5212231 Node: replication-howto-rawdata5214503 Node: replication-howto-newservers5218622 Node: replication-howto-existingdata5220532 Node: replication-howto-additionalslaves5225144 Node: replication-howto-slaveinit5229102 Node: replication-formats5230320 Node: replication-sbr-rbr5234697 Ref: replication-sbr-rbr-sbr-advantages5235673 Ref: replication-sbr-rbr-sbr-disadvantages5236142 Ref: replication-sbr-rbr-rbr-advantages5239986 Ref: replication-sbr-rbr-rbr-disadvantages5241947 Node: replication-rbr-usage5244960 Node: replication-rbr-safe-unsafe5252029 Ref: replication-rbr-safe-unsafe-not5254331 Node: replication-options5257464 Ref: option_mysqld_server-id5258526 Node: replication-options-table5259838 Ref: replication-optvar-summary-table5260272 Ref: binlog-optvar-summary-table5269871 Node: replication-options-master5272906 Ref: replication-sysvars-masters5273896 Ref: sysvar_auto_increment_increment5274024 Ref: sysvar_auto_increment_offset5282172 Node: replication-options-slave5283175 Ref: replication-optvars-slaves5288071 Ref: option_mysqld_abort-slave-event-count5288500 Ref: option_mysqld_disconnect-slave-event-count5289746 Ref: option_mysqld_log-slave-updates5290291 Ref: option_mysqld_log-slow-slave-statements5292612 Ref: option_mysqld_master-connect-retry5295062 Ref: option_mysqld_slave-max-allowed-packet5296122 Ref: option_mysqld_master-host5297612 Ref: option_mysqld_master-info-file5298288 Ref: option_mysqld_master-password5298987 Ref: option_mysqld_master-port5299712 Ref: option_mysqld_master-retry-count5300432 Ref: option_mysqld_master-ssl5301805 Ref: option_mysqld_master-user5302480 Ref: option_mysqld_max-relay-log-size5303319 Ref: option_mysqld_read-only5304152 Ref: option_mysqld_relay-log5305003 Ref: option_mysqld_relay-log-index5307184 Ref: option_mysqld_relay-log-info-file5308772 Ref: option_mysqld_relay-log-purge5309493 Ref: option_mysqld_relay-log-space-limit5310307 Ref: option_mysqld_replicate-do-db5312539 Ref: option_mysqld_replicate-ignore-db5317659 Ref: option_mysqld_replicate-do-table5320620 Ref: option_mysqld_replicate-ignore-table5321602 Ref: option_mysqld_replicate-rewrite-db5322666 Ref: option_mysqld_replicate-same-server-id5324951 Ref: option_mysqld_replicate-wild-do-table5326089 Ref: option_mysqld_replicate-wild-ignore-table5328467 Ref: option_mysqld_report-host5329624 Ref: option_mysqld_report-password5330739 Ref: option_mysqld_report-port5331810 Ref: option_mysqld_report-user5332779 Ref: option_mysqld_show-slave-auth-info5333813 Ref: option_mysqld_skip-slave-start5334438 Ref: optvar_slave_compressed_protocol5335001 Ref: option_mysqld_slave-load-tmpdir5335794 Ref: option_mysqld_slave-net-timeout5337616 Ref: option_mysqld_slave-skip-errors5338806 Ref: replication-sysvars-slaves5342296 Ref: sysvar_init_slave5342627 Ref: sysvar_relay_log5343639 Ref: sysvar_relay_log_index5344216 Ref: sysvar_relay_log_info_file5344975 Ref: sysvar_rpl_recovery_rank5345735 Ref: sysvar_slave_compressed_protocol5345822 Ref: sysvar_slave_exec_mode5346549 Ref: sysvar_slave_max_allowed_packet5348104 Ref: sysvar_slave_load_tmpdir5349537 Ref: sysvar_slave_net_timeout5350301 Ref: sysvar_slave_skip_errors5351195 Ref: sysvar_slave_transaction_retries5352456 Ref: sysvar_slave_type_conversions5354043 Ref: sysvar_sql_slave_skip_counter5355557 Node: replication-options-binary-log5356382 Ref: replication-optvars-binlog5357024 Ref: option_mysqld_binlog-row-event-max-size5357241 Ref: option_mysqld_log-bin5358539 Ref: option_mysqld_log-bin-index5359756 Ref: option_mysqld_log-bin-trust-function-creators5360359 Ref: option_mysqld_log-bin-use-v1-row-events5361466 Ref: option_mysqld_binlog-do-db5364574 Ref: option_mysqld_binlog-ignore-db5370283 Ref: option_mysqld_max-binlog-dump-events5373859 Ref: option_mysqld_sporadic-binlog-dump-fail5374382 Ref: replication-sysvars-binlog5374908 Ref: sysvar_binlog_cache_size5375229 Ref: sysvar_binlog_direct_non_transactional_updates5376911 Ref: sysvar_binlog_format5379552 Ref: sysvar_log_bin5384543 Ref: sysvar_log_bin_use_v1_row_events5385099 Ref: sysvar_log_slave_updates5387294 Ref: sysvar_max_binlog_cache_size5388117 Ref: sysvar_max_binlog_size5390555 Ref: sysvar_sync_binlog5391870 Node: replication-administration5393683 Node: replication-administration-status5394293 Node: replication-administration-pausing5400861 Node: replication-implementation5402951 Node: replication-implementation-details5405608 Node: slave-logs5411275 Node: slave-logs-relaylog5412515 Node: slave-logs-status5415914 Node: replication-rules5422013 Node: replication-rules-db-options5425155 Node: replication-rules-table-options5428841 Node: replication-rules-examples5432137 Node: replication-solutions5435426 Node: replication-solutions-backups5437659 Node: replication-solutions-backups-mysqldump5439693 Node: replication-solutions-backups-rawdata5442400 Node: replication-solutions-backups-read-only5445255 Node: replication-solutions-diffengines5449657 Node: replication-solutions-scaleout5453772 Ref: figure_replication-scaleout5454965 Node: replication-solutions-partitioning5456950 Ref: figure_replication-multi-db5457566 Node: replication-solutions-performance5459795 Ref: figure_replication-performance5460940 Node: replication-solutions-switch5463196 Ref: figure_replication-redundancy-before5464805 Ref: figure_replication-redundancy-after5467972 Node: replication-solutions-ssl5469314 Node: replication-notes5473439 Node: replication-features5473956 Node: replication-features-auto-increment5478865 Node: replication-features-blackhole5483130 Node: replication-features-charset5484220 Node: replication-features-create-if-not-exists5486467 Node: replication-features-create-select5488096 Node: replication-features-current-user5490455 Node: replication-features-create-alter-drop-server5492297 Node: replication-features-drop-if-exists5492948 Node: replication-features-differing-tables5493896 Node: replication-features-more-columns5494983 Node: replication-features-different-data-types5499837 Ref: replication-features-attribute-promotion5506861 Node: replication-features-directory5514110 Node: replication-features-invoked5515105 Node: replication-features-floatvalues5520421 Node: replication-features-flush5521297 Node: replication-features-functions5522739 Node: replication-features-limit5530445 Node: replication-features-load-data5531554 Node: replication-features-logging5532547 Node: replication-features-repair-table5532991 Node: replication-features-shutdowns5533954 Node: replication-features-max-allowed-packet5536441 Node: replication-features-memory5537923 Node: replication-features-temptables5541350 Node: replication-features-mysqldb5544042 Node: replication-features-optimizer5545164 Node: replication-features-reserved-words5545926 Node: replication-features-set-password5548033 Node: replication-features-slaveerrors5548547 Node: replication-features-sql-mode5550894 Node: replication-features-timeout5551970 Node: replication-features-timestamp5552845 Node: replication-features-timezone5553778 Node: replication-features-transactions5554821 Node: replication-features-triggers5560746 Node: replication-features-truncate5562606 Node: replication-features-variables5563810 Node: replication-features-views5568053 Node: replication-compatibility5568900 Node: replication-upgrade5572966 Node: replication-problems5576939 Node: replication-bugs5582109 Node: mysql-cluster5584784 Node: mysql-cluster-overview5595367 Node: mysql-cluster-basics5600375 Node: mysql-cluster-nodes-groups5611483 Ref: mysql-cluster-nodes-groups-nodegroup5612736 Ref: mysql-cluster-nodes-groups-partition5613974 Ref: mysql-cluster-nodes-groups-user-partitioning5614361 Ref: mysql-cluster-nodes-groups-replica5615836 Node: mysql-cluster-overview-requirements5618480 Ref: mysql-cluster-network-latency-issues5621601 Node: mysql-cluster-development5624978 Node: mysql-cluster-development-5-1-ndb-7-25630115 Node: mysql-cluster-development-5-1-ndb-7-15634849 Node: mysql-cluster-development-5-1-ndb-7-05661294 Node: mysql-cluster-development-5-1-ndb-6-35693203 Node: mysql-cluster-development-5-1-ndb-6-25715562 Node: mysql-cluster-development-5-1-ndb-6-15725073 Node: mysql-cluster-development-5-15727029 Ref: mysql-cluster-development-5-1-distribution-awareness5731170 Node: mysql-cluster-compared5733579 Node: mysql-cluster-ndb-innodb-engines5737164 Node: mysql-cluster-ndb-innodb-workloads5746121 Node: mysql-cluster-ndb-innodb-usage5749588 Node: mysql-cluster-limitations5752169 Node: mysql-cluster-limitations-syntax5754662 Node: mysql-cluster-limitations-limits5761831 Node: mysql-cluster-limitations-transactions5766270 Node: mysql-cluster-limitations-error-handling5773939 Node: mysql-cluster-limitations-database-objects5774996 Node: mysql-cluster-limitations-unsupported5776771 Node: mysql-cluster-limitations-performance5778846 Node: mysql-cluster-limitations-exclusive-to-cluster5780053 Node: mysql-cluster-limitations-disk-data5782316 Node: mysql-cluster-limitations-multiple-nodes5783972 Node: mysql-cluster-limitations-resolved5786936 Node: mysql-cluster-installation5803967 Node: mysql-cluster-install-linux5810858 Node: mysql-cluster-install-linux-binary5813111 Node: mysql-cluster-install-linux-rpm5821077 Node: mysql-cluster-install-linux-source5827817 Node: mysql-cluster-install-windows5833239 Node: mysql-cluster-install-windows-binary5834562 Node: mysql-cluster-install-windows-source5848012 Node: mysql-cluster-install-windows-initial-start5850905 Node: mysql-cluster-install-windows-service5859834 Node: mysql-cluster-install-configuration5867297 Node: mysql-cluster-install-first-start5872996 Node: mysql-cluster-install-example-data5875926 Node: mysql-cluster-install-shutdown-restart5885635 Node: mysql-cluster-upgrade-downgrade5888601 Node: mysql-cluster-upgrade-downgrade-compatibility-7.x5891667 Node: mysql-cluster-upgrade-downgrade-compatibility-6.x5901681 Ref: mysql-cluster-upgrade-downgrade-compatibility-online-add-drop-column-6-x5903984 Node: mysql-cluster-upgrade-downgrade-compatibility-5.15906427 Ref: mysql-cluster-upgrade-downgrade-compatibility-online-add-drop-column5910994 Node: mysql-cluster-configuration5913071 Node: mysql-cluster-quick5915060 Node: mysql-cluster-config-file5920609 Node: mysql-cluster-config-example5926394 Ref: mysql-cluster-config-ini-sections5932642 Node: mysql-cluster-config-starting5934996 Node: mysql-cluster-connection-strings5949016 Node: mysql-cluster-computer-definition5954061 Ref: ndbparam-computer-id5954527 Ref: id-computer-table5954534 Ref: ndbparam-computer-hostname5955267 Ref: hostname-computer-table5955280 Node: mysql-cluster-mgm-definition5955697 Ref: ndbparam-mgmd-id5956371 Ref: id-mgmd-table5956378 Ref: ndbparam-mgmd-nodeid5957880 Ref: nodeid-mgmd-table5957891 Ref: ndbparam-mgmd-executeoncomputer5959413 Ref: executeoncomputer-mgmd-table5959435 Ref: ndbparam-mgmd-portnumber5959884 Ref: portnumber-mgmd-table5959899 Ref: ndbparam-mgmd-hostname5960347 Ref: hostname-mgmd-table5960360 Ref: ndbparam-mgmd-logdestination5960967 Ref: logdestination-mgmd-table5960986 Ref: ndbparam-mgmd-arbitrationrank5963435 Ref: arbitrationrank-mgmd-table5963455 Ref: ndbparam-mgmd-arbitrationdelay5965008 Ref: arbitrationdelay-mgmd-table5965029 Ref: ndbparam-mgmd-datadir5965583 Ref: datadir-mgmd-table5965595 Ref: ndbparam-mgmd-heartbeatthreadpriority5966413 Ref: ndbparam-mgmd-extrasendbuffermemory5967060 Ref: extrasendbuffermemory-mgmd-table5967086 Ref: ndbparam-mgmd-totalsendbuffermemory5967724 Ref: totalsendbuffermemory-mgmd-table5967750 Node: mysql-cluster-ndbd-definition5969124 Ref: mysql-cluster-identifying-data-nodes5971833 Ref: ndbparam-ndbd-id5971994 Ref: id-ndbd-table5972001 Ref: ndbparam-ndbd-nodeid5972947 Ref: nodeid-ndbd-table5972958 Ref: ndbparam-ndbd-executeoncomputer5973908 Ref: executeoncomputer-ndbd-table5973930 Ref: ndbparam-ndbd-hostname5974348 Ref: hostname-ndbd-table5974361 Ref: ndbparam-ndbd-serverport5974956 Ref: serverport-ndbd-table5974971 Ref: ndbparam-ndbd-tcpbind_inaddr_any5976421 Ref: ndbparam-ndbd-nodegroup5976693 Ref: nodegroup-ndbd-table5976707 Ref: ndbparam-ndbd-noofreplicas5978164 Ref: noofreplicas-ndbd-table5978181 Ref: ndbparam-ndbd-datadir5980898 Ref: datadir-ndbd-table5980910 Ref: ndbparam-ndbd-filesystempath5981458 Ref: filesystempath-ndbd-table5981477 Ref: ndbparam-ndbd-backupdatadir5982506 Ref: backupdatadir-ndbd-table5982524 Ref: mysql-cluster-data-memory-index-memory-string-memory5983384 Ref: ndbparam-ndbd-datamemory5983765 Ref: datamemory-ndbd-table5983780 Ref: ndbparam-ndbd-indexmemory5990379 Ref: indexmemory-ndbd-table5990395 Ref: ndbparam-ndbd-stringmemory5991383 Ref: stringmemory-ndbd-table5991400 Ref: ndbparam-ndbd-minfreepct5995888 Ref: minfreepct-ndbd-table5996295 Ref: mysql-cluster-transaction-parameters5996910 Ref: ndbparam-ndbd-maxnoofconcurrenttransactions5997760 Ref: maxnoofconcurrenttransactions-ndbd-table5997794 Ref: ndbparam-ndbd-maxnoofconcurrentoperations6000710 Ref: maxnoofconcurrentoperations-ndbd-table6000742 Ref: ndbparam-ndbd-maxnooflocaloperations6004351 Ref: maxnooflocaloperations-ndbd-table6004378 Ref: ndbparam-ndbd-maxdmloperationspertransaction6005086 Ref: maxdmloperationspertransaction-ndbd-table6005121 Ref: mysql-cluster-transaction-temporary-storage6006024 Ref: ndbparam-ndbd-maxnoofconcurrentindexoperations6006644 Ref: maxnoofconcurrentindexoperations-ndbd-table6006681 Ref: ndbparam-ndbd-maxnooffiredtriggers6007874 Ref: maxnooffiredtriggers-ndbd-table6007899 Ref: ndbparam-ndbd-transactionbuffermemory6009099 Ref: transactionbuffermemory-ndbd-table6009127 Ref: mysql-cluster-scans-and-buffering6010310 Ref: ndbparam-ndbd-maxnoofconcurrentscans6010803 Ref: maxnoofconcurrentscans-ndbd-table6010830 Ref: ndbparam-ndbd-maxnooflocalscans6012372 Ref: maxnooflocalscans-ndbd-table6012394 Ref: ndbparam-ndbd-batchsizeperlocalscan6013173 Ref: batchsizeperlocalscan-ndbd-table6013199 Ref: ndbparam-ndbd-longmessagebuffer6013814 Ref: longmessagebuffer-ndbd-table6013836 Ref: ndbparam-ndbd-maxparallelscansperfragment6015134 Ref: maxparallelscansperfragment-ndbd-table6015166 Ref: mysql-cluster-memory-allocation6016218 Ref: ndbparam-ndbd-maxallocate6016241 Ref: maxallocate-ndbd-table6016256 Ref: mysql-cluster-hash-map-size6017311 Ref: ndbparam-ndbd-defaulthashmapsize6017330 Ref: defaulthashmapsize-ndbd-table6017352 Ref: mysql-cluster-defaulthashmapsize-table6018081 Ref: mysql-cluster-logging-and-checkpointing6020051 Ref: ndbparam-ndbd-nooffragmentlogfiles6020155 Ref: nooffragmentlogfiles-ndbd-table6020180 Ref: ndbparam-ndbd-fragmentlogfilesize6022870 Ref: fragmentlogfilesize-ndbd-table6022894 Ref: ndbparam-ndbd-initfragmentlogfiles6023976 Ref: initfragmentlogfiles-ndbd-table6024001 Ref: ndbparam-ndbd-maxnoofopenfiles6025252 Ref: maxnoofopenfiles-ndbd-table6025273 Ref: ndbparam-ndbd-initialnoofopenfiles6026001 Ref: initialnoofopenfiles-ndbd-table6026026 Ref: ndbparam-ndbd-maxnoofsavedmessages6026481 Ref: maxnoofsavedmessages-ndbd-table6026506 Ref: ndbparam-ndbd-maxlcpstartdelay6027052 Ref: maxlcpstartdelay-ndbd-table6027073 Ref: mysql-cluster-metadata-objects6028909 Ref: ndbparam-ndbd-maxnoofattributes6029265 Ref: maxnoofattributes-ndbd-table6029287 Ref: ndbparam-ndbd-maxnooftables6031839 Ref: maxnooftables-ndbd-table6031857 Ref: ndbparam-ndbd-maxnooforderedindexes6033485 Ref: maxnooforderedindexes-ndbd-table6033511 Ref: ndbparam-ndbd-maxnoofuniquehashindexes6034517 Ref: maxnoofuniquehashindexes-ndbd-table6034546 Ref: ndbparam-ndbd-maxnooftriggers6035438 Ref: maxnooftriggers-ndbd-table6035458 Ref: ndbparam-ndbd-maxnoofindexes6036297 Ref: ndbparam-ndbd-maxnoofsubscriptions6036652 Ref: maxnoofsubscriptions-ndbd-table6036677 Ref: ndbparam-ndbd-maxnoofsubscribers6037619 Ref: maxnoofsubscribers-ndbd-table6037642 Ref: ndbparam-ndbd-maxnoofconcurrentsuboperations6039194 Ref: maxnoofconcurrentsuboperations-ndbd-table6039229 Ref: mysql-cluster-boolean-parameters6040095 Ref: ndbparam-ndbd-lockpagesinmainmemory6040342 Ref: lockpagesinmainmemory-ndbd-table6040368 Ref: ndbparam-ndbd-stoponerror6043689 Ref: stoponerror-ndbd-table6043705 Ref: ndbparam-ndbd-crashoncorruptedtuple6044221 Ref: crashoncorruptedtuple-ndbd-table6044247 Ref: ndbparam-ndbd-diskless6044938 Ref: diskless-ndbd-table6044951 Ref: ndbparam-ndbd-odirect6046067 Ref: odirect-ndbd-table6046079 Ref: ndbparam-ndbd-restartonerrorinsert6046990 Ref: restartonerrorinsert-ndbd-table6047015 Ref: ndbparam-ndbd-compressedbackup6047566 Ref: compressedbackup-ndbd-table6047587 Ref: ndbparam-ndbd-compressedlcp6048588 Ref: compressedlcp-ndbd-table6048606 Ref: mysql-cluster-timeouts-intervals-disk-paging6049620 Ref: ndbparam-ndbd-timebetweenwatchdogcheck6049916 Ref: timebetweenwatchdogcheck-ndbd-table6049945 Ref: ndbparam-ndbd-timebetweenwatchdogcheckinitial6050867 Ref: timebetweenwatchdogcheckinitial-ndbd-table6050903 Ref: ndbparam-ndbd-startpartialtimeout6051624 Ref: startpartialtimeout-ndbd-table6051648 Ref: ndbparam-ndbd-startpartitionedtimeout6052475 Ref: startpartitionedtimeout-ndbd-table6052503 Ref: ndbparam-ndbd-startfailuretimeout6053287 Ref: startfailuretimeout-ndbd-table6053311 Ref: ndbparam-ndbd-startnonodegrouptimeout6054260 Ref: startnonodegrouptimeout-ndbd-table6054288 Ref: ndbparam-ndbd-heartbeatintervaldbdb6055529 Ref: heartbeatintervaldbdb-ndbd-table6055555 Ref: ndbparam-ndbd-heartbeatintervaldbapi6056949 Ref: heartbeatintervaldbapi-ndbd-table6056976 Ref: ndbparam-ndbd-heartbeatorder6058151 Ref: heartbeatorder-ndbd-table6058170 Ref: ndbparam-ndbd-connectcheckintervaldelay6063424 Ref: connectcheckintervaldelay-ndbd-table6063454 Ref: ndbparam-ndbd-timebetweenlocalcheckpoints6064083 Ref: timebetweenlocalcheckpoints-ndbd-table6064115 Ref: ndbparam-ndbd-timebetweenglobalcheckpoints6065653 Ref: timebetweenglobalcheckpoints-ndbd-table6065686 Ref: ndbparam-ndbd-timebetweenepochs6067227 Ref: timebetweenepochs-ndbd-table6067249 Ref: ndbparam-ndbd-timebetweenepochstimeout6067976 Ref: timebetweenepochstimeout-ndbd-table6068005 Ref: ndbparam-ndbd-maxbufferedepochs6069761 Ref: maxbufferedepochs-ndbd-table6069783 Ref: ndbparam-ndbd-maxbufferedepochbytes6071049 Ref: maxbufferedepochbytes-ndbd-table6071075 Ref: ndbparam-ndbd-timebetweeninactivetransactionabortcheck6072411 Ref: timebetweeninactivetransactionabortcheck-ndbd-table6072456 Ref: ndbparam-ndbd-transactioninactivetimeout6073129 Ref: transactioninactivetimeout-ndbd-table6073160 Ref: ndbparam-ndbd-transactiondeadlockdetectiontimeout6073907 Ref: transactiondeadlockdetectiontimeout-ndbd-table6073947 Ref: ndbparam-ndbd-disksyncsize6075597 Ref: disksyncsize-ndbd-table6075614 Ref: ndbparam-ndbd-diskcheckpointspeed6076464 Ref: diskcheckpointspeed-ndbd-table6076488 Ref: ndbparam-ndbd-diskcheckpointspeedinrestart6077300 Ref: diskcheckpointspeedinrestart-ndbd-table6077333 Ref: ndbparam-ndbd-noofdiskpagestodiskafterrestarttup6077905 Ref: noofdiskpagestodiskafterrestarttup-ndbd-table6077944 Ref: ndbparam-ndbd-noofdiskpagestodiskafterrestartacc6079812 Ref: noofdiskpagestodiskafterrestartacc-ndbd-table6079851 Ref: ndbparam-ndbd-noofdiskpagestodiskduringrestarttup6080696 Ref: noofdiskpagestodiskduringrestarttup-ndbd-table6080749 Ref: ndbparam-ndbd-noofdiskpagestodiskduringrestartacc6081918 Ref: noofdiskpagestodiskduringrestartacc-ndbd-table6081971 Ref: ndbparam-ndbd-arbitrationtimeout6082944 Ref: arbitrationtimeout-ndbd-table6082967 Ref: ndbparam-ndbd-arbitration6083705 Ref: arbitration-ndbd-table6083721 Ref: mysql-cluster-buffering-and-logging6085974 Ref: ndbparam-ndbd-undoindexbuffer6086482 Ref: undoindexbuffer-ndbd-table6086502 Ref: ndbparam-ndbd-undodatabuffer6088540 Ref: undodatabuffer-ndbd-table6088559 Ref: ndbparam-ndbd-redobuffer6090139 Ref: redobuffer-ndbd-table6090154 Ref: mysql-cluster-controlling-log-messages6091458 Ref: ndbparam-ndbd-loglevelstartup6092243 Ref: loglevelstartup-ndbd-table6092263 Ref: ndbparam-ndbd-loglevelshutdown6092696 Ref: loglevelshutdown-ndbd-table6092717 Ref: ndbparam-ndbd-loglevelstatistic6093160 Ref: loglevelstatistic-ndbd-table6093182 Ref: ndbparam-ndbd-loglevelcheckpoint6093717 Ref: loglevelcheckpoint-ndbd-table6093740 Ref: ndbparam-ndbd-loglevelnoderestart6094178 Ref: loglevelnoderestart-ndbd-table6094202 Ref: ndbparam-ndbd-loglevelconnection6094624 Ref: loglevelconnection-ndbd-table6094647 Ref: ndbparam-ndbd-loglevelerror6095090 Ref: loglevelerror-ndbd-table6095108 Ref: ndbparam-ndbd-loglevelcongestion6095648 Ref: loglevelcongestion-ndbd-table6095671 Ref: ndbparam-ndbd-loglevelinfo6096178 Ref: loglevelinfo-ndbd-table6096195 Ref: ndbparam-ndbd-memreportfrequency6096650 Ref: memreportfrequency-ndbd-table6096673 Ref: ndbparam-ndbd-startupstatusreportfrequency6098426 Ref: startupstatusreportfrequency-ndbd-table6098459 Ref: ndbparam-ndbd-dicttrace6100292 Ref: mysql-cluster-backup-parameters6100713 Ref: ndbparam-ndbd-backupdatabuffersize6100853 Ref: backupdatabuffersize-ndbd-table6100878 Ref: ndbparam-ndbd-backuplogbuffersize6102036 Ref: backuplogbuffersize-ndbd-table6102060 Ref: ndbparam-ndbd-backupmemory6103824 Ref: backupmemory-ndbd-table6103841 Ref: ndbparam-ndbd-backupreportfrequency6104678 Ref: backupreportfrequency-ndbd-table6104704 Ref: ndbparam-ndbd-backupwritesize6105529 Ref: backupwritesize-ndbd-table6105549 Ref: ndbparam-ndbd-backupmaxwritesize6106213 Ref: backupmaxwritesize-ndbd-table6106236 Ref: mysql-cluster-realtime-performance-parameters6107263 Ref: ndbparam-ndbd-lockexecutethreadtocpu6107610 Ref: lockexecutethreadtocpu-ndbd-table6107637 Ref: ndbparam-ndbd-lockmaintthreadstocpu6109509 Ref: lockmaintthreadstocpu-ndbd-table6109535 Ref: ndbparam-ndbd-realtimescheduler6110364 Ref: realtimescheduler-ndbd-table6110386 Ref: ndbparam-ndbd-schedulerexecutiontimer6111087 Ref: schedulerexecutiontimer-ndbd-table6111115 Ref: ndbparam-ndbd-schedulerspintimer6111937 Ref: schedulerspintimer-ndbd-table6111960 Ref: ndbparam-ndbd-buildindexthreads6112436 Ref: buildindexthreads-ndbd-table6112458 Ref: ndbparam-ndbd-twopassinitialnoderestartcopy6114125 Ref: twopassinitialnoderestartcopy-ndbd-table6114159 Ref: ndbparam-ndbd-numa6114835 Ref: numa-ndbd-table6114844 Ref: mysql-cluster-ndbd-definition-ndbmtd-parameters6115853 Ref: ndbparam-ndbmtd-maxnoofexecutionthreads6116604 Ref: maxnoofexecutionthreads-ndbmtd-table6116632 Ref: ndbparam-ndbmtd-threadconfig6119659 Ref: threadconfig-ndbmtd-table6119676 Ref: mysql-cluster-ndbd-definition-disk-data-parameters6124546 Ref: ndbparam-ndbd-diskpagebuffermemory6124665 Ref: diskpagebuffermemory-ndbd-table6124690 Ref: ndbparam-ndbd-sharedglobalmemory6125825 Ref: sharedglobalmemory-ndbd-table6125848 Ref: ndbparam-ndbd-diskiothreadpool6127216 Ref: diskiothreadpool-ndbd-table6127237 Ref: mysql-cluster-ndbd-disk-data-filesystem-parameters6129587 Ref: ndbparam-ndbd-filesystempathdd6129873 Ref: filesystempathdd-ndbd-table6129894 Ref: ndbparam-ndbd-filesystempathdatafiles6131749 Ref: filesystempathdatafiles-ndbd-table6131777 Ref: ndbparam-ndbd-filesystempathundofiles6133370 Ref: filesystempathundofiles-ndbd-table6133398 Ref: mysql-cluster-ndbd-disk-data-object-creation-parameters6135082 Ref: ndbparam-ndbd-initiallogfilegroup6135335 Ref: initiallogfilegroup-ndbd-table6135359 Ref: ndbparam-ndbd-initialtablespace6138549 Ref: initialtablespace-ndbd-table6138571 Ref: mysql-cluster-ndbd-definition-gcp-stop-errors6141386 Ref: ndbparam-ndbd-extrasendbuffermemory6144882 Ref: ndbparam-ndbd-totalsendbuffermemory6145231 Ref: ndbparam-ndbd-reservedsendbuffermemory6145781 Ref: mysql-cluster-redo-over-commit-handling6146897 Ref: ndbparam-ndbd-redoovercommitcounter6147696 Ref: redoovercommitcounter-ndbd-table6147722 Ref: ndbparam-ndbd-redoovercommitlimit6148641 Ref: redoovercommitlimit-ndbd-table6148665 Ref: ndbparam-ndbd-startfailretrydelay6150462 Ref: startfailretrydelay-ndbd-table6150486 Ref: ndbparam-ndbd-maxstartfailretries6151387 Ref: maxstartfailretries-ndbd-table6151411 Node: mysql-cluster-api-definition6152297 Ref: ndbparam-api-id6153524 Ref: id-api-table6153531 Ref: ndbparam-api-nodeid6154993 Ref: nodeid-api-table6155004 Ref: ndbparam-api-executeoncomputer6156474 Ref: executeoncomputer-api-table6156496 Ref: ndbparam-api-hostname6156947 Ref: hostname-api-table6156960 Ref: ndbparam-api-arbitrationrank6157982 Ref: arbitrationrank-api-table6158002 Ref: ndbparam-api-arbitrationdelay6159287 Ref: arbitrationdelay-api-table6159308 Ref: ndbparam-api-batchbytesize6159879 Ref: batchbytesize-api-table6159897 Ref: ndbparam-api-batchsize6160849 Ref: batchsize-api-table6160863 Ref: ndbparam-api-extrasendbuffermemory6161357 Ref: extrasendbuffermemory-api-table6161383 Ref: ndbparam-api-heartbeatthreadpriority6162014 Ref: ndbparam-api-maxscanbatchsize6162645 Ref: maxscanbatchsize-api-table6162666 Ref: ndbparam-api-totalsendbuffermemory6163358 Ref: totalsendbuffermemory-api-table6163384 Ref: ndbparam-api-autoreconnect6164272 Ref: autoreconnect-api-table6164290 Ref: ndbparam-api-defaultoperationredoproblemaction6165567 Ref: defaultoperationredoproblemaction-api-table6165605 Ref: ndbparam-api-defaulthashmapsize6166943 Ref: defaulthashmapsize-api-table6166966 Node: mysql-cluster-tcp-definition6171199 Ref: ndbparam-tcp-nodeid16172736 Ref: nodeid1-tcp-table6172747 Ref: ndbparam-tcp-nodeid26173045 Ref: nodeid2-tcp-table6173061 Ref: ndbparam-tcp-hostname16173655 Ref: hostname1-tcp-table6173668 Ref: ndbparam-tcp-hostname26174028 Ref: hostname2-tcp-table6174046 Ref: ndbparam-tcp-overloadlimit6174654 Ref: overloadlimit-tcp-table6174672 Ref: ndbparam-tcp-sendbuffermemory6175559 Ref: sendbuffermemory-tcp-table6175580 Ref: ndbparam-tcp-sendsignalid6177252 Ref: sendsignalid-tcp-table6177269 Ref: ndbparam-tcp-checksum6177878 Ref: checksum-tcp-table6177891 Ref: ndbparam-tcp-portnumber6178596 Ref: ndbparam-tcp-receivebuffermemory6178871 Ref: receivebuffermemory-tcp-table6178895 Ref: ndbparam-tcp-tcp_rcv_buf_size6179612 Ref: tcp_rcv_buf_size-tcp-table6179633 Ref: ndbparam-tcp-tcp_snd_buf_size6180168 Ref: tcp_snd_buf_size-tcp-table6180189 Node: mysql-cluster-tcp-definition-direct6180716 Node: mysql-cluster-shm-definition6182607 Ref: ndbparam-shm-nodeid16183753 Ref: nodeid1-shm-table6183765 Ref: ndbparam-shm-nodeid26184073 Ref: nodeid2-shm-table6184089 Ref: ndbparam-shm-hostname16184551 Ref: hostname1-shm-table6184565 Ref: ndbparam-shm-hostname26184935 Ref: hostname2-shm-table6184953 Ref: ndbparam-shm-shmkey6185571 Ref: shmkey-shm-table6185582 Ref: ndbparam-shm-shmsize6186101 Ref: shmsize-shm-table6186113 Ref: ndbparam-shm-sendsignalid6186654 Ref: sendsignalid-shm-table6186671 Ref: ndbparam-shm-checksum6187325 Ref: checksum-shm-table6187338 Ref: ndbparam-shm-signum6188031 Ref: signum-shm-table6188042 Node: mysql-cluster-sci-definition6189015 Ref: ndbparam-sci-nodeid16190414 Ref: nodeid1-sci-table6190426 Ref: ndbparam-sci-nodeid26190724 Ref: nodeid2-sci-table6190740 Ref: ndbparam-sci-host1sciid06191192 Ref: host1sciid0-sci-table6191208 Ref: ndbparam-sci-host1sciid16191614 Ref: host1sciid1-sci-table6191630 Ref: ndbparam-sci-host2sciid06192179 Ref: host2sciid0-sci-table6192195 Ref: ndbparam-sci-host2sciid16192602 Ref: host2sciid1-sci-table6192618 Ref: ndbparam-sci-hostname16193062 Ref: hostname1-sci-table6193075 Ref: ndbparam-sci-hostname26193435 Ref: hostname2-sci-table6193453 Ref: ndbparam-sci-sharedbuffersize6194061 Ref: sharedbuffersize-sci-table6194082 Ref: ndbparam-sci-sendlimit6194843 Ref: sendlimit-sci-table6194857 Ref: ndbparam-sci-sendsignalid6195497 Ref: sendsignalid-sci-table6195514 Ref: ndbparam-sci-checksum6196104 Ref: checksum-sci-table6196117 Ref: ndbparam-sci-overloadlimit6196795 Ref: overloadlimit-sci-table6196813 Node: mysql-cluster-config-lcp-params6197308 Node: mysql-cluster-config-send-buffers6203932 Node: mysql-cluster-params-overview6207846 Node: mysql-cluster-params-ndbd6211269 Ref: ndbparam-summary-table-ndbd6212789 Ref: ndbparam-summary-table-ndbmtd6245315 Node: mysql-cluster-params-mgmd6246858 Ref: ndbparam-summary-table-mgmd6248121 Node: mysql-cluster-params-api6253129 Ref: ndbparam-summary-table-api6254654 Node: mysql-cluster-params-other6259941 Ref: ndbparam-summary-table-computer6261264 Ref: ndbparam-summary-table-tcp6262371 Ref: ndbparam-summary-table-shm6266663 Ref: ndbparam-summary-table-sci6270265 Node: mysql-cluster-options-variables6274696 Node: mysql-cluster-option-tables6275713 Ref: mysql-cluster-mysqld-optvars-table6276350 Node: mysql-cluster-program-options-mysqld6317562 Ref: option_mysqld_ndb-batch-size6318750 Ref: option_mysqld_ndb-cluster-connection-pool6319533 Ref: option_mysqld_ndb-blob-read-batch-bytes6322670 Ref: option_mysqld_ndb-blob-write-batch-bytes6324574 Ref: option_mysqld_ndb-connectstring6326498 Ref: option_mysqld_ndb-deferred-constraints6327098 Ref: option_mysqld_ndb-distribution6328360 Ref: option_mysqld_ndb-mgmd-host6329357 Ref: option_mysqld_ndbcluster6330062 Ref: option_mysqld_ndb-log-apply-status6330852 Ref: option_mysqld_ndb-log-orig6332716 Ref: option_mysqld_ndb-log-transaction-id6333621 Ref: option_mysqld_ndb-nodeid6335021 Ref: option_mysqld_ndb-log-empty-epochs6337421 Ref: option_mysqld_server-id-bits6339188 Ref: option_mysqld_skip-ndbcluster6341363 Ref: option_mysqld_ndb-transid-mysql-connection-map6341957 Ref: option_mysqld_ndb-wait-connected6343250 Ref: option_mysqld_ndb-wait-setup6345347 Ref: option_mysqld_ndb_optimization_delay6347411 Node: mysql-cluster-system-variables6348183 Ref: sysvar_have_ndbcluster6348794 Ref: sysvar_multi_range_count6349424 Ref: sysvar_ndb_autoincrement_prefetch_sz6350766 Ref: sysvar_ndb_cache_check_time6356939 Ref: sysvar_ndb_deferred_constraints6358108 Ref: sysvar_ndb_distribution6359319 Ref: sysvar_ndb_extra_logging6360314 Ref: sysvar_ndb_force_send6361896 Ref: sysvar_ndb_index_stat_cache_entries6362633 Ref: sysvar_ndb_index_stat_enable6363575 Ref: sysvar_ndb_index_stat_update_freq6364127 Ref: sysvar_ndb_join_pushdown6365038 Ref: sysvar_ndb_log_apply_status6371347 Ref: sysvar_ndb_log_bin6372252 Ref: sysvar_ndb_log_binlog_index6373205 Ref: sysvar_ndb_log_orig6374268 Ref: sysvar_ndb_optimized_node_selection6375083 Ref: sysvar_ndb_report_thresh_binlog_epoch_slip6378804 Ref: sysvar_ndb_report_thresh_binlog_mem_usage6379725 Ref: sysvar_slave_allow_batching6380601 Ref: sysvar_ndb_table_no_logging6381628 Ref: sysvar_ndb_table_temporary6383763 Ref: sysvar_ndb_use_copying_alter_table6384604 Ref: sysvar_ndb_use_exact_count6385201 Ref: sysvar_ndb_use_transactions6385963 Ref: sysvar_transaction_allow_batching6386899 Ref: sysvar_ndbinfo_database6388508 Ref: sysvar_ndbinfo_max_bytes6389356 Ref: sysvar_ndbinfo_max_rows6390015 Ref: sysvar_ndbinfo_show_hidden6390670 Ref: sysvar_ndbinfo_table_prefix6391467 Ref: sysvar_ndbinfo_version6392550 Ref: sysvar_ndb_log_transaction_id6393118 Ref: sysvar_ndb_log_empty_epochs6394165 Ref: sysvar_server_id_bits6395089 Node: mysql-cluster-status-variables6396358 Ref: statvar_Handler_discover6396886 Ref: statvar_Ndb_api_wait_exec_complete_count_session6397188 Ref: statvar_Ndb_api_wait_exec_complete_count_slave6398062 Ref: statvar_Ndb_api_wait_exec_complete_count6398963 Ref: statvar_Ndb_api_wait_scan_result_count_session6399755 Ref: statvar_Ndb_api_wait_scan_result_count_slave6400454 Ref: statvar_Ndb_api_wait_scan_result_count6401174 Ref: statvar_Ndb_api_wait_meta_request_count_session6401791 Ref: statvar_Ndb_api_wait_meta_request_count_slave6402482 Ref: statvar_Ndb_api_wait_meta_request_count6403199 Ref: statvar_Ndb_api_wait_nanos_count_session6403813 Ref: statvar_Ndb_api_wait_nanos_count_slave6404409 Ref: statvar_Ndb_api_wait_nanos_count6405031 Ref: statvar_Ndb_api_bytes_sent_count_session6405545 Ref: statvar_Ndb_api_bytes_sent_count_slave6406105 Ref: statvar_Ndb_api_bytes_sent_count6406686 Ref: statvar_Ndb_api_bytes_received_count_session6407164 Ref: statvar_Ndb_api_bytes_received_count_slave6407734 Ref: statvar_Ndb_api_bytes_received_count6408330 Ref: statvar_Ndb_api_trans_start_count_session6408818 Ref: statvar_Ndb_api_trans_start_count_slave6409360 Ref: statvar_Ndb_api_trans_start_count6409928 Ref: statvar_Ndb_api_trans_commit_count_session6410388 Ref: statvar_Ndb_api_trans_commit_count_slave6410933 Ref: statvar_Ndb_api_trans_commit_count6411504 Ref: statvar_Ndb_api_trans_abort_count_session6411972 Ref: statvar_Ndb_api_trans_abort_count_slave6412514 Ref: statvar_Ndb_api_trans_abort_count6413082 Ref: statvar_Ndb_api_trans_close_count_session6413542 Ref: statvar_Ndb_api_trans_close_count_slave6414275 Ref: statvar_Ndb_api_trans_close_count6415024 Ref: statvar_Ndb_api_pk_op_count_session6415653 Ref: statvar_Ndb_api_pk_op_count_slave6416373 Ref: statvar_Ndb_api_pk_op_count6417119 Ref: statvar_Ndb_api_uk_op_count_session6417757 Ref: statvar_Ndb_api_uk_op_count_slave6418318 Ref: statvar_Ndb_api_uk_op_count6418905 Ref: statvar_Ndb_api_table_scan_count_session6419384 Ref: statvar_Ndb_api_table_scan_count_slave6419981 Ref: statvar_Ndb_api_table_scan_count6420604 Ref: statvar_Ndb_api_range_scan_count_session6421119 Ref: statvar_Ndb_api_range_scan_count_slave6421679 Ref: statvar_Ndb_api_range_scan_count6422260 Ref: statvar_Ndb_api_pruned_scan_count_session6422738 Ref: statvar_Ndb_api_pruned_scan_count_slave6423314 Ref: statvar_Ndb_api_pruned_scan_count6423916 Ref: statvar_Ndb_api_scan_batch_count_session6424410 Ref: statvar_Ndb_api_scan_batch_count_slave6425028 Ref: statvar_Ndb_api_scan_batch_count6425672 Ref: statvar_Ndb_api_read_row_count_session6426213 Ref: statvar_Ndb_api_read_row_count_slave6426879 Ref: statvar_Ndb_api_read_row_count6427563 Ref: statvar_Ndb_api_trans_local_read_row_count_session6428156 Ref: statvar_Ndb_api_trans_local_read_row_count_slave6428834 Ref: statvar_Ndb_api_trans_local_read_row_count6429530 Ref: statvar_Ndb_api_event_data_count_injector6430135 Ref: statvar_Ndb_api_event_data_count6430616 Ref: statvar_Ndb_api_event_nondata_count_injector6431086 Ref: statvar_Ndb_api_event_nondata_count6431590 Ref: statvar_Ndb_api_event_bytes_count_injector6432083 Ref: statvar_Ndb_api_event_bytes_count6432563 Ref: statvar_Ndb_cluster_node_id6433032 Ref: statvar_Ndb_config_from_host6433276 Ref: statvar_Ndb_config_from_port6433687 Ref: statvar_Ndb_conflict_fn_max6434114 Ref: statvar_Ndb_conflict_fn_old6434584 Ref: statvar_Ndb_conflict_fn_epoch6435038 Ref: statvar_Ndb_conflict_fn_epoch_trans6435471 Ref: statvar_Ndb_conflict_trans_row_conflict_count6435916 Ref: statvar_Ndb_conflict_trans_row_reject_count6436587 Ref: statvar_Ndb_conflict_trans_reject_count6437139 Ref: statvar_Ndb_conflict_trans_detect_iter_count6437527 Ref: statvar_Ndb_conflict_trans_conflict_commit_count6437975 Ref: statvar_Ndb_execute_count6438353 Ref: statvar_Ndb_number_of_data_nodes6438528 Ref: statvar_Ndb_pushed_queries_defined6438870 Ref: statvar_Ndb_pushed_queries_dropped6439167 Ref: statvar_Ndb_pushed_queries_executed6439345 Ref: statvar_Ndb_pushed_reads6439528 Ref: statvar_Slave_heartbeat_period6439861 Ref: statvar_Slave_received_heartbeats6440040 Ref: statvar_Ndb_pruned_scan_count6440372 Ref: statvar_Ndb_scan_count6440960 Node: mysql-cluster-interconnects6441233 Node: mysql-cluster-sci-sockets6443859 Node: mysql-cluster-interconnects-performance6445919 Node: mysql-cluster-programs6450150 Node: mysql-cluster-programs-ndbd6454010 Ref: mysql-cluster-ndbd-options-table6455205 Ref: option_ndbd_bind-address6459143 Ref: option_ndbd_daemon6459727 Ref: option_ndbd_nodaemon6460515 Ref: option_ndbd_foreground6461423 Ref: option_ndbd_initial6462149 Ref: option_ndbd_initial-start6464567 Ref: option_ndbd_nowait-nodes6466197 Ref: option_ndbd_nostart6467652 Ref: option_ndbd_install6468575 Ref: option_ndbd_remove6470319 Ref: option_ndbd_connect-retries6471122 Ref: option_ndbd_connect-delay6472017 Node: mysql-cluster-programs-ndbinfo-select-all6478389 Ref: mysql-cluster-ndbinfo_select_all-options-table6481653 Ref: option_ndbinfo_select_all_delay6482835 Ref: option_ndbinfo_select_all_loops6483365 Node: mysql-cluster-programs-ndbmtd6483934 Node: mysql-cluster-programs-ndb-mgmd6489943 Ref: mysql-cluster-ndb_mgmd-options-table6490892 Ref: option_ndb_mgmd_bind-address6495722 Ref: option_ndb_mgmd_no-nodeid-checks6496678 Ref: option_ndb_mgmd_configdir6497060 Ref: option_ndb_mgmd_config-cache6497729 Ref: option_ndb_mgmd_skip_config-cache6498237 Ref: option_ndb_mgmd_config-file6500740 Ref: option_ndb_mgmd_mycnf6502644 Ref: option_ndb_mgmd_daemon6503002 Ref: option_ndb_mgmd_interactive6503613 Ref: option_ndb_mgmd_initial6504230 Ref: option_ndb_mgmd_log-name6506499 Ref: option_ndb_mgmd_nodaemon6506997 Ref: option_ndb_mgmd_print-full-config6507701 Ref: option_ndb_mgmd_reload6508509 Ref: option_ndb_mgmd_nowait-nodes6510382 Ref: option_ndb_mgmd_install6517248 Ref: option_ndb_mgmd_remove6518925 Node: mysql-cluster-programs-ndb-mgm6519738 Ref: mysql-cluster-ndb_mgm-options-table6521199 Ref: option_ndb_mgm_execute6521934 Ref: option_ndb_mgm_try-reconnect6522950 Node: mysql-cluster-programs-ndb-blob-tool6523742 Ref: mysql-cluster-ndb_blob_tool-options-table6525980 Ref: option_ndb_blob_tool_check-orphans6527114 Ref: option_ndb_blob_tool_database6527554 Ref: option_ndb_blob_tool_delete-orphans6528031 Ref: option_ndb_blob_tool_dump-file6528473 Ref: option_ndb_blob_tool_verbose6529070 Node: mysql-cluster-programs-ndb-config6531510 Ref: mysql-cluster-ndb_config-options-table6533362 Ref: option_ndb_config_usage6537141 Ref: option_ndb_config_config_from_node6537500 Ref: option_ndb_config_version6538393 Ref: option_ndb_config_ndb-connectstring6538704 Ref: option_ndb_config_config-file6539599 Ref: option_ndb_config_mycnf6540301 Ref: option_ndb_config_query6540659 Ref: option_ndb_config_host6541711 Ref: option_ndb_config_id6542932 Ref: option_ndb_config_nodeid6542949 Ref: option_ndb_config_nodes6543454 Ref: option_ndb_config_connections6544076 Ref: option_ndb_config_system6544707 Ref: option_ndb_config_type6545344 Ref: option_ndb_config_fields6545952 Ref: option_ndb_config_rows6546597 Ref: option_ndb_config_configinfo6547224 Ref: option_ndb_config_xml6549039 Node: mysql-cluster-programs-ndb-cpcd6556641 Node: mysql-cluster-programs-ndb-delete-all6557574 Ref: mysql-cluster-ndb_delete_all-options-table6558690 Ref: option_ndb_delete_all_transactional6559740 Node: mysql-cluster-programs-ndb-desc6560011 Ref: mysql-cluster-ndb_desc-options-table6568432 Ref: option_ndb_desc_blob-info6570596 Ref: option_ndb_desc_database6570941 Ref: option_ndb_desc_extra-node-info6571038 Ref: option_ndb_desc_extra-partition-info6571611 Ref: option_ndb_desc_retries6571714 Ref: option_ndb_desc_table6571841 Ref: option_ndb_desc_unqualified6572019 Node: mysql-cluster-programs-ndb-drop-index6572078 Ref: mysql-cluster-ndb_drop_index-options-table6573163 Node: mysql-cluster-programs-ndb-drop-table6575280 Ref: mysql-cluster-ndb_drop_table-options-table6576452 Node: mysql-cluster-programs-ndb-error-reporter6576996 Ref: mysql-cluster-ndb_error_reporter-options-table6578007 Ref: option_ndb_error_reporter_fs6579205 Node: mysql-cluster-programs-ndb-index-stat6579789 Ref: mysql-cluster-ndb_index_stat-options-table6581911 Ref: ndb-index-stat-options-statistics6585566 Ref: option_ndb_index_stat_database6585779 Ref: option_ndb_index_stat_delete6586268 Ref: option_ndb_index_stat_update6586735 Ref: option_ndb_index_stat_dump6587201 Ref: option_ndb_index_stat_query6587589 Ref: ndb-index-stat-options-system6588065 Ref: option_ndb_index_stat_sys-drop6588268 Ref: option_ndb_index_stat_sys-create6588734 Ref: option_ndb_index_stat_sys-create-if-not-exist6589217 Ref: option_ndb_index_stat_sys-create-if-not-valid6589742 Ref: option_ndb_index_stat_sys-check6590268 Ref: option_ndb_index_stat_sys-skip-tables6590724 Ref: option_ndb_index_stat_sys-skip-events6591168 Ref: option_ndb_index_stat_verbose6591601 Ref: option_ndb_index_stat_loops6592027 Node: mysql-cluster-programs-ndb-print-backup-file6592481 Node: mysql-cluster-programs-ndb-print-schema-file6594101 Node: mysql-cluster-programs-ndb-print-sys-file6595502 Node: mysql-cluster-programs-ndbd-redo-log-reader6597187 Ref: mysql-cluster-ndbd_redo_log_reader-options-table6598684 Ref: option_ndbd_redo_log_reader_noprint6600262 Ref: option_ndbd_redo_log_reader_nocheck6600613 Node: mysql-cluster-programs-ndb-restore6601334 Ref: mysql-cluster-ndb_restore-options-table6602946 Ref: option_ndb_restore_connect6613701 Ref: option_ndb_restore_nodeid6614847 Ref: option_ndb_restore_skip-table-check6615543 Ref: option_ndb_restore_promote-attributes6617433 Ref: option_ndb_restore_lossy-conversions6619030 Ref: option_ndb_restore_preserve-trailing-spaces6620059 Ref: option_ndb_restore_backupid6620859 Ref: option_ndb_restore_restore_epoch6621394 Ref: option_ndb_restore_restore_data6621819 Ref: option_ndb_restore_restore_meta6621973 Ref: option_ndb_restore_restore-privilege-tables6622277 Ref: option_ndb_restore_backup_path6622763 Ref: option_ndb_restore_no-upgrade6625741 Ref: option_ndb_restore_print_data6626324 Ref: option_ndb_restore_tab6626939 Ref: option_ndb_restore_fields-enclosed-by6627401 Ref: option_ndb_restore_fields-optionally-enclosed-by6627919 Ref: option_ndb_restore_fields-terminated-by6628588 Ref: option_ndb_restore_hex6629158 Ref: option_ndb_restore_lines-terminated-by6629412 Ref: option_ndb_restore_append6629979 Ref: option_ndb_restore_print_meta6630455 Ref: option_ndb_restore_print_log6630583 Ref: option_ndb_restore_print6630719 Ref: option_ndb_restore_dont_ignore_systab_06631258 Ref: option_ndb_restore_ndb-nodegroup-map6631674 Ref: option_ndb_restore_no-binlog6631876 Ref: option_ndb_restore_no-restore-disk-objects6632127 Ref: option_ndb_restore_parallelism6632424 Ref: option_ndb_restore_progress-frequency6632649 Ref: option_ndb_restore_verbose6632824 Ref: option_ndb_restore_include-databases6633352 Ref: option_ndb_restore_include-tables6633702 Ref: option_ndb_restore_exclude-databases6637002 Ref: option_ndb_restore_exclude-tables6637352 Ref: option_ndb_restore_exclude-missing-columns6642542 Ref: option_ndb_restore_disable-indexes6643411 Ref: option_ndb_restore_rebuild-indexes6644045 Ref: option_ndb_restore_skip-broken-objects6644475 Ref: option_ndb_restore_skip-unknown-objects6645084 Ref: option_ndb_restore_rewrite-database6645677 Node: mysql-cluster-programs-ndb-select-all6648725 Ref: mysql-cluster-ndb_select_all-options-table6649638 Ref: option_ndb_select_all_database6652551 Ref: option_ndb_select_all_parallelism6652684 Ref: option_ndb_select_all_lock6652758 Ref: option_ndb_select_all_order6653032 Ref: option_ndb_select_all_descending6653274 Ref: option_ndb_select_all_header6653429 Ref: option_ndb_select_all_useHexFormat6653500 Ref: option_ndb_select_all_delimiter6653695 Ref: option_ndb_select_all_disk6653915 Ref: option_ndb_select_all_rowid6654062 Ref: option_ndb_select_all_gci6654180 Ref: option_ndb_select_all_tupscan6654424 Ref: option_ndb_select_all_nodata6654498 Node: mysql-cluster-programs-ndb-select-count6656939 Ref: mysql-cluster-ndb_select_count-options-table6658018 Node: mysql-cluster-programs-ndb-show-tables6659331 Ref: mysql-cluster-ndb_show_tables-options-table6660399 Ref: option_ndb_show_tables_database6661979 Ref: option_ndb_show_tables_loops6662077 Ref: option_ndb_show_tables_parsable6662294 Ref: option_ndb_show_tables_show-temp-status6662444 Ref: option_ndb_show_tables_type6662538 Ref: option_ndb_show_tables_unqualified6662888 Node: mysql-cluster-programs-ndb-size-pl6663369 Ref: mysql-cluster-ndb_size_pl-options-table6665492 Ref: option_ndb_size_pl_options6668340 Ref: option_ndb_size_pl_debugging6672836 Ref: option_ndb_size_pl_format6673161 Node: mysql-cluster-programs-ndb-waiter6674236 Ref: mysql-cluster-ndb_waiter-options-table6676269 Ref: mysql-cluster-programs-ndb-waiter-additional-options6677942 Ref: option_ndb_waiter_no-contact6677971 Ref: option_ndb_waiter_not-started6678194 Ref: option_ndb_waiter_timeout6678413 Ref: option_ndb_waiter_single-user6678622 Ref: option_ndb_waiter_nowait-nodes6678712 Ref: option_ndb_waiter_wait-nodes6679122 Node: mysql-cluster-program-options-common6681312 Ref: mysql-cluster-ndb_common-options-table6682711 Ref: option_ndb_common_help6685922 Ref: option_ndb_common_character-sets-dir6686235 Ref: option_ndb_common_ndb-connectstring6686695 Ref: option_ndb_common_core-file6687554 Ref: option_ndb_common_debug6688571 Ref: option_ndb_common_ndb-mgmd-host6689113 Ref: option_ndb_common_ndb-nodeid6689818 Ref: option_ndb_common_ndb-optimized-node-selection6690396 Ref: option_ndb_common_version6690841 Ref: option_ndb_common_ndb-shm6691499 Node: mysql-cluster-management6692136 Node: mysql-cluster-start-phases6698024 Node: mysql-cluster-mgm-client-commands6705433 Node: mysql-cluster-backup6717736 Node: mysql-cluster-backup-concepts6719123 Node: mysql-cluster-backup-using-management-client6720974 Node: mysql-cluster-backup-configuration6729971 Node: mysql-cluster-backup-troubleshooting6731131 Node: mysql-cluster-mysqld6732275 Node: mysql-cluster-rolling-restart6737344 Ref: mysql-cluster-rolling-restart-multiple-ndb-mgmd6745223 Node: mysql-cluster-event-reports6747284 Node: mysql-cluster-logging-management-commands6752468 Node: mysql-cluster-log-events6756611 Node: mysql-cluster-log-statistics6768871 Node: mysql-cluster-logs-ndb-messages6777646 Node: mysql-cluster-logs-cluster-log6778280 Node: mysql-cluster-ndb-transporter-errors6824657 Node: mysql-cluster-single-user-mode6830900 Node: mysql-cluster-sql-statements6833309 Node: mysql-cluster-ndbinfo6841056 Node: mysql-cluster-ndbinfo-arbitrator-validity-detail6853803 Node: mysql-cluster-ndbinfo-arbitrator-validity-summary6855975 Node: mysql-cluster-ndbinfo-blocks6858081 Node: mysql-cluster-ndbinfo-cluster-operations6859482 Node: mysql-cluster-ndbinfo-cluster-transactions6863485 Node: mysql-cluster-ndbinfo-config-params6866609 Node: mysql-cluster-ndbinfo-counters6867889 Node: mysql-cluster-ndbinfo-diskpagebuffer6872298 Node: mysql-cluster-ndbinfo-logbuffers6876020 Node: mysql-cluster-ndbinfo-logspaces6877232 Node: mysql-cluster-ndbinfo-membership6878428 Node: mysql-cluster-ndbinfo-memoryusage6883706 Node: mysql-cluster-ndbinfo-nodes6890451 Node: mysql-cluster-ndbinfo-pools6897373 Node: mysql-cluster-ndbinfo-resources6903319 Node: mysql-cluster-ndbinfo-server-operations6904957 Node: mysql-cluster-ndbinfo-server-transactions6909330 Node: mysql-cluster-ndbinfo-threadblocks6912883 Node: mysql-cluster-ndbinfo-threadstat6914244 Node: mysql-cluster-ndbinfo-transporters6917241 Node: mysql-cluster-security6924134 Node: mysql-cluster-security-networking-issues6925043 Node: mysql-cluster-security-mysql-privileges6935130 Node: mysql-cluster-security-mysql-security-procedures6943844 Node: mysql-cluster-disk-data6948122 Node: mysql-cluster-disk-data-objects6949865 Node: mysql-cluster-disk-data-symlinks6963201 Node: mysql-cluster-disk-data-storage-requirements6968228 Node: mysql-cluster-online-add-node6970293 Node: mysql-cluster-online-add-node-remarks6971381 Node: mysql-cluster-online-add-node-basics6982112 Node: mysql-cluster-online-add-node-example6986572 Node: mysql-cluster-privilege-distribution7008395 Node: mysql-cluster-ndb-api-statistics7018845 Node: mysql-cluster-replication7060456 Ref: mysql-cluster-replication-ndb-non-ndb7065062 Node: mysql-cluster-replication-abbreviations7065677 Node: mysql-cluster-replication-general7067448 Node: mysql-cluster-replication-issues7071133 Ref: mysql-cluster-replication-ndb-to-non-ndb7081448 Ref: mysql-cluster-replication-ndb-to-nontransactional7084862 Ref: mysql-cluster-replication-issues-filtering7085911 Node: mysql-cluster-replication-schema7090122 Node: mysql-cluster-replication-preparation7102769 Node: mysql-cluster-replication-starting7108045 Node: mysql-cluster-replication-two-channels7113082 Node: mysql-cluster-replication-failover7116128 Node: mysql-cluster-replication-backups7120757 Node: mysql-cluster-replication-auto-sync7129367 Node: mysql-cluster-replication-pitr7135508 Node: mysql-cluster-replication-multi-master7139029 Node: mysql-cluster-replication-conflict-resolution7146471 Ref: option_mysqld_ndb-log-updated-only7151700 Ref: option_mysqld_ndb-log-update-as-write7152909 Ref: mysql-cluster-ndb-replication-table7153913 Ref: mysql-cluster-replication-ndb-old7157387 Ref: mysql-cluster-replication-ndb-max7158042 Ref: mysql-cluster-replication-ndb-max-delete-win7158692 Ref: mysql-cluster-replication-ndb-epoch7159781 Ref: mysql-cluster-replication-ndb-epoch-statvars7164361 Ref: mysql-cluster-replication-ndb-epoch-limitations7165150 Ref: mysql-cluster-replication-ndb-epoch-trans7167304 Node: mysql-cluster-news7176005 Node: partitioning7176456 Node: partitioning-overview7184521 Node: partitioning-types7194193 Node: partitioning-range7200621 Node: partitioning-list7210202 Node: partitioning-hash7216307 Node: partitioning-linear-hash7223026 Node: partitioning-key7225898 Node: partitioning-subpartitions7231080 Node: partitioning-handling-nulls7240657 Node: partitioning-management7255257 Node: partitioning-management-range-list7259238 Node: partitioning-management-hash-key7277347 Node: partitioning-maintenance7280211 Node: partitioning-info7284209 Node: partitioning-pruning7290568 Node: partitioning-limitations7302370 Ref: partitioning-limitations-file-system-ops7309079 Ref: partitioning-limitations-max-partitions7311337 Ref: partitioning-limitations-subpartitions7315202 Node: partitioning-limitations-partitioning-keys-unique-keys7319686 Node: partitioning-limitations-storage-engines7328386 Node: partitioning-limitations-functions7332351 Ref: partitioning-limitations-ceiling-floor7334112 Ref: partitioning-limitations-extract7334712 Node: partitioning-limitations-locking7335202 Node: stored-programs-views7337743 Node: stored-programs-defining7340064 Node: stored-routines7343056 Node: stored-routines-syntax7346264 Node: stored-routines-privileges7349379 Node: stored-routines-metadata7351012 Node: stored-routines-last-insert-id7352266 Node: triggers7353262 Node: trigger-syntax7355634 Node: trigger-metadata7365836 Node: events7366358 Node: events-overview7368331 Node: events-configuration7372689 Ref: events-event-scheduler-option7373222 Node: events-syntax7380303 Node: events-metadata7381425 Node: events-status-info7385393 Node: events-privileges7388137 Node: views7396868 Node: view-syntax7398087 Node: view-algorithms7399438 Node: view-updatability7403079 Node: view-metadata7409109 Node: stored-programs-security7409506 Node: stored-programs-logging7415584 Node: information-schema7436898 Node: character-sets-table7447355 Node: collations-table7448345 Node: collation-character-set-applicability-table7450079 Node: columns-table7450972 Node: column-privileges-table7453668 Node: engines-table7455475 Node: events-table7456512 Node: status-table7467658 Node: variables-table7469056 Node: key-column-usage-table7470662 Node: partitions-table7473360 Node: plugins-table7485390 Node: processlist-table7488670 Node: profiling-table7490734 Node: referential-constraints-table7493855 Node: routines-table7495886 Node: schemata-table7499506 Node: schema-privileges-table7500504 Node: statistics-table7501694 Node: tables-table7503751 Node: table-constraints-table7508373 Node: table-privileges-table7509798 Node: triggers-table7511115 Node: user-privileges-table7517159 Node: views-table7518256 Node: mysql-cluster-i_s-tables7522831 Node: files-table7524211 Node: ndb-transid-mysql-connection-map-table7541139 Node: extended-show7546550 Node: connectors-apis7552664 Ref: connectors-apis-summary7558468 Ref: connectors-apis-versions7563434 Node: connector-odbc7565114 Node: connector-odbc-versions7568350 Node: connector-odbc-introduction7571708 Node: connector-odbc-general-information7572621 Node: connector-odbc-architecture7573483 Node: connector-odbc-driver-manager7577556 Node: connector-odbc-installation7579199 Node: connector-odbc-installation-binary-windows7584321 Node: connector-odbc-installation-binary-windows-installer7586235 Node: connector-odbc-installation-binary-windows-dll7588397 Node: connector-odbc-installation-binary-unix7591891 Node: connector-odbc-installation-binary-unix-tarball7592739 Node: connector-odbc-installation-binary-unix-rpm7593898 Node: connector-odbc-installation-binary-macosx7595265 Node: connector-odbc-installation-source-windows7597444 Ref: connector-odbc-installation-source-windows-5-2-building7598812 Node: connector-odbc-installation-source-unix7600096 Ref: connector-odbc-installation-source-unix-cmake-options7602283 Ref: connector-odbc-installation-source-unix-otheroptions7603239 Ref: connector-odbc-installation-source-unix-building7605092 Ref: connector-odbc-installation-source-unix-shared-libraries7605360 Ref: connector-odbc-installation-source-unix-installing7607614 Ref: connector-odbc-installation-source-unix-testing7608320 Node: connector-odbc-installation-source-unix-macosx7608880 Node: connector-odbc-installation-source-development7610865 Node: connector-odbc-configuration7613204 Node: connector-odbc-configuration-dsn7614674 Node: connector-odbc-configuration-connection-parameters7616158 Ref: codbc-dsn-config-options7617078 Ref: codbc-dsn-option-flags7625157 Ref: codbc-dsn-option-combos7643049 Node: connector-odbc-configuration-dsn-windows7644283 Node: connector-odbc-configuration-dsn-windows-5-27647727 Node: connector-odbc-configuration-dsn-windows-5-2-command-line7651122 Node: connector-odbc-configuration-dsn-windows-problems7651713 Node: connector-odbc-configuration-dsn-macosx7652914 Node: connector-odbc-configuration-dsn-unix7655746 Node: connector-odbc-configuration-connection-without-dsn7657728 Node: connector-odbc-configuration-connection-pooling7659243 Node: connector-odbc-configuration-trace7660014 Node: connector-odbc-configuration-trace-windows7660830 Node: connector-odbc-configuration-trace-macosx7661900 Node: connector-odbc-configuration-trace-unix7662589 Node: connector-odbc-configuration-trace-log7663603 Node: connector-odbc-examples7664694 Node: connector-odbc-examples-overview7665838 Node: connector-odbc-examples-walkthrough7666680 Node: connector-odbc-examples-tools7668927 Node: connector-odbc-examples-tools-with-access7671547 Node: connector-odbc-examples-tools-with-access-export7672410 Node: connector-odbc-examples-tools-with-access-import7674218 Node: connector-odbc-examples-tools-with-access-linked-tables7675452 Node: connector-odbc-examples-tools-with-wordexcel7678932 Node: connector-odbc-examples-tools-with-crystalreports7682126 Node: connector-odbc-examples-programming7686838 Node: connector-odbc-examples-programming-vb7687633 Node: connector-odbc-examples-programming-vb-ado7688350 Node: connector-odbc-examples-programming-vb-dao7691269 Node: connector-odbc-examples-programming-vb-rdo7693698 Node: connector-odbc-examples-programming-net7695884 Node: connector-odbc-examples-programming-net-csharp7696444 Node: connector-odbc-examples-programming-net-vb7702392 Node: connector-odbc-reference7706375 Node: connector-odbc-reference-api7707049 Node: connector-odbc-reference-datatypes7719730 Node: connector-odbc-reference-errorcodes7722786 Node: connector-odbc-usagenotes7726074 Node: connector-odbc-usagenotes-functionality7726748 Node: connector-odbc-usagenotes-functionality-last-insert-id7727509 Node: connector-odbc-usagenotes-functionality-dynamic-cursor7729116 Node: connector-odbc-usagenotes-functionality-performance7729805 Node: connector-odbc-usagenotes-functionality-query-timeout7731392 Node: connector-odbc-usagenotes-apptips7731917 Node: connector-odbc-usagenotes-apptips-microsoft7733413 Node: connector-odbc-usagenotes-apptips-microsoft-access7734663 Node: connector-odbc-usagenotes-apptips-microsoft-excel7739162 Node: connector-odbc-usagenotes-apptips-microsoft-visualbasic7740371 Node: connector-odbc-usagenotes-apptips-microsoft-visualinterdev7741214 Node: connector-odbc-usagenotes-apptips-microsoft-visualobjects7741808 Node: connector-odbc-usagenotes-apptips-microsoft-ado7742170 Node: connector-odbc-usagenotes-apptips-microsoft-asp7743771 Node: connector-odbc-usagenotes-apptips-microsoft-vb-asp7744683 Node: connector-odbc-usagenotes-apptips-borland7745417 Node: connector-odbc-usagenotes-apptips-borland-builder7746326 Node: connector-odbc-usagenotes-apptips-borland-delphi7746885 Node: connector-odbc-usagenotes-apptips-borland-cppbuilder7748874 Node: connector-odbc-usagenotes-apptips-coldfusion7749397 Node: connector-odbc-usagenotes-apptips-openoffice7750797 Node: connector-odbc-usagenotes-apptips-sambarserver7751342 Node: connector-odbc-usagenotes-apptips-datajunction7751804 Node: connector-odbc-usagenotes-apptips-vision7752314 Node: connector-odbc-errors7752631 Node: connector-odbc-support7766298 Node: connector-odbc-support-community7766973 Node: connector-odbc-support-bug-report7767889 Node: connector-odbc-support-patch-submission7770457 Node: connector-net7770830 Node: connector-net-versions7774348 Ref: connector-net-prereqs7779092 Node: connector-net-installation7781540 Node: connector-net-installation-windows7782353 Node: connector-net-installation-binary-windows-installer7783087 Node: connector-net-installation-binary-windows-zip7787361 Node: connector-net-installation-unix7789711 Node: connector-net-installation-source7791908 Node: connector-net-visual-studio7793065 Node: connector-net-visual-studio-making-a-connection7796921 Ref: connector-net-visual-studio-add-connection7797747 Ref: connector-net-visual-studio-choose-data-source7798056 Ref: connector-net-visual-studio-add-connection-dialog7798390 Ref: connector-net-visual-studio-new-data-connection7798982 Node: connector-net-visual-studio-intellisense7799586 Node: connector-net-visual-studio-editing-tables7800408 Ref: connector-net-visual-studio-editing-new-table7801730 Ref: connector-net-visual-studio-choose-table-name7802804 Ref: connector-net-visual-studio-newly-created-table7802909 Ref: connector-net-visual-studio-table-designer-menu-item7803284 Node: connector-net-visual-studio-editing-tables-column-editor7803328 Node: connector-net-visual-studio-editing-tables-indexes7804647 Ref: connector-net-visual-studio-indexes-dialog7805224 Node: connector-net-visual-studio-editing-tables-foreign-keys7805547 Ref: connector-net-visual-studio-foreign-key-relationships7806634 Node: connector-net-visual-studio-editing-tables-column-details7806686 Node: connector-net-visual-studio-editing-tables-table-properties7807263 Ref: connector-net-visual-studio-table-properties-menu7807693 Ref: connector-net-visual-studio-selecting-table-properties7808505 Node: connector-net-visual-studio-editing-views7808541 Ref: connector-net-visual-studio-views-edit-sql7809015 Ref: connector-net-visual-studio-views-sql-added7809094 Ref: connector-net-visual-studio-views-sql-saved7809913 Node: connector-net-visual-studio-editing-stored-procedures-and-functions7809947 Ref: connector-net-visual-studio-stored-procedure-edit7810506 Ref: connector-net-visual-studio-stored-procedure-saved7812067 Node: connector-net-visual-studio-editing-triggers7812331 Node: connector-net-visual-studio-editing-user-defined-functions-udf7814225 Node: connector-net-visual-studio-debugger7815825 Ref: connector-net-visual-studio-debugger-connection7817439 Ref: connector-net-visual-studio-debugger-choose-routine7817782 Ref: connector-net-visual-studio-debugger-args17818390 Ref: connector-net-visual-studio-debugger-args27818436 Ref: connector-net-visual-studio-debugger-trigger7821575 Ref: connector-net-visual-studio-debugger-callstack7822051 Ref: connector-net-visual-studio-debugger-stepping7822247 Ref: connector-net-visual-studio-debugger-stepping17822286 Ref: connector-net-visual-studio-debugger-stepping27822337 Ref: connector-net-visual-studio-debugger-conditional-breakpoints7825917 Ref: connector-net-visual-studio-debugger-expressions-breakpoints7825965 Node: connector-net-visual-studio-cloning-database-objects7828053 Node: connector-net-visual-studio-dropping-database-objects7829034 Node: connector-net-visual-studio-entity-framework7829690 Node: connector-net-website-config7831455 Ref: connector-net-website-config-tool7832225 Ref: connector-net-website-config-tool-membership7832374 Ref: connector-net-website-config-tool-string-editor7832767 Ref: connector-net-website-config-tool-options7833770 Ref: connector-net-website-config-tool-roles7834004 Ref: connector-net-website-config-tool-profiles7834229 Ref: connector-net-website-config-tool-session-state7834420 Ref: connector-net-website-config-tool-tables7834966 Node: connector-net-sql-editor7835027 Ref: connector-net-sql-editor-new-file-dialog7835453 Ref: connector-net-sql-editor-query7836209 Node: connector-net-ddl-t4-ef7836367 Ref: connector-net-ddl-t4-ef-properties7837060 Ref: connector-net-ddl-t4-ef-generate7837345 Node: connector-net-tutorials7837413 Node: connector-net-tutorials-intro7838933 Node: connector-net-tutorials-connection7840640 Node: connector-net-tutorials-sql-command7842815 Node: connector-net-tutorials-data-adapter7848776 Ref: connector-net-tutorials-17855890 Node: connector-net-tutorials-parameters7855936 Node: connector-net-tutorials-stored-procedures7859258 Node: connector-net-tutorials-asp-roles7863563 Ref: connector-net-tutorials-authentication-type7869347 Ref: connector-net-tutorials-select-provider7869677 Ref: connector-net-tutorials-tables7869983 Ref: connector-net-tutorials-security-tab7870666 Ref: connector-net-tutorials-create-user7871019 Ref: connector-net-tutorials-users-roles-tables7871221 Node: connector-net-tutorials-asp-provider-session-state7871423 Node: connector-net-tutorials-asp-provider-profile7877954 Ref: connector-net-tutorials-asp-provider-profile-simple-app7881254 Node: connector-net-tutorials-entity-framework-winform-data-source7883659 Ref: connector-net-visual-studio-entity-framework-add-entity-data-model7885220 Ref: connector-net-visual-studio-entity-framework-entity-data-model-wizard-17885477 Ref: connector-net-visual-studio-entity-framework-entity-data-model-wizard-27885873 Ref: connector-net-visual-studio-entity-framework-entity-data-model-wizard-37886534 Ref: connector-net-visual-studio-entity-framework-entity-data-model-diagram7886657 Ref: connector-net-visual-studio-entity-framework-data-source-configuration-wizard-17887135 Ref: connector-net-visual-studio-entity-framework-data-source-configuration-wizard-27887432 Ref: connector-net-visual-studio-entity-framework-data-source-configuration-wizard-37887593 Ref: connector-net-visual-studio-entity-framework-data-sources7887900 Ref: connector-net-visual-studio-entity-framework-data-form-design7888395 Ref: connector-net-visual-studio-entity-framework-form-add-code7888861 Ref: connector-net-visual-studio-entity-framework-app-running-17889039 Ref: connector-net-visual-studio-entity-framework-save-enabled7889666 Ref: connector-net-visual-studio-entity-framework-form-add-code-save7889917 Node: connector-net-tutorials-entity-framework-databinding-linq-entities7890122 Ref: connector-net-visual-studio-entity-framework-tutorial-linq-17891479 Ref: connector-net-visual-studio-entity-framework-tutorial-linq-27891758 Ref: connector-net-visual-studio-entity-framework-tutorial-linq-37892087 Ref: connector-net-visual-studio-entity-framework-tutorial-linq-47892185 Ref: connector-net-visual-studio-entity-framework-tutorial-linq-57892337 Ref: connector-net-visual-studio-entity-framework-tutorial-linq-67896378 Ref: connector-net-visual-studio-entity-framework-tutorial-linq-77896547 Node: connector-net-tutorials-ssl7896758 Node: connector-net-tutorials-mysqlscript7903388 Node: connector-net-tutorials-mysqlscript-delimiter7908991 Node: connector-net-tutorials-efmodel-ddl7912860 Node: connector-net-programming7915056 Node: connector-net-programming-connecting7918223 Node: connector-net-programming-connecting-connection-string7918936 Node: connector-net-programming-connecting-open7920547 Node: connector-net-programming-connecting-errors7923409 Node: connector-net-programming-getschema7926239 Node: connector-net-programming-getschema-collections7927794 Node: connector-net-programming-mysqlcommand7930504 Node: connector-net-programming-connection-pooling7933823 Node: connector-net-programming-authentication-windows-native7936979 Node: connector-net-programming-authentication-user-plugin7938611 Node: connector-net-programming-tablecaching7948337 Node: connector-net-programming-prepared7949530 Node: connector-net-programming-prepared-preparing7950675 Node: connector-net-programming-stored7953315 Node: connector-net-programming-stored-using7956115 Node: connector-net-programming-blob7964457 Node: connector-net-programming-blob-serverprep7965575 Node: connector-net-programming-blob-writing7967680 Node: connector-net-programming-blob-reading7971237 Node: connector-net-interceptors7975085 Node: connector-net-programming-datetime7980414 Node: connector-net-programming-datetime-fractional7981449 Node: connector-net-programming-datetime-problems7983189 Node: connector-net-programming-datetime-restricting7983897 Node: connector-net-programming-datetime-invalid7984947 Node: connector-net-programming-datetime-null7986693 Node: connector-net-programming-bulk-loader7987744 Node: connector-net-programming-tracing7991409 Node: connector-net-programming-tracing-mysql7996476 Node: connector-net-programming-tracing-mysql-custom-listeners8003827 Node: connector-net-programming-binary-issues8007839 Node: connector-net-using-character-sets8009700 Node: connector-net-programming-crystal8011310 Node: connector-net-programming-crystal-source8012025 Node: connector-net-programming-crystal-creating8015528 Node: connector-net-programming-crystal-displaying8016620 Node: connector-net-programming-asp-provider8024367 Node: connector-net-medium-trust8032477 Node: connector-net-medium-trust-evolution8033610 Node: connector-net-medium-trust-gac8035737 Node: connector-net-medium-trust-nongac8040657 Node: connector-net-connection-options8042949 Node: connector-net-rt8073344 Node: connector-net-entityframework508075607 Node: connector-net-ref8083515 Node: connector-net-ref-mysqlclient8084020 Node: connector-net-ref-mysqlclienthierarchy8090306 Node: connector-net-ref-mysqlclient-basecommandinterceptor8090680 Node: connector-net-ref-mysqlclient-baseexceptioninterceptor8091826 Node: connector-net-ref-mysqlclient-mysqlcommand8092974 Node: connector-net-ref-mysqlclient-mysqlcommandmembers8094171 Node: connector-net-ref-mysqlclient-mysqlcommandconstructor8100174 Node: connector-net-ref-mysqlclient-mysqlcommandconstructor18101700 Node: connector-net-ref-mysqlclient-mysqlcommandconstructor28102510 Node: connector-net-ref-mysqlclient-mysqlcommandconstructor38103293 Node: connector-net-ref-mysqlclient-mysqlconnection8104224 Node: connector-net-ref-mysqlclient-mysqlconnectionmembers8105430 Node: connector-net-ref-mysqlclient-mysqlconnectionconstructor8111876 Node: connector-net-ref-mysqlclient-mysqlconnectionconstructor18113045 Node: connector-net-ref-mysqlclient-mysqlconnectionconstructor28113890 Node: connector-net-ref-mysqlclient-mysqlconnection-connectionstring8114642 Node: connector-net-ref-mysqlclient-mysqlconnection-connectiontimeout8115418 Node: connector-net-ref-mysqlclient-mysqlconnection-database8116200 Node: connector-net-ref-mysqlclient-mysqlconnection-datasource8116924 Node: connector-net-ref-mysqlclient-mysqlconnection-serverthread8117604 Node: connector-net-ref-mysqlclient-mysqlconnection-serverversion8118308 Node: connector-net-ref-mysqlclient-mysqlconnection-state8118944 Node: connector-net-ref-mysqlclient-mysqlconnection-usecompression8119677 Node: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overloads8120420 Node: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-18121505 Node: connector-net-ref-mysqlclient-mysqltransaction8122489 Node: connector-net-ref-mysqlclient-mysqltransactionmembers8123710 Node: connector-net-ref-mysqlclient-mysqltransaction-connection8126301 Node: connector-net-ref-mysqlclient-mysqltransaction-isolationlevel8127612 Node: connector-net-ref-mysqlclient-mysqltransaction-commit8128664 Node: connector-net-ref-mysqlclient-mysqltransaction-rollback8129383 Node: connector-net-ref-mysqlclient-mysqlconnection-begintransaction-overload-28130044 Node: connector-net-ref-mysqlclient-mysqlconnection-changedatabase8130935 Node: connector-net-ref-mysqlclient-mysqlconnection-close8131786 Node: connector-net-ref-mysqlclient-mysqlconnection-createcommand8132493 Node: connector-net-ref-mysqlclient-mysqlconnection-open8133154 Node: connector-net-ref-mysqlclient-mysqlconnection-ping8133844 Node: connector-net-ref-mysqlclient-mysqlconnection-infomessage8134475 Node: connector-net-ref-mysqlclient-mysqlinfomessageeventhandler8135275 Node: connector-net-ref-mysqlclient-mysqlinfomessageeventargs8136424 Node: connector-net-ref-mysqlclient-mysqlinfomessageeventargsmembers8137728 Node: connector-net-ref-mysqlclient-mysqlinfomessageeventargsconstructor8140502 Node: connector-net-ref-mysqlclient-mysqlinfomessageeventargs-errors8141326 Node: connector-net-ref-mysqlclient-mysqlerror8142028 Node: connector-net-ref-mysqlclient-mysqlerrormembers8143124 Node: connector-net-ref-mysqlclient-mysqlerrorconstructor8145748 Node: connector-net-ref-mysqlclient-mysqlerror-code8146527 Node: connector-net-ref-mysqlclient-mysqlerror-level8147096 Node: connector-net-ref-mysqlclient-mysqlerror-message8147669 Node: connector-net-ref-mysqlclient-mysqlconnection-statechange8148198 Node: connector-net-ref-mysqlclient-mysqlcommandconstructor48148815 Node: connector-net-ref-mysqlclient-mysqlcommand-commandtext8149681 Node: connector-net-ref-mysqlclient-mysqlcommand-commandtimeout8150395 Node: connector-net-ref-mysqlclient-mysqlcommand-commandtype8151126 Node: connector-net-ref-mysqlclient-mysqlcommand-connection8151862 Node: connector-net-ref-mysqlclient-mysqlcommand-isprepared8152483 Node: connector-net-ref-mysqlclient-mysqlcommand-parameters8153088 Node: connector-net-ref-mysqlclient-mysqlparametercollection8153834 Node: connector-net-ref-mysqlclient-mysqlparametercollectionmembers8155431 Node: connector-net-ref-mysqlclient-mysqlparametercollectionconstructor8161936 Node: connector-net-ref-mysqlclient-mysqlparametercollection-count8162748 Node: connector-net-ref-mysqlclient-mysqlparametercollectionitem8163547 Node: connector-net-ref-mysqlclient-mysqlparameter8165058 Node: connector-net-ref-mysqlclient-mysqlparametermembers8166559 Node: connector-net-ref-mysqlclient-mysqlparameterconstructor8172934 Node: connector-net-ref-mysqlclient-mysqlparameterconstructor18176042 Node: connector-net-ref-mysqlclient-mysqlparameterconstructor38176826 Node: connector-net-ref-mysqlclient-mysqldbtype8178100 Node: connector-net-ref-mysqlclient-mysqlparameterconstructor48185154 Node: connector-net-ref-mysqlclient-mysqlparameterconstructor68186555 Node: connector-net-ref-mysqlclient-mysqlparameter-value8189408 Node: connector-net-ref-mysqlclient-mysqlparameterconstructor58190080 Node: connector-net-ref-mysqlclient-mysqlparameterconstructor28191565 Node: connector-net-ref-mysqlclient-mysqlparameter-dbtype8192719 Node: connector-net-ref-mysqlclient-mysqlparameter-direction8193468 Node: connector-net-ref-mysqlclient-mysqlparameter-isnullable8194434 Node: connector-net-ref-mysqlclient-mysqlparameter-isunsigned8195231 Node: connector-net-ref-mysqlclient-mysqlparameter-mysqldbtype8195845 Node: connector-net-ref-mysqlclient-mysqlparameter-parametername8196529 Node: connector-net-ref-mysqlclient-mysqlparameter-precision8197319 Node: connector-net-ref-mysqlclient-mysqlparameter-scale8198174 Node: connector-net-ref-mysqlclient-mysqlparameter-size8198986 Node: connector-net-ref-mysqlclient-mysqlparameter-sourcecolumn8199739 Node: connector-net-ref-mysqlclient-mysqlparameter-sourceversion8200649 Node: connector-net-ref-mysqlclient-mysqlparameter-tostring8201539 Node: connector-net-ref-mysqlclient-mysqlparametercollection-item18202263 Node: connector-net-ref-mysqlclient-mysqlparametercollection-item28203208 Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overloads8204103 Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-28207628 Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-18208999 Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-48210419 Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-58211909 Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-68213505 Node: connector-net-ref-mysqlclient-mysqlparametercollection-add-overload-38215243 Node: connector-net-ref-mysqlclient-mysqlparametercollection-clear8216744 Node: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overloads8217551 Node: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overload-18218983 Node: connector-net-ref-mysqlclient-mysqlparametercollection-contains-overload-28220379 Node: connector-net-ref-mysqlclient-mysqlparametercollection-copyto8221749 Node: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overloads8222782 Node: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overload-18224203 Node: connector-net-ref-mysqlclient-mysqlparametercollection-indexof-overload-28225601 Node: connector-net-ref-mysqlclient-mysqlparametercollection-insert8227027 Node: connector-net-ref-mysqlclient-mysqlparametercollection-remove8228021 Node: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overloads8228941 Node: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overload-18230320 Node: connector-net-ref-mysqlclient-mysqlparametercollection-removeat-overload-28231544 Node: connector-net-ref-mysqlclient-mysqlcommand-transaction8232796 Node: connector-net-ref-mysqlclient-mysqlcommand-updatedrowsource8233431 Node: connector-net-ref-mysqlclient-mysqlcommand-cancel8234205 Node: connector-net-ref-mysqlclient-mysqlcommand-createparameter8235258 Node: connector-net-ref-mysqlclient-mysqlcommand-executenonquery8236196 Node: connector-net-ref-mysqlclient-mysqlcommand-executereader-overloads8236971 Node: connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-18237988 Node: connector-net-ref-mysqlclient-mysqldatareader8238910 Node: connector-net-ref-mysqlclient-mysqldatareadermembers8240326 Node: connector-net-ref-mysqlclient-mysqldatareader-depth8251302 Node: connector-net-ref-mysqlclient-mysqldatareader-fieldcount8252118 Node: connector-net-ref-mysqlclient-mysqldatareader-hasrows8252885 Node: connector-net-ref-mysqlclient-mysqldatareader-isclosed8253573 Node: connector-net-ref-mysqlclient-mysqldatareaderitem8254337 Node: connector-net-ref-mysqlclient-mysqldatareader-item18255587 Node: connector-net-ref-mysqlclient-mysqldatareader-item28256617 Node: connector-net-ref-mysqlclient-mysqldatareader-recordsaffected8257588 Node: connector-net-ref-mysqlclient-mysqldatareader-close8258428 Node: connector-net-ref-mysqlclient-mysqldatareader-getboolean8259167 Node: connector-net-ref-mysqlclient-mysqldatareader-getbyte8260056 Node: connector-net-ref-mysqlclient-mysqldatareader-getbytes8260924 Node: connector-net-ref-mysqlclient-mysqldatareader-getchar8262438 Node: connector-net-ref-mysqlclient-mysqldatareader-getchars8263316 Node: connector-net-ref-mysqlclient-mysqldatareader-getdatatypename8264573 Node: connector-net-ref-mysqlclient-mysqldatareader-getdatetime8265491 Node: connector-net-ref-mysqlclient-mysqldatareader-getdecimal8266314 Node: connector-net-ref-mysqlclient-mysqldatareader-getdouble8267127 Node: connector-net-ref-mysqlclient-mysqldatareader-getfieldtype8267933 Node: connector-net-ref-mysqlclient-mysqldatareader-getfloat8268836 Node: connector-net-ref-mysqlclient-mysqldatareader-getguid8269631 Node: connector-net-ref-mysqlclient-mysqldatareader-getint168270413 Node: connector-net-ref-mysqlclient-mysqldatareader-getint328271203 Node: connector-net-ref-mysqlclient-mysqldatareader-getint648271994 Node: connector-net-ref-mysqlclient-mysqldatareader-getmysqldatetime8272791 Node: connector-net-ref-mysqlclient-mysqldatareader-getname8273538 Node: connector-net-ref-mysqlclient-mysqldatareader-getordinal8274407 Node: connector-net-ref-mysqlclient-mysqldatareader-getschematable8275317 Node: connector-net-ref-mysqlclient-mysqldatareader-getstring8276196 Node: connector-net-ref-mysqlclient-mysqldatareader-gettimespan8277005 Node: connector-net-ref-mysqlclient-mysqldatareader-getuint168277720 Node: connector-net-ref-mysqlclient-mysqldatareader-getuint328278423 Node: connector-net-ref-mysqlclient-mysqldatareader-getuint648279122 Node: connector-net-ref-mysqlclient-mysqldatareader-getvalue8279821 Node: connector-net-ref-mysqlclient-mysqldatareader-getvalues8280711 Node: connector-net-ref-mysqlclient-mysqldatareader-isdbnull8281630 Node: connector-net-ref-mysqlclient-mysqldatareader-nextresult8282543 Node: connector-net-ref-mysqlclient-mysqldatareader-read8283396 Node: connector-net-ref-mysqlclient-mysqlcommand-executereader-overload-28284104 Node: connector-net-ref-mysqlclient-mysqlcommand-executescalar8284953 Node: connector-net-ref-mysqlclient-mysqlcommand-prepare8285708 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder8286335 Node: connector-net-ref-mysqlclient-mysqlcommandbuildermembers8287531 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overloads8293077 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overload-18294722 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-deriveparameters-overload-28296466 Node: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor8297430 Node: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor18299156 Node: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor38300055 Node: connector-net-ref-mysqlclient-mysqldataadapter8301008 Node: connector-net-ref-mysqlclient-mysqldataadaptermembers8302177 Node: connector-net-ref-mysqlclient-mysqldataadapterconstructor8311192 Node: connector-net-ref-mysqlclient-mysqldataadapterconstructor18312824 Node: connector-net-ref-mysqlclient-mysqldataadapterconstructor28313684 Node: connector-net-ref-mysqlclient-mysqldataadapterconstructor38314521 Node: connector-net-ref-mysqlclient-mysqldataadapterconstructor48315433 Node: connector-net-ref-mysqlclient-mysqldataadapter-deletecommand18316272 Node: connector-net-ref-mysqlclient-mysqldataadapter-insertcommand18316946 Node: connector-net-ref-mysqlclient-mysqldataadapter-selectcommand18317624 Node: connector-net-ref-mysqlclient-mysqldataadapter-updatecommand18318302 Node: connector-net-ref-mysqlclient-mysqldataadapter-rowupdated8318976 Node: connector-net-ref-mysqlclient-mysqlrowupdatedeventhandler8321491 Node: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs8322559 Node: connector-net-ref-mysqlclient-mysqlrowupdatedeventargsmembers8323893 Node: connector-net-ref-mysqlclient-mysqlrowupdatedeventargsconstructor8327345 Node: connector-net-ref-mysqlclient-mysqlrowupdatedeventargs-command18328683 Node: connector-net-ref-mysqlclient-mysqldataadapter-rowupdating8329364 Node: connector-net-ref-mysqlclient-mysqlrowupdatingeventhandler8331600 Node: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs8332680 Node: connector-net-ref-mysqlclient-mysqlrowupdatingeventargsmembers8334030 Node: connector-net-ref-mysqlclient-mysqlrowupdatingeventargsconstructor8337090 Node: connector-net-ref-mysqlclient-mysqlrowupdatingeventargs-command18338417 Node: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor48339106 Node: connector-net-ref-mysqlclient-mysqlcommandbuilderconstructor28340034 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-dataadapter8340817 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-quoteprefix8341489 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-quotesuffix8342142 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-getdeletecommand8342800 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-getinsertcommand8343528 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-getupdatecommand8344261 Node: connector-net-ref-mysqlclient-mysqlcommandbuilder-refreshschema8344991 Node: connector-net-ref-mysqlclient-mysqlexception8345605 Node: connector-net-ref-mysqlclient-mysqlexceptionmembers8346853 Node: connector-net-ref-mysqlclient-mysqlexception-number8350421 Node: connector-net-ref-mysqlclient-mysqlhelper8351001 Node: connector-net-ref-mysqlclient-mysqlhelpermembers8352134 Node: connector-net-ref-mysqlclient-mysqlhelper-executedatarow8355845 Node: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overloads8357132 Node: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-38359644 Node: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-48361064 Node: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-18362656 Node: connector-net-ref-mysqlclient-mysqlhelper-executedataset-overload-28363961 Node: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overloads8365361 Node: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overload-18367104 Node: connector-net-ref-mysqlclient-mysqlhelper-executenonquery-overload-28368768 Node: connector-net-ref-mysqlclient-mysqlhelper-executereader-overloads8370361 Node: connector-net-ref-mysqlclient-mysqlhelper-executereader-overload-18371570 Node: connector-net-ref-mysqlclient-mysqlhelper-executereader-overload-28372861 Node: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overloads8374335 Node: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-38376121 Node: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-48377449 Node: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-18378949 Node: connector-net-ref-mysqlclient-mysqlhelper-executescalar-overload-28380218 Node: connector-net-ref-mysqlclient-mysqlhelper-updatedataset8381585 Node: connector-net-ref-mysqlclient-mysqlerrorcode8382722 Node: connector-net-ref-types8383731 Node: connector-net-ref-typeshierarchy8384650 Node: connector-net-ref-types-mysqlconversionexception8384982 Node: connector-net-ref-types-mysqlconversionexceptionmembers8386213 Node: connector-net-ref-types-mysqlconversionexceptionconstructor8390595 Node: connector-net-ref-types-mysqldatetime8391232 Node: connector-net-ref-types-mysqldatetimemembers8392656 Node: connector-net-ref-types-mysqldatetime-op-explicit8398198 Node: connector-net-ref-types-mysqldatetime-day8398920 Node: connector-net-ref-types-mysqldatetime-hour8399488 Node: connector-net-ref-types-mysqlvalue-isnull8400053 Node: connector-net-ref-types-mysqlvalue8400659 Node: connector-net-ref-types-mysqlvaluemembers8401626 Node: connector-net-ref-types-mysqlvalue-numberformat8405653 Node: connector-net-ref-types-mysqlvalueconstructor8406249 Node: connector-net-ref-types-mysqlvalue-valueasobject8406875 Node: connector-net-ref-types-mysqlvalue-tostring8407488 Node: connector-net-ref-types-mysqlvalue-classtype8408111 Node: connector-net-ref-types-mysqlvalue-dbtype8408695 Node: connector-net-ref-types-mysqlvalue-mysqldbtype8409265 Node: connector-net-ref-types-mysqlvalue-mysqltypename8409863 Node: connector-net-ref-types-mysqlvalue-objectvalue8410479 Node: connector-net-ref-types-mysqldatetime-isvaliddatetime8410989 Node: connector-net-ref-types-mysqldatetime-millisecond8411660 Node: connector-net-ref-types-mysqldatetime-minute8412282 Node: connector-net-ref-types-mysqldatetime-month8412869 Node: connector-net-ref-types-mysqldatetime-second8413446 Node: connector-net-ref-types-mysqldatetime-year8414026 Node: connector-net-ref-types-mysqldatetime-getdatetime8414602 Node: connector-net-ref-types-mysqldatetime-tostring8415222 Node: connector-net-ref-mysqlclient-memcached-client8415826 Node: connector-net-ref-mysqlclient-memcached-clientmembers8416951 Node: connector-net-ref-mysqlclient-memcached-client-server8422338 Node: connector-net-ref-mysqlclient-memcached-client-port8423064 Node: connector-net-ref-mysqlclient-memcached-client-stream8423792 Node: connector-net-ref-mysqlclient-memcached-client-open8424404 Node: connector-net-ref-mysqlclient-memcached-client-close8425118 Node: connector-net-ref-mysqlclient-memcached-client-add8425834 Node: connector-net-ref-mysqlclient-memcached-client-append8426859 Node: connector-net-ref-mysqlclient-memcached-client-cas8427769 Node: connector-net-ref-mysqlclient-memcached-client-decrement8428873 Node: connector-net-ref-mysqlclient-memcached-client-delete8429797 Node: connector-net-ref-mysqlclient-memcached-client-flushall8430606 Node: connector-net-ref-mysqlclient-memcached-client-get8431507 Node: connector-net-ref-mysqlclient-memcached-client-increment8432462 Node: connector-net-ref-mysqlclient-memcached-client-prepend8433387 Node: connector-net-ref-mysqlclient-memcached-client-close-replace8434319 Node: connector-net-ref-mysqlclient-memcached-client-set8435395 Node: connector-net-ref-mysqlclient-memcached-client-getinstance8436407 Node: connector-net-ref-mysqlclient-memcached-binaryclient8437598 Node: connector-net-ref-mysqlclient-memcached-binaryclientmembers8438787 Node: connector-net-ref-mysqlclient-memcached-textclient8441561 Node: connector-net-ref-mysqlclient-memcached-textclientmembers8442717 Node: connector-net-ref-replication8445473 Node: connector-net-ref-replication-replicationmanager8447038 Node: connector-net-ref-replication-replicationmanagermembers8448041 Node: connector-net-ref-replication-replicationmanager-addgroup8450428 Node: connector-net-ref-replication-replicationmanager-addgroup18451506 Node: connector-net-ref-replication-replicationmanager-addgroup28452863 Node: connector-net-ref-replication-replicationmanager-getgroup8454303 Node: connector-net-ref-replication-replicationmanager-getnewconnection8455397 Node: connector-net-ref-replication-replicationmanager-getserver8456771 Node: connector-net-ref-replication-replicationmanager-isreplicationgroup8458033 Node: connector-net-ref-replication-replicationmanager-groups8459115 Node: connector-net-ref-replication-replicationroundrobinservergroup8460087 Node: connector-net-ref-replication-replicationroundrobinservergroupmembers8461305 Node: connector-net-ref-replication-replicationroundrobinservergroup-constructor8465642 Node: connector-net-ref-replication-replicationroundrobinservergroup-getserver8466931 Node: connector-net-ref-replication-replicationroundrobinservergroup-getserver18467956 Node: connector-net-ref-replication-replicationserver8469388 Node: connector-net-ref-replication-replicationservermembers8470365 Node: connector-net-ref-replication-replicationserver-constructor8473342 Node: connector-net-ref-replication-replicationserver-connectionstring8474643 Node: connector-net-ref-replication-replicationserver-isavailable8475597 Node: connector-net-ref-replication-replicationserver-ismaster8476510 Node: connector-net-ref-replication-replicationserver-name8477399 Node: connector-net-ref-replication-replicationservergroup8478174 Node: connector-net-ref-replication-replicationservergroupmembers8479212 Node: connector-net-ref-replication-replicationservergroup-constructor8482912 Node: connector-net-ref-replication-replicationservergroup-addserver8484076 Node: connector-net-ref-replication-replicationservergroup-getserver8485393 Node: connector-net-ref-replication-replicationservergroup-getserver18486511 Node: connector-net-ref-replication-replicationservergroup-getserver28487846 Node: connector-net-ref-replication-replicationservergroup-removeserver8488951 Node: connector-net-ref-replication-replicationservergroup-name8489878 Node: connector-net-ref-replication-replicationservergroup-retrytime8490763 Node: connector-net-ref-replication-replicationservergroup-servers8491692 Node: connector-net-support8492632 Node: connector-net-support-community8493258 Node: connector-net-support-bug-report8493854 Node: connector-net-faq8494932 Ref: qandaitem-22-2-11-1-18495192 Node: connector-j8498534 Node: connector-j-overview8500211 Node: connector-j-versions8501401 Node: connector-j-change-history8504229 Node: connector-j-versions-java8504649 Node: connector-j-installing8506710 Node: connector-j-binary-installation8507883 Node: connector-j-installing-classpath8509731 Node: connector-j-installing-upgrading8512871 Node: connector-j-installing-upgrading-5-18513741 Node: connector-j-installing-upgrading-issues8515028 Node: connector-j-installing-upgrading-3-0-to-3-18516491 Node: connector-j-installing-source8521450 Node: connector-j-examples8525360 Node: connector-j-reference8526348 Node: connector-j-reference-configuration-properties8527340 Node: connector-j-useconfigs8616784 Node: connector-j-reference-implementation-notes8619644 Node: connector-j-reference-type-conversions8630213 Node: connector-j-reference-charsets8636763 Node: connector-j-reference-using-ssl8640709 Node: connector-j-using-pam8649102 Node: connector-j-reference-replication-connection8650763 Node: connector-j-reference-error-sqlstates8654658 Node: connector-j-usagenotes-basic8664068 Node: connector-j-usagenotes-connect-drivermanager8664747 Ref: connector-j-examples-connection-drivermanager8666789 Node: connector-j-usagenotes-statements8668039 Ref: connector-j-examples-execute-select8669785 Node: connector-j-usagenotes-statements-callable8671275 Ref: connector-j-examples-stored-procedure8672435 Ref: connector-j-examples-preparecall8673015 Ref: connector-j-examples-output-param8674094 Ref: connector-j-examples-callablestatement8675386 Ref: connector-j-examples-retrieving-results-params8676408 Node: connector-j-usagenotes-last-insert-id8677131 Ref: connector-j-examples-autoincrement-getgeneratedkeys8678554 Ref: connector-j-examples-autoincrement-select8680587 Ref: connector-j-examples-autoincrement-updateable-resultsets8682395 Node: connector-j-usagenotes-j2ee-concepts-connection-pooling8684926 Ref: connector-j-examples-connectionpool-j2ee8688020 Node: connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections8696184 Node: connector-j-usagenotes-j2ee-concepts-load-balancing-failover8702323 Node: connector-j-interceptors8708397 Node: connector-j-usagenotes-tomcat8710593 Node: connector-j-usagenotes-jboss8714561 Node: connector-j-usagenotes-spring-config8716145 Node: connector-j-usagenotes-spring-config-jdbctemplate8721355 Node: connector-j-usagenotes-spring-config-transactional8724902 Node: connector-j-usagenotes-spring-config-connpooling8729489 Node: connector-j-usagenotes-glassfish-config8731910 Node: connector-j-usagenotes-glassfish-config-jsp8736409 Node: connector-j-usagenotes-glassfish-config-servlet8742008 Node: connector-j-usagenotes-troubleshooting8747787 Ref: qandaitem-22-3-15-1-18751985 Ref: qandaitem-22-3-15-1-28753316 Ref: qandaitem-22-3-15-1-38753811 Ref: qandaitem-22-3-15-1-48755651 Ref: connector-j-examples-transaction-retry8756506 Ref: qandaitem-22-3-15-1-58761194 Ref: qandaitem-22-3-15-1-68762194 Ref: qandaitem-22-3-15-1-78762671 Ref: qandaitem-22-3-15-1-88763978 Ref: qandaitem-22-3-15-1-98764825 Ref: qandaitem-22-3-15-1-108765235 Ref: qandaitem-22-3-15-1-118766310 Ref: qandaitem-22-3-15-1-128766630 Ref: qandaitem-22-3-15-1-138769070 Ref: qandaitem-22-3-15-1-148772425 Ref: qandaitem-22-3-15-1-158772607 Ref: qandaitem-22-3-15-1-168772954 Node: connector-j-usagenotes-known-issues-limitations8773555 Node: connector-j-support8774299 Node: connector-j-support-community8774633 Node: connector-j-support-bug-report8775547 Node: connector-cpp8780559 Node: connector-cpp-downloading8784482 Node: connector-cpp-installation-binary8785566 Ref: connector-cpp-installer-welcome-figure8789269 Ref: connector-cpp-installer-overview-figure8789615 Ref: connector-cpp-installer-custom-figure8789833 Node: connector-cpp-installation-source8789886 Node: connector-cpp-installation-source-unix8791749 Node: connector-cpp-installation-source-windows8797448 Node: connector-cpp-dynamic-linking-client-library8803744 Node: connector-cpp-apps-windows-visual-studio8806071 Ref: connector-cpp-menu-new-project8807742 Ref: connector-cpp-new-project-wizard8808046 Ref: connector-cpp-win32-application-wizard8808347 Ref: connector-cpp-select-release-build8808517 Ref: connector-cpp-menu-project-properties8808689 Ref: connector-cpp-properties8808869 Ref: connector-cpp-mysql-include-dir8809092 Ref: connector-cpp-mysql-include-select-directory-dialog8809239 Ref: connector-cpp-mysql-lib-opt-dir8809516 Ref: connector-cpp-additional-library-dir8809673 Ref: connector-cpp-additional-lib-dir-select8809884 Ref: connector-cpp-application-build-static8809946 Ref: connector-cpp-additional-dependencies8810345 Ref: connector-cpp-additional-dependencies-added8810451 Ref: connector-cpp-cppconn-public-func8811067 Ref: connector-cpp-application-build-dynamic8811271 Node: connector-cpp-apps-linux-netbeans8812022 Ref: connector-cpp-netbeans8812444 Ref: connector-cpp-netbeans-static-properties-include8814291 Ref: connector-cpp-netbeans-static-properties-lib8815947 Ref: connector-cpp-netbeans-dynamic-properties-lib8816878 Ref: connector-cpp-netbeans-static-run8817317 Node: connector-cpp-getting-started-examples8817574 Node: connector-cpp-examples-connecting8821044 Node: connector-cpp-examples-query8821995 Node: connector-cpp-examples-results8823228 Node: connector-cpp-examples-prepared-statements8824742 Node: connector-cpp-examples-complete-example-18826039 Node: connector-cpp-examples-complete-example-28829325 Node: connector-cpp-tutorials8832922 Node: connector-cpp-tutorials-background8833635 Node: connector-cpp-tutorials-stored-routines-statements8837458 Node: connector-cpp-tutorials-stored-routines-prepared-statements8848878 Node: connector-cpp-debug-tracing8856599 Node: connector-cpp-usage-notes8860995 Node: connector-cpp-bugs8873514 Node: connector-cpp-support8875592 Node: connector-c8876322 Node: connector-c-versions8877964 Node: connector-c-platforms8880604 Node: connector-c-contents8881607 Node: connector-c-installation8884689 Node: connector-c-installation-binary8885912 Node: connector-c-installation-source8889603 Ref: connector-c-building-unix8891137 Ref: connector-c-building-windows8892425 Ref: connector-c-build-options8894856 Node: connector-c-postinstallation8895554 Node: connector-c-testing8896437 Node: connector-c-applications8897731 Node: connector-python8898592 Node: connector-python-coding8900931 Node: connector-python-versions8909149 Node: connector-python-installation8910834 Node: connector-python-installation-binary8912843 Node: connector-python-installation-source-unix8915046 Node: connector-python-installation-source-windows8916744 Node: connector-python-verification8918576 Node: connector-python-examples8919117 Node: connector-python-example-connecting8919825 Node: connector-python-example-ddl8921945 Node: connector-python-example-cursor-transaction8929818 Node: connector-python-example-cursor-select8933790 Node: connector-python-tutorials8937018 Node: connector-python-tutorial-cursorbuffered8937497 Node: connector-python-connectargs8939760 Node: connector-python-other8950309 Node: connector-python-connection-pooling8950892 Node: connector-python-django-backend8956095 Node: connector-python-reference8958805 Node: connector-python-api-mysql-connector8960705 Node: connector-python-api-mysql-connector-connect8961582 Node: connector-python-api-mysql-connector-apilevel8962514 Node: connector-python-api-mysql-connector-paramstyle8962949 Node: connector-python-api-mysql-connector-threadsafety8963418 Node: connector-python-api-mysql-connector-version8963906 Node: connector-python-api-mysql-connector-version-info8964401 Node: connector-python-api-mysqlconnection8964885 Node: connector-python-api-mysqlconnection-constructor8969769 Node: connector-python-api-mysqlconnection-close8970329 Node: connector-python-api-mysqlconnection-commit8970995 Node: connector-python-api-mysqlconnection-config8971824 Node: connector-python-api-mysqlconnection-connect8972809 Node: connector-python-api-mysqlconnection-cursor8973753 Node: connector-python-api-mysqlconnection-cmd-change-user8975090 Node: connector-python-api-mysqlconnection-cmd-debug8975798 Node: connector-python-api-mysqlconnection-cmd-init-db8976313 Node: connector-python-api-mysqlconnection-cmd-ping8976906 Node: connector-python-api-mysqlconnection-cmd-process-info8977542 Node: connector-python-api-mysqlconnection-cmd-process-kill8978056 Node: connector-python-api-mysqlconnection-cmd-query8978739 Node: connector-python-api-mysqlconnection-cmd-query-iter8979729 Node: connector-python-api-mysqlconnection-cmd-quit8980743 Node: connector-python-api-mysqlconnection-cmd-refresh8981248 Node: connector-python-api-mysqlconnection-cmd-shutdown8982078 Node: connector-python-api-mysqlconnection-cmd-statistics8982573 Node: connector-python-api-mysqlconnection-disconnect8983084 Node: connector-python-api-mysqlconnection-get-row8983584 Node: connector-python-api-mysqlconnection-get-rows8984384 Node: connector-python-api-mysqlconnection-get-server-info8985451 Node: connector-python-api-mysqlconnection-get-server-version8985931 Node: connector-python-api-mysqlconnection-is-connected8986379 Node: connector-python-api-mysqlconnection-isset-client-flag8987038 Node: connector-python-api-mysqlconnection-ping8987467 Node: connector-python-api-mysqlconnection-reconnect8988350 Node: connector-python-api-mysqlconnection-rollback8989091 Node: connector-python-api-mysqlconnection-set-charset-collation8989973 Node: connector-python-api-mysqlconnection-set-client-flags8991084 Node: connector-python-api-mysqlconnection-start-transaction8992208 Node: connector-python-api-mysqlconnection-autocommit8993556 Node: connector-python-api-mysqlconnection-charset-name8994563 Node: connector-python-api-mysqlconnection-collation-name8995025 Node: connector-python-api-mysqlconnection-connection-id8995490 Node: connector-python-api-mysqlconnection-database8995962 Node: connector-python-api-mysqlconnection-get-warnings8996562 Node: connector-python-api-mysqlconnection-in-transaction8997583 Node: connector-python-api-mysqlconnection-raise-on-warnings8998514 Node: connector-python-api-mysqlconnection-server-host8999911 Node: connector-python-api-mysqlconnection-server-port9000372 Node: connector-python-api-mysqlconnection-sql-mode9000814 Node: connector-python-api-mysqlconnection-time-zone9001927 Node: connector-python-api-mysqlconnection-unix-socket9002689 Node: connector-python-api-mysqlconnection-user9003123 Node: connector-python-api-mysqlconnectionpool9003486 Node: connector-python-api-mysqlconnectionpool-constructor9004377 Node: connector-python-api-mysqlconnectionpool-add-connection9005864 Node: connector-python-api-mysqlconnectionpool-get-connection9006701 Node: connector-python-api-mysqlconnectionpool-set-config9007263 Node: connector-python-api-mysqlconnectionpool-pool-name9008263 Node: connector-python-api-pooledmysqlconnection9008676 Node: connector-python-api-pooledmysqlconnection-constructor9010345 Node: connector-python-api-pooledmysqlconnection-close9011080 Node: connector-python-api-pooledmysqlconnection-config9011858 Node: connector-python-api-pooledmysqlconnection-pool-name9012359 Node: connector-python-api-mysqlcursor9012845 Node: connector-python-api-mysqlcursor-constructor9014940 Node: connector-python-api-mysqlcursor-callproc9015555 Node: connector-python-api-mysqlcursor-close9016945 Node: connector-python-api-mysqlcursor-execute9017428 Node: connector-python-api-mysqlcursor-executemany9019698 Node: connector-python-api-mysqlcursor-fetchall9021030 Node: connector-python-api-mysqlcursor-fetchmany9021852 Node: connector-python-api-mysqlcursor-fetchone9022608 Node: connector-python-api-mysqlcursor-fetchwarnings9023900 Node: connector-python-api-mysqlcursor-stored-results9024894 Node: connector-python-api-mysqlcursor-column-names9025821 Node: connector-python-api-mysqlcursor-description9026594 Node: connector-python-api-mysqlcursor-lastrowid9028293 Node: connector-python-api-mysqlcursor-statement9028912 Node: connector-python-api-mysqlcursor-with-rows9029478 Node: connector-python-api-mysqlcursorbuffered9030510 Node: connector-python-api-mysqlcursorprepared9031699 Node: connector-python-api-clientflag9034710 Node: connector-python-api-fieldtype9035461 Node: connector-python-api-sqlmode9036671 Node: connector-python-api-characterset9037206 Node: connector-python-api-refreshoption9037684 Node: connector-python-api-errors9038877 Node: connector-python-api-errorcode9042540 Node: connector-python-api-errors-error9043155 Node: connector-python-api-errors-dataerror9045911 Node: connector-python-api-errors-databaseerror9046473 Node: connector-python-api-errors-integrityerror9046911 Node: connector-python-api-errors-interfaceerror9047791 Node: connector-python-api-errors-internalerror9048257 Node: connector-python-api-errors-notsupportederror9048736 Node: connector-python-api-errors-operationalerror9049332 Node: connector-python-api-errors-poolerror9049911 Node: connector-python-api-errors-programmingerror9050303 Node: connector-python-api-errors-warning9051119 Node: connector-python-api-errors-custom-error-exception9051890 Node: libmysqld9053071 Ref: refman-apis-libmysqld-mysql-server-library-embeded-functions9054205 Node: libmysqld-compiling9055896 Node: libmysqld-restrictions9058249 Node: libmysqld-options9059394 Node: libmysqld-example9060701 Node: c-api9067818 Node: c-api-implementations9072485 Node: c-api-multiple-installations9075762 Node: c-api-example-programs9079162 Node: c-api-building-running-clients9079736 Node: c-api-building-clients9080381 Node: c-api-threaded-clients9086067 Node: c-api-running-clients9090136 Node: c-api-data-structures9092799 Node: c-api-function-overview9107744 Node: c-api-functions9127506 Node: mysql-affected-rows9132783 Node: mysql-autocommit9135598 Node: mysql-change-user9136004 Node: mysql-character-set-name9138437 Node: mysql-close9138845 Node: mysql-commit9139369 Node: mysql-connect9140065 Node: mysql-create-db9141513 Node: mysql-data-seek9142560 Node: mysql-debug9143317 Node: mysql-drop-db9143977 Node: mysql-dump-debug-info9144995 Node: mysql-eof9145755 Node: mysql-errno9148803 Node: mysql-error9150357 Node: mysql-escape-string9151684 Node: mysql-fetch-field9152363 Node: mysql-fetch-field-direct9154088 Node: mysql-fetch-fields9155093 Node: mysql-fetch-lengths9155902 Node: mysql-fetch-row9157631 Node: mysql-field-count9159763 Node: mysql-field-seek9162144 Node: mysql-field-tell9162758 Node: mysql-free-result9163289 Node: mysql-get-character-set-info9163979 Node: mysql-get-client-info9165191 Node: mysql-get-client-version9165637 Node: mysql-get-host-info9166309 Node: mysql-get-proto-info9166786 Node: mysql-get-server-info9167238 Node: mysql-get-server-version9167676 Node: mysql-get-ssl-cipher9168352 Node: mysql-hex-string9168982 Node: mysql-info9170918 Node: mysql-init9172461 Node: mysql-insert-id9173283 Node: mysql-kill9178747 Node: mysql-library-end9179552 Node: mysql-library-init9180551 Node: mysql-list-dbs9184595 Node: mysql-list-fields9185738 Node: mysql-list-processes9187492 Node: mysql-list-tables9188447 Node: mysql-more-results9189566 Node: mysql-next-result9190564 Node: mysql-num-fields9193893 Node: mysql-num-rows9196355 Node: mysql-options9197582 Node: mysql-ping9209564 Node: mysql-query9211390 Node: mysql-real-connect9212840 Node: mysql-real-escape-string9224928 Node: mysql-real-query9227989 Node: mysql-refresh9229665 Node: mysql-reload9231436 Node: mysql-rollback9232286 Node: mysql-row-seek9232997 Node: mysql-row-tell9234076 Node: mysql-select-db9234748 Node: mysql-set-character-set9235759 Node: mysql-set-local-infile-default9236973 Node: mysql-set-local-infile-handler9237657 Node: mysql-set-server-option9241505 Node: mysql-shutdown9243673 Node: mysql-sqlstate9244903 Node: mysql-ssl-set9246600 Node: mysql-stat9247900 Node: mysql-store-result9248759 Node: mysql-thread-id9252493 Node: mysql-use-result9253470 Node: mysql-warning-count9257061 Node: c-api-prepared-statements9257460 Node: c-api-prepared-statement-data-structures9259275 Node: c-api-prepared-statement-type-codes9272876 Node: c-api-prepared-statement-type-conversions9280129 Node: c-api-prepared-statement-function-overview9285595 Node: c-api-prepared-statement-functions9296422 Node: mysql-stmt-affected-rows9298556 Node: mysql-stmt-attr-get9299337 Node: mysql-stmt-attr-set9300305 Node: mysql-stmt-bind-param9304126 Node: mysql-stmt-bind-result9305698 Node: mysql-stmt-close9308237 Node: mysql-stmt-data-seek9309063 Node: mysql-stmt-errno9309864 Node: mysql-stmt-error9310652 Node: mysql-stmt-execute9311715 Node: mysql-stmt-fetch9320074 Node: mysql-stmt-fetch-column9331822 Node: mysql-stmt-field-count9332880 Node: mysql-stmt-free-result9333683 Node: mysql-stmt-init9334297 Node: mysql-stmt-insert-id9334932 Node: mysql-stmt-num-rows9335846 Node: mysql-stmt-param-count9337063 Node: mysql-stmt-param-metadata9337625 Node: mysql-stmt-prepare9338007 Node: mysql-stmt-reset9340427 Node: mysql-stmt-result-metadata9341583 Node: mysql-stmt-row-seek9343664 Node: mysql-stmt-row-tell9344824 Node: mysql-stmt-send-long-data9345538 Node: mysql-stmt-sqlstate9349818 Node: mysql-stmt-store-result9350765 Node: c-api-thread-functions9353780 Node: my-init9354363 Node: mysql-thread-end9355498 Node: mysql-thread-init9356048 Node: mysql-thread-safe9356958 Node: c-api-embedded-server-functions9357335 Node: mysql-server-init9358326 Node: mysql-server-end9358981 Node: c-api-problems9359506 Node: null-mysql-store-result9360032 Node: query-results9361582 Node: getting-unique-id9363351 Node: auto-reconnect9366498 Node: c-api-multiple-queries9369585 Node: c-api-prepared-statement-problems9377470 Node: c-api-prepared-statement-date-handling9379097 Node: c-api-prepared-call-statements9382656 Node: apis-php9383285 Ref: php-api-copyright9386061 Node: apis-php-mysqlinfo9386511 Node: apis-php-mysqlinfo.intro9387025 Node: apis-php-mysqlinfo.terminology9387584 Node: apis-php-mysqlinfo.api.choosing9391305 Node: apis-php-mysqlinfo.library.choosing9395886 Node: apis-php-mysqlinfo.concepts9399889 Node: apis-php-mysqlinfo.concepts.buffering9400302 Node: apis-php-mysqlinfo.concepts.charset9403409 Node: apis-php-book.mysqlnd-ms9405869 Node: apis-php-mysqlnd-ms.key-features9407830 Node: apis-php-mysqlnd-ms.limitations9411569 Node: apis-php-mysqlnd-ms.name9413229 Node: apis-php-mysqlnd-ms.quickstart9413695 Node: apis-php-mysqlnd-ms.quickstart.configuration9415479 Node: apis-php-mysqlnd-ms.quickstart.usage9420953 Node: apis-php-mysqlnd-ms.quickstart.connectionpooling9425359 Node: apis-php-mysqlnd-ms.quickstart.sqlhints9428862 Node: apis-php-mysqlnd-ms.quickstart.transactions9434128 Node: apis-php-mysqlnd-ms.quickstart.qos-consistency9440279 Node: apis-php-mysqlnd-ms.quickstart.gtid9449549 Node: apis-php-mysqlnd-ms.quickstart.cache9463932 Node: apis-php-mysqlnd-ms.quickstart.failover9471022 Node: apis-php-mysqlnd-ms.quickstart.partitioning9473781 Node: apis-php-mysqlnd-ms.concepts9478200 Node: apis-php-mysqlnd-ms.architecture9479477 Node: apis-php-mysqlnd-ms.pooling9481712 Node: apis-php-mysqlnd-ms.transaction9489615 Node: apis-php-mysqlnd-ms.errorhandling9492655 Node: apis-php-mysqlnd-ms.transient_errors9499762 Node: apis-php-mysqlnd-ms.failover9505324 Node: apis-php-mysqlnd-ms.loadbalancing9510257 Node: apis-php-mysqlnd-ms.rwsplit9511701 Node: apis-php-mysqlnd-ms.filter9513832 Node: apis-php-mysqlnd-ms.qos-consistency9519945 Node: apis-php-mysqlnd-ms.gtid9527555 Node: apis-php-mysqlnd-ms.concept_cache9533006 Node: apis-php-mysqlnd-ms.supportedclusters9539179 Node: apis-php-mysqlnd-ms.setup9547161 Node: apis-php-mysqlnd-ms.requirements9547910 Node: apis-php-mysqlnd-ms.installation9548667 Node: apis-php-mysqlnd-ms.configuration9549524 Ref: apis-php-ini.mysqlnd-ms.enable9550493 Ref: apis-php-ini.mysqlnd-ms.force-config-usage9550757 Ref: apis-php-ini.mysqlnd-ms.ini-file9551831 Ref: apis-php-ini.mysqlnd-ms.config-file9551987 Ref: apis-php-ini.mysqlnd-ms.collect-statistics9552129 Ref: apis-php-ini.mysqlnd-ms.multi-master9552431 Ref: apis-php-ini.mysqlnd-ms.disable-rw-split9552637 Node: apis-php-mysqlnd-ms.plugin-ini-json9553682 Ref: apis-php-mysqlnd-ms.plugin-ini-json.using-section9557297 Ref: apis-php-mysqlnd-ms.plugin-ini-json.server-list-syntax9559412 Ref: apis-php-mysqlnd-ms.plugin-ini-json.debug_config9563869 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.master9566156 Ref: apis-php-mysqlnd-ms.plugin-ini-json.server-config-keywords9567038 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.slave9568288 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.gtid9569463 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.filters9573422 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.filter-random9576171 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.filter-roundrobin9581243 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.filter-user9582592 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.filter-user-multi9592765 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.filter-node-groups9596102 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.filter-qos9601283 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.failover9607987 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.lazy-connections9613600 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.server-charset9615303 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.master-on-write9619220 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.trx-stickiness9620663 Ref: apis-php-ini.mysqlnd-ms-plugin-config-v2.transient_error9625871 Node: apis-php-mysqlnd-ms.plugin-ini-v19628775 Ref: apis-php-ini.mysqlnd-ms-plugin-config.master9632474 Ref: apis-php-ini.mysqlnd-ms-plugin-config.slave9633122 Ref: apis-php-ini.mysqlnd-ms-plugin-config.pick9633792 Ref: apis-php-ini.mysqlnd-ms-plugin-config.failover9634992 Ref: apis-php-ini.mysqlnd-ms-plugin-config.lazy-connections9635712 Ref: apis-php-ini.mysqlnd-ms-plugin-config.master-on-write9637167 Ref: apis-php-ini.mysqlnd-ms-plugin-config.trx-stickiness9637743 Node: apis-php-mysqlnd-ms.testing9639339 Node: apis-php-mysqlnd-ms.debugging9642035 Node: apis-php-mysqlnd-ms.monitoring9646717 Node: apis-php-mysqlnd-ms.constants9650513 Ref: apis-php-constant.mysqlnd-ms-master-switch9652856 Ref: apis-php-constant.mysqlnd-ms-slave-switch9652983 Ref: apis-php-constant.mysqlnd-ms-last-used-switch9653116 Ref: apis-php-constant.mysqlnd-ms-query-use-master9653432 Ref: apis-php-constant.mysqlnd-ms-query-use-slave9653738 Ref: apis-php-constant.mysqlnd-ms-query-use-last-used9654041 Ref: apis-php-constant.mysqlnd-ms-qos-consistency-eventual9654459 Ref: apis-php-constant.mysqlnd-ms-qos-consistency-session9654985 Ref: apis-php-constant.mysqlnd-ms-qos-consistency-strong9655295 Ref: apis-php-constant.mysqlnd-ms-qos-option-gtid9655568 Ref: apis-php-constant.mysqlnd-ms-qos-option-age9655772 Ref: apis-php-constant.mysqlnd-ms-version9656542 Ref: apis-php-constant.mysqlnd-ms-version-id9656643 Node: apis-php-ref.mysqlnd-ms9656736 Node: apis-php-function.mysqlnd-ms-get-last-gtid9657556 Node: apis-php-function.mysqlnd-ms-get-last-used-connection9660425 Node: apis-php-function.mysqlnd-ms-get-stats9664982 Node: apis-php-function.mysqlnd-ms-match-wild9680986 Node: apis-php-function.mysqlnd-ms-query-is-select9683020 Node: apis-php-function.mysqlnd-ms-set-qos9686169 Node: apis-php-function.mysqlnd-ms-set-user-pick-server9692895 Node: apis-php-mysqlnd-ms.changes9699146 Node: apis-php-mysqlnd-ms.changes-one-six9700075 Node: apis-php-mysqlnd-ms.changes-one-five9701417 Node: apis-php-mysqlnd-ms.changes-one-four9707531 Node: apis-php-mysqlnd-ms.changes-one-three9710341 Node: apis-php-mysqlnd-ms.changes-one-two9712483 Node: apis-php-mysqlnd-ms.changes-one-one9714866 Node: apis-php-mysqlnd-ms.changes-one-o9718371 Node: apis-php-book.mysqlnd-qc9719319 Node: apis-php-mysqlnd-qc.key-features9720948 Node: apis-php-mysqlnd-qc.limitations9721721 Node: apis-php-mysqlnd-qc.name9722327 Node: apis-php-mysqlnd-qc.quickstart9722877 Node: apis-php-mysqlnd-qc.quickstart.concepts9724412 Node: apis-php-mysqlnd-qc.quickstart.configuration9729167 Node: apis-php-mysqlnd-qc.quickstart.caching9730244 Node: apis-php-mysqlnd-qc.per-query-ttl9739760 Node: apis-php-mysqlnd-qc.pattern-based-caching9744599 Node: apis-php-mysqlnd-qc.slam-defense9748627 Node: apis-php-mysqlnd-qc.cache-candidates9751339 Node: apis-php-mysqlnd-qc.cache-efficiency9755844 Node: apis-php-mysqlnd-qc.set-user-handlers9767647 Node: apis-php-mysqlnd-qc.setup9775159 Node: apis-php-mysqlnd-qc.requirements9775612 Node: apis-php-mysqlnd-qc.installation9776938 Node: apis-php-mysqlnd-qc.configuration9777795 Ref: apis-php-ini.mysqlnd-qc.enable-qc9779529 Ref: apis-php-ini.mysqlnd-qc.ttl9779795 Ref: apis-php-ini.mysqlnd-qc.cache-by-default9779887 Ref: apis-php-ini.mysqlnd-qc.cache-no-table9780134 Ref: apis-php-ini.mysqlnd-qc.use-request-time9780353 Ref: apis-php-ini.mysqlnd-qc.time-statistics9780684 Ref: apis-php-ini.mysqlnd-qc.collect-statistics9780901 Ref: apis-php-ini.mysqlnd-qc.collect-statistics-log-file9781275 Ref: apis-php-ini.mysqlnd-qc.collect-query-trace9781635 Ref: apis-php-ini.mysqlnd-qc.query-trace-bt-depth9781713 Ref: apis-php-ini.mysqlnd-qc.ignore-sql-comments9781812 Ref: apis-php-ini.mysqlnd-qc.slam-defense9782168 Ref: apis-php-ini.mysqlnd-qc.slam-defense-ttl9782383 Ref: apis-php-ini.mysqlnd-qc.collect-normalized-query-trace9782598 Ref: apis-php-ini.mysqlnd-qc.std-data-copy9782846 Ref: apis-php-ini.mysqlnd-qc.apc-prefix9782981 Ref: apis-php-ini.mysqlnd-qc.memc-server9783182 Ref: apis-php-ini.mysqlnd-qc.memc-port9783274 Ref: apis-php-ini.mysqlnd-qc.sqlite-data-file9783366 Node: apis-php-mysqlnd-qc.constants9783517 Ref: apis-php-constant.mysqlnd-qc-enable-switch9785195 Ref: apis-php-constant.mysqlnd-qc-disable-switch9785291 Ref: apis-php-constant.mysqlnd-qc-ttl-switch9785431 Ref: apis-php-constant.mysqlnd-qc-server-id9785526 Ref: apis-php-constant.mysqlnd-qc-condition-meta-schema-pattern9787768 Ref: apis-php-constant.mysqlnd-qc-version9788545 Ref: apis-php-constant.mysqlnd-qc-version-id9788646 Node: apis-php-ref.mysqlnd-qc9788735 Node: apis-php-function.mysqlnd-qc-clear-cache9789862 Node: apis-php-function.mysqlnd-qc-get-available-handlers9790935 Node: apis-php-function.mysqlnd-qc-get-cache-info9792904 Node: apis-php-function.mysqlnd-qc-get-core-stats9802879 Node: apis-php-function.mysqlnd-qc-get-normalized-query-trace-log9813883 Node: apis-php-function.mysqlnd-qc-get-query-trace-log9820480 Node: apis-php-function.mysqlnd-qc-set-cache-condition9827590 Node: apis-php-function.mysqlnd-qc-set-is-select9830519 Node: apis-php-function.mysqlnd-qc-set-storage-handler9834404 Node: apis-php-function.mysqlnd-qc-set-user-handlers9836664 Node: apis-php-mysqlnd-qc.changes9838626 Node: apis-php-mysqlnd-qc.changes-one-two9839279 Node: apis-php-mysqlnd-qc.changes-one-one9839910 Node: apis-php-mysqlnd-qc.changes-one-o9842889 Node: apis-php-book.mysqlnd-uh9843595 Node: apis-php-mysqlnd-uh.security9846139 Node: apis-php-mysqlnd-uh.docs-note9847092 Node: apis-php-mysqlnd-uh.name9847699 Node: apis-php-mysqlnd-uh.quickstart9848063 Node: apis-php-mysqlnd-uh.quickstart.configuration9850465 Node: apis-php-mysqlnd-uh.quickstart.how-it-works9851232 Node: apis-php-mysqlnd-uh.quickstart.proxy-installation9854437 Node: apis-php-mysqlnd-uh.quickstart.query-monitoring9859140 Node: apis-php-mysqlnd-uh.setup9861894 Node: apis-php-mysqlnd-uh.requirements9862395 Node: apis-php-mysqlnd-uh.installation9863472 Node: apis-php-mysqlnd-uh.configuration9864271 Ref: apis-php-ini.mysqlnd-uh.enable9864919 Ref: apis-php-ini.mysqlnd-uh.report-wrong-types9865189 Node: apis-php-mysqlnd-uh.resources9865377 Node: apis-php-mysqlnd-uh.constants9865658 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-sleep9866590 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-quit9866696 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-init-db9866800 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-query9866910 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-field-list9867016 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-create-db9867132 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-drop-db9867246 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-refresh9867356 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-shutdown9867466 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-statistics9867578 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-process-info9867694 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-connect9867814 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-process-kill9867924 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-debug9868044 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-ping9868150 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-time9868254 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-delayed-insert9868358 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-change-user9868482 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-binlog-dump9868600 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-table-dump9868718 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-connect-out9868834 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-register-slaved9868952 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-stmt-prepare9869078 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-stmt-execute9869198 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-stmt-send-long-data9869318 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-stmt-close9869452 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-stmt-reset9869568 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-set-option9869684 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-stmt-fetch9869800 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-daemon9869916 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-com-end9870024 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prot-greet-packet9870290 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prot-auth-packet9870402 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prot-ok-packet9870519 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prot-eof-packet9870622 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prot-cmd-packet9870727 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prot-rset-header-packet9870836 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prot-rset-fld-packet9870963 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prot-row-packet9871085 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prot-stats-packet9871190 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prepare-resp-packet9871299 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-chg-user-resp-packet9871421 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-prot-last9871548 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-close-explicit9871888 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-close-implicit9871999 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-close-disconnected9872120 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-close-last9872204 Ref: apis-php-constant.mysqlnd-uh-server-option-multi-statements-on9872509 Ref: apis-php-constant.mysqlnd-uh-server-option-multi-statements-off9872623 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-option-opt-connect-timeout9873010 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-option-opt-compress9873112 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-option-opt-named-pipe9873240 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-option-init-command9873361 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-read-default-file9873474 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-read-default-group9873595 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-set-charset-dir9873723 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-set-charset-name9873831 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-local-infile9873917 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-protocol9874036 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-shared-memory-base-name9874132 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-read-timeout9874266 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-write-timeout9874363 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-use-result9874462 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-use-remote-connection9874556 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-use-embedded-connection9874654 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-guess-connection9874754 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-set-client-ip9874827 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-secure-auth9874893 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-report-data-truncation9874957 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-reconnect9875070 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-ssl-verify-server-cert9875175 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-net-cmd-buffer-size9875262 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-net-read-buffer-size9875383 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-ssl-key9875520 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-ssl-cert9875596 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-ssl-ca9875681 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-ssl-capath9875755 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-ssl-cipher9875841 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-ssl-passphrase9875923 Ref: apis-php-constant.mysqlnd-uh-server-option-plugin-dir9876013 Ref: apis-php-constant.mysqlnd-uh-server-option-default-auth9876110 Ref: apis-php-constant.mysqlnd-uh-server-option-set-client-ip9876215 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-max-allowed-packet9876287 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-auth-protocol9876423 Ref: apis-php-constant.mysqlnd-uh-mysqlnd-opt-int-and-float-native9876531 Ref: apis-php-constant.mysqlnd-uh-version9877343 Ref: apis-php-constant.mysqlnd-uh-version-id9877440 Node: apis-php-class.mysqlnduhconnection9877533 Ref: apis-php-mysqlnduhconnection.intro9882186 Ref: apis-php-mysqlnduhconnection.synopsis9882186 Node: apis-php-mysqlnduhconnection.changeuser9886775 Node: apis-php-mysqlnduhconnection.charsetname9889105 Node: apis-php-mysqlnduhconnection.close9890638 Node: apis-php-mysqlnduhconnection.connect9893437 Node: apis-php-mysqlnduhconnection.construct9896147 Node: apis-php-mysqlnduhconnection.endpsession9896776 Node: apis-php-mysqlnduhconnection.escapestring9898281 Node: apis-php-mysqlnduhconnection.getaffectedrows9900144 Node: apis-php-mysqlnduhconnection.geterrornumber9901863 Node: apis-php-mysqlnduhconnection.geterrorstring9904059 Node: apis-php-mysqlnduhconnection.getfieldcount9906572 Node: apis-php-mysqlnduhconnection.gethostinformation9908624 Node: apis-php-mysqlnduhconnection.getlastinsertid9910262 Node: apis-php-mysqlnduhconnection.getlastmessage9911995 Node: apis-php-mysqlnduhconnection.getprotocolinformation9913857 Node: apis-php-mysqlnduhconnection.getserverinformation9915462 Node: apis-php-mysqlnduhconnection.getserverstatistics9917075 Node: apis-php-mysqlnduhconnection.getserverversion9918890 Node: apis-php-mysqlnduhconnection.getsqlstate9920503 Node: apis-php-mysqlnduhconnection.getstatistics9922255 Node: apis-php-mysqlnduhconnection.getthreadid9939084 Node: apis-php-mysqlnduhconnection.getwarningcount9940574 Node: apis-php-mysqlnduhconnection.init9942113 Node: apis-php-mysqlnduhconnection.killconnection9943749 Node: apis-php-mysqlnduhconnection.listfields9945325 Node: apis-php-mysqlnduhconnection.listmethod9947317 Node: apis-php-mysqlnduhconnection.moreresults9949626 Node: apis-php-mysqlnduhconnection.nextresult9951765 Node: apis-php-mysqlnduhconnection.ping9953650 Node: apis-php-mysqlnduhconnection.query9955125 Node: apis-php-mysqlnduhconnection.queryreadresultsetheader9956905 Node: apis-php-mysqlnduhconnection.reapquery9958812 Node: apis-php-mysqlnduhconnection.refreshserver9962222 Node: apis-php-mysqlnduhconnection.restartpsession9963843 Node: apis-php-mysqlnduhconnection.selectdb9965285 Node: apis-php-mysqlnduhconnection.sendclose9966858 Node: apis-php-mysqlnduhconnection.sendquery9968337 Node: apis-php-mysqlnduhconnection.serverdumpdebuginformation9969826 Node: apis-php-mysqlnduhconnection.setautocommit9971468 Node: apis-php-mysqlnduhconnection.setcharset9973229 Node: apis-php-mysqlnduhconnection.setclientoption9974798 Node: apis-php-mysqlnduhconnection.setserveroption9980626 Node: apis-php-mysqlnduhconnection.shutdownserver9982773 Node: apis-php-mysqlnduhconnection.simplecommand9983500 Node: apis-php-mysqlnduhconnection.simplecommandhandleresponse9989829 Node: apis-php-mysqlnduhconnection.sslset9995989 Node: apis-php-mysqlnduhconnection.stmtinit9998053 Node: apis-php-mysqlnduhconnection.storeresult10000064 Node: apis-php-mysqlnduhconnection.txcommit10002365 Node: apis-php-mysqlnduhconnection.txrollback10003769 Node: apis-php-mysqlnduhconnection.useresult10005187 Node: apis-php-class.mysqlnduhpreparedstatement10007004 Ref: apis-php-mysqlnduhpreparedstatement.intro10007665 Ref: apis-php-mysqlnduhpreparedstatement.synopsis10007665 Node: apis-php-mysqlnduhpreparedstatement.construct10007960 Node: apis-php-mysqlnduhpreparedstatement.execute10008639 Node: apis-php-mysqlnduhpreparedstatement.prepare10010512 Node: apis-php-ref.mysqlnd-uh10012562 Node: apis-php-function.mysqlnd-uh-convert-to-mysqlnd10013116 Node: apis-php-function.mysqlnd-uh-set-connection-proxy10015771 Node: apis-php-function.mysqlnd-uh-set-statement-proxy10018757 Node: apis-php-mysqlnd-uh.changes10020354 Node: apis-php-mysqlnd-uh.changes-one-o10021005 Node: apis-php-book.mysqlnd-mux10021841 Node: apis-php-mysqlnd-mux.key-features10023611 Node: apis-php-mysqlnd-mux.limitations10025276 Node: apis-php-mysqlnd-mux.name10026171 Node: apis-php-mysqlnd-mux.concepts10026541 Node: apis-php-mysqlnd-mux.architecture10027130 Node: apis-php-mysqlnd-mux.connection_pool10028803 Node: apis-php-mysqlnd-mux.sharing_connections10029995 Node: apis-php-mysqlnd-mux.setup10031370 Node: apis-php-mysqlnd-mux.requirements10031826 Node: apis-php-mysqlnd-mux.installation10032587 Node: apis-php-mysqlnd-mux.configuration10033236 Ref: apis-php-ini.mysqlnd-mux.enable10033782 Node: apis-php-mysqlnd-mux.constants10034047 Ref: apis-php-constant.mysqlnd-mux-version10035060 Ref: apis-php-constant.mysqlnd-mux-version-id10035162 Node: apis-php-mysqlnd-mux.changes10035256 Node: apis-php-mysqlnd-mux.changes-one-o10035784 Node: apis-php-book.mysqlnd-memcache10036525 Ref: apis-php-mymemflow-figure10037906 Node: apis-php-mysqlnd-memcache.key-features10039268 Node: apis-php-mysqlnd-memcache.limitations10039895 Node: apis-php-mysqlnd-memcache.name10040718 Node: apis-php-mysqlnd-memcache.quickstart10041220 Node: apis-php-mysqlnd-memcache.quickstart.configuration10042198 Node: apis-php-mysqlnd-memcache.quickstart.usage10044468 Node: apis-php-mysqlnd-memcache.setup10046522 Node: apis-php-mysqlnd-memcache.requirements10047015 Node: apis-php-mysqlnd-memcache.installation10048111 Node: apis-php-mysqlnd-memcache.configuration10049002 Ref: apis-php-ini.mysqlnd-memcache.enable10049650 Node: apis-php-mysqlnd-memcache.constants10050165 Ref: apis-php-constant.mysqlnd-memcache-default-regexp10050657 Ref: apis-php-constant.mysqlnd-memcache-version10051676 Ref: apis-php-constant.mysqlnd-memcache-version-id10051779 Node: apis-php-ref.mysqlnd-memcache10051878 Node: apis-php-function.mysqlnd-memcache-get-config10052343 Node: apis-php-function.mysqlnd-memcache-set10060764 Node: apis-php-mysqlnd-memcache.changes10064460 Node: apis-php-mysqlnd-memcache.changes-one-o10065007 Node: connector-php10065671 Node: apis-php-problems10066154 Node: php-mysql-mysqli10067639 Node: apis-perl10068695 Node: apis-python10071214 Node: apis-ruby10071833 Node: apis-ruby-mysqlruby10072661 Node: apis-ruby-rubymysql10073041 Node: apis-tcl10073459 Node: apis-eiffel10073787 Node: extending-mysql10074183 Node: mysql-internals10074563 Node: mysql-threads10075508 Node: mysql-test-suite10078718 Node: plugin-api10081413 Node: plugin-api-characteristics10083540 Node: plugin-api-components10087022 Node: plugin-types10089548 Node: storage-engine-plugins10090186 Node: full-text-plugins10090799 Node: daemon-plugins10094937 Node: information-schema-plugins10095424 Node: writing-plugins10095998 Node: writing-plugins-overview10098262 Node: plugin-data-structures10100098 Node: server-plugin-descriptors10102536 Node: plugin-status-system-variables10118816 Node: compiling-plugin-libraries10129536 Node: writing-full-text-plugins10132988 Node: writing-daemon-plugins10156834 Node: writing-information-schema-plugins10161082 Node: adding-functions10168025 Node: udf-features10170633 Node: adding-udf10171523 Node: udf-calling10177976 Node: udf-aggr-calling10182860 Node: udf-arguments10186373 Node: udf-return-values10192753 Node: udf-compiling10194939 Node: udf-security10201415 Node: adding-native-function10203099 Node: porting10207827 Node: debugging-server10210173 Node: compiling-for-debugging10212778 Node: making-trace-files10215496 Node: making-windows-dumps10217476 Node: using-gdb-on-mysqld10219360 Node: using-stack-trace10222861 Node: using-log-files10227041 Node: reproducible-test-case10230018 Node: debugging-client10232239 Node: dbug-package10233481 Node: mysql-enterprise10242936 Node: mysql-enterprise-monitor10244352 Node: mysql-enterprise-backup10248717 Node: mysql-enterprise-security10250381 Node: mysql-enterprise-audit10251673 Node: mysql-enterprise-thread-pool10252783 Node: workbench10253687 Node: mysql-for-excel10255650 Node: mysql-for-excel-install10256742 Ref: mysql-for-excel-navigation-bar10258194 Node: mysql-for-excel-edit10258248 Ref: mysql-for-excel-edit-table10259087 Node: mysql-for-excel-import10260199 Ref: mysql-for-excel-import-data10261981 Ref: mysql-for-excel-import-data-procedure10263063 Node: mysql-for-excel-append10263142 Ref: mysql-for-excel-append-data-automatic10263891 Ref: mysql-for-excel-append-data-advanced10266228 Node: mysql-for-excel-export10267970 Ref: mysql-for-excel-export-figure10268343 Ref: mysql-for-excel-export-advanced10268531 Node: mysql-for-excel-faq10270764 Ref: qandaitem-26-6-1-110271552 Ref: qandaitem-26-6-1-210272378 Ref: qandaitem-26-6-1-310272865 Ref: qandaitem-26-6-1-410273367 Node: licenses-third-party10273770 Node: license-ant-contrib10280686 Node: license-antlr-310283477 Node: license-antlr-3-310285379 Node: license-boost10287219 Node: license-bouncy-castle-1-710289012 Node: license-c3p0-0-9110290477 Node: license-django-15110291214 Node: license-dtoa10293122 Node: license-libedit10294097 Node: license-findgtest-cmake10300193 Node: license-dbug10302936 Node: license-getarg10304656 Node: license-glib-proxy10306635 Node: license-gnu-gpl-2-010308542 Node: license-gnu-lgpl-2-110328997 Node: license-gnu-libtool10358632 Node: license-gnu-readline10361248 Node: license-google-io-rate-patch10362323 Node: license-google-tcmalloc10364313 Node: license-google-smp-patch10366329 Node: license-jboss-common-jdbc-wrapper10368258 Node: license-lib-sql10369072 Node: license-libevent10369926 Node: license-libiconv-proxy10376717 Node: license-libintl10377418 Node: license-linux-pam10379851 Node: license-lpeg10382236 Node: license-lua10383694 Node: license-luafilesystem10385099 Node: license-md510386514 Node: license-memcached10387528 Node: license-nt-servc10389395 Node: license-openpam10389902 Node: license-openssl-1-010392079 Node: license-paramiko10398733 Node: license-pcre10399395 Node: license-percona-io-threads-patch10402410 Node: license-regex10404381 Node: license-us-secure-hash10405736 Node: license-libstring10407744 Node: license-sha1-in-c10409256 Node: license-slf4j10409575 Node: license-zlib10411091 Node: license-zlib-net10412925 Node: faqs10414805 Node: faqs-general10415854 Ref: qandaitem-B-1-1-110416860 Ref: qandaitem-B-1-1-210417580 Ref: qandaitem-B-1-1-310418249 Ref: qandaitem-B-1-1-410418323 Ref: qandaitem-B-1-1-510418760 Ref: qandaitem-B-1-1-610419217 Ref: qandaitem-B-1-1-710419703 Ref: qandaitem-B-1-1-810420082 Ref: qandaitem-B-1-1-910420268 Ref: qandaitem-B-1-1-1010420588 Ref: qandaitem-B-1-1-1110421005 Node: faqs-storage-engines10421402 Ref: qandaitem-B-2-1-110422034 Ref: qandaitem-B-2-1-210422407 Ref: qandaitem-B-2-1-310423367 Ref: qandaitem-B-2-1-410423598 Ref: qandaitem-B-2-1-510423893 Node: faqs-sql-modes10424270 Ref: qandaitem-B-3-1-110424888 Ref: qandaitem-B-3-1-210425287 Ref: qandaitem-B-3-1-310425461 Ref: qandaitem-B-3-1-410425897 Ref: qandaitem-B-3-1-510426194 Ref: qandaitem-B-3-1-610426522 Ref: qandaitem-B-3-1-710426967 Node: faqs-stored-procs10427192 Ref: qandaitem-B-4-1-110429791 Ref: qandaitem-B-4-1-210429957 Ref: qandaitem-B-4-1-310430083 Ref: qandaitem-B-4-1-410430240 Ref: qandaitem-B-4-1-510430628 Ref: qandaitem-B-4-1-610431106 Ref: qandaitem-B-4-1-710431764 Ref: qandaitem-B-4-1-810432404 Ref: qandaitem-B-4-1-910432537 Ref: qandaitem-B-4-1-1010432612 Ref: qandaitem-B-4-1-1110432787 Ref: qandaitem-B-4-1-1210432909 Ref: qandaitem-B-4-1-1310433096 Ref: qandaitem-B-4-1-1410433291 Ref: qandaitem-B-4-1-1510433740 Ref: qandaitem-B-4-1-1610433828 Ref: qandaitem-B-4-1-1710434010 Ref: qandaitem-B-4-1-1810434097 Ref: qandaitem-B-4-1-1910434245 Ref: qandaitem-B-4-1-2010434570 Ref: qandaitem-B-4-1-2110435079 Ref: qandaitem-B-4-1-2210435246 Ref: qandaitem-B-4-1-2310435554 Ref: qandaitem-B-4-1-2410435925 Ref: qandaitem-B-4-1-2510436344 Ref: qandaitem-B-4-1-2610437099 Ref: qandaitem-B-4-1-2710438429 Ref: qandaitem-B-4-1-2810438607 Node: faqs-triggers10439262 Ref: qandaitem-B-5-1-110440358 Ref: qandaitem-B-5-1-210440455 Ref: qandaitem-B-5-1-310440582 Ref: qandaitem-B-5-1-410440854 Ref: qandaitem-B-5-1-510441072 Ref: qandaitem-B-5-1-610441512 Ref: qandaitem-B-5-1-710442128 Ref: qandaitem-B-5-1-810442264 Ref: qandaitem-B-5-1-910442324 Ref: qandaitem-B-5-1-1010442618 Ref: qandaitem-B-5-1-1110442943 Ref: qandaitem-B-5-1-1210443080 Ref: qandaitem-B-5-1-1310443290 Ref: qandaitem-B-5-1-1410444056 Node: faqs-views10446196 Ref: qandaitem-B-6-1-110446766 Ref: qandaitem-B-6-1-210446854 Ref: qandaitem-B-6-1-310447000 Ref: qandaitem-B-6-1-410447330 Ref: qandaitem-B-6-1-510447387 Ref: qandaitem-B-6-1-610447447 Node: faqs-information-schema10447729 Ref: qandaitem-B-7-1-110448422 Ref: qandaitem-B-7-1-210448545 Ref: qandaitem-B-7-1-310448696 Ref: qandaitem-B-7-1-410449089 Ref: qandaitem-B-7-1-510449467 Node: faqs-migration10449788 Ref: qandaitem-B-8-1-110450193 Ref: qandaitem-B-8-1-210450726 Node: faqs-security10451705 Ref: qandaitem-B-9-1-110452341 Ref: qandaitem-B-9-1-210452904 Ref: qandaitem-B-9-1-310453239 Ref: qandaitem-B-9-1-410453488 Ref: qandaitem-B-9-1-510453592 Node: faqs-mysql-cluster10453696 Ref: qandaitem-B-10-1-110457984 Ref: qandaitem-B-10-1-210460763 Ref: qandaitem-B-10-1-310461646 Ref: qandaitem-B-10-1-410462149 Ref: qandaitem-B-10-1-510463480 Ref: qandaitem-B-10-1-610464125 Ref: qandaitem-B-10-1-710464865 Ref: qandaitem-B-10-1-810467221 Ref: qandaitem-B-10-1-910469658 Ref: qandaitem-B-10-1-1010470189 Ref: qandaitem-B-10-1-1110471134 Ref: qandaitem-B-10-1-1210474489 Ref: qandaitem-B-10-1-1310475586 Ref: qandaitem-B-10-1-1410475930 Ref: qandaitem-B-10-1-1510477909 Ref: qandaitem-B-10-1-1610478989 Ref: qandaitem-B-10-1-1710479802 Ref: qandaitem-B-10-1-1810481165 Ref: qandaitem-B-10-1-1910481814 Ref: qandaitem-B-10-1-2010482211 Ref: qandaitem-B-10-1-2110482497 Ref: qandaitem-B-10-1-2210483231 Ref: qandaitem-B-10-1-2310483725 Ref: qandaitem-B-10-1-2410483929 Ref: qandaitem-B-10-1-2510485802 Ref: qandaitem-B-10-1-2610486352 Ref: qandaitem-B-10-1-2710489028 Ref: qandaitem-B-10-1-2810489616 Ref: qandaitem-B-10-1-2910490518 Ref: qandaitem-B-10-1-3010491160 Ref: qandaitem-B-10-1-3110492966 Ref: qandaitem-B-10-1-3210494040 Ref: qandaitem-B-10-1-3310496377 Ref: qandaitem-B-10-1-3410496619 Ref: qandaitem-B-10-1-3510497095 Ref: qandaitem-B-10-1-3610497600 Ref: qandaitem-B-10-1-3710498302 Ref: qandaitem-B-10-1-3810498674 Ref: qandaitem-B-10-1-3910499123 Ref: qandaitem-B-10-1-4010499748 Ref: qandaitem-B-10-1-4110500023 Ref: qandaitem-B-10-1-4210500517 Node: faqs-cjk10502163 Ref: qandaitem-B-11-1-110504410 Ref: qandaitem-B-11-1-210507239 Ref: qandaitem-B-11-1-310512846 Ref: qandaitem-B-11-1-410513853 Ref: qandaitem-B-11-1-510516731 Ref: qandaitem-B-11-1-610517048 Ref: qandaitem-B-11-1-710517462 Ref: qandaitem-B-11-1-810517699 Ref: qandaitem-B-11-1-910518609 Ref: qandaitem-B-11-1-1010520363 Ref: qandaitem-B-11-1-1110523082 Ref: qandaitem-B-11-1-1210527562 Ref: qandaitem-B-11-1-1310529467 Ref: qandaitem-B-11-1-1410532319 Ref: qandaitem-B-11-1-1510535663 Ref: qandaitem-B-11-1-1610537608 Ref: qandaitem-B-11-1-1710538804 Ref: qandaitem-B-11-1-1810539276 Ref: qandaitem-B-11-1-1910539901 Ref: qandaitem-B-11-1-2010540221 Node: faqs-connectors-apis10540678 Node: faqs-replication10541156 Ref: qandaitem-B-13-1-110543000 Ref: qandaitem-B-13-1-210543839 Ref: qandaitem-B-13-1-310544188 Ref: qandaitem-B-13-1-410545353 Ref: qandaitem-B-13-1-510546355 Ref: qandaitem-B-13-1-610547739 Ref: qandaitem-B-13-1-710548319 Ref: qandaitem-B-13-1-810548541 Ref: qandaitem-B-13-1-910551577 Ref: qandaitem-B-13-1-1010552301 Ref: qandaitem-B-13-1-1110552802 Ref: qandaitem-B-13-1-1210552919 Ref: qandaitem-B-13-1-1310553182 Ref: qandaitem-B-13-1-1410553336 Node: error-handling10553501 Node: error-sources10554370 Node: error-types10556096 Node: error-messages-server10557943 Ref: error_er_hashchk10560210 Ref: error_er_nisamchk10560287 Ref: error_er_no10560365 Ref: error_er_yes10560432 Ref: error_er_cant_create_file10560501 Ref: error_er_cant_create_table10560614 Ref: error_er_cant_create_db10560729 Ref: error_er_db_create_exists10560844 Ref: error_er_db_drop_exists10560966 Ref: error_er_db_drop_delete10561091 Ref: error_er_db_drop_rmdir10561222 Ref: error_er_cant_delete_file10561351 Ref: error_er_cant_find_system_rec10561465 Ref: error_er_cant_get_stat10561581 Ref: error_er_cant_get_wd10561693 Ref: error_er_cant_lock10561806 Ref: error_er_cant_open_file10561905 Ref: error_er_file_not_found10562015 Ref: error_er_cant_read_dir10562125 Ref: error_er_cant_set_wd10562235 Ref: error_er_checkread10562345 Ref: error_er_disk_full10562465 Ref: error_er_dup_key10562594 Ref: error_er_error_on_close10562704 Ref: error_er_error_on_read10562815 Ref: error_er_error_on_rename10562926 Ref: error_er_error_on_write10563047 Ref: error_er_file_used10563159 Ref: error_er_filsort_abort10563260 Ref: error_er_form_not_found10563348 Ref: error_er_get_errno10563457 Ref: error_er_illegal_ha10563561 Ref: error_er_key_not_found10563688 Ref: error_er_not_form_file10563789 Ref: error_er_not_keyfile10563900 Ref: error_er_old_keyfile10564025 Ref: error_er_open_as_readonly10564138 Ref: error_er_outofmemory10564240 Ref: error_er_out_of_sortmemory10564380 Ref: error_er_unexpected_eof10564512 Ref: error_er_con_count_error10564644 Ref: error_er_out_of_resources10564742 Ref: error_er_bad_host_error10565013 Ref: error_er_handshake_error10565125 Ref: error_er_dbaccess_denied_error10565216 Ref: error_er_access_denied_error10565349 Ref: error_er_no_db_error10565484 Ref: error_er_unknown_com_error10565578 Ref: error_er_bad_null_error10565673 Ref: error_er_bad_db_error10565776 Ref: error_er_table_exists_error10565872 Ref: error_er_bad_table_error10565978 Ref: error_er_non_uniq_error10566074 Ref: error_er_server_shutdown10566181 Ref: error_er_bad_field_error10566286 Ref: error_er_wrong_field_with_group10566391 Ref: error_er_wrong_group_field10566498 Ref: error_er_wrong_sum_select10566597 Ref: error_er_wrong_value_count10566733 Ref: error_er_too_long_ident10566851 Ref: error_er_dup_fieldname10566960 Ref: error_er_dup_keyname10567062 Ref: error_er_dup_entry10567159 Ref: error_er_wrong_field_spec10567380 Ref: error_er_parse_error10567501 Ref: error_er_empty_query10567598 Ref: error_er_nonuniq_table10567687 Ref: error_er_invalid_default10567791 Ref: error_er_multiple_pri_key10567899 Ref: error_er_too_many_keys10568006 Ref: error_er_too_many_key_parts10568126 Ref: error_er_too_long_key10568257 Ref: error_er_key_column_does_not_exits10568386 Ref: error_er_blob_used_as_key10568512 Ref: error_er_too_big_fieldlength10568672 Ref: error_er_wrong_auto_key10568834 Ref: error_er_ready10569009 Ref: error_er_normal_shutdown10569144 Ref: error_er_got_signal10569241 Ref: error_er_shutdown_complete10569342 Ref: error_er_forcing_close10569443 Ref: error_er_ipsock_error10569561 Ref: error_er_no_such_index10569658 Ref: error_er_wrong_field_terminators10569816 Ref: error_er_blobs_and_no_terminated10569973 Ref: error_er_textfile_not_readable10570139 Ref: error_er_file_exists_error10570297 Ref: error_er_load_info10570401 Ref: error_er_alter_info10570525 Ref: error_er_wrong_sub_key10570626 Ref: error_er_cant_remove_all_fields10570869 Ref: error_er_cant_drop_field_or_key10571028 Ref: error_er_insert_info10571158 Ref: error_er_update_table_used10571274 Ref: error_er_no_such_thread10571420 Ref: error_er_kill_denied_error10571519 Ref: error_er_no_tables_used10571630 Ref: error_er_too_big_set10571721 Ref: error_er_no_unique_logfile10571833 Ref: error_er_table_not_locked_for_write10571960 Ref: error_er_table_not_locked10572113 Ref: error_er_blob_cant_have_default10572234 Ref: error_er_wrong_db_name10572367 Ref: error_er_wrong_table_name10572471 Ref: error_er_too_big_select10572575 Ref: error_er_unknown_error10572808 Ref: error_er_unknown_procedure10572897 Ref: error_er_wrong_paramcount_to_procedure10572999 Ref: error_er_wrong_parameters_to_procedure10573139 Ref: error_er_unknown_table10573274 Ref: error_er_field_specified_twice10573374 Ref: error_er_invalid_group_func_use10573485 Ref: error_er_unsupported_extension10573599 Ref: error_er_table_must_have_columns10573757 Ref: error_er_record_file_full10573878 Ref: error_er_unknown_character_set10573979 Ref: error_er_too_many_tables10574090 Ref: error_er_too_many_fields10574223 Ref: error_er_too_big_rowsize10574317 Ref: error_er_stack_overrun10574547 Ref: error_er_wrong_outer_join10574742 Ref: error_er_null_column_in_index10574890 Ref: error_er_cant_find_udf10575092 Ref: error_er_cant_initialize_udf10575192 Ref: error_er_udf_no_paths10575308 Ref: error_er_udf_exists10575418 Ref: error_er_cant_open_library10575519 Ref: error_er_cant_find_dl_entry10575644 Ref: error_er_function_not_defined10575758 Ref: error_er_host_is_blocked10575869 Ref: error_er_host_not_privileged10576045 Ref: error_er_password_anonymous_user10576183 Ref: error_er_password_not_allowed10576370 Ref: error_er_password_no_match10576563 Ref: error_er_update_info10576688 Ref: error_er_cant_create_thread10576806 Ref: error_er_wrong_value_count_on_row10577033 Ref: error_er_cant_reopen_table10577169 Ref: error_er_invalid_use_of_null10577273 Ref: error_er_regexp_error10577380 Ref: error_er_mix_of_group_func_and_fields10577481 Ref: error_er_nonexisting_grant10577695 Ref: error_er_tableaccess_denied_error10577832 Ref: error_er_columnaccess_denied_error10577969 Ref: error_er_illegal_grant_for_table10578127 Ref: error_er_grant_wrong_host_or_user10578309 Ref: error_er_no_such_table10578442 Ref: error_er_nonexisting_table_grant10578545 Ref: error_er_not_allowed_command10578707 Ref: error_er_syntax_error10578844 Ref: error_er_delayed_cant_change_lock10579057 Ref: error_er_too_many_delayed_threads10579211 Ref: error_er_aborting_connection10579329 Ref: error_er_net_packet_too_large10579461 Ref: error_er_net_read_error_from_pipe10579595 Ref: error_er_net_fcntl_error10579723 Ref: error_er_net_packets_out_of_order10579826 Ref: error_er_net_uncompress_error10579937 Ref: error_er_net_read_error10580060 Ref: error_er_net_read_interrupted10580179 Ref: error_er_net_error_on_write10580303 Ref: error_er_net_write_interrupted10580426 Ref: error_er_too_long_string10580551 Ref: error_er_table_cant_handle_blob10580684 Ref: error_er_table_cant_handle_auto_increment10580822 Ref: error_er_delayed_insert_table_locked10580980 Ref: error_er_wrong_column_name10581157 Ref: error_er_wrong_key_column10581263 Ref: error_er_wrong_mrg_table10581389 Ref: error_er_dup_unique10581571 Ref: error_er_blob_key_without_length10581700 Ref: error_er_primary_cant_have_null10581859 Ref: error_er_too_many_rows10582039 Ref: error_er_requires_primary_key10582152 Ref: error_er_no_raid_compiled10582273 Ref: error_er_update_without_key_in_safe_mode10582407 Ref: error_er_key_does_not_exits10582612 Ref: error_er_check_no_such_table10582729 Ref: error_er_check_not_implemented10582827 Ref: error_er_cant_do_this_during_an_transaction10582962 Ref: error_er_error_during_commit10583129 Ref: error_er_error_during_rollback10583237 Ref: error_er_error_during_flush_logs10583349 Ref: error_er_error_during_checkpoint10583465 Ref: error_er_new_aborting_connection10583581 Ref: error_er_dump_not_implemented10583733 Ref: error_er_flush_master_binlog_closed10583888 Ref: error_er_index_rebuild10584011 Ref: error_er_master10584135 Ref: error_er_master_net_read10584227 Ref: error_er_master_net_write10584334 Ref: error_er_ft_matching_key_not_found10584440 Ref: error_er_lock_or_active_transaction10584578 Ref: error_er_unknown_system_variable10584766 Ref: error_er_crashed_on_usage10584880 Ref: error_er_crashed_on_repair10585013 Ref: error_er_warning_not_complete_rollback10585165 Ref: error_er_trans_cache_full10585328 Ref: error_er_slave_must_stop10585549 Ref: error_er_slave_not_running10585709 Ref: error_er_bad_slave10585869 Ref: error_er_master_info10586028 Ref: error_er_slave_thread10586206 Ref: error_er_too_many_user_connections10586334 Ref: error_er_set_constants_only10586498 Ref: error_er_lock_wait_timeout10586625 Ref: error_er_lock_table_full10586759 Ref: error_er_read_only_transaction10586890 Ref: error_er_drop_db_with_read_lock10587048 Ref: error_er_create_db_with_read_lock10587204 Ref: error_er_wrong_arguments10587364 Ref: error_er_no_permission_to_create_user10587467 Ref: error_er_union_tables_in_different_dir10587607 Ref: error_er_lock_deadlock10587782 Ref: error_er_table_cant_handle_ft10587929 Ref: error_er_cannot_add_foreign10588064 Ref: error_er_no_referenced_row10588178 Ref: error_er_row_is_referenced10588327 Ref: error_er_connect_to_master10588480 Ref: error_er_query_on_master10588590 Ref: error_er_error_when_executing_command10588701 Ref: error_er_wrong_usage10588832 Ref: error_er_wrong_number_of_columns_in_select10588934 Ref: error_er_cant_update_with_readlock10589101 Ref: error_er_mixing_not_allowed10589258 Ref: error_er_dup_argument10589408 Ref: error_er_user_limit_reached10589518 Ref: error_er_specific_access_denied_error10589665 Ref: error_er_local_variable10589825 Ref: error_er_global_variable10589976 Ref: error_er_no_default10590127 Ref: error_er_wrong_value_for_var10590242 Ref: error_er_wrong_type_for_var10590371 Ref: error_er_var_cant_be_read10590492 Ref: error_er_cant_use_option_here10590610 Ref: error_er_not_supported_yet10590726 Ref: error_er_master_fatal_error_reading_binlog10590852 Ref: error_er_slave_ignored_table10591028 Ref: error_er_incorrect_global_local_var10591184 Ref: error_er_wrong_fk_def10591303 Ref: error_er_key_ref_do_not_match_table_ref10591423 Ref: error_er_operand_columns10591566 Ref: error_er_subquery_no_1_row10591679 Ref: error_er_unknown_stmt_handler10591791 Ref: error_er_corrupt_help_db10591927 Ref: error_er_cyclic_reference10592047 Ref: error_er_auto_convert10592156 Ref: error_er_illegal_reference10592267 Ref: error_er_derived_must_have_alias10592380 Ref: error_er_select_reduced10592509 Ref: error_er_tablename_not_allowed_here10592627 Ref: error_er_not_supported_auth_mode10592771 Ref: error_er_spatial_cant_have_null10592962 Ref: error_er_collation_charset_mismatch10593092 Ref: error_er_slave_was_running10593231 Ref: error_er_slave_was_not_running10593335 Ref: error_er_too_big_for_uncompress10593449 Ref: error_er_zlib_z_mem_error10593649 Ref: error_er_zlib_z_buf_error10593751 Ref: error_er_zlib_z_data_error10593931 Ref: error_er_cut_value_group_concat10594037 Ref: error_er_warn_too_few_records10594159 Ref: error_er_warn_too_many_records10594286 Ref: error_er_warn_null_to_notnull10594450 Ref: error_er_warn_data_out_of_range10594615 Ref: error_warn_data_truncated10594745 Ref: error_er_warn_using_other_handler10594865 Ref: error_er_cant_aggregate_2collations10594990 Ref: error_er_drop_user10595148 Ref: error_er_revoke_grants10595266 Ref: error_er_cant_aggregate_3collations10595413 Ref: error_er_cant_aggregate_ncollations10595577 Ref: error_er_variable_is_not_struct10595710 Ref: error_er_unknown_collation10595879 Ref: error_er_slave_ignored_ssl_params10595982 Ref: error_er_server_is_in_secure_auth_mode10596239 Ref: error_er_warn_field_resolved10596478 Ref: error_er_bad_slave_until_cond10596637 Ref: error_er_missing_skip_slave10596795 Ref: error_er_until_cond_ignored10597069 Ref: error_er_wrong_name_for_index10597215 Ref: error_er_wrong_name_for_catalog10597323 Ref: error_er_warn_qc_resize10597435 Ref: error_er_bad_ft_column10597580 Ref: error_er_unknown_key_cache10597700 Ref: error_er_warn_hostname_wont_work10597802 Ref: error_er_unknown_storage_engine10598000 Ref: error_er_unused_110598110 Ref: error_er_warn_deprecated_syntax10598284 Ref: error_er_non_updatable_table10598455 Ref: error_er_feature_disabled10598583 Ref: error_er_option_prevents_statement10598746 Ref: error_er_duplicated_value_in_type10598921 Ref: error_er_truncated_wrong_value10599051 Ref: error_er_too_much_auto_timestamp_cols10599169 Ref: error_er_invalid_on_update10599395 Ref: error_er_unsupported_ps10599515 Ref: error_er_get_errmsg10599665 Ref: error_er_get_temporary_errmsg10599763 Ref: error_er_unknown_time_zone10599881 Ref: error_er_warn_invalid_timestamp10599997 Ref: error_er_invalid_character_string10600131 Ref: error_er_warn_allowed_packet_overflowed10600251 Ref: error_er_conflicting_declarations10600421 Ref: error_er_sp_no_recursive_create10600551 Ref: error_er_sp_already_exists10600688 Ref: error_er_sp_does_not_exist10600788 Ref: error_er_sp_drop_failed10600888 Ref: error_er_sp_store_failed10600985 Ref: error_er_sp_lilabel_mismatch10601085 Ref: error_er_sp_label_redefine10601196 Ref: error_er_sp_label_mismatch10601295 Ref: error_er_sp_uninit_var10601401 Ref: error_er_sp_badselect10601515 Ref: error_er_sp_badreturn10601654 Ref: error_er_sp_badstatement10601765 Ref: error_er_update_log_deprecated_ignored10601881 Ref: error_er_update_log_deprecated_translated10602127 Ref: error_er_query_interrupted10602398 Ref: error_er_sp_wrong_no_of_args10602509 Ref: error_er_sp_cond_mismatch10602656 Ref: error_er_sp_noreturn10602758 Ref: error_er_sp_noreturnend10602862 Ref: error_er_sp_bad_cursor_query10602971 Ref: error_er_sp_bad_cursor_select10603086 Ref: error_er_sp_cursor_mismatch10603201 Ref: error_er_sp_cursor_already_open10603302 Ref: error_er_sp_cursor_not_open10603409 Ref: error_er_sp_undeclared_var10603508 Ref: error_er_sp_wrong_no_of_fetch_args10603611 Ref: error_er_sp_fetch_no_data10603734 Ref: error_er_sp_dup_param10603864 Ref: error_er_sp_dup_var10603962 Ref: error_er_sp_dup_cond10604057 Ref: error_er_sp_dup_curs10604154 Ref: error_er_sp_cant_alter10604248 Ref: error_er_sp_subselect_nyi10604345 Ref: error_er_stmt_not_allowed_in_sf_or_trg10604452 Ref: error_er_sp_varcond_after_curshndlr10604596 Ref: error_er_sp_cursor_after_handler10604759 Ref: error_er_sp_case_not_found10604889 Ref: error_er_fparser_too_big_file10605002 Ref: error_er_fparser_bad_header10605119 Ref: error_er_fparser_eof_in_comment10605239 Ref: error_er_fparser_error_in_parameter10605373 Ref: error_er_fparser_eof_in_unknown_parameter10605509 Ref: error_er_view_no_explain10605674 Ref: error_er_frm_unknown_type10605828 Ref: error_er_wrong_object10605952 Ref: error_er_nonupdateable_column10606044 Ref: error_er_view_select_derived10606155 Ref: error_er_view_select_clause10606289 Ref: error_er_view_select_variable10606406 Ref: error_er_view_select_tmptable10606535 Ref: error_er_view_wrong_list10606664 Ref: error_er_warn_view_merge10606811 Ref: error_er_warn_view_without_key10606971 Ref: error_er_view_invalid10607131 Ref: error_er_sp_no_drop_sp10607330 Ref: error_er_sp_goto_in_hndlr10607470 Ref: error_er_trg_already_exists10607598 Ref: error_er_trg_does_not_exist10607701 Ref: error_er_trg_on_view_or_temp_table10607804 Ref: error_er_trg_cant_change_row10607933 Ref: error_er_trg_no_such_row_in_trg10608061 Ref: error_er_no_default_for_field10608178 Ref: error_er_division_by_zero10608300 Ref: error_er_truncated_wrong_value_for_field10608392 Ref: error_er_illegal_value_for_type10608542 Ref: error_er_view_nonupd_check10608669 Ref: error_er_view_check_failed10608791 Ref: error_er_procaccess_denied_error10608898 Ref: error_er_relay_log_fail10609036 Ref: error_er_passwd_length10609146 Ref: error_er_unknown_target_binlog10609275 Ref: error_er_io_err_log_index_read10609395 Ref: error_er_binlog_purge_prohibited10609511 Ref: error_er_fseek_fail10609646 Ref: error_er_binlog_purge_fatal_err10609736 Ref: error_er_log_in_use10609849 Ref: error_er_log_purge_unknown_err10609963 Ref: error_er_relay_log_init10610077 Ref: error_er_no_binary_logging10610196 Ref: error_er_reserved_syntax10610308 Ref: error_er_wsas_failed10610460 Ref: error_er_diff_groups_proc10610551 Ref: error_er_no_group_for_proc10610679 Ref: error_er_order_with_proc10610803 Ref: error_er_logging_prohibit_changing_of10610923 Ref: error_er_no_file_mapping10611091 Ref: error_er_wrong_magic10611198 Ref: error_er_ps_many_param10611289 Ref: error_er_key_part_010611414 Ref: error_er_view_checksum10611519 Ref: error_er_view_multiupdate10611620 Ref: error_er_view_no_insert_field_list10611771 Ref: error_er_view_delete_merge_view10611916 Ref: error_er_cannot_user10612038 Ref: error_er_xaer_nota10612138 Ref: error_er_xaer_inval10612232 Ref: error_er_xaer_rmfail10612359 Ref: error_er_xaer_outside10612524 Ref: error_er_xaer_rmerr10612657 Ref: error_er_xa_rbrollback10612827 Ref: error_er_nonexisting_proc_grant10612952 Ref: error_er_proc_auto_grant_fail10613115 Ref: error_er_proc_auto_revoke_fail10613250 Ref: error_er_data_too_long10613384 Ref: error_er_sp_bad_sqlstate10613500 Ref: error_er_startup10613596 Ref: error_er_load_from_fixed_size_rows_to_var10613736 Ref: error_er_cant_create_user_with_grant10613900 Ref: error_er_wrong_value_for_type10614037 Ref: error_er_table_def_changed10614160 Ref: error_er_sp_dup_handler10614294 Ref: error_er_sp_not_var_arg10614415 Ref: error_er_sp_no_retset10614595 Ref: error_er_cant_create_geometry_object10614714 Ref: error_er_failed_routine_break_binlog10614876 Ref: error_er_binlog_unsafe_routine10615170 Ref: error_er_binlog_create_routine_need_super10615465 Ref: error_er_exec_stmt_with_open_cursor10615721 Ref: error_er_stmt_has_no_open_cursor10615936 Ref: error_er_commit_not_allowed_in_sf_or_trg10616061 Ref: error_er_no_default_for_view_field10616238 Ref: error_er_sp_no_recursion10616398 Ref: error_er_too_big_scale10616532 Ref: error_er_too_big_precision10616672 Ref: error_er_m_bigger_than_d10616820 Ref: error_er_wrong_lock_of_system_table10616977 Ref: error_er_connect_to_foreign_data_source10617151 Ref: error_er_query_on_foreign_data_source10617293 Ref: error_er_foreign_data_source_doesnt_exist10617484 Ref: error_er_foreign_data_string_invalid_cant_create10617678 Ref: error_er_foreign_data_string_invalid10617887 Ref: error_er_cant_create_federated_table10618049 Ref: error_er_trg_in_wrong_schema10618195 Ref: error_er_stack_overrun_need_more10618300 Ref: error_er_too_long_body10618533 Ref: error_er_warn_cant_drop_default_keycache10618642 Ref: error_er_too_big_displaywidth10618769 Ref: error_er_xaer_dupid10618906 Ref: error_er_datetime_function_overflow10619013 Ref: error_er_cant_update_used_table_in_sf_or_trg10619138 Ref: error_er_view_prevent_update10619385 Ref: error_er_ps_no_recursion10619537 Ref: error_er_sp_cant_set_autocommit10619790 Ref: error_er_malformed_definer10619943 Ref: error_er_view_frm_no_user10620053 Ref: error_er_view_other_user10620257 Ref: error_er_no_such_user10620409 Ref: error_er_forbid_schema_change10620542 Ref: error_er_row_is_referenced_210620674 Ref: error_er_no_referenced_row_210620834 Ref: error_er_sp_bad_var_shadow10620990 Ref: error_er_trg_no_definer10621121 Ref: error_er_old_file_format10621390 Ref: error_er_sp_recursion_limit10621536 Ref: error_er_sp_proc_table_corrupt10621716 Ref: error_er_sp_wrong_name10621971 Ref: error_er_table_needs_upgrade10622124 Ref: error_er_sp_no_aggregate10622346 Ref: error_er_max_prepared_stmt_count_reached10622523 Ref: error_er_view_recursive10622774 Ref: error_er_non_grouping_field_used10622936 Ref: error_er_table_cant_handle_spkeys10623127 Ref: error_er_no_triggers_on_system_schema10623327 Ref: error_er_removed_spaces10623533 Ref: error_er_autoinc_read_failed10623703 Ref: error_er_username10623897 Ref: error_er_hostname10624023 Ref: error_er_wrong_string_length10624149 Ref: error_er_non_insertable_table10624353 Ref: error_er_admin_wrong_mrg_table10624546 Ref: error_er_too_high_level_of_nesting_for_select10624766 Ref: error_er_name_becomes_empty10624980 Ref: error_er_ambiguous_field_term10625139 Ref: error_er_foreign_server_exists10625403 Ref: error_er_foreign_server_doesnt_exist10625615 Ref: error_er_illegal_ha_create_option10625864 Ref: error_er_partition_requires_values_error10626082 Ref: error_er_partition_wrong_values_error10626267 Ref: error_er_char_set_in_part_field_error10626430 Ref: error_er_partition_maxvalue_error10626660 Ref: error_er_partition_subpartition_error10626801 Ref: error_er_partition_subpart_mix_error10626949 Ref: error_er_partition_wrong_no_part_error10627171 Ref: error_er_partition_wrong_no_subpart_error10627339 Ref: error_er_const_expr_in_partition_func_error10627513 Ref: error_er_wrong_expr_in_partition_func_error10627881 Ref: error_er_no_const_expr_in_range_or_list_error10628274 Ref: error_er_field_not_found_part_error10628426 Ref: error_er_list_of_fields_only_in_hash_error10628585 Ref: error_er_inconsistent_partition_info_error10628734 Ref: error_er_partition_func_not_allowed_error10628935 Ref: error_er_partitions_must_be_defined_error10629073 Ref: error_er_range_not_increasing_error10629221 Ref: error_er_inconsistent_type_of_functions_error10629384 Ref: error_er_multiple_def_const_in_list_part_error10629543 Ref: error_er_drop_partition_failure10629705 Ref: error_er_partition_entry_error10629915 Ref: error_er_drop_partition_when_fk_defined10630048 Ref: error_er_mix_handler_error10630295 Ref: error_er_partition_not_defined_error10630457 Ref: error_er_too_many_partitions_error10630611 Ref: error_er_subpartition_error10630757 Ref: error_er_cant_create_handler_file10630940 Ref: error_er_blob_field_in_part_func_error10631065 Ref: error_er_unique_key_need_all_fields_in_pf10631211 Ref: error_er_no_parts_error10631382 Ref: error_er_tablespace_option_only_once10631499 Ref: error_er_partition_mgmt_on_nonpartitioned10631725 Ref: error_er_create_tablespace_failed10631893 Ref: error_er_foreign_key_on_partitioned10632086 Ref: error_er_drop_tablespace_failed10632315 Ref: error_er_drop_partition_non_existent10632502 Ref: error_er_drop_last_partition10632625 Ref: error_er_coalesce_only_on_hash_partition10632759 Ref: error_er_reorg_hash_only_on_same_no10632916 Ref: error_er_alter_tablespace_failed10633163 Ref: error_er_reorg_no_param_error10633354 Ref: error_er_only_on_range_list_partition10633604 Ref: error_er_add_partition_subpart_error10633754 Ref: error_er_add_partition_no_new_partition10633910 Ref: error_er_coalesce_partition_no_partition10634044 Ref: error_er_reorg_partition_not_exist10634183 Ref: error_er_same_name_partition10634326 Ref: error_er_no_binlog_error10634435 Ref: error_er_consecutive_reorg_partitions10634617 Ref: error_er_reorg_outside_range10634789 Ref: error_er_partition_function_failure10634989 Ref: error_er_part_state_error10635211 Ref: error_er_limited_part_range10635400 Ref: error_er_plugin_is_not_loaded10635590 Ref: error_er_event_col_count_doesnt_match10635698 Ref: error_er_wrong_value10635941 Ref: error_er_event_cannot_load_from_table10636087 Ref: error_er_no_partition_for_given_value10636346 Ref: error_er_filegroup_option_only_once10636542 Ref: error_er_create_filegroup_failed10636740 Ref: error_er_drop_filegroup_failed10636905 Ref: error_er_tablespace_auto_extend_error10637064 Ref: error_er_wrong_size_number10637278 Ref: error_er_size_overflow_error10637493 Ref: error_er_alter_filegroup_failed10637723 Ref: error_er_binlog_row_logging_failed10637886 Ref: error_er_binlog_row_wrong_table_def10638086 Ref: error_er_binlog_row_rbr_to_sbr10638293 Ref: error_er_event_already_exists10638563 Ref: error_er_event_store_failed10638728 Ref: error_er_event_does_not_exist10638929 Ref: error_er_warn_deprecated_statement10639087 Ref: error_er_event_cant_alter10639379 Ref: error_er_warn_deprecated10639537 Ref: error_er_event_drop_failed10639778 Ref: error_er_event_interval_not_positive_or_too_big10639929 Ref: error_er_event_ends_before_starts10640157 Ref: error_er_event_exec_time_in_the_past10640344 Ref: error_er_event_open_table_failed10640563 Ref: error_er_event_neither_m_expr_nor_m_at10640735 Ref: error_er_col_count_doesnt_match_corrupted10640929 Ref: error_er_cannot_load_from_table10641192 Ref: error_er_event_cannot_delete10641394 Ref: error_er_event_compile_error10641575 Ref: error_er_event_same_name10641753 Ref: error_er_event_data_too_long10641910 Ref: error_er_cant_read_lock_log_table10642077 Ref: error_er_drop_index_fk10642326 Ref: error_er_warn_deprecated_syntax_with_ver10642510 Ref: error_er_cant_write_lock_log_table10642767 Ref: error_er_cant_lock_log_table10642984 Ref: error_er_foreign_duplicate_key10643159 Ref: error_er_col_count_doesnt_match_please_update10643406 Ref: error_er_temp_table_prevents_switch_out_of_rbr10643733 Ref: error_er_stored_function_prevents_switch_binlog_format10644012 Ref: error_er_ndb_cant_switch_binlog_format10644292 Ref: error_er_partition_no_temporary10644541 Ref: error_er_partition_const_domain_error10644730 Ref: error_er_partition_function_is_not_allowed10644946 Ref: error_er_ddl_log_error10645156 Ref: error_er_null_in_values_less_than10645299 Ref: error_er_event_recursivity_forbidden10645497 Ref: error_er_wrong_partition_name10645753 Ref: error_er_cant_change_tx_isolation10645918 Ref: error_er_dup_entry_autoincrement_case10646150 Ref: error_er_event_modify_queue_error10646411 Ref: error_er_event_set_var_error10646587 Ref: error_er_partition_merge_error10646793 Ref: error_er_cant_activate_log10646979 Ref: error_er_rbr_not_available10647138 Ref: error_er_base64_decode_error10647324 Ref: error_er_event_recursion_forbidden10647495 Ref: error_er_events_db_error10647718 Ref: error_er_only_integers_allowed10647949 Ref: error_er_unsuported_log_engine10648128 Ref: error_er_bad_log_statement10648321 Ref: error_er_cant_rename_log_table10648505 Ref: error_er_wrong_paramcount_to_native_fct10648813 Ref: error_er_wrong_parameters_to_native_fct10649045 Ref: error_er_wrong_parameters_to_stored_fct10649267 Ref: error_er_native_fct_name_collision10649489 Ref: error_er_dup_entry_with_key_name10649697 Ref: error_er_binlog_purge_emfile10649968 Ref: error_er_event_cannot_create_in_the_past10650162 Ref: error_er_event_cannot_alter_in_the_past10650459 Ref: error_er_slave_incident10650754 Ref: error_er_no_partition_for_given_value_silent10650933 Ref: error_er_binlog_unsafe_statement10651156 Ref: error_er_slave_fatal_error10651356 Ref: error_er_slave_relay_log_read_failure10651506 Ref: error_er_slave_relay_log_write_failure10651694 Ref: error_er_slave_create_event_failure10651885 Ref: error_er_slave_master_com_failure10652057 Ref: error_er_binlog_logging_impossible10652234 Ref: error_er_view_no_creation_ctx10652425 Ref: error_er_view_invalid_creation_ctx10652604 Ref: error_er_sr_invalid_creation_ctx10652800 Ref: error_er_trg_corrupted_file10653002 Ref: error_er_trg_no_creation_ctx10653177 Ref: error_er_trg_invalid_creation_ctx10653369 Ref: error_er_event_invalid_creation_ctx10653572 Ref: error_er_trg_cant_open_table10653771 Ref: error_er_cant_create_sroutine10653949 Ref: error_er_slave_ambigous_exec_mode10654139 Ref: error_er_no_format_description_event_before_binlog_statement10654325 Ref: error_er_slave_corrupt_event10654635 Ref: error_er_load_data_invalid_column10654814 Ref: error_er_log_purge_no_file10655005 Ref: error_er_xa_rbtimeout10655173 Ref: error_er_xa_rbdeadlock10655366 Ref: error_er_need_reprepare10655570 Ref: error_er_delayed_not_supported10655741 Ref: error_warn_no_master_info10655927 Ref: error_warn_option_ignored10656100 Ref: error_warn_plugin_delete_builtin10656252 Ref: error_warn_plugin_busy10656433 Ref: error_er_variable_is_readonly10656610 Ref: error_er_warn_engine_transaction_rollback10656817 Ref: error_er_slave_heartbeat_failure10657101 Ref: error_er_slave_heartbeat_value_out_of_range10657286 Ref: error_er_ndb_replication_schema_error10657510 Ref: error_er_conflict_fn_parse_error10657727 Ref: error_er_exceptions_write_error10657921 Ref: error_er_too_long_table_comment10658112 Ref: error_er_too_long_field_comment10658303 Ref: error_er_func_inexistent_name_collision10658494 Ref: error_er_database_name10658773 Ref: error_er_table_name10658908 Ref: error_er_partition_name10659034 Ref: error_er_subpartition_name10659172 Ref: error_er_temporary_name10659319 Ref: error_er_renamed_name10659457 Ref: error_er_too_many_concurrent_trxs10659589 Ref: error_warn_non_ascii_separator_not_implemented10659777 Ref: error_er_debug_sync_timeout10660015 Ref: error_er_debug_sync_hit_limit10660183 Node: error-messages-client10660353 Ref: error_cr_unknown_error10661113 Ref: error_cr_socket_create_error10661190 Ref: error_cr_connection_error10661283 Ref: error_cr_conn_host_error10661409 Ref: error_cr_ipsock_error10661511 Ref: error_cr_unknown_host10661599 Ref: error_cr_server_gone_error10661691 Ref: error_cr_version_error10661779 Ref: error_cr_out_of_memory10661901 Ref: error_cr_wrong_host_info10661989 Ref: error_cr_localhost_connection10662064 Ref: error_cr_tcp_connection10662154 Ref: error_cr_server_handshake_err10662226 Ref: error_cr_server_lost10662316 Ref: error_cr_commands_out_of_sync10662416 Ref: error_cr_namedpipe_connection10662533 Ref: error_cr_namedpipewait_error10662612 Ref: error_cr_namedpipeopen_error10662728 Ref: error_cr_namedpipesetstate_error10662840 Ref: error_cr_cant_read_charset10662964 Ref: error_cr_net_packet_too_large10663070 Ref: error_cr_embedded_connection10663184 Ref: error_cr_probe_slave_status10663263 Ref: error_cr_probe_slave_hosts10663353 Ref: error_cr_probe_slave_connect10663441 Ref: error_cr_probe_master_connect10663531 Ref: error_cr_ssl_connection_error10663623 Ref: error_cr_malformed_packet10663708 Ref: error_cr_wrong_license10663785 Ref: error_cr_null_pointer10663931 Ref: error_cr_no_prepare_stmt10664015 Ref: error_cr_params_not_bound10664097 Ref: error_cr_data_truncated10664211 Ref: error_cr_no_parameters_exists10664284 Ref: error_cr_invalid_parameter_no10664385 Ref: error_cr_invalid_buffer_use10664474 Ref: error_cr_unsupported_param_type10664615 Ref: error_cr_shared_memory_connection10664731 Ref: error_cr_shared_memory_connect_request_error10664817 Ref: error_cr_shared_memory_connect_answer_error10664971 Ref: error_cr_shared_memory_connect_file_map_error10665123 Ref: error_cr_shared_memory_connect_map_error10665279 Ref: error_cr_shared_memory_file_map_error10665436 Ref: error_cr_shared_memory_map_error10665584 Ref: error_cr_shared_memory_event_error10665733 Ref: error_cr_shared_memory_connect_abandoned_error10665872 Ref: error_cr_shared_memory_connect_set_error10666007 Ref: error_cr_conn_unknow_protocol10666155 Ref: error_cr_invalid_conn_handle10666245 Ref: error_cr_secure_auth10666334 Ref: error_cr_fetch_canceled10666497 Ref: error_cr_no_data10666609 Ref: error_cr_no_stmt_metadata10666707 Ref: error_cr_no_result_set10666807 Ref: error_cr_not_implemented10666950 Ref: error_cr_server_lost_extended10667045 Ref: error_cr_stmt_closed10667225 Ref: error_cr_new_stmt_metadata10667396 Node: problems10667692 Node: what-is-crashing10668530 Node: common-errors10672807 Node: error-access-denied10674465 Node: can-not-connect-to-server10674859 Node: can-not-connect-to-server-on-windows10682778 Node: error-lost-connection10686529 Node: old-client10688304 Node: password-too-long10691508 Node: blocked-host10692429 Node: too-many-connections10694008 Node: out-of-memory10695986 Node: gone-away10696950 Node: packet-too-large10704261 Node: communication-errors10706813 Node: full-table10709826 Node: cannot-create10710581 Node: commands-out-of-sync10712097 Node: ignoring-user10712810 Node: cannot-find-table10714239 Node: cannot-initialize-character-set10715241 Node: not-enough-file-handles10716975 Node: table-corruption10720062 Node: installation-issues10720835 Node: file-permissions10721094 Node: administration-issues10722358 Node: resetting-permissions10722956 Node: resetting-permissions-windows10723943 Node: resetting-permissions-unix10727239 Node: resetting-permissions-generic10730673 Node: crashing10732227 Node: full-disk10740908 Node: temporary-files10743032 Node: problems-with-mysql-sock10745984 Node: timezone-problems10748218 Node: query-issues10749153 Node: case-sensitivity10749872 Node: using-date10754369 Node: problems-with-null10758911 Node: problems-with-alias10762294 Node: nontransactional-tables10764060 Node: deleting-from-related-tables10765906 Node: no-matching-rows10766656 Node: problems-with-float10768853 Node: optimizer-issues10773268 Node: table-definition-issues10775053 Node: alter-table-problems10775367 Node: temporary-table-problems10777338 Node: bugs10778617 Node: news10788302 Node: restrictions10789431 Node: stored-program-restrictions10790117 Ref: stored-routine-sql-restrictions10790908 Ref: stored-routines-function-restrictions10792992 Ref: stored-routines-trigger-restrictions10794604 Ref: stored-routine-name-conflicts10795813 Ref: stored-routines-replication-restrictions10796648 Ref: stored-routines-debugging-restrictions10797669 Ref: stored-routines-standard-restrictions10797750 Ref: stored-routines-event-restrictions10799314 Node: cursor-restrictions10805597 Node: subquery-restrictions10807618 Node: view-restrictions10813737 Node: xa-restrictions10820859 Node: charset-restrictions10823140 Node: limits10824689 Node: joins-limits10825260 Node: database-count-limit10825575 Node: table-size-limit10826144 Node: column-count-limit10831623 Node: limits-frm-file10836954 Node: limits-windows10839444  End Tag Table