Throwing a specific error on purpose

Client code has to behave when ClickHouse says no: retry on a transient Keeper failure, page on TOO_MANY_PARTS, back off on MEMORY_LIMIT_EXCEEDED. Those branches are only tested if you can make the server fail that way, and for the interesting codes that means breaking Keeper or inserting until parts explode. throwIf only ever raised FUNCTION_THROW_IF_VALUE_IS_NON_ZERO (code 395). I asked for a function that throws the code I name.

On the issue, one maintainer asked whether a mock server or a real scenario could do it; I answered that building a real scenario for each error is impractical. Alexey Milovidov agreed with the need but suggested extending throwIf with an extra argument rather than adding a function, and required it to be off by default behind a setting: “we don’t want to have fake errors in normal environments.”

That shipped as PR #40319 (“Allow custom error code in throwIf”, rschu1ze), merged 2022-08-19, eighteen days after the issue, in release 22.9. Checked on 26.4: the third argument must be an Int8, Int16 or Int32 (so a literal needs toInt32()), and the setting allow_custom_error_code_in_throwif must be on.

SELECT throwIf(1, 'simulated', toInt32(252)) SETTINGS allow_custom_error_code_in_throwif = 1;
-- Code: 252. DB::Exception: Value passed to 'throwIf' function is non-zero ... (TOO_MANY_PARTS)

Without the setting, the three-argument form is rejected as a wrong argument count. For names to pick from, see the error codes snippet.