Skip to main content

uqa_execution/schema/sequences/
implicit.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Materialize implicit sequence declarations before publishing their table columns.
8use super::creation::SequenceCreationNamespace;
9use crate::catalog::sequence::SequenceState;
10use uqa_core::RelationIdentity;
11use uqa_sql::ast::{
12    AutoIncrementKind, ColumnDef, IdentitySequenceDeclaration, RelationPersistence,
13};
14use uqa_sql::schema::sequences::{
15    declaration::{declare_sequence, sequence_ownership},
16    implicit::{apply_implicit_sequence_metadata, choose_implicit_sequence_name},
17    ownership::{bind_sequence_owner, SequenceOwnerCatalog},
18};
19use uqa_sql::SQLError;
20use uqa_storage::StorageBackendError;
21
22pub trait ImplicitSequencePublication {
23    fn create_implicit_sequence(
24        &self,
25        name: &str,
26        state: SequenceState,
27        persistence: RelationPersistence,
28    ) -> Result<(), SQLError>;
29}
30
31pub struct ImplicitSequenceContext<'a> {
32    pub namespace: &'a dyn SequenceCreationNamespace,
33    pub owners: &'a dyn SequenceOwnerCatalog,
34    pub publication: &'a dyn ImplicitSequencePublication,
35}
36
37/// Create the sequence of each `SERIAL` and identity column of `table_name`, from the options an identity declaration writes, and record it on its column. `PostgreSQL` names every sequence while it analyzes the statement, and then creates them in column order before the table.
38pub fn materialize_implicit_sequences(
39    context: &ImplicitSequenceContext<'_>,
40    statement: &str,
41    table_name: &str,
42    columns: &mut [ColumnDef],
43    persistence: RelationPersistence,
44) -> Result<(), SQLError> {
45    let relation = RelationIdentity::from_legacy_name(table_name)
46        .map_err(|error| SQLError::Internal(format!("resolve {statement} relation: {error}")))?;
47    let mut sequences = Vec::new();
48    for (index, column) in columns.iter_mut().enumerate() {
49        let Some(auto_increment) = column.auto_increment.as_mut() else {
50            continue;
51        };
52        let declaration = auto_increment
53            .declaration
54            .take()
55            .map(|declaration| *declaration)
56            .unwrap_or_default();
57        if auto_increment.kind == AutoIncrementKind::Legacy || auto_increment.sequence.is_some() {
58            continue;
59        }
60        let identity = auto_increment.is_identity();
61        let name = sequence_name(context, &relation, &column.name, &declaration)?;
62        let persistence = sequence_persistence(&declaration, persistence)?;
63        sequences.push((index, name, persistence, declaration, identity));
64    }
65    for (index, name, persistence, declaration, identity) in sequences {
66        let column = &mut columns[index];
67        create_column_sequence(context, column, &name, persistence, &declaration, identity)?;
68        apply_implicit_sequence_metadata(table_name, column, name).map_err(SQLError::Internal)?;
69    }
70    Ok(())
71}
72
73/// The name `SEQUENCE NAME` gives a column's sequence, in its table's schema unless it names another, or the free name `PostgreSQL` chooses from the table and column names.
74fn sequence_name(
75    context: &ImplicitSequenceContext<'_>,
76    relation: &RelationIdentity,
77    column: &str,
78    declaration: &IdentitySequenceDeclaration,
79) -> Result<String, SQLError> {
80    if let Some(name) = &declaration.name {
81        return Ok(RelationIdentity::new(
82            name.schema
83                .clone()
84                .unwrap_or_else(|| relation.schema.clone()),
85            name.name.clone(),
86        )
87        .qualified_name());
88    }
89    choose_implicit_sequence_name(
90        relation,
91        column,
92        |candidate| {
93            context
94                .namespace
95                .relation_exists(&candidate.qualified_name())
96        },
97        StorageBackendError::Other,
98    )
99    .map_err(|error| {
100        SQLError::Internal(format!(
101            "choose implicit sequence for `{}`.`{column}`: {error}",
102            relation.qualified_name()
103        ))
104    })
105}
106
107/// A column sequence takes its table's persistence, or the `LOGGED` or `UNLOGGED` its declaration writes, which a temporary table's sequence cannot take.
108fn sequence_persistence(
109    declaration: &IdentitySequenceDeclaration,
110    table: RelationPersistence,
111) -> Result<RelationPersistence, SQLError> {
112    match declaration.persistence {
113        Some(_) if table == RelationPersistence::Temporary => Err(SQLError::Routine {
114            sqlstate: "42P16".into(),
115            message: "cannot set logged status of a temporary sequence".into(),
116        }),
117        Some(declared) => Ok(declared),
118        None => Ok(table),
119    }
120}
121
122/// Create one column's sequence as the `CREATE SEQUENCE` `PostgreSQL` issues for it does: read its options, create it, and read the `OWNED BY` the declaration writes.
123fn create_column_sequence(
124    context: &ImplicitSequenceContext<'_>,
125    column: &ColumnDef,
126    name: &str,
127    persistence: RelationPersistence,
128    declaration: &IdentitySequenceDeclaration,
129    identity: bool,
130) -> Result<(), SQLError> {
131    if let Some(error) = declaration.error.clone() {
132        return Err(error.into());
133    }
134    let declared = declare_sequence(&declaration.sequence, &column.ty, identity)?;
135    let mut state = SequenceState::from_definition(declared.definition);
136    state.current = declared.current;
137    context
138        .publication
139        .create_implicit_sequence(name, state, persistence)?;
140    // The column itself owns the sequence. An `OWNED BY` the declaration writes is read and checked as `CREATE SEQUENCE` reads it, and then replaced.
141    if let Some(names) = declaration.sequence.owned_by.as_deref() {
142        bind_sequence_owner(context.owners, name, &sequence_ownership(names)?)?;
143    }
144    Ok(())
145}