cinchdb 0.1.14__py3-none-any.whl → 0.1.17__py3-none-any.whl

cinchdb/managers/data.py

@@ -9,7 +9,7 @@ from pydantic import BaseModel
 
 from cinchdb.core.connection import DatabaseConnection
 from cinchdb.core.path_utils import get_tenant_db_path
-from cinchdb.core.maintenance import check_maintenance_mode
+from cinchdb.core.maintenance_utils import check_maintenance_mode
 from cinchdb.managers.table import TableManager
 from cinchdb.managers.query import QueryManager
 
@@ -283,8 +283,8 @@ class DataManager:
                 conn.rollback()
                 raise
 
-    def delete_by_id(self, model_class: Type[T], record_id: str) -> bool:
-        """Delete a single record by ID.
+    def delete_model_by_id(self, model_class: Type[T], record_id: str) -> bool:
+        """Delete a single record by ID using model class.
 
         Args:
             model_class: Pydantic model class representing the table
@@ -420,12 +420,13 @@ class DataManager:
         return snake_case
 
     def _build_where_clause(
-        self, filters: Dict[str, Any]
+        self, filters: Dict[str, Any], operator: str = "AND"
     ) -> tuple[str, Dict[str, Any]]:
         """Build WHERE clause and parameters from filters.
 
         Args:
             filters: Dictionary of column filters
+            operator: Logical operator to combine conditions - "AND" (default) or "OR"
 
         Returns:
             Tuple of (where_clause, parameters)
@@ -433,31 +434,34 @@ class DataManager:
         if not filters:
             return "", {}
 
+        if operator not in ("AND", "OR"):
+            raise ValueError(f"Operator must be 'AND' or 'OR', got: {operator}")
+
         conditions = []
         params = {}
 
         for key, value in filters.items():
             # Handle special operators (column__operator format)
             if "__" in key:
-                column, operator = key.split("__", 1)
-                param_key = f"{column}_{operator}"
+                column, op = key.split("__", 1)
+                param_key = f"{column}_{op}"
 
-                if operator == "gte":
+                if op == "gte":
                     conditions.append(f"{column} >= :{param_key}")
                     params[param_key] = value
-                elif operator == "lte":
+                elif op == "lte":
                     conditions.append(f"{column} <= :{param_key}")
                     params[param_key] = value
-                elif operator == "gt":
+                elif op == "gt":
                     conditions.append(f"{column} > :{param_key}")
                     params[param_key] = value
-                elif operator == "lt":
+                elif op == "lt":
                     conditions.append(f"{column} < :{param_key}")
                     params[param_key] = value
-                elif operator == "like":
+                elif op == "like":
                     conditions.append(f"{column} LIKE :{param_key}")
                     params[param_key] = value
-                elif operator == "in":
+                elif op == "in":
                     if not isinstance(value, (list, tuple)):
                         raise ValueError(
                             f"'in' operator requires list or tuple, got {type(value)}"
@@ -467,10 +471,182 @@ class DataManager:
                     for i, v in enumerate(value):
                         params[f"{param_key}_{i}"] = v
                 else:
-                    raise ValueError(f"Unsupported operator: {operator}")
+                    raise ValueError(f"Unsupported operator: {op}")
             else:
                 # Exact match
                 conditions.append(f"{key} = :{key}")
                 params[key] = value
 
-        return " AND ".join(conditions), params
+        return f" {operator} ".join(conditions), params
+
+    def delete_where(self, table: str, operator: str = "AND", **filters) -> int:
+        """Delete records from a table based on filter criteria.
+        
+        Args:
+            table: Table name
+            operator: Logical operator to combine conditions - "AND" (default) or "OR"
+            **filters: Filter criteria (supports operators like __gt, __lt, __in, __like, __not)
+                      Multiple conditions are combined with the specified operator
+            
+        Returns:
+            Number of records deleted
+            
+        Examples:
+            # Delete records where status = 'inactive'
+            count = dm.delete_where('users', status='inactive')
+            
+            # Delete records where status = 'inactive' AND age > 65 (default AND)
+            count = dm.delete_where('users', status='inactive', age__gt=65)
+            
+            # Delete records where status = 'inactive' OR age > 65
+            count = dm.delete_where('users', operator='OR', status='inactive', age__gt=65)
+            
+            # Delete records where age > 65
+            count = dm.delete_where('users', age__gt=65)
+            
+            # Delete records where id in [1, 2, 3]
+            count = dm.delete_where('users', id__in=[1, 2, 3])
+            
+            # Delete records where name like 'test%'
+            count = dm.delete_where('users', name__like='test%')
+        """
+        # Check maintenance mode
+        check_maintenance_mode(self.project_root, self.database, self.branch)
+        
+        if not filters:
+            raise ValueError("delete_where requires at least one filter condition")
+        
+        # Build WHERE clause
+        where_clause, params = self._build_where_clause(filters, operator)
+        
+        sql = f"DELETE FROM {table} WHERE {where_clause}"
+        
+        with DatabaseConnection(self.db_path) as conn:
+            cursor = conn.execute(sql, params)
+            conn.commit()
+            return cursor.rowcount
+
+    def update_where(self, table: str, data: Dict[str, Any], operator: str = "AND", **filters) -> int:
+        """Update records in a table based on filter criteria.
+        
+        Args:
+            table: Table name
+            data: Dictionary of column-value pairs to update
+            operator: Logical operator to combine conditions - "AND" (default) or "OR"
+            **filters: Filter criteria (supports operators like __gt, __lt, __in, __like, __not)
+                      Multiple conditions are combined with the specified operator
+            
+        Returns:
+            Number of records updated
+            
+        Examples:
+            # Update status for all users with age > 65
+            count = dm.update_where('users', {'status': 'senior'}, age__gt=65)
+            
+            # Update status where age > 65 AND status = 'active' (default AND)
+            count = dm.update_where('users', {'status': 'senior'}, age__gt=65, status='active')
+            
+            # Update status where age > 65 OR status = 'pending'
+            count = dm.update_where('users', {'status': 'senior'}, operator='OR', age__gt=65, status='pending')
+            
+            # Update multiple fields where id in specific list
+            count = dm.update_where(
+                'users', 
+                {'status': 'inactive', 'updated_at': datetime.now()},
+                id__in=[1, 2, 3]
+            )
+            
+            # Update where name like pattern
+            count = dm.update_where('users', {'category': 'test'}, name__like='test%')
+        """
+        # Check maintenance mode
+        check_maintenance_mode(self.project_root, self.database, self.branch)
+        
+        if not filters:
+            raise ValueError("update_where requires at least one filter condition")
+            
+        if not data:
+            raise ValueError("update_where requires data to update")
+        
+        # Build WHERE clause
+        where_clause, where_params = self._build_where_clause(filters, operator)
+        
+        # Build SET clause
+        set_clauses = []
+        update_params = {}
+        
+        for key, value in data.items():
+            param_key = f"update_{key}"
+            set_clauses.append(f"{key} = :{param_key}")
+            update_params[param_key] = value
+        
+        # Combine parameters (update params first to avoid conflicts)
+        all_params = {**update_params, **where_params}
+        
+        sql = f"UPDATE {table} SET {', '.join(set_clauses)} WHERE {where_clause}"
+        
+        with DatabaseConnection(self.db_path) as conn:
+            cursor = conn.execute(sql, all_params)
+            conn.commit()
+            return cursor.rowcount
+
+    def update_by_id(self, table: str, record_id: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Update a single record by ID.
+        
+        Args:
+            table: Table name
+            record_id: Record ID to update
+            data: Dictionary of column-value pairs to update
+            
+        Returns:
+            Updated record
+        """
+        # Build SET clause
+        set_parts = []
+        params = []
+        
+        for key, value in data.items():
+            set_parts.append(f"{key} = ?")
+            params.append(value)
+        
+        if not set_parts:
+            raise ValueError("No data provided for update")
+        
+        set_clause = ", ".join(set_parts)
+        sql = f"UPDATE {table} SET {set_clause} WHERE id = ?"
+        params.append(record_id)
+        
+        with DatabaseConnection(self.db_path) as conn:
+            cursor = conn.execute(sql, params)
+            conn.commit()
+            
+            if cursor.rowcount == 0:
+                raise ValueError(f"No record found with id: {record_id}")
+            
+            # Return the updated record
+            result = conn.execute(f"SELECT * FROM {table} WHERE id = ?", [record_id])
+            row = result.fetchone()
+            if row:
+                return dict(row)
+            else:
+                raise ValueError(f"Record not found after update: {record_id}")
+    
+    def delete_by_id(self, table: str, record_id: str) -> bool:
+        """Delete a single record by ID using table name.
+        
+        This method is used by the high-level database API.
+        
+        Args:
+            table: Table name
+            record_id: Record ID to delete
+            
+        Returns:
+            True if record was deleted, False if not found
+        """
+        sql = f"DELETE FROM {table} WHERE id = ?"
+        
+        with DatabaseConnection(self.db_path) as conn:
+            cursor = conn.execute(sql, [record_id])
+            conn.commit()
+            return cursor.rowcount > 0
+

cinchdb/managers/index.py

@@ -3,7 +3,6 @@
 from pathlib import Path
 from typing import List, Dict, Any, Optional
 import sqlite3
-import json
 from datetime import datetime, timezone
 import uuid
 
@@ -263,7 +262,7 @@ class IndexManager:
             
             # Get index statistics
             xinfo_result = conn.execute(f"PRAGMA index_xinfo({index_name})")
-            extended_info = xinfo_result.fetchall()
+            xinfo_result.fetchall()
             
             return {
                 "name": index_name,

cinchdb/managers/query.py

@@ -6,7 +6,6 @@ from typing import List, Dict, Any, Optional, Type, TypeVar, Union
 from pydantic import BaseModel, ValidationError
 
 from cinchdb.core.connection import DatabaseConnection
-from cinchdb.core.path_utils import get_tenant_db_path
 from cinchdb.utils import validate_query_safe
 from cinchdb.managers.tenant import TenantManager
 

cinchdb/managers/table.py

@@ -9,7 +9,7 @@ if TYPE_CHECKING:
     from cinchdb.models import Index
 from cinchdb.core.connection import DatabaseConnection
 from cinchdb.core.path_utils import get_tenant_db_path
-from cinchdb.core.maintenance import check_maintenance_mode
+from cinchdb.core.maintenance_utils import check_maintenance_mode
 from cinchdb.managers.change_tracker import ChangeTracker
 from cinchdb.managers.tenant import TenantManager
 
@@ -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,11 +12,10 @@ 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
-from cinchdb.core.maintenance import check_maintenance_mode
+from cinchdb.core.maintenance_utils import check_maintenance_mode
 from cinchdb.utils.name_validator import validate_name
 from cinchdb.infrastructure.metadata_db import MetadataDB
 from cinchdb.infrastructure.metadata_connection_pool import get_metadata_db
@@ -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/managers/view.py

@@ -6,7 +6,7 @@ from typing import List
 from cinchdb.models import View, Change, ChangeType
 from cinchdb.core.connection import DatabaseConnection
 from cinchdb.core.path_utils import get_tenant_db_path
-from cinchdb.core.maintenance import check_maintenance_mode
+from cinchdb.core.maintenance_utils import check_maintenance_mode
 from cinchdb.managers.change_tracker import ChangeTracker
 
 

cinchdb/plugins/__init__.py

@@ -0,0 +1,16 @@
+"""
+Simple Plugin System for CinchDB
+
+Easy-to-use plugin architecture for CinchDB.
+"""
+
+from .base import Plugin
+from .manager import PluginManager
+from .decorators import database_method, auto_extend
+
+__all__ = [
+    "Plugin",
+    "PluginManager",
+    "database_method", 
+    "auto_extend",
+]