MySQL Bugs: #120268: Clarify Symbolic Link Usage and Alternative for InnoDB

Bug #120268	Clarify Symbolic Link Usage and Alternative for InnoDB
Submitted:	14 Apr 19:38
Reporter:	Jean-François Gagné	Email Updates:
Status:	Open	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S1 (Critical)
Version:	5.7, 8.0, 8.4, 9.x	OS:	Any
Assigned to:		CPU Architecture:	Any

Description:
Hi,

In the documentation page about [1], I read below and understand "InnoDB does not support Symbolic Links".

[1]: https://dev.mysql.com/doc/refman/8.4/en/innodb-create-table-external.html

> Using the DATA DIRECTORY clause to create a table in an external directory is an alternative to using symbolic links, which InnoDB does not support.

This is ok, but such mention is missing at least at two other critical places (hence this bug being opened as Critical):

- Using Symbolic Links [2]

- Using Symbolic Links for Databases on Unix [3]

[2]: https://dev.mysql.com/doc/refman/8.4/en/symbolic-links.html

[3]: https://dev.mysql.com/doc/refman/8.4/en/symbolic-links-to-databases.html

This is particularly problematic as [3] gives a useful procedure for solving a classic dba problem (filesystem full), and that a dba could use it on InnoDB without knowing it is unsupported.  It is even more critical because this opens the risk of hitting a crashing (many reports: Bug#120156, Bug#119554, Bug#117660 and Bug#117210).

I think both [2] and [3] above should mention Symbolic Links not being supported for InnoDB with the alternatives, which are:

- Creating Tables Externally [4]

- Moving Tablespace Files While the Server is Offline [5]

[4]: https://dev.mysql.com/doc/refman/8.4/en/innodb-create-table-external.html

[5]: https://dev.mysql.com/doc/refman/8.4/en/innodb-moving-data-files-offline.html

Also, I think something is missing from Moving Tablespace Files While the Server is Offline [5]: from what I understand, this needs innodb_validate_tablespace_paths [6] to be set to ON, which is not mentioned in [5].

[6]: https://dev.mysql.com/doc/refman/8.4/en/innodb-parameters.html#sysvar_innodb_validate_tabl...

There might be other places in the doc where it should be made clear that symlinks are not supported, an example is the 
Server Command Option symbolic-links [7].

[7]: https://dev.mysql.com/doc/refman/8.4/en/server-options.html#option_mysqld_symbolic-links

The links in this bug are for 8.4, but from what I see, the 5.7, 8.0, and 9.x doc are also affected.

Many thanks for looking into this,

Jean-François Gagné

How to repeat:
Read the doc.

Suggested fix:
See Description.