THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Status
Current state: DISCUSS
Discussion thread:
JIRA:
Released:
Problem
Samza SQL users have long been asking for a one stop shell, in which SQL statements and SQL files can be executed interactively. The requirement can be summarized as following:
An interactive command shell
Execute SQL queries and non-queries, show tables, functions, schema, etc.
Execute SQL files
Set environment variables interactively and/or via configuration file to configure behavior of shell
Command editing, history, highlight and auto-completion
Display SQL query in a streaming friendly way
List status of submitted non-query SQL statements and be able to stop them
Apart from Samza SQL, support other streaming SQLs and data sources by letting user implement their own plugins
Proposed Changes
We need to implement a Samza SQL shell.
Terminal: Choice of Programming Language and Libraries
Any shell is essentially a REPL (Repeat-Evaluate-Print Loop), yet any non-trivial one is much more than that. Features like highlighting, history, command line editing, auto completion and rich data presentation require the capability of full control of the terminal. Terminal programming is a messy area, however, with the complexity coming from the long history and the vast variety of terminal types and operating systems. C/C++ is ideal for terminal IO programming, but for easier interoperation with data sources and other systems, Java is chosen.
Using Java to directly control the terminal is a lot of work. For example, to use the alternate screen and restore the previous screen we need to write code like this:
System.out.print(“\e[?1049h"); // tput smcup
System.out.print("\e[?1049l"); // tput rmcup
Which is neither pretty nor platform independent. Library Lanterna offers a Java style abstraction and solves the platform dependency problem. However, Lanterna is a very low level API; there’s still too much work. For example, for features like highlighting and auto completion, we need to use the non-canonical mode of the terminal, in which in order to process the simple user input of backspace we need to move the cursor, print a space, and move the cursor again.
The final library chosen is higher level one, Jline 3.8.2. Though knowledge of terminal programming is still necessary, Jline saves a lot of work. The mysterious code above now becomes:
terminal.puts(InfoCmp.Capability.enter_ca_mode); // tput smcup
terminal.puts(InfoCmp.Capability.exit_ca_mode); // tput rmcup
Commands
Use “HELP” to show all commands and their brief descriptions, or “help <command>” to get more detail about a specific command.
Use "SHOW TABLES" to Displays all tables. Use "SHOW FUNCTIONS" to display all functions. Use "DESCRIBE <table name>" to display the schema of a table. The result is displayed as a formatted table and the column width is automatically adjusted, where lines are automatically wrapped within the columns to make most efficient usage of the screen room. Lines are colored with alternative colors for better reading.
Use "SELECT" command to executes a select SQL statement. The shell uses a logging view to display the result for now (table view will be supported in the future and users will be allowed to choose among various views by the SET command).
// TODO: INSERT A SELECT VIEW HERE
Use "EXECUTE" command to executes a SQL file. All the SELECT statements in the file will be omitted as executing streaming SELECT statements in a batch doesn’t make sense.
Use "INSERT INTO" to execute an INSERT INTO statement. User gets an execution ID if this non-query statement is submitted successfully, and they can use the ID to control the execution later.
Use "LIST" command to list all the non-query executions that have been executed. It displays the ID, status and original statement of the execution. You can also use “LS [id1, id2...]” to list specific executions.
Use "STOP" command to stop the specified execution(s).
Use "RM" command to remove stopped executions(s) that from showing in the future.
