0
# SQL Client Application
1

2
Main application entry point providing embedded execution mode for SQL operations against Flink clusters. The SqlClient class manages the complete lifecycle of the SQL client including mode selection, context creation, and CLI initialization.
3

4
## Capabilities
5

6
### Main Application Entry Point
7

8
Primary entry point for starting the Flink SQL Client application from command line.
9

10
```java { .api }
11
/**
12
 * Main method to start the SQL Client application
13
 * @param args Command line arguments including mode and options
14
 */
15
public static void main(String[] args);
16
```
17

18
**Usage Example:**
19

20
```java
21
// Start in embedded mode (default)
22
SqlClient.main(new String[]{"--jar", "path/to/flink-sql-client.jar"});
23

24
// Start with explicit embedded mode
25
SqlClient.main(new String[]{"embedded", "--jar", "path/to/flink-sql-client.jar"});
26

27
// Start with initialization script
28
SqlClient.main(new String[]{"embedded", "--init", "init.sql", "--jar", "flink-sql-client.jar"});
29
```
30

31
### Programmatic Client Startup
32

33
Test-friendly method for starting the SQL client with custom terminal factory.
34

35
```java { .api }
36
/**
37
 * Start SQL client with custom terminal factory for testing
38
 * @param args Command line arguments
39
 * @param terminalFactory Factory for creating terminal instances
40
 */
41
public static void startClient(String[] args, Supplier<Terminal> terminalFactory);
42
```
43

44
**Usage Example:**
45

46
```java
47
import org.apache.flink.table.client.cli.TerminalUtils;
48

49
// Start with default terminal
50
SqlClient.startClient(args, TerminalUtils::createDefaultTerminal);
51

52
// Start with custom terminal for testing
53
Supplier<Terminal> testTerminalFactory = () -> TerminalUtils.createDumbTerminal(outputStream);
54
SqlClient.startClient(args, testTerminalFactory);
55
```
56

57
### SqlClient Constructor
58

59
Creates a SQL client instance with specified mode and configuration.
60

61
```java { .api }
62
/**
63
 * Create SQL client instance
64
 * @param isEmbedded Whether to use embedded mode (true) or gateway mode (false)
65
 * @param options Parsed command line options
66
 * @param terminalFactory Factory for creating terminal instances
67
 */
68
public SqlClient(boolean isEmbedded, CliOptions options, Supplier<Terminal> terminalFactory);
69
```
70

71
**Usage Example:**
72

73
```java
74
// Parse options and create client
75
CliOptions options = CliOptionsParser.parseEmbeddedModeClient(args);
76
SqlClient client = new SqlClient(true, options, TerminalUtils::createDefaultTerminal);
77
```
78

79
### Start Client Operation
80

81
Initializes and starts the SQL client with the configured options.
82

83
```java { .api }
84
/**
85
 * Start the SQL client and begin processing
86
 * Handles context creation, executor setup, and CLI initialization
87
 */
88
private void start();
89
```
90

91
This method internally:
92
1. Creates a DefaultContext from CLI options
93
2. Initializes a LocalExecutor with the context
94
3. Opens a new session
95
4. Launches the CliClient for interactive or non-interactive mode
96
5. Ensures proper cleanup on shutdown
97

98
## Execution Modes
99

100
### Embedded Mode
101

102
```java { .api }
103
public static final String MODE_EMBEDDED = "embedded";
104
```
105

106
In embedded mode, the SQL CLI is tightly coupled with the executor in a common process. This allows for submitting jobs without having to start an additional component. The embedded mode:
107

108
- Creates a local Flink execution environment
109
- Manages the complete Flink Table API context
110
- Provides direct access to Flink cluster resources
111
- Supports both interactive and batch execution
112

113
### Gateway Mode
114

115
```java { .api }
116
public static final String MODE_GATEWAY = "gateway";
117
```
118

119
Gateway mode is planned for future versions where the SQL CLI client would connect to a REST API gateway. Currently throws `SqlClientException` when used.
120

121
## Error Handling
122

123
The SqlClient handles various error conditions:
124

125
- **SqlClientException**: Thrown for client-level errors including unsupported gateway mode
126
- **SqlExecutionException**: Propagated from underlying SQL execution failures
127
- **Unexpected exceptions**: Wrapped in SqlClientException with appropriate logging
128

129
**Example Error Handling:**
130

131
```java
132
try {
133
    SqlClient client = new SqlClient(true, options, terminalFactory);
134
    client.start();
135
} catch (SqlClientException e) {
136
    System.err.println("SQL Client error: " + e.getMessage());
137
    // Handle client-specific errors
138
} catch (Exception e) {
139
    System.err.println("Unexpected error: " + e.getMessage());
140
    // Handle unexpected errors
141
}
142
```
143

144
## Shutdown Handling
145

146
The SqlClient automatically registers shutdown hooks to ensure proper cleanup:
147

148
```java
149
Runtime.getRuntime().addShutdownHook(new EmbeddedShutdownThread(sessionId, executor));
150
```
151

152
The shutdown process:
153
1. Closes the active session
154
2. Releases executor resources  
155
3. Prints shutdown confirmation message
156

157
## Integration with CLI Components
158

159
The SqlClient integrates with several key components:
160

161
- **CliOptionsParser**: For parsing command line arguments
162
- **LocalContextUtils**: For building default execution context
163
- **LocalExecutor**: For embedded SQL execution
164
- **CliClient**: For interactive terminal interface
165

166
This integration provides a complete SQL client experience from command line parsing through SQL execution and result display.