Chapter 10 Upgrading or Downgrading MySQL

Configuration Changes

Server Changes

SQL Changes

Incompatible change: The InnoDB Plugin is included in MySQL 5.5 releases. It becomes the built-in version of InnoDB in MySQL Server, replacing the version previously included as the built-in InnoDB engine. InnoDB Plugin is also available in MySQL 5.1 as of 5.1.38, but it is an optional storage engine that must be enabled explicitly using two server options:

[mysqld]
ignore-builtin-innodb
plugin-load=innodb=ha_innodb_plugin.so

If you were using InnoDB Plugin in MySQL 5.1 by means of those options, you must remove them after an upgrade to 5.5 or the server will fail to start.

In addition, in InnoDB Plugin, the innodb_file_io_threads system variable has been removed and replaced with innodb_read_io_threads and innodb_write_io_threads. If you upgrade from MySQL 5.1 to MySQL 5.5 and previously explicitly set innodb_file_io_threads at server startup, you must change your configuration. Either remove any reference to innodb_file_io_threads or replace it with references to innodb_read_io_threads and innodb_write_io_threads.

Incompatible change: In MySQL 5.5, the server includes a plugin services interface that complements the plugin API. The services interface enables server functionality to be exposed as a “service” that plugins can access through a function-call interface. The libmysqlservices library provides access to the available services and dynamic plugins now must be linked against this library (use the -lmysqlservices flag). For an example showing how to configure for CMake, see MySQL Services for Plugins.

On Linux systems, the libaio library may be needed. Install it first, if it is not already present on your system.

Known issue: As of MySQL 5.5.32, for new installations, the url columns in the mysql database help tables are now created as type TEXT to accommodate longer URLs. For upgrades, 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;

Incompatible change: As of MySQL 5.5.3, due to work done for Bug #989, FLUSH TABLES is not permitted when there is an active LOCK TABLES ... READ. To provide a workaround for this restriction, FLUSH TABLES has a new variant, FLUSH TABLES tbl_list WITH READ LOCK, that enables tables to be flushed and locked in a single operation. As a result of this change, applications that previously used this statement sequence to lock and flush tables will fail:

LOCK TABLES tbl_list READ;
FLUSH TABLES tbl_list;

Such applications should now use this statement instead:

FLUSH TABLES tbl_list WITH READ LOCK;

Incompatible change: As of MySQL 5.5.7, the server requires that a new grant table, proxies_priv, be present in the mysql database. If you are upgrading to 5.5.7 from a previous MySQL release rather than performing a new installation, the server will find that this table is missing and exit during startup with the following message:

Table 'mysql.proxies_priv' doesn't exist

To create the proxies_priv table, start the server with the --skip-grant-tables option to cause it to skip the normal grant table checks, then run mysql_upgrade. For example:

mysqld --skip-grant-tables &
mysql_upgrade

Then stop the server and restart it normally.

You can specify other options on the mysqld command line if necessary. Alternatively, if your installation is configured so that the server normally reads options from an option file, use the --defaults-file option to specify the file (enter each command on a single line):

mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --skip-grant-tables &
mysql_upgrade

With the --skip-grant-tables option, the server does no password or privilege checking, so any client can connect and effectively have all privileges. For additional security, use the --skip-networking option as well to prevent remote clients from connecting.

Incompatible change: As of MySQL 5.5.7, InnoDB always uses the fast truncation technique, equivalent to DROP TABLE and CREATE TABLE. It no longer performs a row-by-row delete for tables with parent-child foreign key relationships. TRUNCATE TABLE returns an error for such tables. Modify your SQL to issue DELETE FROM table_name for such tables instead.

Incompatible change: Prior to MySQL 5.5.7, if you flushed the logs using FLUSH LOGS or mysqladmin flush-logs and 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:

mysqladmin flush-logs
mv host_name.err-old backup-directory

To avoid the preceding file-loss problem, no renaming occurs as of MySQL 5.5.7; 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:

mv host_name.err host_name.err-old
mysqladmin flush-logs
mv host_name.err-old backup-directory

Incompatible change: As of MySQL 5.5.6, handling of CREATE TABLE IF NOT EXISTS ... SELECT statements has been changed for the case that the destination table already exists:

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 CREATE TABLE IF NOT EXISTS ... 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 CREATE TABLE IF NOT EXISTS ... SELECT is changed in MySQL 5.1 as of 5.1.51:

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 CREATE TABLE IF NOT EXISTS and INSERT ... SELECT statements rather than CREATE TABLE IF NOT EXISTS ... 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 CREATE TABLE IF NOT EXISTS ... 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.5.6, if the server was started with character_set_server set to utf16, it crashed during full-text stopword initialization. Now the stopword file is loaded and searched using latin1 if character_set_server is ucs2, utf16, or utf32. If any table was created with FULLTEXT indexes while the server character set was ucs2, utf16, or utf32, it should be repaired using this statement:

REPAIR TABLE tbl_name QUICK;

Incompatible change: As of MySQL 5.5.5, all numeric operators and functions on integer, floating-point and DECIMAL values throw an “out of range” error (ER_DATA_OUT_OF_RANGE) rather than returning an incorrect value or NULL, when the result is out of the supported range for the corresponding data type. See Out-of-Range and Overflow Handling.

Incompatible change: In very old versions of MySQL (prior to 4.1), the TIMESTAMP 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 TIMESTAMP(N) columns with a MySQL 5.5 or later server:

You should try to handle potential issues of these types proactively by updating with ALTER TABLE any TIMESTAMP(N) columns in your databases so that they use TIMESTAMP instead, before performing any upgrades.

Incompatible change: As of MySQL 5.5.3, the Unicode implementation has been extended to provide support for supplementary characters that lie outside the Basic Multilingual Plane (BMP). Noteworthy features:

In most respects, upgrading to MySQL 5.5 should present few problems with regard to Unicode usage, although there are some potential areas of incompatibility. These are the primary areas of concern:

Consequently, if you want to upgrade tables from utf8 to utf8mb4 to take advantage of supplementary-character support, it may be necessary to change some column or index definitions.

For additional details about the new Unicode character sets and potential incompatibilities, see Unicode Support, and Converting Between 3-Byte and 4-Byte Unicode Character Sets.

Incompatible change: As of MySQL 5.5.3, the server includes dtoa, a library for conversion between strings and numbers by David M. Gay. In MySQL, this library provides the basis for improved conversion between string or DECIMAL values and approximate-value (FLOAT or DOUBLE) numbers.

Because the conversions produced by this library differ in some cases from previous results, the potential exists for incompatibilities in applications that rely on previous results. For example, applications that depend on a specific exact result from previous conversions might need adjustment to accommodate additional precision.

For additional information about the properties of dtoa conversions, see Type Conversion in Expression Evaluation.

Incompatible change: In MySQL 5.5, several changes were made regarding the language and character set of error messages:

For more information, see Setting the Error Message Language, and Error Message Character Set.

Incompatible change: MySQL 5.5 implements new functions used to calculate row placement for tables partitioned by KEY and LINEAR KEY. Tables that were created using KEY or LINEAR KEY partitioning in MySQL 5.1 can be upgraded in MySQL 5.5.31 and later using ALTER TABLE ... PARTITION BY ALGORITHM=2 [LINEAR] KEY (...). (Bug #14521864, Bug #66462)

Incompatible change: Previously, the parser accepted an INTO clause in nested SELECT statements, which is invalid because such statements must return their results to the outer context. As of MySQL 5.5.3, this syntax is no longer permitted and statements that use it must be changed.

Incompatible change: In MySQL 5.5.3, several changes were made to alias resolution in multiple-table DELETE statements so that it is no longer possible to have inconsistent or ambiguous table aliases.

Statements containing alias constructs that are no longer permitted must be rewritten.

Some keywords may be reserved in MySQL 5.5 that were not reserved in MySQL 5.1. See Keywords and Reserved Words.

System Tables.  The mysql.proc.comment column definition changed between MySQL 5.1 and 5.5. After downgrading from 5.5 to 5.1, this table is seen as corrupt and in need of repair. Running mysql_upgrade from the version of MySQL to which you downgraded (as documented in the downgrade procedures) reverts the mysql.proc.comment column definition.

InnoDB.  MySQL 5.5 uses InnoDB Plugin as the built-in version of InnoDB. MySQL 5.1 includes InnoDB Plugin as of 5.1.38, but as an option that must be enabled explicitly. See the Release Notes for MySQL 5.1.38.

Tables partitioned by [LINEAR] KEY.  MySQL 5.5 implements new functions used to calculate row placement for tables partitioned by KEY and LINEAR KEY. Tables that were created using KEY or LINEAR KEY partitioning in MySQL 5.5 cannot be used by a MySQL 5.1 server. In MySQL 5.5.31 and later, you can downgrade such tables with ALTER TABLE ... PARTITION BY ALGORITHM=1 [LINEAR] KEY (...) to make them compatible with MySQL 5.1.

MySQL External Authentication for Windows: Following uninstallation of this plugin, existing MySQL user accounts must be re-created using local authentication. See MySQL User Account Management, for more information.

MySQL External Authentication for PAM: Following uninstallation of this plugin, existing MySQL user accounts must be re-created using local authentication. See MySQL User Account Management, for more information.

MySQL Enterprise Thread Pool: Following uninstallation of this plugin, existing MySQL servers revert to default thread and connection handling.

MySQL Enterprise Audit: Following uninstallation of this plugin, no logging of user logins or query activity occurs.

MySQL High Availability: Following uninstallation of this plugin, automated failover is no longer available.

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.

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.