minidb-engine 0.1.0__py3-none-any.whl

minidb/__init__.py

@@ -0,0 +1,4 @@
+"""MiniDB: a small educational embedded database engine."""
+from .database import Database
+
+__all__ = ["Database"]

minidb/database.py

@@ -0,0 +1,391 @@
+
+"""Public MiniDB API with storage, indexing, schema validation and transactions."""
+
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+from copy import deepcopy
+from threading import RLock
+from functools import wraps
+from time import perf_counter
+
+from .index import Index
+from .executor import execute_query
+from .storage import StorageEngine
+from .plugins import PluginManager
+
+
+def synchronized(method):
+    """Serialize database operations using a re-entrant lock."""
+    @wraps(method)
+    def wrapper(self, *args, **kwargs):
+        with self._lock:
+            return method(self, *args, **kwargs)
+    return wrapper
+
+
+class DatabaseError(Exception):
+    """Base exception for database errors."""
+
+
+class RecordNotFoundError(DatabaseError):
+    """Raised when a requested record does not exist."""
+
+
+class Database:
+
+    def __init__(self, file_path: str | Path = "data/minidb.log"):
+        self.storage = StorageEngine(file_path)
+        self._lock = RLock()
+
+        self.records: dict[str, dict[str, Any]] = {}
+        self.indexes = {}
+        self.schema = None
+        self.plugins = PluginManager()
+
+        self._transaction_snapshot = None
+        self._transaction_operations = None
+
+        self._recover()
+
+    def register_plugin(self, name: str, plugin: Any) -> None:
+        """Register a plugin with this database."""
+        self.plugins.register(name, plugin)
+
+    def activate_plugin(self, name: str) -> None:
+        """Activate a registered plugin for this database."""
+        self.plugins.activate(name, self)
+
+    def list_plugins(self) -> list[str]:
+        """List all registered plugins."""
+        return self.plugins.list_plugins()
+
+    def _recover(self):
+        """Rebuild records by replaying committed operations."""
+
+        def apply_operation(operation):
+            action = operation.get("action")
+            record_id = operation.get("id")
+
+            if not isinstance(record_id, str):
+                raise DatabaseError("Corrupt log: missing record id")
+
+            if action in ("insert", "update"):
+                document = operation.get("document")
+
+                if not isinstance(document, dict):
+                    raise DatabaseError("Corrupt log: invalid document")
+
+                self.records[record_id] = document
+
+            elif action == "delete":
+                self.records.pop(record_id, None)
+
+            else:
+                raise DatabaseError(
+                    f"Corrupt log: unknown action {action!r}"
+                )
+
+        for entry in self.storage.read_all():
+            action = entry.get("action")
+
+            if action == "transaction":
+                operations = entry.get("operations")
+
+                if not isinstance(operations, list):
+                    raise DatabaseError("Corrupt transaction log")
+
+                for operation in operations:
+                    if not isinstance(operation, dict):
+                        raise DatabaseError("Invalid transaction operation")
+
+                for operation in operations:
+                    apply_operation(operation)
+            else:
+                apply_operation(entry)
+
+        self._rebuild_indexes()
+
+    @synchronized
+    def set_schema(self, schema: dict[str, type]):
+        """Define allowed fields and their expected data types."""
+        if not isinstance(schema, dict) or not schema:
+            raise DatabaseError("Schema must be a non-empty dictionary")
+
+        for field, expected_type in schema.items():
+            if not isinstance(field, str) or not isinstance(expected_type, type):
+                raise DatabaseError("Invalid schema definition")
+
+        for document in self.records.values():
+            self._validate_document(document, schema)
+
+        self.schema = schema
+
+    def _validate_document(self, document, schema=None):
+        """Validate document fields and data types against the schema."""
+        schema = schema if schema is not None else self.schema
+
+        if schema is None:
+            return
+
+        unknown_fields = set(document) - set(schema)
+
+        if unknown_fields:
+            raise DatabaseError(
+                f"Unknown fields: {', '.join(sorted(unknown_fields))}"
+            )
+
+        for field, value in document.items():
+            expected_type = schema[field]
+
+            if not isinstance(value, expected_type):
+                raise DatabaseError(
+                    f"Field '{field}' must be of type {expected_type.__name__}"
+                )
+
+    def _rebuild_indexes(self):
+        """Rebuild all indexes from current records."""
+        for field, index in self.indexes.items():
+            index.clear()
+
+            for record_id, document in self.records.items():
+                if field in document:
+                    index.add(document[field], record_id)
+
+    def _write_operation(self, operation):
+        """Buffer operations during a transaction."""
+        if self._transaction_operations is not None:
+            self._transaction_operations.append(operation)
+        else:
+            self.storage.append(operation)
+
+    @synchronized
+    def begin(self):
+        """Start a thread-owned transaction."""
+        if self._transaction_snapshot is not None:
+            raise DatabaseError("Transaction already active")
+
+        self._lock.acquire()
+
+        try:
+            self._transaction_snapshot = deepcopy(self.records)
+            self._transaction_operations = []
+            return "Transaction started"
+
+        except Exception:
+            self._lock.release()
+            raise
+
+    @synchronized
+    def commit(self):
+        """Atomically commit a transaction and release its lock."""
+        if self._transaction_snapshot is None:
+            raise DatabaseError("No active transaction")
+
+        transaction = {
+            "action": "transaction",
+            "operations": self._transaction_operations
+        }
+
+        try:
+            if self._transaction_operations:
+                self.storage.append(transaction)
+
+        except Exception:
+            self.records = self._transaction_snapshot
+            self._transaction_snapshot = None
+            self._transaction_operations = None
+            self._rebuild_indexes()
+            raise
+
+        else:
+            self._transaction_snapshot = None
+            self._transaction_operations = None
+            return "Transaction committed"
+
+        finally:
+            self._lock.release()
+
+    @synchronized
+    def rollback(self):
+        """Restore previous records and release the transaction lock."""
+        if self._transaction_snapshot is None:
+            raise DatabaseError("No active transaction")
+
+        try:
+            self.records = self._transaction_snapshot
+            self._rebuild_indexes()
+            return "Transaction rolled back"
+
+        finally:
+            self._transaction_snapshot = None
+            self._transaction_operations = None
+            self._lock.release()
+
+    @synchronized
+    def insert(self, document: dict[str, Any]) -> str:
+        if not isinstance(document, dict):
+            raise TypeError("document must be a dictionary")
+
+        self._validate_document(document)
+
+        record_id = str(uuid4())
+        stored_document = dict(document)
+
+        self._write_operation({
+            "action": "insert",
+            "id": record_id,
+            "document": stored_document,
+        })
+
+        self.records[record_id] = stored_document
+
+        for field, index in self.indexes.items():
+            if field in stored_document:
+                index.add(stored_document[field], record_id)
+
+        return record_id
+
+    @synchronized
+    def get(self, record_id: str) -> dict[str, Any]:
+        try:
+            return dict(self.records[record_id])
+        except KeyError as exc:
+            raise RecordNotFoundError(
+                f"No record found with id {record_id}"
+            ) from exc
+
+    @synchronized
+    def all(self):
+        return [
+            {"_id": key, **dict(value)}
+            for key, value in self.records.items()
+        ]
+
+    @synchronized
+    def update(self, record_id: str, changes: dict[str, Any]):
+        if record_id not in self.records:
+            raise RecordNotFoundError(
+                f"No record found with id {record_id}"
+            )
+
+        if not isinstance(changes, dict):
+            raise TypeError("changes must be a dictionary")
+
+        old_document = self.records[record_id]
+        updated = {**old_document, **changes}
+
+        self._validate_document(updated)
+
+        self._write_operation({
+            "action": "update",
+            "id": record_id,
+            "document": updated,
+        })
+
+        for field, index in self.indexes.items():
+            if field in old_document:
+                index.remove(old_document[field], record_id)
+
+        self.records[record_id] = updated
+
+        for field, index in self.indexes.items():
+            if field in updated:
+                index.add(updated[field], record_id)
+
+    @synchronized
+    def delete(self, record_id: str):
+        if record_id not in self.records:
+            raise RecordNotFoundError(
+                f"No record found with id {record_id}"
+            )
+
+        old_document = self.records[record_id]
+
+        self._write_operation({
+            "action": "delete",
+            "id": record_id,
+        })
+
+        for field, index in self.indexes.items():
+            if field in old_document:
+                index.remove(old_document[field], record_id)
+
+        del self.records[record_id]
+
+    @synchronized
+    def create_index(self, field):
+        """Create an index for a field."""
+        if field in self.indexes:
+            return "Index already exists"
+
+        index = Index(field)
+
+        for record_id, document in self.records.items():
+            if field in document:
+                index.add(document[field], record_id)
+
+        self.indexes[field] = index
+
+        return f"Index created for {field}"
+
+    @synchronized
+    def find_by_index(self, field, value):
+        """Find records using an existing index."""
+        if field not in self.indexes:
+            raise DatabaseError(f"No index found for {field}")
+
+        record_ids = self.indexes[field].search(value)
+
+        return [
+            {"_id": record_id, **dict(self.records[record_id])}
+            for record_id in record_ids
+            if record_id in self.records
+        ]
+
+    @synchronized
+    
+    
+   
+    @synchronized
+    def execute(self, query: str):
+        """Execute queries and notify registered plugins."""
+        command = query.strip().upper()
+
+        if command == "BEGIN":
+            return self.begin()
+
+        if command == "COMMIT":
+            return self.commit()
+
+        if command == "ROLLBACK":
+            return self.rollback()
+
+        start = perf_counter()
+
+        try:
+            result = execute_query(self, query)
+        except Exception:
+            elapsed_ms = (perf_counter() - start) * 1000
+
+            for name in self.plugins.list_plugins():
+                plugin = self.plugins.get(name)
+
+                if hasattr(plugin, "record_execution"):
+                    plugin.record_execution(query, elapsed_ms, False)
+
+            raise
+
+        elapsed_ms = (perf_counter() - start) * 1000
+
+        for name in self.plugins.list_plugins():
+            plugin = self.plugins.get(name)
+
+            if hasattr(plugin, "record_query"):
+                plugin.record_query(query)
+
+            if hasattr(plugin, "record_execution"):
+                plugin.record_execution(query, elapsed_ms, True)
+
+        return result
+

minidb/executor.py

@@ -0,0 +1,214 @@
+
+import time
+
+from .query import parse, QueryError
+
+
+def convert_value(value):
+    """Convert query values into Python data types."""
+    value = value.strip()
+
+    if value.startswith('"') and value.endswith('"'):
+        return value[1:-1]
+
+    if value.startswith("'") and value.endswith("'"):
+        return value[1:-1]
+
+    try:
+        return int(value)
+    except ValueError:
+        try:
+            return float(value)
+        except ValueError:
+            return value
+
+
+def matches(record, condition):
+    """Check whether a record satisfies a WHERE condition."""
+    if condition is None:
+        return True
+
+    field = condition["field"]
+    operator = condition["operator"]
+    expected = convert_value(condition["value"])
+    actual = record.get(field)
+
+    if actual is None:
+        return False
+
+    try:
+        if operator == "=":
+            return actual == expected
+        if operator == "!=":
+            return actual != expected
+        if operator == ">":
+            return actual > expected
+        if operator == "<":
+            return actual < expected
+        if operator == ">=":
+            return actual >= expected
+        if operator == "<=":
+            return actual <= expected
+    except TypeError:
+        return False
+
+    raise QueryError(f"Unsupported operator: {operator}")
+
+
+def save_statistics(database, scan_type, examined, returned, start):
+    """Save statistics about the latest SELECT query."""
+    database.last_query_stats = {
+        "scan_type": scan_type,
+        "records_examined": examined,
+        "records_returned": returned,
+        "execution_time_ms": round(
+            (time.perf_counter() - start) * 1000, 4
+        )
+    }
+
+
+def execute_select(database, query):
+    """Execute SELECT and collect query statistics."""
+    start = time.perf_counter()
+    parsed = parse(query)
+    condition = parsed["condition"]
+
+    # Basic query planner.
+    if (
+        condition is not None
+        and condition["operator"] == "="
+        and condition["field"] in database.indexes
+    ):
+        value = convert_value(condition["value"])
+
+        candidates = database.find_by_index(
+            condition["field"], value
+        )
+
+        scan_type = "INDEX SCAN"
+        examined = len(candidates)
+
+    else:
+        candidates = database.all()
+        scan_type = "FULL SCAN"
+        examined = len(candidates)
+
+    filtered = [
+        record for record in candidates
+        if matches(record, condition)
+    ]
+
+    # Handle COUNT.
+    aggregate = parsed["fields"][0]
+
+    if aggregate == "COUNT(*)":
+        result = [{"COUNT(*)": len(filtered)}]
+
+    elif aggregate.startswith("SUM("):
+        field = aggregate[4:-1]
+
+        values = [
+            record[field] for record in filtered
+            if isinstance(record.get(field), (int, float))
+            and not isinstance(record.get(field), bool)
+        ]
+
+        result = [{aggregate: sum(values)}]
+
+    elif aggregate.startswith("AVG("):
+        field = aggregate[4:-1]
+
+        values = [
+            record[field] for record in filtered
+            if isinstance(record.get(field), (int, float))
+            and not isinstance(record.get(field), bool)
+        ]
+
+        average = sum(values) / len(values) if values else 0
+        result = [{aggregate: average}]
+
+    else:
+        # Apply ORDER BY.
+        order_by = parsed.get("order_by")
+        direction = parsed.get("direction", "ASC")
+
+        if order_by:
+            filtered.sort(
+                key=lambda record: (
+                    record.get(order_by) is None,
+                    record.get(order_by)
+                ),
+                reverse=(direction == "DESC")
+            )
+
+        # Apply field projection.
+        fields = parsed["fields"]
+
+        if fields == ["*"]:
+            result = filtered
+        else:
+            result = [
+                {
+                    "_id": record["_id"],
+                    **{
+                        field: record[field]
+                        for field in fields
+                        if field in record
+                    }
+                }
+                for record in filtered
+            ]
+
+    save_statistics(
+        database,
+        scan_type,
+        examined,
+        len(result),
+        start
+    )
+
+    return result
+
+
+def execute_query(database, query):
+    """Execute SELECT, INSERT, UPDATE and DELETE."""
+    parsed = parse(query)
+    command = parsed["type"]
+
+    if command == "SELECT":
+        return execute_select(database, query)
+
+    if command == "INSERT":
+        document = {
+            field: convert_value(value)
+            for field, value in parsed["document"].items()
+        }
+
+        return database.insert(document)
+
+    if command == "UPDATE":
+        changes = {
+            field: convert_value(value)
+            for field, value in parsed["changes"].items()
+        }
+
+        count = 0
+
+        for record in database.all():
+            if matches(record, parsed["condition"]):
+                database.update(record["_id"], changes)
+                count += 1
+
+        return count
+
+    if command == "DELETE":
+        count = 0
+
+        for record in database.all():
+            if matches(record, parsed["condition"]):
+                database.delete(record["_id"])
+                count += 1
+
+        return count
+
+    raise QueryError("Unsupported query")

minidb/index.py

@@ -0,0 +1,36 @@
+
+class Index:
+    """Simple in-memory index for faster record lookup."""
+
+    def __init__(self, field):
+        self.field = field
+        self.entries = {}
+
+    def add(self, value, record_id):
+        """Add a record ID to the index."""
+        try:
+            self.entries.setdefault(value, set()).add(record_id)
+        except TypeError:
+            pass
+
+    def remove(self, value, record_id):
+        """Remove a record ID from the index."""
+        try:
+            if value in self.entries:
+                self.entries[value].discard(record_id)
+
+                if not self.entries[value]:
+                    del self.entries[value]
+        except TypeError:
+            pass
+
+    def search(self, value):
+        """Find record IDs matching an exact value."""
+        try:
+            return set(self.entries.get(value, set()))
+        except TypeError:
+            return set()
+
+    def clear(self):
+        """Remove all index entries."""
+        self.entries.clear()

minidb/plugins/__init__.py

@@ -0,0 +1,6 @@
+
+"""MiniDB plugin system."""
+
+from .manager import PluginManager
+
+__all__ = ["PluginManager"]

minidb/plugins/manager.py

@@ -0,0 +1,42 @@
+
+"""Plugin management for MiniDB."""
+
+from typing import Any, Dict
+
+
+class PluginManager:
+    """Register, retrieve, and manage MiniDB plugins."""
+
+    def __init__(self):
+        self._plugins: Dict[str, Any] = {}
+
+    def register(self, name: str, plugin: Any) -> None:
+        """Register a plugin with a unique name."""
+        if not name:
+            raise ValueError("Plugin name cannot be empty.")
+
+        if name in self._plugins:
+            raise ValueError(f"Plugin '{name}' is already registered.")
+
+        if not callable(getattr(plugin, "activate", None)):
+            raise TypeError("A plugin must implement activate(database).")
+
+        self._plugins[name] = plugin
+
+    def activate(self, name: str, database: Any) -> None:
+        """Activate a registered plugin."""
+        if name not in self._plugins:
+            raise KeyError(f"Plugin '{name}' is not registered.")
+
+        self._plugins[name].activate(database)
+
+    def get(self, name: str) -> Any:
+        """Return a registered plugin."""
+        if name not in self._plugins:
+            raise KeyError(f"Plugin '{name}' is not registered.")
+
+        return self._plugins[name]
+
+    def list_plugins(self) -> list[str]:
+        """Return the names of all registered plugins."""
+        return list(self._plugins.keys())