cinchdb 0.1.13__py3-none-any.whl → 0.1.15__py3-none-any.whl

cinchdb/managers/table.py

@@ -19,6 +19,9 @@ class TableManager:
 
     # Protected column names that users cannot use
     PROTECTED_COLUMNS = {"id", "created_at", "updated_at"}
+    
+    # Protected table name prefixes that users cannot use
+    PROTECTED_TABLE_PREFIXES = ("__", "sqlite_")
 
     def __init__(
         self, project_root: Path, database: str, branch: str, tenant: str = "main"
@@ -48,18 +51,24 @@ class TableManager:
         tables = []
 
         with DatabaseConnection(self.db_path) as conn:
-            # Get all user tables (exclude sqlite internal tables)
+            # Get all tables first, then filter in Python (more reliable than SQL LIKE)
             cursor = conn.execute(
                 """
                 SELECT name FROM sqlite_master 
                 WHERE type='table' 
-                AND name NOT LIKE 'sqlite_%'
                 ORDER BY name
                 """
             )
-
-            for row in cursor.fetchall():
-                table = self.get_table(row["name"])
+            
+            # Filter out system tables and protected tables using Python
+            all_table_names = [row["name"] for row in cursor.fetchall()]
+            user_table_names = [
+                name for name in all_table_names 
+                if not name.startswith('sqlite_') and not name.startswith('__')
+            ]
+
+            for table_name in user_table_names:
+                table = self.get_table(table_name)
                 tables.append(table)
 
         return tables
@@ -82,6 +91,14 @@ class TableManager:
         """
         # Check maintenance mode
         check_maintenance_mode(self.project_root, self.database, self.branch)
+        
+        # Validate table name doesn't use protected prefixes
+        for prefix in self.PROTECTED_TABLE_PREFIXES:
+            if table_name.startswith(prefix):
+                raise ValueError(
+                    f"Table name '{table_name}' is not allowed. "
+                    f"Table names cannot start with '{prefix}' as these are reserved for system use."
+                )
 
         # Validate table doesn't exist
         if self._table_exists(table_name):
@@ -325,6 +342,14 @@ class TableManager:
         """
         # Check maintenance mode
         check_maintenance_mode(self.project_root, self.database, self.branch)
+        
+        # Validate target table name doesn't use protected prefixes
+        for prefix in self.PROTECTED_TABLE_PREFIXES:
+            if target_table.startswith(prefix):
+                raise ValueError(
+                    f"Table name '{target_table}' is not allowed. "
+                    f"Table names cannot start with '{prefix}' as these are reserved for system use."
+                )
 
         if not self._table_exists(source_table):
             raise ValueError(f"Source table '{source_table}' does not exist")

cinchdb/managers/tenant.py

@@ -12,7 +12,6 @@ from cinchdb.models import Tenant
 from cinchdb.core.path_utils import (
     get_branch_path,
     get_tenant_db_path,
-    get_database_path,
     list_tenants,
 )
 from cinchdb.core.connection import DatabaseConnection
@@ -279,18 +278,18 @@ class TenantManager:
                 with DatabaseConnection(empty_db_path):
                     pass  # Just initialize with PRAGMAs
             
-            # Optimize with small page size for empty template
+            # Set reasonable default page size for template
             # We need to rebuild the database with new page size
             temp_path = empty_db_path.with_suffix('.tmp')
             
-            # Create new database with 512-byte pages
+            # Create new database with 4KB pages (SQLite default, good balance for general use)
             vacuum_conn = sqlite3.connect(str(empty_db_path))
             vacuum_conn.isolation_level = None
-            vacuum_conn.execute("PRAGMA page_size = 512")
+            vacuum_conn.execute("PRAGMA page_size = 4096")
             vacuum_conn.execute(f"VACUUM INTO '{temp_path}'")
             vacuum_conn.close()
             
-            # Replace original with optimized version
+            # Replace original with default optimized version
             shutil.move(str(temp_path), str(empty_db_path))
             
             # Mark as materialized now that the file exists
@@ -351,150 +350,6 @@ class TenantManager:
                 if shm_path.exists():
                     shm_path.unlink()
 
-    def optimize_all_tenants(self, force: bool = False) -> dict:
-        """Optimize storage for all materialized tenants in the branch.
-        
-        This is designed to be called periodically (e.g., every minute) to:
-        - Reclaim unused space with VACUUM
-        - Adjust page sizes as databases grow
-        - Keep small databases compact
-        
-        Args:
-            force: If True, optimize all tenants regardless of size
-            
-        Returns:
-            Dictionary with optimization results:
-            - optimized: List of tenant names that were optimized
-            - skipped: List of tenant names that were skipped
-            - errors: List of tuples (tenant_name, error_message)
-        """
-        results = {
-            "optimized": [],
-            "skipped": [],
-            "errors": []
-        }
-        
-        # Ensure initialization
-        self._ensure_initialized()
-        
-        if not self.branch_id:
-            return results
-            
-        # Get all materialized tenants for this branch
-        tenants = self.metadata_db.list_tenants(self.branch_id, materialized_only=True)
-        
-        for tenant in tenants:
-            tenant_name = tenant['name']
-            
-            # Skip system tenants unless forced
-            if not force and tenant_name in ["main", self._empty_tenant_name]:
-                results["skipped"].append(tenant_name)
-                continue
-                
-            try:
-                optimized = self.optimize_tenant_storage(tenant_name, force=force)
-                if optimized:
-                    results["optimized"].append(tenant_name)
-                else:
-                    results["skipped"].append(tenant_name)
-            except Exception as e:
-                results["errors"].append((tenant_name, str(e)))
-                
-        return results
-    
-    def optimize_tenant_storage(self, tenant_name: str, force: bool = False) -> bool:
-        """Optimize tenant database storage with VACUUM and optional page size adjustment.
-        
-        This performs:
-        1. Always: VACUUM to reclaim unused space and defragment
-        2. If needed: Rebuild with optimal page size based on database size
-        
-        Args:
-            tenant_name: Name of tenant to optimize
-            force: If True, always perform VACUUM even if page size is optimal
-            
-        Returns:
-            True if optimization was performed, False if tenant doesn't exist
-        """
-        # Ensure initialization
-        self._ensure_initialized()
-        
-        if not self.branch_id:
-            return False
-            
-        # Skip system tenants
-        if tenant_name in ["main", self._empty_tenant_name]:
-            return False
-            
-        # Get tenant info
-        tenant_info = self.metadata_db.get_tenant(self.branch_id, tenant_name)
-        if not tenant_info or not tenant_info['materialized']:
-            return False
-            
-        db_path = get_tenant_db_path(
-            self.project_root, self.database, self.branch, tenant_name
-        )
-        
-        if not db_path.exists():
-            return False
-            
-        # Check current page size
-        conn = sqlite3.connect(str(db_path))
-        current_page_size = conn.execute("PRAGMA page_size").fetchone()[0]
-        conn.close()
-        
-        # Determine optimal page size
-        optimal_page_size = self._get_optimal_page_size(db_path)
-        
-        # Decide if we need to rebuild with new page size
-        needs_page_size_change = (current_page_size != optimal_page_size and 
-                                  db_path.stat().st_size > 1024 * 1024)  # Only if > 1MB
-        
-        if needs_page_size_change:
-            # Rebuild with new page size using VACUUM INTO
-            temp_path = db_path.with_suffix('.tmp')
-            conn = sqlite3.connect(str(db_path))
-            conn.isolation_level = None
-            conn.execute(f"PRAGMA page_size = {optimal_page_size}")
-            conn.execute(f"VACUUM INTO '{temp_path}'")
-            conn.close()
-            
-            # Replace original with optimized version
-            shutil.move(str(temp_path), str(db_path))
-            return True
-        elif force or current_page_size == 512:
-            # Just run regular VACUUM to defragment and reclaim space
-            # Always vacuum 512-byte page databases to keep them compact
-            conn = sqlite3.connect(str(db_path))
-            conn.isolation_level = None
-            conn.execute("VACUUM")
-            conn.close()
-            return True
-            
-        return False
-    
-    def _get_optimal_page_size(self, db_path: Path) -> int:
-        """Determine optimal page size based on database file size.
-        
-        Args:
-            db_path: Path to database file
-            
-        Returns:
-            Optimal page size in bytes
-        """
-        if not db_path.exists():
-            return 512  # Default for new/empty databases
-            
-        size_mb = db_path.stat().st_size / (1024 * 1024)
-        
-        if size_mb < 0.1:  # < 100KB
-            return 512
-        elif size_mb < 10:  # < 10MB
-            return 4096  # 4KB - good balance for small-medium DBs
-        elif size_mb < 100:  # < 100MB
-            return 8192  # 8KB - better for larger rows
-        else:  # >= 100MB
-            return 16384  # 16KB - optimal for bulk operations
     
     def materialize_tenant(self, tenant_name: str) -> None:
         """Materialize a lazy tenant into an actual database file.
@@ -899,3 +754,88 @@ class TenantManager:
         """
         db_path = self.get_tenant_db_path_for_operation(tenant_name, is_write)
         return DatabaseConnection(db_path)
+
+    def vacuum_tenant(self, tenant_name: str) -> dict:
+        """Run VACUUM operation on a specific tenant to reclaim space and optimize performance.
+        
+        This performs SQLite's VACUUM command which:
+        - Reclaims space from deleted records
+        - Defragments the database file
+        - Can improve query performance
+        - Rebuilds database statistics
+        
+        Args:
+            tenant_name: Name of the tenant to vacuum
+            
+        Returns:
+            Dictionary with vacuum results:
+            - success: Whether vacuum completed successfully
+            - tenant: Name of the tenant
+            - size_before: Size in bytes before vacuum
+            - size_after: Size in bytes after vacuum
+            - space_reclaimed: Bytes reclaimed by vacuum
+            - duration_seconds: Time taken for vacuum operation
+            
+        Raises:
+            ValueError: If tenant doesn't exist or is not materialized
+        """
+        import time
+        
+        # Ensure initialization
+        self._ensure_initialized()
+        
+        # Check if tenant exists
+        if tenant_name != self._empty_tenant_name:
+            if not self.branch_id:
+                raise ValueError(f"Branch '{self.branch}' not found")
+                
+            tenant_info = self.metadata_db.get_tenant(self.branch_id, tenant_name)
+            if not tenant_info:
+                raise ValueError(f"Tenant '{tenant_name}' does not exist")
+        
+        # Check if tenant is materialized
+        if self.is_tenant_lazy(tenant_name):
+            raise ValueError(f"Cannot vacuum lazy tenant '{tenant_name}'. Tenant must be materialized first.")
+        
+        # Get database path
+        db_path = self._get_sharded_tenant_db_path(tenant_name)
+        
+        if not db_path.exists():
+            raise ValueError(f"Database file for tenant '{tenant_name}' does not exist")
+        
+        # Get size before vacuum
+        size_before = db_path.stat().st_size
+        
+        # Perform vacuum operation
+        start_time = time.time()
+        success = False
+        error_message = None
+        
+        try:
+            with DatabaseConnection(db_path) as conn:
+                # Run VACUUM command
+                conn.execute("VACUUM")
+            success = True
+        except Exception as e:
+            error_message = str(e)
+        
+        duration = time.time() - start_time
+        
+        # Get size after vacuum
+        size_after = db_path.stat().st_size if db_path.exists() else 0
+        space_reclaimed = max(0, size_before - size_after)
+        
+        result = {
+            "success": success,
+            "tenant": tenant_name,
+            "size_before": size_before,
+            "size_after": size_after,
+            "space_reclaimed": space_reclaimed,
+            "space_reclaimed_mb": round(space_reclaimed / (1024 * 1024), 2),
+            "duration_seconds": round(duration, 2)
+        }
+        
+        if not success:
+            result["error"] = error_message
+        
+        return result

cinchdb/plugins/__init__.py

@@ -0,0 +1,17 @@
+"""
+CinchDB Plugin System
+
+Extensible plugin architecture for CinchDB.
+"""
+
+from .base import BasePlugin, PluginHook
+from .manager import PluginManager
+from .decorators import hook, plugin_method
+
+__all__ = [
+    "BasePlugin",
+    "PluginHook", 
+    "PluginManager",
+    "hook",
+    "plugin_method",
+]

cinchdb/plugins/base.py

@@ -0,0 +1,99 @@
+"""
+Base classes for CinchDB plugins.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Callable
+from enum import Enum
+
+
+class PluginHook(Enum):
+    """Available plugin hooks."""
+    # Database lifecycle hooks
+    DATABASE_INIT = "database_init"
+    DATABASE_CONNECT = "database_connect"
+    DATABASE_DISCONNECT = "database_disconnect"
+    
+    # Query hooks
+    QUERY_BEFORE = "query_before"
+    QUERY_AFTER = "query_after"
+    QUERY_ERROR = "query_error"
+    
+    # Table hooks
+    TABLE_CREATE = "table_create"
+    TABLE_DROP = "table_drop"
+    TABLE_ALTER = "table_alter"
+    
+    # Tenant hooks
+    TENANT_CREATE = "tenant_create"
+    TENANT_DROP = "tenant_drop"
+    
+    # Branch hooks
+    BRANCH_CREATE = "branch_create"
+    BRANCH_SWITCH = "branch_switch"
+    BRANCH_MERGE = "branch_merge"
+    
+    # CLI hooks
+    CLI_COMMAND_BEFORE = "cli_command_before"
+    CLI_COMMAND_AFTER = "cli_command_after"
+
+
+class BasePlugin(ABC):
+    """Base class for all CinchDB plugins."""
+    
+    def __init__(self):
+        self.name = self.__class__.__name__
+        self.version = "1.0.0"
+        self.description = ""
+        self._hooks: Dict[PluginHook, List[Callable]] = {}
+        self._methods: Dict[str, Callable] = {}
+        
+    @abstractmethod
+    def initialize(self, cinchdb_instance) -> None:
+        """Initialize the plugin with a CinchDB instance."""
+        pass
+    
+    def register_hook(self, hook: PluginHook, callback: Callable) -> None:
+        """Register a callback for a specific hook."""
+        if hook not in self._hooks:
+            self._hooks[hook] = []
+        self._hooks[hook].append(callback)
+    
+    def register_method(self, method_name: str, method: Callable) -> None:
+        """Register a new method to be added to CinchDB instances."""
+        self._methods[method_name] = method
+    
+    def get_hooks(self) -> Dict[PluginHook, List[Callable]]:
+        """Get all registered hooks."""
+        return self._hooks.copy()
+    
+    def get_methods(self) -> Dict[str, Callable]:
+        """Get all registered methods."""
+        return self._methods.copy()
+    
+    def call_hook(self, hook: PluginHook, *args, **kwargs) -> Any:
+        """Call all callbacks for a specific hook."""
+        results = []
+        for callback in self._hooks.get(hook, []):
+            try:
+                result = callback(*args, **kwargs)
+                results.append(result)
+            except Exception as e:
+                # Log error but don't break other plugins
+                print(f"Plugin {self.name} hook {hook} failed: {e}")
+        return results
+    
+    def cleanup(self) -> None:
+        """Cleanup when plugin is unloaded."""
+        pass
+    
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        """Get plugin metadata."""
+        return {
+            "name": self.name,
+            "version": self.version,
+            "description": self.description,
+            "hooks": list(self._hooks.keys()),
+            "methods": list(self._methods.keys()),
+        }

cinchdb/plugins/decorators.py

@@ -0,0 +1,45 @@
+"""
+Decorators for plugin development.
+"""
+
+from typing import Callable
+
+from .base import PluginHook
+
+
+def hook(hook_type: PluginHook):
+    """Decorator to register a method as a hook callback."""
+    def decorator(func: Callable) -> Callable:
+        func._plugin_hook = hook_type
+        return func
+    return decorator
+
+
+def plugin_method(method_name: str):
+    """Decorator to register a method to be added to CinchDB instances."""
+    def decorator(func: Callable) -> Callable:
+        func._plugin_method_name = method_name
+        return func
+    return decorator
+
+
+class PluginDecorators:
+    """Helper class to collect decorated methods from a plugin class."""
+    
+    @staticmethod
+    def collect_hooks(plugin_instance) -> None:
+        """Collect and register hook methods from a plugin instance."""
+        for attr_name in dir(plugin_instance):
+            attr = getattr(plugin_instance, attr_name)
+            if callable(attr) and hasattr(attr, '_plugin_hook'):
+                hook_type = attr._plugin_hook
+                plugin_instance.register_hook(hook_type, attr)
+    
+    @staticmethod
+    def collect_methods(plugin_instance) -> None:
+        """Collect and register plugin methods from a plugin instance."""
+        for attr_name in dir(plugin_instance):
+            attr = getattr(plugin_instance, attr_name)
+            if callable(attr) and hasattr(attr, '_plugin_method_name'):
+                method_name = attr._plugin_method_name
+                plugin_instance.register_method(method_name, attr)

cinchdb/plugins/manager.py

@@ -0,0 +1,178 @@
+"""
+Plugin manager for CinchDB.
+"""
+
+import importlib
+import importlib.util
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+try:
+    from importlib.metadata import entry_points
+except ImportError:
+    # Fallback for Python < 3.8
+    from importlib_metadata import entry_points
+
+from .base import BasePlugin, PluginHook
+
+logger = logging.getLogger(__name__)
+
+
+class PluginManager:
+    """Manages plugin lifecycle and hooks for CinchDB."""
+    
+    def __init__(self):
+        self.plugins: Dict[str, BasePlugin] = {}
+        self._cinchdb_instance = None
+        
+    def set_cinchdb_instance(self, instance):
+        """Set the CinchDB instance for plugins."""
+        self._cinchdb_instance = instance
+        
+        # Initialize any already loaded plugins
+        for plugin in self.plugins.values():
+            try:
+                plugin.initialize(instance)
+            except Exception as e:
+                logger.error(f"Failed to initialize plugin {plugin.name}: {e}")
+    
+    def register_plugin(self, plugin: BasePlugin) -> None:
+        """Register a plugin instance."""
+        plugin_name = plugin.name
+        
+        if plugin_name in self.plugins:
+            logger.warning(f"Plugin {plugin_name} already registered, replacing")
+        
+        self.plugins[plugin_name] = plugin
+        
+        # Initialize with CinchDB instance if available
+        if self._cinchdb_instance:
+            try:
+                plugin.initialize(self._cinchdb_instance)
+                self._apply_plugin_methods(plugin)
+            except Exception as e:
+                logger.error(f"Failed to initialize plugin {plugin_name}: {e}")
+        
+        logger.info(f"Plugin {plugin_name} registered successfully")
+    
+    def unregister_plugin(self, plugin_name: str) -> None:
+        """Unregister a plugin."""
+        if plugin_name in self.plugins:
+            plugin = self.plugins[plugin_name]
+            try:
+                plugin.cleanup()
+            except Exception as e:
+                logger.error(f"Error cleaning up plugin {plugin_name}: {e}")
+            
+            del self.plugins[plugin_name]
+            logger.info(f"Plugin {plugin_name} unregistered")
+    
+    def load_plugin_from_module(self, module_name: str) -> None:
+        """Load a plugin from a module name."""
+        try:
+            module = importlib.import_module(module_name)
+            
+            # Look for plugin classes
+            for attr_name in dir(module):
+                attr = getattr(module, attr_name)
+                if (isinstance(attr, type) and 
+                    issubclass(attr, BasePlugin) and 
+                    attr != BasePlugin):
+                    
+                    plugin_instance = attr()
+                    self.register_plugin(plugin_instance)
+                    return
+            
+            logger.warning(f"No plugin class found in module {module_name}")
+            
+        except ImportError as e:
+            logger.error(f"Failed to import plugin module {module_name}: {e}")
+        except Exception as e:
+            logger.error(f"Failed to load plugin from {module_name}: {e}")
+    
+    def load_plugin_from_file(self, file_path: Path) -> None:
+        """Load a plugin from a Python file."""
+        try:
+            spec = importlib.util.spec_from_file_location("plugin_module", file_path)
+            if spec and spec.loader:
+                module = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(module)
+                
+                # Look for plugin classes
+                for attr_name in dir(module):
+                    attr = getattr(module, attr_name)
+                    if (isinstance(attr, type) and 
+                        issubclass(attr, BasePlugin) and 
+                        attr != BasePlugin):
+                        
+                        plugin_instance = attr()
+                        self.register_plugin(plugin_instance)
+                        return
+                
+                logger.warning(f"No plugin class found in file {file_path}")
+        
+        except Exception as e:
+            logger.error(f"Failed to load plugin from file {file_path}: {e}")
+    
+    def discover_plugins(self) -> None:
+        """Discover plugins using entry points."""
+        try:
+            eps = entry_points()
+            # Handle both old and new entry_points API
+            if hasattr(eps, 'select'):
+                # New API (Python 3.10+)
+                plugin_eps = eps.select(group='cinchdb.plugins')
+            else:
+                # Old API
+                plugin_eps = eps.get('cinchdb.plugins', [])
+            
+            for entry_point in plugin_eps:
+                try:
+                    plugin_class = entry_point.load()
+                    if issubclass(plugin_class, BasePlugin):
+                        plugin_instance = plugin_class()
+                        self.register_plugin(plugin_instance)
+                except Exception as e:
+                    logger.error(f"Failed to load plugin {entry_point.name}: {e}")
+        except Exception as e:
+            logger.error(f"Failed to discover plugins: {e}")
+    
+    def _apply_plugin_methods(self, plugin: BasePlugin) -> None:
+        """Apply plugin methods to the CinchDB instance."""
+        if not self._cinchdb_instance:
+            return
+            
+        for method_name, method in plugin.get_methods().items():
+            # Bind method to the instance
+            bound_method = method.__get__(self._cinchdb_instance, type(self._cinchdb_instance))
+            setattr(self._cinchdb_instance, method_name, bound_method)
+    
+    def call_hook(self, hook: PluginHook, *args, **kwargs) -> List[Any]:
+        """Call all plugin hooks for a specific event."""
+        results = []
+        
+        for plugin in self.plugins.values():
+            try:
+                plugin_results = plugin.call_hook(hook, *args, **kwargs)
+                results.extend(plugin_results)
+            except Exception as e:
+                logger.error(f"Plugin {plugin.name} hook {hook} failed: {e}")
+        
+        return results
+    
+    def get_plugin(self, name: str) -> Optional[BasePlugin]:
+        """Get a plugin by name."""
+        return self.plugins.get(name)
+    
+    def list_plugins(self) -> List[Dict[str, Any]]:
+        """List all registered plugins with their metadata."""
+        return [plugin.metadata for plugin in self.plugins.values()]
+    
+    def plugin_exists(self, name: str) -> bool:
+        """Check if a plugin is registered."""
+        return name in self.plugins
+    
+    def cleanup_all(self) -> None:
+        """Cleanup all plugins."""
+        for plugin_name in list(self.plugins.keys()):
+            self.unregister_plugin(plugin_name)