How to connect to Valkey or Redis on Java via Unix domain socket (UDS)

Published on
May 1, 2025

Valkey and Redis clients running on the same host as the server have the option of connecting via Unix domain socket (UDS) instead of TCP. While TCP and UDP are standard networking protocols, sockets are a fast, efficient way to connect to local services. 

Since Java doesn't support Valkey or Redis out of the box, there is no way for Java apps to natively connect to these data stores via UDS. However, Redisson, a Valkey and Redis client for Java, provides an easy method for socket connections. Here's how to connect to Valkey or Redis on Java via UDS.

What is a Unix domain socket (UDS)?

Unix domain sockets (UDS) are files that facilitate connections between programs running on the same computer or host. They are similar to the TCP sockets used in the standard TCP/IP networking protocol but for local connections only. 

UDS works by creating special socket files, usually with a .sock extension. Processes can send and receive data through the socket, which is similar to a network socket but without the overhead associated with network protocols.

Why would I choose UDS over TCP?

While clients and other processes can connect to Redis or Valkey via TCP when running on the same machine (via TCP loopback or localhost connections), UDS has a few advantages.

Speed is the main reason for choosing UDS over TCP. UDS is typically faster than TCP for local connections because it avoids network protocol overhead. In addition, UDS is highly efficient. Since UDS has less overhead, local socket connections have little impact on system resources. 

Finally, some users make the argument that UDS connections are more secure than local TCP connections (via TCP loopback or localhost connections), as they are only accessible to processes running on the same host as the Valkey or Redis service.

How do I connect to Valkey or Redis on Java via Unix domain socket (UDS)?

You can use Redisson, a Java client for Valkey and Redis, to connect via UDS directly in your Java applications. After installing and configuring Redisson, there are just a few steps to follow.

First, make sure your Redis or Valkey server is configured to use a Unix socket. Add the following lines to your Valkey or Redis configuration file:

unixsocket /var/run/redis/redis.sock
unixsocketperm 775

The first line sets the location for the .sock file, while the second sets the permissions for the file.

For the next step, create a Redisson configuration object in your Java code and set the address using the UDS protocol. The Java code will be slightly different for Redis and Valkey.

Java code example for Redis:

Config config = new Config();
config.useSingleServer()
 .setAddress("redis+uds:///var/run/redis/redis.sock");

For Valkey, use the "valkey+uds://" protocol instead:

Config config = new Config();
config.useSingleServer()
 .setAddress("valkey+uds:///var/run/redis/redis.sock");

Now, create a RedissonClient instance:

RedissonClient redisson = Redisson.create(config);

Connecting to Valkey and Redis in Java with Redisson

This is just one of the many ways Redisson makes it easy for Java developers to work with Valkey or Redis. To learn more, check out the feature comparison between Redisson and the Redisson PRO edition.