Skip to main content

valence_core/storage_layout/
diff.rs

1//! Desired vs inspected layout → additive ops + safe tweaks.
2
3use super::{FieldStorage, LayoutField, StorageLayout};
4use crate::error::{Error, Result};
5use crate::KnownEngines;
6
7fn inspect_compatible(live: FieldStorage, desired: FieldStorage) -> bool {
8    if live == desired {
9        return true;
10    }
11    // Coarse PRAGMA / information_schema mapping.
12    matches!(
13        (live, desired),
14        (
15            FieldStorage::String,
16            FieldStorage::String | FieldStorage::Date | FieldStorage::Json | FieldStorage::Currency
17        ) | (
18            FieldStorage::Json,
19            FieldStorage::Currency | FieldStorage::Json
20        ) | (FieldStorage::Integer, FieldStorage::Boolean)
21            | (FieldStorage::Boolean, FieldStorage::Integer)
22    )
23}
24
25/// One additive change to apply during sync.
26#[derive(Debug, Clone, PartialEq, Eq)]
27pub enum AdditiveOp {
28    /// Add a missing field/column.
29    AddField(LayoutField),
30    /// Create a unique index that is missing.
31    AddUniqueIndex { field: String },
32    /// Create a non-unique index that is missing.
33    AddIndex { field: String },
34}
35
36/// Nullability / DEFAULT changes that do not rewrite existing row payloads.
37#[derive(Debug, Clone, PartialEq, Eq)]
38pub enum SafeTweak {
39    /// Allow NULL (`DROP NOT NULL` on Postgres).
40    SetNullable { field: String },
41    /// Disallow NULL (`SET NOT NULL` on Postgres; fails if NULLs exist).
42    SetNotNull { field: String },
43    /// Set column DEFAULT from schema field default string.
44    SetDefault { field: String, value: String },
45    /// Clear column DEFAULT.
46    DropDefault { field: String },
47}
48
49/// Result of comparing desired layout to live physical layout.
50#[derive(Debug, Clone, Default, PartialEq, Eq)]
51pub struct LayoutDiff {
52    /// Additive field / index ops.
53    pub ops: Vec<AdditiveOp>,
54    /// Safe nullability / default tweaks.
55    pub tweaks: Vec<SafeTweak>,
56}
57
58fn engine_supports_nullability_tweaks(engine_id: &str) -> bool {
59    matches!(
60        engine_id,
61        KnownEngines::POSTGRES | KnownEngines::HYBRID_INDRA_SQL
62    )
63}
64
65fn engine_supports_default_tweaks(engine_id: &str) -> bool {
66    matches!(
67        engine_id,
68        KnownEngines::POSTGRES | KnownEngines::HYBRID_INDRA_SQL
69    )
70}
71
72/// Compute additive ops + safe tweaks to bring `live` toward `desired`.
73///
74/// Ship policy: refuse drops / renames / type changes (orphan live fields → Validation).
75/// SQLite cannot change nullability without a table rebuild → Validation.
76///
77/// # Errors
78///
79/// Returns [`Error::Validation`] when live has fields not in desired, incompatible types,
80/// or an unsupported safe tweak on this engine.
81pub fn additive_ops(desired: &StorageLayout, live: &StorageLayout) -> Result<LayoutDiff> {
82    layout_diff(desired, live, KnownEngines::SQLITE)
83}
84
85/// Like [`additive_ops`], but engine-aware for safe tweaks.
86///
87/// # Errors
88///
89/// Same as [`additive_ops`], plus engine-specific refuse for unsupported tweaks.
90pub fn layout_diff(
91    desired: &StorageLayout,
92    live: &StorageLayout,
93    engine_id: &str,
94) -> Result<LayoutDiff> {
95    for live_f in &live.fields {
96        if !desired.fields.iter().any(|d| d.name == live_f.name) {
97            return Err(Error::Validation(format!(
98                "sync_typed_table refuses drop of live field {}.{} (destructive sync is Future)",
99                live.table, live_f.name
100            )));
101        }
102        if let Some(d) = desired.fields.iter().find(|d| d.name == live_f.name) {
103            if d.storage != live_f.storage
104                && live_f.name != "id"
105                && !inspect_compatible(live_f.storage, d.storage)
106            {
107                return Err(Error::Validation(format!(
108                    "sync_typed_table refuses type change on {}.{} ({:?} → {:?})",
109                    live.table, live_f.name, live_f.storage, d.storage
110                )));
111            }
112        }
113    }
114
115    let mut ops = Vec::new();
116    let mut tweaks = Vec::new();
117    for d in &desired.fields {
118        if !live.fields.iter().any(|l| l.name == d.name) {
119            ops.push(AdditiveOp::AddField(d.clone()));
120            continue;
121        }
122        let live_f = live
123            .fields
124            .iter()
125            .find(|l| l.name == d.name)
126            .expect("live field present after membership check");
127        if d.unique && !live_f.unique {
128            ops.push(AdditiveOp::AddUniqueIndex {
129                field: d.name.clone(),
130            });
131        }
132        if d.indexed && !live_f.indexed && !d.unique {
133            ops.push(AdditiveOp::AddIndex {
134                field: d.name.clone(),
135            });
136        }
137
138        if d.name == "id" {
139            continue;
140        }
141
142        if d.nullable != live_f.nullable {
143            if !engine_supports_nullability_tweaks(engine_id) {
144                return Err(Error::Validation(format!(
145                    "sync_typed_table refuses nullability change on {}.{} on engine {engine_id} \
146                     (SQLite requires table rebuild — Future)",
147                    live.table, d.name
148                )));
149            }
150            if d.nullable {
151                tweaks.push(SafeTweak::SetNullable {
152                    field: d.name.clone(),
153                });
154            } else {
155                tweaks.push(SafeTweak::SetNotNull {
156                    field: d.name.clone(),
157                });
158            }
159        }
160
161        if engine_supports_default_tweaks(engine_id) {
162            match (&d.default, &live_f.default) {
163                (Some(want), live_def) if live_def.as_deref() != Some(want.as_str()) => {
164                    tweaks.push(SafeTweak::SetDefault {
165                        field: d.name.clone(),
166                        value: want.clone(),
167                    });
168                }
169                (None, Some(_)) => {
170                    tweaks.push(SafeTweak::DropDefault {
171                        field: d.name.clone(),
172                    });
173                }
174                _ => {}
175            }
176        }
177    }
178    Ok(LayoutDiff { ops, tweaks })
179}
180
181#[cfg(test)]
182mod tests {
183    use super::*;
184
185    fn field(name: &str, nullable: bool) -> LayoutField {
186        LayoutField {
187            name: name.into(),
188            storage: FieldStorage::String,
189            primary_key: name == "id",
190            nullable,
191            unique: name == "id",
192            indexed: false,
193            default: None,
194            record_table: None,
195        }
196    }
197
198    #[test]
199    fn add_missing_field() {
200        let desired = StorageLayout {
201            table: "t".into(),
202            fields: vec![
203                field("id", false),
204                field("name", true),
205                field("score", true),
206            ],
207        };
208        let live = StorageLayout {
209            table: "t".into(),
210            fields: vec![field("id", false), field("name", true)],
211        };
212        let diff = layout_diff(&desired, &live, KnownEngines::SQLITE).unwrap();
213        assert!(matches!(diff.ops[0], AdditiveOp::AddField(ref f) if f.name == "score"));
214        assert!(diff.tweaks.is_empty());
215    }
216
217    #[test]
218    fn refuse_orphan_live_field() {
219        let desired = StorageLayout {
220            table: "t".into(),
221            fields: vec![field("id", false), field("name", true)],
222        };
223        let live = StorageLayout {
224            table: "t".into(),
225            fields: vec![
226                field("id", false),
227                field("name", true),
228                field("legacy", true),
229            ],
230        };
231        let err = layout_diff(&desired, &live, KnownEngines::SQLITE).unwrap_err();
232        assert!(err.to_string().contains("refuses drop"));
233    }
234
235    #[test]
236    fn postgres_nullability_tweak() {
237        let desired = StorageLayout {
238            table: "t".into(),
239            fields: vec![field("id", false), field("name", true)],
240        };
241        let mut live_name = field("name", false);
242        live_name.nullable = false;
243        let live = StorageLayout {
244            table: "t".into(),
245            fields: vec![field("id", false), live_name],
246        };
247        let diff = layout_diff(&desired, &live, KnownEngines::POSTGRES).unwrap();
248        assert_eq!(
249            diff.tweaks,
250            vec![SafeTweak::SetNullable {
251                field: "name".into()
252            }]
253        );
254    }
255
256    #[test]
257    fn sqlite_nullability_refused() {
258        let desired = StorageLayout {
259            table: "t".into(),
260            fields: vec![field("id", false), field("name", true)],
261        };
262        let mut live_name = field("name", false);
263        live_name.nullable = false;
264        let live = StorageLayout {
265            table: "t".into(),
266            fields: vec![field("id", false), live_name],
267        };
268        let err = layout_diff(&desired, &live, KnownEngines::SQLITE).unwrap_err();
269        assert!(err.to_string().contains("nullability"));
270    }
271
272    #[test]
273    fn refuse_incompatible_type_change() {
274        let desired = StorageLayout {
275            table: "t".into(),
276            fields: vec![
277                field("id", false),
278                LayoutField {
279                    name: "score".into(),
280                    storage: FieldStorage::Integer,
281                    primary_key: false,
282                    nullable: true,
283                    unique: false,
284                    indexed: false,
285                    default: None,
286                    record_table: None,
287                },
288            ],
289        };
290        let live = StorageLayout {
291            table: "t".into(),
292            fields: vec![
293                field("id", false),
294                LayoutField {
295                    name: "score".into(),
296                    storage: FieldStorage::String,
297                    primary_key: false,
298                    nullable: true,
299                    unique: false,
300                    indexed: false,
301                    default: None,
302                    record_table: None,
303                },
304            ],
305        };
306        let err = layout_diff(&desired, &live, KnownEngines::SQLITE).unwrap_err();
307        assert!(
308            err.to_string().contains("refuses type change"),
309            "unexpected error: {err}"
310        );
311    }
312}