sqlite::database_exception | vsqlite++ Reference

All database errors throw std::exception derived types to ensure C++ code can respond appropriately. Each class mirrors a distinct error category: runtime failures, misuse/logic errors, buffer sizing mistakes, and system (errno) failures.

Use cases

Every exception carries enough metadata (SQL text, SQLite error code, optional errno) to log actionable diagnostics.
Runtime vs. logic errors follow the STL policy: user mistakes are std::logic_error derived, environmental issues remain std::runtime_error.
Prefer catching the more specific type if you want to branch on error_code() or include the failing SQL statement in metrics.

Example usage

try {
    sqlite::execute cmd{db, "INSERT INTO files(path, blob) VALUES(?, ?)"};
    cmd % path % blob_span;
    cmd();
} catch (sqlite::database_exception_code const & ex) {
    if (ex.error_code() == SQLITE_CONSTRAINT_UNIQUE) {
        log::warn(\"Duplicate path {}\", path);
    } else {
        throw; // unexpected SQLite state
    }
} catch (sqlite::database_system_error const & sys) {
    throw filesystem_error(sys.error_code(), sys.what());
}

Those exception messages already carry the [SQL: ...] suffix, so logging ex.what() verbatim is usually enough to find the failing statement later.

Runtime errors

Type	Members	Description
`struct database_exception : std::runtime_error`	`explicit database_exception(std::string const& msg)`	Base class for general SQLite failures.
`struct database_exception_code : database_exception`	`database_exception_code(std::string const& msg, int sqlite_err, std::string sql = {})` `int error_code() const` `std::string const& sql() const`	Captures `sqlite3_errcode` plus the SQL snippet that failed.
`std::string append_sql_context(std::string message, std::string const& sql)`	Free helper	Formats `"Message [SQL: ...]"` strings.

Misuse & buffer errors

Type	Members	Description
`struct buffer_too_small_exception : std::runtime_error`	`explicit buffer_too_small_exception(std::string const& msg)`	Raised when user-provided buffers cannot hold a blob/text column.
`struct database_misuse_exception : std::logic_error`	`explicit database_misuse_exception(std::string const& msg)`	Signals API misuse detected by vsqlite++ (e.g., stale cursor access).
`struct database_misuse_exception_code : database_misuse_exception`	`database_misuse_exception_code(std::string const& msg, int sqlite_err, std::string sql = {})` `int error_code() const` `std::string const& sql() const`	Logic-error equivalent of `database_exception_code`.

System errors

Type	Members	Description
`struct database_system_error : database_exception`	`database_system_error(std::string const& msg, int errno_value)` `int error_code() const`	Wraps OS-level failures when interacting with the filesystem adapter.