vibesql_parser/
lib.rs

1//! SQL:1999 Parser crate.
2//!
3//! Provides tokenization and parsing of SQL statements into the shared AST.
4//!
5//! # Arena-allocated Parser
6//!
7//! For performance-critical code paths, the [`arena_parser`] module provides
8//! an arena-based parser that allocates AST nodes from a bump allocator.
9//!
10//! # Arena Fallback Parsing
11//!
12//! The [`parse_with_arena_fallback`] function provides optimized parsing by
13//! using arena allocation for supported statement types (SELECT) while falling
14//! back to standard heap allocation for other statements. This provides the
15//! best of both worlds: arena performance where it helps most (complex queries)
16//! and full feature support for all SQL statements.
17//!
18//! ```
19//! use vibesql_parser::parse_with_arena_fallback;
20//!
21//! let stmt = parse_with_arena_fallback("SELECT * FROM users").unwrap();
22//! // Uses arena parsing internally, converts to standard Statement
23//! ```
24
25pub mod arena_parser;
26
27mod keywords;
28mod lexer;
29mod parser;
30#[cfg(test)]
31mod tests;
32mod token;
33
34pub use keywords::Keyword;
35pub use lexer::{Lexer, LexerError};
36pub use parser::{ParseError, Parser};
37pub use token::Token;
38
39use vibesql_ast::Statement;
40
41/// Parse SQL using arena allocation where supported, falling back to standard parsing.
42///
43/// This function provides optimized parsing by:
44/// 1. Detecting the statement type from the first token
45/// 2. Using arena-allocated parsing for SELECT statements
46/// 3. Converting arena AST to standard heap-allocated AST
47/// 4. Falling back to standard parsing for unsupported statement types
48///
49/// # Performance
50///
51/// Arena parsing can provide 10-15% improvement for complex SELECT statements
52/// due to reduced allocation overhead and better cache locality. The conversion
53/// to standard AST types adds minimal overhead.
54///
55/// # Supported Statement Types
56///
57/// Currently uses arena parsing for:
58/// - SELECT statements (including CTEs, subqueries, joins)
59///
60/// Falls back to standard parsing for:
61/// - INSERT, UPDATE, DELETE (arena support planned for future)
62/// - DDL statements (CREATE, ALTER, DROP)
63/// - Transaction statements (BEGIN, COMMIT, ROLLBACK)
64/// - Other SQL statements
65///
66/// # Example
67///
68/// ```
69/// use vibesql_parser::parse_with_arena_fallback;
70///
71/// // Uses arena parsing
72/// let select = parse_with_arena_fallback("SELECT * FROM users WHERE id = 1").unwrap();
73///
74/// // Falls back to standard parsing
75/// let insert = parse_with_arena_fallback("INSERT INTO users VALUES (1, 'Alice')").unwrap();
76/// ```
77pub fn parse_with_arena_fallback(sql: &str) -> Result<Statement, ParseError> {
78    // Tokenize to detect statement type
79    let mut lexer = Lexer::new(sql);
80    let tokens =
81        lexer.tokenize().map_err(|e| ParseError { message: format!("Lexer error: {}", e) })?;
82
83    // Check first token to determine statement type
84    if let Some(first_token) = tokens.first() {
85        if matches!(first_token, Token::Keyword(Keyword::Select) | Token::Keyword(Keyword::With)) {
86            // Use arena parsing for SELECT statements (including WITH CTEs)
87            match arena_parser::parse_select_to_owned(sql) {
88                Ok(select_stmt) => {
89                    return Ok(Statement::Select(Box::new(select_stmt)));
90                }
91                Err(_) => {
92                    // Arena parsing failed, fall back to standard parser
93                    // This can happen with edge cases the arena parser doesn't support yet
94                }
95            }
96        }
97    }
98
99    // Fall back to standard parser for all other statements
100    // or if arena parsing failed
101    Parser::parse_sql(sql)
102}
103
104#[cfg(test)]
105mod arena_fallback_tests {
106    use super::*;
107
108    #[test]
109    fn test_arena_fallback_simple_select() {
110        let result = parse_with_arena_fallback("SELECT * FROM users");
111        assert!(result.is_ok());
112        assert!(matches!(result.unwrap(), Statement::Select(_)));
113    }
114
115    #[test]
116    fn test_arena_fallback_select_with_where() {
117        let result = parse_with_arena_fallback("SELECT id, name FROM users WHERE active = TRUE");
118        assert!(result.is_ok());
119        assert!(matches!(result.unwrap(), Statement::Select(_)));
120    }
121
122    #[test]
123    fn test_arena_fallback_select_with_cte() {
124        let result = parse_with_arena_fallback(
125            "WITH active_users AS (SELECT * FROM users WHERE active = TRUE) \
126             SELECT * FROM active_users",
127        );
128        assert!(result.is_ok());
129        assert!(matches!(result.unwrap(), Statement::Select(_)));
130    }
131
132    #[test]
133    fn test_arena_fallback_insert() {
134        let result = parse_with_arena_fallback("INSERT INTO users (id, name) VALUES (1, 'Alice')");
135        assert!(result.is_ok());
136        assert!(matches!(result.unwrap(), Statement::Insert(_)));
137    }
138
139    #[test]
140    fn test_arena_fallback_update() {
141        let result = parse_with_arena_fallback("UPDATE users SET name = 'Bob' WHERE id = 1");
142        assert!(result.is_ok());
143        assert!(matches!(result.unwrap(), Statement::Update(_)));
144    }
145
146    #[test]
147    fn test_arena_fallback_delete() {
148        let result = parse_with_arena_fallback("DELETE FROM users WHERE id = 1");
149        assert!(result.is_ok());
150        assert!(matches!(result.unwrap(), Statement::Delete(_)));
151    }
152
153    #[test]
154    fn test_arena_fallback_create_table() {
155        let result = parse_with_arena_fallback("CREATE TABLE users (id INT PRIMARY KEY)");
156        assert!(result.is_ok());
157        assert!(matches!(result.unwrap(), Statement::CreateTable(_)));
158    }
159}
vibesql_parser/lib.rs

vibesql_parser/
lib.rs
