Bug #86831 STOP SLAVE syntax documentation is wrong
Submitted: 26 Jun 2017 22:05 Modified: 28 Apr 2019 0:55
Reporter: monty solomon Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.7.18 OS:Any
Assigned to: CPU Architecture:Any

[26 Jun 2017 22:05] monty solomon
Description:
STOP SLAVE FOR CHANNEL without a specified channel fails with an error 1064.

The documentation states

https://dev.mysql.com/doc/refman/5.7/en/stop-slave.html

If a STOP SLAVE statement does not have a channel defined when using multiple channels, this statement stops the specified threads for all channels.

There does not appear to be a way to list the existing channels.

How to repeat:
mysql> reset slave all;
ERROR 3081 (HY000): This operation cannot be performed with running replication threads; run STOP SLAVE FOR CHANNEL '' first

mysql> STOP SLAVE FOR CHANNEL;
ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near '' at line 1

mysql> STOP SLAVE FOR CHANNEL '';
Query OK, 0 rows affected (0.00 sec)

Suggested fix:
Fix STOP SLAVE FOR CHANNEL and/or the documentation.
[26 Jun 2017 22:06] monty solomon
The documentation is somewhat confusing where it states "this statement stops the specified threads for all channels" but not what it does if no threads are specified.

"If a STOP SLAVE statement does not have a channel defined when using multiple channels, this statement stops the specified threads for all channels."
[27 Jun 2017 8:23] MySQL Verification Team
Hello Monty,

Thank you for the report.
This sounds like documentation request to me rather than code bug.

I followed 
https://dev.mysql.com/doc/refman/5.7/en/replication-multi-source-tutorials.html
 
-- Tried just STOP SLAVE and confirmed that channels are indeed stopped

STOP SLAVE;

or starting both channels START SLAVE and confirmed that both channels started.

Thanks,
Umesh
[27 Jun 2017 8:27] MySQL Verification Team
test results

Attachment: 86831.results (application/octet-stream, text), 29.38 KiB.

[29 Jun 2017 4:48] monty solomon
I think you misunderstood.

I was writing about "STOP SLAVE FOR CHANNEL", not "STOP SLAVE"

Thanks.
[29 Jun 2017 9:01] MySQL Verification Team
Hi Monty, 

No, I meant just "STOP SLAVE FOR CHANNEL", per internal discussion with developer FOR CHANNEL channel_name is optional.  Either you specify 'FOR CHANNEL channel_name', or you do not specify anything.

Sounds like doc request.

Thanks,
Umesh
[29 Jun 2017 9:06] Venkatesh Duggirala
Post by Developer:
==================

Just like all other replication commands, 

[FOR CHANNEL channel_name] clause is optional. 

i.e., 
> STOP SLAVE is valid syntax
> STOP SLAVE FOR CHANNEL 'master1' is valid syntax to stop 'master1' channel.
> STOP SLAVE FOR CHANNEL '' is valid syntax to stop empty channel (the default channel that server provides).

But stopping the query in between like the one mentioned in this bug 
'STOP SLAVE FOR CHANNEL'  is syntax error and it is expected.

Hence the reported bug is "not a bug"

But I noticed that 
https://dev.mysql.com/doc/refman/5.7/en/stop-slave.html 
syntax section does not have channel_option. Hence converting
this bug as documentation bug to update the syntax with

STOP SLAVE [thread_types] [channel_option]

thread_types:
    [thread_type [, thread_type] ... ]

thread_type: IO_THREAD | SQL_THREAD

channel_option:
    FOR CHANNEL channel

I hope this cleared your doubts about the syntax

Marking this bug as "documentation bug" to add [channel_option] clause.

Regards,
Venkatesh.
[28 Apr 2019 0:55] Paul DuBois
Posted by developer:
 
Syntax updated.