minidb-sql 1.3.0__py3-none-any.whl

minidb_sql/__init__.py

@@ -0,0 +1,168 @@
+"""
+MiniDB - A miniature in-memory database with SQL-like query support.
+
+Features:
+- CREATE TABLE with typed columns (INTEGER, STRING, FLOAT, BOOLEAN)
+- INSERT, SELECT, UPDATE, DELETE operations
+- WHERE clause with AND/OR, comparisons (=, >, <, LIKE, IN)
+- ORDER BY for sorting
+- GROUP BY with aggregations (COUNT, SUM, AVG, MIN, MAX)
+- JOIN between tables
+- Automatic indexing on primary keys
+- Query planner (index scan vs table scan)
+- Persistence to JSON files
+
+Example:
+    from minidb_sql import MiniDB, Column, ColumnType
+
+    # Create database
+    db = MiniDB()
+
+    # Create table programmatically
+    db.create_table('users', [
+        Column('id', ColumnType.INTEGER, primary_key=True),
+        Column('name', ColumnType.STRING),
+        Column('age', ColumnType.INTEGER),
+    ])
+
+    # Or use SQL
+    db.execute('''
+        CREATE TABLE orders (
+            id INTEGER PRIMARY KEY,
+            user_id INTEGER,
+            total FLOAT
+        )
+    ''')
+
+    # Insert data
+    db.execute("INSERT INTO users (id, name, age) VALUES (1, 'Alice', 30)")
+    db.execute("INSERT INTO orders (id, user_id, total) VALUES (1, 1, 99.99)")
+
+    # Query with SQL
+    results = db.query('''
+        SELECT users.name, orders.total
+        FROM users
+        JOIN orders ON users.id = orders.user_id
+        WHERE users.age > 25
+    ''')
+
+    # Save and load
+    db.save('mydb.json')
+    db = MiniDB.load('mydb.json')
+"""
+
+from .column import Column, Schema
+from .database import MiniDB
+from .errors import (
+    AmbiguousColumnError,
+    ColumnError,
+    ColumnExistsError,
+    ColumnNotFoundError,
+    ConstraintError,
+    DuplicateKeyError,
+    FileReadError,
+    FileWriteError,
+    InvalidQueryError,
+    MiniDBError,
+    NullValueError,
+    ParseError,
+    PersistenceError,
+    PrimaryKeyError,
+    QueryError,
+    SyntaxError_,
+    TableError,
+    TableExistsError,
+    TableNotFoundError,
+    TypeError_,
+    TypeMismatchError,
+    VersionMismatchError,
+)
+from .index import HashIndex, IndexManager
+from .parser import (
+    BeginQuery,
+    CommitQuery,
+    CreateTableQuery,
+    DeleteQuery,
+    DropTableQuery,
+    InsertQuery,
+    Lexer,
+    Parser,
+    RollbackQuery,
+    SelectQuery,
+    Token,
+    UpdateQuery,
+    parse_sql,
+)
+from .persistence import _deserialize as load_database
+from .persistence import _serialize as save_database
+from .planner import QueryPlan, QueryPlanner, ScanType
+from .query import QueryExecutor
+from .table import Table
+from .types import ColumnType, QueryResult, QueryType, Row, TokenType
+
+__all__ = [
+    'AmbiguousColumnError',
+    'BeginQuery',
+    # Schema
+    'Column',
+    'ColumnError',
+    'ColumnExistsError',
+    'ColumnNotFoundError',
+    # Types
+    'ColumnType',
+    'CommitQuery',
+    'ConstraintError',
+    'CreateTableQuery',
+    'DeleteQuery',
+    'DropTableQuery',
+    'DuplicateKeyError',
+    'FileReadError',
+    'FileWriteError',
+    # Indexing
+    'HashIndex',
+    'IndexManager',
+    'InsertQuery',
+    'InvalidQueryError',
+    'Lexer',
+    # Main API
+    'MiniDB',
+    # Errors
+    'MiniDBError',
+    'NullValueError',
+    'ParseError',
+    'Parser',
+    'PersistenceError',
+    'PrimaryKeyError',
+    'QueryError',
+    # Query execution
+    'QueryExecutor',
+    'QueryPlan',
+    # Query planning
+    'QueryPlanner',
+    'QueryResult',
+    'QueryType',
+    'RollbackQuery',
+    'Row',
+    'ScanType',
+    'Schema',
+    'SelectQuery',
+    'SyntaxError_',
+    # Storage
+    'Table',
+    'TableError',
+    'TableExistsError',
+    'TableNotFoundError',
+    'Token',
+    'TokenType',
+    'TypeError_',
+    'TypeMismatchError',
+    'UpdateQuery',
+    'VersionMismatchError',
+    'load_database',
+    # Parsing
+    'parse_sql',
+    # Persistence
+    'save_database',
+]
+
+__version__ = '1.3.0'  # x-release-please-version

minidb_sql/column.py

@@ -0,0 +1,170 @@
+"""Column definition and schema management for MiniDB."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import ColumnError, NullValueError, TypeMismatchError
+from .types import ColumnType
+
+
+@dataclass
+class Column:
+    """Represents a column definition in a table."""
+
+    name: str
+    type: ColumnType
+    primary_key: bool = False
+    nullable: bool = True
+    default: Any = None
+
+    def __post_init__(self):
+        """Validate column definition after initialization."""
+        if self.primary_key and not self.nullable:
+            # Primary keys are implicitly NOT NULL
+            pass
+        if self.primary_key:
+            self.nullable = False
+        if self.default is not None:
+            # Same cast as INSERT. A raw default skips INTEGER's int() rules.
+            self.default = self.validate(self.default)
+
+    def validate(self, value: Any) -> Any:
+        """
+        Validate and optionally cast a value for this column.
+
+        Args:
+            value: The value to validate
+
+        Returns:
+            The validated (and possibly cast) value
+
+        Raises:
+            NullValueError: If value is None and column is not nullable
+            TypeMismatchError: If value cannot be cast to the column type
+        """
+        if value is None:
+            if not self.nullable:
+                raise NullValueError(self.name)
+            return None
+
+        # Try to cast the value to the correct type
+        try:
+            cast_value = self.type.cast(value)
+        except (ValueError, TypeError) as e:
+            raise TypeMismatchError(self.name, self.type.name, type(value).__name__) from e
+
+        return cast_value
+
+    def to_dict(self) -> dict:
+        """Serialize column to a dictionary."""
+        return {
+            'name': self.name,
+            'type': self.type.name,
+            'primary_key': self.primary_key,
+            'nullable': self.nullable,
+            'default': self.default,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'Column':
+        """Deserialize column from a dictionary."""
+        return cls(
+            name=data['name'],
+            type=ColumnType[data['type']],
+            primary_key=data.get('primary_key', False),
+            nullable=data.get('nullable', True),
+            default=data.get('default'),
+        )
+
+
+@dataclass
+class Schema:
+    """Represents a table schema with multiple columns."""
+
+    columns: list[Column] = field(default_factory=list)
+    _column_map: dict[str, Column] = field(default_factory=dict, repr=False)
+    _primary_key: str | None = field(default=None, repr=False)
+
+    def __post_init__(self):
+        """Build internal structures after initialization."""
+        self._rebuild_indexes()
+
+    def _rebuild_indexes(self):
+        """Rebuild internal indexes for fast lookups."""
+        seen: set[str] = set()
+        for col in self.columns:
+            if col.name in seen:
+                # The map would keep the last column and drop the earlier type.
+                raise ColumnError(f"Duplicate column name '{col.name}'")
+            seen.add(col.name)
+        self._column_map = {col.name: col for col in self.columns}
+        primary_keys = [col.name for col in self.columns if col.primary_key]
+        if len(primary_keys) > 1:
+            quoted = ', '.join(f"'{name}'" for name in primary_keys)
+            raise ColumnError(f'Multiple PRIMARY KEY columns: {quoted}')
+        self._primary_key = primary_keys[0] if primary_keys else None
+
+    def add_column(self, column: Column) -> None:
+        """Add a column to the schema."""
+        if column.name in self._column_map:
+            raise ValueError(f"Column '{column.name}' already exists")
+        if column.primary_key and self._primary_key is not None:
+            raise ColumnError(f"Multiple PRIMARY KEY columns: '{self._primary_key}', '{column.name}'")
+        self.columns.append(column)
+        self._column_map[column.name] = column
+        if column.primary_key:
+            self._primary_key = column.name
+
+    def get_column(self, name: str) -> Column | None:
+        """Get a column by name."""
+        return self._column_map.get(name)
+
+    def has_column(self, name: str) -> bool:
+        """Check if a column exists."""
+        return name in self._column_map
+
+    @property
+    def primary_key(self) -> str | None:
+        """Get the primary key column name, if any."""
+        return self._primary_key
+
+    @property
+    def column_names(self) -> list[str]:
+        """Get list of all column names."""
+        return [col.name for col in self.columns]
+
+    def validate_row(self, row: dict, allow_missing: bool = False) -> dict:
+        """
+        Validate a row against the schema.
+
+        Args:
+            row: The row data to validate
+            allow_missing: If True, missing columns get default values
+
+        Returns:
+            A validated row with all columns present
+        """
+        validated = {}
+        for col in self.columns:
+            if col.name in row:
+                validated[col.name] = col.validate(row[col.name])
+            elif allow_missing:
+                if col.default is not None:
+                    validated[col.name] = col.validate(col.default)
+                elif col.nullable:
+                    validated[col.name] = None
+                else:
+                    raise NullValueError(col.name)
+            else:
+                raise ValueError(f'Missing column: {col.name}')
+        return validated
+
+    def to_dict(self) -> dict:
+        """Serialize schema to a dictionary."""
+        return {'columns': [col.to_dict() for col in self.columns]}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'Schema':
+        """Deserialize schema from a dictionary."""
+        columns = [Column.from_dict(col_data) for col_data in data['columns']]
+        return cls(columns=columns)

minidb_sql/database.py

@@ -0,0 +1,258 @@
+"""Main database API for MiniDB."""
+
+import copy
+from collections.abc import Sequence
+from typing import Any
+
+from .column import Column, Schema
+from .errors import InvalidQueryError, MiniDBError, TableExistsError, TableNotFoundError
+from .parser import (
+    BeginQuery,
+    CommitQuery,
+    CreateTableQuery,
+    DropTableQuery,
+    RollbackQuery,
+    SelectQuery,
+    bind_params,
+    parse_sql,
+)
+from .persistence import _deserialize, _serialize
+from .planner import QueryPlan, QueryPlanner, ScanType
+from .query import QueryExecutor
+from .table import Table
+from .types import QueryResult, Row
+
+
+class MiniDB:
+    """
+    MiniDB - A miniature in-memory database with SQL-like query support.
+
+    Example usage:
+        db = MiniDB()
+
+        # Create a table
+        db.execute('''
+            CREATE TABLE users (
+                id INTEGER PRIMARY KEY,
+                name STRING,
+                age INTEGER,
+                salary FLOAT,
+                active BOOLEAN
+            )
+        ''')
+
+        # Insert data
+        db.execute("INSERT INTO users (id, name, age, salary, active) VALUES (1, 'Alice', 30, 50000.0, true)")
+
+        # Query data
+        results = db.query("SELECT * FROM users WHERE age > 25")
+
+        # Save to file
+        db.save('database.json')
+
+        # Load from file
+        db = MiniDB.load('database.json')
+    """
+
+    def __init__(self):
+        """Initialize an empty database."""
+        self._tables: dict[str, Table] = {}
+        self._executor: QueryExecutor | None = None
+        self._txn_snapshot: dict[str, Table] | None = None
+
+    @property
+    def tables(self) -> list[str]:
+        """Get list of table names."""
+        return list(self._tables.keys())
+
+    @property
+    def executor(self) -> QueryExecutor:
+        """Get or create the query executor."""
+        if self._executor is None:
+            self._executor = QueryExecutor(self._tables)
+        return self._executor
+
+    def create_table(self, name: str, columns: list[Column]) -> None:
+        """
+        Programmatically create a table.
+
+        Args:
+            name: Table name
+            columns: List of Column objects
+
+        Raises:
+            TableExistsError: If table already exists
+            ColumnError: If more than one column is a primary key
+        """
+        if name in self._tables:
+            raise TableExistsError(name)
+
+        schema = Schema(columns=columns)
+        table = Table(name=name, schema=schema)
+        self._tables[name] = table
+
+        # Reset executor to pick up new tables
+        self._executor = None
+
+    def drop_table(self, name: str) -> None:
+        """
+        Drop a table.
+
+        Args:
+            name: Table name
+
+        Raises:
+            TableNotFoundError: If table doesn't exist
+        """
+        if name not in self._tables:
+            raise TableNotFoundError(name)
+
+        del self._tables[name]
+        self._executor = None
+
+    def get_table(self, name: str) -> Table | None:
+        """Get a table by name."""
+        return self._tables.get(name)
+
+    def execute(self, sql: str, params: Sequence[Any] | None = None) -> QueryResult:
+        """
+        Execute a SQL statement.
+
+        Args:
+            sql: SQL statement string
+            params: Values for ? placeholders, bound left-to-right after parse
+
+        Returns:
+            - For SELECT: list of row dictionaries
+            - For INSERT: row ID (int)
+            - For UPDATE/DELETE: number of affected rows (int)
+            - For CREATE/DROP TABLE: None
+            - For BEGIN/COMMIT/ROLLBACK: None
+
+        Raises:
+            MiniDBError: If query execution fails
+        """
+        query = parse_sql(sql)
+        bind_params(query, params)
+
+        if isinstance(query, BeginQuery):
+            if self._txn_snapshot is not None:
+                raise InvalidQueryError('already in a transaction')
+            self._txn_snapshot = {
+                name: Table.from_dict(copy.deepcopy(table.to_dict())) for name, table in self._tables.items()
+            }
+            return None
+
+        if isinstance(query, CommitQuery):
+            if self._txn_snapshot is None:
+                raise InvalidQueryError('no transaction in progress')
+            self._txn_snapshot = None
+            self._executor = None
+            return None
+
+        if isinstance(query, RollbackQuery):
+            if self._txn_snapshot is None:
+                raise InvalidQueryError('no transaction in progress')
+            self._tables = self._txn_snapshot
+            self._txn_snapshot = None
+            self._executor = None
+            return None
+
+        if isinstance(query, CreateTableQuery):
+            columns = [
+                Column(name=col.name, type=col.type, primary_key=col.primary_key, nullable=col.nullable)
+                for col in query.columns
+            ]
+            self.create_table(query.table, columns)
+            return None
+
+        elif isinstance(query, DropTableQuery):
+            self.drop_table(query.table)
+            return None
+
+        else:
+            return self.executor.execute(query)
+
+    def query(self, sql: str, params: Sequence[Any] | None = None) -> list[Row]:
+        """
+        Execute a SELECT query and return results.
+
+        Args:
+            sql: SELECT statement
+            params: Values for ? placeholders, bound left-to-right after parse
+
+        Returns:
+            List of row dictionaries
+
+        Raises:
+            MiniDBError: If the statement is not SELECT or execution fails
+        """
+        result = self.execute(sql, params)
+        if isinstance(result, list):
+            return result
+        raise MiniDBError('query() only runs SELECT; use execute() for INSERT, UPDATE, DELETE, CREATE, or DROP')
+
+    def explain(self, sql: str, params: Sequence[Any] | None = None) -> str:
+        """
+        Return the query plan for a SELECT statement.
+
+        Args:
+            sql: SELECT statement
+            params: Values for ? placeholders, bound before planning
+
+        Returns:
+            String representation of the scan that runs
+
+        Raises:
+            MiniDBError: If the statement is not SELECT
+            TableNotFoundError: If the FROM table does not exist
+        """
+        query = parse_sql(sql)
+        bind_params(query, params)
+        if not isinstance(query, SelectQuery):
+            raise MiniDBError('explain() is SELECT-only')
+        if query.table not in self._tables:
+            raise TableNotFoundError(query.table)
+        # Joins nested-loop both sides. Do not report an index plan of the FROM table.
+        if query.joins:
+            estimated = self._tables[query.table].row_count
+            return str(QueryPlan(scan_type=ScanType.TABLE_SCAN, estimated_rows=estimated))
+        return str(QueryPlanner(self._tables[query.table]).plan_select(query))
+
+    def save(self, filepath: str) -> None:
+        """
+        Save the database to a file.
+
+        Args:
+            filepath: Path to the output file
+        """
+        _serialize(self._tables, filepath)
+
+    @classmethod
+    def load(cls, filepath: str) -> 'MiniDB':
+        """
+        Load a database from a file.
+
+        Args:
+            filepath: Path to the input file
+
+        Returns:
+            Loaded database instance
+        """
+        tables = _deserialize(filepath)
+        db = cls()
+        db._tables = tables
+        return db
+
+    def __repr__(self) -> str:
+        """String representation of the database."""
+        table_info = ', '.join(f'{name}({table.row_count} rows)' for name, table in self._tables.items())
+        return f'MiniDB({table_info})'
+
+    def __len__(self) -> int:
+        """Return number of tables."""
+        return len(self._tables)
+
+    def __contains__(self, table_name: str) -> bool:
+        """Check if a table exists."""
+        return table_name in self._tables