Menu:
mysql-upgrade:: mysql_upgrade -- Check and Upgrade MySQL Tables
The programs in this section are used when installing or upgrading MySQL.
File: manual.info.tmp, Node: comp-err, Next: mysql-install-db, Prev: programs-installation, Up: programs-installation
note 'comp_err': comp-err. creates the 'errmsg.sys' file that is used by note 'mysqld': mysqld. to determine the error messages to display for different error codes. *note 'comp_err': comp-err. normally is run automatically when MySQL is built. It compiles the 'errmsg.sys' file from the text-format error information file located at 'sql/share/errmsg-utf8.txt' in MySQL source distributions.
*note 'comp_err': comp-err. also generates the 'mysqld_error.h', 'mysqld_ername.h', and 'sql_state.h' header files.
For more information about how error messages are defined, see the MySQL Internals Manual (https://dev.mysql.com/doc/internals/en).
Invoke *note 'comp_err': comp-err. like this:
comp_err [OPTIONS]*note 'comp_err': comp-err. supports the following options.
'--help', '-?'
Command-Line Format
'--help'
Type
Boolean
Default Value
'false'
Display a help message and exit.
'--charset=DIR_NAME', '-C DIR_NAME'
Command-Line Format
'--charset'
Type
String
Default Value
'../share/charsets'
The character set directory. The default is '../sql/share/charsets'.
'--debug=DEBUG_OPTIONS', '-# DEBUG_OPTIONS'
Command-Line Format
'--debug=options'
Type
String
Default Value
'd:t:O,/tmp/comp_err.trace'
In debug builds, write a debugging log. A typical DEBUG_OPTIONS string is 'd:t:O,FILE_NAME'. The default is 'd:t:O,/tmp/comp_err.trace'.
For non-debug builds, this option is non-functional and causes the program to exit with an explanatory message.
Note:
The short form of this option is '-#', using a literal '#' character.
'--debug-info', '-T'
Command-Line Format
'--debug-info'
Type
Boolean
Default Value
'false'
Print some debugging information when the program exits.
'--header-file=FILE_NAME', '-H FILE_NAME'
Command-Line Format
'--header-file=name'
Type
File name
Default Value
'mysqld_error.h'
The name of the error header file. The default is 'mysqld_error.h'.
'--in-file=FILE_NAME', '-F FILE_NAME'
Command-Line Format
'--in-file=path'
Type
File name
Default Value
'[none]'
The name of the input file that defines error messages. The default is '../sql/share/errmsg-utf8.txt'.
'--name-file=FILE_NAME', '-N FILE_NAME'
Command-Line Format
'--name-file=name'
Type
File name
Default Value
'mysqld_ername.h'
The name of the error name file. The default is 'mysqld_ername.h'.
'--out-dir=DIR_NAME', '-D DIR_NAME'
Command-Line Format
'--out-dir=path'
Type
String
Default Value
'../share/'
The name of the output base directory. The default is '../sql/share/'.
'--out-file=FILE_NAME', '-O FILE_NAME'
Command-Line Format
'--out-file=name'
Type
File name
Default Value
'errmsg.sys'
The name of the output file. The default is 'errmsg.sys'.
'--state-file=FILE_NAME', '-S FILE_NAME'
Command-Line Format
'--state-file=name'
Type
File name
Default Value
'sql_state.h'
The name for the SQLSTATE header file. The default is 'sql_state.h'.
'--version', '-V'
Command-Line Format
'--version'
Type
Boolean
Default Value
'false'
Display version information and exit.
File: manual.info.tmp, Node: mysql-install-db, Next: mysql-plugin, Prev: comp-err, Up: programs-installation
Note:
note 'mysql_install_db': mysql-install-db. is deprecated as of MySQL 5.7.6 because its functionality has been integrated into note 'mysqld': mysqld, the MySQL server. To initialize a MySQL installation, invoke note 'mysqld': mysqld. with the '--initialize' or '--initialize-insecure' option. For more information, see note data-directory-initialization::. You should expect *note 'mysql_install_db': mysql-install-db. to be removed in a future MySQL release.
note 'mysql_install_db': mysql-install-db. handles initialization tasks that must be performed before the MySQL server, note 'mysqld': mysqld, is ready to use:
It initializes the MySQL data directory and creates the system tables that it contains.
It initializes the system tablespace and related data structures needed to manage *note 'InnoDB': innodb-storage-engine. tables.
It loads the server-side help tables.
It installs the 'sys' schema.
It creates an administrative account. Older versions of *note 'mysql_install_db': mysql-install-db. may create anonymous-user accounts.
Secure-by-Default Deployment
Current versions of *note 'mysql_install_db': mysql-install-db. produce a MySQL deployment that is secure by default, with these characteristics:
A single administrative account named ''root'@'localhost'' is created with a randomly generated password, which is marked expired.
No anonymous-user accounts are created.
No 'test' database accessible by all users is created.
'--admin-XXX' options are available to control characteristics of the administrative account.
The '--random-password-file' option is available to control where the random password is written.
The '--insecure' option is available to suppress random password generation.
If *note 'mysql_install_db': mysql-install-db. generates a random administative password, it writes the password to a file and displays the file name. The password entry includes a timestamp to indicate when it was written. By default, the file is '.mysql_secret' in the home directory of the effective user running the script. '.mysql_secret' is created with mode 600 to be accessible only to the operating system user for whom it is created.
Important:
When note 'mysql_install_db': mysql-install-db. generates a random password for the administrative account, it is necessary after note 'mysql_install_db': mysql-install-db. has been run to start the server, connect using the administrative account with the password written to the '.mysql_secret' file, and specify a new administrative password. Until this is done, the administrative account cannot be used for anything else. To change the password, you can use the note 'SET PASSWORD': set-password. statement (for example, with the note 'mysql': mysql. or note 'mysqladmin': mysqladmin. client). After resetting the password, remove the '.mysql_secret' file; otherwise, if you run note 'mysql_secure_installation': mysql-secure-installation, that command may see the file and expire the 'root' password again as part of ensuring secure deployment.
Invocation Syntax
Change location to the MySQL installation directory and use this invocation syntax:
bin/mysql_install_db --datadir=PATH/TO/DATADIR [OTHER_OPTIONS]The '--datadir' option is mandatory. *note 'mysql_install_db': mysql-install-db. creates the data directory, which must not already exist:
If the data directory does already exist, you are performing an upgrade operation (not an install operation) and should run note 'mysql_upgrade': mysql-upgrade, not note 'mysql_install_db': mysql-install-db. See *note mysql-upgrade::.
If the data directory does not exist but note 'mysql_install_db': mysql-install-db. fails, you must remove any partially created data directory before running note 'mysql_install_db': mysql-install-db. again.
Because the MySQL server, note 'mysqld': mysqld, must access the data directory when it runs later, you should either run note 'mysql_install_db': mysql-install-db. from the same system account used for running note 'mysqld': mysqld, or run it as 'root' and specify the '--user' option to indicate the user name that note 'mysqld': mysqld. runs under. It might be necessary to specify other options such as '--basedir' if *note 'mysql_install_db': mysql-install-db. does not use the correct location for the installation directory. For example:
bin/mysql_install_db --user=mysql \
--basedir=/opt/mysql/mysql \
--datadir=/opt/mysql/mysql/dataNote:
After note 'mysql_install_db': mysql-install-db. sets up the 'InnoDB' system tablespace, changes to some tablespace characteristics require setting up a whole new instance. This includes the file name of the first file in the system tablespace and the number of undo logs. If you do not want to use the default values, make sure that the settings for the 'innodb_data_file_path' and 'innodb_log_file_size' configuration parameters are in place in the MySQL configuration file before running note 'mysql_install_db': mysql-install-db. Also make sure to specify as necessary other parameters that affect the creation and location of 'InnoDB' files, such as 'innodb_data_home_dir' and 'innodb_log_group_home_dir'.
If those options are in your configuration file but that file is not in a location that MySQL reads by default, specify the file location using the '--defaults-extra-file' option when you run *note 'mysql_install_db': mysql-install-db.
Note:
If you have set a custom 'TMPDIR' environment variable when performing the installation, and the specified directory is not accessible, *note 'mysql_install_db': mysql-install-db. may fail. If so, unset 'TMPDIR' or set 'TMPDIR' to point to the system temporary directory (usually '/tmp').
Administrative Account Creation
*note 'mysql_install_db': mysql-install-db. creates an administrative account named ''root'@'localhost'' by default.
*note 'mysql_install_db': mysql-install-db. provides options that enable you to control several aspects of the administrative account:
To change the user or host parts of the account name, use '--login-path', or '--admin-user' and '--admin-host'.
'--insecure' suppresses generation of a random password.
'--admin-auth-plugin' specifies the authentication plugin.
'--admin-require-ssl' specifies whether the account must use SSL connections.
For more information, see the descriptions of those options.
*note 'mysql_install_db': mysql-install-db. assigns 'mysql.user' system table rows a nonempty 'plugin' column value to set the authentication plugin. The default value is 'mysql_native_password'. The value can be changed using the '--admin-auth-plugin' option.
Default my.cnf File
*note 'mysql_install_db': mysql-install-db. creates no default 'my.cnf' file.
Note:
As of MySQL 5.7.18, 'my-default.cnf' is no longer included in or installed by distribution packages.
With one exception, the settings in the default option file are commented and have no effect. The exception is that the file sets the 'sql_mode' system variable to 'NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES'. This setting produces a server configuration that results in errors rather than warnings for bad data in operations that modify transactional tables. See *note sql-mode::.
Command Options
note 'mysql_install_db': mysql-install-db. supports the following options, which can be specified on the command line or in the '[mysql_install_db]' group of an option file. For information about option files used by MySQL programs, see note option-files::.
mysql_install_db Options
Option Name Description
-admin-auth-plugin Administrative account authentication plugin
-admin-host Administrative account name host part
-admin-require-ssl Require SSL for administrative account
-admin-user Administrative account name user part
-basedir Path to base directory
-builddir Path to build directory (for out-of-source builds)
-datadir Path to data directory
-defaults Read default option files
-defaults-extra-file Read named option file in addition to usual option files
-defaults-file Read only named option file
-extra-sql-file Optional SQL file to execute during bootstrap
-help Display help message and exit
-insecure Do not generate administrative account random password
-lc-messages Locale for error messages
-lc-messages-dir Directory where error messages are installed
-login-file File to read for login path information
-login-path Read login path options from .mylogin.cnf
-mysqld-file Path to mysqld binary
-no-defaults Read no option files
-random-password-file File in which to write administrative account random password
-skip-sys-schema Do not install or upgrade the sys schema
-srcdir For internal use
-user Operating system user under which to execute mysqld
-verbose Verbose mode
-version Display version information and exit
'--help', '-?'
Command-Line Format
'--help'
Display a help message and exit.
'--admin-auth-plugin=PLUGIN_NAME'
Command-Line Format
'--admin-auth-plugin=plugin_name'
Type
String
The authentication plugin to use for the administrative account. The default is 'mysql_native_password'.
'--admin-host=HOST_NAME'
Command-Line Format
'--admin-host=host_name'
Type
String
The host part to use for the adminstrative account name. The default is 'localhost'. This option is ignored if '--login-path' is also specified.
'--admin-require-ssl'
Command-Line Format
'--admin-require-ssl'
Type
Boolean
Default Value
'FALSE'
Whether to require SSL for the administrative account. The default is not to require it. With this option enabled, the statement that *note 'mysql_install_db': mysql-install-db. uses to create the account includes a 'REQUIRE SSL' clause. As a result, the administrative account must use secure connections when connecting to the server.
'--admin-user=USER_NAME'
Command-Line Format
'--admin-user=user_name'
Type
String
The user part to use for the adminstrative account name. The default is 'root'. This option is ignored if '--login-path' is also specified.
'--basedir=DIR_NAME'
Command-Line Format
'--basedir=dir_name'
Type
Directory name
The path to the MySQL installation directory.
'--builddir=DIR_NAME'
Command-Line Format
'--builddir=dir_name'
Type
Directory name
For use with '--srcdir' and out-of-source builds. Set this to the location of the directory where the built files reside.
'--datadir=DIR_NAME'
Command-Line Format
'--datadir=dir_name'
Type
Directory name
The path to the MySQL data directory. Only the last component of the path name is created if it does not exist; the parent directory must already exist or an error occurs.
Note:
The '--datadir' option is mandatory and the data directory must not already exist.
'--defaults'
Command-Line Format
'--defaults'
Type
Boolean
Default Value
'FALSE'
This option causes note 'mysql_install_db': mysql-install-db. to invoke note 'mysqld': mysqld. in such a way that it reads option files from the default locations. If given as '--no-defaults', and '--defaults-file' or '--defaults-extra-file' is not also specified, note 'mysql_install_db': mysql-install-db. passes '--no-defaults' to note 'mysqld': mysqld, to prevent option files from being read. This may help if program startup fails due to reading unknown options from an option file.
'--defaults-extra-file=FILE_NAME'
Command-Line Format
'--defaults-extra-file=file_name'
Type
File name
Read this option file after the global option file but (on Unix) before the user option file. If the file does not exist or is otherwise inaccessible, an error occurs. If FILE_NAME is not an absolute path name, it is interpreted relative to the current directory.
This option is passed by note 'mysql_install_db': mysql-install-db. to note 'mysqld': mysqld.
For additional information about this and other option-file options, see *note option-file-options::.
'--defaults-file=FILE_NAME'
Command-Line Format
'--defaults-file=file_name'
Type
File name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs. If FILE_NAME is not an absolute path name, it is interpreted relative to the current directory.
This option is passed by note 'mysql_install_db': mysql-install-db. to note 'mysqld': mysqld.
For additional information about this and other option-file options, see *note option-file-options::.
'--extra-sql-file=FILE_NAME', '-f FILE_NAME'
Command-Line Format
'--extra-sql-file=file_name'
Type
File name
This option names a file containing additional SQL statements to be executed after the standard bootstrapping statements. Accepted statement syntax in the file is like that of the *note 'mysql': mysql. command-line client, including support for multiple-line C-style comments and delimiter handling to enable definition of stored programs.
'--insecure'
Command-Line Format
'--insecure'
Type
Boolean
Default Value
'FALSE'
Do not generate a random password for the adminstrative account.
If '--insecure' is not given, it is necessary after note 'mysql_install_db': mysql-install-db. has been run to start the server, connect using the administrative account with the password written to the '.mysql_secret' file, and specify a new administrative password. Until this is done, the administrative account cannot be used for anything else. To change the password, you can use the note 'SET PASSWORD': set-password. statement (for example, with the note 'mysql': mysql. or note 'mysqladmin': mysqladmin. client). After resetting the password, remove the '.mysql_secret' file; otherwise, if you run *note 'mysql_secure_installation': mysql-secure-installation, that command may see the file and expire the 'root' password again as part of ensuring secure deployment.
'--lc-messages=name'
Command-Line Format
'--lc-messages=name'
Type
String
Default Value
'en_US'
The locale to use for error messages. The default is 'en_US'. The argument is converted to a language name and combined with the value of '--lc-messages-dir' to produce the location for the error message file. See *note error-message-language::.
'--lc-messages-dir=DIR_NAME'
Command-Line Format
'--lc-messages-dir=dir_name'
Type
Directory name
The directory where error messages are located. The value is used together with the value of '--lc-messages' to produce the location for the error message file. See *note error-message-language::.
'--login-file=FILE_NAME'
Command-Line Format
'--login-file=file_name'
Type
File name
The file from which to read the login path if the '--login-path=FILE_NAME' option is specified. The default file is '.mylogin.cnf'.
'--login-path=NAME'
Command-Line Format
'--login-path=name'
Type
String
Read options from the named login path in the '.mylogin.cnf' login path file. The default login path is 'client'. (To read a different file, use the '--login-file=NAME' option.) A 'login path' is an option group containing options that specify which MySQL server to connect to and which account to authenticate as. To create or modify a login path file, use the note 'mysql_config_editor': mysql-config-editor. utility. See note mysql-config-editor::.
If the '--login-path' option is specified, the user, host, and password values are taken from the login path and used to create the administrative account. The password must be defined in the login path or an error occurs, unless the '--insecure' option is also specified. In addition, with '--login-path', any '--admin-host' and '--admin-user' options are ignored.
For additional information about this and other option-file options, see *note option-file-options::.
'--mysqld-file=FILE_NAME'
Command-Line Format
'--mysqld-file=file_name'
Type
File name
The path name of the *note 'mysqld': mysqld. binary to execute. The option value must be an absolute path name or an error occurs.
If this option is not given, note 'mysql_install_db': mysql-install-db. searches for note 'mysqld': mysqld. in these locations:
* In the 'bin' directory under the '--basedir' option value, if
that option was given.
* In the 'bin' directory under the '--srcdir' option value, if
that option was given.
* In the 'bin' directory under the '--builddir' option value, if
that option was given.
* In the local directory and in the 'bin' and 'sbin' directories
under the local directory.
* In '/usr/bin', '/usr/sbin', '/usr/local/bin',
'/usr/local/sbin', '/opt/local/bin', '/opt/local/sbin'.'--no-defaults'
Command-Line Format
'--no-defaults'
For behavior of this option, see the description of '--defaults'.
For additional information about this and other option-file options, see *note option-file-options::.
'--random-password-file=FILE_NAME'
Command-Line Format
'--random-password-file=file_name'
Type
File name
The path name of the file in which to write the randomly generated password for the administrative account. The option value must be an absolute path name or an error occurs. The default is '$HOME/.mysql_secret'.
'--skip-sys-schema'
Command-Line Format
'--skip-sys-schema'
Type
Boolean
Default Value
'FALSE'
*note 'mysql_install_db': mysql-install-db. installs the 'sys' schema. The '--skip-sys-schema' option suppresses this behavior.
'--srcdir=DIR_NAME'
Command-Line Format
'--srcdir=dir_name'
Type
Directory name
For internal use. This option specifies the directory under which *note 'mysql_install_db': mysql-install-db. looks for support files such as the error message file and the file for populating the help tables.
'--user=USER_NAME', '-u USER_NAME'
Command-Line Format
'--user=user_name'
The system (login) user name to use for running note 'mysqld': mysqld. Files and directories created by note 'mysqld': mysqld. are owned by this user. You must be the system 'root' user to use this option. By default, *note 'mysqld': mysqld. runs using your current login name; files and directories that it creates are owned by you.
'--verbose', '-v'
Command-Line Format
'--verbose'
Verbose mode. Print more information about what the program does. You can use this option to see the note 'mysqld': mysqld. command that note 'mysql_install_db': mysql-install-db. invokes to start the server in bootstrap mode.
'--version', '-V'
Command-Line Format
'--version'
Display version information and exit.
File: manual.info.tmp, Node: mysql-plugin, Next: mysql-secure-installation, Prev: mysql-install-db, Up: programs-installation
Note:
note 'mysql_plugin': mysql-plugin. is deprecated as of MySQL 5.7.11 and removed in MySQL 8.0. Alternatives include loading plugins at server startup using the '--plugin-load' or '--plugin-load-add' option, or at runtime using the note 'INSTALL PLUGIN': install-plugin. statement.
The note 'mysql_plugin': mysql-plugin. utility enables MySQL administrators to manage which plugins a MySQL server loads. It provides an alternative to manually specifying the '--plugin-load' option at server startup or using the note 'INSTALL PLUGIN': install-plugin. and *note 'UNINSTALL PLUGIN': uninstall-plugin. statements at runtime.
Depending on whether note 'mysql_plugin': mysql-plugin. is invoked to enable or disable plugins, it inserts or deletes rows in the 'mysql.plugin' table that serves as a plugin registry. (To perform this operation, note 'mysql_plugin': mysql-plugin. invokes the MySQL server in bootstrap mode. This means that the server must not already be running.) For normal server startups, the server loads and enables plugins listed in 'mysql.plugin' automatically. For additional control over plugin activation, use '--PLUGIN_NAME' options named for specific plugins, as described in *note plugin-loading::.
Each invocation of note 'mysql_plugin': mysql-plugin. reads a configuration file to determine how to configure the plugins contained in a single plugin library file. To invoke note 'mysql_plugin': mysql-plugin, use this syntax:
mysql_plugin [OPTIONS] PLUGIN {ENABLE|DISABLE}PLUGIN is the name of the plugin to configure. 'ENABLE' or 'DISABLE' (not case-sensitive) specify whether to enable or disable components of the plugin library named in the configuration file. The order of the PLUGIN and 'ENABLE' or 'DISABLE' arguments does not matter.
For example, to configure components of a plugin library file named 'myplugins.so' on Linux or 'myplugins.dll' on Windows, specify a PLUGIN value of 'myplugins'. Suppose that this plugin library contains three plugins, 'plugin1', 'plugin2', and 'plugin3', all of which should be configured under *note 'mysql_plugin': mysql-plugin. control. By convention, configuration files have a suffix of '.ini' and the same base name as the plugin library, so the default configuration file name for this plugin library is 'myplugins.ini'. The configuration file contents look like this:
myplugins
plugin1
plugin2
plugin3The first line in the 'myplugins.ini' file is the name of the library file, without any extension such as '.so' or '.dll'. The remaining lines are the names of the components to be enabled or disabled. Each value in the file should be on a separate line. Lines on which the first character is ''#'' are taken as comments and ignored.
To enable the plugins listed in the configuration file, invoke *note 'mysql_plugin': mysql-plugin. this way:
mysql_plugin myplugins ENABLETo disable the plugins, use 'DISABLE' rather than 'ENABLE'.
An error occurs if note 'mysql_plugin': mysql-plugin. cannot find the configuration file or plugin library file, or if note 'mysql_plugin': mysql-plugin. cannot start the MySQL server.
note 'mysql_plugin': mysql-plugin. supports the following options, which can be specified on the command line or in the '[mysqld]' group of any option file. For options specified in a '[mysqld]' group, note 'mysql_plugin': mysql-plugin. recognizes the '--basedir', '--datadir', and '--plugin-dir' options and ignores others. For information about option files used by MySQL programs, see *note option-files::.
mysql_plugin Options
Option Name Description
-basedir The server base directory
-datadir The server data directory
-help Display help message and exit
-my-print-defaults Path to my_print_defaults
-mysqld Path to server
-no-defaults Do not read configuration file
-plugin-dir Directory where plugins are installed
-plugin-ini The plugin configuration file
-print-defaults Show configuration file defaults
-verbose Verbose mode
-version Display version information and exit
'--help', '-?'
Command-Line Format
'--help'
Display a help message and exit.
'--basedir=DIR_NAME', '-b DIR_NAME'
Command-Line Format
'--basedir=dir_name'
Type
Directory name
The server base directory.
'--datadir=DIR_NAME', '-d DIR_NAME'
Command-Line Format
'--datadir=dir_name'
Type
Directory name
The server data directory.
'--my-print-defaults=FILE_NAME', '-b FILE_NAME'
Command-Line Format
'--my-print-defaults=file_name'
Type
File name
The path to the *note 'my_print_defaults': my-print-defaults. program.
'--mysqld=FILE_NAME', '-b FILE_NAME'
Command-Line Format
'--mysqld=file_name'
Type
File name
The path to the *note 'mysqld': mysqld. server.
'--no-defaults', '-p'
Command-Line Format
'--no-defaults'
Do not read values from the configuration file. This option enables an administrator to skip reading defaults from the configuration file.
With *note 'mysql_plugin': mysql-plugin, this option need not be given first on the command line, unlike most other MySQL programs that support '--no-defaults'.
'--plugin-dir=DIR_NAME', '-p DIR_NAME'
Command-Line Format
'--plugin-dir=dir_name'
Type
Directory name
The server plugin directory.
'--plugin-ini=FILE_NAME', '-i FILE_NAME'
Command-Line Format
'--plugin-ini=file_name'
Type
File name
The *note 'mysql_plugin': mysql-plugin. configuration file. Relative path names are interpreted relative to the current directory. If this option is not given, the default is 'PLUGIN.ini' in the plugin directory, where PLUGIN is the PLUGIN argument on the command line.
'--print-defaults', '-P'
Command-Line Format
'--print-defaults'
Display the default values from the configuration file. This option causes *note 'mysql_plugin': mysql-plugin. to print the defaults for '--basedir', '--datadir', and '--plugin-dir' if they are found in the configuration file. If no value for a variable is found, nothing is shown.
With *note 'mysql_plugin': mysql-plugin, this option need not be given first on the command line, unlike most other MySQL programs that support '--print-defaults'.
'--verbose', '-v'
Command-Line Format
'--verbose'
Verbose mode. Print more information about what the program does. This option can be used multiple times to increase the amount of information.
'--version', '-V'
Command-Line Format
'--version'
Display version information and exit.
File: manual.info.tmp, Node: mysql-secure-installation, Next: mysql-ssl-rsa-setup, Prev: mysql-plugin, Up: programs-installation
This program enables you to improve the security of your MySQL installation in the following ways:
You can set a password for 'root' accounts.
You can remove 'root' accounts that are accessible from outside the local host.
You can remove anonymous-user accounts.
You can remove the 'test' database (which by default can be accessed by all users, even anonymous users), and privileges that permit anyone to access databases with names that start with 'test_'.
note 'mysql_secure_installation': mysql-secure-installation. helps you implement security recommendations similar to those described at note default-privileges::.
Normal usage is to connect to the local MySQL server; invoke *note 'mysql_secure_installation': mysql-secure-installation. without arguments:
mysql_secure_installationWhen executed, *note 'mysql_secure_installation': mysql-secure-installation. prompts you to determine which actions to perform.
The 'validate_password' plugin can be used for password strength checking. If the plugin is not installed, *note 'mysql_secure_installation': mysql-secure-installation. prompts the user whether to install it. Any passwords entered later are checked using the plugin if it is enabled.
Most of the usual MySQL client options such as '--host' and '--port' can be used on the command line and in option files. For example, to connect to the local server over IPv6 using port 3307, use this command:
mysql_secure_installation --host=::1 --port=3307note 'mysql_secure_installation': mysql-secure-installation. supports the following options, which can be specified on the command line or in the '[mysql_secure_installation]' and '[client]' groups of an option file. For information about option files used by MySQL programs, see note option-files::.
mysql_secure_installation Options
Option Name Description Introduced
-defaults-extra-file
Read named option file in addition to usual option files
-defaults-file
Read only named option file
-defaults-group-suffix
Option group suffix value
-help
Display help message and exit
-host
Host on which MySQL server is located
-no-defaults
Read no option files
-password
Accepted but always ignored. Whenever mysql_secure_installation is invoked, the user is prompted for a password, regardless
-port
TCP/IP port number for connection
-print-defaults
Print default options
-protocol
Transport protocol to use
-socket
Unix socket file or Windows named pipe to use
-ssl
Enable connection encryption
-ssl-ca
File that contains list of trusted SSL Certificate Authorities
-ssl-capath
Directory that contains trusted SSL Certificate Authority certificate files
-ssl-cert
File that contains X.509 certificate
-ssl-cipher
Permissible ciphers for connection encryption
-ssl-crl
File that contains certificate revocation lists
-ssl-crlpath
Directory that contains certificate revocation-list files
-ssl-key
File that contains X.509 key
-ssl-mode
Desired security 5.7.11 state of connection
to server
-ssl-verify-server-cert
Verify host name against server certificate Common Name identity
-tls-version
Permissible TLS 5.7.10 protocols for
encrypted connections
-use-default
Execute with no user interactivity
-user
MySQL user name to use when connecting to server
'--help', '-?'
Command-Line Format
'--help'
Display a help message and exit.
'--defaults-extra-file=FILE_NAME'
Command-Line Format
'--defaults-extra-file=file_name'
Type
File name
Read this option file after the global option file but (on Unix) before the user option file. If the file does not exist or is otherwise inaccessible, an error occurs. If FILE_NAME is not an absolute path name, it is interpreted relative to the current directory.
For additional information about this and other option-file options, see *note option-file-options::.
'--defaults-file=FILE_NAME'
Command-Line Format
'--defaults-file=file_name'
Type
File name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs. If FILE_NAME is not an absolute path name, it is interpreted relative to the current directory.
For additional information about this and other option-file options, see *note option-file-options::.
'--defaults-group-suffix=STR'
Command-Line Format
'--defaults-group-suffix=str'
Type
String
Read not only the usual option groups, but also groups with the usual names and a suffix of STR. For example, *note 'mysql_secure_installation': mysql-secure-installation. normally reads the '[client]' and '[mysql_secure_installation]' groups. If this option is given as '--defaults-group-suffix=_other', *note 'mysql_secure_installation': mysql-secure-installation. also reads the '[client_other]' and '[mysql_secure_installation_other]' groups.
For additional information about this and other option-file options, see *note option-file-options::.
'--host=HOST_NAME', '-h HOST_NAME'
Command-Line Format
'--host'
Connect to the MySQL server on the given host.
'--no-defaults'
Command-Line Format
'--no-defaults'
Do not read any option files. If program startup fails due to reading unknown options from an option file, '--no-defaults' can be used to prevent them from being read.
The exception is that the '.mylogin.cnf' file is read in all cases, if it exists. This permits passwords to be specified in a safer way than on the command line even when '--no-defaults' is used. To create '.mylogin.cnf', use the note 'mysql_config_editor': mysql-config-editor. utility. See note mysql-config-editor::.
For additional information about this and other option-file options, see *note option-file-options::.
'--password=PASSWORD', '-p PASSWORD'
Command-Line Format
'--password=password'
Type
String
Default Value
'[none]'
This option is accepted but ignored. Whether or not this option is used, *note 'mysql_secure_installation': mysql-secure-installation. always prompts the user for a password.
'--port=PORT_NUM', '-P PORT_NUM'
Command-Line Format
'--port=port_num'
Type
Numeric
Default Value
'3306'
For TCP/IP connections, the port number to use.
'--print-defaults'
Command-Line Format
'--print-defaults'
Print the program name and all options that it gets from option files.
For additional information about this and other option-file options, see *note option-file-options::.
'--protocol={TCP|SOCKET|PIPE|MEMORY}'
Command-Line Format
'--protocol=type'
Type
String
Default Value
'[see text]'
Valid Values
'TCP' 'SOCKET' 'PIPE' 'MEMORY'
The transport protocol to use for connecting to the server. It is useful when the other connection parameters normally result in use of a protocol other than the one you want. For details on the permissible values, see *note transport-protocols::.
'--socket=PATH', '-S PATH'
Command-Line Format
'--socket={file_name|pipe_name}'
Type
String
For connections to 'localhost', the Unix socket file to use, or, on Windows, the name of the named pipe to use.
On Windows, this option applies only if the server was started with the 'named_pipe' system variable enabled to support named-pipe connections. In addition, the user making the connection must be a member of the Windows group specified by the 'named_pipe_full_access_group' system variable.
'--ssl*'
Options that begin with '--ssl' specify whether to connect to the server using encryption and indicate where to find SSL keys and certificates. See *note encrypted-connection-options::.
'--tls-version=PROTOCOL_LIST'
Command-Line Format
'--tls-version=protocol_list'
Introduced
5.7.10
Type
String
Default Value (≥ 5.7.28)
'TLSv1,TLSv1.1,TLSv1.2'
Default Value (<= 5.7.27)
'TLSv1,TLSv1.1,TLSv1.2' (OpenSSL) 'TLSv1,TLSv1.1' (yaSSL)
The permissible TLS protocols for encrypted connections. The value is a list of one or more comma-separated protocol names. The protocols that can be named for this option depend on the SSL library used to compile MySQL. For details, see *note encrypted-connection-protocols-ciphers::.
This option was added in MySQL 5.7.10.
'--use-default'
Command-Line Format
'--use-default'
Type
Boolean
Execute noninteractively. This option can be used for unattended installation operations.
'--user=USER_NAME', '-u USER_NAME'
Command-Line Format
'--user=user_name'
Type
String
The user name of the MySQL account to use for connecting to the server.
File: manual.info.tmp, Node: mysql-ssl-rsa-setup, Next: mysql-tzinfo-to-sql, Prev: mysql-secure-installation, Up: programs-installation
This program creates the SSL certificate and key files and RSA key-pair files required to support secure connections using SSL and secure password exchange using RSA over unencrypted connections, if those files are missing. *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. can also be used to create new SSL files if the existing ones have expired.
Note:
*note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. uses the 'openssl' command, so its use is contingent on having OpenSSL installed on your machine.
Another way to generate SSL and RSA files, for MySQL distributions compiled using OpenSSL, is to have the server generate them automatically. See *note creating-ssl-rsa-files-using-mysql::.
Important:
note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. helps lower the barrier to using SSL by making it easier to generate the required files. However, certificates generated by note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. are self-signed, which is not very secure. After you gain experience using the files created by *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup, consider obtaining a CA certificate from a registered certificate authority.
Invoke *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. like this:
mysql_ssl_rsa_setup [OPTIONS]Typical options are '--datadir' to specify where to create the files, and '--verbose' to see the 'openssl' commands that *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. executes.
*note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. attempts to create SSL and RSA files using a default set of file names. It works as follows:
note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. checks for the 'openssl' binary at the locations specified by the 'PATH' environment variable. If 'openssl' is not found, note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. does nothing. If 'openssl' is present, *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. looks for default SSL and RSA files in the MySQL data directory specified by the '--datadir' option, or the compiled-in data directory if the '--datadir' option is not given.
*note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. checks the data directory for SSL files with the following names:
ca.pem
server-cert.pem
server-key.pemIf any of those files are present, *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. creates no SSL files. Otherwise, it invokes 'openssl' to create them, plus some additional files:
ca.pem Self-signed CA certificate
ca-key.pem CA private key
server-cert.pem Server certificate
server-key.pem Server private key
client-cert.pem Client certificate
client-key.pem Client private keyThese files enable secure client connections using SSL; see *note using-encrypted-connections::.
*note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. checks the data directory for RSA files with the following names:
private_key.pem Private member of private/public key pair
public_key.pem Public member of private/public key pairIf any of these files are present, note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. creates no RSA files. Otherwise, it invokes 'openssl' to create them. These files enable secure password exchange using RSA over unencrypted connections for accounts authenticated by the 'sha256_password' plugin; see note sha256-pluggable-authentication::.
For information about the characteristics of files created by note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup, see note creating-ssl-rsa-files-using-mysql::.
At startup, the MySQL server automatically uses the SSL files created by *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. to enable SSL if no explicit SSL options are given other than '--ssl' (possibly along with 'ssl_cipher'). If you prefer to designate the files explicitly, invoke clients with the '--ssl-ca', '--ssl-cert', and '--ssl-key' options at startup to name the 'ca.pem', 'server-cert.pem', and 'server-key.pem' files, respectively.
The server also automatically uses the RSA files created by *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. to enable RSA if no explicit RSA options are given.
If the server is SSL-enabled, clients use SSL by default for the connection. To specify certificate and key files explicitly, use the '--ssl-ca', '--ssl-cert', and '--ssl-key' options to name the 'ca.pem', 'client-cert.pem', and 'client-key.pem' files, respectively. However, some additional client setup may be required first because *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. by default creates those files in the data directory. The permissions for the data directory normally enable access only to the system account that runs the MySQL server, so client programs cannot use files located there. To make the files available, copy them to a directory that is readable (but not writable) by clients:
For local clients, the MySQL installation directory can be used. For example, if the data directory is a subdirectory of the installation directory and your current location is the data directory, you can copy the files like this:
cp ca.pem client-cert.pem client-key.pem ..For remote clients, distribute the files using a secure channel to ensure they are not tampered with during transit.
If the SSL files used for a MySQL installation have expired, you can use *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. to create new ones:
Stop the server.
Rename or remove the existing SSL files. You may wish to make a backup of them first. (The RSA files do not expire, so you need not remove them. *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. sees that they exist and not overwrite them.)
Run *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. with the '--datadir' option to specify where to create the new files.
Restart the server.
note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. supports the following command-line options, which can be specified on the command line or in the '[mysql_ssl_rsa_setup]', '[mysql_install_db]', and '[mysqld]' groups of an option file. For information about option files used by MySQL programs, see note option-files::.
mysql_ssl_rsa_setup Options
Option Name Description
-datadir Path to data directory
-help Display help message and exit
-suffix Suffix for X.509 certificate Common Name attribute
-uid Name of effective user to use for file permissions
-verbose Verbose mode
-version Display version information and exit
'--help', '?'
Command-Line Format
'--help'
Display a help message and exit.
'--datadir=DIR_NAME'
Command-Line Format
'--datadir=dir_name'
Type
Directory name
The path to the directory that *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. should check for default SSL and RSA files and in which it should create files if they are missing. The default is the compiled-in data directory.
'--suffix=STR'
Command-Line Format
'--suffix=str'
Type
String
The suffix for the Common Name attribute in X.509 certificates. The suffix value is limited to 17 characters. The default is based on the MySQL version number.
'--uid=name', '-v'
Command-Line Format
'--uid=name'
The name of the user who should be the owner of any created files. The value is a user name, not a numeric user ID. In the absence of this option, files created by *note 'mysql_ssl_rsa_setup': mysql-ssl-rsa-setup. are owned by the user who executes it. This option is valid only if you execute the program as 'root' on a system that supports the 'chown()' system call.
'--verbose', '-v'
Command-Line Format
'--verbose'
Verbose mode. Produce more output about what the program does. For example, the program shows the 'openssl' commands it runs, and produces output to indicate whether it skips SSL or RSA file creation because some default file already exists.
'--version', '-V'
Command-Line Format
'--version'
Display version information and exit.
File: manual.info.tmp, Node: mysql-tzinfo-to-sql, Next: mysql-upgrade, Prev: mysql-ssl-rsa-setup, Up: programs-installation
The note 'mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. program loads the time zone tables in the 'mysql' database. It is used on systems that have a zoneinfo database (the set of files describing time zones). Examples of such systems are Linux, FreeBSD, Solaris, and macOS. One likely location for these files is the '/usr/share/zoneinfo' directory ('/usr/share/lib/zoneinfo' on Solaris). If your system does not have a zoneinfo database, you can use the downloadable package described in note time-zone-support::.
*note 'mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. can be invoked several ways:
mysql_tzinfo_to_sql TZ_DIR
mysql_tzinfo_to_sql TZ_FILE TZ_NAME
mysql_tzinfo_to_sql --leap TZ_FILEFor the first invocation syntax, pass the zoneinfo directory path name to note 'mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. and send the output into the note 'mysql': mysql. program. For example:
mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysqlnote 'mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. reads your system's time zone files and generates SQL statements from them. note 'mysql': mysql. processes those statements to load the time zone tables.
The second syntax causes *note 'mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. to load a single time zone file TZ_FILE that corresponds to a time zone name TZ_NAME:
mysql_tzinfo_to_sql TZ_FILE TZ_NAME | mysql -u root mysqlIf your time zone needs to account for leap seconds, invoke *note 'mysql_tzinfo_to_sql': mysql-tzinfo-to-sql. using the third syntax, which initializes the leap second information. TZ_FILE is the name of your time zone file:
mysql_tzinfo_to_sql --leap TZ_FILE | mysql -u root mysqlAfter running *note 'mysql_tzinfo_to_sql': mysql-tzinfo-to-sql, it is best to restart the server so that it does not continue to use any previously cached time zone data.
File: manual.info.tmp, Node: mysql-upgrade, Prev: mysql-tzinfo-to-sql, Up: programs-installation
Each time you upgrade MySQL, you should execute *note 'mysql_upgrade': mysql-upgrade, which looks for incompatibilities with the upgraded MySQL server:
It upgrades the system tables in the 'mysql' schema so that you can take advantage of new privileges or capabilities that might have been added.
It upgrades the Performance Schema and 'sys' schema.
It examines user schemas.
If note 'mysql_upgrade': mysql-upgrade. finds that a table has a possible incompatibility, it performs a table check and, if problems are found, attempts a table repair. If the table cannot be repaired, see note rebuilding-tables:: for manual table repair strategies.
*note 'mysql_upgrade': mysql-upgrade. communicates directly with the MySQL server, sending it the SQL statements required to perform an upgrade.
Important:
In MySQL 5.7.11, the default '--early-plugin-load' value is the name of the 'keyring_file' plugin library file, causing that plugin to be loaded by default. In MySQL 5.7.12 and higher, the default '--early-plugin-load' value is empty; to load the 'keyring_file' plugin, you must explicitly specify the option with a value naming the 'keyring_file' plugin library file.
'InnoDB' tablespace encryption requires that the keyring plugin to be used be loaded prior to 'InnoDB' initialization, so this change of default '--early-plugin-load' value introduces an incompatibility for upgrades from 5.7.11 to 5.7.12 or higher. Administrators who have encrypted 'InnoDB' tablespaces must take explicit action to ensure continued loading of the keyring plugin: Start the server with an '--early-plugin-load' option that names the plugin library file. For additional information, see *note keyring-plugin-installation::.
Important:
If you upgrade to MySQL 5.7.2 or later from a version older than 5.7.2, a change to the 'mysql.user' table requires a special sequence of steps to perform an upgrade using note 'mysql_upgrade': mysql-upgrade. For details, see note upgrading-from-previous-series::.
Note:
On Windows, you must run *note 'mysql_upgrade': mysql-upgrade. with administrator privileges. You can do this by running a Command Prompt as Administrator and running the command. Failure to do so may result in the upgrade failing to execute correctly.
Caution:
You should always back up your current MySQL installation before performing an upgrade. See *note backup-methods::.
Some upgrade incompatibilities may require special handling before upgrading your MySQL installation and running note 'mysql_upgrade': mysql-upgrade. See note upgrading::, for instructions on determining whether any such incompatibilities apply to your installation and how to handle them.
Use *note 'mysql_upgrade': mysql-upgrade. like this:
Ensure that the server is running.
Invoke *note 'mysql_upgrade': mysql-upgrade. to upgrade the system tables in the 'mysql' schema and check and repair tables in other schemas:
mysql_upgrade [OPTIONS]Stop the server and restart it so that any system table changes take effect.
If you have multiple MySQL server instances to upgrade, invoke *note 'mysql_upgrade': mysql-upgrade. with connection parameters appropriate for connecting to each of the desired servers. For example, with servers running on the local host on parts 3306 through 3308, upgrade each of them by connecting to the appropriate port:
mysql_upgrade --protocol=tcp -P 3306 [OTHER_OPTIONS]
mysql_upgrade --protocol=tcp -P 3307 [OTHER_OPTIONS]
mysql_upgrade --protocol=tcp -P 3308 [OTHER_OPTIONS]For local host connections on Unix, the '--protocol=tcp' option forces a connection using TCP/IP rather than the Unix socket file.
By default, note 'mysql_upgrade': mysql-upgrade. runs as the MySQL 'root' user. If the 'root' password is expired when you run note 'mysql_upgrade': mysql-upgrade, it displays a message telling you that your password is expired and that note 'mysql_upgrade': mysql-upgrade. failed as a result. To correct this, reset the 'root' password to unexpire it and run note 'mysql_upgrade': mysql-upgrade. again. First, connect to the server as 'root':
$> mysql -u root -p
Enter password: **** <- enter root password hereReset the password using *note 'ALTER USER': alter-user.:
mysql> ALTER USER USER() IDENTIFIED BY 'ROOT-PASSWORD';Then exit note 'mysql': mysql. and run note 'mysql_upgrade': mysql-upgrade. again:
$> mysql_upgrade [OPTIONS]Note:
If you run the server with the 'disabled_storage_engines' system variable set to disable certain storage engines (for example, 'MyISAM'), *note 'mysql_upgrade': mysql-upgrade. might fail with an error like this:
mysql_upgrade: [ERROR] 3161: Storage engine MyISAM is disabled
(Table creation is disallowed).To handle this, restart the server with 'disabled_storage_engines' disabled. Then you should be able to run *note 'mysql_upgrade': mysql-upgrade. successfully. After that, restart the server with 'disabled_storage_engines' set to its original value.
Unless invoked with the '--upgrade-system-tables' option, note 'mysql_upgrade': mysql-upgrade. processes all tables in all user schemas as necessary. Table checking might take a long time to complete. Each table is locked and therefore unavailable to other sessions while it is being processed. Check and repair operations can be time-consuming, particularly for large tables. Table checking uses the 'FOR UPGRADE' option of the note 'CHECK TABLE': check-table. statement. For details about what this option entails, see *note check-table::.
note 'mysql_upgrade': mysql-upgrade. marks all checked and repaired tables with the current MySQL version number. This ensures that the next time you run note 'mysql_upgrade': mysql-upgrade. with the same version of the server, it can be determined whether there is any need to check or repair a given table again.
*note 'mysql_upgrade': mysql-upgrade. saves the MySQL version number in a file named 'mysql_upgrade_info' in the data directory. This is used to quickly check whether all tables have been checked for this release so that table-checking can be skipped. To ignore this file and perform the check regardless, use the '--force' option.
*note 'mysql_upgrade': mysql-upgrade. checks 'mysql.user' system table rows and, for any row with an empty 'plugin' column, sets that column to ''mysql_native_password'' or ''mysql_old_password'' depending on the hash format of the 'Password' column value.
Support for pre-4.1 password hashing and 'mysql_old_password' has been removed, so note 'mysql_upgrade': mysql-upgrade. sets empty 'plugin' values to ''mysql_native_password'' if the credentials use a hash format compatible with that plugin. Rows with a pre-4.1 password hash must be upgraded manually. For account upgrade instructions, see note account-upgrades::.
note 'mysql_upgrade': mysql-upgrade. does not upgrade the contents of the time zone tables or help tables. For upgrade instructions, see note time-zone-support::, and *note server-side-help-support::.
Unless invoked with the '--skip-sys-schema' option, *note 'mysql_upgrade': mysql-upgrade. installs the 'sys' schema if it is not installed, and upgrades it to the current version otherwise. An error occurs if a 'sys' schema exists but has no 'version' view, on the assumption that its absence indicates a user-created schema:
A sys schema exists with no sys.version view. If
you have a user created sys schema, this must be renamed for the
upgrade to succeed.To upgrade in this case, remove or rename the existing 'sys' schema first.
note 'mysql_upgrade': mysql-upgrade. checks for partitioned 'InnoDB' tables that were created using the generic partitioning handler and attempts to upgrade them to 'InnoDB' native partitioning. (Bug #76734, Bug #20727344) You can upgrade such tables individually in the note 'mysql': mysql. client using the *note 'ALTER TABLE ... UPGRADE PARTITIONING': alter-table-partition-operations. SQL statement.
note 'mysql_upgrade': mysql-upgrade. supports the following options, which can be specified on the command line or in the '[mysql_upgrade]' and '[client]' groups of an option file. For information about option files used by MySQL programs, see note option-files::.
mysql_upgrade Options
Option Name Description Introduced
-bind-address
Use specified network interface to connect to MySQL Server
-character-sets-dir
Directory where character sets are installed
-compress
Compress all information sent between client and server
-debug
Write debugging log
-debug-check
Print debugging information when program exits
-debug-info
Print debugging information, memory, and CPU statistics when program exits
-default-auth
Authentication plugin to use
-default-character-set
Specify default character set
-defaults-extra-file
Read named option file in addition to usual option files
-defaults-file
Read only named option file
-defaults-group-suffix
Option group suffix value
-force
Force execution even if mysql_upgrade has already been executed for current MySQL version
-help
Display help message and exit
-host
Host on which MySQL server is located
-login-path
Read login path options from .mylogin.cnf
-max-allowed-packet
Maximum packet length to send to or receive from server
-net-buffer-length
Buffer size for TCP/IP and socket communication
-no-defaults
Read no option files
-password
Password to use when connecting to server
-pipe
Connect to server using named pipe (Windows only)
-plugin-dir
Directory where plugins are installed
-port
TCP/IP port number for connection
-print-defaults
Print default options
-protocol
Transport protocol to use
-shared-memory-base-name
Shared-memory name for shared-memory connections (Windows only)
-skip-sys-schema
Do not install or upgrade sys schema
-socket
Unix socket file or Windows named pipe to use
-ssl
Enable connection encryption
-ssl-ca
File that contains list of trusted SSL Certificate Authorities
-ssl-capath
Directory that contains trusted SSL Certificate Authority certificate files
-ssl-cert
File that contains X.509 certificate
-ssl-cipher
Permissible ciphers for connection encryption
-ssl-crl
File that contains certificate revocation lists
-ssl-crlpath
Directory that contains certificate revocation-list files
-ssl-key
File that contains X.509 key
-ssl-mode
Desired security 5.7.11 state of connection
to server
-ssl-verify-server-cert
Verify host name against server certificate Common Name identity
-tls-version
Permissible TLS 5.7.10 protocols for
encrypted connections
-upgrade-system-tables
Update only system tables, not user schemas
-user
MySQL user name to use when connecting to server
-verbose
Verbose mode
-version-check
Check for proper server version
-write-binlog
Write all statements to binary log
'--help'
Command-Line Format
'--help'
Display a short help message and exit.
'--bind-address=IP_ADDRESS'
Command-Line Format
'--bind-address=ip_address'
On a computer having multiple network interfaces, use this option to select which interface to use for connecting to the MySQL server.
'--character-sets-dir=DIR_NAME'
Command-Line Format
'--character-sets-dir=dir_name'
Type
Directory name
The directory where character sets are installed. See *note charset-configuration::.
'--compress', '-C'
Command-Line Format
'--compress[={OFF|ON}]'
Type
Boolean
Default Value
'OFF'
Compress all information sent between the client and the server if possible. See *note connection-compression-control::.
'--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'
Command-Line Format
'--debug[=#]'
Type
String
Default Value
'd:t:O,/tmp/mysql_upgrade.trace'
Write a debugging log. A typical DEBUG_OPTIONS string is 'd:t:o,FILE_NAME'. The default is 'd:t:O,/tmp/mysql_upgrade.trace'.
'--debug-check'
Command-Line Format
'--debug-check'
Type
Boolean
Print some debugging information when the program exits.
'--debug-info', '-T'
Command-Line Format
'--debug-info'
Type
Boolean
Default Value
'FALSE'
Print debugging information and memory and CPU usage statistics when the program exits.
'--default-auth=PLUGIN'
Command-Line Format
'--default-auth=plugin'
Type
String
A hint about which client-side authentication plugin to use. See *note pluggable-authentication::.
'--default-character-set=CHARSET_NAME'
Command-Line Format
'--default-character-set=name'
Type
String
Use CHARSET_NAME as the default character set. See *note charset-configuration::.
'--defaults-extra-file=FILE_NAME'
Command-Line Format
'--defaults-extra-file=file_name'
Type
File name
Read this option file after the global option file but (on Unix) before the user option file. If the file does not exist or is otherwise inaccessible, an error occurs. If FILE_NAME is not an absolute path name, it is interpreted relative to the current directory.
For additional information about this and other option-file options, see *note option-file-options::.
'--defaults-file=FILE_NAME'
Command-Line Format
'--defaults-file=file_name'
Type
File name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs. If FILE_NAME is not an absolute path name, it is interpreted relative to the current directory.
For additional information about this and other option-file options, see *note option-file-options::.
'--defaults-group-suffix=STR'
Command-Line Format
'--defaults-group-suffix=str'
Type
String
Read not only the usual option groups, but also groups with the usual names and a suffix of STR. For example, *note 'mysql_upgrade': mysql-upgrade. normally reads the '[client]' and '[mysql_upgrade]' groups. If this option is given as '--defaults-group-suffix=_other', *note 'mysql_upgrade': mysql-upgrade. also reads the '[client_other]' and '[mysql_upgrade_other]' groups.
For additional information about this and other option-file options, see *note option-file-options::.
'--force'
Command-Line Format
'--force'
Type
Boolean
Ignore the 'mysql_upgrade_info' file and force execution even if *note 'mysql_upgrade': mysql-upgrade. has already been executed for the current version of MySQL.
'--host=HOST_NAME', '-h HOST_NAME'
Command-Line Format
'--host=name'
Type
String
Connect to the MySQL server on the given host.
'--login-path=NAME'
Command-Line Format
'--login-path=name'
Type
String
Read options from the named login path in the '.mylogin.cnf' login path file. A 'login path' is an option group containing options that specify which MySQL server to connect to and which account to authenticate as. To create or modify a login path file, use the note 'mysql_config_editor': mysql-config-editor. utility. See note mysql-config-editor::.
For additional information about this and other option-file options, see *note option-file-options::.
'--max-allowed-packet=VALUE'
Command-Line Format
'--max-allowed-packet=value'
Type
Integer
Default Value
'25165824'
Minimum Value
'4096'
Maximum Value
'2147483648'
The maximum size of the buffer for client/server communication. The default value is 24MB. The minimum and maximum values are 4KB and 2GB.
'--net-buffer-length=VALUE'
Command-Line Format
'--net-buffer-length=value'
Type
Integer
Default Value
'1047552'
Minimum Value
'4096'
Maximum Value
'16777216'
The initial size of the buffer for client/server communication. The default value is 1MB − 1KB. The minimum and maximum values are 4KB and 16MB.
'--no-defaults'
Command-Line Format
'--no-defaults'
Do not read any option files. If program startup fails due to reading unknown options from an option file, '--no-defaults' can be used to prevent them from being read.
The exception is that the '.mylogin.cnf' file is read in all cases, if it exists. This permits passwords to be specified in a safer way than on the command line even when '--no-defaults' is used. To create '.mylogin.cnf', use the note 'mysql_config_editor': mysql-config-editor. utility. See note mysql-config-editor::.
For additional information about this and other option-file options, see *note option-file-options::.
'--password[=PASSWORD]', '-p[PASSWORD]'
Command-Line Format
'--password[=name]'
Type
String
The password of the MySQL account used for connecting to the server. The password value is optional. If not given, *note 'mysql_upgrade': mysql-upgrade. prompts for one. If given, there must be no space between '--password=' or '-p' and the password following it. If no password option is specified, the default is to send no password.
Specifying a password on the command line should be considered insecure. To avoid giving the password on the command line, use an option file. See *note password-security-user::.
To explicitly specify that there is no password and that *note 'mysql_upgrade': mysql-upgrade. should not prompt for one, use the '--skip-password' option.
'--pipe', '-W'
Command-Line Format
'--pipe'
Type
String
On Windows, connect to the server using a named pipe. This option applies only if the server was started with the 'named_pipe' system variable enabled to support named-pipe connections. In addition, the user making the connection must be a member of the Windows group specified by the 'named_pipe_full_access_group' system variable.
'--plugin-dir=DIR_NAME'
Command-Line Format
'--plugin-dir=dir_name'
Type
Directory name
The directory in which to look for plugins. Specify this option if the '--default-auth' option is used to specify an authentication plugin but note 'mysql_upgrade': mysql-upgrade. does not find it. See note pluggable-authentication::.
'--port=PORT_NUM', '-P PORT_NUM'
Command-Line Format
'--port=#'
Type
Numeric
For TCP/IP connections, the port number to use.
'--print-defaults'
Command-Line Format
'--print-defaults'
Print the program name and all options that it gets from option files.
'--protocol={TCP|SOCKET|PIPE|MEMORY}'
Command-Line Format
'--protocol=name'
Type
String
The transport protocol to use for connecting to the server. It is useful when the other connection parameters normally result in use of a protocol other than the one you want. For details on the permissible values, see *note transport-protocols::.
'--shared-memory-base-name=NAME'
Command-Line Format
'--shared-memory-base-name=name'
Platform Specific
Windows
On Windows, the shared-memory name to use for connections made using shared memory to a local server. The default value is 'MYSQL'. The shared-memory name is case-sensitive.
This option applies only if the server was started with the 'shared_memory' system variable enabled to support shared-memory connections.
'--skip-sys-schema'
Command-Line Format
'--skip-sys-schema'
Type
Boolean
Default Value
'FALSE'
By default, *note 'mysql_upgrade': mysql-upgrade. installs the 'sys' schema if it is not installed, and upgrades it to the current version otherwise. The '--skip-sys-schema' option suppresses this behavior.
'--socket=PATH', '-S PATH'
Command-Line Format
'--socket={file_name|pipe_name}'
Type
String
For connections to 'localhost', the Unix socket file to use, or, on Windows, the name of the named pipe to use.
On Windows, this option applies only if the server was started with the 'named_pipe' system variable enabled to support named-pipe connections. In addition, the user making the connection must be a member of the Windows group specified by the 'named_pipe_full_access_group' system variable.
'--ssl*'
Options that begin with '--ssl' specify whether to connect to the server using encryption and indicate where to find SSL keys and certificates. See *note encrypted-connection-options::.
'--tls-version=PROTOCOL_LIST'
Command-Line Format
'--tls-version=protocol_list'
Introduced
5.7.10
Type
String
Default Value (≥ 5.7.28)
'TLSv1,TLSv1.1,TLSv1.2'
Default Value (<= 5.7.27)
'TLSv1,TLSv1.1,TLSv1.2' (OpenSSL) 'TLSv1,TLSv1.1' (yaSSL)
The permissible TLS protocols for encrypted connections. The value is a list of one or more comma-separated protocol names. The protocols that can be named for this option depend on the SSL library used to compile MySQL. For details, see *note encrypted-connection-protocols-ciphers::.
This option was added in MySQL 5.7.10.
'--upgrade-system-tables', '-s'
Command-Line Format
'--upgrade-system-tables'
Type
Boolean
Upgrade only the system tables in the 'mysql' schema, do not upgrade user schemas.
'--user=USER_NAME', '-u USER_NAME'
Command-Line Format
'--user=name'
Type
String
The user name of the MySQL account to use for connecting to the server. The default user name is 'root'.
'--verbose'
Command-Line Format
'--verbose'
Type
Boolean
Verbose mode. Print more information about what the program does.
'--version-check', '-k'
Command-Line Format
'--version-check'
Type
Boolean
Check the version of the server to which note 'mysql_upgrade': mysql-upgrade. is connecting to verify that it is the same as the version for which note 'mysql_upgrade': mysql-upgrade. was built. If not, *note 'mysql_upgrade': mysql-upgrade. exits. This option is enabled by default; to disable the check, use '--skip-version-check'.
'--write-binlog'
Command-Line Format
'--write-binlog'
Type
Boolean
Default Value
'OFF'
By default, binary logging by *note 'mysql_upgrade': mysql-upgrade. is disabled. Invoke the program with '--write-binlog' if you want its actions to be written to the binary log.
When the server is running with global transaction identifiers (GTIDs) enabled ('gtid_mode=ON'), do not enable binary logging by *note 'mysql_upgrade': mysql-upgrade.
File: manual.info.tmp, Node: programs-client, Next: programs-admin-utils, Prev: programs-installation, Up: programs