Skip to main content

uqa_sql/catalog/
system_relations.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Built-in relation identity, bootstrap security and ordered view references.
8
9use super::{
10    security::{table_binding::BoundTableAclEntry, BoundTableSecurity, TablePrivileges},
11    VirtualRelation,
12};
13mod columns;
14
15macro_rules! system_relations {
16    ($($variant:ident => ($schema:literal, $name:literal, $oid:literal, $kind:literal)),* $(,)?) => {
17        /// Catalog identity is independent of whether a virtual row projector is available.
18        #[derive(Clone, Copy, Debug, PartialEq, Eq)]
19        pub enum SystemRelation {
20            Projected(VirtualRelation),
21            $($variant),*
22        }
23
24        impl SystemRelation {
25            pub fn all() -> impl Iterator<Item = Self> {
26                VirtualRelation::ALL.iter().copied().map(Self::Projected)
27                    .chain([$(Self::$variant),*])
28            }
29
30            pub const fn namespace(self) -> &'static str {
31                match self {
32                    Self::Projected(relation) => relation.namespace(),
33                    $(Self::$variant => $schema),*
34                }
35            }
36
37            pub const fn name(self) -> &'static str {
38                match self {
39                    Self::Projected(relation) => relation.name(),
40                    $(Self::$variant => $name),*
41                }
42            }
43
44            pub fn oid(self) -> i64 {
45                match self {
46                    Self::Projected(relation) => relation.oid(),
47                    $(Self::$variant => $oid),*
48                }
49            }
50
51            pub const fn kind(self) -> &'static str {
52                match self {
53                    Self::Projected(relation) => relation.kind(),
54                    $(Self::$variant => $kind),*
55                }
56            }
57
58            pub fn at(schema: &str, name: &str) -> Option<Self> {
59                VirtualRelation::at(schema, name).map(Self::Projected).or_else(|| {
60                    match (schema, name) {
61                        $(($schema, $name) => Some(Self::$variant),)*
62                        _ => None,
63                    }
64                })
65            }
66        }
67    };
68}
69
70system_relations! {
71    PgDbRoleSetting => ("pg_catalog", "pg_db_role_setting", 2964, "table"),
72    PgShadow => ("pg_catalog", "pg_shadow", 12005, "view"),
73    PgTablespace => ("pg_catalog", "pg_tablespace", 1213, "table"),
74    PgCollation => ("pg_catalog", "pg_collation", 3456, "table"),
75    PgSequence => ("pg_catalog", "pg_sequence", 2224, "table"),
76    InformationEnabledRoles => ("information_schema", "enabled_roles", 13410, "view"),
77}
78
79impl SystemRelation {
80    /// `PostgreSQL`'s pinned system catalogs and their metadata views are outside SSI. AGE catalogs are ordinary extension tables and retain data predicates.
81    pub const fn tracks_serializable_reads(self) -> bool {
82        matches!(
83            self,
84            Self::Projected(VirtualRelation::AgGraph | VirtualRelation::AgLabel)
85        )
86    }
87
88    pub fn qualified_name(self) -> String {
89        format!("{}.{}", self.namespace(), self.name())
90    }
91
92    pub fn from_qualified_name(name: &str) -> Option<Self> {
93        let reference = uqa_core::RelationIdentity::borrowed_reference(name)?;
94        let schema = reference.schema?;
95        Self::all().find(|relation| {
96            schema == uqa_core::RelationName::decoded(relation.namespace())
97                && reference.name == uqa_core::RelationName::decoded(relation.name())
98        })
99    }
100
101    /// Immutable built-ins retain the same identity in every session; lock managers retain database affinity.
102    pub fn object_id(self) -> [u8; 16] {
103        let mut identity = [0; 16];
104        identity[..8].copy_from_slice(b"UQA:cat:");
105        identity[8..].copy_from_slice(&self.oid().to_be_bytes());
106        identity
107    }
108
109    pub fn bootstrap_security(self) -> BoundTableSecurity {
110        let (acl, count) = self.bootstrap_acl();
111        let mut security = BoundTableSecurity::owner(super::roles::RoleIdentity::BOOTSTRAP);
112        security.acl = Some(acl.into_iter().take(count).collect());
113        security
114    }
115
116    /// Borrowing authorization consumers retain the at-most-two bootstrap entries inline.
117    pub fn bootstrap_acl(self) -> ([BoundTableAclEntry; 2], usize) {
118        let owner = super::roles::RoleIdentity::BOOTSTRAP;
119        let owner_entry = BoundTableAclEntry {
120            role: Some(owner),
121            grantor: owner,
122            privileges: TablePrivileges::ALL,
123            grant_options: TablePrivileges::default(),
124        };
125        let public_entry = BoundTableAclEntry {
126            role: None,
127            grantor: owner,
128            privileges: TablePrivileges {
129                select: true,
130                update: self == Self::Projected(VirtualRelation::PgSettings),
131                ..TablePrivileges::default()
132            },
133            grant_options: TablePrivileges::default(),
134        };
135        let count = if matches!(
136            self,
137            Self::PgShadow
138                | Self::Projected(
139                    VirtualRelation::PgAuthid | VirtualRelation::AgGraph | VirtualRelation::AgLabel
140                )
141        ) {
142            1
143        } else {
144            2
145        };
146        ([owner_entry, public_entry], count)
147    }
148
149    /// `PostgreSQL` 18 view range-table order, followed by expression and range-table subqueries. Repeated references preserve that order; consumers own recursion and lock retention.
150    pub const fn view_sources(self) -> &'static [Self] {
151        use SystemRelation::Projected as P;
152        use VirtualRelation::{
153            InformationColumnPrivileges, PgAttrdef, PgAttribute, PgClass, PgIndex, PgLanguage,
154            PgNamespace, PgProc, PgRewrite, PgTrigger, PgType,
155        };
156        if let Some(sources) = self.constraint_view_sources() {
157            return sources;
158        }
159        match self {
160            P(VirtualRelation::InformationSchemata) => {
161                &[P(PgNamespace), Self::Projected(VirtualRelation::PgAuthid)]
162            }
163            P(VirtualRelation::InformationTables) => {
164                &[P(PgNamespace), P(PgClass), P(PgType), P(PgNamespace)]
165            }
166            P(VirtualRelation::InformationColumns) => &[
167                P(PgAttribute),
168                P(PgAttrdef),
169                P(PgClass),
170                P(PgNamespace),
171                P(PgType),
172                P(PgNamespace),
173                P(PgType),
174                P(PgNamespace),
175                Self::PgCollation,
176                P(PgNamespace),
177                P(VirtualRelation::PgDepend),
178                Self::PgSequence,
179            ],
180            P(InformationColumnPrivileges) => &[
181                P(PgNamespace),
182                Self::Projected(VirtualRelation::PgAuthid),
183                P(PgAttribute),
184                P(PgClass),
185                P(PgClass),
186                P(PgAttribute),
187                P(PgClass),
188                Self::Projected(VirtualRelation::PgAuthid),
189            ],
190            P(VirtualRelation::InformationRoleColumnGrants) => &[
191                P(InformationColumnPrivileges),
192                Self::InformationEnabledRoles,
193                Self::InformationEnabledRoles,
194            ],
195            P(VirtualRelation::InformationViews) => &[
196                P(PgNamespace),
197                P(PgClass),
198                P(PgTrigger),
199                P(PgTrigger),
200                P(PgTrigger),
201            ],
202            P(VirtualRelation::InformationRoutines) => &[
203                P(PgNamespace),
204                P(PgProc),
205                P(PgLanguage),
206                P(PgType),
207                P(PgNamespace),
208            ],
209            P(VirtualRelation::InformationSequences) => &[
210                P(PgNamespace),
211                P(PgClass),
212                Self::PgSequence,
213                P(VirtualRelation::PgDepend),
214            ],
215            P(VirtualRelation::PgRules) => &[P(PgRewrite), P(PgClass), P(PgNamespace)],
216            P(VirtualRelation::PgTables | VirtualRelation::PgMatviews) => {
217                &[P(PgClass), P(PgNamespace), Self::PgTablespace]
218            }
219            P(VirtualRelation::PgViews) => &[P(PgClass), P(PgNamespace)],
220            P(VirtualRelation::PgIndexes) => &[
221                P(PgIndex),
222                P(PgClass),
223                P(PgClass),
224                P(PgNamespace),
225                Self::PgTablespace,
226            ],
227            P(VirtualRelation::PgRoles) | Self::PgShadow => &[
228                Self::Projected(VirtualRelation::PgAuthid),
229                Self::PgDbRoleSetting,
230            ],
231            P(VirtualRelation::PgUser) => &[Self::PgShadow],
232            P(VirtualRelation::PgSequences) => &[Self::PgSequence, P(PgClass), P(PgNamespace)],
233            Self::InformationEnabledRoles => &[Self::Projected(VirtualRelation::PgAuthid)],
234            _ => &[],
235        }
236    }
237    const fn constraint_view_sources(self) -> Option<&'static [Self]> {
238        use SystemRelation::Projected as P;
239        use VirtualRelation::{
240            PgAttribute, PgClass, PgConstraint, PgDepend, PgIndex, PgNamespace, PgType,
241        };
242        match self {
243            P(VirtualRelation::InformationTableConstraints) => Some(&[
244                P(PgNamespace),
245                P(PgNamespace),
246                P(PgConstraint),
247                P(PgClass),
248                P(PgIndex),
249            ]),
250            P(VirtualRelation::InformationCheckConstraints) => Some(&[
251                P(PgConstraint),
252                P(PgNamespace),
253                P(PgClass),
254                P(PgType),
255                P(PgConstraint),
256                P(PgNamespace),
257                P(PgClass),
258                P(PgType),
259                P(PgAttribute),
260            ]),
261            P(VirtualRelation::InformationDomainConstraints) => {
262                Some(&[P(PgNamespace), P(PgNamespace), P(PgConstraint), P(PgType)])
263            }
264            P(VirtualRelation::InformationKeyColumnUsage) => Some(&[
265                P(PgAttribute),
266                P(PgNamespace),
267                P(PgClass),
268                P(PgNamespace),
269                P(PgConstraint),
270            ]),
271            P(VirtualRelation::InformationConstraintColumnUsage) => Some(&[
272                P(PgNamespace),
273                P(PgClass),
274                P(PgAttribute),
275                P(PgDepend),
276                P(PgNamespace),
277                P(PgConstraint),
278                P(PgNamespace),
279                P(PgClass),
280                P(PgAttribute),
281                P(PgNamespace),
282                P(PgConstraint),
283                P(PgNamespace),
284                P(PgClass),
285                P(PgAttribute),
286                P(PgNamespace),
287                P(PgConstraint),
288            ]),
289            P(VirtualRelation::InformationConstraintTableUsage) => {
290                Some(&[P(PgConstraint), P(PgNamespace), P(PgClass), P(PgNamespace)])
291            }
292            _ => None,
293        }
294    }
295}
296
297#[cfg(test)]
298mod tests;