minidb-sql 1.3.0__py3-none-any.whl

minidb_sql/parser.py

@@ -0,0 +1,1278 @@
+"""SQL parser for MiniDB."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import InvalidQueryError, SyntaxError_
+from .types import ColumnType, TokenType
+
+
+@dataclass
+class Token:
+    """Represents a single token from the lexer."""
+
+    type: TokenType
+    value: Any
+    position: int
+
+
+@dataclass
+class ParamPlaceholder:
+    """Sentinel for a ? parameter that is bound after parse."""
+
+
+@dataclass
+class Condition:
+    """Represents a WHERE condition."""
+
+    column: str
+    operator: str  # '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'IN', 'IS NULL', 'IS NOT NULL'
+    value: Any
+    table_alias: str | None = None  # For JOIN column references
+    negated: bool = False
+
+
+@dataclass
+class WhereClause:
+    """Represents a WHERE clause with AND/OR logic."""
+
+    conditions: list  # List of Condition or WhereClause (nested)
+    operator: str = 'AND'  # 'AND' or 'OR'
+
+    def and_conjuncts(self) -> list[Condition]:
+        """AND predicates, including a comparison wrapped in parentheses.
+
+        A parenthesized comparison is its own WhereClause. Nested OR is a
+        different predicate and must not become an index probe.
+        """
+        if self.operator != 'AND':
+            return []
+        found: list[Condition] = []
+        for cond in self.conditions:
+            if isinstance(cond, Condition):
+                found.append(cond)
+            elif isinstance(cond, WhereClause) and cond.operator == 'AND':
+                found.extend(cond.and_conjuncts())
+        return found
+
+
+@dataclass
+class JoinClause:
+    """Represents a JOIN clause."""
+
+    table: str
+    left_column: str
+    right_column: str
+    join_type: str = 'INNER'  # 'INNER', 'LEFT', 'RIGHT'
+    left_table: str | None = None
+    right_table: str | None = None
+
+
+@dataclass
+class OrderByItem:
+    """Represents an ORDER BY item."""
+
+    column: str
+    direction: str = 'ASC'
+    table_alias: str | None = None
+
+
+@dataclass
+class CaseResult:
+    """A THEN or ELSE value. column is set for a column reference."""
+
+    literal: Any = None
+    column: str | None = None
+    table_alias: str | None = None
+
+
+@dataclass
+class CaseWhen:
+    """One searched WHEN arm. condition uses the WHERE grammar."""
+
+    condition: WhereClause
+    result: CaseResult
+
+
+@dataclass
+class CaseExpr:
+    """Searched CASE. else_result None means no ELSE, which is NULL."""
+
+    whens: list[CaseWhen]
+    else_result: CaseResult | None = None
+
+
+@dataclass
+class AggregateFunction:
+    """Represents an aggregate function call."""
+
+    function: str  # 'COUNT', 'SUM', 'AVG', 'MIN', 'MAX'
+    column: str  # Column name or '*' for COUNT(*)
+    alias: str | None = None
+
+
+@dataclass
+class SelectColumn:
+    """Represents a column in a SELECT statement."""
+
+    name: str  # Column name or '*'
+    table_alias: str | None = None
+    aggregate: AggregateFunction | None = None
+    alias: str | None = None
+    case: CaseExpr | None = None
+
+
+@dataclass
+class SelectQuery:
+    """Represents a parsed SELECT query."""
+
+    columns: list[SelectColumn]
+    table: str
+    where: WhereClause | None = None
+    order_by: list[OrderByItem] = field(default_factory=list)
+    group_by: list[str] = field(default_factory=list)
+    having: WhereClause | None = None
+    limit: int | None = None
+    joins: list[JoinClause] = field(default_factory=list)
+    distinct: bool = False
+
+
+@dataclass
+class InsertQuery:
+    """Represents a parsed INSERT query."""
+
+    table: str
+    columns: list[str]
+    values: list[Any]
+
+
+@dataclass
+class UpdateQuery:
+    """Represents a parsed UPDATE query."""
+
+    table: str
+    set_clause: dict[str, Any]
+    where: WhereClause | None = None
+
+
+@dataclass
+class DeleteQuery:
+    """Represents a parsed DELETE query."""
+
+    table: str
+    where: WhereClause | None = None
+
+
+@dataclass
+class ColumnDef:
+    """Represents a column definition in CREATE TABLE."""
+
+    name: str
+    type: ColumnType
+    primary_key: bool = False
+    nullable: bool = True
+
+
+@dataclass
+class CreateTableQuery:
+    """Represents a parsed CREATE TABLE query."""
+
+    table: str
+    columns: list[ColumnDef]
+
+
+@dataclass
+class DropTableQuery:
+    """Represents a parsed DROP TABLE query."""
+
+    table: str
+
+
+@dataclass
+class BeginQuery:
+    """Represents a parsed BEGIN statement."""
+
+
+@dataclass
+class CommitQuery:
+    """Represents a parsed COMMIT statement."""
+
+
+@dataclass
+class RollbackQuery:
+    """Represents a parsed ROLLBACK statement."""
+
+
+class Lexer:
+    """Tokenizes SQL queries."""
+
+    KEYWORDS = {
+        'SELECT': TokenType.SELECT,
+        'FROM': TokenType.FROM,
+        'WHERE': TokenType.WHERE,
+        'INSERT': TokenType.INSERT,
+        'INTO': TokenType.INTO,
+        'VALUES': TokenType.VALUES,
+        'UPDATE': TokenType.UPDATE,
+        'SET': TokenType.SET,
+        'DELETE': TokenType.DELETE,
+        'CREATE': TokenType.CREATE,
+        'TABLE': TokenType.TABLE,
+        'DROP': TokenType.DROP,
+        'ORDER': TokenType.ORDER,
+        'BY': TokenType.BY,
+        'GROUP': TokenType.GROUP,
+        'JOIN': TokenType.JOIN,
+        'INNER': TokenType.INNER,
+        'LEFT': TokenType.LEFT,
+        'RIGHT': TokenType.RIGHT,
+        'ON': TokenType.ON,
+        'AND': TokenType.AND,
+        'OR': TokenType.OR,
+        'NOT': TokenType.NOT,
+        'IN': TokenType.IN,
+        'LIKE': TokenType.LIKE,
+        'ASC': TokenType.ASC,
+        'DESC': TokenType.DESC,
+        'PRIMARY': TokenType.PRIMARY,
+        'KEY': TokenType.KEY,
+        'NULL': TokenType.NULL,
+        'IS': TokenType.IS,
+        'LIMIT': TokenType.LIMIT,
+        'AS': TokenType.AS,
+        'DISTINCT': TokenType.DISTINCT,
+        'HAVING': TokenType.HAVING,
+        'CASE': TokenType.CASE,
+        'WHEN': TokenType.WHEN,
+        'THEN': TokenType.THEN,
+        'ELSE': TokenType.ELSE,
+        'END': TokenType.END,
+        'BEGIN': TokenType.BEGIN,
+        'COMMIT': TokenType.COMMIT,
+        'ROLLBACK': TokenType.ROLLBACK,
+    }
+
+    def __init__(self, sql: str):
+        self.sql = sql
+        self.pos = 0
+        self.tokens: list[Token] = []
+
+    def tokenize(self) -> list[Token]:
+        """Tokenize the SQL string."""
+        while self.pos < len(self.sql):
+            self._skip_whitespace()
+            if self.pos >= len(self.sql):
+                break
+
+            char = self.sql[self.pos]
+
+            # String literal
+            if char in ('"', "'"):
+                self._read_string(char)
+            # Number
+            elif char.isdigit() or (char == '-' and self.pos + 1 < len(self.sql) and self.sql[self.pos + 1].isdigit()):
+                self._read_number()
+            # Identifier or keyword
+            elif char.isalpha() or char == '_':
+                self._read_identifier()
+            # Operators and punctuation
+            elif char == '=':
+                self.tokens.append(Token(TokenType.EQUALS, '=', self.pos))
+                self.pos += 1
+            elif char == '!':
+                if self.pos + 1 < len(self.sql) and self.sql[self.pos + 1] == '=':
+                    self.tokens.append(Token(TokenType.NOT_EQUALS, '!=', self.pos))
+                    self.pos += 2
+                else:
+                    raise SyntaxError_("Unexpected character '!'", self.pos)
+            elif char == '>':
+                if self.pos + 1 < len(self.sql) and self.sql[self.pos + 1] == '=':
+                    self.tokens.append(Token(TokenType.GREATER_EQUAL, '>=', self.pos))
+                    self.pos += 2
+                else:
+                    self.tokens.append(Token(TokenType.GREATER, '>', self.pos))
+                    self.pos += 1
+            elif char == '<':
+                if self.pos + 1 < len(self.sql) and self.sql[self.pos + 1] == '=':
+                    self.tokens.append(Token(TokenType.LESS_EQUAL, '<=', self.pos))
+                    self.pos += 2
+                else:
+                    self.tokens.append(Token(TokenType.LESS, '<', self.pos))
+                    self.pos += 1
+            elif char == ',':
+                self.tokens.append(Token(TokenType.COMMA, ',', self.pos))
+                self.pos += 1
+            elif char == '.':
+                self.tokens.append(Token(TokenType.DOT, '.', self.pos))
+                self.pos += 1
+            elif char == '(':
+                self.tokens.append(Token(TokenType.LPAREN, '(', self.pos))
+                self.pos += 1
+            elif char == ')':
+                self.tokens.append(Token(TokenType.RPAREN, ')', self.pos))
+                self.pos += 1
+            elif char == ';':
+                self.tokens.append(Token(TokenType.SEMICOLON, ';', self.pos))
+                self.pos += 1
+            elif char == '*':
+                self.tokens.append(Token(TokenType.STAR, '*', self.pos))
+                self.pos += 1
+            elif char == '?':
+                self.tokens.append(Token(TokenType.PLACEHOLDER, '?', self.pos))
+                self.pos += 1
+            elif char == '-' and self.pos + 1 < len(self.sql) and self.sql[self.pos + 1] == '-':
+                self._skip_line_comment()
+            elif char == '/' and self.pos + 1 < len(self.sql) and self.sql[self.pos + 1] == '*':
+                self._skip_block_comment()
+            else:
+                raise SyntaxError_(f"Unexpected character: '{char}'", self.pos)
+
+        self.tokens.append(Token(TokenType.EOF, None, self.pos))
+        return self.tokens
+
+    def _skip_line_comment(self) -> None:
+        """Skip a -- comment through the end of the line."""
+        self.pos += 2
+        while self.pos < len(self.sql) and self.sql[self.pos] not in '\n\r':
+            self.pos += 1
+
+    def _skip_block_comment(self) -> None:
+        """Skip a /* */ comment. An unclosed comment is a syntax error."""
+        start = self.pos
+        self.pos += 2
+        while self.pos + 1 < len(self.sql):
+            if self.sql[self.pos] == '*' and self.sql[self.pos + 1] == '/':
+                self.pos += 2
+                return
+            self.pos += 1
+        raise SyntaxError_('Unterminated block comment', start)
+
+    def _skip_whitespace(self):
+        """Skip whitespace characters."""
+        while self.pos < len(self.sql) and self.sql[self.pos].isspace():
+            self.pos += 1
+
+    def _read_string(self, quote_char: str):
+        """Read a string literal."""
+        start = self.pos
+        self.pos += 1  # Skip opening quote
+        value = []
+
+        while self.pos < len(self.sql):
+            char = self.sql[self.pos]
+            if char == quote_char:
+                # Check for escaped quote
+                if self.pos + 1 < len(self.sql) and self.sql[self.pos + 1] == quote_char:
+                    value.append(quote_char)
+                    self.pos += 2
+                else:
+                    self.pos += 1  # Skip closing quote
+                    break
+            elif char == '\\' and self.pos + 1 < len(self.sql):
+                # Handle escape sequences
+                next_char = self.sql[self.pos + 1]
+                if next_char == 'n':
+                    value.append('\n')
+                elif next_char == 't':
+                    value.append('\t')
+                elif next_char == '\\':
+                    value.append('\\')
+                elif next_char == quote_char:
+                    value.append(quote_char)
+                else:
+                    value.append(next_char)
+                self.pos += 2
+            else:
+                value.append(char)
+                self.pos += 1
+        else:
+            raise SyntaxError_('Unterminated string literal', start)
+
+        self.tokens.append(Token(TokenType.STRING_LITERAL, ''.join(value), start))
+
+    def _read_number(self):
+        """Read a numeric literal."""
+        start = self.pos
+        value = []
+
+        if self.sql[self.pos] == '-':
+            value.append('-')
+            self.pos += 1
+
+        while self.pos < len(self.sql) and self.sql[self.pos].isdigit():
+            value.append(self.sql[self.pos])
+            self.pos += 1
+
+        # Check for decimal
+        if self.pos < len(self.sql) and self.sql[self.pos] == '.':
+            value.append('.')
+            self.pos += 1
+            while self.pos < len(self.sql) and self.sql[self.pos].isdigit():
+                value.append(self.sql[self.pos])
+                self.pos += 1
+            self.tokens.append(Token(TokenType.FLOAT_LITERAL, float(''.join(value)), start))
+        else:
+            self.tokens.append(Token(TokenType.INTEGER_LITERAL, int(''.join(value)), start))
+
+    def _read_identifier(self):
+        """Read an identifier or keyword."""
+        start = self.pos
+        value = []
+
+        while self.pos < len(self.sql) and (self.sql[self.pos].isalnum() or self.sql[self.pos] == '_'):
+            value.append(self.sql[self.pos])
+            self.pos += 1
+
+        identifier = ''.join(value)
+        upper = identifier.upper()
+
+        # Check for keywords
+        if upper in self.KEYWORDS:
+            self.tokens.append(Token(self.KEYWORDS[upper], upper, start))
+        # Check for boolean literals
+        elif upper == 'TRUE':
+            self.tokens.append(Token(TokenType.BOOLEAN_LITERAL, True, start))
+        elif upper == 'FALSE':
+            self.tokens.append(Token(TokenType.BOOLEAN_LITERAL, False, start))
+        else:
+            self.tokens.append(Token(TokenType.IDENTIFIER, identifier, start))
+
+
+class Parser:
+    """Parses tokenized SQL queries."""
+
+    def __init__(self, tokens: list[Token]):
+        self.tokens = tokens
+        self.pos = 0
+        self._paren_depth = 0
+
+    def parse(
+        self,
+    ) -> (
+        SelectQuery
+        | InsertQuery
+        | UpdateQuery
+        | DeleteQuery
+        | CreateTableQuery
+        | DropTableQuery
+        | BeginQuery
+        | CommitQuery
+        | RollbackQuery
+    ):
+        """Parse the token stream into a query object."""
+        token = self._current()
+
+        if token.type == TokenType.SELECT:
+            return self._parse_select()
+        elif token.type == TokenType.INSERT:
+            return self._parse_insert()
+        elif token.type == TokenType.UPDATE:
+            return self._parse_update()
+        elif token.type == TokenType.DELETE:
+            return self._parse_delete()
+        elif token.type == TokenType.CREATE:
+            return self._parse_create()
+        elif token.type == TokenType.DROP:
+            return self._parse_drop()
+        elif token.type == TokenType.BEGIN:
+            return self._parse_begin()
+        elif token.type == TokenType.COMMIT:
+            return self._parse_commit()
+        elif token.type == TokenType.ROLLBACK:
+            return self._parse_rollback()
+        else:
+            raise SyntaxError_(f'Unexpected token: {token.value}', token.position)
+
+    def _current(self) -> Token:
+        """Get the current token."""
+        return self.tokens[self.pos] if self.pos < len(self.tokens) else self.tokens[-1]
+
+    def _peek(self, offset: int = 1) -> Token:
+        """Peek at a future token."""
+        pos = self.pos + offset
+        return self.tokens[pos] if pos < len(self.tokens) else self.tokens[-1]
+
+    def _advance(self) -> Token:
+        """Advance to the next token and return the previous one."""
+        token = self._current()
+        self.pos += 1
+        return token
+
+    def _expect(self, token_type: TokenType) -> Token:
+        """Expect a specific token type."""
+        token = self._current()
+        if token.type != token_type:
+            raise SyntaxError_(f'Expected {token_type.name}, got {token.type.name}', token.position)
+        return self._advance()
+
+    def _match(self, *token_types: TokenType) -> bool:
+        """Check if current token matches any of the given types."""
+        return self._current().type in token_types
+
+    def _expect_end(self) -> None:
+        """Consume an optional semicolon, then require end of input."""
+        if self._match(TokenType.SEMICOLON):
+            self._advance()
+        token = self._current()
+        if token.type != TokenType.EOF:
+            raise SyntaxError_(f'Unexpected token: {token.value}', token.position)
+
+    def _parse_select(self) -> SelectQuery:
+        """Parse a SELECT query."""
+        self._expect(TokenType.SELECT)
+
+        distinct = False
+        if self._match(TokenType.DISTINCT):
+            self._advance()
+            distinct = True
+
+        # Parse columns
+        columns = self._parse_select_columns()
+
+        # FROM clause
+        self._expect(TokenType.FROM)
+        table_token = self._expect(TokenType.IDENTIFIER)
+        table = table_token.value
+
+        # JOIN clauses
+        joins = []
+        while self._match(TokenType.JOIN, TokenType.INNER, TokenType.LEFT, TokenType.RIGHT):
+            joins.append(self._parse_join())
+
+        # WHERE clause
+        where = None
+        if self._match(TokenType.WHERE):
+            self._advance()
+            where = self._parse_where()
+
+        # GROUP BY clause
+        group_by = []
+        if self._match(TokenType.GROUP):
+            self._advance()
+            self._expect(TokenType.BY)
+            group_by = self._parse_group_by()
+
+        # HAVING clause
+        having = None
+        if self._match(TokenType.HAVING):
+            self._advance()
+            having = self._parse_where()
+
+        # ORDER BY clause
+        order_by = []
+        if self._match(TokenType.ORDER):
+            self._advance()
+            self._expect(TokenType.BY)
+            order_by = self._parse_order_by()
+
+        # LIMIT clause
+        limit = None
+        if self._match(TokenType.LIMIT):
+            self._advance()
+            limit_token = self._expect(TokenType.INTEGER_LITERAL)
+            limit = limit_token.value
+
+        self._expect_end()
+
+        return SelectQuery(
+            columns=columns,
+            table=table,
+            where=where,
+            order_by=order_by,
+            group_by=group_by,
+            having=having,
+            limit=limit,
+            joins=joins,
+            distinct=distinct,
+        )
+
+    def _parse_select_columns(self) -> list[SelectColumn]:
+        """Parse SELECT column list."""
+        columns = []
+
+        while True:
+            col = self._parse_select_column()
+            columns.append(col)
+
+            if not self._match(TokenType.COMMA):
+                break
+            self._advance()
+
+        return columns
+
+    def _parse_select_column(self) -> SelectColumn:
+        """Parse a single SELECT column."""
+        if self._match(TokenType.CASE):
+            return self._parse_case_column()
+
+        # Check for aggregate functions
+        if self._match(TokenType.IDENTIFIER):
+            name = self._current().value.upper()
+            if name in ('COUNT', 'SUM', 'AVG', 'MIN', 'MAX'):
+                return self._parse_aggregate_column()
+
+        # Check for *
+        if self._match(TokenType.STAR):
+            self._advance()
+            return SelectColumn(name='*')
+
+        # Check for table.column or just column
+        table_alias = None
+        col_name = self._expect(TokenType.IDENTIFIER).value
+
+        if self._match(TokenType.DOT):
+            self._advance()
+            if self._match(TokenType.STAR):
+                self._advance()
+                return SelectColumn(name='*', table_alias=col_name)
+            table_alias = col_name
+            col_name = self._expect(TokenType.IDENTIFIER).value
+
+        alias = None
+        if self._match(TokenType.AS):
+            self._advance()
+            alias = self._expect(TokenType.IDENTIFIER).value
+        elif self._match(TokenType.IDENTIFIER):
+            alias = self._advance().value
+
+        return SelectColumn(name=col_name, table_alias=table_alias, alias=alias)
+
+    def _parse_aggregate_column(self) -> SelectColumn:
+        """Parse an aggregate function column."""
+        func_name = self._advance().value.upper()
+        self._expect(TokenType.LPAREN)
+
+        table_alias = None
+        if self._match(TokenType.STAR):
+            self._advance()
+            col_name = '*'
+        else:
+            col_name = self._expect(TokenType.IDENTIFIER).value
+            # Check for table.column syntax
+            if self._match(TokenType.DOT):
+                self._advance()
+                table_alias = col_name
+                col_name = self._expect(TokenType.IDENTIFIER).value
+
+        self._expect(TokenType.RPAREN)
+
+        alias = None
+        if self._match(TokenType.AS):
+            self._advance()
+            alias = self._expect(TokenType.IDENTIFIER).value
+        elif self._match(TokenType.IDENTIFIER):
+            alias = self._advance().value
+
+        return SelectColumn(
+            name=col_name,
+            table_alias=table_alias,
+            aggregate=AggregateFunction(function=func_name, column=col_name, alias=alias),
+            alias=alias,
+        )
+
+    def _parse_case_column(self) -> SelectColumn:
+        """Parse CASE WHEN ... THEN ... [ELSE ...] END [AS alias]."""
+        self._expect(TokenType.CASE)
+        if not self._match(TokenType.WHEN):
+            token = self._current()
+            raise SyntaxError_(f'Expected WHEN, got {token.type.name}', token.position)
+
+        whens: list[CaseWhen] = []
+        while self._match(TokenType.WHEN):
+            self._advance()
+            condition = self._parse_or()
+            self._expect(TokenType.THEN)
+            whens.append(CaseWhen(condition=condition, result=self._parse_case_result()))
+
+        else_result = None
+        if self._match(TokenType.ELSE):
+            self._advance()
+            else_result = self._parse_case_result()
+        self._expect(TokenType.END)
+
+        alias = None
+        if self._match(TokenType.AS):
+            self._advance()
+            alias = self._expect(TokenType.IDENTIFIER).value
+        elif self._match(TokenType.IDENTIFIER):
+            alias = self._advance().value
+
+        return SelectColumn(name='CASE', alias=alias, case=CaseExpr(whens=whens, else_result=else_result))
+
+    def _parse_case_result(self) -> CaseResult:
+        """Parse a THEN or ELSE result: literal, parameter, or column."""
+        token = self._current()
+        if token.type in (
+            TokenType.STRING_LITERAL,
+            TokenType.INTEGER_LITERAL,
+            TokenType.FLOAT_LITERAL,
+            TokenType.BOOLEAN_LITERAL,
+            TokenType.NULL,
+            TokenType.PLACEHOLDER,
+        ):
+            return CaseResult(literal=self._parse_value())
+        if token.type == TokenType.IDENTIFIER:
+            name = self._advance().value
+            table_alias = None
+            if self._match(TokenType.DOT):
+                self._advance()
+                table_alias = name
+                name = self._expect(TokenType.IDENTIFIER).value
+            return CaseResult(column=name, table_alias=table_alias)
+        raise SyntaxError_(f'Expected literal value, got {token.type.name}', token.position)
+
+    def _parse_join(self) -> JoinClause:
+        """Parse a JOIN clause."""
+        join_type = 'INNER'
+
+        if self._match(TokenType.LEFT):
+            join_type = 'LEFT'
+            self._advance()
+        elif self._match(TokenType.RIGHT):
+            join_type = 'RIGHT'
+            self._advance()
+        elif self._match(TokenType.INNER):
+            self._advance()
+
+        self._expect(TokenType.JOIN)
+        right_table = self._expect(TokenType.IDENTIFIER).value
+
+        self._expect(TokenType.ON)
+
+        # Parse join condition: left_col = right_col
+        left_col = self._expect(TokenType.IDENTIFIER).value
+        left_table = None
+        if self._match(TokenType.DOT):
+            self._advance()
+            left_table = left_col
+            left_col = self._expect(TokenType.IDENTIFIER).value
+
+        self._expect(TokenType.EQUALS)
+
+        right_col = self._expect(TokenType.IDENTIFIER).value
+        right_table_alias = None
+        if self._match(TokenType.DOT):
+            self._advance()
+            right_table_alias = right_col
+            right_col = self._expect(TokenType.IDENTIFIER).value
+
+        return JoinClause(
+            table=right_table,
+            left_column=left_col,
+            right_column=right_col,
+            join_type=join_type,
+            left_table=left_table,
+            right_table=right_table_alias,
+        )
+
+    def _parse_where(self) -> WhereClause:
+        """Parse a WHERE clause with AND binding tighter than OR."""
+        return self._parse_or()
+
+    def _parse_or(self) -> WhereClause:
+        """Parse OR-separated AND groups."""
+        conditions = [self._parse_and()]
+        while self._match(TokenType.OR):
+            self._advance()
+            conditions.append(self._parse_and())
+        if len(conditions) == 1:
+            if isinstance(conditions[0], WhereClause):
+                return conditions[0]
+            return WhereClause(conditions=conditions, operator='AND')
+        return WhereClause(conditions=conditions, operator='OR')
+
+    def _parse_and(self) -> Condition | WhereClause:
+        """Parse AND-separated predicates."""
+        conditions = [self._parse_predicate()]
+        while self._match(TokenType.AND):
+            self._advance()
+            conditions.append(self._parse_predicate())
+        if len(conditions) == 1:
+            return conditions[0]
+        return WhereClause(conditions=conditions, operator='AND')
+
+    def _parse_predicate(self) -> Condition | WhereClause:
+        """Parse a parenthesized clause or a single condition."""
+        if self._match(TokenType.LPAREN):
+            # Each pair recurses through OR and AND. Past this depth the
+            # call stack raises RecursionError instead of a SQL error.
+            if self._paren_depth >= 100:
+                token = self.tokens[self.pos]
+                raise SyntaxError_('Parentheses nested more than 100 levels', token.position)
+            self._advance()
+            self._paren_depth += 1
+            try:
+                clause = self._parse_or()
+            finally:
+                self._paren_depth -= 1
+            self._expect(TokenType.RPAREN)
+            return clause
+        return self._parse_condition()
+
+    def _parse_condition(self) -> Condition:
+        """Parse a single condition."""
+        negated = False
+        if self._match(TokenType.NOT):
+            self._advance()
+            negated = True
+
+        # Parse column (possibly with table prefix or aggregate syntax)
+        table_alias = None
+        column = self._expect(TokenType.IDENTIFIER).value
+
+        if column.upper() in ('COUNT', 'SUM', 'AVG', 'MIN', 'MAX') and self._match(TokenType.LPAREN):
+            func = column.upper()
+            self._advance()
+            if self._match(TokenType.STAR):
+                self._advance()
+                agg_col = '*'
+            else:
+                agg_col = self._expect(TokenType.IDENTIFIER).value
+                if self._match(TokenType.DOT):
+                    self._advance()
+                    table_alias = agg_col
+                    agg_col = self._expect(TokenType.IDENTIFIER).value
+            self._expect(TokenType.RPAREN)
+            shown = f'{table_alias}.{agg_col}' if table_alias else agg_col
+            column = f'{func}({shown})'
+        elif self._match(TokenType.DOT):
+            self._advance()
+            table_alias = column
+            column = self._expect(TokenType.IDENTIFIER).value
+
+        # Parse operator
+        if self._match(TokenType.IS):
+            self._advance()
+            if self._match(TokenType.NOT):
+                self._advance()
+                self._expect(TokenType.NULL)
+                return Condition(
+                    column=column,
+                    operator='IS NOT NULL',
+                    value=None,
+                    table_alias=table_alias,
+                    negated=negated,
+                )
+            self._expect(TokenType.NULL)
+            return Condition(
+                column=column,
+                operator='IS NULL',
+                value=None,
+                table_alias=table_alias,
+                negated=negated,
+            )
+
+        if self._match(TokenType.EQUALS):
+            op = '='
+            self._advance()
+        elif self._match(TokenType.NOT_EQUALS):
+            op = '!='
+            self._advance()
+        elif self._match(TokenType.GREATER):
+            op = '>'
+            self._advance()
+        elif self._match(TokenType.GREATER_EQUAL):
+            op = '>='
+            self._advance()
+        elif self._match(TokenType.LESS):
+            op = '<'
+            self._advance()
+        elif self._match(TokenType.LESS_EQUAL):
+            op = '<='
+            self._advance()
+        elif self._match(TokenType.LIKE):
+            op = 'LIKE'
+            self._advance()
+        elif self._match(TokenType.IN):
+            op = 'IN'
+            self._advance()
+        else:
+            raise SyntaxError_(
+                f'Expected comparison operator, got {self._current().type.name}', self._current().position
+            )
+
+        # Parse value
+        if op == 'IN':
+            self._expect(TokenType.LPAREN)
+            values = []
+            while True:
+                values.append(self._parse_value())
+                if not self._match(TokenType.COMMA):
+                    break
+                self._advance()
+            self._expect(TokenType.RPAREN)
+            value = values
+        else:
+            value = self._parse_value()
+
+        return Condition(column=column, operator=op, value=value, table_alias=table_alias, negated=negated)
+
+    def _parse_value(self) -> Any:
+        """Parse a literal value."""
+        token = self._current()
+
+        if (
+            token.type == TokenType.STRING_LITERAL
+            or token.type == TokenType.INTEGER_LITERAL
+            or token.type == TokenType.FLOAT_LITERAL
+            or token.type == TokenType.BOOLEAN_LITERAL
+        ):
+            self._advance()
+            return token.value
+        elif token.type == TokenType.NULL:
+            self._advance()
+            return None
+        elif token.type == TokenType.PLACEHOLDER:
+            self._advance()
+            return ParamPlaceholder()
+        else:
+            raise SyntaxError_(f'Expected literal value, got {token.type.name}', token.position)
+
+    def _parse_group_by(self) -> list[str]:
+        """Parse GROUP BY columns. A qualifier is kept as 'table.column'."""
+        columns = []
+        while True:
+            name = self._expect(TokenType.IDENTIFIER).value
+            if self._match(TokenType.DOT):
+                self._advance()
+                name = f'{name}.{self._expect(TokenType.IDENTIFIER).value}'
+            columns.append(name)
+            if not self._match(TokenType.COMMA):
+                break
+            self._advance()
+        return columns
+
+    def _parse_order_by(self) -> list[OrderByItem]:
+        """Parse ORDER BY clause."""
+        items = []
+        while True:
+            column = self._expect(TokenType.IDENTIFIER).value
+            table_alias = None
+
+            if self._match(TokenType.DOT):
+                self._advance()
+                table_alias = column
+                column = self._expect(TokenType.IDENTIFIER).value
+
+            direction = 'ASC'
+            if self._match(TokenType.ASC):
+                self._advance()
+            elif self._match(TokenType.DESC):
+                self._advance()
+                direction = 'DESC'
+
+            items.append(OrderByItem(column=column, direction=direction, table_alias=table_alias))
+
+            if not self._match(TokenType.COMMA):
+                break
+            self._advance()
+
+        return items
+
+    def _parse_insert(self) -> InsertQuery:
+        """Parse an INSERT query."""
+        self._expect(TokenType.INSERT)
+        self._expect(TokenType.INTO)
+
+        table = self._expect(TokenType.IDENTIFIER).value
+
+        # Parse columns
+        self._expect(TokenType.LPAREN)
+        columns = []
+        while True:
+            columns.append(self._expect(TokenType.IDENTIFIER).value)
+            if not self._match(TokenType.COMMA):
+                break
+            self._advance()
+        self._expect(TokenType.RPAREN)
+
+        # Parse VALUES
+        self._expect(TokenType.VALUES)
+        self._expect(TokenType.LPAREN)
+        values = []
+        while True:
+            values.append(self._parse_value())
+            if not self._match(TokenType.COMMA):
+                break
+            self._advance()
+        self._expect(TokenType.RPAREN)
+
+        self._expect_end()
+
+        return InsertQuery(table=table, columns=columns, values=values)
+
+    def _parse_update(self) -> UpdateQuery:
+        """Parse an UPDATE query."""
+        self._expect(TokenType.UPDATE)
+        table = self._expect(TokenType.IDENTIFIER).value
+
+        # Parse SET clause
+        self._expect(TokenType.SET)
+        set_clause = {}
+        while True:
+            col = self._expect(TokenType.IDENTIFIER).value
+            self._expect(TokenType.EQUALS)
+            val = self._parse_value()
+            if col in set_clause:
+                raise InvalidQueryError(f"Duplicate column name '{col}'")
+            set_clause[col] = val
+
+            if not self._match(TokenType.COMMA):
+                break
+            self._advance()
+
+        # Parse WHERE clause
+        where = None
+        if self._match(TokenType.WHERE):
+            self._advance()
+            where = self._parse_where()
+
+        self._expect_end()
+
+        return UpdateQuery(table=table, set_clause=set_clause, where=where)
+
+    def _parse_delete(self) -> DeleteQuery:
+        """Parse a DELETE query."""
+        self._expect(TokenType.DELETE)
+        self._expect(TokenType.FROM)
+
+        table = self._expect(TokenType.IDENTIFIER).value
+
+        # Parse WHERE clause
+        where = None
+        if self._match(TokenType.WHERE):
+            self._advance()
+            where = self._parse_where()
+
+        self._expect_end()
+
+        return DeleteQuery(table=table, where=where)
+
+    def _parse_create(self) -> CreateTableQuery:
+        """Parse a CREATE TABLE query."""
+        self._expect(TokenType.CREATE)
+        self._expect(TokenType.TABLE)
+
+        table = self._expect(TokenType.IDENTIFIER).value
+
+        # Parse column definitions
+        self._expect(TokenType.LPAREN)
+        columns = []
+        while True:
+            col = self._parse_column_def()
+            columns.append(col)
+
+            if not self._match(TokenType.COMMA):
+                break
+            self._advance()
+        self._expect(TokenType.RPAREN)
+
+        self._expect_end()
+
+        return CreateTableQuery(table=table, columns=columns)
+
+    def _parse_column_def(self) -> ColumnDef:
+        """Parse a column definition."""
+        name = self._expect(TokenType.IDENTIFIER).value
+        type_str = self._expect(TokenType.IDENTIFIER).value
+        col_type = ColumnType.from_string(type_str)
+
+        primary_key = False
+        nullable = True
+
+        # Check for PRIMARY KEY
+        if self._match(TokenType.PRIMARY):
+            self._advance()
+            self._expect(TokenType.KEY)
+            primary_key = True
+            nullable = False
+
+        # Check for NULL/NOT NULL
+        if self._match(TokenType.NOT):
+            self._advance()
+            self._expect(TokenType.NULL)
+            nullable = False
+        elif self._match(TokenType.NULL):
+            self._advance()
+            if primary_key:
+                raise InvalidQueryError(f"PRIMARY KEY column '{name}' cannot be NULL")
+            nullable = True
+
+        return ColumnDef(name=name, type=col_type, primary_key=primary_key, nullable=nullable)
+
+    def _parse_drop(self) -> DropTableQuery:
+        """Parse a DROP TABLE query."""
+        self._expect(TokenType.DROP)
+        self._expect(TokenType.TABLE)
+
+        table = self._expect(TokenType.IDENTIFIER).value
+
+        self._expect_end()
+
+        return DropTableQuery(table=table)
+
+    def _parse_begin(self) -> BeginQuery:
+        """Parse a BEGIN statement."""
+        self._expect(TokenType.BEGIN)
+        self._expect_end()
+        return BeginQuery()
+
+    def _parse_commit(self) -> CommitQuery:
+        """Parse a COMMIT statement."""
+        self._expect(TokenType.COMMIT)
+        self._expect_end()
+        return CommitQuery()
+
+    def _parse_rollback(self) -> RollbackQuery:
+        """Parse a ROLLBACK statement."""
+        self._expect(TokenType.ROLLBACK)
+        self._expect_end()
+        return RollbackQuery()
+
+
+def parse_sql(
+    sql: str,
+) -> (
+    SelectQuery
+    | InsertQuery
+    | UpdateQuery
+    | DeleteQuery
+    | CreateTableQuery
+    | DropTableQuery
+    | BeginQuery
+    | CommitQuery
+    | RollbackQuery
+):
+    """Parse a SQL string into a query object."""
+    lexer = Lexer(sql)
+    tokens = lexer.tokenize()
+    parser = Parser(tokens)
+    return parser.parse()
+
+
+def _count_placeholders_in_value(value: Any) -> int:
+    if isinstance(value, ParamPlaceholder):
+        return 1
+    if isinstance(value, list):
+        return sum(_count_placeholders_in_value(item) for item in value)
+    return 0
+
+
+def _count_where_placeholders(where: WhereClause | None) -> int:
+    if where is None:
+        return 0
+    total = 0
+    for cond in where.conditions:
+        if isinstance(cond, Condition):
+            total += _count_placeholders_in_value(cond.value)
+        elif isinstance(cond, WhereClause):
+            total += _count_where_placeholders(cond)
+    return total
+
+
+def _count_query_placeholders(
+    query: (
+        SelectQuery
+        | InsertQuery
+        | UpdateQuery
+        | DeleteQuery
+        | CreateTableQuery
+        | DropTableQuery
+        | BeginQuery
+        | CommitQuery
+        | RollbackQuery
+    ),
+) -> int:
+    if isinstance(query, InsertQuery):
+        return sum(_count_placeholders_in_value(value) for value in query.values)
+    if isinstance(query, UpdateQuery):
+        return sum(
+            _count_placeholders_in_value(value) for value in query.set_clause.values()
+        ) + _count_where_placeholders(query.where)
+    if isinstance(query, DeleteQuery):
+        return _count_where_placeholders(query.where)
+    if isinstance(query, SelectQuery):
+        total = _count_where_placeholders(query.where) + _count_where_placeholders(query.having)
+        for col in query.columns:
+            if col.case is not None:
+                total += _count_case_placeholders(col.case)
+        return total
+    return 0
+
+
+def _count_case_placeholders(expr: CaseExpr) -> int:
+    total = 0
+    for when in expr.whens:
+        total += _count_where_placeholders(when.condition)
+        if when.result.column is None:
+            total += _count_placeholders_in_value(when.result.literal)
+    if expr.else_result is not None and expr.else_result.column is None:
+        total += _count_placeholders_in_value(expr.else_result.literal)
+    return total
+
+
+def _bind_case(expr: CaseExpr, params: list[Any], index: list[int]) -> None:
+    for when in expr.whens:
+        _bind_where(when.condition, params, index)
+        if when.result.column is None:
+            when.result.literal = _bind_value(when.result.literal, params, index)
+    if expr.else_result is not None and expr.else_result.column is None:
+        expr.else_result.literal = _bind_value(expr.else_result.literal, params, index)
+
+
+def _bind_value(value: Any, params: list[Any], index: list[int]) -> Any:
+    if isinstance(value, ParamPlaceholder):
+        bound = params[index[0]]
+        index[0] += 1
+        return bound
+    if isinstance(value, list):
+        return [_bind_value(item, params, index) for item in value]
+    return value
+
+
+def _bind_where(where: WhereClause | None, params: list[Any], index: list[int]) -> None:
+    if where is None:
+        return
+    for cond in where.conditions:
+        if isinstance(cond, Condition):
+            cond.value = _bind_value(cond.value, params, index)
+        elif isinstance(cond, WhereClause):
+            _bind_where(cond, params, index)
+
+
+def bind_params(
+    query: (
+        SelectQuery
+        | InsertQuery
+        | UpdateQuery
+        | DeleteQuery
+        | CreateTableQuery
+        | DropTableQuery
+        | BeginQuery
+        | CommitQuery
+        | RollbackQuery
+    ),
+    params: Sequence[Any] | None = None,
+) -> None:
+    """Replace ParamPlaceholder sentinels left-to-right with bound values."""
+    values = list(params) if params is not None else []
+    expected = _count_query_placeholders(query)
+    if expected != len(values):
+        raise InvalidQueryError(f'expected {expected} parameters, got {len(values)}')
+
+    index = [0]
+    if isinstance(query, InsertQuery):
+        query.values = [_bind_value(value, values, index) for value in query.values]
+    elif isinstance(query, UpdateQuery):
+        for key in query.set_clause:
+            query.set_clause[key] = _bind_value(query.set_clause[key], values, index)
+        _bind_where(query.where, values, index)
+    elif isinstance(query, DeleteQuery):
+        _bind_where(query.where, values, index)
+    elif isinstance(query, SelectQuery):
+        for col in query.columns:
+            if col.case is not None:
+                _bind_case(col.case, values, index)
+        _bind_where(query.where, values, index)
+        _bind_where(query.having, values, index)