Learning About InnoDB – Finding Docs

With all the changes surrounding Sun and MySQL joining Oracle, and InnoDB becoming part of the MySQL organization, let’s recap how and where to find information related to InnoDB, so first-time users can learn InnoDB from the ground up, and long-time users can keep up with the latest developments.

MySQL 5.1

In MySQL 5.1, the MySQL Reference Manual has information about the InnoDB storage engine in the Storage Engine chapter.

To take advantage of the latest InnoDB features and performance improvements in the 5.1 release, you’ll need to start using the InnoDB Plugin. The InnoDB Plugin went through a series of “Early Adopter” releases, reaching GA status with InnoDB 1.0.x. So this is the level of InnoDB that you should be using with 5.1, and it comes with 5.1, but requires action on your part to enable it. The InnoDB Plugin has its own manual that discuss features like fast index creation, table compression, file-format management, and many performance enhancements.

If you are used to going to the InnoDB web site for the InnoDB Plugin documentation, you can still find it there, for the 1.0.x Plugin anyway. However, all these links redirect to the dev.mysql.com site where the latest, authoritative documentation lives.

MySQL 5.5

In MySQL 5.5, there’s only one instance of InnoDB. It’s descended from the InnoDB Plugin, but it’s fully integrated with MySQL; it doesn’t require any extra installation or configuration steps to enable its features. This is what we call InnoDB 1.1, dropping the “Plugin” name. (Although we put so much effort into publicizing the “Plugin” name that you might still see stray references to “InnoDB Plugin” in 5.5. That just means the latest InnoDB that has all the features like fast index creation and table compression, that originated with the InnoDB Plugin.)

The InnoDB Plugin manual continues in MySQL 5.5, now just called the “InnoDB 1.1″ manual. This manual is available from the dev.mysql.com doc page.

The tighter integration of InnoDB 1.1 back into MySQL 5.5 means we also fold the former InnoDB Plugin documentation into the MySQL Reference Manual for 5.5. It appears in the Storage Engine chapter, as a new major section, the InnoDB 1.1 addendum.

In MySQL 5.5, InnoDB becomes the default storage engine. Some of the former InnoDB-only or InnoDB Plugin-only features and options thus are now standard out-of-the-box behavior of MySQL 5.5. To make all these changes easier for new users to find and learn, we move some information _out_ of the Storage Engine / InnoDB section to other, more prominent locations. For example, InnoDB-related performance guidelines and tips are now part of the Optimization chapter.

This process of parcelling out InnoDB-specific details, and de-emphasizing MyISAM-specific behavior, is a long-term project. You can expect to see these types of doc enhancements throughout the 5.5 life cycle.

Change History / Change Log

When the MySQL and InnoDB teams merged their development processes and timelines, the former InnoDB change log was folded into the Change History section of the MySQL Reference Manual.

In MySQL 5.1, we stopped making new change history sections in the InnoDB Plugin documentation, around InnoDB 1.0.8 / MySQL 5.1.4x. The relevant entries go into the MySQL change history for 5.1.4x, 5.1.4y, 5.1.4z, and so on. Since 5.1 has both the built-in InnoDB and the optional InnoDB Plugin, we specify which bug fixes apply to the built-in, the Plugin, or both. The web page on innodb.com that displayed the change log also is no longer update, replaced by the change log information in the MySQL Reference Manual.

Also in MySQL 5.1, we start de-emphasizing the separate InnoDB Plugin 1.0.x release number, because it increments along with the MySQL 5.1.y version number. Thus you report InnoDB Plugin bugs against a release like MySQL 5.1.47, and it might be fixed in MySQL 5.1.50. (Rather than referring to InnoDB Plugin 1.0.8 and InnoDB Plugin 1.0.10.)

In MySQL 5.5, the InnoDB manual contains only a very brief change history, because MySQL 5.5 + InnoDB 1.1 debuted at the 2010 MySQL User Conference, and immediately afterward we started folding the change history information into the MySQL Reference Manual.

InnoDB Glossary

For the benefit of new users, switchers from competitive databases, and users who do not spend their spare time delving into the InnoDB source code, we have compiled an InnoDB glossary to define InnoDB-specific and MySQL-specific terminology.

This glossary is included in the InnoDB Plugin manual (for MySQL 5.1) and the InnoDB 1.1 manual (for MySQL 5.5). To avoid blowing up the MySQL Reference Manual even more, that material is not embedded in the full Reference Manual. When possibly unfamiliar terms are introduced in the InnoDB-specific documentation, or anywhere in the MySQL Reference Manual, we may cross-link to the relevant glossary definition. From any definition, you can trace back to related terms, so that you can refresh your memory with some quick facts, or build your understanding from the ground up so that you can follow jargon-filled discussions.

INFORMATION_SCHEMA

Some new InnoDB-related INFORMATION_SCHEMA tables were first documented in the InnoDB Plugin manual. For MySQL 5.5 and higher, this information is in the INFORMATION_SCHEMA chapter in the MySQL Reference manual.

PERFORMANCE_SCHEMA

There is some InnoDB-specific output in the PERFORMANCE_SCHEMA tables of MySQL 5.5 and higher. The detailed information about the output is in the PERFORMANCE_SCHEMA chapter. A summary and InnoDB-related guidelines are part of the InnoDB information in the Storage Engine chapter.

Performance

In MySQL 5.1, the InnoDB Plugin manual included information about performance enhancements, a mix of guidelines and “FYI” explanations. The Storage Engine section about InnoDB included some InnoDB performance tips. In MySQL 5.5 and higher, all this information is centralized in the Optimization chapter of the MySQL Reference Manual.

Fast Index Creation

With InnoDB becoming the default storage engine in MySQL 5.5, including all the former InnoDB Plugin features, everyone will be able to take advantage of the “Fast Index Creation” feature out of the box. Currently, the information about this feature remains in the InnoDB 1.1 addendum, because you do not really need to do anything to get the benefits of this feature. You need to be aware of it mainly in the context of troubleshooting for performance issues.

Table Compression

With InnoDB becoming the default storage engine in MySQL 5.5, including all the former InnoDB Plugin features, everyone will be able to take advantage of the “Table Compression” feature out of the box. Currently, the detailed information about this feature remains in the InnoDB 1.1 addendum.

The SQL syntax for this feature (the ROW_FORMAT=COMPRESSED keywords) isn’t fully documented in the SQL syntax section for CREATE TABLE, but will be!

DYNAMIC and COMPRESSED Row Formats

The detailed information about the storage format for DYNAMIC and COMPRESSED row formats, especially the way that BLOB and long VARCHAR columns are represented by off-page storage, currently remains in the InnoDB 1.1 addendum in the MySQL 5.5 Reference Manual. It is primarily useful for understanding and diagnosing issues of performance and storage usage.

Upgrading and Downgrading

In MySQL 5.1, the InnoDB Plugin manual was concerned with upgrade/downgrade issues going between the built-in InnoDB and the InnoDB Plugin. In MySQL 5.5, with only one instance of InnoDB, the upgrade and downgrade scenarios involve going between different MySQL Releases, such as MySQL 5.1 -> 5.5 or vice versa. Consequently, any upgrade and downgrade considerations are documented in the Upgrade and Downgrade chapters in the MySQL Reference Manual.

Upgrading to 5.5, be sure to run a complete set of compatibility tests with all your applications. With InnoDB becoming the default storage engine in MySQL 5.5, and certain configuration settings having new defaults, you might experience some unexpected results when upgrading. For example, the innodb_file_per_table setting is turned on, producing a separate .ibd file for each InnoDB table, rather than a single giant InnoDB tablespace. Because tables with no ENGINE= clause will be InnoDB tables, you may end up with very different data file layout than in previous releases, or encounter issues if you rely on MyISAM-specific features without explicity creating MyISAM tables in your application’s installation/setup routines.

If you use any InnoDB Plugin-specific features in MySQL 5.5, then a downgrade to MySQL 5.1 might require enabling the InnoDB Plugin with 5.1. For example, you could not create a compressed table in MySQL 5.5, and then downgrade to MySQL 5.1 with the built-in InnoDB.