Valkey

docs/config.yaml

@@ -11,3 +11,11 @@ dataStore:
 
 clusterStatsConfiguration:
   monitorType: INFO_API
+
+# Valkey distributed cache (optional - for multi-instance deployments)
+valkeyConfiguration:
+  enabled: false
+  host: localhost
+  port: 6379
+  # password: ${VALKEY_PASSWORD}  # Uncomment if Valkey requires AUTH
+  # cacheTtlSeconds: 1800  # Cache TTL in seconds (default: 1800 = 30 minutes)

docs/installation.md

@@ -157,10 +157,37 @@ Find more information in the [routing rules documentation](routing-rules.md).
 To configure the logging level for various classes, specify the path to the 
 `log.properties` file by setting `log.levels-file` in `serverConfig`.
 
-For additional configurations, use the `log.*` properties from the 
+For additional configurations, use the `log.*` properties from the
 [Trino logging properties documentation](https://trino.io/docs/current/admin/properties-logging.html) and specify
 the properties in `serverConfig`.
 
+### Configure distributed cache (optional)
+
+For multi-instance deployments, Trino Gateway supports distributed caching
+using Valkey (or Redis) to share query metadata across gateway instances.
+This improves query routing and enables horizontal scaling.
+
+For single gateway deployments, distributed caching is not needed - the
+local cache is sufficient.
+
+```yaml
+valkeyConfiguration:
+  enabled: true
+  host: valkey.internal.prod
+  port: 6379
+  password: ${ENV:VALKEY_PASSWORD}
+  cacheTtlSeconds: 1800  # Cache TTL (default: 1800 = 30 minutes)
+```
+
+Optional parameters: You can customize `cacheTtlSeconds` based on your query duration:
+
+- Short queries (< 5 min): 600 seconds (10 minutes)
+- Default queries: 1800 seconds (30 minutes)
+- Long-running queries: 3600 seconds (1 hour)
+
+See Valkey distributed cache configuration for detailed configuration options,
+deployment scenarios, and performance tuning.
+
 ### Proxying additional paths
 
 By default, Trino Gateway only proxies requests to paths starting with

gateway-ha/.gitignore

@@ -0,0 +1 @@
+gateway-ha/gateway.log

gateway-ha/config.yaml

@@ -23,3 +23,11 @@ clusterStatsConfiguration:
 monitor:
   taskDelay: 1m
   clusterMetricsRegistryRefreshPeriod: 30s
+
+# Valkey distributed cache (optional - for multi-instance deployments)
+valkeyConfiguration:
+  enabled: false  # Set to true to enable distributed caching
+  host: localhost
+  port: 6379
+  # password: ${VALKEY_PASSWORD}  # Uncomment if Valkey requires AUTH
+  # cacheTtlSeconds: 1800  # Cache TTL in seconds (default: 1800 = 30 minutes)

gateway-ha/pom.xml

@@ -189,6 +189,12 @@
             <version>${dep.trino.version}</version>
         </dependency>
 
+        <dependency>
+            <groupId>io.valkey</groupId>
+            <artifactId>valkey-java</artifactId>
+            <version>5.5.0</version>
+        </dependency>
+
         <dependency>
             <groupId>jakarta.annotation</groupId>
             <artifactId>jakarta.annotation-api</artifactId>

gateway-ha/src/main/java/io/trino/gateway/ha/config/HaGatewayConfiguration.java

@@ -47,6 +47,8 @@ public class HaGatewayConfiguration
 
     private UIConfiguration uiConfiguration = new UIConfiguration();
 
+    private ValkeyConfiguration valkeyConfiguration = new ValkeyConfiguration();
+
     // List of Modules with FQCN (Fully Qualified Class Name)
     private List<String> modules;
 
@@ -215,6 +217,16 @@ public void setUiConfiguration(UIConfiguration uiConfiguration)
         this.uiConfiguration = uiConfiguration;
     }
 
+    public ValkeyConfiguration getValkeyConfiguration()
+    {
+        return valkeyConfiguration;
+    }
+
+    public void setValkeyConfiguration(ValkeyConfiguration valkeyConfiguration)
+    {
+        this.valkeyConfiguration = valkeyConfiguration;
+    }
+
     public List<String> getModules()
     {
         return this.modules;

gateway-ha/src/main/java/io/trino/gateway/ha/config/ValkeyConfiguration.java

@@ -0,0 +1,128 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.trino.gateway.ha.config;
+
+public class ValkeyConfiguration
+{
+    private boolean enabled;
+    private String host = "localhost";
+    private int port = 6379;
+    private String password;
+    private int database;
+    private int maxTotal = 20;
+    private int maxIdle = 10;
+    private int minIdle = 5;
+    private int timeoutMs = 2000;
+    private long cacheTtlSeconds = 1800;
+
+    public boolean isEnabled()
+    {
+        return enabled;
+    }
+
+    public void setEnabled(boolean enabled)
+    {
+        this.enabled = enabled;
+    }
+
+    public String getHost()
+    {
+        return host;
+    }
+
+    public void setHost(String host)
+    {
+        this.host = host;
+    }
+
+    public int getPort()
+    {
+        return port;
+    }
+
+    public void setPort(int port)
+    {
+        this.port = port;
+    }
+
+    public String getPassword()
+    {
+        return password;
+    }
+
+    public void setPassword(String password)
+    {
+        this.password = password;
+    }
+
+    public int getDatabase()
+    {
+        return database;
+    }
+
+    public void setDatabase(int database)
+    {
+        this.database = database;
+    }
+
+    public int getMaxTotal()
+    {
+        return maxTotal;
+    }
+
+    public void setMaxTotal(int maxTotal)
+    {
+        this.maxTotal = maxTotal;
+    }
+
+    public int getMaxIdle()
+    {
+        return maxIdle;
+    }
+
+    public void setMaxIdle(int maxIdle)
+    {
+        this.maxIdle = maxIdle;
+    }
+
+    public int getMinIdle()
+    {
+        return minIdle;
+    }
+
+    public void setMinIdle(int minIdle)
+    {
+        this.minIdle = minIdle;
+    }
+
+    public int getTimeoutMs()
+    {
+        return timeoutMs;
+    }
+
+    public void setTimeoutMs(int timeoutMs)
+    {
+        this.timeoutMs = timeoutMs;
+    }
+
+    public long getCacheTtlSeconds()
+    {
+        return cacheTtlSeconds;
+    }
+
+    public void setCacheTtlSeconds(long cacheTtlSeconds)
+    {
+        this.cacheTtlSeconds = cacheTtlSeconds;
+    }
+}

gateway-ha/src/main/java/io/trino/gateway/ha/module/HaGatewayProviderModule.java

@@ -40,9 +40,11 @@
 import io.trino.gateway.ha.config.OAuth2GatewayCookieConfigurationPropertiesProvider;
 import io.trino.gateway.ha.config.RoutingRulesConfiguration;
 import io.trino.gateway.ha.config.RulesExternalConfiguration;
+import io.trino.gateway.ha.config.ValkeyConfiguration;
 import io.trino.gateway.ha.persistence.JdbcConnectionManager;
 import io.trino.gateway.ha.persistence.RecordAndAnnotatedConstructorMapper;
 import io.trino.gateway.ha.router.BackendStateManager;
+import io.trino.gateway.ha.router.DistributedCache;
 import io.trino.gateway.ha.router.ForRouter;
 import io.trino.gateway.ha.router.GatewayBackendManager;
 import io.trino.gateway.ha.router.HaGatewayManager;
@@ -52,6 +54,7 @@
 import io.trino.gateway.ha.router.QueryHistoryManager;
 import io.trino.gateway.ha.router.ResourceGroupsManager;
 import io.trino.gateway.ha.router.RoutingGroupSelector;
+import io.trino.gateway.ha.router.ValkeyDistributedCache;
 import io.trino.gateway.ha.security.AuthorizationManager;
 import io.trino.gateway.ha.security.LbAuthorizer;
 import io.trino.gateway.ha.security.LbFormAuthManager;
@@ -198,4 +201,28 @@ public static ClusterStatsMonitor getClusterStatsMonitor(@ForMonitor HttpClient
             case NOOP -> new NoopClusterStatsMonitor();
         };
     }
+
+    @Provides
+    @Singleton
+    public ValkeyConfiguration getValkeyConfiguration()
+    {
+        return configuration.getValkeyConfiguration();
+    }
+
+    @Provides
+    @Singleton
+    public DistributedCache getDistributedCache()
+    {
+        ValkeyConfiguration valkeyConfig = configuration.getValkeyConfiguration();
+        return new ValkeyDistributedCache(
+                valkeyConfig.getHost(),
+                valkeyConfig.getPort(),
+                valkeyConfig.getPassword(),
+                valkeyConfig.getDatabase(),
+                valkeyConfig.isEnabled(),
+                valkeyConfig.getMaxTotal(),
+                valkeyConfig.getMaxIdle(),
+                valkeyConfig.getMinIdle(),
+                valkeyConfig.getTimeoutMs());
+    }
 }