mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Statement analysis: the layer that decides whether a statement may be sent.
//!
//! # The order is the whole design
//!
//! 1. [`mod@strip`] blanks comments, text literals and quoted identifiers. Every
//!    textual comparison in this layer runs over that output and never over the
//!    raw statement.
//! 2. [`mod@parse`] reads the text into a syntax tree, inside a size ceiling and
//!    on a stack it owns, because the parser feature that guards recursion was
//!    switched off to keep the build free of a C toolchain.
//! 3. [`mod@classify`] decides from that tree what the statement does, never
//!    from its first word.
//! 4. [`guard`] applies the structural refusals over the tree, falling back to
//!    the blanked text only where the tree cannot carry the answer.
//!
//! A statement whose shape is not recognised is refused. It is never treated as
//! a read, because that is the guess that lets a change through.
//!
//! # The defects this replaces
//!
//! Both reference implementations decide by prefix over raw text. That produces
//! failures in both directions, and every one of them has a test here:
//!
//! * A legitimate query carrying a reserved word inside a literal is refused.
//! * A statement whose first word is moved by a comment escapes the decision.
//! * A text ending in a separator escapes the single-command refusal, so
//!   `SELECT 1; SELECT 2;` is admitted.
//!
//! # The other two members
//!
//! [`ident`] quotes an object name that introspection pastes into a statement,
//! because a name cannot travel as a parameter. [`rewrite`] imposes this tool's
//! own row ceiling on a caller's query without wrapping it in a derived table,
//! which is what breaks an unnamed or a repeated column name.

pub mod classify;
pub mod guard;
pub mod ident;
pub mod parse;
pub mod rewrite;
pub mod strip;

pub use classify::{analyze, classify, Analysis, Classification};
pub use guard::{admit, Admission};
pub use ident::{quote, quote_qualified};
pub use parse::{parse, ParseLimits};
pub use rewrite::with_limit;
pub use strip::{strip, Stripped};

#[cfg(test)]
mod tests {
    use super::*;

    /// The three failures measured in the reference implementations, checked
    /// against the assembled layer rather than against one module.
    #[test]
    fn the_measured_defects_of_the_reference_implementations_are_closed() {
        // A row change hidden behind a comment is still a row change.
        let hidden = admit("/* SELECT */ DELETE FROM users", ParseLimits::default())
            .expect("a recognised statement");
        assert_eq!(hidden.classification(), Classification::Change);

        // A reserved word inside a literal does not refuse a legitimate query.
        let literal = admit("SELECT 'DROP TABLE users' AS note", ParseLimits::default())
            .expect("a legitimate query");
        assert_eq!(literal.classification(), Classification::Read);

        // Ending in a separator does not make two statements one.
        let two = admit("SELECT 1; SELECT 2;", ParseLimits::default())
            .expect_err("two statements are refused");
        assert_eq!(two.code(), "sql.multiple_statements");
    }

    #[test]
    fn a_name_pasted_into_a_statement_cannot_close_its_own_quoting() {
        assert_eq!(
            quote("t` ; DROP TABLE users; -- ").expect("a quotable name"),
            "`t`` ; DROP TABLE users; -- `"
        );
    }

    /// The bounds that replace the disabled parser feature carry through the
    /// assembled layer, not only through the module that owns them.
    #[test]
    fn the_parse_bounds_reach_the_whole_layer() {
        let tight = ParseLimits::new(16, parse::DEFAULT_PARSER_STACK_BYTES);
        assert_eq!(
            admit("SELECT 1 FROM a_very_long_table_name", tight)
                .expect_err("the ceiling is enforced")
                .code(),
            "sql.too_large"
        );
        assert_eq!(
            classify("SELECT 1", ParseLimits::new(64, 0)).expect("within the ceiling"),
            Classification::Read
        );
    }

    #[test]
    fn a_ceiling_is_imposed_without_wrapping_the_callers_query() {
        assert_eq!(
            with_limit("SELECT a + 1 FROM t", 10, None, ParseLimits::default())
                .expect("a query that accepts a ceiling"),
            "SELECT a + 1 FROM t\nLIMIT 10"
        );
    }
}