razeri_plugin_contract/
constraint_enforcement.rs

1// Copyright (C) 2026 Gabriel Shea <gshea@ideapivot.com> - All Rights Reserved
2
3//! **Whether this engine actually checks the constraints it accepts** — the
4//! dialect's answer, and the one place the rendered DDL and the docs read it
5//! from.
6//!
7//! A `PRIMARY KEY` that is enforced and a `PRIMARY KEY` that is decoration look
8//! identical in a `CREATE TABLE`. On two of the engines Razeri renders for they
9//! are the second thing, and until this seam existed the only place that fact
10//! was written down was a book page:
11//!
12//! - **`BigQuery`** has the words for it. `PRIMARY KEY (x) NOT ENFORCED` is the
13//!   only legal spelling — a bare `PRIMARY KEY` is refused — so the engine
14//!   itself makes the declaration honest.
15//! - **`Redshift`** has no such words. It accepts `PRIMARY KEY`, `FOREIGN KEY`
16//!   and `UNIQUE`, enforces none of them, and there is no keyword to say so. A
17//!   reader of that DDL has no way to tell it apart from `PostgreSQL`'s, which
18//!   is the near-neighbour trap in its purest form.
19//!
20//! So the seam carries two things: the engine's own **keyword**, where it has
21//! one, and a **note** the renderer writes above the constraint list, where it
22//! does not. Both are the dialect's words.
23
24/// Whether the engine checks the key, unique and check constraints it accepts.
25///
26/// `#[non_exhaustive]`, on this module's whole family's rule: Razeri adds an
27/// arm when it has measured one.
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
29#[non_exhaustive]
30pub enum ConstraintEnforcement {
31    /// The engine rejects a row that violates a declared constraint. Eight of
32    /// Razeri's registered platforms, and the default: claiming an engine
33    /// checks nothing is the unusual assertion, and it is made deliberately,
34    /// one dialect at a time.
35    #[default]
36    Enforced,
37    /// **The engine accepts the declaration and checks nothing.** The
38    /// constraint is metadata — an optimizer hint, or documentation — and a
39    /// violating row is stored without complaint.
40    DeclaredOnly(DeclaredOnly),
41}
42
43impl ConstraintEnforcement {
44    /// The words appended to a rendered key constraint, or `""`.
45    ///
46    /// This is what [`crate::renderer::DdlRenderer::key_constraint_suffix`]
47    /// answers by default, so a dialect states enforcement once and the suffix
48    /// follows. Empty on an enforcing engine, and empty on a declaring engine
49    /// that has no keyword for it.
50    #[must_use]
51    pub const fn keyword(self) -> &'static str {
52        match self {
53            ConstraintEnforcement::DeclaredOnly(declared) => declared.keyword,
54            ConstraintEnforcement::Enforced => "",
55        }
56    }
57
58    /// The sentence the rendered DDL carries above a table's constraints, or
59    /// `None` where the engine enforces them.
60    ///
61    /// `None` on an engine whose *keyword* already says it: `NOT ENFORCED`
62    /// written on the constraint line is more precise than a comment above it,
63    /// and printing both would say the same thing twice in one statement.
64    #[must_use]
65    pub const fn ddl_note(self) -> Option<&'static str> {
66        match self {
67            ConstraintEnforcement::DeclaredOnly(declared) if declared.keyword.is_empty() => {
68                Some(declared.note)
69            }
70            _ => None,
71        }
72    }
73
74    /// Whether the engine leaves declared constraints unchecked — the fact the
75    /// platform docs and the conformance report read.
76    #[must_use]
77    pub const fn is_declared_only(self) -> bool {
78        matches!(self, ConstraintEnforcement::DeclaredOnly(_))
79    }
80}
81
82/// What a declaring-but-not-enforcing engine says about its own constraints.
83#[derive(Debug, Clone, Copy, PartialEq, Eq)]
84pub struct DeclaredOnly {
85    /// **The engine's own words, appended to every key constraint it renders**
86    /// — `BigQuery`'s `" NOT ENFORCED"`, leading space included, because the
87    /// suffix is concatenated onto the constraint text.
88    ///
89    /// `""` where the engine has no such keyword. That is not a lesser answer:
90    /// it is the honest one for `Redshift`, and it is what routes the fact into
91    /// [`ConstraintEnforcement::ddl_note`] instead.
92    pub keyword: &'static str,
93    /// **One sentence saying what this engine does with a declared
94    /// constraint**, written for whoever is reading the rendered DDL.
95    ///
96    /// Say what is and is not guaranteed, and where the guarantee has to come
97    /// from instead — a reader who learns only *"not enforced"* still does not
98    /// know whether their data is safe. It is rendered inside a SQL comment,
99    /// so keep it to prose and never spell a statement.
100    ///
101    /// Required even when `keyword` is non-empty: the docs read it in both
102    /// cases, and only the DDL note is skipped where the keyword already
103    /// speaks.
104    pub note: &'static str,
105}
106
107#[cfg(test)]
108mod tests {
109    use super::*;
110
111    /// The default is the enforcing engine, which is eight of Razeri's ten and
112    /// the safe thing to assume of a dialect that has not said.
113    #[test]
114    fn the_default_is_an_enforcing_engine() {
115        assert_eq!(ConstraintEnforcement::default(), ConstraintEnforcement::Enforced);
116        assert_eq!(ConstraintEnforcement::default().keyword(), "");
117        assert_eq!(ConstraintEnforcement::default().ddl_note(), None);
118        assert!(!ConstraintEnforcement::default().is_declared_only());
119    }
120
121    /// **The two shapes of "declared only", and the split between them is the
122    /// point of the type.** An engine with a keyword writes it on the
123    /// constraint; an engine without one gets the comment, and neither gets
124    /// both.
125    #[test]
126    fn a_keyword_speaks_on_the_constraint_and_a_note_speaks_above_it() {
127        let with_keyword = ConstraintEnforcement::DeclaredOnly(DeclaredOnly {
128            keyword: " NOT ENFORCED",
129            note: "keys here are optimizer metadata.",
130        });
131        assert_eq!(with_keyword.keyword(), " NOT ENFORCED");
132        assert_eq!(
133            with_keyword.ddl_note(),
134            None,
135            "the keyword is on the constraint line already — a comment saying it again is one \
136             statement making the same claim twice"
137        );
138        assert!(with_keyword.is_declared_only());
139
140        let without_keyword = ConstraintEnforcement::DeclaredOnly(DeclaredOnly {
141            keyword: "",
142            note: "this engine accepts the declaration and checks nothing.",
143        });
144        assert_eq!(without_keyword.keyword(), "");
145        assert_eq!(
146            without_keyword.ddl_note(),
147            Some("this engine accepts the declaration and checks nothing."),
148            "with no keyword the comment is the only place a reader of this DDL can learn it"
149        );
150        assert!(without_keyword.is_declared_only());
151    }
152}
razeri_plugin_contract/constraint_enforcement.rs

razeri_plugin_contract/
constraint_enforcement.rs
