tessl/maven-org-apache-flink--flink-sql-client-2-12

SQL Client for exploring and submitting SQL programs to Flink

—

Pending

Overview

Eval results

Files

Command Line Interface

Name: tessl/maven-org-apache-flink--flink-sql-client-2-12
Author: tessl

Interactive and non-interactive CLI for executing SQL statements with terminal support, result display, and command history. The CLI provides a rich interactive experience with auto-completion, syntax highlighting, and multiple result display formats.

Capabilities

CliClient Class

Core CLI client implementation handling both interactive and non-interactive SQL execution.

public class CliClient implements AutoCloseable {
    /**
     * Create CLI client with terminal factory and session context
     * @param terminalFactory Factory for creating terminal instances
     * @param sessionId Session identifier for executor operations
     * @param executor Executor instance for SQL operations
     * @param historyFilePath Path to command history file
     */
    public CliClient(Supplier<Terminal> terminalFactory, String sessionId, Executor executor, Path historyFilePath);
    
    /**
     * Create CLI client with input transformer for password masking
     * @param terminalFactory Factory for creating terminal instances
     * @param sessionId Session identifier for executor operations
     * @param executor Executor instance for SQL operations
     * @param historyFilePath Path to command history file
     * @param inputTransformer Callback for transforming input (e.g., password masking)
     */
    public CliClient(Supplier<Terminal> terminalFactory, String sessionId, Executor executor, Path historyFilePath, MaskingCallback inputTransformer);
}

Interactive Mode Execution

Opens interactive SQL shell with readline support, auto-completion, and command history.

/**
 * Execute CLI in interactive mode with full terminal features
 * Provides SQL auto-completion, command history, and result display
 */
public void executeInInteractiveMode();

Usage Example:

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

// Create CLI client and start interactive mode
try (CliClient cli = new CliClient(
        TerminalUtils::createDefaultTerminal,
        sessionId,
        executor,
        Paths.get(System.getProperty("user.home"), ".flink-sql-history")
)) {
    cli.executeInInteractiveMode();
}

Interactive mode features:

SQL auto-completion with table and function names
Command history with up/down arrow navigation
Multi-line SQL statement support
Ctrl+C cancellation support
Graceful shutdown with Ctrl+D

Non-Interactive Mode Execution

Executes SQL content from files or strings without interactive features.

/**
 * Execute SQL content in non-interactive mode
 * @param content SQL content to execute (file content or statement string)
 */
public void executeInNonInteractiveMode(String content);

Usage Example:

// Execute SQL from file content
String sqlContent = Files.readString(Paths.get("queries.sql"));
cli.executeInNonInteractiveMode(sqlContent);

// Execute single statement
cli.executeInNonInteractiveMode("SELECT COUNT(*) FROM users");

Non-interactive mode characteristics:

Executes all statements sequentially
Stops execution on first error
Uses tableau result display mode
No user interaction required

Initialization Script Execution

Executes initialization scripts with restricted operation support and silent output.

/**
 * Execute initialization script content
 * @param content SQL initialization script content
 * @return true if initialization succeeded, false if any errors occurred
 */
public boolean executeInitialization(String content);

Usage Example:

// Execute initialization script
String initScript = """
    SET 'sql-client.execution.result-mode' = 'tableau';
    CREATE CATALOG my_catalog WITH (...);
    USE CATALOG my_catalog;
    """;

boolean success = cli.executeInitialization(initScript);
if (!success) {
    System.err.println("Initialization failed - check logs for details");
}

Initialization mode restrictions:

Only allows: SET, RESET, CREATE, DROP, USE, ALTER, LOAD MODULE, UNLOAD MODULE, ADD JAR, REMOVE JAR
Other operations throw SqlExecutionException
Output is captured and logged rather than displayed

Terminal Management

Access and control terminal properties and display.

/**
 * Get the current terminal instance
 * @return Terminal instance for advanced terminal operations
 */
public Terminal getTerminal();

/**
 * Clear terminal screen (platform-aware)
 */
public void clearTerminal();

/**
 * Check if terminal supports advanced features
 * @return true if terminal is plain/simple, false if it supports advanced features
 */
public boolean isPlainTerminal();

/**
 * Get terminal width
 * @return Terminal width in characters
 */
public int getWidth();

/**
 * Get terminal height  
 * @return Terminal height in lines
 */
public int getHeight();

Usage Example:

// Check terminal capabilities
if (cli.isPlainTerminal()) {
    System.out.println("Using simple terminal mode");
} else {
    System.out.printf("Terminal size: %dx%d%n", cli.getWidth(), cli.getHeight());
}

// Clear screen
cli.clearTerminal();

Session and Executor Access

Access underlying session and executor for advanced operations.

/**
 * Get session identifier
 * @return Current session ID
 */
public String getSessionId();

/**
 * Get executor instance
 * @return Executor instance for direct SQL operations
 */
public Executor getExecutor();

CliOptions Class

Container for parsed command line arguments and configuration.

public class CliOptions {
    /**
     * Whether help should be displayed instead of starting client
     * @return true if help flag was provided
     */
    public boolean isPrintHelp();
    
    /**
     * Session identifier for this client instance
     * @return session ID or null if not specified
     */
    public String getSessionId();
    
    /**
     * Initialization script file URL
     * @return URL to initialization script or null
     */
    public URL getInitFile();
    
    /**
     * SQL script file URL for non-interactive execution
     * @return URL to SQL script file or null
     */
    public URL getSqlFile();
    
    /**
     * JAR dependency URLs to add to classpath
     * @return List of JAR URLs
     */
    public List<URL> getJars();
    
    /**
     * Library directory URLs for dependency resolution
     * @return List of library directory URLs
     */
    public List<URL> getLibraryDirs();
    
    /**
     * Single SQL statement for execution (deprecated, use getSqlFile)
     * @return SQL statement string or null
     */
    public String getUpdateStatement();
    
    /**
     * Command history file path
     * @return Path to history file or null for default
     */
    public String getHistoryFilePath();
    
    /**
     * Python-specific configuration
     * @return Configuration for Python integration
     */
    public Configuration getPythonConfiguration();
}

CliOptionsParser Class

Command line argument parser with static utilities for different modes.

public class CliOptionsParser {
    /**
     * Parse command line arguments for embedded mode
     * @param args Command line arguments
     * @return Parsed CliOptions instance
     */
    public static CliOptions parseEmbeddedModeClient(String[] args);
    
    /**
     * Parse command line arguments for gateway mode client
     * @param args Command line arguments  
     * @return Parsed CliOptions instance
     */
    public static CliOptions parseGatewayModeClient(String[] args);
    
    /**
     * Print general client help information
     */
    public static void printHelpClient();
    
    /**
     * Print embedded mode specific help
     */
    public static void printHelpEmbeddedModeClient();
    
    /**
     * Validate file path accessibility
     * @param filePath Path to validate
     * @throws IllegalArgumentException if path is invalid
     */
    public static void checkFilePath(String filePath);
}

Usage Example:

// Parse embedded mode options
try {
    CliOptions options = CliOptionsParser.parseEmbeddedModeClient(args);
    if (options.isPrintHelp()) {
        CliOptionsParser.printHelpEmbeddedModeClient();
        return;
    }
    // Use options to configure client
} catch (Exception e) {
    System.err.println("Invalid command line options: " + e.getMessage());
    CliOptionsParser.printHelpEmbeddedModeClient();
}

Command Line Options

Common Options

--help, -h: Display help information
--session <sessionId>: Specify session identifier
--init <file>: Initialization script file
--file, -f <file>: SQL script file for non-interactive execution
--jar <jar>: JAR files to add to classpath (can be repeated)
--library <dir>: Library directories for dependencies (can be repeated)
--history <file>: Command history file path

Deprecated Options

--update, -u <statement>: Single SQL statement (use --file instead)

Error Handling

The CLI handles various error conditions gracefully:

SQL parsing errors: Display error with line/column information
Execution errors: Show detailed error messages with optional stack traces
Terminal errors: Fallback to simple terminal mode
File access errors: Validate file permissions and existence
Cancellation: Handle Ctrl+C and Ctrl+D gracefully

Example Error Display:

Flink SQL> SELECT * FROM non_existent_table;
[ERROR] Could not execute SQL statement. Reason:
org.apache.flink.table.api.TableException: Table 'non_existent_table' not found

Flink SQL>

Result Display Integration

The CLI integrates with result display components:

CliTableauResultView: For tableau-format results
CliTableResultView: For paginated table results
CliChangelogResultView: For streaming changelog results

Result display is automatically selected based on query type and configuration settings.

Install with Tessl CLI

npx tessl i tessl/maven-org-apache-flink--flink-sql-client-2-12

docs

command-line-interface.md

configuration-options.md

index.md

result-handling-display.md

session-context-management.md

sql-client-application.md

sql-execution-gateway.md

tile.json

tessl/maven-org-apache-flink--flink-sql-client-2-12