uqa_execution/catalog/foreign/
reference.rs1use 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
140pub(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;