rubydb 0.1.0

data/lib/rubydb/sql/parser.rb

@@ -0,0 +1,1185 @@
+# frozen_string_literal: true
+
+module RubyDB
+  module SQL
+    # SQL Parser - converts tokens into AST
+    class Parser
+      attr_reader :tokens, :position, :current_token
+
+      def initialize(tokens)
+        @tokens = tokens
+        @position = 0
+        @current_token = @tokens[0]
+      end
+
+      def parse
+        statements = []
+        while current_token && current_token.type != Token::Type::EOF
+          stmt = parse_statement
+          statements << stmt if stmt
+          # Skip semicolons between statements
+          while current_token && current_token.type == Token::Type::SEMICOLON
+            advance
+          end
+        end
+        statements
+      end
+
+      private
+
+      def parse_statement
+        case current_token&.type
+        when Token::Type::WITH
+          parse_with
+        when Token::Type::SELECT
+          parse_select
+        when Token::Type::INSERT
+          parse_insert
+        when Token::Type::UPDATE
+          parse_update
+        when Token::Type::DELETE
+          parse_delete
+        when Token::Type::CREATE
+          parse_create
+        when Token::Type::DROP
+          parse_drop
+        when Token::Type::ALTER
+          parse_alter
+        when Token::Type::BEGIN_TRANSACTION
+          parse_begin
+        when Token::Type::COMMIT
+          parse_commit
+        when Token::Type::ROLLBACK
+          parse_rollback
+        when Token::Type::SAVEPOINT
+          parse_savepoint
+        when Token::Type::RELEASE
+          parse_release_savepoint
+        when Token::Type::EXPLAIN
+          parse_explain
+        when Token::Type::VACUUM
+          advance
+          AST::Vacuum.new
+        when nil, Token::Type::EOF
+          nil
+        else
+          raise ParserError, "Unexpected token: #{current_token}"
+        end
+      end
+
+      def parse_select
+        expect(Token::Type::SELECT)
+        distinct = false
+        if current_token&.type == Token::Type::DISTINCT
+          advance
+          distinct = true
+        end
+
+        columns = parse_select_columns
+        from = nil
+        joins = []
+        if current_token&.type == Token::Type::FROM
+          advance
+          from = parse_table_reference
+          joins = parse_joins
+        end
+
+        where = nil
+        if current_token&.type == Token::Type::WHERE
+          advance
+          where = parse_expression
+        end
+
+        group_by = []
+        if current_token&.type == Token::Type::GROUP
+          advance
+          expect(Token::Type::BY)
+          group_by = parse_expression_list
+        end
+
+        having = nil
+        if current_token&.type == Token::Type::HAVING
+          advance
+          having = parse_expression
+        end
+
+        order_by = nil
+        if current_token&.type == Token::Type::ORDER
+          advance
+          expect(Token::Type::BY)
+          order_by = parse_order_by
+        end
+
+        limit = nil
+        if current_token&.type == Token::Type::LIMIT
+          advance
+          limit = parse_expression
+        end
+
+        offset = nil
+        if current_token&.type == Token::Type::OFFSET
+          advance
+          offset = parse_expression
+        end
+
+        select = AST::Select.new(columns, from, where, order_by, limit, offset, distinct,
+                                 joins: joins, group_by: group_by, having: having)
+        return select unless [Token::Type::UNION, Token::Type::INTERSECT, Token::Type::EXCEPT].include?(current_token&.type)
+
+        operator = current_token.type.to_s.downcase.to_sym
+        advance
+        all = current_token&.type == Token::Type::ALL
+        advance if all
+        AST::SetOperation.new(select, parse_select, operator, all: all)
+      end
+
+      def parse_with
+        expect(Token::Type::WITH)
+        recursive = current_token&.type == Token::Type::RECURSIVE
+        advance if recursive
+
+        ctes = []
+        loop do
+          name = expect(Token::Type::IDENTIFIER).value
+          expect(Token::Type::AS)
+          expect(Token::Type::LPAREN)
+          query = parse_select
+          expect(Token::Type::RPAREN)
+          ctes << [name, query]
+          break unless current_token&.type == Token::Type::COMMA
+          advance
+        end
+        AST::With.new(ctes, parse_select, recursive: recursive)
+      end
+
+      def parse_select_columns
+        columns = []
+        while true
+          if qualified_star?
+            table = expect(Token::Type::IDENTIFIER).value
+            expect(Token::Type::DOT)
+            expect(Token::Type::STAR)
+            columns << AST::SelectColumn.new(AST::Star.new(table: table))
+          elsif current_token&.type == Token::Type::STAR
+            columns << AST::Star.new
+            advance
+          else
+            expr = parse_expression
+            alias_name = nil
+            if current_token&.type == Token::Type::AS
+              advance
+              alias_name = expect(Token::Type::IDENTIFIER)
+              alias_name = alias_name.value
+            elsif current_token&.type == Token::Type::IDENTIFIER
+              # Implicit alias
+              alias_name = current_token.value
+              advance
+            end
+            columns << AST::SelectColumn.new(expr, alias_name)
+          end
+
+          break unless current_token&.type == Token::Type::COMMA
+          advance
+        end
+        columns
+      end
+
+      def qualified_star?
+        current_token&.type == Token::Type::IDENTIFIER &&
+          @tokens[@position + 1]&.type == Token::Type::DOT &&
+          @tokens[@position + 2]&.type == Token::Type::STAR
+      end
+
+      def parse_table_reference
+        table = expect(Token::Type::IDENTIFIER).value
+        alias_name = nil
+        if current_token&.type == Token::Type::AS
+          advance
+          alias_name = expect(Token::Type::IDENTIFIER).value
+        elsif current_token&.type == Token::Type::IDENTIFIER
+          alias_name = current_token.value
+          advance
+        end
+        AST::TableRef.new(table, alias_name)
+      end
+
+      def parse_joins
+        joins = []
+        while join_start?
+          join_type = parse_join_type
+          table = parse_table_reference
+          condition = nil
+          if current_token&.type == Token::Type::ON
+            advance
+            condition = parse_expression
+          elsif join_type != :cross
+            raise ParserError, "Expected ON clause for #{join_type.to_s.upcase} JOIN"
+          end
+          joins << AST::Join.new(join_type, table, condition)
+        end
+        joins
+      end
+
+      def join_start?
+        [Token::Type::JOIN, Token::Type::INNER, Token::Type::LEFT, Token::Type::RIGHT, Token::Type::FULL, Token::Type::CROSS].include?(current_token&.type)
+      end
+
+      def parse_join_type
+        case current_token&.type
+        when Token::Type::JOIN
+          advance
+          :inner
+        when Token::Type::INNER
+          advance
+          expect(Token::Type::JOIN)
+          :inner
+        when Token::Type::LEFT
+          advance
+          advance if current_token&.type == Token::Type::OUTER
+          expect(Token::Type::JOIN)
+          :left
+        when Token::Type::RIGHT
+          advance
+          advance if current_token&.type == Token::Type::OUTER
+          expect(Token::Type::JOIN)
+          :right
+        when Token::Type::FULL
+          advance
+          advance if current_token&.type == Token::Type::OUTER
+          expect(Token::Type::JOIN)
+          :full
+        when Token::Type::CROSS
+          advance
+          expect(Token::Type::JOIN)
+          :cross
+        end
+      end
+
+      def parse_expression
+        parse_or
+      end
+
+      def parse_or
+        expr = parse_and
+        while current_token&.type == Token::Type::OR
+          advance
+          right = parse_and
+          expr = AST::BinaryOp.new(:or, expr, right)
+        end
+        expr
+      end
+
+      def parse_and
+        expr = parse_comparison
+        while current_token&.type == Token::Type::AND
+          advance
+          right = parse_comparison
+          expr = AST::BinaryOp.new(:and, expr, right)
+        end
+        expr
+      end
+
+      def parse_comparison
+        expr = parse_additive
+
+        # IS NULL / IS NOT NULL have a dedicated AST node and must be parsed
+        # before the generic binary-comparison path. Treating IS as a normal
+        # comparison loses the null predicate and can turn it into a
+        # three-valued expression that is always truthy at the filter layer.
+        if current_token && Operators.comparison?(current_token.type) &&
+           ![Token::Type::IN, Token::Type::IS].include?(current_token.type)
+          op = current_token.type
+          advance
+          right = parse_additive
+          expr = AST::BinaryOp.new(op, expr, right)
+        end
+
+        if current_token&.type == Token::Type::IS
+          advance
+          is_not = current_token&.type == Token::Type::NOT
+          advance if is_not
+          expect(Token::Type::NULL)
+          expr = AST::IsNull.new(expr, is_not)
+        end
+
+        if current_token&.type == Token::Type::BETWEEN
+          advance
+          low = parse_additive
+          expect(Token::Type::AND)
+          high = parse_additive
+          expr = AST::Between.new(expr, low, high)
+        end
+
+        if current_token&.type == Token::Type::IN
+          advance
+          expect(Token::Type::LPAREN)
+          values = []
+          if current_token&.type == Token::Type::SELECT
+            values << AST::Subquery.new(parse_select)
+          else
+            while true
+              values << parse_expression
+              break unless current_token&.type == Token::Type::COMMA
+              advance
+            end
+          end
+          expect(Token::Type::RPAREN)
+          expr = AST::In.new(expr, values)
+        end
+
+        expr
+      end
+
+      def parse_additive
+        expr = parse_multiplicative
+        while current_token && [Token::Type::PLUS, Token::Type::MINUS].include?(current_token.type)
+          op = current_token.type
+          advance
+          right = parse_multiplicative
+          expr = AST::BinaryOp.new(op, expr, right)
+        end
+        expr
+      end
+
+      def parse_multiplicative
+        expr = parse_unary
+        while current_token && [Token::Type::STAR, Token::Type::SLASH, Token::Type::PERCENT].include?(current_token.type)
+          op = current_token.type
+          advance
+          right = parse_unary
+          expr = AST::BinaryOp.new(op, expr, right)
+        end
+        expr
+      end
+
+      def parse_unary
+        if current_token && Operators.unary?(current_token.type)
+          op = current_token.type
+          advance
+          expr = parse_primary
+          AST::UnaryOp.new(op, expr)
+        else
+          parse_primary
+        end
+      end
+
+      def parse_primary
+        case current_token&.type
+        when Token::Type::STAR
+          advance
+          AST::Star.new
+        when Token::Type::EXISTS
+          advance
+          expect(Token::Type::LPAREN)
+          query = parse_select
+          expect(Token::Type::RPAREN)
+          AST::Exists.new(query)
+        when Token::Type::LPAREN
+          advance
+          expr = current_token&.type == Token::Type::SELECT ? AST::Subquery.new(parse_select) : parse_expression
+          expect(Token::Type::RPAREN)
+          expr
+        when Token::Type::IDENTIFIER
+          ident = current_token.value
+          advance
+          if current_token&.type == Token::Type::DOT
+            advance
+            column = expect(Token::Type::IDENTIFIER).value
+            AST::Identifier.new(column, table: ident)
+          elsif current_token&.type == Token::Type::LPAREN
+            # Function call
+            advance
+            args = []
+            distinct = false
+            if current_token&.type == Token::Type::DISTINCT
+              advance
+              distinct = true
+            end
+            unless current_token&.type == Token::Type::RPAREN
+              while true
+                args << parse_expression
+                break unless current_token&.type == Token::Type::COMMA
+                advance
+              end
+            end
+            expect(Token::Type::RPAREN)
+            window = current_token&.type == Token::Type::OVER ? parse_window_spec : nil
+            AST::FunctionCall.new(ident, args, distinct: distinct, window: window)
+          else
+            AST::Identifier.new(ident)
+          end
+        when Token::Type::STRING, Token::Type::NUMBER
+          value = current_token.value
+          type = current_token.type
+          advance
+          AST::Literal.new(value, type)
+        when Token::Type::NULL
+          advance
+          AST::NullLiteral.new
+        when Token::Type::TRUE
+          advance
+          AST::Literal.new(true, Token::Type::TRUE)
+        when Token::Type::FALSE
+          advance
+          AST::Literal.new(false, Token::Type::FALSE)
+        when Token::Type::PARAMETER
+          value = current_token.value
+          advance
+          AST::Parameter.new(value)
+        else
+          raise ParserError, "Unexpected token in expression: #{current_token}"
+        end
+      end
+
+      def parse_order_by
+        order_items = []
+        while true
+          expr = parse_expression
+          direction = :asc
+          if [Token::Type::ASC, Token::Type::DESC].include?(current_token&.type)
+            direction = :desc if current_token.type == Token::Type::DESC
+            advance
+          end
+          order_items << AST::OrderItem.new(expr, direction)
+          break unless current_token&.type == Token::Type::COMMA
+          advance
+        end
+        order_items
+      end
+
+      def parse_window_spec
+        expect(Token::Type::OVER)
+        expect(Token::Type::LPAREN)
+        partition_by = []
+        if current_token&.type == Token::Type::PARTITION
+          advance
+          expect(Token::Type::BY)
+          partition_by = parse_expression_list
+        end
+
+        order_by = []
+        if current_token&.type == Token::Type::ORDER
+          advance
+          expect(Token::Type::BY)
+          order_by = parse_order_by
+        end
+        frame = parse_window_frame if current_token&.type == Token::Type::ROWS
+        expect(Token::Type::RPAREN)
+        { partition_by: partition_by, order_by: order_by, frame: frame }
+      end
+
+      def parse_window_frame
+        expect(Token::Type::ROWS)
+        if current_token&.type == Token::Type::BETWEEN
+          advance
+          start = parse_frame_boundary
+          expect(Token::Type::AND)
+          finish = parse_frame_boundary
+          { start: start, finish: finish }
+        else
+          { start: parse_frame_boundary, finish: { kind: :current_row } }
+        end
+      end
+
+      def parse_frame_boundary
+        case current_token&.type
+        when Token::Type::UNBOUNDED
+          advance
+          direction = current_token&.type
+          unless [Token::Type::PRECEDING, Token::Type::FOLLOWING].include?(direction)
+            raise ParserError, "Expected PRECEDING or FOLLOWING after UNBOUNDED"
+          end
+          advance
+          { kind: direction == Token::Type::PRECEDING ? :unbounded_preceding : :unbounded_following }
+        when Token::Type::CURRENT
+          advance
+          row = expect(Token::Type::IDENTIFIER)
+          raise ParserError, "Expected ROW after CURRENT" unless row.value.to_s.upcase == "ROW"
+          { kind: :current_row }
+        when Token::Type::NUMBER
+          value = expect(Token::Type::NUMBER).value
+          unless value.is_a?(Integer) && value >= 0
+            raise ParserError, "Window frame offset must be a non-negative integer"
+          end
+          direction = current_token&.type
+          unless [Token::Type::PRECEDING, Token::Type::FOLLOWING].include?(direction)
+            raise ParserError, "Expected PRECEDING or FOLLOWING after frame offset"
+          end
+          advance
+          { kind: direction == Token::Type::PRECEDING ? :preceding : :following, value: value }
+        else
+          raise ParserError, "Expected window frame boundary"
+        end
+      end
+
+      def parse_expression_list
+        expressions = []
+        loop do
+          expressions << parse_expression
+          break unless current_token&.type == Token::Type::COMMA
+
+          advance
+        end
+        expressions
+      end
+
+      def parse_insert
+        expect(Token::Type::INSERT)
+        expect(Token::Type::INTO)
+        table = expect(Token::Type::IDENTIFIER).value
+
+        columns = []
+        if current_token&.type == Token::Type::LPAREN
+          advance
+          while true
+            columns << expect(Token::Type::IDENTIFIER).value
+            break unless current_token&.type == Token::Type::COMMA
+            advance
+          end
+          expect(Token::Type::RPAREN)
+        end
+
+        expect(Token::Type::VALUES)
+        rows = []
+        loop do
+          expect(Token::Type::LPAREN)
+          values = []
+          while true
+            values << parse_expression
+            break unless current_token&.type == Token::Type::COMMA
+            advance
+          end
+          expect(Token::Type::RPAREN)
+          rows << values
+          break unless current_token&.type == Token::Type::COMMA
+          advance
+        end
+
+        on_conflict = nil
+        if current_token&.type == Token::Type::ON
+          advance
+          expect(Token::Type::CONFLICT)
+          target = []
+          if current_token&.type == Token::Type::LPAREN
+            advance
+            target << expect(Token::Type::IDENTIFIER).value
+            while current_token&.type == Token::Type::COMMA
+              advance
+              target << expect(Token::Type::IDENTIFIER).value
+            end
+            expect(Token::Type::RPAREN)
+          end
+          expect(Token::Type::DO)
+          if current_token&.type == Token::Type::NOTHING
+            advance
+            on_conflict = :nothing
+          elsif current_token&.type == Token::Type::UPDATE
+            advance
+            expect(Token::Type::SET)
+            assignments = []
+            loop do
+              column = expect(Token::Type::IDENTIFIER).value
+              expect(Token::Type::EQ)
+              assignments << AST::Assignment.new(column, parse_expression)
+              break unless current_token&.type == Token::Type::COMMA
+              advance
+            end
+            on_conflict = { action: :update, target: target, assignments: assignments }
+          else
+            raise ParserError, "Expected NOTHING or UPDATE after ON CONFLICT DO"
+          end
+        end
+        AST::Insert.new(table, columns, rows.first || [], rows: rows, on_conflict: on_conflict)
+      end
+
+      def parse_update
+        expect(Token::Type::UPDATE)
+        table = expect(Token::Type::IDENTIFIER).value
+        expect(Token::Type::SET)
+
+        assignments = []
+        while true
+          column = expect(Token::Type::IDENTIFIER).value
+          expect(Token::Type::EQ)
+          value = parse_expression
+          assignments << AST::Assignment.new(column, value)
+          break unless current_token&.type == Token::Type::COMMA
+          advance
+        end
+
+        where = nil
+        if current_token&.type == Token::Type::WHERE
+          advance
+          where = parse_expression
+        end
+
+        AST::Update.new(table, assignments, where)
+      end
+
+      def parse_delete
+        expect(Token::Type::DELETE)
+        expect(Token::Type::FROM)
+        table = expect(Token::Type::IDENTIFIER).value
+
+        where = nil
+        if current_token&.type == Token::Type::WHERE
+          advance
+          where = parse_expression
+        end
+
+        AST::Delete.new(table, where)
+      end
+
+      def parse_create
+        expect(Token::Type::CREATE)
+        case current_token&.type
+        when Token::Type::TABLE
+          parse_create_table
+        when Token::Type::INDEX
+          parse_create_index
+        when Token::Type::UNIQUE
+          advance
+          parse_create_index(unique: true)
+        when Token::Type::DATABASE
+          parse_create_database
+        when Token::Type::SCHEMA
+          parse_create_schema
+        when Token::Type::VIEW
+          parse_create_view
+        when Token::Type::TRIGGER
+          parse_create_trigger
+        else
+          raise ParserError, "Unexpected CREATE type: #{current_token}"
+        end
+      end
+
+      def parse_create_table
+        advance # TABLE
+        if_not_exists = false
+        if current_token&.type == Token::Type::IF
+          advance
+          expect(Token::Type::NOT)
+          expect(Token::Type::EXISTS)
+          if_not_exists = true
+        end
+        table_name = expect(Token::Type::IDENTIFIER).value
+        expect(Token::Type::LPAREN)
+
+        columns = []
+        constraints = []
+
+        while current_token&.type != Token::Type::RPAREN
+          if current_token&.type == Token::Type::CONSTRAINT
+            advance
+            constraint_name = expect(Token::Type::IDENTIFIER).value
+            constraint = parse_constraint(constraint_name)
+            constraints << constraint
+          elsif current_token&.type == Token::Type::PRIMARY ||
+                current_token&.type == Token::Type::FOREIGN ||
+                current_token&.type == Token::Type::UNIQUE ||
+                current_token&.type == Token::Type::CHECK
+            constraint = parse_constraint
+            constraints << constraint if constraint
+          else
+            # Column definition
+            column_name = expect(Token::Type::IDENTIFIER).value
+            column_type = expect_data_type
+            options = parse_column_options
+            columns << AST::ColumnDefinition.new(column_name, column_type, options)
+          end
+
+          break unless current_token&.type == Token::Type::COMMA
+          advance
+        end
+
+        expect(Token::Type::RPAREN)
+
+        AST::CreateTable.new(table_name, columns, constraints, if_not_exists: if_not_exists)
+      end
+
+      def parse_data_type
+        case current_token&.type
+        when Token::Type::INTEGER
+          advance
+          :integer
+        when Token::Type::BIGINT
+          advance
+          :bigint
+        when Token::Type::SMALLINT
+          advance
+          :smallint
+        when Token::Type::FLOAT
+          advance
+          :float
+        when Token::Type::DECIMAL
+          advance
+          if current_token&.type == Token::Type::LPAREN
+            advance
+            precision = expect(Token::Type::NUMBER).value
+            scale = 0
+            if current_token&.type == Token::Type::COMMA
+              advance
+              scale = expect(Token::Type::NUMBER).value
+            end
+            expect(Token::Type::RPAREN)
+            { type: :decimal, precision: precision, scale: scale }
+          else
+            :decimal
+          end
+        when Token::Type::BOOLEAN
+          advance
+          :boolean
+        when Token::Type::TEXT
+          advance
+          :text
+        when Token::Type::VARCHAR
+          advance
+          if current_token&.type == Token::Type::LPAREN
+            advance
+            limit = expect(Token::Type::NUMBER).value
+            expect(Token::Type::RPAREN)
+            { type: :varchar, limit: limit }
+          else
+            { type: :varchar, limit: 255 }
+          end
+        when Token::Type::BLOB
+          advance
+          :blob
+        when Token::Type::DATE
+          advance
+          :date
+        when Token::Type::TIME
+          advance
+          :time
+        when Token::Type::TIMESTAMP
+          advance
+          :timestamp
+        when Token::Type::JSON
+          advance
+          :json
+        when Token::Type::UUID
+          advance
+          :uuid
+        else
+          raise ParserError, "Expected data type, got: #{current_token}"
+        end
+      end
+
+      def parse_column_options
+        options = {}
+        while true
+          case current_token&.type
+          when Token::Type::PRIMARY
+            advance
+            expect(Token::Type::KEY)
+            options[:primary_key] = true
+          when Token::Type::UNIQUE
+            advance
+            options[:unique] = true
+          when Token::Type::NOT
+            advance
+            expect(Token::Type::NULL)
+            options[:null] = false
+          when Token::Type::NULL
+            advance
+            options[:null] = true
+          when Token::Type::DEFAULT
+            advance
+            options[:default] = parse_expression
+          when Token::Type::REFERENCES
+            advance
+            ref_table = expect(Token::Type::IDENTIFIER).value
+            expect(Token::Type::LPAREN)
+            ref_column = expect(Token::Type::IDENTIFIER).value
+            expect(Token::Type::RPAREN)
+            options[:references] = { table: ref_table, column: ref_column }
+          when Token::Type::IDENTIFIER
+            # SQLite spells an automatically allocated integer primary key
+            # `AUTOINCREMENT`. Keep it as column metadata; RubyDB's durable
+            # integer-primary-key allocator provides the actual behavior.
+            if current_token.value.to_s.upcase == "AUTOINCREMENT"
+              advance
+              options[:auto_increment] = true
+            else
+              break
+            end
+          else
+            break
+          end
+        end
+        options
+      end
+
+      def parse_referential_action(kind)
+        return nil unless current_token&.type == Token::Type::ON
+        advance
+        expected = kind == :delete ? Token::Type::DELETE : Token::Type::UPDATE
+        expect(expected)
+        action = case current_token&.type
+                 when Token::Type::CASCADE
+                   advance
+                   :cascade
+                 when Token::Type::RESTRICT
+                   advance
+                   :restrict
+                 when Token::Type::SET
+                   advance
+                   expect(Token::Type::NULL) if current_token&.type == Token::Type::NULL
+                   if current_token&.type == Token::Type::DEFAULT
+                     advance
+                     :set_default
+                   else
+                     :set_null
+                   end
+                 else
+                   raise ParserError, "Expected referential action, got #{current_token}"
+                 end
+        action
+      end
+
+      def parse_constraint(name = nil)
+        case current_token&.type
+        when Token::Type::PRIMARY
+          advance
+          expect(Token::Type::KEY)
+          expect(Token::Type::LPAREN)
+          columns = []
+          while true
+            columns << expect(Token::Type::IDENTIFIER).value
+            break unless current_token&.type == Token::Type::COMMA
+            advance
+          end
+          expect(Token::Type::RPAREN)
+          AST::PrimaryKeyConstraint.new(name, columns)
+        when Token::Type::FOREIGN
+          advance
+          expect(Token::Type::KEY)
+          expect(Token::Type::LPAREN)
+          columns = []
+          while true
+            columns << expect(Token::Type::IDENTIFIER).value
+            break unless current_token&.type == Token::Type::COMMA
+            advance
+          end
+          expect(Token::Type::RPAREN)
+          expect(Token::Type::REFERENCES)
+          ref_table = expect(Token::Type::IDENTIFIER).value
+          expect(Token::Type::LPAREN)
+          ref_columns = []
+          while true
+            ref_columns << expect(Token::Type::IDENTIFIER).value
+            break unless current_token&.type == Token::Type::COMMA
+            advance
+          end
+          expect(Token::Type::RPAREN)
+          on_delete = parse_referential_action(:delete)
+          on_update = parse_referential_action(:update)
+          AST::ForeignKeyConstraint.new(name, columns, ref_table, ref_columns, on_delete: on_delete, on_update: on_update)
+        when Token::Type::UNIQUE
+          advance
+          expect(Token::Type::LPAREN)
+          columns = []
+          while true
+            columns << expect(Token::Type::IDENTIFIER).value
+            break unless current_token&.type == Token::Type::COMMA
+            advance
+          end
+          expect(Token::Type::RPAREN)
+          AST::UniqueConstraint.new(name, columns)
+        when Token::Type::CHECK
+          advance
+          expect(Token::Type::LPAREN)
+          condition = parse_expression
+          expect(Token::Type::RPAREN)
+          AST::CheckConstraint.new(name, condition)
+        else
+          nil
+        end
+      end
+
+      def parse_create_index(unique: false)
+        advance # INDEX
+        if_not_exists = false
+        if current_token&.type == Token::Type::IF
+          advance
+          expect(Token::Type::NOT)
+          expect(Token::Type::EXISTS)
+          if_not_exists = true
+        end
+        index_name = expect(Token::Type::IDENTIFIER).value
+        expect(Token::Type::ON)
+        table_name = expect(Token::Type::IDENTIFIER).value
+        expect(Token::Type::LPAREN)
+        columns = []
+        while true
+          columns << expect(Token::Type::IDENTIFIER).value
+          break unless current_token&.type == Token::Type::COMMA
+          advance
+        end
+        expect(Token::Type::RPAREN)
+
+        # Legacy grammar accepted UNIQUE after the column list; retain it.
+        if current_token&.type == Token::Type::UNIQUE
+          unique = true
+          advance
+        end
+
+        AST::CreateIndex.new(index_name, table_name, columns, unique: unique, if_not_exists: if_not_exists)
+      end
+
+      def parse_create_database
+        advance # DATABASE
+        if_not_exists = false
+        if current_token&.type == Token::Type::IF
+          advance
+          expect(Token::Type::NOT)
+          expect(Token::Type::EXISTS)
+          if_not_exists = true
+        end
+        db_name = expect(Token::Type::IDENTIFIER).value
+        AST::CreateDatabase.new(db_name, if_not_exists: if_not_exists)
+      end
+
+      def parse_create_schema
+        advance
+        if_not_exists = false
+        if current_token&.type == Token::Type::IF
+          advance
+          expect(Token::Type::NOT)
+          expect(Token::Type::EXISTS)
+          if_not_exists = true
+        end
+        name = expect(Token::Type::IDENTIFIER).value
+        AST::CreateSchema.new(name, if_not_exists: if_not_exists)
+      end
+
+      def parse_create_view
+        advance
+        if_not_exists = false
+        if current_token&.type == Token::Type::IF
+          advance
+          expect(Token::Type::NOT)
+          expect(Token::Type::EXISTS)
+          if_not_exists = true
+        end
+        name = expect(Token::Type::IDENTIFIER).value
+        expect(Token::Type::AS)
+        AST::CreateView.new(name, parse_select, if_not_exists: if_not_exists)
+      end
+
+      def parse_create_trigger
+        advance
+        name = expect(Token::Type::IDENTIFIER).value
+        timing = if current_token&.type == Token::Type::BEFORE
+                   advance
+                   :before
+                 else
+                   expect(Token::Type::AFTER)
+                   :after
+                 end
+        event_token = current_token
+        unless [Token::Type::INSERT, Token::Type::UPDATE, Token::Type::DELETE].include?(event_token&.type)
+          raise ParserError, "Expected trigger event, got: #{event_token}"
+        end
+        advance
+        expect(Token::Type::ON)
+        table_name = expect(Token::Type::IDENTIFIER).value
+        expect(Token::Type::EXECUTE)
+        expect(Token::Type::FUNCTION)
+        function_name = expect(Token::Type::IDENTIFIER).value
+        expect(Token::Type::LPAREN)
+        expect(Token::Type::RPAREN)
+        AST::CreateTrigger.new(name, timing, event_token.value.to_s.downcase.to_sym, table_name, function_name)
+      end
+
+      def parse_drop
+        expect(Token::Type::DROP)
+        case current_token&.type
+        when Token::Type::TABLE
+          advance
+          if_exists = false
+          if current_token&.type == Token::Type::IF
+            advance
+            expect(Token::Type::EXISTS)
+            if_exists = true
+          end
+          table_name = expect(Token::Type::IDENTIFIER).value
+          AST::DropTable.new(table_name, if_exists: if_exists)
+        when Token::Type::INDEX
+          advance
+          if_exists = false
+          if current_token&.type == Token::Type::IF
+            advance
+            expect(Token::Type::EXISTS)
+            if_exists = true
+          end
+          index_name = expect(Token::Type::IDENTIFIER).value
+          AST::DropIndex.new(index_name, if_exists: if_exists)
+        when Token::Type::DATABASE
+          advance
+          if_exists = false
+          if current_token&.type == Token::Type::IF
+            advance
+            expect(Token::Type::EXISTS)
+            if_exists = true
+          end
+          db_name = expect(Token::Type::IDENTIFIER).value
+          AST::DropDatabase.new(db_name, if_exists: if_exists)
+        when Token::Type::SCHEMA
+          advance
+          if_exists = false
+          if current_token&.type == Token::Type::IF
+            advance
+            expect(Token::Type::EXISTS)
+            if_exists = true
+          end
+          name = expect(Token::Type::IDENTIFIER).value
+          cascade = false
+          if current_token&.type == Token::Type::CASCADE
+            advance
+            cascade = true
+          end
+          AST::DropSchema.new(name, if_exists: if_exists, cascade: cascade)
+        when Token::Type::VIEW
+          advance
+          if_exists = false
+          if current_token&.type == Token::Type::IF
+            advance
+            expect(Token::Type::EXISTS)
+            if_exists = true
+          end
+          AST::DropView.new(expect(Token::Type::IDENTIFIER).value, if_exists: if_exists)
+        when Token::Type::TRIGGER
+          advance
+          if_exists = false
+          if current_token&.type == Token::Type::IF
+            advance
+            expect(Token::Type::EXISTS)
+            if_exists = true
+          end
+          AST::DropTrigger.new(expect(Token::Type::IDENTIFIER).value, if_exists: if_exists)
+        else
+          raise ParserError, "Unexpected DROP type: #{current_token}"
+        end
+      end
+
+      def parse_alter
+        expect(Token::Type::ALTER)
+        expect(Token::Type::TABLE)
+        table_name = expect(Token::Type::IDENTIFIER).value
+
+        case current_token&.type
+        when Token::Type::ADD
+          advance
+          skip_optional_column_keyword
+          if current_token&.type == Token::Type::CONSTRAINT
+            advance
+            constraint_name = expect(Token::Type::IDENTIFIER).value
+            constraint = parse_constraint(constraint_name)
+            AST::AlterTableAddConstraint.new(table_name, constraint)
+          else
+            column_name = expect(Token::Type::IDENTIFIER).value
+            column_type = parse_data_type
+            options = parse_column_options
+            AST::AlterTableAddColumn.new(table_name, column_name, column_type, options)
+          end
+        when Token::Type::DROP
+          advance
+          skip_optional_column_keyword
+          if current_token&.type == Token::Type::CONSTRAINT
+            advance
+            constraint_name = expect(Token::Type::IDENTIFIER).value
+            AST::AlterTableDropConstraint.new(table_name, constraint_name)
+          else
+            column_name = expect(Token::Type::IDENTIFIER).value
+            AST::AlterTableDropColumn.new(table_name, column_name)
+          end
+        else
+          raise ParserError, "Unexpected ALTER TABLE operation: #{current_token}"
+        end
+      end
+
+      def parse_begin
+        expect(Token::Type::BEGIN_TRANSACTION)
+        if current_token&.type == Token::Type::TRANSACTION
+          advance
+        end
+        AST::BeginTransaction.new
+      end
+
+      def skip_optional_column_keyword
+        return unless current_token&.type == Token::Type::IDENTIFIER
+        return unless current_token.value.to_s.casecmp("COLUMN").zero?
+
+        advance
+      end
+
+      def parse_commit
+        expect(Token::Type::COMMIT)
+        if current_token&.type == Token::Type::TRANSACTION
+          advance
+        end
+        AST::Commit.new
+      end
+
+      def parse_rollback
+        expect(Token::Type::ROLLBACK)
+        if current_token&.type == Token::Type::TRANSACTION
+          advance
+        end
+        if current_token&.type == Token::Type::TO
+          advance
+          advance if current_token&.type == Token::Type::SAVEPOINT
+          savepoint = expect(Token::Type::IDENTIFIER).value
+          return AST::RollbackToSavepoint.new(savepoint)
+        end
+        AST::Rollback.new
+      end
+
+      def parse_savepoint
+        expect(Token::Type::SAVEPOINT)
+        AST::Savepoint.new(expect(Token::Type::IDENTIFIER).value)
+      end
+
+      def parse_release_savepoint
+        expect(Token::Type::RELEASE)
+        expect(Token::Type::SAVEPOINT) if current_token&.type == Token::Type::SAVEPOINT
+        AST::ReleaseSavepoint.new(expect(Token::Type::IDENTIFIER).value)
+      end
+
+      def parse_explain
+        expect(Token::Type::EXPLAIN)
+        if current_token&.type == Token::Type::ANALYZE
+          advance
+          analyze = true
+        else
+          analyze = false
+        end
+        statement = parse_statement
+        AST::Explain.new(statement, analyze: analyze)
+      end
+
+      def expect(type)
+        token = current_token
+        if token.nil? || token.type != type
+          raise ParserError, "Expected #{type}, got #{token}"
+        end
+        advance
+        token
+      end
+
+      def expect_data_type
+        type = parse_data_type
+        unless type
+          raise ParserError, "Expected data type, got #{current_token}"
+        end
+        type
+      end
+
+      def advance
+        @position += 1
+        @current_token = @tokens[@position]
+      end
+    end
+  end
+end