Documentation Home
Connectors and APIs Manual
Download this Manual

Connectors and APIs Manual  /  ...  /  Connecting Using Named Pipes

3.5.9 Connecting Using Named Pipes

Important

For MySQL 8.0.14 and later, 5.7.25 and later, and 5.6.43 and later, minimal permissions on named pipes are granted to clients that use them to connect to the server. Connector/J, however, can only use named pipes when granted full access on them. As a workaround, the MySQL Server that Connector/J wants to connect to must be started with the system variable named_pipe_full_access_group, which specifies a Windows local group containing the user by which the client application JVM (and thus Connector/J) is being executed; see the description for named_pipe_full_access_group for more details.

Note

Support for named pipes is not available for X Protocol connections.

Connector/J also supports access to MySQL using named pipes on Windows platforms with the NamedPipeSocketFactory as a plugin-sockets factory. If you do not use a namedPipePath property, the default of '\\.\pipe\MySQL' is used. If you use the NamedPipeSocketFactory, the host name and port number values in the JDBC URL are ignored. To enable this feature, set the socketFactory property:

socketFactory=com.mysql.cj.protocol.NamedPipeSocketFactory

Set this property, as well as the path of the named pipe, with the following connection URL:

jdbc:mysql:///test?socketFactory=com.mysql.cj.protocol.NamedPipeSocketFactory&namedPipePath=\\.\pipe\MySQL80

To create your own socket factories, follow the sample code in com.mysql.cj.protocol.NamedPipeSocketFactory or com.mysql.cj.protocol.StandardSocketFactory.

An alternate approach is to use the following two properties in connection URLs for establishing named pipe connections on Windows platforms:

  • (protocol=pipe) for named pipes (default value for the property is tcp).

  • (path=path_to_pipe) for path of named pipes. Default value for the path is \\.\pipe\MySQL.

The address-equals or key-value form of host specification (see Single host for details) greatly simplifies the URL for a named pipe connection on Windows. For example, to use the default named pipe of \\.\pipe\MySQL, just specify:

jdbc:mysql://address=(protocol=pipe)/test

To use the custom named pipe of \\.\pipe\MySQL80 :

jdbc:mysql://address=(protocol=pipe)(path=\\.\pipe\MySQL80)/test

With (protocol=pipe), the NamedPipeSocketFactory is automatically selected.

Named pipes only work when connecting to a MySQL server on the same physical machine where the JDBC driver is running. In simple performance tests, named pipe access is between 30%-50% faster than the standard TCP/IP access. However, this varies per system, and named pipes are slower than TCP/IP in many Windows configurations.