Enum Error 

#[non_exhaustive]
pub enum Error {
    Connection {
        message: String,
        source: Option<Error>,
        sqlstate: Option<String>,
    },
    Authentication(String),
    Tls(String),
    Server {
        sqlstate: Option<String>,
        message: String,
        detail: Option<String>,
        hint: Option<String>,
    },
    Protocol(String),
    Io(Error),
    Closed {
        message: String,
        sqlstate: Option<String>,
    },
    Timeout(String),
    Cancelled {
        message: String,
        sqlstate: Option<String>,
    },
    Conversion(String),
    Config(String),
    FeatureNotSupported(String),
    InvalidName(String),
    InvalidTableDefinition(String),
    NotFound(String),
    AlreadyExists(String),
    InvalidOperation(String),
    Column {
        name: String,
        kind: ColumnErrorKind,
    },
    ColumnIndexOutOfBounds {
        idx: usize,
        column_count: usize,
    },
    Internal {
        message: String,
    },
}

The error type for Hyper API operations.

This enum is #[non_exhaustive]: new variants may be added in minor releases, so match arms must include a wildcard _ => pattern.

Struct variants (Connection, Server, Column, ColumnIndexOutOfBounds, Internal) cannot use Rust’s #[non_exhaustive] (E0639), so forward-compatibility for new fields relies on construction via the provided constructors:

• Self::internal for Self::Internal
• Self::connection / Self::connection_with_io for Self::Connection
• Self::server for Self::Server
• Self::column for Self::Column
• Self::column_index_out_of_bounds for Self::ColumnIndexOutOfBounds

Downstream code that uses struct-expression syntax for these variants will fail to compile if a new field is added in a minor release; using the constructors keeps callers source-compatible.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Connection

Connection-level failure (network, handshake, lifecycle, socket I/O). Carries the underlying std::io::Error when one is available; the type is erased at the wire-protocol boundary in hyperdb-api-core, so source is None for errors that originated there. sqlstate is set when the server provided a connection-class SQLSTATE (e.g. 08001, 08006, 57P03).

Construct via Self::connection, Self::connection_with_io, or Self::connection_with_sqlstate.

Fields

message: String

Human-readable description.

source: Option<Error>

Underlying I/O error, if available.

sqlstate: Option<String>

PostgreSQL SQLSTATE code, if the server provided one (typically 08* connection-class codes).

Authentication(String)

Authentication failed.

Tls(String)

TLS handshake or configuration failure.

Server

Server-side error (a SQL query or DDL command failed at the server). sqlstate is the 5-character PostgreSQL SQLSTATE code when the server reported one. detail and hint mirror the structured fields the server may include in its error response and are appended to the Display output when present.

Fields

sqlstate: Option<String>

The 5-character PostgreSQL SQLSTATE code, if reported.

message: String

The primary error message from the server.

detail: Option<String>

Additional detail line from the server’s error response.

hint: Option<String>

Resolution hint from the server’s error response.

Protocol(String)

Wire-protocol or framing error.

Io(Error)

Direct I/O error (file system, non-network sockets) at the SDK boundary. Network I/O during connection lifecycle is reported as Self::Connection instead.

Closed

Operation attempted on a closed connection. sqlstate is set when the server provided one (typically 57P01 admin shutdown or 57P02 crash shutdown). Construct via Self::closed or Self::closed_with_sqlstate.

Fields

message: String

Human-readable description.

sqlstate: Option<String>

PostgreSQL SQLSTATE code, if the server provided one.

Timeout(String)

Operation timed out.

Cancelled

Operation was cancelled. sqlstate is set when the server provided one (typically 57014 query_canceled). Construct via Self::cancelled or Self::cancelled_with_sqlstate.

Fields

message: String

Human-readable description.

sqlstate: Option<String>

PostgreSQL SQLSTATE code, if the server provided one.

Conversion(String)

Type or value conversion failed (out-of-range numeric, malformed binary value, scalar query returned no rows, etc.). For column-specific decoding errors, prefer Self::Column.

Config(String)

Configuration error (invalid endpoint, missing env var, bad option combination).

FeatureNotSupported(String)

Feature is not supported on this connection or transport.

InvalidName(String)

Database identifier is invalid (empty, exceeds the PostgreSQL 63-byte limit, or violates other naming rules).

InvalidTableDefinition(String)

Table definition is invalid (zero columns, conflicting attributes).

NotFound(String)

Database object (schema, table, etc.) was not found.

AlreadyExists(String)

Database object already exists.

InvalidOperation(String)

Caller-API misuse: a method was called in an invalid sequence or combination (e.g. mixing two mutually exclusive insertion modes on a single inserter, calling a method after the resource has been finalized). Distinct from Self::Internal, which is reserved for true library invariant violations the caller could not have triggered. Construct via Self::invalid_operation.

Column

Structured error for named-column access in row decoding. Used by FromRow impls and Row::try_get / Row::get_by_name to signal which column failed and why.

Fields

name: String

The column name.

kind: ColumnErrorKind

The structured cause of the column-access failure.

ColumnIndexOutOfBounds

Column index was out of bounds for the row. Used for positional access; named access uses Self::Column with ColumnErrorKind::Missing.

Fields

idx: usize

The requested 0-based column index.

column_count: usize

The actual column count of the row.

Internal

Internal invariant violation — a state the library believes should be unreachable. Callers cannot trigger this from the public API in well-formed code; reaching it indicates a bug inside hyperdb-api. Recovery is generally impossible beyond logging and bailing.

For caller-API misuse (e.g. mixing two mutually exclusive methods, using a finalized resource), prefer Self::InvalidOperation.

Construct via Self::internal.

Fields

message: String

Human-readable description of what invariant was violated.

Implementations

impl Error

pub fn internal(message: impl Into<String>) -> Self

Constructs an Self::Internal error. Prefer this over struct-expression syntax to remain source-compatible if new fields are added in a minor release.

pub fn connection(message: impl Into<String>) -> Self

Constructs an Self::Connection error with no underlying I/O source and no SQLSTATE. Prefer this over struct-expression syntax to remain source-compatible if new fields are added in a minor release.

pub fn connection_with_io(message: impl Into<String>, source: Error) -> Self

Constructs an Self::Connection error wrapping an underlying std::io::Error. Prefer this over struct-expression syntax to remain source-compatible if new fields are added in a minor release.

pub fn connection_with_sqlstate( message: impl Into<String>, sqlstate: impl Into<String>, ) -> Self

Constructs an Self::Connection error carrying a SQLSTATE code (typically 08* connection-class) and no I/O source.

pub fn server( sqlstate: Option<String>, message: impl Into<String>, detail: Option<String>, hint: Option<String>, ) -> Self

Constructs an Self::Server error. Prefer this over struct-expression syntax to remain source-compatible if new fields are added in a minor release.

pub fn column(name: impl Into<String>, kind: ColumnErrorKind) -> Self

Constructs an Self::Column error. Prefer this over struct-expression syntax to remain source-compatible if new fields are added in a minor release.

pub fn column_index_out_of_bounds(idx: usize, column_count: usize) -> Self

Constructs an Self::ColumnIndexOutOfBounds error. Prefer this over struct-expression syntax to remain source-compatible if new fields are added in a minor release.

pub fn authentication(message: impl Into<String>) -> Self

Constructs an Self::Authentication error.

pub fn tls(message: impl Into<String>) -> Self

Constructs an Self::Tls error.

pub fn protocol(message: impl Into<String>) -> Self

Constructs an Self::Protocol error.

pub fn closed(message: impl Into<String>) -> Self

Constructs an Self::Closed error with no SQLSTATE.

pub fn closed_with_sqlstate( message: impl Into<String>, sqlstate: impl Into<String>, ) -> Self

Constructs an Self::Closed error carrying a SQLSTATE code (typically 57P01 admin shutdown or 57P02 crash shutdown).

pub fn timeout(message: impl Into<String>) -> Self

Constructs an Self::Timeout error.

pub fn cancelled(message: impl Into<String>) -> Self

Constructs an Self::Cancelled error with no SQLSTATE.

pub fn cancelled_with_sqlstate( message: impl Into<String>, sqlstate: impl Into<String>, ) -> Self

Constructs an Self::Cancelled error carrying a SQLSTATE code (typically 57014 query_canceled).

pub fn conversion(message: impl Into<String>) -> Self

Constructs an Self::Conversion error.

pub fn config(message: impl Into<String>) -> Self

Constructs an Self::Config error.

pub fn feature_not_supported(message: impl Into<String>) -> Self

Constructs an Self::FeatureNotSupported error.

pub fn invalid_name(message: impl Into<String>) -> Self

Constructs an Self::InvalidName error.

pub fn invalid_table_definition(message: impl Into<String>) -> Self

Constructs an Self::InvalidTableDefinition error.

pub fn not_found(message: impl Into<String>) -> Self

Constructs an Self::NotFound error.

pub fn already_exists(message: impl Into<String>) -> Self

Constructs an Self::AlreadyExists error.

pub fn invalid_operation(message: impl Into<String>) -> Self

Constructs an Self::InvalidOperation error.

pub fn message(&self) -> String

Returns the error message in human-readable form. Equivalent to self.to_string().

pub fn sqlstate(&self) -> Option<&str>

Returns the PostgreSQL SQLSTATE code if this error carries one, otherwise None.

Returns Some(...) for Self::Server (Query-class codes), Self::Connection (typically 08*), Self::Closed (typically 57P0* shutdown codes), and Self::Cancelled (typically 57014 query_canceled) when the underlying server provided a code.

SQLSTATE codes are 5-character strings — see the PostgreSQL errcodes appendix.

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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 Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Infallible> for Error

fn from(_: Infallible) -> Self

Converts to this type from the input type.