Cli on Opensource internals

How the ClickHouse Client Splits a Script into Queries

Jay Hubbert — Sat, 24 Oct 2026 09:00:00 +0000

TL;DR: clickhouse-client --queries-file script.sql does not split the file on ;. It parses one statement at a time, lets the parser tell it where the statement ended, ends inline INSERT data at a blank line, and then walks forward over the semicolons and the trailing comment so the -- { serverError 42 } hint stays attached to the statement it describes.

Splitting a SQL script into statements sounds trivial. It is not, and the reasons are all in the corners of the language:

A semicolon can be data: INSERT INTO t VALUES ('a;b').
A semicolon can be part of a format’s data: INSERT INTO t FORMAT CSV 1,2;3 — is that the number 3 or the end of the statement?
A semicolon can be inside a comment: -- nothing; to see here.
A semicolon can be inside a string: SELECT ';'.
A statement can have no semicolon at all: the last line of the file.
A statement can be followed by a comment that belongs to it: SELECT 1; -- { serverError 42 } — and the client’s test framework depends on that comment being attached to the right statement.

Here is a script that exercises all of it:

 sql
 
 
-- script.sql
SELECT 1; -- statement 1, terminated by ';'
SELECT 'a;b'; -- the ';' is inside a string: still one statement
INSERT INTO t FORMAT CSV
1,2;3
 -- a blank line ends the payload, not the ';'
SELECT 3 -- statement 4, no trailing ';' at all

And the pipeline the client runs to get there:

 text
 
 
 script text
 |
 v
 parseQuery(one statement) -- the parser advances the pointer itself
 |
 v
 INSERT with inline data? --yes--> VALUES: the real VALUES format parser
 | other formats: find the next "\n\n"
 |no
 v
 adjustQueryEnd: skip the ';'s, pull in the trailing comment
 |
 v
 execute | check the "-- { serverError N }" hint

Every SQL client solves this differently, and every solution leaks somewhere. psql uses a lexer. mysql uses a lexer with a mode stack. ClickHouse’s client uses a parser — it asks the real SQL parser where the statement ends — and then applies a small number of special cases for the places where the parser cannot know.

The entry point

--queries-file is a plain option:

 cpp
 
 
// src/Client/ClientBase.cpp:4678
 ("query,q", po::value<std::vector<std::string>>()->multitoken(), R"(Query. Can be specified multiple times (--query "SELECT 1" --query "SELECT 2") or once with multiple semicolon-separated queries (--query "SELECT 1; SELECT 2;"). In the latter case, INSERT queries with non-VALUE format must be separated by empty lines.)")
 ("queries-file", po::value<std::vector<std::string>>()->multitoken(), "File path with queries to execute; multiple files can be specified (--queries-file file1 file2...)")
 ("multiquery,n", "Obsolete, does nothing")

Note the multiquery flag: it is documented as obsolete and does nothing, because the client has always been able to run a multi-statement script. The flag survives only so that old scripts do not break.

Several files can be given, and each can be preceded by “interleave” files that are run before it — a mechanism for setting up state:

 cpp
 
 
// programs/client/Client.cpp:1211
 ("interleave-queries-file",

The whole thing is driven from runNonInteractive:

 cpp
 
 
// src/Client/ClientBase.cpp:5385
 if (!buzz_house && !queries_files.empty())
 {
 for (const auto & queries_file : queries_files)
 {
 for (const auto & interleave_file : interleave_queries_files)
 if (!processMultiQueryFromFile(interleave_file))
 return;

 if (!processMultiQueryFromFile(queries_file))
 return;
 }

 return;
 }

and processMultiQueryFromFile reads the whole file into memory and hands it to the multi-statement executor:

 cpp
 
 
// src/Client/ClientBase.cpp:5356
bool ClientBase::processMultiQueryFromFile(const String & file_name)
{
 if (isEmbeeddedClient())
 throw Exception(ErrorCodes::SUPPORT_IS_DISABLED, "Reading queries from file is not supported for an embedded client");

 String queries_from_file;

 ReadBufferFromFile in(file_name);
 readStringUntilEOF(queries_from_file, in);

 /// For `clickhouse-local` only: same entry point as `-q` / stdin so meta-commands (`clear`, `ls`,
 /// `\i`, …) work for whole-file input. Remote `clickhouse-client` keeps `executeMultiQuery` so
 /// `--queries-file` does not apply `exit_strings` and other text-level metas (avoids silent
 /// behavior changes for batch automation).
 if (supportsLocalMetaCommands())
 return processQueryText(queries_from_file);
 return executeMultiQuery(queries_from_file);
}

The difference at the end is a deliberate compatibility decision: clickhouse-local treats a file as “text typed at the prompt”, so \i and clear work inside it; clickhouse-client treats it as a script, and running it through the meta-command processor could change the meaning of an existing pipeline.

The same function is the implementation of the interactive \i command, so “read this file and run it” is one code path everywhere.

The splitting rule, as the code states it

The rule the client actually implements is written down in a comment, right where the multi-statement executor is set up:

 cpp
 
 
// src/Client/ClientBase.cpp:3587
 /// Several queries separated by ';'.
 /// INSERT data is ended by the empty line (\n\n), not ';'.
 /// Unnecessary semicolons may cause data to be parsed containing ';'
 /// e.g. 'insert into xx format csv val;' will insert "val;" instead of "val"
 /// 'insert into xx format csv val\n;' will insert "val" and ";"
 /// An exception is VALUES format where we also support semicolon in
 /// addition to end of line.

That comment is the whole specification, and it is worth reading twice, because the third line is the surprising one: insert into xx format csv val; inserts the string val; — the semicolon is data. The only reliable separator for a data-carrying INSERT is a blank line.

The executor is a loop over a state machine with four states:

 cpp
 
 
// src/Client/ClientBase.cpp:3607
 while (true)
 {
 auto stage = analyzeMultiQueryText(this_query_begin, this_query_end, all_queries_end,
 parsed_query, current_exception);
 switch (stage)
 {
 case MultiQueryProcessingStage::QUERIES_END:
 {
 /// Compatible with old version when run interactive, e.g. "", "\ld"
 if (is_first && is_interactive)
 {
 auto u = processTextAsSingleQuery(all_queries_text);
 UNUSED(u);
 }
 return true;
 }

QUERIES_END, PARSING_FAILED, CONTINUE_PARSING and PARSING_EXCEPTION are the four outcomes; the interesting one is EXECUTE_QUERY, which falls through the switch into the code that runs the statement.

Stage one: let the parser find the boundary

analyzeMultiQueryText is where the work happens. Its first job is to throw away the leading whitespace, so that the queries in the server’s query log do not start with a newline:

 cpp
 
 
// src/Client/ClientBase.cpp:3340
 const char * raw_query_begin = this_query_begin;

 // Remove leading empty newlines and other whitespace, because they
 // are annoying to filter in the query log. This is mostly relevant for
 // the tests.
 while (this_query_begin < all_queries_end && isWhitespaceASCII(*this_query_begin))
 ++this_query_begin;

Its second job is to detect the “only comments left” case, which the parser cannot handle:

 cpp
 
 
// src/Client/ClientBase.cpp:3354
 // If there are only comments left until the end of file, we just
 // stop. The parser can't handle this situation because it always
 // expects that there is some query that it can parse.
 // We can get into this situation because the parser also doesn't
 // skip the trailing comments after parsing a query. This is because
 // they may as well be the leading comments for the next query,
 // and it makes more sense to treat them as such.
 {
 Tokens tokens(this_query_begin, all_queries_end);
 IParser::Pos token_iterator(tokens, max_parser_depth, max_parser_backtracks);
 bool only_comments_left = !token_iterator.isValid();

and its third job — the actual split — is to hand the rest of the script to the parser and let it consume exactly one statement:

 cpp
 
 
// src/Client/ClientBase.cpp:3384
 this_query_end = this_query_begin;
 try
 {
 parsed_query = parseQuery(this_query_end, all_queries_end,
 client_context->getSettingsRef(),
 /*allow_multi_statements=*/ true, raw_query_begin);
 }

parseQuery takes a const char *& and advances it past what it parsed. That is the trick: the parser is the splitter. The client does not look for semicolons; it asks ClickHouse’s own SQL parser to parse one statement and tells it where the end of the buffer is. A ; inside a string literal is inside the string literal, because the lexer said so.

The one thing the parser cannot do is know where a FORMAT CSV payload ends, because the payload is not SQL at all. That is handled separately, below.

Stage two: the INSERT data

After the parser returns, the client checks whether the statement is an INSERT with inline data, and if so, finds the end of the data:

 cpp
 
 
// src/Client/ClientBase.cpp:3444
 // INSERT queries may have the inserted data in the query text that follow the query itself, e.g. "insert into t format CSV 1,2". They
 // need special handling.
 // - If the INSERT statement FORMAT is VALUES, we use the VALUES format parser to skip the inserted data until we reach the trailing single semicolon.
 // - Other formats (e.g. FORMAT CSV) are arbitrarily more complex and tricky to parse. For example, we may be unable to distinguish if the semicolon
 // is part of the data or ends the statement. In this case, we simply assume that the end of the INSERT statement is determined by \n\n (two newlines).

VALUES gets the good treatment: the actual VALUES format parser is used to walk the rows, so a semicolon inside a string literal is handled correctly:

 cpp
 
 
// src/Client/ClientBase.cpp:3461
 if (insert_ast->format == "Values")
 {
 // Invoke the VALUES format parser to skip the inserted data.
 // Skip SQL comments too (as ValuesBlockInputFormat::read does), not just
 // whitespace: a trailing comment after the last row would otherwise be scanned
 // as row data past the terminating ';', swallowing the following queries.
 ReadBufferFromMemory data_in(insert_ast->data, all_queries_end - insert_ast->data);
 skipBOMIfExists(data_in);
 do
 {
 skipWhitespaceAndSQLComments(data_in);
 if (data_in.eof() || *data_in.position() == ';')
 break;
 }
 while (ValuesBlockInputFormat::skipToNextRow(&data_in, 1, 0));

Every other format gets the crude rule — a blank line ends the data:

 cpp
 
 
// src/Client/ClientBase.cpp:3488
 else
 {
 // Handling of generic formats
 auto pos_newline = String(insert_ast->data, all_queries_end).find("\n\n");
 if (pos_newline != std::string::npos)
 this_query_end = insert_ast->data + pos_newline;
 else
 this_query_end = all_queries_end;
 }
 insert_ast->end = this_query_end;

This is the rule the option’s help text warns about: “In the latter case, INSERT queries with non-VALUE format must be separated by empty lines.”

It is a real limitation, and the reason is not laziness: a FORMAT CSV payload has no length, no terminator and no quoting rules the client could rely on. A semicolon in a CSV field is legal. A blank line is the only separator the client and the server can agree on without reimplementing every format’s parser.

Stage three: eat the semicolons and the trailing comment

Now the client knows where the statement ends, but there may be a semicolon and a trailing comment after it. The semicolon has to go, and the comment has to be kept — because the test framework puts the expected error code in it:

 cpp
 
 
// src/Client/ClientBase.cpp:764
void ClientBase::adjustQueryEnd(
 const char *& this_query_end, const char * all_queries_end, uint32_t max_parser_depth, uint32_t max_parser_backtracks)
{
 // We have to skip the trailing semicolon that might be left
 // after VALUES parsing or just after a normal semicolon-terminated query.
 Tokens after_query_tokens(this_query_end, all_queries_end);
 IParser::Pos after_query_iterator(after_query_tokens, max_parser_depth, max_parser_backtracks);
 while (after_query_iterator.isValid() && after_query_iterator->type == TokenType::Semicolon)
 {
 this_query_end = after_query_iterator->end;
 ++after_query_iterator;
 }

Note that it skips all consecutive semicolons, so SELECT 1;; is one statement, not two.

Then the comment logic, which is the subtlest part of the whole file:

 cpp
 
 
// src/Client/ClientBase.cpp:777
 // Now we have to do some extra work to add the trailing
 // same-line comment to the query, but preserve the leading
 // comments of the next query. The trailing comment is important
 // because the test hints are usually written this way, e.g.:
 // select nonexistent_column; -- { serverError 12345 }.
 // The token iterator skips comments and whitespace, so we have
 // to find the newline in the string manually. If it's earlier
 // than the next significant token, it means that the text before
 // newline is some trailing whitespace or comment, and we should
 // add it to our query. There are also several special cases
 // that are described below.
 const auto * newline = find_first_symbols<'\n'>(this_query_end, all_queries_end);
 const char * next_query_begin = after_query_iterator->begin;

 // We include the entire line if the next query starts after
 // it. This is a generic case of trailing in-line comment.
 // The "equals" condition is for case of end of input (they both equal
 // all_queries_end);
 if (newline <= next_query_begin)
 {
 chassert(newline >= this_query_end);
 this_query_end = newline;
 }
 else
 {
 // Many queries on one line, can't do anything. By the way, this
 // syntax is probably going to work as expected:
 // select nonexistent /* { serverError 12345 } */; select 1
 }

The rule is: if the next statement starts on a later line, everything up to the end of the current line belongs to this statement. If two statements share a line, the comment is ambiguous and the client gives up — with the comment above pointing at the syntax that does work.

This matters because of TestHint, the mechanism ClickHouse’s own test suite uses to assert on errors:

 cpp
 
 
// src/Client/TestHint.h:17
/// Checks expected server and client error codes.
///
/// The following comment hints are supported:
///
/// - "-- { serverError 60 }" -- in case of you are expecting server error.
/// - "-- { serverError 16, 36 }" -- in case of you are expecting one of the 2 errors.
///
/// - "-- { clientError 20 }" -- in case of you are expecting client error.
/// - "-- { clientError 20, 60, 92 }" -- It's expected that the client will return one of the 3 errors.

and the hint is checked against the exception the server (or the client) produced:

 cpp
 
 
// src/Client/ClientBase.cpp:3804
 else if (test_hint.hasServerErrors())
 {
 if (!server_exception)
 {
 error_matches_hint = false;
 error_stream << fmt::format("Expected server error code '{}' but got no server error (query: {}).\n",
 test_hint.serverErrors(), full_query);
 }

So the whole comment-attaching dance exists so that a test file can say “this statement must fail with error 60” and the client can check it. The hint is not a nicety; it is the assertion mechanism of the entire ClickHouse integration test suite.

The statement that is executed

After all of that, the client has three views of the same statement, and uses each for a different purpose:

 cpp
 
 
// src/Client/ClientBase.cpp:3694
 // Save query without trailing comment
 auto query_to_execute = std::string_view(all_queries_text).substr(this_query_begin - all_queries_text.data(), this_query_end - this_query_begin);
 size_t insert_query_without_data_length = 0;
 if (const auto * insert = parsed_query->as<ASTInsertQuery>())
 insert_query_without_data_length = insert->data - query_to_execute.data();

 // Try to include the trailing comment with test hints. It is just
 // a guess for now, because we don't yet know where the query ends
 // if it is an INSERT query with inline data. We will do it again
 // after we have processed the query. But even this guess is
 // beneficial so that we see proper trailing comments in "echo" and
 // server log.
 {
 unsigned max_parser_depth = static_cast<unsigned>(client_context->getSettingsRef()[Setting::max_parser_depth]);
 unsigned max_parser_backtracks = static_cast<unsigned>(client_context->getSettingsRef()[Setting::max_parser_backtracks]);
 adjustQueryEnd(this_query_end, all_queries_end, max_parser_depth, max_parser_backtracks);
 }
 // query + inline INSERT data + trailing comments (the latter is our best guess for now).
 auto full_query = std::string_view(all_queries_text).substr(this_query_begin - all_queries_text.data(), this_query_end - this_query_begin);

query_to_execute — the statement without the trailing comment. This is what is sent to the server, so the comment never becomes part of the SQL.
full_query — the statement with the trailing comment. This is what is scanned for the test hint, and what is echoed.
parsed_query — the AST, which is what actually gets planned and sent.

And the script position is tracked for the server’s benefit:

 cpp
 
 
// src/Client/ClientBase.cpp:3714
 ++script_query_number;
 script_line_number += std::count(prev_query_begin, this_query_begin, '\n');
 prev_query_begin = this_query_begin;
 client_context->setScriptQueryAndLineNumber(script_query_number, 1 + script_line_number);

so that an error message from the server can say “statement 7, line 42 of your script” rather than just quoting the statement.

The format follows the file extension

One more piece of “the client guesses” behaviour, and it is the one users notice first. The client infers the format from the file name — for the input, from the file the client is reading; for the output, from the file the query writes to.

For the input, the client has to ask the kernel what file descriptor 0 actually is:

 cpp
 
 
// src/Common/tryGetFileNameByFileDescriptor.cpp:14
std::optional<String> tryGetFileNameFromFileDescriptor(int fd)
{
#ifdef OS_LINUX
 std::string proc_path = fmt::format("/proc/self/fd/{}", fd);
 char file_path[PATH_MAX] = {'\0'};
 if (readlink(proc_path.c_str(), file_path, sizeof(file_path) - 1) != -1)
 return file_path;
 return std::nullopt;
#elif defined(OS_DARWIN)
 char file_path[PATH_MAX] = {'\0'};
 if (fcntl(fd, F_GETPATH, file_path) != -1)
 return file_path;
 return std::nullopt;

readlink("/proc/self/fd/0") gives the original path of the redirected file, even through a pipe (/dev/stdin -> the real file), and F_GETPATH is the macOS equivalent. With that name in hand, the extension is mapped to a format:

 cpp
 
 
// src/Formats/FormatFactory.cpp:1113
std::optional<String> FormatFactory::tryGetFormatFromFileName(String file_name)
{
 if (file_name == "stdin")
 return tryGetFormatFromFileDescriptor(STDIN_FILENO);

 CompressionMethod compression_method = chooseCompressionMethod(file_name, "");
 if (CompressionMethod::None != compression_method)
 {
 auto pos = file_name.find_last_of('.');
 if (pos != String::npos)
 file_name = file_name.substr(0, pos);
 }

 auto pos = file_name.find_last_of('.');
 if (pos == String::npos)
 return std::nullopt;

 String file_extension = file_name.substr(pos + 1, String::npos);
 boost::algorithm::to_lower(file_extension);
 auto it = file_extension_formats.find(file_extension);
 if (it == file_extension_formats.end())
 return std::nullopt;

 return it->second;
}

Three details: the compression suffix is stripped first (so data.csv.gz is a CSV file, not a “gz” file), the extension is lowercased (so DATA.CSV works), and an unknown extension returns nothing rather than guessing.

The client then uses it as the default input format:

 cpp
 
 
// src/Client/ClientBase.cpp:1418
 else
 {
 std::optional<String> format_from_file_name = FormatFactory::instance().tryGetFormatFromFileDescriptor(stdin_fd);
 if (format_from_file_name)
 default_input_format = *format_from_file_name;
 else
 default_input_format = "auto";
 }

so clickhouse-client < data.csv reads CSV, clickhouse-client < data.jsonl reads JSONEachRow, and clickhouse-client < data.whatever falls back to auto (the format that sniffs the input).

The output side is the same trick, applied to INTO OUTFILE:

 cpp
 
 
// src/Client/ClientBase.cpp:1124
 else if (query_with_output->out_file)
 {
 auto format_name = FormatFactory::instance().tryGetFormatFromFileName(out_file);
 if (format_name)
 {
 current_format = *format_name;
 outfile_format_from_extension = true;
 }
 }

SELECT * FROM t INTO OUTFILE 'out.json' writes JSON, because the file is called out.json. And the extension-derived format has a higher priority than the default_format setting, which is why the code needs a flag to remember where the format came from:

 cpp
 
 
// src/Client/ClientBase.cpp:1146
 /// ... only when the client itself was not given an explicit output format. `--output-format`,
 /// `--format` and `--vertical` all set `is_default_format = false` (the last via
 /// `default_output_format = "Vertical"`), and such an explicit choice must win over the
 /// `default_format` *setting* — e.g. the display default the local client now seeds as a
 /// setting. Without this guard, `clickhouse-local --vertical` is silently overridden by that
 /// setting and prints TSV instead of Vertical.
 else if (is_default_format && !has_format_clause && !outfile_format_from_extension
 && !format_settings_ref[Setting::default_format].value.empty())
 current_format = format_settings_ref[Setting::default_format];

The full precedence chain is: an explicit FORMAT clause or --format wins; then the output_format/format settings; then the file extension; then the default_format setting; then the client’s built-in default.

Trade-offs

What the design buys.

Correct splitting for free. Because the real parser does the split, the client agrees with the server about where a statement ends in every case the SQL grammar can express — including semicolons inside strings, inside comments, and inside CASE ... WHEN ... THEN ... END.
No lexer to maintain. A hand-written lexer would have to reimplement the SQL string, identifier and comment rules, and would drift from the server’s.
Errors are attributable. The script query number and line number are tracked and sent to the server, so a failure in a 5 000-line script points at a line.
The test framework rides on it. The -- { serverError 42 } hint mechanism is a direct consequence of attaching the trailing comment to the right statement.
Formats are inferred. clickhouse-client < data.csv and INTO OUTFILE 'x.json' both work without a --format flag, because the client asks the kernel for the file name and looks at the extension.

What it costs.

The whole file is in memory. readStringUntilEOF reads the entire script before running anything. A 2 GB script is a 2 GB allocation.
The INSERT ... FORMAT rule is crude. Everything except VALUES ends at a blank line, so a CSV payload cannot contain a blank line, and a payload whose last row is followed by a single newline runs to the end of the file. The VALUES case is much better, because it uses the real format parser.
Two statements on one line lose their comment. select 1 /* { serverError 5 } */; select 2 cannot be disambiguated, and the client says so in a comment rather than guessing.
The extension inference can surprise you. INTO OUTFILE 'data.txt' writes whatever format txt maps to — or, if txt is not registered, it silently keeps the default format. The inference is a convenience with a sharp edge, and the sharp edge is that the mapping is global and configurable by whatever formats the build has.

A parse error aborts the rest of the script unless --ignore-error is given, in which case the client resynchronises by skipping to the next semicolon:

 cpp
 
 
// src/Client/ClientBase.cpp:3419
 else
 {
 Tokens tokens(this_query_begin, all_queries_end);
 IParser::Pos token_iterator(tokens, max_parser_depth, max_parser_backtracks);
 while (token_iterator->type != TokenType::Semicolon && token_iterator.isValid())
 ++token_iterator;
 this_query_begin = token_iterator->end;
 }

which is another place where a ; inside a string would confuse the resynchronisation.

The one thing to remember: the client does not split scripts on semicolons. It parses them, one statement at a time, and lets the parser tell it where the boundary is. The semicolon handling and the blank-line rule exist only for the two cases the parser cannot see: inline INSERT payloads and trailing comments.

The part people get wrong: INSERT ... FORMAT CSV data is not terminated by a semicolon, and the client will happily insert the ; as data. If your loader produces a file with a trailing semicolon after the last row, the semicolon is now a column value. Put a blank line after the payload, or use VALUES.

How Ctrl-C Reaches a Running Query: The Client's Cancel Packet

Jay Hubbert — Sat, 24 Oct 2026 09:00:00 +0000

TL;DR: The client’s signal handler does nothing but decrement an atomic counter — no I/O, no allocation, no locks. The receive loop is the thing that notices the counter, writes a one-byte Cancel packet on the same socket it is reading results from, and then keeps reading until the server’s EndOfStream so the connection stays in sync for the next query.

Pressing Ctrl-C in clickhouse-client has to satisfy four constraints that pull in opposite directions:

The server must stop working on the query now, not when the client finishes reading what it already has.
The connection must be left in a state where the next query works — no leftover result blocks, no half-read packet, no lost session state.
The rows the server already produced must not be silently dropped from the output, unless the user asked for that.
The whole thing must work when the client is blocked in a read() on a socket, in a signal handler, or in the middle of formatting output.

The shape of the answer:

 text
 
 
 user presses Ctrl-C
 |
 v
 SIGINT handler ---- or ---- 0x03 byte read by the keystroke thread
 | |
 +-------------+----------------+
 v
 exit_after_signals.fetch_sub(1) <-- the ONLY thing the interrupt does
 |
 +-----------------+-----------------+
 | |
 tryStop() == true cancelled() == true
 (the process exits) (the receive loop sends Cancel)
 |
 v
 read and discard the rest of the
 result until the server says EndOfStream

Most implementations solve this by making the client disconnect: send a RST, throw away the socket, reconnect for the next query. That satisfies (1) and (2) — a dead socket is trivially in sync — but it costs a round trip, it loses session state (temporary tables, the current database, SET values), and it produces an ugly error.

ClickHouse does not disconnect. It sends a packet, and then it does the hard part: it keeps the conversation going to the end.

The signal handler does nothing

Here is the whole of the client’s interrupt handling, in src/Client/ClientApplicationBase.cpp:

 cpp
 
 
// src/Client/ClientApplicationBase.cpp:49
/// This signal handler is set only for SIGINT and SIGQUIT.
void interruptSignalHandler(int signum)
{
 /// Signal handler might be called even before the setup is fully finished
 /// and client application started to process the query.
 /// Because of that we have to manually check it.
 if (auto * instance = ClientApplicationBase::instanceRawPtr(); instance)
 if (auto * base = dynamic_cast<ClientApplicationBase *>(instance); base)
 if (base->tryStopQuery())
 /// No leak check: in signal context it deadlocks if the interrupt landed under
 /// the allocator lock. Quiet, because here stderr is program output, not a log.
 safeExit(128 + signum, LeakCheck::SkipQuietly);
}

Read it again: there is no write(), no send(), no throw. The handler calls tryStopQuery(), which is an atomic decrement, and if that says “this was the last interrupt” it exits the process. The cancel packet is not sent from here — it cannot be, because sending on a socket from a signal handler is not async-signal-safe: send() may take a lock, and the interrupt may have landed while that lock was held.

So the handler’s only job is to move a number. The number is a counter of outstanding interrupts, and it lives in a small class that exists for exactly this purpose:

 cpp
 
 
// src/Client/ClientBase.h:339
 class QueryInterruptHandler : private boost::noncopyable
 {
 public:
 /// Store how much interrupt signals can be before stopping the query
 /// by default stop after the first interrupt signal.
 void start(Int32 signals_before_stop = 1) { exit_after_signals.store(signals_before_stop); }

 /// Set value not greater then 0 to mark the query as stopped.
 void stop() { exit_after_signals.store(0); }

 /// Return true if the query was stopped.
 /// Query was stopped if it received at least "signals_before_stop" interrupt signals.
 bool tryStop() { return exit_after_signals.fetch_sub(1) <= 0; }
 bool cancelled() { return exit_after_signals.load() <= 0; }

 /// Return how much interrupt signals remain before stop.
 Int32 cancelled_status() { return exit_after_signals.load(); }

 private:
 std::atomic<Int32> exit_after_signals = 0;
 };

Two methods, and the difference between them is the whole trick:

tryStop() decrements and reports whether the counter has reached zero. It is called from the signal handler. It is the “should the process die?” question, and it is answered exactly once per interrupt.
cancelled() reads the counter. It is called from the receive loop. It is the “should the server be told to stop?” question, and it is answered thousands of times per second.

Because tryStop() decrements and cancelled() reads, a single Ctrl-C does both jobs at once: the counter goes from 1 to 0, so cancelled() becomes true (the server should be told to stop) while tryStop() returns false (the process should not die yet — the query owns that first interrupt). We will come back to exactly why, because it is the key to the two-stage cancel.

The other path: Ctrl-C as a byte, not a signal

There is a second, more interesting way Ctrl-C can reach the client. When a client runs interactively with the progress table enabled, it puts the terminal into raw mode and reads keystrokes itself:

 cpp
 
 
// src/Client/TerminalKeystrokeInterceptor.cpp:67
 /// Set terminal to the raw terminal mode.
 struct termios raw = *orig_termios;
 raw.c_lflag &= ~(ECHO | ICANON);
 raw.c_cc[VMIN] = 0;
 raw.c_cc[VTIME] = 1;
 if (tcsetattr(fd, TCSAFLUSH, &raw))
 throw DB::ErrnoException(
 DB::ErrorCodes::SYSTEM_ERROR, "Cannot set terminal to the raw mode for the terminal referred to by file descriptor '{}'", fd);

 intercept_thread = std::make_unique<std::thread>(&TerminalKeystrokeInterceptor::run, this, callbacks);

In raw mode the terminal driver does not translate ^C into SIGINT — the byte 0x03 is simply delivered to the reader. The interceptor’s thread polls the terminal with ioctl(FIONREAD) and dispatches on the byte:

 cpp
 
 
// src/Client/TerminalKeystrokeInterceptor.cpp:125
void TerminalKeystrokeInterceptor::runImpl(const DB::TerminalKeystrokeInterceptor::CallbackMap & map) const
{
 char ch = 0;

 int available = 0;
 if (ioctl(fd, FIONREAD, &available) < 0)
 throw DB::ErrnoException(DB::ErrorCodes::SYSTEM_ERROR, "ioctl({}, FIONREAD)", fd);

 if (available <= 0)
 return;

 if (read(fd, &ch, 1) > 0) /// NOLINT(clang-analyzer-unix.BlockInCriticalSection)
 {
 auto it = map.find(ch);
 if (it != map.end())
 {
 auto fn = it->second;
 fn();
 }
 }
}

and the client registers the keys it cares about — the space bar that toggles the progress table, and, in the embedded client only, 0x03:

 cpp
 
 
// src/Client/ClientBase.cpp:1541
void ClientBase::initKeystrokeInterceptor()
{
 if (is_interactive && need_render_progress_table && progress_table_toggle_enabled)
 {
 keystroke_interceptor = std::make_unique<TerminalKeystrokeInterceptor>(stdin_fd, error_stream);
 keystroke_interceptor->registerCallback(' ', [this]() { progress_table_toggle_on = !progress_table_toggle_on; });

 if (isEmbeeddedClient())
 keystroke_interceptor->registerCallback(0x03, [this]() { tryStopQuery(); });
 }
}

So in the embedded client, Ctrl-C is not a signal at all: it is a byte read by a dedicated thread, which calls the very same tryStopQuery() — one code path for both, and no signal-handler-safety questions at all. In the ordinary clickhouse-client the interceptor only steals the space bar, and Ctrl-C remains a SIGINT.

The receive loop: where the cancel actually happens

The counter is checked in ClientBase::receiveResult, the loop that reads the server’s answer:

 cpp
 
 
// src/Client/ClientBase.cpp:1968
 while (true)
 {
 Stopwatch receive_watch(CLOCK_MONOTONIC_COARSE);

 while (true)
 {
 /// Has the Ctrl+C been pressed and thus the query should be cancelled?
 /// If this is the case, inform the server about it and receive the remaining packets
 /// to avoid losing sync.
 if (!cancelled)
 {
 if (partial_result_on_first_cancel && query_interrupt_handler.cancelled_status() == signals_before_stop - 1)
 {
 sendCancel();
 /// First cancel reading request was sent. Next requests will only be with a full cancel
 partial_result_on_first_cancel = false;
 }
 else if (query_interrupt_handler.cancelled())
 {
 cancelQuery();
 }
 else
 {
 double elapsed = receive_watch.elapsedSeconds();
 if (break_on_timeout && elapsed > receive_timeout.totalSeconds())
 {
 PreformattedMessage error_message = PreformattedMessage::create
 (
 "Timeout exceeded while receiving data from server. Waited for {} seconds, timeout is {} seconds.",
 static_cast<size_t>(elapsed),
 receive_timeout.totalSeconds()
 );

 client_exception = std::make_unique<Exception>(error_message, ErrorCodes::TIMEOUT_EXCEEDED);
 have_error = true;

 cancelQuery();
 }
 }
 }

Three things to notice.

The check is inside the poll loop, before the poll. The loop is:

 cpp
 
 
 /// Poll for changes after a cancellation check, otherwise it never reached
 /// because of progress updates from server.

 if (connection->poll(poll_interval))
 break;

so the client wakes up at most every poll_interval microseconds, checks the counter, and only then blocks in poll(). The poll interval is derived from the receive timeout and clamped:

 cpp
 
 
// src/Client/ClientBase.cpp:1955
 const auto receive_timeout = connection_parameters.timeouts.receive_timeout;
 constexpr size_t default_poll_interval = 1000000; /// in microseconds
 constexpr size_t min_poll_interval = 5000; /// in microseconds
 const size_t poll_interval
 = std::max(min_poll_interval, std::min<size_t>(receive_timeout.totalMicroseconds(), default_poll_interval));

Between 5 ms and 1 s. That is the client-side cancellation latency — the time between the user pressing Ctrl-C and the server being told. The server-side article covers the other half of that latency.

The “keep receiving to avoid losing sync” comment is the whole design. The client does not stop reading after it sends the cancel. It keeps reading until the server says the query is over.

The same machinery cancels for two other reasons. A receive timeout (TIMEOUT_EXCEEDED) and a broken output pipe (a LocalFormatError from the output formatter) both call sendCancel and then keep receiving:

 cpp
 
 
// src/Client/ClientBase.cpp:2040
 catch (const LocalFormatError &)
 {
 /// Remember the first exception.
 if (!local_format_error)
 local_format_error = std::current_exception();
 sendCancel(std::current_exception());
 }

which is why head -1 on a clickhouse-client pipe does not leave the server burning CPU, and does not leave the connection unusable.

The packet itself

The cancel is one VarUInt on the same socket:

 cpp
 
 
// src/Client/Connection.cpp:1236
void Connection::sendCancel()
{
 /// If we already disconnected.
 if (!out)
 throw Exception(ErrorCodes::NETWORK_ERROR, "Connection to {} terminated", getDescription());

 writeVarUInt(Protocol::Client::Cancel, *out);
 out->finishChunk();
 out->next();
}

Protocol::Client::Cancel is 3:

 cpp
 
 
// src/Core/Protocol.h:123
 Cancel = 3, /// Cancel the query execution.

That is the entire wire format of a cancellation: one byte, 0x03, plus the chunked-protocol framing. The TCP socket is full-duplex, so the client can write it while it is in the middle of reading result blocks — no second connection, no out-of-band channel, no kill -SIGINT on the server.

The client’s sendCancel wrapper handles the one case where this is impossible:

 cpp
 
 
// src/Client/ClientBase.cpp:2949
bool ClientBase::sendCancel(std::exception_ptr exception_ptr)
{
 if (!connection->isConnected())
 {
 error_stream << "Cannot send Cancel due to connection is lost";
 if (exception_ptr)
 {
 error_stream << ": ";
 error_stream << getExceptionMessage(exception_ptr, /*with_stacktrace=*/ true);
 }
 error_stream << '\n';
 return false;
 }
 else
 {
 connection->sendCancel();
 return true;
 }
}

and the user-visible counterpart clears the progress display and says so:

 cpp
 
 
// src/Client/ClientBase.cpp:2969
void ClientBase::cancelQuery()
{
 sendCancel();

 stopKeystrokeInterceptorIfExists();

 if (need_render_progress && tty_buf)
 {
 std::unique_lock lock(tty_mutex);
 progress_indication.clearProgressOutput(*tty_buf, lock);
 }
 if (need_render_progress_table && tty_buf)
 {
 std::unique_lock lock(tty_mutex);
 progress_table.clearTableOutput(*tty_buf, lock);
 }

 if (is_interactive)
 output_stream << "Cancelling query." << std::endl;

 cancelled = true;
}

Staying in sync: the part everyone forgets

After the cancel, the server may still have blocks in flight. The client keeps reading them and discards them, which is what keeps the protocol aligned:

 cpp
 
 
// src/Client/ClientBase.cpp:2060
bool ClientBase::receiveAndProcessPacket(ASTPtr parsed_query, bool cancelled_)
{
 Packet packet = connection->receivePacket();

 switch (packet.type)
 {
 case Protocol::Server::Data:
 if (!cancelled_)
 onData(packet.block, parsed_query);
 return true;

 case Protocol::Server::Progress:
 onProgress(packet.progress);
 return true;

Data, Totals and Extremes are dropped when cancelled_ is true; Progress, Log and ProfileEvents are still processed (the progress bar should keep updating until the server actually stops). The loop ends when the server sends EndOfStream:

 cpp
 
 
// src/Client/ClientBase.cpp:2097
 case Protocol::Server::EndOfStream:
 onEndOfStream();
 return false;

and onEndOfStream is where the client explicitly declares the session clean:

 cpp
 
 
// src/Client/ClientBase.cpp:2149
void ClientBase::onEndOfStream()
{
 /// `EndOfStream` terminates the query exchange with the protocol in sync, whatever happens
 /// below or afterwards. This also covers the failures that are recovered by draining the
 /// exchange: a `LocalFormatError` in the middle of a result (`receiveResult` sends `Cancel`
 /// and keeps receiving until the end of the stream) and a client-side failure while sending
 /// the data of an `INSERT` (`processInsertQuery` sends `Cancel` and calls
 /// `receiveEndOfQueryForInsert`). Such a session must not resynchronize the connection with
 /// a round trip: a `Pong` that does not arrive within `sync_request_timeout` is
 /// indistinguishable from a closed connection, and the client would silently reconnect,
 /// losing its temporary tables, current database and session settings.
 connection_needs_resynchronization = false;

This is the payoff of the whole design. Because the client drained the exchange, it knows the protocol is in sync, and it therefore does not have to resynchronize — which would cost a round trip and, if the Pong did not come back, would silently reconnect and lose the session. Cancelling a query costs the user nothing but the query.

One Ctrl-C or two: the partial-result trick

The counter is armed with a number that depends on a setting:

 cpp
 
 
// src/Client/ClientBase.cpp:1849
 const auto & settings = client_context->getSettingsRef();
 const Int32 signals_before_stop = settings[Setting::partial_result_on_first_cancel] ? 2 : 1;

and it is armed (and disarmed) around the query itself:

 cpp
 
 
// src/Client/ClientBase.cpp:1864
 try
 {
 query_interrupt_handler.start(signals_before_stop);
 SCOPE_EXIT({ query_interrupt_handler.stop(); });

partial_result_on_first_cancel defaults to false:

 cpp
 
 
// src/Core/Settings.cpp:3311
 DECLARE(Bool, partial_result_on_first_cancel, false, R"(
Allows query to return a partial result after cancel.
)", 0) \

so by default signals_before_stop is 1 and the counter starts at 1. Now look closely at tryStop() again:

 cpp
 
 
// src/Client/ClientBase.h:351
 bool tryStop() { return exit_after_signals.fetch_sub(1) <= 0; }

fetch_sub returns the value before the subtraction. With the counter at 1, the first Ctrl-C makes fetch_sub(1) return 1, and 1 <= 0 is false — so tryStop() returns false and the process does not exit. But the counter is now 0, so cancelled() is true and the query gets cancelled.

In other words: start(1) means “one interrupt cancels the query, a second one kills the client”. The first Ctrl-C is consumed by the query, not by the process. Only when the query is over does the SCOPE_EXIT reset the counter to 0, at which point the next Ctrl-C’s fetch_sub returns 0, 0 <= 0 is true, and the process exits with 128 + SIGINT.

That is the design in one sentence: the counter is shared between “stop the query” and “stop the process”, and the query gets the first interrupt.

The two-stage cancel works the same way. With partial_result_on_first_cancel enabled, the counter is armed at 2 and the receive loop distinguishes the two interrupts by their residual count:

 cpp
 
 
// src/Client/ClientBase.cpp:1979
 if (partial_result_on_first_cancel && query_interrupt_handler.cancelled_status() == signals_before_stop - 1)
 {
 sendCancel();
 /// First cancel reading request was sent. Next requests will only be with a full cancel
 partial_result_on_first_cancel = false;
 }
 else if (query_interrupt_handler.cancelled())
 {
 cancelQuery();
 }

After the first Ctrl-C the residual count is 1, which equals signals_before_stop - 1 (2 - 1), so the client sends a soft cancel. After the second Ctrl-C the residual count is 0, cancelled() is true, and the client sends the hard cancel.

The server is what makes the two cancels different. The first one is interpreted as “stop working, but send me what you have”:

 cpp
 
 
// src/Server/TCPHandler.cpp:3155
void TCPHandler::processCancel(QueryState & state)
{
 if (state.allow_partial_result_on_first_cancel && !state.stop_read_return_partial_result)
 {
 state.stop_read_return_partial_result = true;
 LOG_INFO(log, "Received 'Cancel' packet from the client, returning partial result.");
 return;
 }

 state.read_all_data = true;
 state.stop_query = true;

 throw Exception(ErrorCodes::QUERY_WAS_CANCELLED_BY_CLIENT, "Received 'Cancel' packet from the client, canceling the query.");
}

The first Cancel flips a flag and returns; the second one sets stop_query and throws. The client’s choice of which cancel to send is therefore a two-way handshake encoded in a counter.

The local connection

Not every client talks to a server over TCP. clickhouse-local runs the server in-process, and the “cancel” is a different mechanism with the same interface:

 cpp
 
 
// src/Client/LocalConnection.cpp:113
LocalConnection::~LocalConnection()
{
 /// Last query may have not been finished or cancelled due to exception on client side.
 if (state && !state->is_finished && !state->is_cancelled)
 {
 try
 {
 LocalConnection::sendCancel();
 }
 catch (...) // NOLINT(bugprone-empty-catch)
 {
 /// Just ignore any exception.
 }
 }
 state.reset();
}

Note the destructor: even if the client is destroyed mid-query, it makes a best-effort attempt to cancel the query it abandoned.

Trade-offs

What the design buys.

The session survives. No reconnect, no lost temporary tables, no lost SET values, no lost current database. Cancelling a query in the middle of a session is free.
The latency is bounded. The client checks the flag at least every 5 ms, and the server checks the socket at least every interactive_delay (100 ms by default). The end-to-end cancellation latency is therefore tens of milliseconds, not “whenever the result set finishes”.
One mechanism, four uses. User interrupt, receive timeout, broken output pipe, and client-side failure during an INSERT all funnel into sendCancel + drain. There is exactly one place where the “am I still in sync?” question is answered.
The signal handler is trivially safe. It touches one atomic integer. There is no write() in a signal handler, no allocation, and no lock.

What it costs.

The connection must be drained. After a cancel, the client keeps reading until EndOfStream. If the server is in the middle of sending a 10 GB result, the client still reads (and discards) all of it. The cancellation saves the server’s compute, not the server’s output bandwidth. On a fast local socket with a huge result, cancelling can feel like it takes a while.
The poll interval is a trade-off. 5 ms of polling is a wake-up every 5 ms for the life of the query; 1 s would make Ctrl-C feel sluggish. The client picks min(receive_timeout, 1 s) and floors it at 5 ms.
The two-stage cancel is stateful and subtle. The residual counter has to mean “one more interrupt” in one place and “the last interrupt” in another, and the server has to remember whether it has already sent a partial result. A mistake in either direction shows up as “the first Ctrl-C returned partial results when I did not ask for that” or “the second Ctrl-C did nothing”.
The exit code is confusing. Because tryStop() decrements before comparing, a counter armed at 1 means “one Ctrl-C cancels the query, two kill the client”. Users expect Ctrl-C to exit the process, and it does — but only on the second press, and the first press is now a “cancel the query” instead. This is a behaviour change from the mysql client, where Ctrl-C always kills the process.
The terminal must be in raw mode for the byte path. The keystroke interceptor only exists when the progress table is enabled and the client is interactive, and the 0x03 callback is registered only in the embedded client; in every other configuration Ctrl-C is a SIGINT and the signal path is used.

The one thing to remember: the client is not “killing” the query, it is asking the server to stop, over the same connection, in one byte, and then finishing the conversation politely. That is why the connection survives.

The part people get wrong: cancelling does not free the server’s output bandwidth. The client drains the rest of the result stream, it just does not print it. If you are cancelling a query that is streaming hundreds of gigabytes to the client, the server will keep writing until the client has read it all.

What to go do about it: try SETTINGS partial_result_on_first_cancel = 1 on a long query and press Ctrl-C once. You get the rows that had already been computed; press it again and the query is killed outright.