Skip navigation links

Additional languages
4.2.3 Specifying Program Options »
Section Navigation      [Toggle]

4.2.2. Connecting to the MySQL Server

For a client program to be able 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 username and password of your MySQL account. Each connection parameter has a default value, but you can override them 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 connection parameters explicitly: 

shell> mysql

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

  • The default hostname is localhost. On Unix, this has a special meaning, as described later.

  • The default username is ODBC on Windows or your Unix login name on Unix.

  • No password is sent if neither -p nor --password is given.

To specify the hostname and username explicitly, as well as a password, supply appropriate options on the command line: 

shell> mysql --host=localhost --user=myname --password=mypass
shell> mysql -h localhost -u myname -pmypass

For password options, the password value is optional:

  • If you use a -p or --password option but do not specify the password value, the client program prompts you to enter the password. The password is not displayed as you enter it. This is more secure than giving the password on the command line. Any user on your system may be able to see a password specified on the command line by executing a command such as ps auxw. See Section 5.6.6, “Keeping Your Password Secure”.

  • If you use a -p or --password option and do specify the password value, there must be no space between -p or --password= and the password following it.

On Unix, MySQL programs treat the hostname localhost specially, in a way that is likely different from what you expect compared to other network-based programs. For connections to localhost, MySQL programs attempt to connect to the local server by 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 hostname 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. For example: 

shell> mysql --host=127.0.0.1
shell> mysql --protocol=TCP

The --protocol option enables you to establish a particular type of connection even when the other options would normally default to some other protocol.

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 named-pipe connections are not enabled, 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 always use TCP/IP. This command connects to the server running on remote.example.com using the default port number (3306): 

shell> mysql --host=remote.example.com

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

shell> 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 will use a socket file by default. You will need to force a TCP/IP connection as already described or any option that specifies a port number will be ignored.

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

shell> mysql --port=13306 --host=localhost

To cause the port number to be used, invoke the program in either of these ways: 

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

The following options may be used to control how client programs connect to the server:

  • --host=host_name, -h host_name

    The host where the server is running. The default value is localhost.

  • --password[=pass_val], -p[pass_val]

    The password of the MySQL account. As described earlier, the password value is optional, but if given, there must be no space between -p or --password= and the password following it. The default is to send no password.

  • --pipe, -W

    On Windows, connect to the server via a named pipe. This option applies for connections to a local server only. The server must have been started with the --enable-named-pipe option to enable named-pipe connections.

  • --port=port_num, -P port_num

    The port number to use for the connection, for connections made via TCP/IP. The default port number is 3306.

  • --protocol=type

    This option explicitly specifies a protocol to use for connecting to the server. It is useful when the other connection parameters normally would cause a protocol to be used other than the one you want. For example, connections on Unix to localhost are made via a Unix socket file by default: 

    shell> mysql --host=localhost

    To force a TCP/IP connection to be used instead, specify a --protocol option: 

    shell> mysql --host=localhost --protocol=TCP

    The following table shows the allowable --protocol option values and indicates the platforms on which each value may be used. The values are not case sensitive.

    --protocol Value Connection Protocol Allowable Operating Systems
    TCP TCP/IP connection to local or remote server All
    SOCKET Unix socket file connection to local server Unix only
    PIPE Named-pipe connection to local server Windows only
    MEMORY Shared-memory connection to local server Windows only

    The --protocol option was added in MySQL 4.1.

  • --shared-memory-base-name=name

    On Windows, the shared-memory name to use, for connections made via shared memory to a local server. The default value is MYSQL. The shared-memory name is case sensitive.

    The server must be started with the --shared-memory option to enable shared-memory connections.

  • --socket=file_name, -S file_name

    On Unix, the name of the Unix socket file to use, for connections made via a named pipe to a local server. The default Unix socket filename is /tmp/mysql.sock.

    On Windows, the name of the named pipe to use, for connections to a local server. The default Windows pipe name is MySQL. The pipe name is not case sensitive.

    The server must be started with the --enable-named-pipe option to enable named-pipe connections.

  • --ssl*

    Options that begin with --ssl are used for establishing a secure connection to the server via SSL, if the server is configured with SSL support. For details, see Section 5.6.7.3, “SSL Command Options”.

  • --user=user_name, -u user_name

    The username of the MySQL account you want to use. The default username is ODBC on Windows or your Unix login name on Unix.

It is possible to specify different default values to be used when you make a connection so that you need not enter them on the command line each time you invoke a client program. This can be done in a couple of ways:

  • You can specify connection parameters in the [client] section of an option file. The relevant section of the file might look like this: 

    [client]
host=host_name
user=user_name
password=your_pass

    Section 4.2.3.2, “Using Option Files”, discusses option files further.

  • You can specify some connection parameters using environment variables. The host can be specified for mysql using MYSQL_HOST. The MySQL username can be specified using USER (this is for Windows and NetWare only). The password can be specified using MYSQL_PWD, although this is insecure; see Section 5.6.6, “Keeping Your Password Secure”. For a list of variables, see Section 2.14, “Environment Variables”.