[MDEV-28671] Presentation of aliases in `mariadbd --verbose --help` is highly redundant Created: 2022-05-25  Updated: 2024-01-23

Status: Stalled
Project: MariaDB Server
Component/s: None
Fix Version/s: 10.11, 11.5

Type: Task Priority: Critical
Reporter: Daniel Lenski Assignee: Sergei Golubchik
Resolution: Unresolved Votes: 0
Labels: beginner-friendly

Issue Links:
Blocks
blocks MDEV-29297 remove aliases of system variables Open
blocks MDEV-30731 Deprecated variables are not consiste... Open
PartOf
includes MDEV-30332 PLUGIN_VAR_DEPRECATED fails to throw ... Closed

 Description   

There are many mariadbd command-line options and system variables which have aliases or alternate names:

In some cases (e.g. --old-alter-table vs. --alter-algorithm), some of the names are deprecated.

In other cases (e.g. --tmp-memory-table-size vs. --tmp-table-size), there's no clear distinction in terms of deprecation/preference.

In all cases, the options/variable are listed multiple times in the mariadb --verbose --help output, with:

  • Almost entirely redundant content.
  • No consistent way in which the aliases or other names are presented.

In order to simplify the documentation, it would be beneficial to combine the listing of these options in the verbose help text.

Examples of how options with multiple names are shown now

$ mariadbd --verbose --help
 
  ...
 
  --alter-algorithm[=name] 
                      Specify the alter table algorithm. One of: DEFAULT, COPY,
 
                      INPLACE, NOCOPY, INSTANT
 
  …
 
  --old-alter-table[=name] 
                      Alias for alter_algorithm. Deprecated. Use
 
                      --alter-algorithm instead.. One of: DEFAULT, COPY, 
                      INPLACE, NOCOPY, INSTANT
 
  ...
 
  --tmp-memory-table-size=# 
                      If an internal in-memory temporary table exceeds this
 
                      size, MariaDB will automatically convert it to an on-disk
 
                      MyISAM or Aria table. Same as tmp_table_size.
 
  --tmp-table-size=#  Alias for tmp_memory_table_size. If an internal in-memory
 
                      temporary table exceeds this size, MariaDB will
 
                      automatically convert it to an on-disk MyISAM or Aria
 
                      table.

How these should be shown

This format will considerably shorten the verbose help output, enable users to quickly recognize aliases, and identify which of those aliases are deprecated.

$ mariadbd --verbose --help
 
  ...
 
  --alter-algorithm[=name] 
  --old-alter-table[=name]    (Deprecated)
 
                      Specify the alter table algorithm. One of: DEFAULT, COPY,
 
                      INPLACE, NOCOPY, INSTANT
 
  …
 
  --tmp-memory-table-size=# 
  --tmp-table-size=#
 
                      If an internal in-memory temporary table exceeds this
 
                      size, MariaDB will automatically convert it to an on-disk
 
                      MyISAM or Aria table.



 Comments   
Comment by Daniel Black [ 2022-05-25 ]

Good call in removing deprecated options here.

Be a bit careful however, the --help --verbose text is used by machine parsing in some circumstances.

Comment by Daniel Lenski [ 2022-05-25 ]

Thanks! To be clear, I wasn't proposing to remove them entirely from the listing, but simply to list them as deprecated; although if you're okay with simply removing the ones that are deprecated, I'd be in favor of that too.

Be a bit careful however, the --help --verbose text is used by machine parsing in some circumstances.

From the comment preceding that line, it looks like the verbose help text is only parsed because my_print_defaults is missing some of the relevant information. (https://github.com/MariaDB/mariadb-docker/blob/master/docker-entrypoint.sh#L111-L119)

Perhaps we could improve the my_print_defaults output and de-cruft the options list in one fell swoop.

Comment by Daniel Black [ 2022-05-26 ]

I'm in favour of removal from output. serg do you have a preference?

The problem with my_print_defaults is that it can parse config files and arguments well, however what scripts are often after is the server defaults (which also neglects the auto sized/determined values which are not in the output of --help --verbose as far as I remember). Its a rather big task if you want to take it on (I suspect it would be taking sys_vars.cc and compiling into both the my_print_defaults and server).

Comment by Sergei Golubchik [ 2022-06-06 ]

Yes, let's remove deprecated options and aliases

Comment by Christian Gonzalez [ 2022-11-24 ]

Hi! I can start working on this one if nobody else is doing it.

Comment by Daniel Black [ 2022-11-24 ]

Christianggm, nobody is immediately working on it so please go for it. Looking forward to seeing your code.

Comment by Daniel Black [ 2023-01-03 ]

Happy with https://github.com/MariaDB/server/pull/2376 ?

Generated at Thu Feb 08 10:02:35 UTC 2024 using Jira 8.20.16#820016-sha1:9d11dbea5f4be3d4cc21f03a88dd11d8c8687422.