MySQL :: MySQL Shell for VS Code :: A.1 Dba Class Methods

Check Instance for InnoDB Cluster

Validates an instance for MySQL InnoDB Cluster usage.

JavaScript: dba.checkInstanceConfiguration(instance[, options])
Python: dba.check_instance_configuration(instance[, options])

Options are as follows:

mycnfPath: Optional path to the MySQL configuration file for the instance. Used as an alias for verifyMyCnf.
verifyMyCnf: Optional path to the MySQL configuration file for the instance. If this option is given, the configuration file will be verified for the expected option values, in addition to the global MySQL system variables.
password: The password to get connected to the instance.
interactive: Boolean value used to disable or enable the wizards in the command execution, meaning prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

Example: Validate MySQL instance at ic-1:3306 for use in an InnoDB Cluster.

dba.checkInstanceConfiguration('icadmin@ic-1:3306')

For more information, see Pre-Checking Instance Configuration for InnoDB Cluster Usage.

Configure Instance for InnoDB Cluster

Validates and configures an instance for MySQL InnoDB Cluster usage.

JavaScript: dba.configureInstance([instance][, options])
Python: dba.configure_instance([instance][, options])

Options are as follows:

mycnfPath: The path to the MySQL configuration file of the instance.
outputMycnfPath: Alternative output path to write the MySQL configuration file of the instance.
password: The password to be used on the connection.
clusterAdmin: The name of the "cluster administrator" account.
clusterAdminPassword: The password for the "cluster administrator" account.
clearReadOnly: Boolean value used to confirm that super_read_only must be disabled.
restart: Boolean value used to indicate that a remote restart of the target instance should be performed to finalize the operation.
interactive: Boolean value used to disable or enable the wizards in the command execution, meaning prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.
applierWorkerThreads: Number of threads used for applying replicated transactions. The default value is 4.

Example: Configure local MySQL instance listening on port 3306 for use in an InnoDB Cluster.

dba.configureInstance('user@example:3306')

For more information, see Configuring Production Instances for InnoDB Cluster Usage.

Configure Local Instance for InnoDB Cluster

Validates and configures an instance for InnoDB Cluster usage.

JavaScript: dba.configureLocalInstance([instance][, options])
Python: dba.configure_local_instance([instance][, options])

Options are as follows:

mycnfPath: The path to the MySQL configuration file of the instance.
outputMycnfPath: Alternative output path to write the MySQL configuration file of the instance.
password: The password to be used on the connection.
clusterAdmin: The name of the cluster administrator account.
clusterAdminPassword: The password for the cluster administrator account.
clearReadOnly: Boolean value used to confirm that super_read_only must be disabled.
restart: Boolean value used to indicate that a remote restart of the target instance should be performed to finalize the operation.
interactive: Boolean value used to disable or enable the wizards in the command execution, meaning prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

Example: Configure local MySQL instance listening on port 3306 for use in an InnoDB Cluster.

dba.configureLocalInstance('icadmin@ic-2:3306')

For more information, see Configuring Instances with dba.configureLocalInstance().

Configure InnoDB ReplicaSet

Validates and configures an instance for use in an InnoDB ReplicaSet.

JavaScript: dba.configureReplicaSetInstance([instance][, options])
Python: dba.configure_replica_set_instance([instance][, options])
Options are as follows:
- password: The password to be used on the connection.
- clusterAdmin: The name of a cluster administrator user to be created. The supported format is the standard MySQL account name format.
- clusterAdminPassword: The password for the "cluster administrator" account.
- interactive: Boolean value used to disable or enable the wizards in the command execution, meaning prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.
- restart: Boolean value used to indicate that a remote restart of the target instance should be performed to finalize the operation.
- applierWorkerThreads: Number of threads used for applying replicated transactions. The default value is 4.
Example: Configure the instance at rs-1:3306, with an InnoDB Cluster administrator named rsadmin.
```
dba.configureReplicaSetInstance('root@rs-1:3306', {clusterAdmin: "'rsadmin'@'rs-1%'"})
```

For more information, see Deploying InnoDB ReplicaSet.

Delpoy InnoDB Cluster

Deploys an instance for use in an InnoDB Cluster.

JavaScript: dba.createCluster(name[, options])
Python: dba.create_cluster(name[, options])

Options are as follows:

disableClone: Boolean value used to disable the clone usage on the cluster.
gtidSetIsComplete: Boolean value which indicates whether the GTID set of the seed instance corresponds to all transactions executed. Default is false.
multiPrimary: Boolean value used to define an InnoDB Cluster with multiple writable instances.
force: Boolean, confirms that the multiPrimary option must be applied and/or the operation must proceed even if unmanaged replication channels were detected.
interactive: Boolean value used to disable or enable the wizards in the command execution, meaning prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.
adoptFromGR: Boolean value used to create the InnoDB Cluster based on existing replication group.
memberSslMode: SSL mode used to configure the members of the cluster.
ipWhitelist: The list of hosts allowed to connect to the instance for group replication. Deprecated.
ipAllowlist: The list of hosts allowed to connect to the instance for group replication.
groupName: String value with the Group Replication group name UUID to be used instead of the automatically generated one.
localAddress: String value with the Group Replication local address to be used instead of the automatically generated one.
groupSeeds: String value with a comma-separated list of the Group Replication peer addresses to be used instead of the automatically generated one. Deprecated and ignored.
manualStartOnBoot: Boolean (default false). If false, Group Replication in cluster instances will automatically start and rejoin when MySQL starts, otherwise, it must be started manually.
replicationAllowedHost: String value to use as the host name part of internal replication accounts (meaning 'mysql_innodb_cluster_###'@'hostname'). Default is %. It must be possible for any member of the cluster to connect to any other member using accounts with this host name value.
exitStateAction: String value indicating the group replication exit state action.
memberWeight: Integer value with a percentage weight for automatic primary election on failover.
consistency: String value indicating the consistency guarantees that the cluster provides.
failoverConsistency: String value indicating the consistency guarantees that the cluster provides.
expelTimeout: Integer value to define the time period in seconds that cluster members should wait for a non-responding member before evicting it from the cluster.
autoRejoinTries: Integer value to define the number of times an instance will attempt to rejoin the cluster after being expelled.
clearReadOnly: Boolean value used to confirm that super_read_only must be disabled. Deprecated.
multiMaster: Boolean value used to define an InnoDB Cluster with multiple writable instances. Deprecated.

Example: Create an InnoDB Cluster called testCluster and assign the returned cluster to a variable called ic-1.

ic-1 = dba.createCluster('testCluster')

For more information, see Creating an InnoDB Cluster.

Deploy InnoDB ReplicaSet

Validates and configures an instance for use in an InnoDB ReplicaSet.

JavaScript: dba.createReplicaSet(name[, options])
Python: dba.create_replica_set(name[, options])

Options are as follows:

adoptFromAR: Boolean value used to create the InnoDB ReplicaSet based on an existing asynchronous replication setup.
instanceLabel: String a name to identify the target instance. Defaults to hostname:port.
dryRun: Boolean if true, all validations and steps for creating a replica set are executed, but no changes are actually made. An exception will be thrown when finished.
gtidSetIsComplete: Boolean value which indicates whether the GTID set of the seed instance corresponds to all transactions executed. Default is false.
replicationAllowedHost: String value to use as the host name part of internal replication accounts, meaning mysql_innodb_rs_###'@'hostname'. Default is %. It must be possible for any member of the InnoDB ReplicaSet to connect to any other member using accounts with this host name value.
interactive: Boolean value used to disable or enable the wizards in the command execution, meaning prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

Example: Create a InnoDB ReplicaSet named example and assign it to the rs variable.

rs = dba.createReplicaSet("example")

For more information, see Deploying InnoDB ReplicaSet.

Delete a Sandbox Instance

Deletes an existing MySQL server sandbox instance, which was deployed on the local host.

JavaScript: dba.deleteSandboxInstance(port[, options])
Python: dba.delete_sandbox_instance(port[, options])

Options are as follows:

sandboxDir: The path where the instance is located.

Example: Delete a Sandbox Instance listening on port 3316.

dba.deleteSandboxInstance(3316)

For more information, see Managing Sandbox Instances.

Deploy Sandbox Instance

Creates a new MySQL server sandbox instance on the local host.

JavaScript: dba.deploySandboxInstance(port[, options])
Python: dba.deploy_sandbox_instance(port[, options])

Options are as follows:

port: port where the new instance will listen for X Protocol connections.
sandboxDir: Path where the new instance will be deployed.
password: Password for the MySQL root user on the new instance.
allowRootFrom: Create remote root account, restricted to the given address pattern, with a default value of %.
ignoreSslError: Ignore errors when adding SSL support for the new instance, by default: true.
mysqldOptions: List of MySQL configuration options to write to the my.cnf file, as option=value strings.

Example: Deploy a new sandbox instance listening on port 3310.

dba.deploySandboxInstance(3310)

For more information, see Managing Sandbox Instances.

Drop the Metadata Schema

JavaScript: dba.dropMetadataSchema(options)
Python: dba.drop_metadata_schema(options)

Drops the metadata schema.

Options are as follows:

force: Boolean, confirms that the drop operation must be executed.
clearReadOnly: Boolean value used to confirm that super_read_only must be disabled.

Example: Remove the metadata from the connected cluster assigned to a variable called myCluster.

myCluster = dba.dropMetadataSchema()

Retrieve an InnoDB Cluster from the Metadata Store

Retrieves a cluster from the Metadata Store and returns the cluster object identified by the given name or if name is not specified or is null then the default cluster will be returned.

JavaScript: dba.getCluster([name][, options])
Python: dba.get_cluster([name][, options])

Options are as follows:

connectToPrimary: Indicates if the shell to automatically connect to the primary member of the cluster, with a default value of true.

Example: Get an object that represents the InnoDB Cluster and assign it to a variable named ic-1.

ic-1 = dba.getCluster()

Retrieve an InnoDB ClusterSet from the Metadata Store

Retrieves a ClusterSet from the Metadata Store and returns the ClusterSet object.

JavaScript: dba.getClusterSet()
Python: dba.get_cluster_set()

Example: Get an object that represents the InnoDB ClusterSet, and assign it to a variable namedcs1.

cs1 = dba.getClusterSet()

Retrieve a ReplicaSet from the Metadata Store.

Retrieves a ClusterSet from the Metadata Store and returns the ReplicaSet object.

JavaScript: dba.getReplicaSet()
Python: dba.get_replica_set()

Example: Get an object that represents the InnoDB ReplicaSet, and assign it to a variable namedrs-1.

rs-1 = dba.getReplicaSet()

Dba Help

Provides help about this object and its members.

JavaScript: dba.help([member])
Python: dba.help([member])

To see the help options for the getReplicaSet method, type:

dba.help("getReplicaSet")

Forcibly Stop Sandbox Instance

Forcibly stops a running MySQL server instance on the local host.

JavaScript: dba.killSandboxInstance(port[, options])
Python: dba.kill_sandbox_instance(port[, options])

Options are as follows:

sandboxDir: Path where the instance is located.

Example: Stop the instance listening on port 3319, without gracefully stopping it, simulating an unexpected halt.

dba.killSandboxInstance(3319)

Reboot Cluster From Complete Outage

Brings a cluster back online when all members are offline.

JavaScript: dba.rebootClusterFromCompleteOutage([clusterName][, options])
Python: dba.reboot_cluster_from_complete_outage([clusterName][, options])

Options are as follows:

user: The user used for the instances sessions required operations.
password: The password used for the instances sessions required operations.
removeInstances: The list of instances to be removed from the cluster.
rejoinInstances: The list of instances to be rejoined to the cluster.
clearReadOnly: Boolean value used to confirm that super_read_only must be disabled.

Example: Reboot the cluster by issuing, assign the output of this command to a variable named cluster.

var cluster = dba.rebootClusterFromCompleteOutage()

For more information, see Restoring and Rebooting an InnoDB Cluster.

Start Sandbox Instance

Starts an existing MySQL server instance on the local host.

JavaScript: dba.startSandboxInstance(port[, options])
Python: dba.start_sandbox_instance(port[, options])

Options are as follows:

sandboxDir: Path where the instance is located.

Example: Start a sandbox instance listening on port 3319.

dba.startSandboxInstance(3319)

Stop Sandbox Instances

Stops a running MySQL server sandbox instance on the local host.

JavaScript: dba.stopSandboxInstance(port[, options])
Python: dba.stop_sandbox_instance(port[, options])

Options are as follows:

sandboxDir: Path where the instance is located.
password: Password for the MySQL root user on the instance.

Example: Stop a sandbox instance listening on port 3319.

dba.stopSandboxInstance(3319)

Upgrade Metadata

Upgrades or restores the metadata to the version supported by MySQL Shell.

JavaScript: dba.upgradeMetadata([options])
Python: dba.upgrade_metadata([options])

Options are as follows:

dryRun: Boolean value used to enable a dry run of the upgrade process.
interactive: Boolean value used to disable or enable the wizards in the command execution, meaning prompts and confirmations will be provided or not according to the value set. The default value is equal to MySQL Shell wizard mode.

Example: Use the dba.upgradeMetadata() operation to upgrade the cluster’s metadata to the new metadata.

cluster = dba.upgradeMetadata()

For more information, see Upgrade Metadata Schema.