engine

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 1, 2025 License: AGPL-3.0 Imports: 11 Imported by: 0

Documentation

Overview

Package engine provides SQL parsing, planning, and execution for tinySQL.

This file focuses on the query compilation cache:

  • What: A lightweight in-memory cache that stores parsed/compiled representations of SQL statements (CompiledQuery).
  • How: Queries are keyed by their exact SQL string. The cache holds a Statement AST plus metadata (ParsedAt) and returns it to callers to avoid re-parsing. A simple FIFO eviction based on oldest ParsedAt keeps the cache within a fixed size.
  • Why: Parsing is comparatively expensive and often repeated in loops or hot paths. Caching reduces parse overhead, improves latency, and keeps the execution path predictable while remaining simple and thread-safe.

Package engine implements the tinySQL execution engine.

What: This module evaluates parsed SQL statements (AST) against the storage layer and produces ResultSets. It covers DDL/DML/SELECT, joins, grouping, aggregates, expression evaluation, simple functions (JSON_*, DATEDIFF, etc.), and a minimal tri-state boolean logic (true/false/unknown).

How: The executor converts tables to row maps with both qualified and unqualified column keys, applies WHERE/GROUP/HAVING/ORDER/LIMIT/OFFSET, and optionally combines results with UNION/EXCEPT/INTERSECT. Expression evaluation is recursive over a small algebra of literals, variables, unary/ binary ops, IS NULL, and function calls. Aggregate evaluation runs per- group with reusable helpers shared with the scalar evaluator.

Why: Keeping execution self-contained and data-structure driven (Row maps and simple slices) makes the engine easy to reason about and to extend with new functions, operators, and clauses without introducing heavy planners.

Package engine contains the SQL lexer used by the parser.

What: A minimal, whitespace- and comment-aware tokenizer that recognizes identifiers, keywords, numeric and string literals, and symbols. How: Single-pass rune-based scanner supporting -- and /* */ comments, uppercasing keywords, and preserving identifier case. Keywords are a fixed allow-list tailored to tinySQL features. Why: A compact lexer reduces parser complexity and keeps error messages local and actionable without external dependencies.

Package engine provides a hand-written SQL parser for tinySQL.

What: It parses a practical subset of SQL into an AST (statements and expressions) used by the execution engine. Supported features include DDL, DML, SELECT with JOIN/GROUP/HAVING/ORDER/LIMIT/OFFSET, and set ops. How: A straightforward recursive-descent parser over a small token stream from the lexer. It favors clarity and precise error messages. Ident-like parsing accepts keywords as identifiers to keep the grammar practical for common column names. Why: A small, readable parser is easy to extend and reason about, enabling rapid iteration on language features without a complex generator toolchain.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Binary 

type Binary struct {
	Op          string
	Left, Right Expr
}

Binary represents binary operators (+,-,*,/, comparisons, AND/OR).

type CTE 

type CTE struct {
	Name   string
	Select *Select
}

CTE represents a Common Table Expression (WITH clause)

type CompiledQuery 

type CompiledQuery struct {
	SQL       string
	Statement Statement
	ParsedAt  time.Time
}

CompiledQuery represents a pre-parsed and cached SQL query.

func (*CompiledQuery) Execute 

func (cq *CompiledQuery) Execute(ctx context.Context, db *storage.DB, tenant string) (*ResultSet, error)

Execute runs a compiled query against the database.

type CreateTable 

type CreateTable struct {
	Name     string
	Cols     []storage.Column
	IsTemp   bool
	AsSelect *Select
}

CreateTable represents a CREATE TABLE statement.

type Delete 

type Delete struct {
	Table string
	Where Expr
}

Delete represents a DELETE statement.

type DropTable 

type DropTable struct{ Name string }

DropTable represents a DROP TABLE statement.

type ExecEnv 

type ExecEnv struct {
	// contains filtered or unexported fields
}

type Expr 

type Expr interface{}

type FromItem 

type FromItem struct{ Table, Alias string }

FromItem binds a source table and its alias in FROM/JOIN.

type FuncCall 

type FuncCall struct {
	Name string
	Args []Expr
	Star bool
}

FuncCall represents a function call, optionally with a star (COUNT(*)).

type Insert 

type Insert struct {
	Table string
	Cols  []string
	Vals  []Expr
}

Insert represents an INSERT statement.

type IsNull 

type IsNull struct {
	Expr   Expr
	Negate bool
}

IsNull represents IS [NOT] NULL predicate.

type JoinClause 

type JoinClause struct {
	Type  JoinType
	Right FromItem
	On    Expr
}

JoinClause holds a JOIN type with the right side and join condition.

type JoinType 

type JoinType int
const (
	// JoinInner represents INNER JOIN.
	JoinInner JoinType = iota
	// JoinLeft represents LEFT (OUTER) JOIN.
	JoinLeft
	// JoinRight represents RIGHT (OUTER) JOIN.
	JoinRight
)

type Literal 

type Literal struct{ Val any }

Literal holds a constant value (number, string, bool, NULL).

type OrderItem 

type OrderItem struct {
	Col  string
	Desc bool
}

OrderItem specifies ordering column and direction.

type Parser 

type Parser struct {
	// contains filtered or unexported fields
}

Parser holds the lexer and current/peek tokens for recursive-descent parsing.

func NewParser 

func NewParser(sql string) *Parser

NewParser creates a new SQL parser for the provided input string.

func (*Parser) ParseStatement 

func (p *Parser) ParseStatement() (Statement, error)

ParseStatement parses a single SQL statement into an AST.

type QueryCache 

type QueryCache struct {
	// contains filtered or unexported fields
}

QueryCache manages compiled queries.

func NewQueryCache 

func NewQueryCache(maxSize int) *QueryCache

NewQueryCache creates a new query cache with the specified maximum size.

func (*QueryCache) Clear 

func (qc *QueryCache) Clear()

Clear removes all cached queries.

func (*QueryCache) Compile 

func (qc *QueryCache) Compile(sql string) (*CompiledQuery, error)

Compile parses and caches a SQL query for reuse.

func (*QueryCache) MustCompile 

func (qc *QueryCache) MustCompile(sql string) *CompiledQuery

MustCompile is like Compile but panics on error (similar to regexp.MustCompile).

func (*QueryCache) Size 

func (qc *QueryCache) Size() int

Size returns the number of cached queries.

func (*QueryCache) Stats 

func (qc *QueryCache) Stats() map[string]interface{}

Stats returns cache statistics.

type ResultSet 

type ResultSet struct {
	Cols []string
	Rows []Row
}

ResultSet holds the column order and the returned rows from a query. Cols preserve the display order; Rows store values in a case-insensitive map.

func Execute 

func Execute(ctx context.Context, db *storage.DB, tenant string, stmt Statement) (*ResultSet, error)

Execute runs a parsed SQL statement against the given storage DB and tenant. It dispatches to handlers per statement kind and returns a ResultSet for SELECT (nil for DDL/DML). The context is checked at safe points to support cancellation.

type Row 

type Row map[string]any

Row represents a single result row mapped by lower-cased column name. Keys include both qualified (table.column) and unqualified (column) names to simplify expression evaluation and projection.

type Select 

type Select struct {
	Distinct bool
	From     FromItem
	Joins    []JoinClause
	Projs    []SelectItem
	Where    Expr
	GroupBy  []VarRef
	Having   Expr
	OrderBy  []OrderItem
	Limit    *int
	Offset   *int
	Union    *UnionClause // For UNION operations
	CTEs     []CTE        // Common Table Expressions
}

Select represents a SELECT query and its clauses.

type SelectItem 

type SelectItem struct {
	Expr  Expr
	Alias string
	Star  bool
}

SelectItem represents a projection item, optionally with alias or *.

type Statement 

type Statement interface{}

Statement is the root interface for all parsed SQL statements.

type Unary 

type Unary struct {
	Op   string
	Expr Expr
}

Unary represents unary operators like +, -, NOT.

type UnionClause 

type UnionClause struct {
	Type  UnionType
	Right *Select
	Next  *UnionClause // For chaining multiple UNIONs
}

UnionClause represents a set operation chaining RIGHT select with current one.

type UnionType 

type UnionType int
const (
	// UnionDistinct corresponds to UNION (distinct).
	UnionDistinct UnionType = iota
	// UnionAll corresponds to UNION ALL.
	UnionAll
	// Except corresponds to EXCEPT.
	Except
	// Intersect corresponds to INTERSECT.
	Intersect
)

type Update 

type Update struct {
	Table string
	Sets  map[string]Expr
	Where Expr
}

Update represents an UPDATE statement.

type VarRef 

type VarRef struct{ Name string }

VarRef refers to a column (qualified or unqualified) in expressions.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.