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}