Enum SqlError 

pub enum SqlError {
    UnsupportedScheme(String),
    InvalidUrl(String),
    BackendDisabled(String),
    ConnectionFailed(String),
    QueryFailed(String),
    BulkUnavailable(String),
    TlsError(String),
    Io(Error),
    SshHostKeyMismatch {
        host: String,
        port: u16,
    },
    SshUnknownHost {
        host: String,
        port: u16,
        algorithm: String,
        fingerprint: String,
        key: Box<PublicKey>,
    },
    Timeout,
    CellTooLarge {
        row: u64,
        column: String,
        size: usize,
        cap: usize,
    },
    RowTooLarge {
        row: u64,
        size: usize,
        cap: usize,
    },
    BufferTooLarge {
        rows_buffered: u64,
        cap: usize,
    },
    RegistryError(String),
}

Errors originating in the ferrule-sql driver and write-path layer.

Every backend method, URL parse, connect dispatch, transaction helper, and copy routine returns this type. Variant names and tuple shapes are load-bearing across the workspace (the CLI pattern-matches SqlError::QueryFailed in several hot paths), so preserve them when editing.

RegistryError is registry/CLI-level rather than driver-level; it rides along here as a deliberate minimal-diff choice during the ferrule-core -> ferrule-sql extraction and is a candidate for a later relocation to a core-side error type.

Variants

UnsupportedScheme(String)

InvalidUrl(String)

BackendDisabled(String)

ConnectionFailed(String)

QueryFailed(String)

BulkUnavailable(String)

Backend-native bulk-load path is not usable at runtime (server config, missing capability, permission denied, target relation is not a base table, etc.). Callers may retry on the generic INSERT path. The string is intended for stderr only; do not match on it.

TlsError(String)

Io(Error)

SshHostKeyMismatch

Host key mismatch during SSH tunnel setup (always fatal).

Fields

host: String

port: u16

SshUnknownHost

Unknown host during SSH tunnel setup (can be TOFU-prompted interactively by the CLI layer).

Fields

host: String

port: u16

algorithm: String

fingerprint: String

key: Box<PublicKey>

Boxed so this (otherwise large) variant doesn’t inflate the whole SqlError enum — every synchronous backend method returns Result<_, SqlError> by value, so an oversized error variant would bloat every Ok path too.

Timeout

CellTooLarge

A single cell exceeded the configured max_cell_bytes guard.

Raised by the read paths (streaming cursor and eager query) before the offending value is retained, so the guard caps peak memory at one over-budget cell rather than letting a pathological bytea / TEXT blow the heap. row is the 0-based row ordinal within the current result; column names the offending column; size and cap are byte counts.

Fields

row: u64

column: String

size: usize

cap: usize

RowTooLarge

A whole row’s measured byte size exceeded max_row_bytes.

Like CellTooLarge this fires before the row is appended to any buffer, so an unexpectedly wide row fails fast instead of being materialized. row is the 0-based ordinal; size/cap are byte counts.

Fields

row: u64

size: usize

cap: usize

BufferTooLarge

The running total of buffered row bytes crossed max_total_buffered_bytes while materializing an eager result.

This is the guard the CLI’s eager table path relies on: rather than collect an unbounded Vec<Row> for a huge table, the eager query accumulates a byte tally and aborts once it crosses the cap. rows_buffered is how many rows had been accumulated; cap is the byte ceiling.

Fields

rows_buffered: u64

cap: usize

RegistryError(String)

Trait Implementations

impl Debug for SqlError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for SqlError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for SqlError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for SqlError

fn from(source: Error) -> Self

Converts to this type from the input type.