MySQL Bugs: #49792: innodb_file_format_check: default and allowed values?

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:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:		OS:	Any
Assigned to:	Paul DuBois	CPU Architecture:	Any

Description:
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:

innodb_file_format_check
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:

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

What's the real story here?

How to repeat:
See above.

Thank you for the bug report.

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:

innodb_file_format_check_validate()
{

               if (innobase_file_format_check_on_off(file_format_input)) {
                        push_warning_printf(thd,
                                MYSQL_ERROR::WARN_LEVEL_WARN,
                                ER_WRONG_ARGUMENTS,
                                "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.

Thanks
Jimmy

See also: BUG#50442.

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():
ha_innobase::open()/ha_innobase::create()
{
.....
if (prebuilt->table) {
/* We update the highest file format in the system table
space, if this table has higher file format setting. */

trx_sys_file_format_max_upgrade(
(const char**) &innobase_file_format_max,
dict_table_get_format(prebuilt->table));
}
}

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.

Jimmy, thanks for the info. I'll reclassify this as a docs bug now and assign to myself.

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
variable. 

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.