Skip to main content

uqa_engine/
sequences.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7use super::{
8    BTreeMap, Engine, RelationIdentity, SQLError, SequenceDataType, SequenceRestart, SequenceState,
9    StorageBackendError, StorageBackendResult,
10};
11
12impl Engine {
13    /// Resolve a sequence reference at DDL binding time using the current
14    /// `search_path`. Persisted expressions must store the returned canonical
15    /// relation name so later session state cannot change their target.
16    pub(crate) fn resolve_sequence_reference_for_binding(
17        &self,
18        reference: &str,
19    ) -> StorageBackendResult<String> {
20        self.try_resolve_sequence_name(reference)?.ok_or_else(|| {
21            StorageBackendError::Other(format!("Sequence `{reference}` does not exist"))
22        })
23    }
24
25    /// Bind a session portal to the sequence's stable `regclass` carrier so a later rename or schema move cannot retarget or break the cursor.
26    pub(crate) fn try_resolve_sequence_oid_reference_for_binding(
27        &self,
28        reference: &str,
29    ) -> StorageBackendResult<Option<String>> {
30        let Some(canonical) = self.try_resolve_sequence_name(reference)? else {
31            return Ok(None);
32        };
33        let relation = Self::resolved_relation_identity(&canonical)?;
34        let object_id = self
35            .durable
36            .sequence_object_ids
37            .read()
38            .get(&relation)
39            .copied()
40            .ok_or_else(|| {
41                StorageBackendError::Other(format!(
42                    "sequence `{canonical}` has no durable object identity"
43                ))
44            })?;
45        Ok(Some(
46            uqa_execution::catalog::sequence::catalog_oids::sequence_catalog_oid(
47                &self.durable.sequence_catalog_oids.read(),
48                &object_id,
49            )
50            .to_string(),
51        ))
52    }
53
54    /// Resolve a reference read from persisted metadata against the loaded registry without using the current session's `search_path`. An unqualified local name is safe only when exactly one catalog sequence has that name.
55    pub(crate) fn resolve_stored_sequence_reference_from_loaded_registry(
56        &self,
57        reference: &str,
58    ) -> StorageBackendResult<String> {
59        uqa_sql::schema::sequences::names::resolve_stored_sequence_reference(self, reference)
60            .map_err(StorageBackendError::Other)
61    }
62
63    pub fn create_sequence(
64        &self,
65        name: &str,
66        start: i64,
67        increment: i64,
68        if_not_exists: bool,
69    ) -> Result<bool, String> {
70        self.with_implicit_string_transaction(|engine| {
71            uqa_execution::schema::sequences::creation::create_sequence(
72                &engine.sequence_creation_context(),
73                name,
74                SequenceState::initial(start, increment, SequenceDataType::BigInt),
75                if_not_exists,
76                uqa_sql::ast::RelationPersistence::Permanent,
77                &uqa_sql::ast::SequenceOwnership::Unchanged,
78            )
79            .map_err(|error| error.to_string())
80        })
81    }
82
83    pub(crate) fn create_implicit_sequence_with_persistence(
84        &self,
85        name: &str,
86        state: SequenceState,
87        persistence: uqa_sql::ast::RelationPersistence,
88    ) -> Result<(), SQLError> {
89        self.with_implicit_transaction(|engine| {
90            uqa_execution::schema::sequences::creation::create_sequence(
91                &engine.sequence_creation_context(),
92                name,
93                state,
94                false,
95                persistence,
96                &uqa_sql::ast::SequenceOwnership::Unchanged,
97            )?;
98            Ok(())
99        })
100    }
101
102    /// Compatibility wrapper for the original direct API. SQL lowering and
103    /// all internal execution use [`SequenceRestart`] instead.
104    #[allow(clippy::option_option)]
105    pub fn alter_sequence(
106        &self,
107        name: &str,
108        restart: Option<Option<i64>>,
109        increment: Option<i64>,
110        start: Option<i64>,
111    ) -> Result<(), String> {
112        let restart = match restart {
113            None => SequenceRestart::Unchanged,
114            Some(None) => SequenceRestart::FromStart,
115            Some(Some(value)) => SequenceRestart::With(value),
116        };
117        let alter = uqa_sql::ast::AlterSequence {
118            name: name.into(),
119            restart,
120            increment,
121            start,
122            ..Default::default()
123        };
124        self.with_implicit_string_transaction(|engine| {
125            engine
126                .alter_sequence_inner(&alter)
127                .map(|_| ())
128                .map_err(|error| error.to_string())
129        })
130    }
131
132    fn alter_sequence_inner(&self, alter: &uqa_sql::ast::AlterSequence) -> Result<bool, SQLError> {
133        uqa_execution::schema::sequences::dispatch::alter_sequence(
134            &self.sequence_alter_context(),
135            alter,
136        )
137    }
138
139    pub(crate) fn persist_sequence_state_replacement(
140        &self,
141        name: &str,
142        relation: &RelationIdentity,
143        object_id: [u8; 16],
144        persistence: uqa_sql::ast::RelationPersistence,
145        state: SequenceState,
146        invalidate_current_cache: bool,
147    ) -> Result<(), SQLError> {
148        let temporary = persistence == uqa_sql::ast::RelationPersistence::Temporary;
149        let security = self
150            .durable
151            .sequence_security
152            .read()
153            .get(relation)
154            .cloned()
155            .ok_or_else(|| {
156                SQLError::Internal(format!("sequence `{name}` has no security metadata"))
157            })?;
158        if !temporary {
159            if let Some(catalog) = self.storage.catalog.as_ref() {
160                if !catalog
161                    .replace_sequence_row(
162                        &Self::sequence_row(name, object_id, state, persistence, &security)
163                            .map_err(|error| {
164                                SQLError::Internal(format!("build sequence catalog row: {error}"))
165                            })?,
166                    )
167                    .map_err(|error| {
168                        SQLError::Internal(format!("persist sequence catalog: {error}"))
169                    })?
170                {
171                    return Err(SQLError::Internal(format!(
172                        "sequence `{name}` disappeared during ALTER"
173                    )));
174                }
175            }
176        }
177        self.durable
178            .sequences
179            .write()
180            .insert(relation.clone(), state);
181        self.durable
182            .sequence_persistence
183            .write()
184            .insert(relation.clone(), persistence);
185        if invalidate_current_cache {
186            self.session.sequence_caches.lock().remove(relation);
187        }
188        self.note_catalog_registry_changed();
189        self.note_prepared_relation_change(relation);
190        Ok(())
191    }
192
193    pub(crate) fn restart_owned_sequence(&self, name: &str) -> StorageBackendResult<()> {
194        self.alter_sequence_inner(&uqa_sql::ast::AlterSequence {
195            name: name.into(),
196            restart: SequenceRestart::FromStart,
197            ..Default::default()
198        })
199        .map(|_| ())
200        .map_err(|error| StorageBackendError::Other(error.to_string()))
201    }
202
203    /// Snapshot of all registered sequences as `(name, state)` pairs.
204    pub fn try_sequences_snapshot(&self) -> StorageBackendResult<BTreeMap<String, SequenceState>> {
205        self.with_catalog_read_snapshot(|engine| {
206            let snapshot = engine.query_sequence_snapshot()?;
207            Ok(engine
208                .sequence_states_at_positions(&snapshot)?
209                .into_iter()
210                .map(|(relation, state)| (relation.qualified_name(), state))
211                .collect())
212        })
213    }
214
215    pub fn sequences_snapshot(&self) -> StorageBackendResult<BTreeMap<String, SequenceState>> {
216        self.try_sequences_snapshot()
217    }
218
219    /// Resolve a sequence name through the current `search_path` and return
220    /// its canonical name with the current state.
221    pub fn sequence_state(
222        &self,
223        name: &str,
224    ) -> StorageBackendResult<Option<(String, SequenceState)>> {
225        self.with_catalog_read_snapshot(|engine| {
226            use uqa_execution::catalog::sequence::snapshot::SequenceSnapshotSource;
227            let snapshot = engine.query_sequence_snapshot()?;
228            let Some((name, state)) =
229                snapshot.first_state(&engine.relation_lookup_candidates(name)?)
230            else {
231                return Ok(None);
232            };
233            let relation =
234                RelationIdentity::from_legacy_name(&name).map_err(StorageBackendError::Other)?;
235            let position = match snapshot.object_ids.get(&relation) {
236                Some(object_id) => engine.sequence_position(state.position_key(*object_id))?,
237                None => None,
238            };
239            Ok(Some((name, state.at_position(position))))
240        })
241    }
242}