error.rs

Overview

This file defines error handling constructs for interfacing with SQLite, encapsulating SQLite error codes and extended error codes into Rust-friendly types and messages. It provides an ErrorCode enumeration that represents various SQLite error conditions, an Error struct that holds both a primary error code and an extended error code, and utility functions for mapping numeric SQLite error codes to human-readable descriptions. Additionally, it optionally defines an InitError enumeration for loadable extension initialization errors, conditional on the loadable_extension feature.

The file's primary purpose is to convert raw SQLite error codes into strongly-typed Rust errors with descriptive messages, facilitating robust error management in database operations.

Enumerations and Structs

ErrorCode

An enum representing the canonical set of SQLite error codes.

• Variants include:

  • InternalMalfunction: Internal logic error in SQLite

  • PermissionDenied: Access permission denied

  • OperationAborted: Callback routine requested an abort

  • DatabaseBusy: The database file is locked

  • DatabaseLocked: A table in the database is locked

  • OutOfMemory: A malloc() failed

  • ReadOnly: Attempt to write a readonly database

  • OperationInterrupted: Operation terminated by sqlite3_interrupt()

  • SystemIoFailure: Some kind of disk I/O error occurred

  • DatabaseCorrupt: The database disk image is malformed

  • NotFound: Unknown opcode in sqlite3_file_control()

  • DiskFull: Insertion failed because database is full

  • CannotOpen: Unable to open the database file

  • FileLockingProtocolFailed: Database lock protocol error

  • SchemaChanged: The database schema changed

  • TooBig: String or BLOB exceeds size limit

  • ConstraintViolation: Abort due to constraint violation

  • TypeMismatch: Data type mismatch

  • ApiMisuse: Library used incorrectly

  • NoLargeFileSupport: Uses OS features not supported on host

  • AuthorizationForStatementDenied: Authorization denied

  • ParameterOutOfRange: 2nd parameter to sqlite3_bind out of range

  • NotADatabase: File opened that is not a database file

  • Unknown: Fallback for unknown error codes

• Attributes:

  • #[non_exhaustive] indicates the enum may be extended in the future, preventing exhaustive matching outside this crate.

  • Implements Clone, Copy, Debug, PartialEq, and Eq.

Error

A struct that represents a SQLite error, combining the main error code and the extended error code.

• Fields:

  • code: ErrorCode — The primary error category.

  • extended_code: c_int — The raw SQLite extended error code (including subcode information).

• Methods:

  • pub fn new(result_code: c_int) -> Self

    Constructs an Error from a raw SQLite result code integer. It masks the lower 8 bits to map to the primary ErrorCode, while preserving the full extended code.

    • Parameters:

      • result_code: The SQLite error code integer.

    • Returns:

      • An Error instance representing the mapped error.

    • Usage example:

    let err = Error::new(sqlite_result_code);
    println!("Error: {}", err);
    

• Trait Implementations:

  • fmt::Display — Formats the error for human-readable output, showing the extended code and its string description.

  • error::Error — Implements the standard error trait with a description() method that returns the error description string.

Functions

code_to_str

pub fn code_to_str(code: c_int) -> &'static str

Maps an SQLite raw error code (including extended codes) to a static string description.

• Parameters:

  • code: The integer SQLite error code or extended code.

• Returns:

  • A string slice describing the error.

• Notes:

  • Contains a comprehensive match arm with mappings for all known SQLite error codes and extended codes.

  • Returns "Unknown error code" for unrecognized codes.

• Example:

let description = code_to_str(sqlite_code);
println!("Error description: {}", description);

Loadable Extension Error Handling (Feature-gated)

InitError

Defined only if the loadable_extension feature is enabled.

An enum representing errors during loadable SQLite extension initialization.

• Variants:

  • VersionMismatch { compile_time: i32, runtime: i32 }

    • Indicates a version mismatch between the extension compiled time and the runtime SQLite library.

  • NullFunctionPointer

    • Indicates one or more null function pointers in sqlite3_api_routines.

• Trait Implementations:

  • fmt::Display — Provides formatted error messages for each variant.

  • error::Error — Implements the standard error trait.

Implementation Details and Algorithms

• The Error::new method isolates the primary error code by masking the low 8 bits of the extended SQLite result code (result_code & 0xff). This matches SQLite's error code conventions where the lower 8 bits represent the basic error category and the higher bits encode extended error information.

• Extended error codes are defined in this file as constants (e.g., SQLITE_IOERR_BEGIN_ATOMIC) by combining the base error code with shifted values to create subcodes. These constants are used in the code_to_str function to provide descriptive error messages.

• The code_to_str function uses a large match statement to translate both primary and extended SQLite error codes to human-readable descriptions. This is essential for debugging and user feedback.

• The Error struct stores both the base and extended codes, enabling more granular error handling if needed.

Interaction with Other Parts of the System

• The error codes (SQLITE_INTERNAL, SQLITE_PERM, etc.) are imported from a sibling module or the parent module (super::). This file relies on those constants being defined elsewhere, likely in bindings generated from SQLite's C headers.

• The Error struct and related enums are intended to be used throughout the project wherever SQLite operations occur, providing consistent error handling and messaging.

• The InitError enum integrates with the loadable extension feature, which is an advanced SQLite capability allowing runtime loading of extensions. This ties into dynamic function pointers and API structure validation.

• The test module verifies the correctness of the Error::new constructor by asserting that given SQLite codes map to the expected ErrorCode variants and that the formatted string representations are non-empty.

Visual Diagram: Error Handling Structure

classDiagram
class ErrorCode {
<<enum>>
+InternalMalfunction
+PermissionDenied
+OperationAborted
+DatabaseBusy
+DatabaseLocked
+OutOfMemory
+ReadOnly
+OperationInterrupted
+SystemIoFailure
+DatabaseCorrupt
+NotFound
+DiskFull
+CannotOpen
+FileLockingProtocolFailed
+SchemaChanged
+TooBig
+ConstraintViolation
+TypeMismatch
+ApiMisuse
+NoLargeFileSupport
+AuthorizationForStatementDenied
+ParameterOutOfRange
+NotADatabase
+Unknown
}
class Error {
+code: ErrorCode
+extended_code: c_int
+new()
+fmt::Display
+error::Error
}
class InitError {
<<enum>>
+VersionMismatch
+NullFunctionPointer
+fmt::Display
+error::Error
}
Error --> ErrorCode : has
Error ..> "code_to_str()" : uses
InitError <|-- (feature: loadable_extension)

Testing

• The module test contains unit tests for validating the Error::new function.

• It checks that various SQLite error codes correctly map to ErrorCode variants.

• Also verifies that the Display implementation produces non-empty strings.

• This ensures the error mapping and formatting are functioning as expected.

Key References

• For detailed SQLite error codes and their meanings, see SQLite Error Codes.

• For Rust error handling conventions and traits, refer to Error Handling in Rust.

• For loadable extension architecture and API, consult SQLite Loadable Extensions.