MySQL Bugs: #77829: "Alter table syntax" and "online ddl" section should be clarified

Bug #77829	"Alter table syntax" and "online ddl" section should be clarified
Submitted:	24 Jul 2015 13:09	Modified:	28 Jul 2015 19:59
Reporter:	Shahriyar Rzayev	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.7.7-rc	OS:	Any (7)
Assigned to:		CPU Architecture:	Any

Description:
http://dev.mysql.com/doc/refman/5.7/en/alter-table.html

It says that, we will see an error:

"As of MySQL 5.7.4, ALTER TABLE upgrades old temporal columns to 5.6 format for ADD COLUMN, CHANGE COLUMN, MODIFY COLUMN, ADD INDEX, and FORCE operations. This conversion cannot be done using the INPLACE algorithm because the table must be rebuilt, so specifying ALGORITHM=INPLACE in these cases results in an error. Specify ALGORITHM=COPY if necessary."

But there is no error:

mysql> alter table t1 ALGORITHM=INPLACE, add column a1 varchar(5) default null;
Query OK, 0 rows affected (1 min 58.42 sec)
Records: 0  Duplicates: 0  Warnings: 0

Again in same page:

"You can also use ALTER TABLE tbl_name FORCE to perform a “null” alter operation that rebuilds the table. Previously the FORCE option was recognized but ignored. As of MySQL 5.7.4, online DDL support is provided for the FORCE option."

But in: 
http://dev.mysql.com/doc/refman/5.7/en/innodb-create-index-overview.html

In section:
Table 14.8 Summary of Online Status for DDL Operations.

There is a point to "FORCE" -> Uses ALGORITHM=INPLACE as of MySQL 5.6.17. 

How to repeat:
Read documentation:
http://dev.mysql.com/doc/refman/5.7/en/alter-table.html
http://dev.mysql.com/doc/refman/5.7/en/innodb-create-index-overview.html

Suggested fix:
Provided in description.

These are indeed small mistakes in our documentation, which have to be fixed.

Fully verified.

The ALTER TABLE documentation has been updated to indicate that "ALTER TABLE
upgrades *MySQL 5.5* temporal columns to 5.6 format
for ADD COLUMN, CHANGE COLUMN, MODIFY COLUMN, ADD INDEX, and FORCE
operations."

The error should occur if you attempt an in-place ALTER TABLE ... ADD COLUMN,
CHANGE COLUMN, MODIFY COLUMN, ADD INDEX, or FORCE operation in MySQL 5.6.16 /
MySQL 5.7.4 or later on a MySQL 5.5 table with a temporal column that has not
been converted to 5.6 format. (See Bug #17246318).

In "Summary of Online Status for DDL Operations" in the 5.7 reference manual,
the version information was incorrect. It should have stated,
"Uses ALGORITHM=INPLACE as of MySQL 5.7.4".

Thank you for the bug report.