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}