SQL Client Application

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.

Capabilities

Main Application Entry Point

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

/**
 * Main method to start the SQL Client application
 * @param args Command line arguments including mode and options
 */
public static void main(String[] args);

Usage Example:

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

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

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

Programmatic Client Startup

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

/**
 * Start SQL client with custom terminal factory for testing
 * @param args Command line arguments
 * @param terminalFactory Factory for creating terminal instances
 */
public static void startClient(String[] args, Supplier<Terminal> terminalFactory);

Usage Example:

import org.apache.flink.table.client.cli.TerminalUtils;

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

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

SqlClient Constructor

Creates a SQL client instance with specified mode and configuration.

/**
 * Create SQL client instance
 * @param isEmbedded Whether to use embedded mode (true) or gateway mode (false)
 * @param options Parsed command line options
 * @param terminalFactory Factory for creating terminal instances
 */
public SqlClient(boolean isEmbedded, CliOptions options, Supplier<Terminal> terminalFactory);

Usage Example:

// Parse options and create client
CliOptions options = CliOptionsParser.parseEmbeddedModeClient(args);
SqlClient client = new SqlClient(true, options, TerminalUtils::createDefaultTerminal);

Start Client Operation

Initializes and starts the SQL client with the configured options.

/**
 * Start the SQL client and begin processing
 * Handles context creation, executor setup, and CLI initialization
 */
private void start();

This method internally:

1. Creates a DefaultContext from CLI options
2. Initializes a LocalExecutor with the context
3. Opens a new session
4. Launches the CliClient for interactive or non-interactive mode
5. Ensures proper cleanup on shutdown

Execution Modes

Embedded Mode

public static final String MODE_EMBEDDED = "embedded";

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:

• Creates a local Flink execution environment
• Manages the complete Flink Table API context
• Provides direct access to Flink cluster resources
• Supports both interactive and batch execution

Gateway Mode

public static final String MODE_GATEWAY = "gateway";

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

Error Handling

The SqlClient handles various error conditions:

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

Example Error Handling:

try {
    SqlClient client = new SqlClient(true, options, terminalFactory);
    client.start();
} catch (SqlClientException e) {
    System.err.println("SQL Client error: " + e.getMessage());
    // Handle client-specific errors
} catch (Exception e) {
    System.err.println("Unexpected error: " + e.getMessage());
    // Handle unexpected errors
}

Shutdown Handling

The SqlClient automatically registers shutdown hooks to ensure proper cleanup:

Runtime.getRuntime().addShutdownHook(new EmbeddedShutdownThread(sessionId, executor));

The shutdown process:

1. Closes the active session
2. Releases executor resources
3. Prints shutdown confirmation message

Integration with CLI Components

The SqlClient integrates with several key components:

• CliOptionsParser: For parsing command line arguments
• LocalContextUtils: For building default execution context
• LocalExecutor: For embedded SQL execution
• CliClient: For interactive terminal interface

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