Skip to main content

kevy_sql/
plan.rs

1//! `plan` — compile a schema and report **every** query's fate, instead
2//! of stopping at the first one that cannot be served.
3//!
4//! [`compile`](crate::compile) is the build-time entry: one unservable
5//! view is a compile error, which is right when the output is commands
6//! you are about to apply. A migration plan is the other shape. The
7//! person reading it arrived with a schema and forty queries and wants
8//! one answer — *which of these work here, and what do the rest need?*
9//! Stopping at the first refusal answers that one fortieth of the way.
10//!
11//! The line between the two failure kinds is deliberate:
12//!
13//! * **A DDL error is still fatal.** If `CREATE TABLE` does not parse
14//!   there is no schema, and a plan against no schema is a fiction.
15//! * **A view that cannot be served is an entry, not an error** — that
16//!   is precisely what the plan exists to report. The refusal text
17//!   already names the `CREATE INDEX` that would fix it, so it is
18//!   carried verbatim rather than restated worse.
19
20use crate::{QueryCard, SqlError, lex, parse, schema, viewplan};
21
22/// Whether a declared query can be served, and by what.
23///
24/// ```
25/// let p = kevy_sql::plan(
26///     "CREATE TABLE t (id bigint PRIMARY KEY, n bigint);
27///      CREATE INDEX ON t (n);
28///      CREATE VIEW big AS SELECT * FROM t WHERE n >= 10;
29///      CREATE VIEW odd AS SELECT * FROM t WHERE id = 1;",
30/// )?;
31/// assert!(matches!(p.queries[0].served, kevy_sql::Served::View { .. }));
32/// assert_eq!(p.queries[0].served.paths(), Some(&["t.n".to_string()][..]));
33/// assert!(!p.queries[1].served.is_served());
34/// # Ok::<(), kevy_sql::SqlError>(())
35/// ```
36#[derive(Debug, Clone, PartialEq, Eq, Hash)]
37#[non_exhaustive]
38pub enum Served {
39    /// Served by the engine holding the whole query as a view.
40    ///
41    /// ```
42    /// let p = kevy_sql::plan(
43    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
44    ///      CREATE INDEX ON orders (user_id);
45    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
46    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
47    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
48    /// )?;
49    /// let kevy_sql::Served::View { argv, .. } = &p.queries[0].served else { unreachable!() };
50    /// assert_eq!(argv[..2], ["VIEW.CREATE", "mine"]);
51    /// # Ok::<(), kevy_sql::SqlError>(())
52    /// ```
53    View {
54        /// The `table.column` paths this query rides, in argv order.
55        ///
56        /// ```
57        /// let p = kevy_sql::plan(
58        ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
59        ///      CREATE INDEX ON orders (user_id);
60        ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
61        ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
62        ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
63        /// )?;
64        /// let kevy_sql::Served::View { paths, .. } = &p.queries[0].served else { unreachable!() };
65        /// assert_eq!(paths, &["orders.user_id"]);
66        /// # Ok::<(), kevy_sql::SqlError>(())
67        /// ```
68        paths: Vec<String>,
69        /// The `VIEW.CREATE` argv.
70        ///
71        /// ```
72        /// let p = kevy_sql::plan(
73        ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
74        ///      CREATE INDEX ON orders (user_id);
75        ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
76        ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
77        ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
78        /// )?;
79        /// let kevy_sql::Served::View { argv, .. } = &p.queries[0].served else { unreachable!() };
80        /// assert_eq!(argv.join(" "), "VIEW.CREATE mine QUERY orders.user_id EQ 7 ORDER BY orders.user_id");
81        /// # Ok::<(), kevy_sql::SqlError>(())
82        /// ```
83        argv: Vec<String>,
84    },
85    /// Served by a runtime template the application binds and sends.
86    ///
87    /// ```
88    /// let p = kevy_sql::plan(
89    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
90    ///      CREATE INDEX ON orders (user_id);
91    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
92    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
93    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
94    /// )?;
95    /// let kevy_sql::Served::Card { card, .. } = &p.queries[1].served else { unreachable!() };
96    /// assert_eq!(card.argv[..4], ["IDX.QUERY", "orders.user_id", "EQ", "$1"]);
97    /// # Ok::<(), kevy_sql::SqlError>(())
98    /// ```
99    Card {
100        /// The `table.column` paths this query rides, in argv order.
101        ///
102        /// ```
103        /// let p = kevy_sql::plan(
104        ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
105        ///      CREATE INDEX ON orders (user_id);
106        ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
107        ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
108        ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
109        /// )?;
110        /// let kevy_sql::Served::Card { paths, .. } = &p.queries[1].served else { unreachable!() };
111        /// assert_eq!(paths, &["orders.user_id"]);
112        /// # Ok::<(), kevy_sql::SqlError>(())
113        /// ```
114        paths: Vec<String>,
115        /// The query card.
116        ///
117        /// ```
118        /// let p = kevy_sql::plan(
119        ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
120        ///      CREATE INDEX ON orders (user_id);
121        ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
122        ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
123        ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
124        /// )?;
125        /// let kevy_sql::Served::Card { card, .. } = &p.queries[1].served else { unreachable!() };
126        /// assert_eq!((card.name.as_str(), card.params[0].column.as_str()), ("by_user", "user_id"));
127        /// # Ok::<(), kevy_sql::SqlError>(())
128        /// ```
129        card: QueryCard,
130    },
131    /// Not served, with the compiler's own refusal — which names the
132    /// alternative rather than only saying no.
133    ///
134    /// ```
135    /// let p = kevy_sql::plan(
136    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
137    ///      CREATE INDEX ON orders (user_id);
138    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
139    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
140    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
141    /// )?;
142    /// assert!(matches!(p.queries[2].served, kevy_sql::Served::Refused { .. }));
143    /// # Ok::<(), kevy_sql::SqlError>(())
144    /// ```
145    Refused {
146        /// The refusal, verbatim.
147        ///
148        /// ```
149        /// let p = kevy_sql::plan(
150        ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
151        ///      CREATE INDEX ON orders (user_id);
152        ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
153        ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
154        ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
155        /// )?;
156        /// let kevy_sql::Served::Refused { reason } = &p.queries[2].served else { unreachable!() };
157        /// assert!(reason.ends_with("add: CREATE INDEX ON orders (status)"));
158        /// # Ok::<(), kevy_sql::SqlError>(())
159        /// ```
160        reason: String,
161    },
162}
163
164impl Served {
165    /// Whether this query can be served as declared.
166    ///
167    /// ```
168    /// let p = kevy_sql::plan(
169    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
170    ///      CREATE INDEX ON orders (user_id);
171    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
172    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
173    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
174    /// )?;
175    /// let served: Vec<bool> = p.queries.iter().map(|q| q.served.is_served()).collect();
176    /// assert_eq!(served, [true, true, false]);
177    /// # Ok::<(), kevy_sql::SqlError>(())
178    /// ```
179    pub fn is_served(&self) -> bool {
180        self.paths().is_some()
181    }
182
183    /// The `table.column` paths a served query rides, in argv order;
184    /// `None` when it is refused.
185    ///
186    /// ```
187    /// let p = kevy_sql::plan(
188    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
189    ///      CREATE INDEX ON orders (user_id);
190    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
191    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
192    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
193    /// )?;
194    /// assert_eq!(p.queries[0].served.paths(), Some(&["orders.user_id".to_string()][..]));
195    /// assert_eq!(p.queries[2].served.paths(), None);
196    /// # Ok::<(), kevy_sql::SqlError>(())
197    /// ```
198    pub fn paths(&self) -> Option<&[String]> {
199        match self {
200            Served::View { paths, .. } | Served::Card { paths, .. } => Some(paths),
201            Served::Refused { .. } => None,
202        }
203    }
204}
205
206/// One query's row in the plan.
207///
208/// ```
209/// let p = kevy_sql::plan(
210///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
211///      CREATE INDEX ON orders (user_id);
212///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
213///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
214///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
215/// )?;
216/// let q = &p.queries[2];
217/// assert_eq!((q.name.as_str(), q.table.as_str(), q.line), ("paid", "orders", 5));
218/// assert!(!q.served.is_served());
219/// # Ok::<(), kevy_sql::SqlError>(())
220/// ```
221#[derive(Debug, Clone, PartialEq, Eq, Hash)]
222#[non_exhaustive]
223pub struct PlanEntry {
224    /// The view name.
225    ///
226    /// ```
227    /// let p = kevy_sql::plan(
228    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
229    ///      CREATE INDEX ON orders (user_id);
230    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
231    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
232    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
233    /// )?;
234    /// let names: Vec<&str> = p.queries.iter().map(|q| q.name.as_str()).collect();
235    /// assert_eq!(names, ["mine", "by_user", "paid"]);
236    /// # Ok::<(), kevy_sql::SqlError>(())
237    /// ```
238    pub name: String,
239    /// The table it reads.
240    ///
241    /// ```
242    /// let p = kevy_sql::plan(
243    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
244    ///      CREATE INDEX ON orders (user_id);
245    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
246    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
247    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
248    /// )?;
249    /// assert!(p.queries.iter().all(|q| q.table == "orders"));
250    /// # Ok::<(), kevy_sql::SqlError>(())
251    /// ```
252    pub table: String,
253    /// 1-based source line, so a refusal points back at the SQL.
254    ///
255    /// ```
256    /// let p = kevy_sql::plan(
257    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
258    ///      CREATE INDEX ON orders (user_id);
259    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
260    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
261    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
262    /// )?;
263    /// // the refused view is the fifth line of the SQL above
264    /// assert_eq!(p.queries[2].line, 5);
265    /// # Ok::<(), kevy_sql::SqlError>(())
266    /// ```
267    pub line: u32,
268    /// The verdict.
269    ///
270    /// ```
271    /// let p = kevy_sql::plan(
272    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
273    ///      CREATE INDEX ON orders (user_id);
274    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
275    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
276    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
277    /// )?;
278    /// assert!(p.queries[0].served.is_served());
279    /// # Ok::<(), kevy_sql::SqlError>(())
280    /// ```
281    pub served: Served,
282}
283
284/// A migration plan: what to declare, and what becomes of each query.
285///
286/// ```
287/// let p = kevy_sql::plan(
288///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
289///      CREATE INDEX ON orders (user_id);
290///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
291///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
292///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
293/// )?;
294/// assert_eq!(p.declares.len(), 1);
295/// assert_eq!(p.queries.len(), 3);
296/// assert_eq!(p.unserved(), 1);
297/// # Ok::<(), kevy_sql::SqlError>(())
298/// ```
299#[derive(Debug, Clone, PartialEq, Eq, Hash)]
300#[non_exhaustive]
301pub struct Plan {
302    /// `TABLE.DECLARE` argv per table, declaration order.
303    ///
304    /// ```
305    /// let p = kevy_sql::plan(
306    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
307    ///      CREATE INDEX ON orders (user_id);
308    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
309    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
310    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
311    /// )?;
312    /// assert_eq!(p.declares[0][..2], ["TABLE.DECLARE", "orders"]);
313    /// # Ok::<(), kevy_sql::SqlError>(())
314    /// ```
315    pub declares: Vec<Vec<String>>,
316    /// Every `CREATE VIEW`, served or not, declaration order.
317    ///
318    /// ```
319    /// let p = kevy_sql::plan(
320    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
321    ///      CREATE INDEX ON orders (user_id);
322    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
323    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
324    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
325    /// )?;
326    /// assert_eq!(p.queries.len(), 3);
327    /// # Ok::<(), kevy_sql::SqlError>(())
328    /// ```
329    pub queries: Vec<PlanEntry>,
330    /// Honest-mapping notes, as [`crate::Compilation::notes`].
331    ///
332    /// ```
333    /// let p = kevy_sql::plan("CREATE TABLE ev (id bigint PRIMARY KEY, at timestamp);")?;
334    /// assert!(p.notes.iter().any(|n| n.contains("ev.at: timestamp → str")));
335    /// # Ok::<(), kevy_sql::SqlError>(())
336    /// ```
337    pub notes: Vec<String>,
338    /// Tables (and stray indexes) that could NOT be declared:
339    /// `(name, named reason)`. The charter's migration bar reads
340    /// "every type either moved or named" — this is the named half.
341    ///
342    /// ```
343    /// let p = kevy_sql::plan(
344    ///     "CREATE TABLE users (id bigint PRIMARY KEY, email text);
345    ///      CREATE TABLE billing (id bigint PRIMARY KEY, amount money);",
346    /// )?;
347    /// assert_eq!(p.declares.len(), 1); // users still declares
348    /// assert_eq!(p.dropped[0].0, "billing");
349    /// assert!(p.dropped[0].1.contains("money"));
350    /// # Ok::<(), kevy_sql::SqlError>(())
351    /// ```
352    pub dropped: Vec<(String, String)>,
353}
354
355impl Plan {
356    /// How many queries cannot be served as declared.
357    ///
358    /// ```
359    /// let p = kevy_sql::plan(
360    ///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
361    ///      CREATE INDEX ON orders (user_id);
362    ///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
363    ///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
364    ///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
365    /// )?;
366    /// assert_eq!(p.unserved(), 1);
367    /// # Ok::<(), kevy_sql::SqlError>(())
368    /// ```
369    pub fn unserved(&self) -> usize {
370        self.queries.iter().filter(|q| !q.served.is_served()).count()
371    }
372}
373
374/// Plan a whole SQL file: DDL becomes declarations, each `CREATE VIEW`
375/// becomes an entry saying whether it can be served and by what.
376///
377/// Errors only on the schema itself — a file whose DDL does not parse
378/// has no plan. A view that cannot be served comes back as an entry.
379///
380/// ```
381/// let p = kevy_sql::plan(
382///     "CREATE TABLE orders (id bigint PRIMARY KEY, user_id bigint, status text);
383///      CREATE INDEX ON orders (user_id);
384///      CREATE VIEW mine AS SELECT * FROM orders WHERE user_id = 7;
385///      CREATE VIEW by_user AS SELECT * FROM orders WHERE user_id = $1;
386///      CREATE VIEW paid AS SELECT * FROM orders WHERE status = 'paid';",
387/// )?;
388/// // one refused view does not stop the other two from being planned
389/// assert_eq!(p.queries.len(), 3);
390/// assert_eq!(p.unserved(), 1);
391///
392/// // a schema that does not parse has no plan at all
393/// assert!(kevy_sql::plan("CREATE TABLE (").is_err());
394/// # Ok::<(), kevy_sql::SqlError>(())
395/// ```
396pub fn plan(sql: &str) -> Result<Plan, SqlError> {
397    let toks = lex::lex(sql)?;
398    let stmts = parse::parse_script(&toks)?;
399    let ((tables, views, mut notes), dropped) = schema::build_lenient(&stmts);
400    let declares: Vec<Vec<String>> = tables.iter().map(schema::declare_argv).collect();
401    let mut queries = Vec::with_capacity(views.len());
402    for v in &views {
403        let served = match tables.iter().find(|t| t.name == v.table) {
404            None => Served::Refused {
405                reason: match dropped.iter().find(|(n, _)| *n == v.table) {
406                    Some((_, why)) => {
407                        format!("its table '{}' was not declarable — {why}", v.table)
408                    }
409                    None => format!(
410                        "FROM unknown table '{}' — CREATE TABLE it first (this compiler is whole-file: declare, then view)",
411                        v.table
412                    ),
413                },
414            },
415            Some(t) => match viewplan::plan_view(v, t, &mut notes) {
416                Ok(viewplan::Planned::View(argv)) => {
417                    Served::View { paths: paths_in(&argv, &t.name), argv }
418                }
419                Ok(viewplan::Planned::Card(card)) => {
420                    Served::Card { paths: paths_in(&card.argv, &t.name), card }
421                }
422                Err(e) => Served::Refused { reason: e.message },
423            },
424        };
425        queries.push(PlanEntry {
426            name: v.name.clone(),
427            table: v.table.clone(),
428            line: v.line,
429            served,
430        });
431    }
432    Ok(Plan { declares, queries, notes, dropped })
433}
434
435/// The declared paths an argv rides, read off the argv rather than
436/// re-derived: both `VIEW.CREATE` and `IDX.QUERY` name their paths as
437/// `table.column`, so there is nothing here to infer.
438fn paths_in(argv: &[String], table: &str) -> Vec<String> {
439    let prefix = format!("{table}.");
440    let mut out: Vec<String> = Vec::new();
441    for a in argv {
442        if a.starts_with(&prefix) && !out.contains(a) {
443            out.push(a.clone());
444        }
445    }
446    out
447}