Bug #92077 where is "dba.configureInstance"
Submitted: 20 Aug 2018 8:07 Modified: 30 Jan 2020 12:49
Reporter: yitao Xu Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Document Store: MySQL Shell Severity:S3 (Non-critical)
Version:mysql-shell-8.0.12-linux-glibc2.12-x86-6, 8.0.12 OS:CentOS (CentOS 7)
Assigned to: CPU Architecture:Any

[20 Aug 2018 8:07] yitao Xu
Description:
mysql server
MySQL  ic-03:33060+ ssl  SQL > select version();
+-----------+
| version() |
+-----------+
| 8.0.12    |
+-----------+
1 row in set (0.00 sec)
when list the methods in dba using dba.help()
 MySQL  ic-03:33060+ ssl  JS > dba.help()

The global variable 'dba' is used to access the AdminAPI functionality and
perform DBA operations. It is used for managing MySQL InnoDB clusters.

The following properties are currently supported.

 - verbose Enables verbose mode on the Dba operations.

The following functions are currently supported.

 - checkInstanceConfiguration      Validates an instance for cluster usage.
 - configureLocalInstance          Validates and configures an instance for
                                   cluster usage.
 - createCluster                   Creates a MySQL InnoDB cluster.
 - deleteSandboxInstance           Deletes an existing MySQL Server instance on
                                   localhost.
 - deploySandboxInstance           Creates a new MySQL Server instance on
                                   localhost.
 - dropMetadataSchema              Drops the Metadata Schema.
 - getCluster                      Retrieves a cluster from the Metadata Store.
 - help                            Provides help about this class and it's
                                   members
 - killSandboxInstance             Kills a running MySQL Server instance on
                                   localhost.
 - rebootClusterFromCompleteOutage Brings a cluster back ONLINE when all
                                   members are OFFLINE.
 - startSandboxInstance            Starts an existing MySQL Server instance on
                                   localhost.
 - stopSandboxInstance             Stops a running MySQL Server instance on
                                   localhost.

For more help on a specific function use: dba.help('<functionName>')

e.g. dba.help('deploySandboxInstance')

There is no dba.configureInstance in it.
When I execute "mysql-js> dba.configureInstance('ic@ic-1:3306', \ 
{clusterAdmin: 'icadmin@ic-1%',clusterAdminPassword: 'password'});" flow the online manual https://dev.mysql.com/doc/refman/8.0/en/mysql-innodb-cluster-production-deployment.html 

 MySQL  ic-03:33060+ ssl  JS > dba.configureInstance('root@ic-02:3306');
Invalid object member configureInstance (AttributeError)
It doesn't work,but dba.checkInstanceConfiguration('root@ic-02:3306') done it.
 MySQL  ic-03:33060+ ssl  JS > dba.checkInstanceConfiguration('root@ic-02:3306')

Please provide the password for 'root@ic-02:3306': *****
Validating instance...

The instance 'ic-02:3306' is valid for Cluster usage
{
    "status": "ok"
}

The problem is which is the correct one, manual or mysqlsh ?

How to repeat:
using mysql mysql-8.0.12-linux-glibc2.12-x86_64 and mysql-shell-8.0.12-linux-glibc2.12-x86-64bit execute "dba.help()" via mysqlsh

Suggested fix:
modify the manual or fix mysqlsh
it will confuse the user. Follow the manual, nobody can do it success.
[20 Aug 2018 10:29] MySQL Verification Team
Hello Yitao,

Thank you for the report.
I quickly tried at my end, both binary tarballs from internal repository and able to use dba.configureInstance().

-- On OL7
 bin/mysqlsh --log-level=DEBUG3
MySQL Shell 8.0.12

Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type '\help' or '\?' for help; '\quit' to exit.

 MySQL  JS > \c root@localhost
Creating a session to 'root@localhost'
Please provide the password for 'root@localhost':
Fetching schema names for autocompletion... Press ^C to stop.
Your MySQL connection id is 8 (X protocol)
Server version: 8.0.12 MySQL Community Server - GPL
No default schema selected; type \use <schema> to set one.

 MySQL  localhost:33060+ ssl  JS > dba.help()
NAME
      dba - Global variable for InnoDB cluster management.

DESCRIPTION
      The global variable dba is used to access the AdminAPI functionality and
      perform DBA operations. It is used for managing MySQL InnoDB clusters.

PROPERTIES
      verbose
            Enables verbose mode on the dba operations.

FUNCTIONS
      checkInstanceConfiguration(instance[, options])
            Validates an instance for MySQL InnoDB Cluster usage.

      configureInstance([instance][, options])
            Validates and configures an instance for MySQL InnoDB Cluster
            usage.
[...]

 MySQL  localhost:33060+ ssl  JS > dba.configureInstance('root@localhost:3333')
Please provide the password for 'root@localhost:3333':
Configuring local MySQL instance listening at port 3333 for use in an InnoDB cluster...

This instance reports its own address as hod03
Clients and other cluster members will communicate with it through this address by default. If this is not correct, the report_host MySQL system variable should be changed.

WARNING: User 'root' can only connect from localhost.
If you need to manage this instance while connected from other hosts, new account(s) with the proper source address specification must be created.

1) Create remotely usable account for 'root' with same grants and password
2) Create a new admin account for InnoDB cluster with minimal required grants
3) Ignore and continue
4) Cancel

Please select an option [1]: 4
Canceling...

Only issue I noted was that as is copied statement i.e dba.configureInstance('ic@ic-1:3306', \ 
{clusterAdmin: 'icadmin@ic-1%',clusterAdminPassword: 'password'}); from https://dev.mysql.com/doc/refman/8.0/en/mysql-innodb-cluster-production-deployment.html ended up with:

MySQL  localhost:33060+ ssl  JS > dba.configureInstance('root@localhost:3333', \
SyntaxError: Unexpected token ILLEGAL

 MySQL  localhost:33060+ ssl  JS > {clusterAdmin: 'cluster_admin@%',clusterAdminPassword: 'Pass12345!'})^C
 MySQL  localhost:33060+ ssl  JS >
 MySQL  localhost:33060+ ssl  JS > dba.configureInstance('root@localhost:3333', \
SyntaxError: Unexpected token ILLEGAL

But again, when I remove "\" from the statement it works:

 MySQL  localhost:33060+ ssl  JS > dba.configureInstance('root@localhost:3333', {clusterAdmin: 'cluster_admin@%',clusterAdminPassword: 'Pass12345!'});
Please provide the password for 'root@localhost:3333':
Configuring local MySQL instance listening at port 3333 for use in an InnoDB cluster...

This instance reports its own address as hod03
Clients and other cluster members will communicate with it through this address by default. If this is not correct, the report_host MySQL system variable should be changed.

Some configuration options need to be fixed:
+--------------------------+---------------+----------------+--------------------------------------------------+
| Variable                 | Current Value | Required Value | Note                                             |
+--------------------------+---------------+----------------+--------------------------------------------------+
| binlog_checksum          | CRC32         | NONE           | Update the server variable                       |
| enforce_gtid_consistency | OFF           | ON             | Update read-only variable and restart the server |
| gtid_mode                | OFF           | ON             | Update read-only variable and restart the server |
| server_id                | 1             | <unique ID>    | Update read-only variable and restart the server |
+--------------------------+---------------+----------------+--------------------------------------------------+

Do you want to perform the required configuration changes? [y/n]: n

So, other than one issue noted above i.e when copied statement as is from manual rest seems to work. Could you please confirm this? Thank you!

Thanks,
Umesh
[20 Aug 2018 10:33] MySQL Verification Team
Tried on CentOS7, MySQL Shell and Server installed using rpm packages:

ushastry@BugCentOS7 Downloads]$ mysqlsh --log-level=DEBUG3
MySQL Shell 8.0.12

Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type '\help' or '\?' for help; '\quit' to exit.

 MySQL  JS > \c root@localhost
Creating a session to 'root@localhost'
Please provide the password for 'root@localhost': ********
Save password for 'root@localhost'? [Y]es/[N]o/Ne[v]er (default No): 
Fetching schema names for autocompletion... Press ^C to stop.
Your MySQL connection id is 20 (X protocol)
Server version: 8.0.12 MySQL Community Server - GPL
No default schema selected; type \use <schema> to set one.

 MySQL  localhost:33060+ ssl  JS > db.help()
TypeError: Cannot read property 'help' of null

 MySQL  localhost:33060+ ssl  JS > db.help
TypeError: Cannot read property 'help' of null

 MySQL  localhost:33060+ ssl  JS > dba.help()
NAME
      dba - Global variable for InnoDB cluster management.

DESCRIPTION
      The global variable dba is used to access the AdminAPI functionality and
      perform DBA operations. It is used for managing MySQL InnoDB clusters.

PROPERTIES
      verbose
            Enables verbose mode on the dba operations.

FUNCTIONS
      checkInstanceConfiguration(instance[, options])
            Validates an instance for MySQL InnoDB Cluster usage.

      configureInstance([instance][, options])
            Validates and configures an instance for MySQL InnoDB Cluster
            usage.

      configureLocalInstance(instance[, options])
            Validates and configures a local instance for MySQL InnoDB Cluster
            usage.

      createCluster(name[, options])
            Creates a MySQL InnoDB cluster.

      deleteSandboxInstance(port[, options])
            Deletes an existing MySQL Server instance on localhost.

      deploySandboxInstance(port[, options])
            Creates a new MySQL Server instance on localhost.

      dropMetadataSchema(options)
            Drops the Metadata Schema.

      getCluster([name][, options])
            Retrieves a cluster from the Metadata Store.

      help([member])
            Provides help about this object and it's members

      killSandboxInstance(port[, options])
            Kills a running MySQL Server instance on localhost.

      rebootClusterFromCompleteOutage([clusterName][, options])
            Brings a cluster back ONLINE when all members are OFFLINE.

      startSandboxInstance(port[, options])
            Starts an existing MySQL Server instance on localhost.

      stopSandboxInstance(port[, options])
            Stops a running MySQL Server instance on localhost.

      For more help on a specific function use: dba.help('<functionName>')

      e.g. dba.help('deploySandboxInstance')

 MySQL  localhost:33060+ ssl  JS > dba.configureInstance('root@localhost:3306')
Please provide the password for 'root@localhost:3306': ********
Save password for 'root@localhost:3306'? [Y]es/[N]o/Ne[v]er (default No): 
Configuring local MySQL instance listening at port 3306 for use in an InnoDB cluster...

This instance reports its own address as BugCentOS7
Clients and other cluster members will communicate with it through this address by default. If this is not correct, the report_host MySQL system variable should be changed.

WARNING: User 'root' can only connect from localhost.
If you need to manage this instance while connected from other hosts, new account(s) with the proper source address specification must be created.

1) Create remotely usable account for 'root' with same grants and password
2) Create a new admin account for InnoDB cluster with minimal required grants
3) Ignore and continue
4) Cancel

Please select an option [1]: 4
Canceling...
Dba.configureInstance: Cancelled (RuntimeError)

 MySQL  localhost:33060+ ssl  JS > dba.configureInstance('root@localhost', \ 
SyntaxError: Unexpected token ILLEGAL

 MySQL  localhost:33060+ ssl  JS > {clusterAdmin: 'cluster_admin@%',clusterAdminPassword: 'Pass12345!'})

If you are seeing the same issue then will handle this as a doc issue.
[21 Aug 2018 2:09] yitao Xu
Hello Umesh,
Thank you for your confirmation.Verified what you did, it's a doc bug.
Thanks
[21 Aug 2018 4:37] MySQL Verification Team
Thank you for confirming, verifying as a doc issue for now but if "\" is considered/treated a valid continue command here then better to fix it.

regards,
Umesh
[21 Aug 2018 23:25] Juan Rene Ramirez Monarrez
Posted by developer:
 
Hi Umesh

Based on the help output, it seems you are using a non official version of the shell package in 8.0.12

In 8.0.12 we reformatted the help output to produce a more appealing format so it is easy to identify you are using a version that was not final, given it does not have the help updates.

It is possible that in such version the dba help was not showing the function you mention on the title.

I've downloaded the released generic linux package for 8.0.12 and this is what I get, which correctly shows the function you are asking for.

 MySQL  JS  dba.help()
NAME
      dba - Global variable for InnoDB cluster management.

DESCRIPTION
      The global variable dba is used to access the AdminAPI functionality and
      perform DBA operations. It is used for managing MySQL InnoDB clusters.

PROPERTIES
      verbose
            Enables verbose mode on the dba operations.

FUNCTIONS
      checkInstanceConfiguration(instance[, options])
            Validates an instance for MySQL InnoDB Cluster usage.

      configureInstance([instance][, options])
            Validates and configures an instance for MySQL InnoDB Cluster
            usage.

      configureLocalInstance(instance[, options])
            Validates and configures a local instance for MySQL InnoDB Cluster
            usage.

      createCluster(name[, options])
            Creates a MySQL InnoDB cluster.

      deleteSandboxInstance(port[, options])
            Deletes an existing MySQL Server instance on localhost.

      deploySandboxInstance(port[, options])
            Creates a new MySQL Server instance on localhost.

      dropMetadataSchema(options)
            Drops the Metadata Schema.

      getCluster([name][, options])
            Retrieves a cluster from the Metadata Store.

      help([member])
            Provides help about this object and it's members

      killSandboxInstance(port[, options])
            Kills a running MySQL Server instance on localhost.

      rebootClusterFromCompleteOutage([clusterName][, options])
            Brings a cluster back ONLINE when all members are OFFLINE.

      startSandboxInstance(port[, options])
            Starts an existing MySQL Server instance on localhost.

      stopSandboxInstance(port[, options])
            Stops a running MySQL Server instance on localhost.

      For more help on a specific function use: dba.help('<functionName>')

      e.g. dba.help('deploySandboxInstance')
[22 Aug 2018 3:31] MySQL Verification Team
Hello Juan Rene,

Please note that issue is not with the packages etc as I have used official builds from vanheim and help lists everything but I have truncated the help output in order to post here, here the issue is that one cannot use the statement "mysql-js> dba.configureInstance('ic@ic-1:3306', \ {clusterAdmin: 'icadmin@ic-1%',clusterAdminPassword: 'password'});" as is since mysql shell cannot parse "\" which is provided in the manual -

https://dev.mysql.com/doc/refman/8.0/en/mysql-innodb-cluster-production-deployment.html

Only issue I noted was that as is copied statement i.e dba.configureInstance('ic@ic-1:3306', \ 
{clusterAdmin: 'icadmin@ic-1%',clusterAdminPassword: 'password'}); from https://dev.mysql.com/doc/refman/8.0/en/mysql-innodb-cluster-production-deployment.html ended up with:

MySQL  localhost:33060+ ssl  JS > dba.configureInstance('root@localhost:3333', \
SyntaxError: Unexpected token ILLEGAL

If you think that "\" should be allowed then it is a code bug, because MySQL shell cannot parse it but if it is by design and "\" is illegal char then may be remove the same from doc to avoid further confusion.

Hope this is clear now. 

Thanks,
Umesh
[30 Jan 2020 12:49] David Moss
Posted by developer:
 
Thanks for the feedback. Indeed I verify that the exact statement from the manual failed when copy and pasted into the Shell terminal.
I am now fixing this through the docs.