sqlx_build_trust_core/
error.rs

1//! Types for working with errors produced by SQLx.
2
3use std::any::type_name;
4use std::borrow::Cow;
5use std::error::Error as StdError;
6use std::fmt::Display;
7use std::io;
8
9use crate::database::Database;
10
11use crate::type_info::TypeInfo;
12use crate::types::Type;
13
14/// A specialized `Result` type for SQLx.
15pub type Result<T, E = Error> = ::std::result::Result<T, E>;
16
17// Convenience type alias for usage within SQLx.
18// Do not make this type public.
19pub type BoxDynError = Box<dyn StdError + 'static + Send + Sync>;
20
21/// An unexpected `NULL` was encountered during decoding.
22///
23/// Returned from [`Row::get`](crate::row::Row::get) if the value from the database is `NULL`,
24/// and you are not decoding into an `Option`.
25#[derive(thiserror::Error, Debug)]
26#[error("unexpected null; try decoding as an `Option`")]
27pub struct UnexpectedNullError;
28
29/// Represents all the ways a method can fail within SQLx.
30#[derive(Debug, thiserror::Error)]
31#[non_exhaustive]
32pub enum Error {
33    /// Error occurred while parsing a connection string.
34    #[error("error with configuration: {0}")]
35    Configuration(#[source] BoxDynError),
36
37    /// Error returned from the database.
38    #[error("error returned from database: {0}")]
39    Database(#[source] Box<dyn DatabaseError>),
40
41    /// Error communicating with the database backend.
42    #[error("error communicating with database: {0}")]
43    Io(#[from] io::Error),
44
45    /// Error occurred while attempting to establish a TLS connection.
46    #[error("error occurred while attempting to establish a TLS connection: {0}")]
47    Tls(#[source] BoxDynError),
48
49    /// Unexpected or invalid data encountered while communicating with the database.
50    ///
51    /// This should indicate there is a programming error in a SQLx driver or there
52    /// is something corrupted with the connection to the database itself.
53    #[error("encountered unexpected or invalid data: {0}")]
54    Protocol(String),
55
56    /// No rows returned by a query that expected to return at least one row.
57    #[error("no rows returned by a query that expected to return at least one row")]
58    RowNotFound,
59
60    /// Type in query doesn't exist. Likely due to typo or missing user type.
61    #[error("type named {type_name} not found")]
62    TypeNotFound { type_name: String },
63
64    /// Column index was out of bounds.
65    #[error("column index out of bounds: the len is {len}, but the index is {index}")]
66    ColumnIndexOutOfBounds { index: usize, len: usize },
67
68    /// No column found for the given name.
69    #[error("no column found for name: {0}")]
70    ColumnNotFound(String),
71
72    /// Error occurred while decoding a value from a specific column.
73    #[error("error occurred while decoding column {index}: {source}")]
74    ColumnDecode {
75        index: String,
76
77        #[source]
78        source: BoxDynError,
79    },
80
81    /// Error occurred while decoding a value.
82    #[error("error occurred while decoding: {0}")]
83    Decode(#[source] BoxDynError),
84
85    /// Error occurred within the `Any` driver mapping to/from the native driver.
86    #[error("error in Any driver mapping: {0}")]
87    AnyDriverError(#[source] BoxDynError),
88
89    /// A [`Pool::acquire`] timed out due to connections not becoming available or
90    /// because another task encountered too many errors while trying to open a new connection.
91    ///
92    /// [`Pool::acquire`]: crate::pool::Pool::acquire
93    #[error("pool timed out while waiting for an open connection")]
94    PoolTimedOut,
95
96    /// [`Pool::close`] was called while we were waiting in [`Pool::acquire`].
97    ///
98    /// [`Pool::acquire`]: crate::pool::Pool::acquire
99    /// [`Pool::close`]: crate::pool::Pool::close
100    #[error("attempted to acquire a connection on a closed pool")]
101    PoolClosed,
102
103    /// A background worker has crashed.
104    #[error("attempted to communicate with a crashed background worker")]
105    WorkerCrashed,
106
107    #[cfg(feature = "migrate")]
108    #[error("{0}")]
109    Migrate(#[source] Box<crate::migrate::MigrateError>),
110}
111
112impl StdError for Box<dyn DatabaseError> {}
113
114impl Error {
115    pub fn into_database_error(self) -> Option<Box<dyn DatabaseError + 'static>> {
116        match self {
117            Error::Database(err) => Some(err),
118            _ => None,
119        }
120    }
121
122    pub fn as_database_error(&self) -> Option<&(dyn DatabaseError + 'static)> {
123        match self {
124            Error::Database(err) => Some(&**err),
125            _ => None,
126        }
127    }
128
129    #[doc(hidden)]
130    #[inline]
131    pub fn protocol(err: impl Display) -> Self {
132        Error::Protocol(err.to_string())
133    }
134
135    #[doc(hidden)]
136    #[inline]
137    pub fn config(err: impl StdError + Send + Sync + 'static) -> Self {
138        Error::Configuration(err.into())
139    }
140
141    pub(crate) fn tls(err: impl Into<Box<dyn StdError + Send + Sync + 'static>>) -> Self {
142        Error::Tls(err.into())
143    }
144
145    #[doc(hidden)]
146    #[inline]
147    pub fn decode(err: impl Into<Box<dyn StdError + Send + Sync + 'static>>) -> Self {
148        Error::Decode(err.into())
149    }
150}
151
152pub fn mismatched_types<DB: Database, T: Type<DB>>(ty: &DB::TypeInfo) -> BoxDynError {
153    // TODO: `#name` only produces `TINYINT` but perhaps we want to show `TINYINT(1)`
154    format!(
155        "mismatched types; Rust type `{}` (as SQL type `{}`) is not compatible with SQL type `{}`",
156        type_name::<T>(),
157        T::type_info().name(),
158        ty.name()
159    )
160    .into()
161}
162
163/// The error kind.
164///
165/// This enum is to be used to identify frequent errors that can be handled by the program.
166/// Although it currently only supports constraint violations, the type may grow in the future.
167#[derive(Debug, PartialEq, Eq)]
168#[non_exhaustive]
169pub enum ErrorKind {
170    /// Unique/primary key constraint violation.
171    UniqueViolation,
172    /// Foreign key constraint violation.
173    ForeignKeyViolation,
174    /// Not-null constraint violation.
175    NotNullViolation,
176    /// Check constraint violation.
177    CheckViolation,
178    /// An unmapped error.
179    Other,
180}
181
182/// An error that was returned from the database.
183pub trait DatabaseError: 'static + Send + Sync + StdError {
184    /// The primary, human-readable error message.
185    fn message(&self) -> &str;
186
187    /// The (SQLSTATE) code for the error.
188    fn code(&self) -> Option<Cow<'_, str>> {
189        None
190    }
191
192    #[doc(hidden)]
193    fn as_error(&self) -> &(dyn StdError + Send + Sync + 'static);
194
195    #[doc(hidden)]
196    fn as_error_mut(&mut self) -> &mut (dyn StdError + Send + Sync + 'static);
197
198    #[doc(hidden)]
199    fn into_error(self: Box<Self>) -> Box<dyn StdError + Send + Sync + 'static>;
200
201    #[doc(hidden)]
202    fn is_transient_in_connect_phase(&self) -> bool {
203        false
204    }
205
206    /// Returns the name of the constraint that triggered the error, if applicable.
207    /// If the error was caused by a conflict of a unique index, this will be the index name.
208    ///
209    /// ### Note
210    /// Currently only populated by the Postgres driver.
211    fn constraint(&self) -> Option<&str> {
212        None
213    }
214
215    /// Returns the name of the table that was affected by the error, if applicable.
216    ///
217    /// ### Note
218    /// Currently only populated by the Postgres driver.
219    fn table(&self) -> Option<&str> {
220        None
221    }
222
223    /// Returns the kind of the error, if supported.
224    ///
225    /// ### Note
226    /// Not all back-ends behave the same when reporting the error code.
227    fn kind(&self) -> ErrorKind;
228
229    /// Returns whether the error kind is a violation of a unique/primary key constraint.
230    fn is_unique_violation(&self) -> bool {
231        matches!(self.kind(), ErrorKind::UniqueViolation)
232    }
233
234    /// Returns whether the error kind is a violation of a foreign key.
235    fn is_foreign_key_violation(&self) -> bool {
236        matches!(self.kind(), ErrorKind::ForeignKeyViolation)
237    }
238
239    /// Returns whether the error kind is a violation of a check.
240    fn is_check_violation(&self) -> bool {
241        matches!(self.kind(), ErrorKind::CheckViolation)
242    }
243}
244
245impl dyn DatabaseError {
246    /// Downcast a reference to this generic database error to a specific
247    /// database error type.
248    ///
249    /// # Panics
250    ///
251    /// Panics if the database error type is not `E`. This is a deliberate contrast from
252    /// `Error::downcast_ref` which returns `Option<&E>`. In normal usage, you should know the
253    /// specific error type. In other cases, use `try_downcast_ref`.
254    pub fn downcast_ref<E: DatabaseError>(&self) -> &E {
255        self.try_downcast_ref().unwrap_or_else(|| {
256            panic!("downcast to wrong DatabaseError type; original error: {self}")
257        })
258    }
259
260    /// Downcast this generic database error to a specific database error type.
261    ///
262    /// # Panics
263    ///
264    /// Panics if the database error type is not `E`. This is a deliberate contrast from
265    /// `Error::downcast` which returns `Option<E>`. In normal usage, you should know the
266    /// specific error type. In other cases, use `try_downcast`.
267    pub fn downcast<E: DatabaseError>(self: Box<Self>) -> Box<E> {
268        self.try_downcast()
269            .unwrap_or_else(|e| panic!("downcast to wrong DatabaseError type; original error: {e}"))
270    }
271
272    /// Downcast a reference to this generic database error to a specific
273    /// database error type.
274    #[inline]
275    pub fn try_downcast_ref<E: DatabaseError>(&self) -> Option<&E> {
276        self.as_error().downcast_ref()
277    }
278
279    /// Downcast this generic database error to a specific database error type.
280    #[inline]
281    pub fn try_downcast<E: DatabaseError>(self: Box<Self>) -> Result<Box<E>, Box<Self>> {
282        if self.as_error().is::<E>() {
283            Ok(self.into_error().downcast().unwrap())
284        } else {
285            Err(self)
286        }
287    }
288}
289
290impl<E> From<E> for Error
291where
292    E: DatabaseError,
293{
294    #[inline]
295    fn from(error: E) -> Self {
296        Error::Database(Box::new(error))
297    }
298}
299
300#[cfg(feature = "migrate")]
301impl From<crate::migrate::MigrateError> for Error {
302    #[inline]
303    fn from(error: crate::migrate::MigrateError) -> Self {
304        Error::Migrate(Box::new(error))
305    }
306}
307
308/// Format an error message as a `Protocol` error
309#[macro_export]
310macro_rules! err_protocol {
311    ($expr:expr) => {
312        $crate::error::Error::Protocol($expr.into())
313    };
314
315    ($fmt:expr, $($arg:tt)*) => {
316        $crate::error::Error::Protocol(format!($fmt, $($arg)*))
317    };
318}
sqlx_build_trust_core/error.rs

sqlx_build_trust_core/
error.rs
