sqlx_core_oldapi/

error.rs

//! Types for working with errors produced by SQLx.

use std::any::type_name;
use std::borrow::Cow;
use std::error::Error as StdError;
use std::fmt::Display;
use std::io;
use std::result::Result as StdResult;

use crate::database::Database;
use crate::type_info::TypeInfo;
use crate::types::Type;

/// A specialized `Result` type for SQLx.
pub type Result<T> = StdResult<T, Error>;

// Convenience type alias for usage within SQLx.
// Do not make this type public.
pub type BoxDynError = Box<dyn StdError + 'static + Send + Sync>;

/// An unexpected `NULL` was encountered during decoding.
///
/// Returned from [`Row::get`](crate::row::Row::get) if the value from the database is `NULL`,
/// and you are not decoding into an `Option`.
#[derive(thiserror::Error, Debug)]
#[error("unexpected null; try decoding as an `Option`")]
pub struct UnexpectedNullError;

/// Error indicating that a Rust type is not compatible with a SQL type.
#[derive(thiserror::Error, Debug)]
#[error("mismatched types; Rust type `{rust_type}` (as SQL type `{rust_sql_type}`) could not be decoded into SQL type `{sql_type}`")]
pub struct MismatchedTypeError {
    /// The name of the Rust type.
    pub rust_type: String,
    /// The SQL type name that the Rust type would map to.
    pub rust_sql_type: String,
    /// The actual SQL type from the database.
    pub sql_type: String,
    /// Optional source error that caused the mismatch.
    #[source]
    pub source: Option<BoxDynError>,
}

fn rust_sql_type<DB: Database, T: Type<DB>>() -> String {
    if is_any_db::<DB>() {
        return "<unknown>".to_string();
    }

    T::type_info().name().to_string()
}

#[cfg(all(
    feature = "any",
    any(
        feature = "postgres",
        feature = "mysql",
        feature = "mssql",
        feature = "sqlite",
        feature = "odbc"
    )
))]
fn is_any_db<DB: Database>() -> bool {
    std::any::TypeId::of::<DB>() == std::any::TypeId::of::<crate::any::Any>()
}

#[cfg(not(all(
    feature = "any",
    any(
        feature = "postgres",
        feature = "mysql",
        feature = "mssql",
        feature = "sqlite",
        feature = "odbc"
    )
)))]
fn is_any_db<DB: Database>() -> bool {
    let _ = std::any::TypeId::of::<DB>();
    false
}

impl MismatchedTypeError {
    /// Create a new mismatched type error without a source.
    pub fn new<DB: Database, T: Type<DB>>(ty: &DB::TypeInfo) -> Self {
        Self {
            rust_type: type_name::<T>().to_string(),
            rust_sql_type: rust_sql_type::<DB, T>(),
            sql_type: ty.name().to_string(),
            source: None,
        }
    }

    /// Create a new mismatched type error with a source error.
    pub fn with_source<DB: Database, T: Type<DB>>(ty: &DB::TypeInfo, source: BoxDynError) -> Self {
        Self {
            rust_type: type_name::<T>().to_string(),
            rust_sql_type: rust_sql_type::<DB, T>(),
            sql_type: ty.name().to_string(),
            source: Some(source),
        }
    }
}

/// Represents all the ways a method can fail within SQLx.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// Error occurred while parsing a connection string.
    #[error("error with configuration: {0}")]
    Configuration(#[source] BoxDynError),

    /// Error returned from the database.
    #[error("error returned from database: {0}")]
    Database(#[source] Box<dyn DatabaseError>),

    /// Error communicating with the database backend.
    #[error("error communicating with database: {0}")]
    Io(#[from] io::Error),

    /// Error occurred while attempting to establish a TLS connection.
    #[error("error occurred while attempting to establish a TLS connection: {0}")]
    Tls(#[source] BoxDynError),

    /// Unexpected or invalid data encountered while communicating with the database.
    ///
    /// This should indicate there is a programming error in a SQLx driver or there
    /// is something corrupted with the connection to the database itself.
    #[error("encountered unexpected or invalid data: {0}")]
    Protocol(String),

    /// No rows returned by a query that expected to return at least one row.
    #[error("no rows returned by a query that expected to return at least one row")]
    RowNotFound,

    /// Type in query doesn't exist. Likely due to typo or missing user type.
    #[error("type named {type_name} not found")]
    TypeNotFound { type_name: String },

    /// Column index was out of bounds.
    #[error("column index out of bounds: the len is {len}, but the index is {index}")]
    ColumnIndexOutOfBounds { index: usize, len: usize },

    /// No column found for the given name.
    #[error("no column found for name: {0}")]
    ColumnNotFound(String),

    /// Error occurred while decoding a value from a specific column.
    #[error("error occurred while decoding column {index}: {source}")]
    ColumnDecode {
        index: String,

        #[source]
        source: BoxDynError,
    },

    /// Error occurred while decoding a value.
    #[error("error occurred while decoding: {0}")]
    Decode(#[source] BoxDynError),

    /// A [`Pool::acquire`] timed out due to connections not becoming available or
    /// because another task encountered too many errors while trying to open a new connection.
    ///
    /// [`Pool::acquire`]: crate::pool::Pool::acquire
    #[error("pool timed out while waiting for an open connection")]
    PoolTimedOut,

    /// [`Pool::close`] was called while we were waiting in [`Pool::acquire`].
    ///
    /// [`Pool::acquire`]: crate::pool::Pool::acquire
    /// [`Pool::close`]: crate::pool::Pool::close
    #[error("attempted to acquire a connection on a closed pool")]
    PoolClosed,

    /// A background worker has crashed.
    #[error("attempted to communicate with a crashed background worker")]
    WorkerCrashed,

    #[cfg(feature = "migrate")]
    #[error("{0}")]
    Migrate(#[source] Box<crate::migrate::MigrateError>),

    #[error("integer overflow while converting to target type")]
    IntegerOverflow(#[source] std::num::TryFromIntError),
}

impl StdError for Box<dyn DatabaseError> {}

impl Error {
    pub fn into_database_error(self) -> Option<Box<dyn DatabaseError + 'static>> {
        match self {
            Error::Database(err) => Some(err),
            _ => None,
        }
    }

    pub fn as_database_error(&self) -> Option<&(dyn DatabaseError + 'static)> {
        match self {
            Error::Database(err) => Some(&**err),
            _ => None,
        }
    }

    #[allow(dead_code)]
    #[inline]
    pub(crate) fn protocol(err: impl Display) -> Self {
        Error::Protocol(err.to_string())
    }

    #[allow(dead_code)]
    #[inline]
    pub(crate) fn config(err: impl StdError + Send + Sync + 'static) -> Self {
        Error::Configuration(err.into())
    }

    #[allow(dead_code)]
    #[inline]
    pub(crate) fn tls<T: Into<BoxDynError>>(err: T) -> Self {
        Error::Tls(err.into())
    }
}

pub(crate) fn mismatched_types<DB: Database, T: Type<DB>>(ty: &DB::TypeInfo) -> BoxDynError {
    let rust_sql_type = rust_sql_type::<DB, T>();
    Box::new(MismatchedTypeError {
        rust_type: format!(
            "{} ({}compatible with SQL type `{}`)",
            type_name::<T>(),
            if T::compatible(ty) { "" } else { "in" },
            rust_sql_type
        ),
        rust_sql_type,
        sql_type: ty.name().to_string(),
        source: None,
    })
}

#[cfg(all(test, feature = "any", feature = "postgres"))]
mod tests {
    use crate::any::Any;
    use crate::error::mismatched_types;
    use crate::postgres::PgTypeInfo;

    #[test]
    fn mismatched_types_any_does_not_panic() {
        let ty = crate::any::AnyTypeInfo::from(PgTypeInfo::with_name("TEXT"));
        assert!(std::panic::catch_unwind(|| mismatched_types::<Any, i32>(&ty)).is_ok());
    }
}

/// An error that was returned from the database.
pub trait DatabaseError: 'static + Send + Sync + StdError {
    /// The primary, human-readable error message.
    fn message(&self) -> &str;

    /// The (SQLSTATE) code for the error.
    fn code(&self) -> Option<Cow<'_, str>> {
        None
    }

    /// The byte offset in the query string where the error occurred, if applicable
    fn offset(&self) -> Option<usize> {
        None
    }

    #[doc(hidden)]
    fn as_error(&self) -> &(dyn StdError + Send + Sync + 'static);

    #[doc(hidden)]
    fn as_error_mut(&mut self) -> &mut (dyn StdError + Send + Sync + 'static);

    #[doc(hidden)]
    fn into_error(self: Box<Self>) -> Box<dyn StdError + Send + Sync + 'static>;

    #[doc(hidden)]
    fn is_transient_in_connect_phase(&self) -> bool {
        false
    }

    /// Returns the name of the constraint that triggered the error, if applicable.
    /// If the error was caused by a conflict of a unique index, this will be the index name.
    ///
    /// ### Note
    /// Currently only populated by the Postgres driver.
    fn constraint(&self) -> Option<&str> {
        None
    }
}

impl dyn DatabaseError {
    /// Downcast a reference to this generic database error to a specific
    /// database error type.
    ///
    /// # Panics
    ///
    /// Panics if the database error type is not `E`. This is a deliberate contrast from
    /// `Error::downcast_ref` which returns `Option<&E>`. In normal usage, you should know the
    /// specific error type. In other cases, use `try_downcast_ref`.
    pub fn downcast_ref<E: DatabaseError>(&self) -> &E {
        self.try_downcast_ref().unwrap_or_else(|| {
            panic!(
                "downcast to wrong DatabaseError type; original error: {}",
                self
            )
        })
    }

    /// Downcast this generic database error to a specific database error type.
    ///
    /// # Panics
    ///
    /// Panics if the database error type is not `E`. This is a deliberate contrast from
    /// `Error::downcast` which returns `Option<E>`. In normal usage, you should know the
    /// specific error type. In other cases, use `try_downcast`.
    pub fn downcast<E: DatabaseError>(self: Box<Self>) -> Box<E> {
        self.try_downcast().unwrap_or_else(|e| {
            panic!(
                "downcast to wrong DatabaseError type; original error: {}",
                e
            )
        })
    }

    /// Downcast a reference to this generic database error to a specific
    /// database error type.
    #[inline]
    pub fn try_downcast_ref<E: DatabaseError>(&self) -> Option<&E> {
        self.as_error().downcast_ref()
    }

    /// Downcast this generic database error to a specific database error type.
    #[inline]
    pub fn try_downcast<E: DatabaseError>(self: Box<Self>) -> StdResult<Box<E>, Box<Self>> {
        if self.as_error().is::<E>() {
            Ok(self.into_error().downcast().unwrap())
        } else {
            Err(self)
        }
    }
}

impl<E> From<E> for Error
where
    E: DatabaseError,
{
    #[inline]
    fn from(error: E) -> Self {
        Error::Database(Box::new(error))
    }
}

#[cfg(feature = "migrate")]
impl From<crate::migrate::MigrateError> for Error {
    #[inline]
    fn from(error: crate::migrate::MigrateError) -> Self {
        Error::Migrate(Box::new(error))
    }
}

#[cfg(feature = "_tls-native-tls")]
impl From<sqlx_rt::native_tls::Error> for Error {
    #[inline]
    fn from(error: sqlx_rt::native_tls::Error) -> Self {
        Error::Tls(Box::new(error))
    }
}

// Format an error message as a `Protocol` error
macro_rules! err_protocol {
    ($expr:expr) => {
        $crate::error::Error::Protocol($expr.into())
    };

    ($fmt:expr, $($arg:tt)*) => {
        $crate::error::Error::Protocol(format!($fmt, $($arg)*))
    };
}