2.3.2.2 MySQL Configurator CLI

MySQL Configurator supports GUI (default) and CLI (by passing in --console) modes using the mysql_configurator.exe executable.

Note

MySQL Configurator CLI functionality was added in MySQL Configurator 9.2.0.

Executing MySQL Configurator requires a Windows user with administrative privileges, as otherwise the system prompts for the credentials.

CLI Syntax

The general syntax is:

mysql_configurator.exe --console [--help] | [--action=action_name | -a=action_name] | ...]

Table 2.6 Syntax

Option name	Shortcut	Supported values	Usage example	Description
console	c	N/A	--console	Activates the CLI in MySQL Configurator, otherwise the GUI is launched.
action	a	configure, reconfigure, remove, or upgrade	--action=configure	Runs MySQL Configurator CLI in new configuration, reconfiguration, removal or upgrade mode.
help	h	N/A	--help	Displays general help or help for the corresponding action. If no --action element is provided, the general help section is displayed.
action option and value	N/A	See section "Configure/Reconfigure/Remove/Upgrade options" for supported values and details	--datadir="C:\MySQL...", --port=3306	Defines the various configuration options available for each CLI action (configuration, reconfiguration, removal or upgrade)

Available Actions

Each action (configure, reconfigure, remove, and upgrade) have a specific set of options that define the elements to configure when performing the operation. The syntax is --action_option=action_value with a full list of action options below:

Table 2.7 Syntax

Action option	Shortcut	Aliases (deprecated aliases marked)	Type	Values	Default value	Action	Condition	Description
backup-data	N/A	backup-databases, dump-databases, backup-data-directory (deprecated)	bool	true, false	true	upgrade	N/A	Creates a backup of the databases so that data can be restored if a failure occurs.
binary-log-file-name	N/A	log-bin, binary-log-file, binary-log, binary-log-path, log-bin-file, log-bin-file-name, log-bin-path	File name	N/A	{host_name}-bin	configure, reconfigure	enable-binary-log=true	Specifies the base name to use for binary log files. With binary logging enabled, the server logs all statements that change data to the binary log, which is used for backup and replication. The binary log is a sequence of files with a base name and numeric extension.
configure-as-process	N/A	run-as-process	bool	true, false	false	configure, reconfigure	N/A	Configures MySQL Server to run as a Windows process.
configure-as-windows-service	N/A	configure-as-win-service, configure-as-service, run-as-service, run-as-windows-service, run-as-win-service, as-windows-service (deprecated), as-win-service (deprecated)	bool	true, false	true	configure, reconfigure	N/A	Configures MySQL Server to run as a Windows service. By default, the Windows service runs using the Standard System Account (Network Service).
create-windows-firewall-rules	N/A	create-firewall-rules, create-win-fw-rules, create-fw-rules, open-win-firewall (deprecated), open-windows-firewall (deprecated), openfirewall (deprecated)	bool	true, false	true	configure, reconfigure	enable-tcp-ip=true	Creates Windows Firewall rules to allow traffic through both the classic and X Protocol TCP/IP ports.
data-directory	d	data-dir, datadir	Path	N/A	"C:\\ProgramData\\MySQL\\MySQL Server x.x" where x.x corresponds to the corresponding server major and minor version.	configure	N/A	The path to the MySQL server data directory. This option sets the datadir system variable.
enable-binary-log	N/A	enable-log-bin	bool	true, false	true	configure, reconfigure	N/A	Indicates whether the binary log is enabled.
enable-general-log	N/A	general-log (deprecated), generallog (deprecated)	bool	true, false	false	configure, reconfigure	N/A	Indicates whether the general query log is enabled.
enable-named-pipes	N/A	enable-pipes, named-pipes (deprecated)	bool	true, false	false	configure, reconfigure	N/A	Indicates whether the server permits connections over a named pipe.
enable-shared-memory	N/A	shared-memory	bool	true, false	false	configure, reconfigure	N/A	Indicates whether the server permits shared-memory connections.
enable-slow-query-log	N/A	slow-query-log (deprecated), enable-slow-log (deprecated)	bool	true, false	false	configure, reconfigure	N/A	Indicates whether the slow query log is enabled.
error-log-file-name	N/A	log-error, error-log, error-log-file, error-log-path, errorlogname (deprecated)	Path/File name	N/A	{host_name}.err	configure, reconfigure	enable-error-log=true	Defines the name and path of the error log. If no path is given, the file is created in the data directory.
general-log-file-name	N/A	general-log-file, general-log-path, generallogname (deprecated)	File name	N/A	{host_name}.log	configure, reconfigure	enable-general-log=true	Defines the name and path of the general query log. If no path is given, the file is created in the data directory.
install-sample-databases	N/A	install-example-databases, create-sample-databases, create-example-databases, install-sample-database (deprecated), install-example-database (deprecated)	list	All, Sakila, World, None	none	configure, reconfigure	N/A	Installs the specified sample databases (Sakila or World).
keep-data-directory	N/A	keep-data, keep-data-dir, keep-datadir	bool	true, false	false	remove	N/A	Prevents the data directory from being deleted when MySQL Server configurations are removed.
lower-case-table-names	N/A	table-names (deprecated)	list	0, 1, 2	1	configure	N/A	If set to 0, table names are stored as specified and comparisons are case-sensitive. If set to 1, table names are stored in lowercase on disk and comparisons are not case-sensitive. If set to 2, table names are stored as given but compared in lowercase. This option also applies to database names and table aliases.
mysqlx-port	X	x-port, xport (deprecated)	number	N/A	3306	configure, reconfigure	enable-tcp-ip=true	The network port on which X Plugin listens for TCP/IP connections. This is the X Plugin equivalent of port; see that variable description for more information.
named-pipe-full-access-group	N/A	pipe-full-access-group, full-access-group	string	"", everyone, valid Windows local group name	"" (empty string)	configure, reconfigure	enable-named-pipes=true	Sets the name of a Windows local group whose members are granted sufficient access by the MySQL server to use named-pipe clients. The default value is an empty string, which means that no Windows user is granted full access to the named pipe.
named-pipe-name	N/A	socket, pipe-name, named-pipe, pipename (deprecated)	string	N/A	MYSQL	configure, reconfigure	enable-named-pipes=true	Specifies the pipe name to use when listening for local connections that use a named pipe.
old-instance-connection-protocol	N/A	old-instance-protocol, existing-instance-protocol, existing-instance-connection-protocol	list	Socket, Sockets, Tcp, Pipe, NamedPipe, SharedMemory, Memory	tcp-ip	upgrade	N/A	The connection protocol used by the server instance that is being upgraded.
old-instance-pipe-name	N/A	old-instance-named-pipe, existing-instance-named-pipe, existing-instance-pipe-name	string	N/A	MYSQL	upgrade	N/A	Specifies the named pipe used for local connections by the server instance that is being upgraded.
old-instance-port	N/A	old-instance-tcp-ip-port, existing-instance-tcp-ip-port, existing-instance-port (deprecated)	number	N/A	3306	upgrade	N/A	The TCP/IP port used by the server instance that is being upgraded.
old-instance-shared-memory-name	N/A	existing-instance-memory-name, existing-instance-shared-memory-name	string	N/A	MYSQL	upgrade	N/A	The name of the shared-memory connection used to communicate with the server instance that is being upgraded.
password	p	pwd, root-password, root-pwd, passwd, rootpasswd (deprecated)	string	N/A	N/A	configure, reconfigure	N/A	The password assigned to the root user during a new configuration or reconfiguration. The password cannot be changed during reconfiguration, but it is required to validate that MySQL Configurator can connect to the server.
root-password-file	N/A	root-pass-file, root-pwd-file, defaults-extra-file	Path	N/A	N/A	reconfigure, upgrade	N/A	Defines the name and path of the file containing the password of the root user.
server-file-full-permissions-list	N/A	server-file-full-access-list, server-file-full-control-list, full-access-list (deprecated), full-control-list (deprecated)	comma separated list	windows users/groups	user running the windows service (if applicable) and Administrators group	configure, upgrade	server-file-permissions=configure	Defines a comma-separated list of Windows users or groups that have full access to the server files.
server-file-no-permissions-list	N/A	server-file-no-access-list, no-access-list (deprecated)	comma separated list	windows users/groups	empty	configure, upgrade	server-file-permissions=configure	Defines a comma-separated list of users or groups that have no access to the server files.
server-file-permissions	N/A	server-file-access, server-file-permissions-access (deprecated)	list	FullAccess, Configure, Manual	full-access	configure, upgrade	N/A	Configures the user level of access for the server files, including the data directory and all files within it.
server-id	N/A	serverid (deprecated)	number	N/A	1	configure	N/A	For servers used in a replication topology, specifies a unique server ID in the range from 1 to 2^32 - 1. Each ID must differ from every other ID used by a source or replica in the topology.
server-type	N/A	server-configuration-type, server-config-type, configuration-type, config-type	list	Developer, Server, Dedicated, Manual	development	configure, reconfigure	N/A	Optimizes system resources depending on the intended use of the server instance.
shared-memory-name	N/A	shared-memory-base-name, shared-mem-name, memory-name	string	N/A	MYSQL	configure, reconfigure	enable-shared-memory=true	The name of the shared-memory connection used to communicate with the server.
slow-query-log-file	N/A	slow-log-file, slow-log-file-name, slow-query-log-file-name, slow-log-path, slow-query-log-path, slowlogname (deprecated)	File name	N/A	{host_name}-slow.log	configure, reconfigure	enable-slow-query-log=true	Defines the name and path of the slow query log file. If no path is given, the file is created in the data directory.
uninstall-sample-databases	N/A	uninstall-example-databases, remove-sample-databases, remove-example-databases, uninstall-sample-database (deprecated), uninstall-example-database (deprecated)	list	All, Sakila, World, None	none	configure, reconfigure	N/A	Uninstalls the specified sample databases (Sakila or World).
windows-service-auto-start	N/A	win-service-auto-start, service-auto-start, auto-start (deprecated), autostart (deprecated)	bool	true, false	true	configure, reconfigure	configure-as-windows-service=true	If configured as a Windows service, this value sets the service to start automatically at system startup.
windows-service-name	N/A	win-service-name, service-name, servicename (deprecated)	string	N/A	"MySQLxx" where xx corresponds to the server major and minor version.	configure, reconfigure	configure-as-windows-service=true	The name given to the Windows service used to run MySQL Server.
windows-service-password	N/A	win-service-password, win-service-pwd, service-password, service-pwd, sapass (deprecated)	string	N/A	"" (empty string)	configure, reconfigure	configure-as-windows-service=true	The password of the Windows user account used to run the Windows service.

Note

Do not specify both --configure-as-windows-service=true and --configure-as-process=true. MySQL Configurator reports an error if both options are enabled.

MySQL User Management

The configure and reconfigure actions allow you to create and edit MySQL users as per the --add-user option:

• --add-user='user_name':'password'|'file_path'|'windows_security_token':host:role:authentication

  Only valid for the configure (not reconfigure) action.

The username, password, and token file path must be enclosed in single or double quotes. Escape single quotes, double quotes, and back slashes if present in the username or password.

Add user examples:

mysql_configurator.exe --console --action=configure --add-user='john':'mypass12%':%:"Db Admin":MYSQL
mysql_configurator.exe --console --action=configure --add-user='jenny':'jenny-T480\jenny':localhost:"Administrator":Windows

General Examples

A new configuration:

# Simple 
mysql_configurator.exe --console --action=configure --password=test

# Configure the server to run as a Windows process
mysql_configurator.exe --console --action=configure --password=test --configure-as-process=true

# More complex
mysql_configurator.exe --console --action=configure --password=test --port=3320 --enable-named-pipes=true --named-pipe-name=MYSQL_PIPE --server-id=2 --install-sample-databases=All

# More complex, also with users
mysql_configurator.exe --console --action=configure --password=other123 --add-user='john':'pa$$':"Db Admin":MYSQL --add-user='mary':'p4ssW0rd':"Administrator":MYSQL

A reconfiguration:

# Basic reconfiguration
mysql_configurator.exe --console --action=reconfigure --password=test --port=3310

# Complex reconfiguration
mysql_configurator.exe --console --action=reconfigure --password=test --enable-shared-memory=false

A removal:

mysql_configurator.exe --console --action=remove --keep-data-directory=true

An upgrade:

# Basic upgrade
mysql_configurator.exe --console --action=upgrade --old-instance-password=test

# Complex upgrade
mysql_configurator.exe --console --action=upgrade --old-instance-password=test --backup-data=false --server-file-permissions=full

Root Password Handling

There are multiple ways to pass in the root user password, depending on the needs in terms of security and simplicity. The different methods, in order of precedence:

1. Pass passwords as command-line arguments:

   Pass in the --password (for configuration and reconfiguration) or --old-instance-password (for upgrades) to the command line.

2. Set passwords in the my.ini MySQL configuration file:

   Having the entry "password={password_here}" directly in the my.ini defines the root user password.

   Having the entry "password={password_here}" in the extra configuration file specified by --root-password-file can define the root user password.

3. Defining passwords using environment variables:

   MYSQL_PWD: Similar to the MySQL client, the value defined in the MYSQL_PWD environment variable can define the root user password if no other method was used to define it. This variable applies to the configure, reconfigure, and upgrade actions.

   WIN_SERVICE_ACCOUNT_PWD: This environment variable can set the password of the Windows service account user that is configured to run the MySQL Windows Service if the server has been configured to run as a service. This variable applies to the configure and reconfigure actions.