4.2.4 Connecting to the MySQL Server Using Command Options

This section describes use of command-line options to specify how to establish connections to the MySQL server, for clients such as mysql or mysqldump. For information on establishing connections using URI-like connection strings or key-value pairs, for clients such as MySQL Shell, see Section 4.2.5, “Connecting to the Server Using URI-Like Strings or Key-Value Pairs”. For additional information if you are unable to connect, see Section 6.2.21, “Troubleshooting Problems Connecting to MySQL”.

For a client program to connect to the MySQL server, it must use the proper connection parameters, such as the name of the host where the server is running and the user name and password of your MySQL account. Each connection parameter has a default value, but you can override default values as necessary using program options specified either on the command line or in an option file.

The examples here use the mysql client program, but the principles apply to other clients such as mysqldump, mysqladmin, or mysqlshow.

This command invokes mysql without specifying any explicit connection parameters:

mysql

Because there are no parameter options, the default values apply:

To specify the host name and user name explicitly, as well as a password, supply appropriate options on the command line. To select a default database, add a database-name argument. Examples:

mysql --host=localhost --user=myname --password=password mydb
mysql -h localhost -u myname -ppassword mydb

For password options, the password value is optional:

As just mentioned, including the password value on the command line can be a security risk. To avoid this risk, specify the --password or -p option without any following password value:

mysql --host=localhost --user=myname --password mydb
mysql -h localhost -u myname -p mydb

When the --password or -p option is given with no password value, the client program prints a prompt and waits for you to enter the password. (In these examples, mydb is not interpreted as a password because it is separated from the preceding password option by a space.)

On some systems, the library routine that MySQL uses to prompt for a password automatically limits the password to eight characters. That limitation is a property of the system library, not MySQL. Internally, MySQL does not have any limit for the length of the password. To work around the limitation on systems affected by it, specify your password in an option file (see Section 4.2.2.2, “Using Option Files”). Another workaround is to change your MySQL password to a value that has eight or fewer characters, but that may be unacceptable because shorter passwords tend to be less secure.

Client programs determine what type of connection to make as follows:

The --protocol option enables you to establish a particular type of connection even when other options normally result in use of a different protocol. That is, --protocol specifies the connection protocol explicitly and overrides the preceding rules, even for localhost.

Only connection options that are relevant to the selected protocol are used or checked. Other connection options are ignored. For example, with --host=localhost on Unix, the client attempts to connect to the local server using a Unix socket file. This occurs even if a --port or -P option is given to specify a port number.

To ensure that the client makes a TCP/IP connection to the local server, use --host or -h to specify a host name value of 127.0.0.1, or the IP address or name of the local server. You can also specify the connection protocol explicitly, even for localhost, by using the --protocol=TCP option. Examples:

mysql --host=127.0.0.1
mysql --protocol=TCP

If the server is configured to accept IPv6 connections, clients can connect to the local server over IPv6 using --host=::1. See Section 5.1.12, “IPv6 Support”.

On Windows, you can force a MySQL client to use a named-pipe connection by specifying the --pipe or --protocol=PIPE option, or by specifying . (period) as the host name. If the server was not started with the named_pipe system variable enabled to support named-pipe connections or if the user making the connection is not a member of the Windows group specified by the named_pipe_full_access_group system variable, an error occurs. Use the --socket option to specify the name of the pipe if you do not want to use the default pipe name.

Connections to remote servers use TCP/IP. This command connects to the server running on remote.example.com using the default port number (3306):

mysql --host=remote.example.com

To specify a port number explicitly, use the --port or -P option:

mysql --host=remote.example.com --port=13306

You can specify a port number for connections to a local server, too. However, as indicated previously, connections to localhost on Unix use a socket file by default, so unless you force a TCP/IP connection as previously described, any option that specifies a port number is ignored.

For this command, the program uses a socket file on Unix and the --port option is ignored:

mysql --port=13306 --host=localhost

To cause the port number to be used, force a TCP/IP connection. For example, invoke the program in either of these ways:

mysql --port=13306 --host=127.0.0.1
mysql --port=13306 --protocol=TCP

For additional information about options that control how client programs establish connections to the server, see Section 4.2.3, “Command Options for Connecting to the Server”.

It is possible to specify connection parameters without entering them on the command line each time you invoke a client program: