Bug #34777 mysqlbinlog: --help output for --base64-output is hard to understand
Submitted: 23 Feb 2008 15:54 Modified: 18 Dec 2009 20:31
Reporter: Paul Dubois Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Command-line Clients Severity:S3 (Non-critical)
Version:5.1 OS:Any
Assigned to: Daogang Qu CPU Architecture:Any
Triage: Triaged: D4 (Minor) / R1 (None/Negligible) / E1 (None/Negligible)

[23 Feb 2008 15:54] Paul Dubois
Description:
In mysqlbinlog.cc, the option structure for the --base64-output option looks like this:

  {"base64-output", OPT_BASE64_OUTPUT_MODE,
   "Determine when the output statements should be base64-encoded BINLOG "
   "statements: 'never' disables it and works only for binlogs without "
   "row-based events; 'auto' is the default and prints base64 only when "
   "necessary (i.e., for row-based events and format description events); "
   "'always' prints base64 whenever possible. 'always' is for debugging "
   "only and should not be used in a production system. The default is "
   "'auto'. --base64-output is a short form for --base64-output=always."
   ,(uchar**) &opt_base64_output_mode_str,
   (uchar**) &opt_base64_output_mode_str,
   0, GET_STR, OPT_ARG, 0, 0, 0, 0, 0, 0},

There are some problems here:

- It is stated that "auto" is the default twice. It need be stated only once.

- It is stated that --base64-output is short for --base64-output=always. But that sounds like the default is "always", not "auto". I cannot figure out what this means, but I'm guessing the reality is this:

If the --base64-output option is not given at all, the default is "auto".
If the --base64-output option is given without a value, the default is "always"

How to repeat:
N/A

Suggested fix:
If my suppositions about how the option is used are correct, I suggest this help text (which also eliminates the duplicate statement about 'auto' being the default):

Determine when the output statements should be base64-encoded BINLOG 
statements: 'never' disables it and works only for binlogs without 
row-based events; 'auto' prints base64 only when necessary (i.e.,
for row-based events and format description events); 'always' prints
base64 whenever possible. 'always' is for debugging only and should 
not be used in a production system. If this argument is not given,
the default is 'auto'; if it is given with no argument, 'always'is used.
[23 Feb 2008 20:43] Valeriy Kravchuk
Thank you for a bug report.
[24 Apr 2008 20:27] Jim Winstead
This text was already changed in 5.1. It now warns that this option is only for debugging purposes.
[23 Sep 2009 15:48] Sven Sandberg
The text in 5.1 has not been changed, it is still as in this report. Re-opening the bug and assigning to replication team.
[10 Oct 2009 9:37] Bugs System
A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/86481

3153 Dao-Gang.Qu@sun.com	2009-10-10
      Bug #34777  	mysqlbinlog: --help output for --base64-output is hard to understand
      
      There are some problems about help text:
      - It is stated that "auto" is the default twice. It need be stated only once.
      - It is stated that --base64-output is short for --base64-output=always. But that sounds
      like the default is "always", not "auto".
      
      Make the help text clear as following:
      Determine when the output statements should be base64-encoded BINLOG 
      statements: 'never' disables it and works only for binlogs without 
      row-based events; 'auto' prints base64 only when necessary (i.e., 
      for row-based events and format description events); 'always' prints 
      base64 whenever possible. 'always' is for debugging only and should 
      not be used in a production system. If this argument is not given, 
      the default is 'auto'; if it is given with no argument, 'always'is used.
[16 Oct 2009 5:27] Bugs System
A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/87061

3175 Dao-Gang.Qu@sun.com	2009-10-16
      Bug #34777  	mysqlbinlog: --help output for --base64-output is hard to understand
      
      There are some problems about help text:
      - It is stated that "auto" is the default twice. It need be stated only once.
      - It is stated that --base64-output is short for --base64-output=always. But that sounds
      like the default is "always", not "auto".
      
      Make the help text clear as following:
      Determine when the output statements should be base64-encoded BINLOG 
      statements: 'never' disables it and works only for binlogs without 
      row-based events; 'auto' prints base64 only when necessary (i.e., 
      for row-based events and format description events); 'always' prints 
      base64 whenever possible. 'always' is for debugging only and should 
      not be used in a production system. If this argument is not given, 
      the default is 'auto'; if it is given with no argument, 'always' is used.
[20 Oct 2009 5:18] Bugs System
A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/87389

3186 Dao-Gang.Qu@sun.com	2009-10-20
      Bug #34777  	mysqlbinlog: --help output for --base64-output is hard to understand
      
      There are some problems about help text:
      - It is stated that "auto" is the default twice. It need be stated only once.
      - It is stated that --base64-output is short for --base64-output=always. But that sounds
      like the default is "always", not "auto".
      
      Make the help text clear as following:
      Determine when the output statements should be base64-encoded BINLOG 
      statements: 'never' disables it and works only for binlogs without 
      row-based events; 'auto' prints base64 only when necessary (i.e., 
      for row-based events and format description events); 'always' prints 
      base64 whenever possible. 'always' is for debugging only and should 
      not be used in a production system. If this argument is not given, 
      the default is 'auto'; if it is given with no argument, 'always' is used.
[20 Oct 2009 5:27] Bugs System
A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/87391

3679 Dao-Gang.Qu@sun.com	2009-10-20 [merge]
      Bug #34777  	mysqlbinlog: --help output for --base64-output is hard to understand
            
      There are some problems about help text:
      - It is stated that "auto" is the default twice. It need be stated only once.
      - It is stated that --base64-output is short for --base64-output=always. 
      But that sounds like the default is "always", not "auto".
            
      Make the help text clear as following:
      Determine when the output statements should be base64-encoded BINLOG 
      statements: 'never' disables it and works only for binlogs without 
      row-based events; 'auto' prints base64 only when necessary (i.e., 
      for row-based events and format description events); 'always' prints 
      base64 whenever possible. 'always' is for debugging only and should 
      not be used in a production system. If this argument is not given, 
      the default is 'auto'; if it is given with no argument, 'always' is used.
[22 Oct 2009 15:48] Paul Dubois
I'm sorry at this late date to point out another problem, but I've just become aware of another issue: There is another possible --base64-output value: decode-rows. That value isn't listed in the --help text.

The manual describes this value thus:

DECODE-ROWS specifies to mysqlbinlog that you intend for row events to be decoded and displayed as commented SQL statements by also specifying the --verbose option. Like NEVER, DECODE-ROWS suppresses display of BINLOG statements, but unlike NEVER, it does not exit with an error if a row event is found.

 http://dev.mysql.com/doc/refman/5.1/en/mysqlbinlog.html

Will that be addressed here, or would you like me to open a separate bug report?
[26 Oct 2009 8:45] Sven Sandberg
Setting back to in-progress based on Paul's comment.
[26 Oct 2009 8:45] Sven Sandberg
Setting back to verified based on Paul's comment.
[27 Oct 2009 3:45] Bugs System
A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/88240

3192 Dao-Gang.Qu@sun.com	2009-10-27
      Bug #34777  	mysqlbinlog: --help output for --base64-output is hard to understand
      
      Append the description of the 'decode-rows' value for --base64-output argument.
[27 Oct 2009 9:10] Bugs System
A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/88267

3192 Dao-Gang.Qu@sun.com	2009-10-27
      Bug #34777  	mysqlbinlog: --help output for --base64-output is hard to understand
      
      Append the description of the 'decode-rows' value for --base64-output argument.
[28 Oct 2009 7:06] Bugs System
A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/88439

3161 Dao-Gang.Qu@sun.com	2009-10-28
      Bug #34777  	mysqlbinlog: --help output for --base64-output is hard to understand
      
      Append the description of the 'decode-rows' value for --base64-output argument.
[28 Oct 2009 7:14] Bugs System
A patch for this bug has been committed. After review, it may
be pushed to the relevant source trees for release in the next
version. You can access the patch from:

  http://lists.mysql.com/commits/88440

3649 Dao-Gang.Qu@sun.com	2009-10-28 [merge]
      Bug #34777  	mysqlbinlog: --help output for --base64-output is hard to understand
      
      Append the description of the 'decode-rows' value for --base64-output argument.
[4 Nov 2009 9:24] Bugs System
Pushed into 5.1.41 (revid:joro@sun.com-20091104092152-qz96bzlf2o1japwc) (version source revid:kristofer.pettersson@sun.com-20091103162305-08l4gkeuif2ozsoj) (merge vers: 5.1.41) (pib:13)
[5 Nov 2009 1:40] Paul Dubois
Cosmetic change. No changelog entry needed.

Setting report to NDI pending push to 5.5.x.
[11 Nov 2009 6:48] Bugs System
Pushed into 6.0.14-alpha (revid:alik@sun.com-20091110093407-rw5g8dys2baqkt67) (version source revid:alik@sun.com-20091109080109-7dxapd5y5pxlu08w) (merge vers: 6.0.14-alpha) (pib:13)
[11 Nov 2009 6:55] Bugs System
Pushed into 5.5.0-beta (revid:alik@sun.com-20091109115615-nuohp02h8mdrz8m2) (version source revid:alik@sun.com-20091105092355-jzukkw6wnd7hmgrj) (merge vers: 5.5.0-beta) (pib:13)
[11 Nov 2009 14:21] Paul Dubois
Cosmetic change. No changelog entry needed.
[18 Dec 2009 10:37] Bugs System
Pushed into 5.1.41-ndb-7.1.0 (revid:jonas@mysql.com-20091218102229-64tk47xonu3dv6r6) (version source revid:jonas@mysql.com-20091218095730-26gwjidfsdw45dto) (merge vers: 5.1.41-ndb-7.1.0) (pib:15)
[18 Dec 2009 10:53] Bugs System
Pushed into 5.1.41-ndb-6.2.19 (revid:jonas@mysql.com-20091218100224-vtzr0fahhsuhjsmt) (version source revid:jonas@mysql.com-20091217101452-qwzyaig50w74xmye) (merge vers: 5.1.41-ndb-6.2.19) (pib:15)
[18 Dec 2009 11:07] Bugs System
Pushed into 5.1.41-ndb-6.3.31 (revid:jonas@mysql.com-20091218100616-75d9tek96o6ob6k0) (version source revid:jonas@mysql.com-20091217154335-290no45qdins5bwo) (merge vers: 5.1.41-ndb-6.3.31) (pib:15)
[18 Dec 2009 11:22] Bugs System
Pushed into 5.1.41-ndb-7.0.11 (revid:jonas@mysql.com-20091218101303-ga32mrnr15jsa606) (version source revid:jonas@mysql.com-20091218064304-ezreonykd9f4kelk) (merge vers: 5.1.41-ndb-7.0.11) (pib:15)