MySQL Bugs: #47450: ignore-builtin-innodb option not documented

Bug #47450	ignore-builtin-innodb option not documented
Submitted:	19 Sep 2009 9:33	Modified:	27 Aug 2010 17:01
Reporter:	Peter Laursen (Basic Quality Contributor)	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
Tags:	qc

Description:
1)
Shouldn't it here: http://dev.mysql.com/doc/refman/5.1/en/server-options.html ?
(like it is in 5.1.38 release notes)

2)
Also I tried starting server with
"ignore-builtin-innodb"
but without.
"plugin-load=innodb=ha_innodb_plugin.dll"
.. server won't start. So if I am right that first is invalid without second it should be documented as well.

3) 
Finally it should be documented how "ignore-builtin-innodb" and "skip-innodb" are evaluated - if they are valid at the same time etc.

How to repeat:
see above

Suggested fix:
see above

This is documented at http://dev.mysql.com/doc/refman/5.1/en/innodb-parameters.html#sysvar_ignore_builtin_innodb

I am sorry, but I do not agree. But thanks for the link anyway.

From your link: "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."

1)
No mentioning that '--ignore-builtin-innodb' without spcifying the innodb pluging is valid. With '--ignore-builtin-innodb' alone server won't start in my experience. 

2)
"which causes the server to behave as if the built-in InnoDB is not present". Literally understood this should mean that '--ignore-builtin-innodb' without spcifying the innodb pluging is equivalent to --skip-innodb

3)
If http://dev.mysql.com/doc/refman/5.1/en/innodb-parameters.html#sysvar_ignore_builtin_innodb means what it says "This section describes the InnoDB-related command options and system variables." then --skip-innodb should also be listed here (it is in the table view only, but no description or link below)

4) 
No explanation about the difference between --skip-innodb and --ignore-builtin-innodb and how they are avaluated together.  Reading descriptions of each (in two different pages) does not clarify much.

Please reconsider each above.

1. --ignore-builtin-innodb works for me without innodb plugin. As far as I remember, you're mainly using windows - perhaps you have default-storage-engine=innodb ? That won't work without innodb, right.

2. no, it's not equivalent. With --skip-innodb the server knows that InnoDB is compiled in, but disabled. SHOW ENGINES for example will reflect that. With --ignore-builtin-innodb the server will ignore the builtin innodb altogether.

reply to Sergey's questions:

1) yes - I have default-storage-engine=innodb.  Good point and thanks!

2)
"no, it's not equivalent. With --skip-innodb the server knows that InnoDB is compiled in, but disabled."  That is not how I read the docs ("which causes the server to behave as if the built-in InnoDB is not present").  But 'not present' is not very exact. It can be 'not present' for more reasons (not compiled, standard innodb disabled and/or innodb plugin not enabled).  SHOW ENGINES does not have output like "NOT PRESENT". If you think I am pedantic here I can tell that I can now been trying for 3-4 hours to understand docs as compared to the server behavior I see with all builds available from 5.1.38 and up (and server output to queries about metadata and configuration details is very important for us). It makes sense to request a description the differences of the two options in detail I think. And still can I use both at the same time?  They should both have a note that they cannot be use along with the other or (if possible t ohave both) which one takes precedence.  Such details are important.  The manual need to be a quick reference and there should be no need to experiment for hours as I did.

3)
"SHOW ENGINES for example will reflect that."   Should I understand that with  --skip-innodb SHOW ENGINES would return DISABLED and with --ignore-builtin-innodb SHOW ENGINES would return NO? That is not what I see as reported here: http://bugs.mysql.com/bug.php?id=47452. With --skip-innodb SHOW ENGINES returns NO and without --skip-innodb InnoDB is not listed in SHOW ENGINES output at all.  And what about SHOW VARIABLES LIKE 'have_innodb'? Why the inconsistence between the two statements?

Now it is a little confusing what builds I could reasonably test (maybe the 5.1.39 on FTP will never be released as it is). Anyway I think SHOW ENGINES/SELECT FROM I_S.ENGINES as well as SHOW VARIABLES LIKE 'have_innodb' should be verified against the lastest 5.1.39 source tree from bzr (if different from 5.1.39 available on FTP).

2) "not present" as in completely absent, does not exist, "not compiled in". If it is simply disabled it's "present but disabled".

Everything else follow from it. For example - using both options at the same time - with --ignore-builtin-innodb the server behaves as if no innodb was compiled in. So, naturally, --skip-innodb won't be recognized. But (!) if you have installed dynamic innodb plugin, then --skip-innodb will work, it'll disable dynamic innodb plugin.

3) Sorry, my mistake. SHOW ENGINES doesn't show "disabled", SHOW PLUGINS does.

Updated description for --ignore-builtin-innodb:

This option causes the server to behave as if the built-in InnoDB is
not present. If InnoDB Plugin is not used in place of the built-in
InnoDB, other InnoDB options will not be recognized and should not be
used. In addition, the server will not start if the default storage
is set to InnoDB. Use --default-storage-engine to set the default to 
some other engine if necessary. 

Updated description for --innodb:

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.

To disable InnoDB, use --innodb=OFF or --skip-innodb. In this case,
the server will not start if the default storage is set to InnoDB.
Use --default-storage-engine to set the default to some other engine 
if necessary.

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.

Second revised descriptions:

For --ignore-builtin-innodb:

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 Section 13.6.2.1, “Using InnoDB Plugin Instead of the Built-In 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 InnoDB 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 InnoDB. Use --default-storage-engine to set the default to some other engine if necessary.

* InnoDB will not appear in the output of SHOW ENGINES.

For --innodb:

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 Section 5.1.3, “Server Options for Loading Plugins”.

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 InnoDB. Use --default-storage-engine to set the default to some other engine if necessary.