0
# Configuration Options
1

2
Comprehensive configuration system for SQL Gateway service behavior, session management, worker threads, REST endpoints, and workflow scheduling with extensive customization options.
3

4
## Capabilities
5

6
### SqlGatewayServiceConfigOptions
7

8
Core service configuration options for session management, threading, and performance tuning.
9

10
```java { .api }
11
/**
12
 * Configuration options for SQL Gateway service
13
 */
14
public class SqlGatewayServiceConfigOptions {
15
    
16
    /** Session idle timeout before automatic cleanup (default: 10 minutes) */
17
    public static final ConfigOption<Duration> SQL_GATEWAY_SESSION_IDLE_TIMEOUT;
18
    
19
    /** Interval for checking idle sessions (default: 1 minute) */
20
    public static final ConfigOption<Duration> SQL_GATEWAY_SESSION_CHECK_INTERVAL;
21
    
22
    /** Maximum number of concurrent sessions (default: 1,000,000) */
23
    public static final ConfigOption<Integer> SQL_GATEWAY_SESSION_MAX_NUM;
24
    
25
    /** Enable plan caching for improved performance (default: false) */
26
    public static final ConfigOption<Boolean> SQL_GATEWAY_SESSION_PLAN_CACHE_ENABLED;
27
    
28
    /** Maximum entries in plan cache (default: 100) */
29
    public static final ConfigOption<Integer> SQL_GATEWAY_SESSION_PLAN_CACHE_SIZE;
30
    
31
    /** Time-to-live for cached plans (default: 1 hour) */
32
    public static final ConfigOption<Duration> SQL_GATEWAY_SESSION_PLAN_CACHE_TTL;
33
    
34
    /** Maximum worker threads for operation execution (default: 500) */
35
    public static final ConfigOption<Integer> SQL_GATEWAY_WORKER_THREADS_MAX;
36
    
37
    /** Minimum worker threads maintained (default: 5) */
38
    public static final ConfigOption<Integer> SQL_GATEWAY_WORKER_THREADS_MIN;
39
    
40
    /** Thread keepalive time when idle (default: 5 minutes) */
41
    public static final ConfigOption<Duration> SQL_GATEWAY_WORKER_KEEPALIVE_TIME;
42
}
43
```
44

45
### SqlGatewayRestOptions
46

47
REST endpoint configuration for network settings and server behavior.
48

49
```java { .api }
50
/**
51
 * Options to configure SqlGatewayRestEndpoint
52
 * By default, the user must select a local address to set ADDRESS, then the server will bind the
53
 * address to all the local IPV4 address (0.0.0.0) and bind the port to BIND_PORT(fallback to the
54
 * default value of PORT).
55
 */
56
public class SqlGatewayRestOptions {
57
    
58
    /** The address that should be used by clients to connect to the sql gateway server */
59
    public static final ConfigOption<String> ADDRESS;
60
    
61
    /** The address that the sql gateway server binds itself to */
62
    public static final ConfigOption<String> BIND_ADDRESS;
63
    
64
    /** The port range that the sql gateway server could bind itself to (default: "8083") */
65
    public static final ConfigOption<String> BIND_PORT;
66
    
67
    /** The port that the client connects to (default: 8083) */
68
    public static final ConfigOption<Integer> PORT;
69
}
70
```
71

72
## Usage Examples
73

74
### Basic Service Configuration
75

76
```java
77
import org.apache.flink.configuration.Configuration;
78
import org.apache.flink.table.gateway.api.config.SqlGatewayServiceConfigOptions;
79

80
// Configure SQL Gateway service
81
Configuration config = new Configuration();
82

83
// Session management
84
config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_IDLE_TIMEOUT, 
85
    Duration.ofMinutes(30)); // 30 minute timeout
86
config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_MAX_NUM, 10000);
87
config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_CHECK_INTERVAL, 
88
    Duration.ofSeconds(30));
89

90
// Performance tuning
91
config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_PLAN_CACHE_ENABLED, true);
92
config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_PLAN_CACHE_SIZE, 500);
93
config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_PLAN_CACHE_TTL, 
94
    Duration.ofHours(2));
95

96
// Worker thread configuration
97
config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_WORKER_THREADS_MAX, 200);
98
config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_WORKER_THREADS_MIN, 10);
99
config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_WORKER_KEEPALIVE_TIME, 
100
    Duration.ofMinutes(10));
101

102
// Use configuration with SQL Gateway
103
DefaultContext context = DefaultContext.load(config, Collections.emptyList(), true);
104
SessionManager sessionManager = SessionManager.create(context);
105
SqlGateway gateway = new SqlGateway(config, sessionManager);
106
```
107

108
### REST Endpoint Configuration
109

110
```java
111
import org.apache.flink.table.gateway.rest.util.SqlGatewayRestOptions;
112

113
// Configure REST endpoint
114
Configuration restConfig = new Configuration();
115

116
// Basic network settings
117
restConfig.set(SqlGatewayRestOptions.BIND_ADDRESS, "0.0.0.0"); // Bind to all interfaces
118
restConfig.set(SqlGatewayRestOptions.PORT, 9083); // Custom port
119
restConfig.set(SqlGatewayRestOptions.REQUEST_TIMEOUT, Duration.ofMinutes(5));
120

121
// Performance settings
122
restConfig.set(SqlGatewayRestOptions.MAX_REQUEST_SIZE, MemorySize.ofMebiBytes(64)); // 64MB max
123

124
// SSL configuration for production
125
restConfig.set(SqlGatewayRestOptions.SSL_ENABLED, true);
126
restConfig.set(SqlGatewayRestOptions.SSL_KEYSTORE_PATH, "/path/to/keystore.jks");
127
restConfig.set(SqlGatewayRestOptions.SSL_KEYSTORE_PASSWORD, "keystorePassword");
128
restConfig.set(SqlGatewayRestOptions.SSL_TRUSTSTORE_PATH, "/path/to/truststore.jks");
129
restConfig.set(SqlGatewayRestOptions.SSL_TRUSTSTORE_PASSWORD, "truststorePassword");
130

131
// Create SQL Gateway with REST configuration
132
SqlGateway gateway = new SqlGateway(restConfig, sessionManager);
133
gateway.start(); // Will start REST endpoint with custom configuration
134
```
135

136
### Production Configuration Example
137

138
```java
139
// Production-ready configuration
140
public class ProductionGatewayConfig {
141
    
142
    public static Configuration createProductionConfig() {
143
        Configuration config = new Configuration();
144
        
145
        // Session management for high-load scenarios
146
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_IDLE_TIMEOUT, 
147
            Duration.ofHours(4)); // Longer timeout for batch jobs
148
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_MAX_NUM, 50000);
149
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_CHECK_INTERVAL, 
150
            Duration.ofMinutes(2));
151
        
152
        // Enable plan caching for performance
153
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_PLAN_CACHE_ENABLED, true);
154
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_PLAN_CACHE_SIZE, 2000);
155
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_PLAN_CACHE_TTL, 
156
            Duration.ofHours(8));
157
        
158
        // High-performance thread pool
159
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_WORKER_THREADS_MAX, 1000);
160
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_WORKER_THREADS_MIN, 50);
161
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_WORKER_KEEPALIVE_TIME, 
162
            Duration.ofMinutes(15));
163
        
164
        // REST endpoint with SSL
165
        config.set(SqlGatewayRestOptions.BIND_ADDRESS, "0.0.0.0");
166
        config.set(SqlGatewayRestOptions.PORT, 8083);
167
        config.set(SqlGatewayRestOptions.REQUEST_TIMEOUT, Duration.ofMinutes(10));
168
        config.set(SqlGatewayRestOptions.MAX_REQUEST_SIZE, MemorySize.ofMebiBytes(128));
169
        config.set(SqlGatewayRestOptions.SSL_ENABLED, true);
170
        
171
        // Additional Flink configuration
172
        config.setString("execution.target", "yarn-per-job");
173
        config.setString("execution.savepoint.path", "hdfs://cluster/savepoints");
174
        config.setInteger("parallelism.default", 8);
175
        config.setString("execution.checkpointing.interval", "60s");
176
        
177
        return config;
178
    }
179
}
180
```
181

182
### Configuration via Properties File
183

184
```java
185
// Load configuration from properties file
186
public class ConfigurationLoader {
187
    
188
    public static Configuration loadFromProperties(String propertiesFile) throws IOException {
189
        Properties props = new Properties();
190
        try (InputStream input = new FileInputStream(propertiesFile)) {
191
            props.load(input);
192
        }
193
        
194
        Configuration config = Configuration.fromMap(
195
            props.entrySet().stream()
196
                .collect(Collectors.toMap(
197
                    e -> e.getKey().toString(),
198
                    e -> e.getValue().toString()
199
                ))
200
        );
201
        
202
        return config;
203
    }
204
}
205

206
// Example properties file (gateway.properties):
207
/*
208
sql-gateway.session.idle-timeout=30min
209
sql-gateway.session.check-interval=1min  
210
sql-gateway.session.max-num=10000
211
sql-gateway.session.plan-cache.enabled=true
212
sql-gateway.session.plan-cache.size=500
213
sql-gateway.worker.threads.max=200
214
sql-gateway.worker.threads.min=10
215
rest.port=8083
216
rest.bind-address=0.0.0.0
217
rest.ssl.enabled=false
218
*/
219
```
220

221
### Environment-Specific Configuration
222

223
```java
224
// Environment-specific configuration patterns
225
public class EnvironmentConfigurations {
226
    
227
    public static Configuration forDevelopment() {
228
        Configuration config = new Configuration();
229
        
230
        // Development - minimal resources, fast feedback
231
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_IDLE_TIMEOUT, Duration.ofMinutes(5));
232
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_MAX_NUM, 100);
233
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_WORKER_THREADS_MAX, 20);
234
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_PLAN_CACHE_ENABLED, false);
235
        
236
        config.set(SqlGatewayRestOptions.PORT, 8083);
237
        config.set(SqlGatewayRestOptions.SSL_ENABLED, false);
238
        
239
        return config;
240
    }
241
    
242
    public static Configuration forTesting() {
243
        Configuration config = new Configuration();
244
        
245
        // Testing - isolated, predictable
246
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_IDLE_TIMEOUT, Duration.ofMinutes(1));
247
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_MAX_NUM, 10);
248
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_WORKER_THREADS_MAX, 5);
249
        config.set(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_PLAN_CACHE_ENABLED, false);
250
        
251
        config.set(SqlGatewayRestOptions.PORT, 0); // Random port
252
        config.set(SqlGatewayRestOptions.SSL_ENABLED, false);
253
        
254
        return config;
255
    }
256
    
257
    public static Configuration forProduction() {
258
        // Use production config from previous example
259
        return ProductionGatewayConfig.createProductionConfig();
260
    }
261
}
262
```
263

264
### Dynamic Configuration Updates
265

266
```java
267
// Configuration monitoring and updates (conceptual)
268
public class DynamicConfigurationManager {
269
    private final SqlGateway gateway;
270
    private volatile Configuration currentConfig;
271
    
272
    public DynamicConfigurationManager(SqlGateway gateway, Configuration initialConfig) {
273
        this.gateway = gateway;
274
        this.currentConfig = initialConfig;
275
    }
276
    
277
    public synchronized void updateConfiguration(Map<String, String> updates) {
278
        Configuration newConfig = currentConfig.clone();
279
        
280
        for (Map.Entry<String, String> entry : updates.entrySet()) {
281
            newConfig.setString(entry.getKey(), entry.getValue());
282
        }
283
        
284
        // Apply configuration changes that don't require restart
285
        applyRuntimeConfigChanges(newConfig);
286
        
287
        this.currentConfig = newConfig;
288
    }
289
    
290
    private void applyRuntimeConfigChanges(Configuration newConfig) {
291
        // Update session timeout
292
        Duration newTimeout = newConfig.get(SqlGatewayServiceConfigOptions.SQL_GATEWAY_SESSION_IDLE_TIMEOUT);
293
        // Apply to session manager...
294
        
295
        // Update thread pool sizes
296
        int maxThreads = newConfig.get(SqlGatewayServiceConfigOptions.SQL_GATEWAY_WORKER_THREADS_MAX);
297
        // Apply to thread pool...
298
        
299
        // Some changes may require restart - log warnings
300
        if (configRequiresRestart(currentConfig, newConfig)) {
301
            System.out.println("Warning: Some configuration changes require gateway restart");
302
        }
303
    }
304
    
305
    private boolean configRequiresRestart(Configuration old, Configuration updated) {
306
        // Check if port, SSL settings, or other restart-required settings changed
307
        return !Objects.equals(old.get(SqlGatewayRestOptions.PORT), updated.get(SqlGatewayRestOptions.PORT)) ||
308
               !Objects.equals(old.get(SqlGatewayRestOptions.SSL_ENABLED), updated.get(SqlGatewayRestOptions.SSL_ENABLED));
309
    }
310
}
311
```