5.8.2.2 Defining Arguments

As mentioned in Section 5.8.2.1, “Command Line Integration for MySQL Shell API Functions”, most of the APIs available in MySQL Shell expect a specific data type for the arguments being provided. Values in command-line arguments can be provided using the JSON specification with the following considerations. Some terminals do their own pre-processing of the data which can impact the way the data is provided to MySQL Shell, and this varies depending on the terminal being used. For example:

• Some terminals split arguments if whitespace is found.

• Consecutive whitespace could be ignored by the splitting logic.

• Quotes could be removed.

MySQL Shell interprets the values as provided by the terminal it is running in, therefore you must provide the data to the terminal in a way that is correctly formatted. For example:

• Important

  Some terminals require quotes to be escaped

• String arguments should be quoted in the following cases:

  • They contain whitespace

  • The argument is for a list parameter and contains commas

  • They contain escaped characters

• The API parameter can accept different data types and the value (based on the JSON specification) could be the wrong data type.

• When defining parameters using JSON, quote string values and string keys. Avoid using whitespace outside of quoted items.

The following examples illustrate some of the handling of parameters.

• To pass in multiple parameters, each a single string, no quoting is required:

  $ mysqlsh -- object function simple string

  In this case, MySQL Shell gets two arguments - argument 1 is simple, and argument 2 is string.

• If you want these two strings to be treated as a single parameter, they must be surrounded by quote marks, as follows

  $ mysqlsh -- object function "simple string"

  In this case, MySQL Shell gets one argument - argument 1 is simple string.

• To use an argument which contains characters such as a backslash, the string must be quoted. Otherwise the character is ignored. For example:

  $ mysqlsh -- object function simple\tstring

  In this case, MySQL Shell gets one argument - simpletstring, the backslash character (\) has been ignored.

  To ensure the backslash character is passed to MySQL Shell, surround the string with quotes:

  $ mysqlsh -- object function "simple\tstring"

  In this case, MySQL Shell gets one argument - simple\tstring.

When using the command-line integration, defining a JSON array has its own caveats. For example, in the MySQL Shell interactive mode you define a JSON array as:

["simple",123]

To use the same array in the command-line integration requires specific quoting. The following example illustrates how to correctly quote the JSON array:

• Attempting to pass the JSON array in the same way as the interactive mode does not work:

  $ mysqlsh -- object function ["simple", 123]

  In this case, MySQL Shell gets two arguments - argument 1 is [simple, and argument 2 is 123].

• Not using spaces in the array helps, but it is still an invalid JSON array:

  $ mysqlsh -- object function ["simple",123]

  In this case, MySQL Shell gets one argument - [simple,123].

• To make a valid JSON array, add escaped quotes within the already quoted string element, for example:

  $ mysqlsh -- object function ["\"simple\"",123]

  In this case, MySQL Shell gets one argument - ["simple",123].

To use a JSON array which contains JSON objects requires quoting in a similar way. For example, in the MySQL Shell interactive mode you define a JSON array which contains JSON objects as:

{"firstName":"John","lastName":"Smith"}

The following example illustrates how to correctly quote the same array in the command-line integration:

• Attempting to pass the JSON array in the same way as the interactive mode does not work:

  $ mysqlsh -- object function {"firstName":"John","lastName":"Smith"}

  In this case, MySQL Shell gets two arguments - argument 1 is firstName:John and argument 2 is lastName:Smith.

• Using escaped quotes for string data leads to:

  $ mysqlsh -- object function {"\"firstName\"":"\"John\"","\"lastName\"":"\"Smith\""}

  In this case, MySQL Shell gets two arguments - argument 1 is "firstName":"John" and argument 2 is "lastName":"Smith".

• To fix this, you need to additionally quote the whole JSON object, to get:

  $ mysqlsh -- object function "{"\"firstName\"":"\"John\"","\"lastName\"":"\"Smith\""}"

  In this case, MySQL Shell gets one argument - {"firstName":"John","lastName":"Smith"}.

Due to the difficulties shown and the fact that the way the terminals in different platforms behave might be different, the following formats are supported.

String Arguments

Strings require quoting only in the following cases:

• The value contains spaces

• The value itself contains commas and is for a list parameter (to avoid splitting)

• The value contains escaped characters

• The value is a number, null, true, false but it is meant to be a string. In these cases the value should be quoted with inner escaped quotes. In other words, if a string value is "true", it should be defined in a CLI call as ""true"".

List Arguments

In addition to a JSON array, an argument for a list parameter can be provided as:

• a comma separated list of values

• separate anonymous arguments

When a list parameter is being processed (in positional order), all of the remaining anonymous arguments are part of the list. The following MySQL Shell CLI calls are equivalent:

• Using a comma separated list of values:

  $ mysqlsh root@localhost -- util dump-schemas sakila,employees

• Using consecutive anonymous arguments:

  $ mysqlsh root@localhost -- util dump-schemas sakila employees

• Using a JSON array:

  $ mysqlsh root@localhost -- util dump-schemas ["\"sakila\"","\"employees\""]

Dictionary Arguments

Dictionaries are created using key-value pairs, the value for a key in a dictionary argument can also be specified using named arguments:

--key=value

The following MySQL Shell CLI call illustrates how the threads and osBucketName keys are defined for the options parameter in the util.dumpInstance() function:

$ mysqlsh -- util dump-instance my-dump --threads=8 --osBucketName=my-bucket

List Keys

You can define the values of a list key in a dictionary in the following ways:

• Defining the value as a JSON array.

• Defining the value as a comma separated list of values.

• Defining values for the key repeatedly.

For example, in the following calls, the definition of the excludeSchemas key passed to the util.dumpInstance() operation is equivalent:

• Using a comma separated list of values:

  $ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=sakila,employees

• Using a JSON array:

  $ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=["\"sakila\"","\"employees\""]

• Defining several values for the --excludeSchemas key:

  $ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=sakila --excludeSchemas=employees

Dictionary Keys

Nested dictionaries are supported with the following restrictions:

• Only one level of nesting is supported.

• Validation for inner pre-defined keys is not supported.

• Validation for inner expected data types is not supported.

The syntax to define a value for a key in a nested dictionary is as follows:

--key=innerKey=value

For example, to define the decodeColumns key and pass it to the util.importTable() operation:

$ mysqlsh -- util import-table --decodeColumns=myColumn=1

Additional Named Arguments

As shown in the previous section, dictionary parameters are supported through named arguments using the --key=value syntax. There is another case when arguments must be specified as named arguments: parameters which are defined after a list parameter. The most convenient way to provide arguments that belong to a list parameter is by using anonymous arguments, for example as shown in the example at List Arguments:

$ mysqlsh root@localhost -- util dump-schemas sakila employees

However, this example is missing the argument for the outputUrl parameter, which is mandatory for the util.dumpSchemas() operation. Because all of the remaining anonymous arguments are included as items in the schemas list, there is no way to specify the outputUrl as an anonymous argument. For example the following would not work:

$ mysqlsh root@localhost -- util dump-schemas sakila employees path/to/dump

In this call, the path path/to/dump would be interpreted as another item in the schemas list. For this reason, any parameter defined after a list parameter must be specified as a named argument when calling the function from the command-line. For example:

$ mysqlsh root@localhost -- util dump-schemas sakila employees --outputUrl=path/to/dump