nodedb_sql/
error.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! Error types for the nodedb-sql crate.
4
5/// Errors produced during SQL parsing, resolution, or planning.
6#[derive(Debug, PartialEq, thiserror::Error)]
7pub enum SqlError {
8    #[error("parse error: {detail}")]
9    Parse { detail: String },
10
11    #[error("table not found: {name}")]
12    UnknownTable { name: String },
13
14    #[error("unknown column '{column}' in table '{table}'")]
15    UnknownColumn { table: String, column: String },
16
17    #[error("ambiguous column '{column}' — qualify with table name")]
18    AmbiguousColumn { column: String },
19
20    #[error("type mismatch: {detail}")]
21    TypeMismatch { detail: String },
22
23    #[error("unsupported: {detail}")]
24    Unsupported { detail: String },
25
26    #[error("invalid function call: {detail}")]
27    InvalidFunction { detail: String },
28
29    #[error("invalid window frame: {detail}")]
30    InvalidWindowFrame { detail: String },
31
32    #[error("missing required field '{field}' for {context}")]
33    MissingField { field: String, context: String },
34
35    /// A descriptor the planner depends on is being drained by
36    /// an in-flight DDL. Callers (pgwire handlers) should retry
37    /// the whole statement after a short backoff. Propagated
38    /// from `SqlCatalogError::RetryableSchemaChanged`.
39    #[error("retryable schema change on {descriptor}")]
40    RetryableSchemaChanged { descriptor: String },
41
42    /// Identifier is a NodeDB reserved keyword. Use a quoted identifier to bypass.
43    #[error(
44        "identifier '{name}' is reserved by NodeDB ({reason}); \
45         use a quoted identifier (e.g., \"{name}\") to bypass"
46    )]
47    ReservedIdentifier { name: String, reason: &'static str },
48
49    /// An unsupported SQL constraint was used in a DDL statement.
50    ///
51    /// Rendered as SQLSTATE `0A000` (feature_not_supported). The `feature` field
52    /// names the constraint keyword and `hint` points to the NodeDB equivalent.
53    #[error("unsupported constraint: {feature}; {hint}")]
54    UnsupportedConstraint { feature: String, hint: String },
55
56    /// Both a `WITH (engine='...')` clause and a trailing `ENGINE = ...`
57    /// suffix were given on the same `CREATE COLLECTION` / `CREATE TABLE`
58    /// statement, naming different engines.
59    ///
60    /// Rendered as SQLSTATE `0A000` (feature_not_supported), matching the
61    /// existing duplicate-axis rejection precedent for `WITH (profile=...)`.
62    #[error(
63        "conflicting engine selection: WITH (engine='{with_engine}') and \
64         ENGINE = {suffix_engine} name different engines; only one engine-selection \
65         clause is allowed"
66    )]
67    ConflictingEngineClause {
68        with_engine: String,
69        suffix_engine: String,
70    },
71
72    /// WITH RECURSIVE used a set operator other than UNION or UNION ALL.
73    ///
74    /// Only `UNION` and `UNION ALL` are permitted in the recursive term of a
75    /// `WITH RECURSIVE` CTE. `INTERSECT` and `EXCEPT` are rejected because
76    /// they cannot guarantee termination in standard iterative evaluation.
77    #[error(
78        "WITH RECURSIVE: only UNION / UNION ALL are allowed in the recursive term; \
79         {op} is not permitted"
80    )]
81    InvalidRecursiveSetOp { op: String },
82
83    /// The recursive self-reference is absent, appears more than once, or
84    /// appears inside a subquery, aggregate, or the nullable side of an outer join.
85    #[error("WITH RECURSIVE: invalid self-reference to '{cte_name}' in recursive term: {reason}")]
86    InvalidRecursiveSelfRef { cte_name: String, reason: String },
87
88    /// The anchor SELECT produces a different number of columns than the
89    /// column list declared on the CTE (or the recursive arm).
90    #[error(
91        "WITH RECURSIVE CTE '{cte_name}': anchor produces {anchor_cols} column(s) \
92         but {declared_cols} were declared"
93    )]
94    RecursiveColumnMismatch {
95        cte_name: String,
96        anchor_cols: usize,
97        declared_cols: usize,
98    },
99
100    /// The recursive CTE exceeded the configured `max_recursion_depth`.
101    ///
102    /// This is a runtime error produced by the executor, not the planner.
103    #[error(
104        "WITH RECURSIVE CTE '{cte_name}' exceeded max recursion depth {max_depth}; \
105         add a stricter termination condition or raise max_recursion_depth"
106    )]
107    RecursionDepthExceeded { cte_name: String, max_depth: usize },
108
109    /// Collection is soft-deleted (within retention window).
110    /// Propagated from `SqlCatalogError::CollectionDeactivated`;
111    /// the pgwire layer renders this as sqlstate 42P01 with an
112    /// `UNDROP COLLECTION <name>` hint in the message.
113    #[error(
114        "collection '{name}' was dropped; \
115         restore with `{undrop_hint}` before retention elapses \
116         at {retention_expires_at_ns} ns"
117    )]
118    CollectionDeactivated {
119        name: String,
120        retention_expires_at_ns: u64,
121        undrop_hint: String,
122    },
123}
124
125impl From<crate::catalog::SqlCatalogError> for SqlError {
126    fn from(e: crate::catalog::SqlCatalogError) -> Self {
127        match e {
128            crate::catalog::SqlCatalogError::RetryableSchemaChanged { descriptor } => {
129                Self::RetryableSchemaChanged { descriptor }
130            }
131            crate::catalog::SqlCatalogError::CollectionDeactivated {
132                name,
133                retention_expires_at_ns,
134            } => {
135                let undrop_hint = format!("UNDROP COLLECTION {name}");
136                Self::CollectionDeactivated {
137                    name,
138                    retention_expires_at_ns,
139                    undrop_hint,
140                }
141            }
142        }
143    }
144}
145
146impl From<nodedb_query::expr_parse::ExprParseError> for SqlError {
147    fn from(e: nodedb_query::expr_parse::ExprParseError) -> Self {
148        Self::Parse {
149            detail: e.to_string(),
150        }
151    }
152}
153
154impl From<sqlparser::parser::ParserError> for SqlError {
155    fn from(e: sqlparser::parser::ParserError) -> Self {
156        Self::Parse {
157            detail: e.to_string(),
158        }
159    }
160}
161
162pub type Result<T> = std::result::Result<T, SqlError>;
nodedb_sql/error.rs

nodedb_sql/
error.rs
