(I don't know what would cause sqlite3_prepare_v2 to fail

Passing a NULL to finalize() is perfectly legal and harmless, but passing an uninitalized pointer invokes undefined behavior.

The very first thing the prepare() variants do is assign *ppStmt to NULL and they only assign *ppStmt to non-NULL if they succeed. Thus if, after they return, that pointer is not NULL then (A) it succeeded and (B) you need to pass it to finalize().

There is one odd corner case: prepare() will succeed (return 0) for empty inputs (e.g. just comments or spaces) but *ppStmt will be NULL for that case. It's safe to pass that NULL to finalize() but it's not safe to assume that success equates to a non-NULL statement handle.

Edit: Citation: reading the source code. We'll get the docs updated to clarify this behavior.

We'll get the docs updated to clarify this behavior.

Not necessary. The docs currently say:

*ppStmt is left pointing to a compiled prepared statement that can be executed using sqlite3_step(). If there is an error, *ppStmt is set to NULL. If the input text contains no SQL (if the input is an empty string or a comment) then *ppStmt is set to NULL. The calling procedure is responsible for deleting the compiled SQL statement using sqlite3_finalize() after it has finished with it. ppStmt may not be NULL.

Which seems to address all of the cases. finalize()'s own docs clarify that:

Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.

Thanks, missed the first doc reference.