Skip to main content

uqa_engine/
prepared.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7use super::Engine;
8use crate::transactions::prepared::PreparedOperation;
9use std::sync::{Arc, Weak};
10use uqa_sql::{ColumnType, RowSchema, SQLError, SQLParam, SQLResult};
11
12/// A session-owned prepared definition's identity. Removing and recreating its catalog name never rebinds this handle.
13pub struct PreparedStatement {
14    name: String,
15    source: Arc<uqa_sql::Statement>,
16    owner: Weak<crate::state::SessionContext>,
17    definition: Weak<uqa_sql::plan::UnifiedPlan>,
18}
19
20/// Preparation-time parameter and positional result descriptors.
21pub struct PreparedStatementDescription {
22    pub parameter_types: Vec<Option<ColumnType>>,
23    pub result_schema: Option<RowSchema>,
24}
25
26impl PreparedStatement {
27    fn matches(&self, engine: &Engine, entry: &super::PreparedStatementPlan) -> bool {
28        self.owner.ptr_eq(&Arc::downgrade(&engine.session))
29            && self.definition.ptr_eq(&Arc::downgrade(&entry.source_plan))
30    }
31
32    fn invalid(&self) -> SQLError {
33        uqa_sql::prepared::statement_error("26000", &self.name, "does not exist")
34    }
35}
36
37impl Engine {
38    /// Prepare native SQL with optional explicit parameter declarations. Definitions survive transaction rollback and are removed by finalize, DEALLOCATE or DISCARD ALL.
39    pub fn prepare_statement(
40        &self,
41        sql: &str,
42        declared: &[ColumnType],
43    ) -> Result<PreparedStatement, SQLError> {
44        self.with_prepared_registration(
45            |engine| {
46                uqa_execution::statement::prepared::parse_host_sql(
47                    sql,
48                    engine.parser_settings(),
49                    &engine.runtime.notices,
50                    &engine.runtime.cancellation,
51                )
52            },
53            |engine, source| {
54                let name = loop {
55                    let identity = engine
56                        .session
57                        .next_prepared_handle
58                        .fetch_update(
59                            std::sync::atomic::Ordering::Relaxed,
60                            std::sync::atomic::Ordering::Relaxed,
61                            |value| value.checked_add(1),
62                        )
63                        .map_err(|_| SQLError::Routine {
64                            sqlstate: "54000".into(),
65                            message: "prepared statement identity space exhausted".into(),
66                        })?;
67                    let name = format!("__uqa_prepared_{identity}");
68                    if !engine.session.prepared.read().contains_key(&name) {
69                        break name;
70                    }
71                };
72                uqa_execution::statement::prepared::register_host_statement(
73                    &engine.prepared_registration_context(),
74                    name.clone(),
75                    &source,
76                    sql,
77                    declared,
78                )?;
79                let registry = engine.session.prepared.read();
80                let entry = registry.get(&name).expect("published prepared definition");
81                Ok(PreparedStatement {
82                    name,
83                    source,
84                    owner: Arc::downgrade(&engine.session),
85                    definition: Arc::downgrade(&entry.source_plan),
86                })
87            },
88        )
89    }
90
91    pub fn validate_prepared_statement(
92        &self,
93        statement: &PreparedStatement,
94    ) -> Result<(), SQLError> {
95        let _gate = self.lock_statement_gate();
96        if self
97            .session
98            .prepared
99            .read()
100            .get(&statement.name)
101            .is_some_and(|entry| statement.matches(self, entry))
102        {
103            Ok(())
104        } else {
105            Err(statement.invalid())
106        }
107    }
108
109    pub fn describe_prepared_statement(
110        &self,
111        statement: &PreparedStatement,
112    ) -> Result<PreparedStatementDescription, SQLError> {
113        let _statement = self.lock_statement_gate();
114        let (_execution, nested) = crate::queries::SQLExecutionScope::enter(self);
115        self.run_prepared_operation(
116            || {
117                let registry = self.session.prepared.read();
118                let entry = registry
119                    .get(&statement.name)
120                    .filter(|entry| statement.matches(self, entry))
121                    .ok_or_else(|| statement.invalid())?;
122                Ok((
123                    PreparedOperation::Describe {
124                        returns_rows: entry.result_schema.is_some(),
125                        outermost: !nested,
126                        requires_analysis: uqa_sql::prepared::utility::requires_analysis(
127                            &entry.source_plan,
128                        ),
129                    },
130                    entry.clone(),
131                ))
132            },
133            |entry| {
134                if let Some(definition) =
135                    uqa_planner::statement_planning::prepared::selection::describe_entry(
136                        &self.prepared_definition_context(),
137                        &entry,
138                    )?
139                {
140                    let mut registry = self.session.prepared.write();
141                    let current = registry
142                        .get_mut(&statement.name)
143                        .filter(|current| statement.matches(self, current))
144                        .ok_or_else(|| statement.invalid())?;
145                    if Arc::ptr_eq(&current.logical_plan, &entry.logical_plan) {
146                        current.record_analysis(definition);
147                    }
148                }
149                Ok(PreparedStatementDescription {
150                    parameter_types: entry.parameter_types,
151                    result_schema: entry.result_schema,
152                })
153            },
154        )
155    }
156
157    pub fn execute_prepared_statement(
158        &self,
159        statement: &PreparedStatement,
160        params: &[SQLParam],
161    ) -> Result<SQLResult, SQLError> {
162        self.run_prepared_operation(
163            || {
164                let registry = self.session.prepared.read();
165                let entry = registry
166                    .get(&statement.name)
167                    .filter(|entry| statement.matches(self, entry))
168                    .ok_or_else(|| statement.invalid())?;
169                uqa_sql::prepared::validate_host_parameter_count(
170                    &statement.name,
171                    params.len(),
172                    entry.parameter_types.len(),
173                )?;
174                Ok((
175                    PreparedOperation::Bind {
176                        statement: Arc::clone(&statement.source),
177                        parameter_count: params.len(),
178                    },
179                    entry.source_sql.clone(),
180                ))
181            },
182            |sql| {
183                self.execute_compiled_prepared(
184                    &statement.name,
185                    Arc::clone(&statement.source),
186                    sql.as_deref(),
187                    params,
188                )
189            },
190        )
191    }
192
193    /// An invalidated handle is harmless to release and cannot remove a replacement definition.
194    pub fn finalize_prepared_statement(&self, statement: &PreparedStatement) {
195        let _gate = self.lock_statement_gate();
196        let mut registry = self.session.prepared.write();
197        if registry
198            .get(&statement.name)
199            .is_some_and(|entry| statement.matches(self, entry))
200        {
201            registry.remove(&statement.name);
202        }
203    }
204
205    pub fn register_prepared(
206        &self,
207        name: String,
208        definition: uqa_sql::ast::Statement,
209    ) -> Result<(), uqa_sql::SQLError> {
210        self.with_prepared_registration(
211            |_| Ok(Arc::new(definition)),
212            |engine, definition| {
213                uqa_execution::statement::prepared::register_statement(
214                    &engine.prepared_registration_context(),
215                    name,
216                    definition.as_ref().clone(),
217                )
218            },
219        )
220    }
221
222    pub(crate) fn prepared_parameter_types(
223        &self,
224        name: &str,
225    ) -> Option<Vec<Option<uqa_sql::ast::ColumnType>>> {
226        self.session
227            .prepared
228            .read()
229            .get(name)
230            .map(|entry| entry.parameter_types.clone())
231    }
232
233    pub fn lookup_prepared(&self, name: &str) -> Option<uqa_planner::UnifiedPlan> {
234        self.session
235            .prepared
236            .read()
237            .get(name)
238            .map(|entry| entry.plan.as_ref().unwrap_or(&entry.logical_plan).clone())
239    }
240
241    /// Invalidate executable plans without removing connection-owned definitions.
242    /// Catalog changes are checked when each statement is next executed, so a
243    /// dropped dependency cannot make unrelated commands or rollback fail.
244    pub(crate) fn invalidate_prepared_plans(&self) {
245        uqa_execution::statement::prepared::invalidation::invalidate_execution_plans_with_routines(
246            self.session.prepared.write().values_mut(),
247            &self.session.routine_bodies,
248        );
249    }
250
251    /// Read original input syntax again after a binding dependency changes.
252    pub(crate) fn invalidate_prepared_analysis(&self) {
253        uqa_execution::statement::prepared::invalidation::PreparedCatalogChange::GlobalCatalog
254            .invalidate_with_routines(
255                self.session.prepared.write().values_mut(),
256                &self.session.routine_bodies,
257            );
258    }
259
260    pub fn deallocate_prepared(&self, name: Option<&str>) {
261        let _gate = self.lock_statement_gate();
262        match name {
263            Some(name) => {
264                self.session.prepared.write().remove(name);
265            }
266            None => self.session.prepared.write().clear(),
267        }
268    }
269}