Skip to main content

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}