Skip to main content

uqa_execution/catalog/foreign/
reference.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Foreign tables retain the server they named at creation, including after concurrent deletion or name reuse.
8
9use super::StoredForeignTable;
10use serde::{Deserialize, Serialize};
11use std::collections::BTreeMap;
12use uqa_sql::{catalog::foreign_server::ForeignServerDefinition, SQLError};
13use uqa_storage::{CatalogFacade, StorageBackendError, StorageBackendResult};
14
15const FORMAT_KEY: &str = "foreign-table-server-reference-format";
16const FORMAT_MARKER: &str = r#"{"version":2}"#;
17
18#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
19#[serde(deny_unknown_fields)]
20pub struct ForeignServerReference {
21    pub oid: u32,
22    pub object_id: [u8; 16],
23}
24
25impl From<&ForeignServerDefinition> for ForeignServerReference {
26    fn from(server: &ForeignServerDefinition) -> Self {
27        Self {
28            oid: server.metadata.oid,
29            object_id: server.metadata.object_id,
30        }
31    }
32}
33
34impl StoredForeignTable {
35    pub fn server_oid(&self) -> Result<u32, SQLError> {
36        self.server_reference
37            .map(|reference| reference.oid)
38            .ok_or_else(|| {
39                SQLError::Internal(format!(
40                    "foreign table `{}` has no server identity",
41                    self.name
42                ))
43            })
44    }
45
46    pub fn bound_server<'a>(
47        &self,
48        servers: &'a BTreeMap<String, ForeignServerDefinition>,
49    ) -> Result<&'a ForeignServerDefinition, SQLError> {
50        let oid = self.server_oid()?;
51        servers
52            .get(&self.server_name)
53            .filter(|server| Some(ForeignServerReference::from(*server)) == self.server_reference)
54            .ok_or_else(|| SQLError::Routine {
55                sqlstate: "XX000".into(),
56                message: format!("cache lookup failed for foreign server {oid}"),
57            })
58    }
59}
60
61pub fn validate_query_source(
62    catalog: &crate::catalog::CatalogReadView,
63    resolution: &crate::catalog::RelationNameResolution,
64    name: &str,
65) -> Result<(), SQLError> {
66    if let Some(table) = catalog.foreign_table_resolved(resolution, name)? {
67        let definitions = &catalog.snapshot().definitions;
68        table
69            .bound_server(&definitions.foreign_servers)?
70            .bound_wrapper(&definitions.foreign_wrappers)?
71            .require_handler()?;
72    }
73    Ok(())
74}
75
76pub(super) fn validate_schema_reference(
77    name: &str,
78    version: u8,
79    reference: Option<ForeignServerReference>,
80) -> StorageBackendResult<()> {
81    let valid = match (version, reference) {
82        (1, None) => true,
83        (2 | 3, Some(reference)) => reference.oid >= 16_384 && reference.object_id != [0; 16],
84        _ => false,
85    };
86    if valid {
87        Ok(())
88    } else {
89        Err(invalid(format!(
90            "foreign table `{name}` has invalid server identity for schema version {version}"
91        )))
92    }
93}
94
95pub(crate) fn check_format(catalog: &dyn CatalogFacade) -> StorageBackendResult<Option<u32>> {
96    let Some(marker) = catalog.get_metadata(FORMAT_KEY)? else {
97        return Ok(None);
98    };
99    let marker: serde_json::Value = serde_json::from_str(&marker)?;
100    for version in [1, 2] {
101        if marker == serde_json::json!({"version":version}) {
102            return Ok(Some(version));
103        }
104    }
105    Err(invalid(
106        "unsupported foreign-table server-reference format marker",
107    ))
108}
109
110pub(super) fn initialize_format(catalog: &dyn CatalogFacade) -> StorageBackendResult<()> {
111    catalog.set_metadata(FORMAT_KEY, FORMAT_MARKER)
112}
113
114pub(super) fn restore_format(
115    catalog: &dyn CatalogFacade,
116    allow_migration: bool,
117) -> StorageBackendResult<Option<u32>> {
118    let version = check_format(catalog)?;
119    if version != Some(2) && !allow_migration {
120        return Err(invalid(
121            "foreign-table option order requires an initial-open migration",
122        ));
123    }
124    Ok(version)
125}
126
127pub(super) fn validate_schema_format(
128    version: Option<u32>,
129    legacy: bool,
130    name: &str,
131) -> StorageBackendResult<()> {
132    if version == Some(2) && legacy {
133        return Err(invalid(format!(
134            "foreign table `{name}` has a legacy schema under the current option-order marker"
135        )));
136    }
137    Ok(())
138}
139
140/// Legacy names bind once, within complete initial restoration. Current references may name a concurrently deleted server and must never bind a replacement.
141pub(super) fn restore(
142    table: &mut StoredForeignTable,
143    servers: &BTreeMap<String, ForeignServerDefinition>,
144    current: bool,
145    allow_migration: bool,
146) -> StorageBackendResult<bool> {
147    if table.server_reference.is_some() {
148        if !current {
149            return Err(invalid(
150                "foreign-table server identity exists without its format marker",
151            ));
152        }
153        return Ok(false);
154    }
155    if current || !allow_migration {
156        return Err(invalid(format!(
157            "foreign table `{}` has no server identity and requires an initial-open migration",
158            table.name
159        )));
160    }
161    let server = servers.get(&table.server_name).ok_or_else(|| {
162        invalid(format!(
163            "foreign table `{}` references missing server `{}`",
164            table.name, table.server_name
165        ))
166    })?;
167    table.server_reference = Some(ForeignServerReference::from(server));
168    Ok(true)
169}
170
171fn invalid(message: impl Into<String>) -> StorageBackendError {
172    StorageBackendError::Other(message.into())
173}
174
175#[cfg(test)]
176mod tests;