Skip to main content

chdb_rust/
error.rs

1//! Error types for chdb-rust.
2//!
3//! This module defines the error types used throughout the crate.
4
5use std::ffi::NulError;
6use std::string::FromUtf8Error;
7
8/// Errors that can occur when using chdb-rust.
9///
10/// This enum represents all possible errors that can be returned by the library.
11/// Most errors are self-explanatory, with `QueryError` containing the actual error
12/// message from the underlying chDB library.
13#[derive(Debug, thiserror::Error)]
14#[non_exhaustive]
15pub enum Error {
16    /// An unknown error has occurred.
17    #[error("An unknown error has occurred")]
18    Unknown,
19    /// No result was returned from the query.
20    #[error("No result")]
21    NoResult,
22    /// Failed to establish a connection to chDB.
23    #[error("Connection failed")]
24    ConnectionFailed,
25    /// The engine is already bound to a different data path.
26    ///
27    /// One engine per process serves one storage path. An in-memory connection
28    /// counts as a path of its own, since the engine binds `:memory:` when none
29    /// is given.
30    #[error(
31        "the engine is already open on {active}; chDB serves one data path per \
32         process, so {requested} cannot be opened until every connection to \
33         {active} is closed"
34    )]
35    PathConflict {
36        /// The path the engine is bound to.
37        active: String,
38        /// The path that was asked for.
39        requested: String,
40    },
41    /// Invalid data was encountered.
42    #[error("Invalid data: {0}")]
43    InvalidData(String),
44    /// Invalid path was provided.
45    #[error("Invalid path")]
46    PathError,
47    /// An I/O error occurred.
48    #[error(transparent)]
49    Io(#[from] std::io::Error),
50    /// A null byte was found in a string where it's not allowed.
51    #[error(transparent)]
52    Nul(#[from] NulError),
53    /// Insufficient permissions to access the directory.
54    #[error("Insufficient dir permissions")]
55    InsufficientPermissions,
56    /// The data contains invalid UTF-8 sequences.
57    #[error("Non UTF-8 sequence: {0}")]
58    NonUtf8Sequence(FromUtf8Error),
59    /// The result data is not valid UTF-8.
60    ///
61    /// Returned by [`QueryResult::data_str`](crate::query_result::QueryResult::data_str),
62    /// which checks the bytes in place rather than copying them first.
63    #[error("Invalid UTF-8 in result: {0}")]
64    InvalidUtf8(std::str::Utf8Error),
65    /// The linked library cannot report which chdb-core release it is.
66    ///
67    /// `chdb_version()` arrived in chdb-core v26.7.0; an older library does not
68    /// export it, so there is nothing to call. Deliberately not answered with
69    /// `SELECT version()`, which reports a ClickHouse version — a different
70    /// scheme, and so not a substitute.
71    #[error("the linked libchdb does not export chdb_version(); it predates chdb-core v26.7.0")]
72    EngineVersionUnavailable,
73    /// A durable-object operation failed.
74    ///
75    /// Carries the durable error whole, so its
76    /// [`Category`](crate::durable::Error::category) and the detail
77    /// accessors survive the conversion — a caller can still branch on the
78    /// specifics after the error has crossed into a crate-level [`Result`].
79    ///
80    /// This exists so a function returning [`Result`] can apply `?` to a
81    /// durable call directly, instead of mapping the error by hand.
82    #[cfg(all(feature = "durable", has_durable_abi))]
83    #[error(transparent)]
84    Durable(#[from] crate::durable::Error),
85
86    /// A chDB call reported failure without saying why.
87    ///
88    /// `call` names the C function, so the two cases this covers — a shutdown
89    /// that could not stop every engine thread, and an insert-stream append
90    /// that failed with no error recorded on the stream — can be told apart.
91    #[error("{call} failed without reporting a reason")]
92    EngineCallFailed {
93        /// The chDB C function that failed.
94        call: &'static str,
95    },
96
97    /// A query execution error occurred.
98    ///
99    /// This contains the error message from the underlying chDB library,
100    /// which typically includes details about SQL syntax errors, missing tables, etc.
101    #[error("{0}")]
102    QueryError(String),
103    /// Shutdown was asked for while connections were still open.
104    ///
105    /// The engine refuses this rather than tearing itself down under a live
106    /// connection. Close every connection and drop every result first.
107    #[error(
108        "the engine cannot be shut down while {count} connection(s) are open; \
109         drop them first"
110    )]
111    ConnectionsStillOpen {
112        /// How many connection handles are still holding the engine.
113        count: usize,
114    },
115    /// The engine was shut down earlier in this process.
116    ///
117    /// [`runtime::shutdown`](crate::runtime::shutdown) is one-way: once it
118    /// succeeds the library is closed for business for the rest of the process.
119    #[error("the engine was shut down; a new connection cannot be opened in this process")]
120    EngineShutDown,
121}
122
123/// A type alias for `Result<T, Error>`.
124///
125/// This is the standard result type used throughout the crate.
126pub type Result<T, Err = Error> = std::result::Result<T, Err>;
127
128#[cfg(test)]
129mod tests {
130    use super::Error;
131
132    #[test]
133    fn engine_call_failed_names_the_call() {
134        let err = Error::EngineCallFailed {
135            call: "chdb_shutdown",
136        };
137        assert_eq!(
138            err.to_string(),
139            "chdb_shutdown failed without reporting a reason"
140        );
141    }
142}