WL#10322: InnoDB: Deprecate innodb_undo_logs in 5.7

Affects: Server-8.0 — Status: Complete

Description
Requirements
High Level Architecture

Due to a redesign of undo tablespaces in v8.0 in WL9507 the setting
innodb_undo_logs will be deleted. So it should be deprecated in 5.7.

The setting innodb_undo_logs has been an alias for innodb_rollback_segments
since it was introduced in v5.6 with WL#5535 - Separate tablespace(s) for the
InnoDB undo log.  

With WL9507, v8.0 will no longer use the words "undo log" to refer to a rollback
segment. In WL9507, the original setting, innodb_rollback_segments, will remain.  

The redesign in WL9507 allows each undo tablespace to contain this number of
rollback segments.  In 5.7 and earlier, Rollback segments are only tracked in
the TRX_SYS page of the system tablespace so the whole database was limited by
the number of rollback segments in this setting.  So in v8.0, the meaning of the
innodb_rollback_segments setting will change to "number of rollback segments per
undo tablespace. The undo tablespaces that this applies to are the system
tablespace, the shared temporary tablespace, and any
other undo tablespace. 

In addition, the status variable innodb_available_undo_logs will also be deleted
in the same WL9507.  The number of available rollback segments per tablespace
will always be view-able by:

   SHOW VARIABLES LIKE 'innodb_rollback_segments';
This status variable should be deprecated in the documentation only. Since it is
not a setting, it cannot be changed explicitly.

FR1:  If --innodb-undo-logs=n is used on the command line a deprecation warning
message will appear in the error log when n is not the default value of 128.

FR2:  If innodb_undo_logs=n is used in a config file a deprecation warning
message will appear in the error log when n is not the default value of 128.

FR3:  If SET GLOBAL innodb_undo_logs=n is used in SQL a deprecation warning
message will appear in the error log and the same message is returned as a 
warning.

The following code changes were made in v5.6 in ha_innodb.cc:

/* Alias for innodb_undo_logs, this config variable is deprecated. */

static MYSQL_SYSVAR_ULONG(rollback_segments, srv_undo_logs,

 PLUGIN_VAR_OPCMDARG,

"Number of undo logs to use (deprecated).",

+ "Number of rollback segments to use.",

 NULL, NULL,
 TRX_SYS_N_RSEGS,	/* Default setting */
 1,			/* Minimum value */
 TRX_SYS_N_RSEGS, 0);	/* Maximum value */

static MYSQL_SYSVAR_ULONG(undo_logs, srv_undo_logs,

 PLUGIN_VAR_OPCMDARG,

"Number of undo logs to use.",

+ "Number of rollback segments to use.",

 NULL, NULL,
 TRX_SYS_N_RSEGS,	/* Default setting */
 1,			/* Minimum value */
 TRX_SYS_N_RSEGS, 0);	/* Maximum value */

This worklog will reverse that and do a more complete deprecation. The following changes will be made:

1) Change the declaration of innodb_undo_logs and innodb_rollback_segments as follows:

Code Changes v5.7+wl10322 in ha_innodb.cc:

/* Alias for innodb_undo_logs, this config variable is deprecated. */

static MYSQL_SYSVAR_ULONG(rollback_segments, srv_undo_logs,

+static MYSQL_SYSVAR_ULONG(rollback_segments, srv_rollback_segments,

  PLUGIN_VAR_OPCMDARG,

"Number of undo logs to use (deprecated).",

+ "Number of rollback segments to use for storing undo logs.",

  NULL, NULL,
  TRX_SYS_N_RSEGS,	/* Default setting */
  1,			/* Minimum value */

-static MYSQL_SYSVAR_ULONG(undo_logs, srv_undo_logs,

+static MYSQL_SYSVAR_ULONG(undo_logs, srv_rollback_segments,

  PLUGIN_VAR_OPCMDARG,

"Number of undo logs to use.", - NULL, NULL,

+ "Number of rollback segments to use for storing undo logs. (deprecated)", + NULL, innodb_undo_logs_update,

  TRX_SYS_N_RSEGS,	/* Default setting */
  1,			/* Minimum value */
  TRX_SYS_N_RSEGS, 0);	/* Maximum value */

2) The new function innodb_undo_logs_update() will put warning messages in the error log and return that warning to the SQL interface. This is only called by the server when the setting is changed in SQL while online.

3) If the setting is used at startup and has a value other than the default (128), then the deprecation warning will be put into the error log.

4) References in the code to srv_undo_logs will be changed to srv_rollback_segments.

5) References to innodb_undo_logs in collections and all but one testcase will be changed to innodb_rollback_segments. The one testcase is sys_vars.innodb_undo_logs_basic.test.

Documentation v5.6

https://dev.mysql.com/doc/refman/5.6/en/innodb-parameters.html#sysvar_innodb_rollback_segments "This setting, while still valid, is replaced by innodb_undo_logs." Replace with; "The innodb_rollback_segments option is an alias for innodb_undo_logs."

https://dev.mysql.com/doc/refman/5.6/en/innodb-parameters.html#sysvar_innodb_undo_logs "The innodb_undo_logs option replaces innodb_rollback_segments." Replace with; "The innodb_undo_logs option is an alias for innodb_rollback_segments." Consider duplicating all the text under innodb_undo_logs to innodb_rollback_segments.

https://dev.mysql.com/doc/refman/5.6/en/innodb-parameters.html#sysvar_innodb_undo_logs "The innodb_undo_logs option replaces innodb_rollback_segments." Replace with; "The innodb_undo_logs option is an alias for innodb_rollback_segments. Future versions will not use the innodb_undo_logs setting."

Consider duplicating all the text under innodb_undo_logs to innodb_rollback_segments.