Skip to main content

uqa_execution/schema/
namespaces.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Schema registration and owner publication through live catalog and authorization guards.
8pub mod authority;
9pub mod identity;
10pub mod locking;
11pub mod privileges;
12pub mod relation_names;
13pub mod removal;
14pub mod rename;
15pub mod restoration;
16pub mod type_names;
17
18use crate::catalog::security::roles::RoleCatalogGuards;
19use crate::catalog::security::roles::{
20    dependencies::{prepare_role_owner, RoleDependencyCandidate},
21    locking::RoleLockContext,
22};
23use crate::row_locks::shared_objects::SharedObjectLockSession;
24use std::{collections::BTreeMap, ops::DerefMut};
25use uqa_sql::{
26    catalog::{
27        roles::{self, RoleReferenceNames},
28        security::{schema::rewrite_schema_acl_owner, BoundSchemaSecurity},
29    },
30    SQLError, SQLResult,
31};
32use uqa_storage::{StorageBackendError, StorageBackendResult};
33
34pub trait SchemaStatementWriter {
35    fn prepare_writer(&self) -> Result<(), SQLError>;
36}
37pub trait NamespaceCatalogRefresh {
38    fn refresh_catalog(&self) -> StorageBackendResult<()>;
39}
40pub trait NamespaceCatalogChanges {
41    fn prepared_catalog_changed(
42        &self,
43        _change: crate::statement::prepared::invalidation::PreparedCatalogChange,
44    ) {
45    }
46    fn catalog_registry_changed(&self);
47
48    fn catalog_registry_changed_kind(
49        &self,
50        _change: crate::statement::prepared::invalidation::CatalogRegistryChange,
51    ) {
52        self.catalog_registry_changed();
53    }
54
55    fn namespace_catalog_changed(&self) {
56        self.catalog_registry_changed();
57        self.prepared_catalog_changed(
58            crate::statement::prepared::invalidation::PreparedCatalogChange::GlobalCatalog,
59        );
60    }
61}
62
63pub type SchemaRegistryWrite<'a> =
64    Box<dyn DerefMut<Target = BTreeMap<String, BoundSchemaSecurity>> + 'a>;
65pub trait SchemaRegistrationState {
66    fn schemas_write(&self) -> SchemaRegistryWrite<'_>;
67    fn contains_graph(&self, name: &str) -> bool;
68}
69pub trait SchemaRegistrationPersistence {
70    fn persist_schema(
71        &self,
72        name: &str,
73        security: &BoundSchemaSecurity,
74    ) -> StorageBackendResult<()>;
75}
76pub struct SchemaRegistrationContext<'a> {
77    pub state: &'a dyn SchemaRegistrationState,
78    pub persistence: &'a dyn SchemaRegistrationPersistence,
79    pub changes: &'a dyn NamespaceCatalogChanges,
80}
81
82pub fn register_schema(
83    context: &SchemaRegistrationContext<'_>,
84    name: &str,
85    if_not_exists: bool,
86    role_owner: uqa_core::catalog_role::RoleIdentity,
87    tuple: uqa_core::catalog_schema::SchemaTupleIdentity,
88) -> StorageBackendResult<bool> {
89    uqa_sql::schema::namespaces::validate_schema_name(name).map_err(StorageBackendError::Other)?;
90    if !tuple.is_valid() {
91        return Err(StorageBackendError::Other(
92            "invalid schema catalog tuple identity".into(),
93        ));
94    }
95    let mut schemas = context.state.schemas_write();
96    if schemas.contains_key(name) || context.state.contains_graph(name) {
97        if if_not_exists {
98            return Ok(false);
99        }
100        return Err(StorageBackendError::Other(format!(
101            "schema `{name}` already exists"
102        )));
103    }
104    let security = BoundSchemaSecurity {
105        tuple: Some(tuple),
106        role_owner,
107        acl: None,
108    };
109    context.persistence.persist_schema(name, &security)?;
110    schemas.insert(name.to_string(), security);
111    drop(schemas);
112    context.changes.namespace_catalog_changed();
113    Ok(true)
114}
115
116pub trait SchemaRegistration {
117    fn register_schema(
118        &self,
119        name: &str,
120        if_not_exists: bool,
121        role_owner: uqa_core::catalog_role::RoleIdentity,
122        tuple: uqa_core::catalog_schema::SchemaTupleIdentity,
123    ) -> StorageBackendResult<bool>;
124}
125pub struct SchemaCreationContext<'a> {
126    pub tuples: locking::SchemaLockContext<'a>,
127    pub writer: &'a dyn SchemaStatementWriter,
128    pub session: &'a dyn RoleReferenceNames,
129    pub roles: &'a dyn RoleCatalogGuards,
130    pub locks: &'a dyn SharedObjectLockSession,
131    pub database: &'a dyn uqa_sql::catalog::security::database_inquiry::DatabasePrivilegeCatalog,
132    pub registration: &'a dyn SchemaRegistration,
133    pub catalog: &'a dyn SchemaSecurityCatalog,
134    pub schemas: &'a dyn uqa_sql::catalog::security::schema_inquiry::SchemaPrivilegeCatalog,
135    pub notices: &'a dyn crate::catalog::notices::CatalogNotices,
136}
137
138/// The host API keeps its declaration rules while sharing transactional owner dependency publication with SQL.
139pub fn register_api_schema(
140    context: &SchemaCreationContext<'_>,
141    name: &str,
142    if_not_exists: bool,
143) -> Result<bool, SQLError> {
144    context.locks.refresh_shared_catalog()?;
145    uqa_sql::schema::namespaces::validate_schema_name(name).map_err(SQLError::Internal)?;
146    let locks = RoleLockContext {
147        roles: context.roles,
148        session: context.locks,
149    };
150    let owner = locks.bind(&context.session.current_role())?;
151    let RoleDependencyCandidate {
152        roles,
153        memberships,
154        value,
155        ..
156    } = prepare_role_owner(
157        locks,
158        &owner,
159        || context.writer.prepare_writer(),
160        |_, _, _| {
161            Ok(context
162                .catalog
163                .schema_security(name)
164                .is_none()
165                .then_some(()))
166        },
167    )?;
168    drop(memberships);
169    drop(roles);
170    let created = if value.is_some() {
171        let tuple = identity::reserve_creation(context, name)?;
172        context
173            .registration
174            .register_schema(name, if_not_exists, owner.identity(), tuple)
175            .map_err(|error| uqa_sql::catalog::errors::storage_error("CREATE SCHEMA", &error))?
176    } else if if_not_exists {
177        false
178    } else {
179        return Err(SQLError::Internal(format!(
180            "schema `{name}` already exists"
181        )));
182    };
183    Ok(created)
184}
185
186pub fn create_schema(
187    context: &SchemaCreationContext<'_>,
188    name: Option<&str>,
189    if_not_exists: bool,
190    authorization: Option<&uqa_sql::ast::SchemaAuthorization>,
191) -> Result<SQLResult, SQLError> {
192    let current_user = context.session.current_role();
193    let target = uqa_sql::schema::namespaces::creation::schema_creation_target(
194        context.session,
195        context.roles,
196        &current_user,
197        name,
198        authorization,
199    )?;
200    let locks = RoleLockContext {
201        roles: context.roles,
202        session: context.locks,
203    };
204    let owner = locks.bind(&target.role_owner)?;
205    let RoleDependencyCandidate {
206        roles,
207        memberships,
208        value,
209        ..
210    } = prepare_role_owner(
211        locks,
212        &owner,
213        || context.writer.prepare_writer(),
214        |roles, memberships, new_owner| {
215            uqa_sql::catalog::security::ownership::OwnerChangeAuthority {
216                roles,
217                memberships,
218                current_user: &current_user,
219                new_owner,
220            }
221            .require_database_create(&context.database.security())?;
222            roles::require_set_role(roles, memberships, &current_user, new_owner)?;
223            uqa_sql::schema::namespaces::creation::validate_schema_creation_name(&target.name)?;
224            Ok(context
225                .catalog
226                .schema_security(&target.name)
227                .is_none()
228                .then_some(()))
229        },
230    )?;
231    drop(memberships);
232    drop(roles);
233    let created = if value.is_none() {
234        false
235    } else {
236        let tuple = identity::reserve_creation(context, &target.name)?;
237        context
238            .registration
239            .register_schema(&target.name, true, owner.identity(), tuple)
240            .map_err(|error| {
241                SQLError::Internal(format!("CREATE SCHEMA catalog write failed: {error}"))
242            })?
243    };
244    if !created {
245        if !if_not_exists {
246            return Err(SQLError::Routine {
247                sqlstate: "42P06".into(),
248                message: format!(r#"schema "{}" already exists"#, target.name),
249            });
250        }
251        context.notices.notice(
252            uqa_sql::SQLNotice::notice(format!(
253                r#"schema "{}" already exists, skipping"#,
254                target.name
255            ))
256            .with_sqlstate("42P06"),
257        );
258    }
259    Ok(SQLResult::empty())
260}
261
262pub trait SchemaSecurityCatalog {
263    fn schema_security(&self, name: &str) -> Option<BoundSchemaSecurity>;
264}
265pub trait SchemaSecurityPersistence {
266    fn persist_security(&self, name: &str, security: &BoundSchemaSecurity) -> Result<(), SQLError>;
267}
268pub trait SchemaSecurityPublication {
269    fn publish_security(&self, name: &str, security: BoundSchemaSecurity);
270}
271pub struct SchemaOwnerContext<'a> {
272    pub writer: &'a dyn SchemaStatementWriter,
273    pub refresh: &'a dyn NamespaceCatalogRefresh,
274    pub session: &'a dyn RoleReferenceNames,
275    pub roles: &'a dyn RoleCatalogGuards,
276    pub locks: &'a dyn SharedObjectLockSession,
277    pub tuples: locking::SchemaLockContext<'a>,
278    pub database: &'a dyn uqa_sql::catalog::security::database_inquiry::DatabasePrivilegeCatalog,
279    pub catalog: &'a dyn SchemaSecurityCatalog,
280    pub publication: &'a dyn SchemaSecurityPublication,
281    pub persistence: &'a dyn SchemaSecurityPersistence,
282    pub changes: &'a dyn NamespaceCatalogChanges,
283}
284
285pub fn alter_schema_owner(
286    context: &SchemaOwnerContext<'_>,
287    name: &str,
288    requested: &uqa_sql::ast::RoleSpecification,
289) -> Result<(), SQLError> {
290    context
291        .refresh
292        .refresh_catalog()
293        .map_err(|error| SQLError::Internal(error.to_string()))?;
294    let new_owner = roles::resolve_role_specification(context.session, requested);
295    let locks = RoleLockContext {
296        roles: context.roles,
297        session: context.locks,
298    };
299    let owner = locks.bind(&new_owner)?;
300    context.tuples.catalog_write()?;
301    let current = context
302        .catalog
303        .schema_security(name)
304        .ok_or_else(|| locking::missing(name))?;
305    let current_user = context.session.current_role();
306    let RoleDependencyCandidate {
307        roles,
308        memberships,
309        value,
310        ..
311    } = prepare_role_owner(
312        locks,
313        &owner,
314        || context.writer.prepare_writer(),
315        |roles, memberships, new_owner| {
316            if current.role_owner == owner.identity() {
317                return Ok(None);
318            }
319            let mut security = current.resolve(roles).map_err(SQLError::Internal)?;
320            let authority = uqa_sql::catalog::security::ownership::OwnerChangeAuthority {
321                roles,
322                memberships,
323                current_user: &current_user,
324                new_owner,
325            };
326            authority.require_owner_change(&security.role_owner, "schema", name)?;
327            authority.require_database_create(&context.database.security())?;
328            rewrite_schema_acl_owner(&mut security, new_owner);
329            let mut security =
330                BoundSchemaSecurity::bind(&security, roles).map_err(SQLError::Internal)?;
331            identity::replace_tuple(&current, &mut security)?;
332            Ok(Some(security))
333        },
334    )?;
335    let Some(security) = value else {
336        return Ok(());
337    };
338    drop(memberships);
339    drop(roles);
340    context.tuples.replace(name, locking::tuple(&current)?)?;
341    context.persistence.persist_security(name, &security)?;
342    context.publication.publish_security(name, security);
343    context.changes.namespace_catalog_changed();
344    Ok(())
345}
346
347pub mod relations;