Exceptions

All exceptions in SQLiter inherit from SqliterError. Import them from sqliter.exceptions:

from sqliter.exceptions import (
    SqliterError,
    DatabaseConnectionError,
    RecordInsertionError,
    # ...
)

Source: sqliter/exceptions.py

See also: Guide -- Exceptions

Hierarchy

Exception
└── SqliterError
    ├── DatabaseConnectionError
    ├── TableCreationError
    ├── TableDeletionError
    ├── RecordInsertionError
    ├── RecordUpdateError
    ├── RecordNotFoundError
    ├── RecordFetchError
    ├── RecordDeletionError
    ├── InvalidFilterError
    ├── InvalidOffsetError
    ├── InvalidOrderError
    ├── InvalidRelationshipError
    ├── InvalidPrefetchError
    ├── InvalidIndexError
    ├── ForeignKeyError
    │   ├── ForeignKeyConstraintError
    │   └── InvalidForeignKeyError
    └── SqlExecutionError

Base Exception

SqliterError

Base exception class for all SQLiter-specific errors.

class SqliterError(Exception):
    message_template: str = "An error occurred in the SQLiter package."

Attributes:

Behavior:

• Formats message_template with positional *args.
• Captures the active exception via sys.exc_info() and appends its type, location, and message.
• Chains the original exception using __cause__.

Connection Exceptions

DatabaseConnectionError

Raised when a database connection cannot be established.

message_template = "Failed to connect to the database: '{}'"

Raised by:

• SqliterDB.connect()

Table Exceptions

TableCreationError

Raised when a table cannot be created in the database.

message_template = "Failed to create the table: '{}'"

Raised by:

• SqliterDB.create_table()

TableDeletionError

Raised when a table cannot be deleted from the database.

message_template = "Failed to delete the table: '{}'"

Raised by:

• SqliterDB.drop_table()

Record Exceptions

RecordInsertionError

Raised when a record cannot be inserted into the database.

message_template = "Failed to insert record into table: '{}'"

Raised by:

• SqliterDB.insert()

RecordUpdateError

Raised when a record cannot be updated in the database.

message_template = "Failed to update record in table: '{}'"

Raised by:

• SqliterDB.update()

RecordNotFoundError

Raised when a requested record is not found in the database.

message_template = "Failed to find that record in the table (key '{}') "

Raised by:

• SqliterDB.update() (when no rows match)
• SqliterDB.delete() (when no rows match)

RecordFetchError

Raised on an error fetching records from the database.

message_template = "Failed to fetch record from table: '{}'"

Raised by:

• SqliterDB.get()
• QueryBuilder._execute_query() (internal)

RecordDeletionError

Raised when a record cannot be deleted from the database.

message_template = "Failed to delete record from table: '{}'"

Raised by:

• SqliterDB.delete()
• QueryBuilder.delete()

Query Exceptions

InvalidFilterError

Raised when an invalid filter is applied to a query.

message_template = "Failed to apply filter: invalid field '{}'"

Raised by:

• QueryBuilder.filter()

InvalidOffsetError

Raised when an invalid offset value is provided.

message_template = (
    "Invalid offset value: '{}'. Offset must be a positive integer."
)

Raised by:

• QueryBuilder.offset()

InvalidOrderError

Raised when an invalid order specification is provided.

message_template = "Invalid order value - {}"

Raised by:

• QueryBuilder.order()

InvalidRelationshipError

Raised when an invalid relationship path is specified in select_related() or relationship filter traversal.

message_template = (
    "Invalid relationship path '{}': field '{}' is not a valid "
    "foreign key relationship on model {}"
)

Raised by:

• QueryBuilder.select_related()
• QueryBuilder.filter() (relationship traversal)

InvalidPrefetchError

Raised when an invalid relationship path is specified in prefetch_related(). This includes paths that don't exist, forward FK paths (which should use select_related()), and any attribute that is not a reverse FK or M2M relationship.

message_template = (
    "Invalid prefetch path '{}': '{}' is not a reverse "
    "foreign key or many-to-many relationship on model {}"
)

Raised by:

• QueryBuilder.prefetch_related()

Index Exceptions

InvalidIndexError

Raised when one or more fields specified for an index do not exist in the model's fields. Has a custom __init__ that accepts structured arguments.

class InvalidIndexError(SqliterError):
    message_template = "Invalid fields for indexing in model '{}': {}"

    def __init__(
        self,
        invalid_fields: list[str],
        model_class: str,
    ) -> None:

Parameters:

Attributes:

Raised by:

• SqliterDB.create_table() (during index creation)

Foreign Key Exceptions

ForeignKeyError

Base exception for foreign key related errors.

message_template = "Foreign key error: {}"

ForeignKeyConstraintError

Raised when a foreign key constraint is violated (e.g., inserting a record with a FK value that does not exist in the referenced table, or deleting a record that is still referenced).

message_template = (
    "Foreign key constraint violation: Cannot {} record - "
    "referenced record {}"
)

Raised by:

• SqliterDB.insert() (FK value not in referenced table)
• SqliterDB.delete() (record still referenced with RESTRICT)

InvalidForeignKeyError

Raised when an invalid foreign key configuration is detected (e.g., using SET NULL without null=True).

message_template = "Invalid foreign key configuration: {}"

Raised by:

• ForeignKey() factory function

SQL Exceptions

SqlExecutionError

Raised when a raw SQL execution fails.

message_template = "Failed to execute SQL: '{}'"

Raised by:

• Internal SqliterDB._execute_sql() method (used by create_table(), drop_table(), and index creation)