Bug #49792 innodb_file_format_check: default and allowed values?
Submitted: 18 Dec 2009 0:52 Modified: 12 Jul 2010 17:04
Reporter: Paul DuBois Email Updates:
Status: Closed Impact on me:
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version: OS:Any
Assigned to: Paul DuBois CPU Architecture:Any

[18 Dec 2009 0:52] Paul DuBois
This is a docs issue, but I am filing this report as a request for information from the InnoDB developers.

http://www.innodb.com/doc/innodb_plugin-1.0/innodb-parameter-changes.html says this about innodb_file_format_check:

Table C.1. InnoDB Plugin new parameter summary

Name	Cmd-Line	Option File	System Var	Scope	Dynamic	Default
innodb_file_format_check	YES	YES	YES	GLOBAL	YES	ON

That is, a default of "ON".

And the section also says:

Whether InnoDB performs file format compatibility checking when opening a database. The default value is ON. This parameter was added in InnoDB Plugin 1.0.1. See Section 4.4.1, “Startup File Format Compatibility Checking” for more information.

That is, a default of "ON".

Also, if I check here: http://www.innodb.com/doc/innodb_plugin-1.0/innodb-file-format.html#innodb-file-format-com...
I see only that innodb_file_format_check is described as having values of ON or OFF.

But I find this variable to always have a default value of a file format name.  From 5.1.38 to 5.1.41 (InnoDB Plugin 1.0.4 or 1.0.5), I get this:

mysql> show variables like 'innodb_file_format_check';
| Variable_name            | Value    |
| innodb_file_format_check | Antelope |

In 5.1.42+ (InnoDB Plugin 1.0.6) , I get this:

mysql> show variables like 'innodb_file_format_check';
| Variable_name            | Value     |
| innodb_file_format_check | Barracuda |

What's the real story here?

How to repeat:
See above.
[18 Dec 2009 2:36] MySQL Verification Team
Thank you for the bug report.
[29 Dec 2009 3:12] Jimmy Yang
Apparently, this parameter needs better documentation. From design, this parameter has different meaning during server start up time and run time. During server start up time, "on/off" are its possible choices. And in the run time, it represents the max possible file format for the server.

In innodb_file_format_check validation function, it states the "on/off" can only be specified during server startup time or in the configuration file for innodb_file_format_check:


               if (innobase_file_format_check_on_off(file_format_input)) {
                                "InnoDB: invalid innodb_file_format_check "
                                "value; on/off can only be set at startup or "
                                "in the configuration file");

During the run time, this innodb_file_format_check represents the highest possible format id for this server release and it uses trx_sys_file_format_max_set to update file format tag. For plugin release, the max format id is "Barracuda" as we recently fixed.

Calvin probably will provide more information on this parameter.

[22 Jan 2010 13:14] Luis Soares
See also: BUG#50442.
[24 Jun 2010 12:50] Jimmy Yang
In 5.1, innodb_file_format_check has overloaded two sets of values:

1) on/off, to decide whether to do the file format check
2) max file format name, record the maximum file format used in the server.

The "on/off" should be set at the server startup time or in configure file. And most likely a read only option. While the max file format values can be set to innodb_file_format_check at run time.

We used to set "on" as the default value, however, this causes problem when user issues command "set innodb_file_format_check=default", as at the run time we expect a file format name rather than on/off.
So we fixed this in #47167 by setting the default value from "on" to "Barracuda". That is why you see the difference.

In 5.5, we will split the two options, and add innodb_file_format_max (done in 53654). Following are some introduction on the two parameters 

1. innodb_file_format_check - this option is a start up command line option (can be set in configure file) only, during run time, it is read only. This option tells server whether it needs to check the file format in file system table, and compare it with DICT_TF_FORMAT_MAX (the hard coded highest file format supported for this server) and block the server start up.

The actual check is performed in trx_sys_file_format_max_check().

2. the newly added "innodb_file_format_max" - this system variable can be set during startup time as well as at run time. It is a mirror mapping with the file format tag in the system table space. Interestingly, it is a value can be changed in several occasions:
a) During first time start up with a newly build server installation, it is initialized as  DICT_TF_FORMAT_51 ("Antelope") by trx_sys_file_format_init().

b) By user using "set global innodb_file_format_max=..." with innodb_file_format_max_update().

c) By creating/opening a table with newer file format than the current value using trx_sys_file_format_max_upgrade():
        if (prebuilt->table) {
                /* We update the highest file format in the system table
                space, if this table has higher file format setting. */

                        (const char**) &innobase_file_format_max,

The "innodb_file_format_check" used to assume the role of this "innodb_file_format_max" during run time, however, it is hard to document the dual role without some confusion, even without the complexity of this "innodb_file_format_max" variable.

By looking at this variable, we notice it can be changed automatically by the server, if server discovers a newer file format than the current value. So it is a "settable" "high water marker" in the server. By allowing user to set it, it provides a means for user to access the tag in the system file space. So users can manually downgrade it if they decided to downgrade the server (boot a newer database installation with older server).

3) innodb_file_format - It is a dynamic variable used to specify file format for new InnoDB tables. We have not change any aspect of this variable. As documented, "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."

In summary, by adding the innodb_file_format_max, innodb_file_format_check will really play the role of deciding whether to check the file format constraint. And innodb_file_format_max will act the role of a "high water mark" representation of the file format used in the server. Its behavior described above should be well documented.
[7 Jul 2010 15:46] Paul DuBois
Jimmy, thanks for the info. I'll reclassify this as a docs bug now and assign to myself.
[12 Jul 2010 17:04] Paul DuBois
Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.

Noted in 5.5.5 changelog.

Previously, the innodb_file_format_check system variable could 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. This behavior overloads the functions of
whether to check the tag and recording the tag onto a single

Now, checking and recording the file format tag are handled using
separate variables. innodb_file_format_check 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. If the tag is checked and is 
higher than that supported by the current version of InnoDB, an error
occurs and InnoDB does not start. If the tag is not higher, InnoDB
sets the value of innodb_file_format_max to the file format tag.