mariadb_cli/sql/mod.rs
1//! Statement analysis: the layer that decides whether a statement may be sent.
2//!
3//! # The order is the whole design
4//!
5//! 1. [`mod@strip`] blanks comments, text literals and quoted identifiers. Every
6//! textual comparison in this layer runs over that output and never over the
7//! raw statement.
8//! 2. [`mod@parse`] reads the text into a syntax tree, inside a size ceiling and
9//! on a stack it owns, because the parser feature that guards recursion was
10//! switched off to keep the build free of a C toolchain.
11//! 3. [`mod@classify`] decides from that tree what the statement does, never
12//! from its first word.
13//! 4. [`guard`] applies the structural refusals over the tree, falling back to
14//! the blanked text only where the tree cannot carry the answer.
15//!
16//! A statement whose shape is not recognised is refused. It is never treated as
17//! a read, because that is the guess that lets a change through.
18//!
19//! # The defects this replaces
20//!
21//! Both reference implementations decide by prefix over raw text. That produces
22//! failures in both directions, and every one of them has a test here:
23//!
24//! * A legitimate query carrying a reserved word inside a literal is refused.
25//! * A statement whose first word is moved by a comment escapes the decision.
26//! * A text ending in a separator escapes the single-command refusal, so
27//! `SELECT 1; SELECT 2;` is admitted.
28//!
29//! # The other two members
30//!
31//! [`ident`] quotes an object name that introspection pastes into a statement,
32//! because a name cannot travel as a parameter. [`rewrite`] imposes this tool's
33//! own row ceiling on a caller's query without wrapping it in a derived table,
34//! which is what breaks an unnamed or a repeated column name.
35
36pub mod classify;
37pub mod guard;
38pub mod ident;
39pub mod parse;
40pub mod rewrite;
41pub mod strip;
42
43pub use classify::{analyze, classify, Analysis, Classification};
44pub use guard::{admit, Admission};
45pub use ident::{quote, quote_qualified};
46pub use parse::{parse, ParseLimits};
47pub use rewrite::with_limit;
48pub use strip::{strip, Stripped};
49
50#[cfg(test)]
51mod tests {
52 use super::*;
53
54 /// The three failures measured in the reference implementations, checked
55 /// against the assembled layer rather than against one module.
56 #[test]
57 fn the_measured_defects_of_the_reference_implementations_are_closed() {
58 // A row change hidden behind a comment is still a row change.
59 let hidden = admit("/* SELECT */ DELETE FROM users", ParseLimits::default())
60 .expect("a recognised statement");
61 assert_eq!(hidden.classification(), Classification::Change);
62
63 // A reserved word inside a literal does not refuse a legitimate query.
64 let literal = admit("SELECT 'DROP TABLE users' AS note", ParseLimits::default())
65 .expect("a legitimate query");
66 assert_eq!(literal.classification(), Classification::Read);
67
68 // Ending in a separator does not make two statements one.
69 let two = admit("SELECT 1; SELECT 2;", ParseLimits::default())
70 .expect_err("two statements are refused");
71 assert_eq!(two.code(), "sql.multiple_statements");
72 }
73
74 #[test]
75 fn a_name_pasted_into_a_statement_cannot_close_its_own_quoting() {
76 assert_eq!(
77 quote("t` ; DROP TABLE users; -- ").expect("a quotable name"),
78 "`t`` ; DROP TABLE users; -- `"
79 );
80 }
81
82 /// The bounds that replace the disabled parser feature carry through the
83 /// assembled layer, not only through the module that owns them.
84 #[test]
85 fn the_parse_bounds_reach_the_whole_layer() {
86 let tight = ParseLimits::new(16, parse::DEFAULT_PARSER_STACK_BYTES);
87 assert_eq!(
88 admit("SELECT 1 FROM a_very_long_table_name", tight)
89 .expect_err("the ceiling is enforced")
90 .code(),
91 "sql.too_large"
92 );
93 assert_eq!(
94 classify("SELECT 1", ParseLimits::new(64, 0)).expect("within the ceiling"),
95 Classification::Read
96 );
97 }
98
99 #[test]
100 fn a_ceiling_is_imposed_without_wrapping_the_callers_query() {
101 assert_eq!(
102 with_limit("SELECT a + 1 FROM t", 10, None, ParseLimits::default())
103 .expect("a query that accepts a ceiling"),
104 "SELECT a + 1 FROM t\nLIMIT 10"
105 );
106 }
107}