Skip to main content

uqa_engine/capabilities/
sequences.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind sequence catalog consumers to session namespaces and durable registry state.
8use crate::{state::BoundSequenceSecurity, Engine, SequenceState};
9use uqa_core::RelationIdentity;
10use uqa_execution::schema::sequences::{
11    creation::{SequenceCreationContext, SequenceCreationNamespace, SequenceCreationPublication},
12    implicit::{ImplicitSequenceContext, ImplicitSequencePublication},
13};
14use uqa_sql::schema::sequences::ownership::{SequenceOwnerCatalog, SequenceOwnerColumns};
15use uqa_sql::{ast::RelationPersistence, SQLError};
16use uqa_storage::StorageBackendResult;
17
18impl Engine {
19    pub(crate) fn sequence_creation_context(&self) -> SequenceCreationContext<'_> {
20        SequenceCreationContext {
21            identities: self.catalog_identity_reservation_context(),
22            creation: self.relation_creation_context(),
23            namespace: self,
24            owners: self,
25            publication: self,
26        }
27    }
28    pub(crate) fn implicit_sequence_context(&self) -> ImplicitSequenceContext<'_> {
29        ImplicitSequenceContext {
30            namespace: self,
31            owners: self,
32            publication: self,
33        }
34    }
35}
36
37impl SequenceCreationNamespace for Engine {
38    fn refresh_sequences(&self) -> StorageBackendResult<()> {
39        self.refresh_sequences_from_catalog()
40    }
41    fn relation_exists(&self, name: &str) -> StorageBackendResult<bool> {
42        self.relation_kind_at(name).map(|kind| kind.is_some())
43    }
44}
45impl ImplicitSequencePublication for Engine {
46    fn create_implicit_sequence(
47        &self,
48        name: &str,
49        state: SequenceState,
50        persistence: RelationPersistence,
51    ) -> Result<(), SQLError> {
52        self.create_implicit_sequence_with_persistence(name, state, persistence)
53    }
54}
55impl SequenceOwnerCatalog for Engine {
56    fn resolve_owner_relation(
57        &self,
58        name: &str,
59    ) -> Result<Option<(String, &'static str)>, SQLError> {
60        self.try_resolve_visible_relation_kind(name)
61    }
62    fn owner_table_columns(
63        &self,
64        canonical: &str,
65    ) -> Result<Option<SequenceOwnerColumns>, SQLError> {
66        self.try_table(canonical)
67            .map_err(|error| SQLError::Internal(format!("load table `{canonical}`: {error}")))
68            .map(|table| table.map(|table| (table.object_id(), table.columns.read().clone())))
69    }
70    fn owner_foreign_columns(&self, relation: &RelationIdentity) -> Option<SequenceOwnerColumns> {
71        self.durable
72            .foreign_tables
73            .read()
74            .get(relation)
75            .map(|table| (table.object_id, table.columns.clone()))
76    }
77}
78impl SequenceCreationPublication for Engine {
79    fn insert_sequence(
80        &self,
81        name: &str,
82        relation: &RelationIdentity,
83        mut state: SequenceState,
84        persistence: RelationPersistence,
85        role_owner: uqa_core::catalog_role::RoleIdentity,
86        catalog_oid: u32,
87    ) -> Result<bool, SQLError> {
88        let security = BoundSequenceSecurity::owner(role_owner);
89        let object_id = crate::new_sequence_object_id().map_err(|error| {
90            SQLError::Internal(format!("allocate sequence `{name}` identity: {error}"))
91        })?;
92        state.definition_generation = object_id;
93        if persistence == RelationPersistence::Temporary {
94            let seqs = self.durable.sequences.read();
95            if seqs.contains_key(relation) {
96                return Ok(false);
97            }
98        } else if let Some(catalog) = self.storage.catalog.as_ref() {
99            let created = catalog
100                .create_sequence_row(
101                    &Self::sequence_row(name, object_id, state, persistence, &security).map_err(
102                        |error| SQLError::Internal(format!("build sequence catalog row: {error}")),
103                    )?,
104                )
105                .map_err(|error| {
106                    SQLError::Internal(format!("persist sequence catalog: {error}"))
107                })?;
108            if !created {
109                return Ok(false);
110            }
111            uqa_execution::catalog::sequence::catalog_oids::record(
112                catalog.as_ref(),
113                &object_id,
114                catalog_oid,
115            )
116            .map_err(|error| {
117                SQLError::Internal(format!("persist sequence catalog OID: {error}"))
118            })?;
119        } else {
120            let seqs = self.durable.sequences.read();
121            if seqs.contains_key(relation) {
122                return Ok(false);
123            }
124        }
125        self.durable
126            .sequences
127            .write()
128            .insert(relation.clone(), state);
129        self.durable
130            .sequence_object_ids
131            .write()
132            .insert(relation.clone(), object_id);
133        self.durable
134            .sequence_catalog_oids
135            .write()
136            .insert(object_id, catalog_oid);
137        self.durable
138            .sequence_persistence
139            .write()
140            .insert(relation.clone(), persistence);
141        self.durable
142            .sequence_security
143            .write()
144            .insert(relation.clone(), security);
145        self.note_catalog_registry_changed();
146        self.note_prepared_catalog_change(
147            uqa_execution::statement::prepared::invalidation::PreparedCatalogChange::Relation(
148                catalog_oid,
149            ),
150        );
151        Ok(true)
152    }
153}
154
155impl Engine {
156    pub(crate) fn implicit_ownership_context(
157        &self,
158    ) -> uqa_execution::schema::sequences::ownership::ImplicitOwnershipContext<'_> {
159        uqa_execution::schema::sequences::ownership::ImplicitOwnershipContext {
160            owners: self,
161            names: self,
162            tables: self,
163            publication: self,
164        }
165    }
166}
167impl uqa_sql::schema::sequences::implicit_ownership::StoredSequenceNames for Engine {
168    fn stored_sequence_name_with_control(
169        &self,
170        reference: &str,
171        control: &uqa_core::memory::ProductionControl<'_>,
172    ) -> Result<uqa_core::memory::Produced<String>, SQLError> {
173        uqa_sql::schema::sequences::names::resolve_stored_sequence_reference_with_control(
174            self, reference, control,
175        )
176    }
177    fn stored_sequence_name(&self, reference: &str) -> Result<String, String> {
178        self.resolve_stored_sequence_reference_from_loaded_registry(reference)
179            .map_err(|error| error.to_string())
180    }
181}
182impl uqa_execution::schema::sequences::ownership::ImplicitOwnerTables for Engine {
183    fn table_owner_columns(
184        &self,
185        table: &str,
186    ) -> StorageBackendResult<Option<([u8; 16], Vec<uqa_sql::ast::ColumnDef>)>> {
187        self.try_table(table)
188            .map(|table| table.map(|table| (table.object_id(), table.columns.read().clone())))
189    }
190}
191impl uqa_execution::schema::sequences::ownership::ImplicitOwnerPublication for Engine {
192    fn attach_owner(
193        &self,
194        sequence: &str,
195        owner: uqa_storage::SequenceOwner,
196    ) -> Result<(), SQLError> {
197        self.attach_sequence_owner_identity(sequence, owner)
198    }
199}
200
201impl uqa_sql::schema::sequences::lifecycle::SequenceLifecycleCatalog for Engine {
202    fn temporary_schema_name(&self) -> String {
203        Engine::temporary_schema_name(self)
204    }
205    fn sequence_is_owned(&self, relation: &RelationIdentity) -> bool {
206        self.durable
207            .sequences
208            .read()
209            .get(relation)
210            .is_some_and(|state| state.owner.is_some())
211    }
212    fn relation_kind_at(&self, name: &str) -> Result<Option<&'static str>, String> {
213        Engine::relation_kind_at(self, name).map_err(|error| error.to_string())
214    }
215}
216impl uqa_sql::schema::sequences::names::StoredSequenceRegistry for Engine {
217    fn visit_sequence_names_with_control(
218        &self,
219        control: &uqa_core::memory::ProductionControl<'_>,
220        visit: &mut dyn FnMut(&RelationIdentity) -> Result<(), SQLError>,
221    ) -> Result<(), SQLError> {
222        control.check()?;
223        for name in self.durable.sequences.read().keys() {
224            control.check()?;
225            visit(name)?;
226        }
227        Ok(())
228    }
229    fn contains_sequence(&self, relation: &RelationIdentity) -> bool {
230        self.durable.sequences.read().contains_key(relation)
231    }
232    fn sequence_names(&self) -> Vec<RelationIdentity> {
233        self.durable.sequences.read().keys().cloned().collect()
234    }
235}
236
237impl Engine {
238    pub(crate) fn sequence_definition_context(
239        &self,
240    ) -> uqa_execution::schema::sequences::alteration::SequenceDefinitionContext<'_> {
241        uqa_execution::schema::sequences::alteration::SequenceDefinitionContext {
242            catalog: self,
243            owners: self,
244            publication: self,
245            markers: self.schema_dependency_publication_context(),
246            new_generation: crate::new_sequence_definition_generation,
247        }
248    }
249}
250impl uqa_execution::schema::sequences::alteration::SequenceDefinitionCatalog for Engine {
251    fn object_id(&self, relation: &RelationIdentity) -> Option<[u8; 16]> {
252        self.durable
253            .sequence_object_ids
254            .read()
255            .get(relation)
256            .copied()
257    }
258    fn state(&self, relation: &RelationIdentity) -> Result<Option<SequenceState>, SQLError> {
259        let Some(state) = self.durable.sequences.read().get(relation).copied() else {
260            return Ok(None);
261        };
262        let object_id = self
263            .durable
264            .sequence_object_ids
265            .read()
266            .get(relation)
267            .copied();
268        let (Some(positions), Some(object_id)) = (self.shared_sequence_positions(), object_id)
269        else {
270            return Ok(Some(state));
271        };
272        Ok(Some(state.at_position(
273            positions.sequence_position(state.position_key(object_id))?,
274        )))
275    }
276    fn owner_target(&self, owner: uqa_storage::SequenceOwner) -> Option<(String, String, bool)> {
277        self.sequence_owner_target(owner)
278    }
279}
280impl uqa_execution::schema::sequences::alteration::SequenceDefinitionPublication for Engine {
281    fn replace_sequence(
282        &self,
283        name: &str,
284        relation: &RelationIdentity,
285        object_id: [u8; 16],
286        persistence: RelationPersistence,
287        state: SequenceState,
288        invalidate_current_cache: bool,
289    ) -> Result<(), SQLError> {
290        self.persist_sequence_state_replacement(
291            name,
292            relation,
293            object_id,
294            persistence,
295            state,
296            invalidate_current_cache,
297        )
298    }
299}
300
301impl Engine {
302    pub(crate) fn sequence_role_ownership_context(
303        &self,
304    ) -> uqa_execution::schema::sequences::role_ownership::SequenceRoleOwnershipContext<'_> {
305        uqa_execution::schema::sequences::role_ownership::SequenceRoleOwnershipContext {
306            locks: self,
307            writer: self,
308            roles: self,
309            session: self,
310            schemas: self,
311            metadata: self,
312            security: self,
313            changes: self,
314        }
315    }
316}
317impl uqa_execution::schema::sequences::role_ownership::SequenceSecurityPublication for Engine {
318    fn security(&self, relation: &RelationIdentity) -> Option<BoundSequenceSecurity> {
319        self.durable.sequence_security.read().get(relation).cloned()
320    }
321    fn persist_security(
322        &self,
323        name: &str,
324        relation: &RelationIdentity,
325        security: &BoundSequenceSecurity,
326    ) -> Result<(), SQLError> {
327        self.persist_sequence_security(name, relation, security)
328    }
329    fn publish_security(&self, relation: &RelationIdentity, security: BoundSequenceSecurity) {
330        self.durable
331            .sequence_security
332            .write()
333            .insert(relation.clone(), security);
334        self.note_prepared_relation_change(relation);
335    }
336}
337
338impl Engine {
339    pub(crate) fn sequence_lifecycle_context(
340        &self,
341    ) -> uqa_execution::schema::sequences::lifecycle::SequenceLifecycleContext<'_> {
342        uqa_execution::schema::sequences::lifecycle::SequenceLifecycleContext {
343            analysis: self,
344            creation: self.relation_creation_context(),
345            schemas: self.schema_dependency_publication_context(),
346            views: self.view_sequence_rewrite_context(),
347            state: self,
348            catalog: self,
349            events: self.event_catalog_context(),
350            changes: self,
351        }
352    }
353    pub(crate) fn sequence_alter_context(
354        &self,
355    ) -> uqa_execution::schema::sequences::dispatch::SequenceAlterContext<'_> {
356        uqa_execution::schema::sequences::dispatch::SequenceAlterContext {
357            catalog: self,
358            authority: self.table_privilege_context(),
359            definition: self.sequence_definition_context(),
360            roles: self.sequence_role_ownership_context(),
361            lifecycle: self.sequence_lifecycle_context(),
362        }
363    }
364}
365impl uqa_execution::schema::sequences::entry::SequenceCreationTransactions for Engine {
366    fn with_sequence_creation(
367        &self,
368        write: uqa_execution::schema::sequences::entry::SequenceCreationWrite<'_>,
369    ) -> Result<bool, SQLError> {
370        self.with_implicit_transaction(|engine| write(&engine.sequence_creation_context()))
371    }
372}
373impl uqa_execution::schema::sequences::entry::SequenceAlterTransactions for Engine {
374    fn with_sequence_write(
375        &self,
376        write: uqa_execution::schema::sequences::entry::SequenceAlterWrite<'_>,
377    ) -> Result<bool, SQLError> {
378        self.with_implicit_transaction(|engine| write(&engine.sequence_alter_context()))
379    }
380}
381impl uqa_execution::schema::sequences::lifecycle::SequenceStateRename for Engine {
382    fn move_state(
383        &self,
384        source: &RelationIdentity,
385        target: &RelationIdentity,
386    ) -> Result<(), SQLError> {
387        self.move_sequence_state(source, target)?;
388        self.note_prepared_relation_change(target);
389        Ok(())
390    }
391}
392impl uqa_execution::schema::sequences::lifecycle::SequenceRenameCatalog for Engine {
393    fn has_catalog(&self) -> bool {
394        self.storage.catalog.is_some()
395    }
396    fn rename_sequence_row(&self, source: &str, target: &str) -> StorageBackendResult<bool> {
397        let renamed = self.storage.catalog.as_ref().map_or(Ok(false), |catalog| {
398            catalog.rename_sequence_row(source, target)
399        })?;
400        if renamed {
401            let relation = RelationIdentity::from_legacy_name(source)
402                .map_err(uqa_storage::StorageBackendError::Other)?;
403            self.note_prepared_relation_change(&relation);
404        }
405        Ok(renamed)
406    }
407}
408impl uqa_execution::schema::sequences::dispatch::SequenceCommandCatalog for Engine {
409    fn resolve_visible_relation(
410        &self,
411        name: &str,
412    ) -> Result<uqa_sql::catalog::resolution::RelationResolution, SQLError> {
413        self.resolve_visible_relation_kind(name)
414    }
415    fn sequence_persistence(&self, relation: &RelationIdentity) -> RelationPersistence {
416        self.durable
417            .sequence_persistence
418            .read()
419            .get(relation)
420            .copied()
421            .unwrap_or_default()
422    }
423}