Exceptions

deep_db_agents.exceptions

Exceptions raised by the deep-db-agents library.

DeepDbAgentError

Bases: Exception

Base class for all exceptions raised by the library.

EstimateExceededError

Bases: GuardrailError

The EXPLAIN row estimate exceeded the configured threshold.

Like :class:RowBudgetExceededError, the query tools catch this and turn it into corrective feedback for the agent instead of interrupting the turn: the query is still not executed, but the agent is told to refine its filters or aggregate and retry.

GuardrailError

Bases: DeepDbAgentError

A hard guardrail blocked execution (e.g. EXPLAIN threshold or budget exceeded).

InvalidDbUrlError

Bases: DeepDbAgentError

The database URL is not in the <scheme>://<host>:<port> format.

InvalidMultiAgentConfigError

Bases: DeepDbAgentError

The db_agents configuration for the multi-database orchestrator is invalid.

QueryNotAllowedError

Bases: DeepDbAgentError

The query violates the whitelist of allowed operations (e.g. it is not a SELECT).

RowBudgetExceededError

Bases: GuardrailError

The cumulative session row budget was exhausted.

Raised by :meth:SessionBudget.charge once the rows consumed in the session exceed the configured budget. Like :class:EstimateExceededError, the query tools catch this and turn it into corrective feedback for the agent instead of interrupting the turn: the just-retrieved result is not returned, and the agent is told to aggregate/summarize or start a new session rather than extract more rows.

UnsupportedSchemeError

UnsupportedSchemeError(scheme: str, available: list[str])

Bases: DeepDbAgentError

No dialect is registered for the requested scheme.

Initialize the error with the offending scheme and the available ones.

Parameters:

Name	Type	Description	Default
scheme	str	The unsupported URL scheme that was requested.	required
available	list[str]	The list of currently registered schemes.	required

Source code in src/deep_db_agents/exceptions.py

def __init__(self, scheme: str, available: list[str]):
    """Initialize the error with the offending scheme and the available ones.

    Args:
        scheme: The unsupported URL scheme that was requested.
        available: The list of currently registered schemes.
    """
    self.scheme = scheme
    self.available = available
    super().__init__(
        f"Unsupported database scheme: {scheme!r}. "
        f"Available schemes: {', '.join(sorted(available)) or '(none)'}."
    )