The REPL

Why this stage exists

Every other stage in this tutorial is reached through this loop. The lexer, the pager, the B+Tree, transactions — none of them has a user interface of its own. They are all things that happen between a line arriving and an answer being printed.

That makes the loop worth getting right once, because two of its properties are load-bearing for everything after it. The first: an error is an answer, not a stop. A database that exits when you type a bad query is a database you cannot use, and every later stage produces errors — a malformed statement, a full page, a duplicate key, a transaction that cannot commit. If the loop dies on the first one, none of those stages can be tested. The second: the exit status is a promise to whoever is running you. The tests for every later stage run your program as a subprocess and check that status.

There is a third reason, smaller but immediate: this stage is where you print your first error, so it is where the error format is settled. One line, a code that says what went wrong, and a message you are free to word however you like.

What the loop does

Notice what is not in the diagram: there is no path from an error to the end. Every answer, including an error, leads back to the prompt. The only two ways out are .exit and end of input, and both of them take the same exit.

The two kinds of input

A line beginning with . is a meta command: an instruction to the program itself rather than to the data. .exit and .help are the two you implement here; later stages add .mode. They are answered by the loop and never reach the query machinery.

Everything else is a statement, and eventually goes to the lexer and the parser. Not yet, though — there is nowhere to send it. So at this stage the loop recognises meta commands and rejects everything else, which is a real answer and not a placeholder: an unknown command is exactly what a line of SQL is to a program that has no SQL in it.

Output contract for this stage

These are the exact lines the tests check. The full definition is on the output contract page, sections 2 and 3.

An error is one line: [ERROR:SSCCC] message. The five digits are fixed by the contract and the tests assert them; the message after them is yours to word, and a second line starting HINT: may follow if you want to be helpful. Errors go to standard output, like everything else, so that a test reading one stream sees the session in the order it happened.

Why numbers rather than sentences? Because a message is for a person and a code is for everything else — a test, a log, a support question, a future you grepping the source. Sentences get reworded; 00103 does not. The first two digits say which part of the program noticed (01 is the command line and the loop), the last three say what it noticed.

What you should see when done

Welcome to droid!
>.help
Available commands:
.exit - Exit the program
.help - Show this help message
>
>   .help
Available commands:
.exit - Exit the program
.help - Show this help message
>.foo
[ERROR:00103] Unknown meta command: .foo
>select * from users;
[ERROR:00105] Unknown command: select
>.exit
exiting.. good bye!

Three things to notice. The empty line printed nothing — the prompt after it is the only trace. The indented .help worked, because the line was trimmed before it was compared. And the session ended normally after two errors: they were answers, not accidents.

From a script, without a session around it:

$droid -c ".help"
Available commands:
.exit - Exit the program
.help - Show this help message
$echo $?
0
$droid -c "select * from users;"
[ERROR:00105] Unknown command: select
$echo $?
1

Common bugs in this stage

• The prompt appears in the wrong place. Printing it after the answer instead of before the read produces output that looks right on a terminal and wrong everywhere else. Print, then read.
• The prompt never appears. With no newline to flush it, output can sit in a buffer while the program blocks on the read. Flush after printing the prompt.
• .exit never matches. The line still carries its newline, or its leading spaces. Trim before comparing, and the trimmed-help-with-spaces test is the one that catches it.
• An empty line prints an error, or a blank line. It should print nothing at all and go straight back to the prompt.
• End of input is treated as a failure. A closed input is not an error: say goodbye and exit 0, exactly as .exit does. Piped input hits this every time.
• An error exits the program. Print it and read the next line. If your error path calls the exit routine, every later stage becomes untestable.
• The status is always 0, or always 1. A session with errors in it still exits 0; a -c whose command failed exits 1. The status describes the request, not the crash.
• A fixed-size input buffer. A statement may be 4096 bytes long. Read the whole line however long it is, or at minimum refuse it without overrunning anything.
• Errors printed to standard error. Everything goes to standard output, so the order of a session is preserved for whoever is reading it.

Language notes

The page above is the same for every language. These are the only language-specific hints.

• C: getline allocates and grows the buffer for you; fgets with a fixed array is where the 4096-byte case goes wrong. fflush(stdout) after the prompt.
• C++: std::getline(std::cin, line) returns a falsy stream at end of input, which is the loop's exit condition. std::cout << std::flush after the prompt.
• Rust: BufRead::read_line returns Ok(0) at end of input — a zero-length read, not an error. io::stdout().flush() after the prompt.
• Zig: readUntilDelimiterOrEof returns null at end of input. Remember the allocator for the line, and flush the writer after the prompt.