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

cinchdb/core/database.py

@@ -1,11 +1,13 @@
 """Unified database connection interface for CinchDB."""
 
+import os
 from pathlib import Path
 from typing import List, Dict, Any, Optional, TYPE_CHECKING
 
 from cinchdb.models import Column, Change
 from cinchdb.core.path_utils import get_project_root
 from cinchdb.utils import validate_query_safe
+from cinchdb.infrastructure.metadata_connection_pool import get_metadata_db
 
 if TYPE_CHECKING:
     from cinchdb.managers.table import TableManager
@@ -78,7 +80,7 @@ class CinchDB:
         self.database = database
         self.branch = branch
         self.tenant = tenant
-
+        
         # Determine connection type
         if project_dir is not None:
             # Local connection
@@ -120,16 +122,26 @@ class CinchDB:
             return
             
         # Check if this is a lazy database using metadata DB
-        from cinchdb.infrastructure.metadata_db import MetadataDB
-        
-        with MetadataDB(self.project_dir) as metadata_db:
-            db_info = metadata_db.get_database(self.database)
+        metadata_db = get_metadata_db(self.project_dir)
+        db_info = metadata_db.get_database(self.database)
         
         if db_info and not db_info['materialized']:
             # Database exists in metadata but not materialized
             from cinchdb.core.initializer import ProjectInitializer
             initializer = ProjectInitializer(self.project_dir)
             initializer.materialize_database(self.database)
+    
+    def get_connection(self, db_path) -> "DatabaseConnection":
+        """Get a database connection.
+        
+        Args:
+            db_path: Path to database file
+            
+        Returns:
+            DatabaseConnection instance
+        """
+        from cinchdb.core.connection import DatabaseConnection
+        return DatabaseConnection(db_path)
 
     @property
     def session(self):
@@ -464,38 +476,189 @@ class CinchDB:
                 )
                 return result
 
-    def update(self, table: str, id: str, data: Dict[str, Any]) -> Dict[str, Any]:
-        """Update a record in a table.
+    def update(self, table: str, *updates: Dict[str, Any]) -> Dict[str, Any] | List[Dict[str, Any]]:
+        """Update one or more records in a table.
 
         Args:
             table: Table name
-            id: Record ID
-            data: Updated data as dictionary
+            *updates: One or more update dictionaries, each must contain 'id' field
 
         Returns:
-            Updated record
+            Single record dict if one record updated, list of dicts if multiple
+
+        Examples:
+            # Single update
+            db.update("users", {"id": "123", "name": "John Updated", "status": "active"})
+            
+            # Multiple updates using star expansion
+            db.update("users", 
+                {"id": "123", "name": "John Updated", "status": "active"},
+                {"id": "456", "name": "Jane Updated", "email": "jane.new@example.com"},
+                {"id": "789", "status": "inactive"}
+            )
+            
+            # Or with a list using star expansion
+            user_updates = [
+                {"id": "abc", "name": "Alice Updated"},
+                {"id": "def", "status": "premium"}
+            ]
+            db.update("users", *user_updates)
         """
+        if not updates:
+            raise ValueError("At least one update record must be provided")
+            
+        # Validate that all updates have an 'id' field
+        for i, update_data in enumerate(updates):
+            if 'id' not in update_data:
+                raise ValueError(f"Update record {i} missing required 'id' field")
+            
         if self.is_local:
-            return self.data.update(table, id, data)
+            # Single record
+            if len(updates) == 1:
+                update_data = updates[0].copy()
+                record_id = update_data.pop('id')
+                return self.data.update_by_id(table, record_id, update_data)
+            
+            # Multiple records - batch update
+            results = []
+            for update_data in updates:
+                update_copy = update_data.copy()
+                record_id = update_copy.pop('id')
+                result = self.data.update_by_id(table, record_id, update_copy)
+                results.append(result)
+            return results
         else:
-            # Remote update - use new data CRUD endpoint
-            result = self._make_request(
-                "PUT", f"/tables/{table}/data/{id}", json={"data": data}
-            )
-            return result
+            # Remote update
+            if len(updates) == 1:
+                # Single record - use existing endpoint
+                update_data = updates[0].copy()
+                record_id = update_data.pop('id')
+                result = self._make_request(
+                    "PUT", f"/tables/{table}/data/{record_id}", json={"data": update_data}
+                )
+                return result
+            else:
+                # Multiple records - use bulk endpoint
+                result = self._make_request(
+                    "PUT", f"/tables/{table}/data/bulk", json={"updates": list(updates)}
+                )
+                return result
 
-    def delete(self, table: str, id: str) -> None:
-        """Delete a record from a table.
+    def delete(self, table: str, *ids: str) -> int:
+        """Delete one or more records from a table.
 
         Args:
             table: Table name
-            id: Record ID
+            *ids: One or more record IDs
+
+        Returns:
+            Number of records deleted
+
+        Examples:
+            # Single delete
+            db.delete("users", "123")
+            
+            # Multiple deletes
+            db.delete("users", "123", "456", "789")
+            
+            # Or with a list using star expansion
+            user_ids = ["abc", "def", "ghi"]
+            db.delete("users", *user_ids)
         """
+        if not ids:
+            raise ValueError("At least one ID must be provided")
+            
         if self.is_local:
-            self.data.delete(table, id)
+            # Single record
+            if len(ids) == 1:
+                success = self.data.delete_by_id(table, ids[0])
+                return 1 if success else 0
+            
+            # Multiple records - batch delete
+            deleted_count = 0
+            for record_id in ids:
+                success = self.data.delete_by_id(table, record_id)
+                if success:
+                    deleted_count += 1
+            return deleted_count
         else:
             # Remote delete
-            self._make_request("DELETE", f"/tables/{table}/data/{id}")
+            if len(ids) == 1:
+                # Single record - use existing endpoint
+                self._make_request("DELETE", f"/tables/{table}/data/{ids[0]}")
+                return 1
+            else:
+                # Multiple records - use bulk endpoint
+                result = self._make_request(
+                    "DELETE", f"/tables/{table}/data/bulk", json={"ids": list(ids)}
+                )
+                return result.get("deleted_count", len(ids))
+
+    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' (single condition)
+            count = db.delete_where('users', status='inactive')
+            
+            # Delete records where status = 'inactive' AND age > 65 (default AND)
+            count = db.delete_where('users', status='inactive', age__gt=65)
+            
+            # Delete records where status = 'inactive' OR age > 65
+            count = db.delete_where('users', operator='OR', status='inactive', age__gt=65)
+            
+            # Delete records where item_id in [1, 2, 3]
+            count = db.delete_where('items', item_id__in=[1, 2, 3])
+        """
+        if self.is_local:
+            return self.data.delete_where(table, operator=operator, **filters)
+        else:
+            raise NotImplementedError("Remote bulk delete not implemented")
+
+    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 (single condition)
+            count = db.update_where('users', {'status': 'senior'}, age__gt=65)
+            
+            # Update status where age > 65 AND status = 'active' (default AND)
+            count = db.update_where('users', {'status': 'senior'}, age__gt=65, status='active')
+            
+            # Update status where age > 65 OR status = 'pending' 
+            count = db.update_where('users', {'status': 'senior'}, operator='OR', age__gt=65, status='pending')
+            
+            # Update multiple fields where item_id in specific list
+            count = db.update_where(
+                'items', 
+                {'status': 'inactive', 'updated_at': datetime.now()},
+                item_id__in=[1, 2, 3]
+            )
+        """
+        if self.is_local:
+            return self.data.update_where(table, data, operator=operator, **filters)
+        else:
+            raise NotImplementedError("Remote bulk update not implemented")
+
 
     def create_index(
         self,
@@ -581,31 +744,6 @@ class CinchDB:
                 changes.append(Change(**data))
             return changes
 
-    def optimize_tenant(self, tenant_name: str = None, force: bool = False) -> bool:
-        """Optimize a tenant's storage with VACUUM and page size adjustment.
-
-        Args:
-            tenant_name: Name of the tenant to optimize (default: current tenant)
-            force: If True, always perform optimization
-
-        Returns:
-            True if optimization was performed, False otherwise
-            
-        Examples:
-            # Optimize current tenant
-            db.optimize_tenant()
-            
-            # Optimize specific tenant
-            db.optimize_tenant("store_west")
-            
-            # Force optimization even if not needed
-            db.optimize_tenant(force=True)
-        """
-        if self.is_local:
-            tenant_to_optimize = tenant_name or self.tenant
-            return self.tenants.optimize_tenant_storage(tenant_to_optimize, force=force)
-        else:
-            raise NotImplementedError("Remote tenant optimization not implemented")
 
     def get_tenant_size(self, tenant_name: str = None) -> dict:
         """Get storage size information for a tenant.
@@ -639,6 +777,46 @@ class CinchDB:
         else:
             raise NotImplementedError("Remote tenant size query not implemented")
     
+    def vacuum_tenant(self, tenant_name: str = None) -> dict:
+        """Run VACUUM operation on a specific tenant to optimize storage and performance.
+        
+        VACUUM reclaims space from deleted records, defragments the database file,
+        and can improve query performance by rebuilding internal structures.
+        
+        Args:
+            tenant_name: Name of tenant to vacuum (default: current tenant)
+            
+        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
+            - space_reclaimed_mb: MB reclaimed (rounded to 2 decimals)
+            - duration_seconds: Time taken for vacuum operation
+            - error: Error message if vacuum failed
+            
+        Raises:
+            ValueError: If tenant doesn't exist or is not materialized
+            NotImplementedError: If called on remote database
+            
+        Examples:
+            # Vacuum current tenant
+            result = db.vacuum_tenant()
+            if result['success']:
+                print(f"Reclaimed {result['space_reclaimed_mb']:.2f} MB")
+            
+            # Vacuum specific tenant
+            result = db.vacuum_tenant("store_east")
+            print(f"Vacuum took {result['duration_seconds']} seconds")
+        """
+        if self.is_local:
+            tenant_to_vacuum = tenant_name or self.tenant
+            return self.tenants.vacuum_tenant(tenant_to_vacuum)
+        else:
+            raise NotImplementedError("Remote tenant vacuum not implemented")
+    
     def get_storage_info(self) -> dict:
         """Get storage size information for all tenants in current branch.
         
@@ -667,35 +845,6 @@ class CinchDB:
         else:
             raise NotImplementedError("Remote storage info not implemented")
     
-    def optimize_all_tenants(self, force: bool = False) -> dict:
-        """Optimize storage for all tenants in current branch.
-
-        This is designed to be called periodically 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)
-            
-        Examples:
-            # Run periodic optimization
-            results = db.optimize_all_tenants()
-            print(f"Optimized {len(results['optimized'])} tenants")
-            
-            # Force optimization of all tenants
-            results = db.optimize_all_tenants(force=True)
-        """
-        if self.is_local:
-            return self.tenants.optimize_all_tenants(force=force)
-        else:
-            raise NotImplementedError("Remote tenant optimization not implemented")
 
     def close(self):
         """Close any open connections."""

cinchdb/core/maintenance_utils.py

@@ -0,0 +1,43 @@
+"""Maintenance utilities for CinchDB operations."""
+
+from pathlib import Path
+from cinchdb.infrastructure.metadata_connection_pool import get_metadata_db
+
+
+class MaintenanceError(Exception):
+    """Exception raised when operation blocked by maintenance mode."""
+    pass
+
+
+def check_maintenance_mode(project_root: Path, database: str, branch: str = None) -> None:
+    """Check if database or branch is in maintenance mode and raise error if so.
+    
+    Args:
+        project_root: Path to project root
+        database: Database name  
+        branch: Branch name (optional)
+        
+    Raises:
+        MaintenanceError: If database or branch is in maintenance mode
+    """
+    try:
+        metadata_db = get_metadata_db(project_root)
+        
+        # Check database-level maintenance
+        if metadata_db.is_database_in_maintenance(database):
+            info = metadata_db.get_maintenance_info(database)
+            reason = info.get("reason", "Database maintenance in progress") if info else "Database maintenance in progress"
+            raise MaintenanceError(f"Database '{database}' is in maintenance mode: {reason}")
+        
+        # Check branch-level maintenance if branch specified
+        if branch and metadata_db.is_branch_in_maintenance(database, branch):
+            info = metadata_db.get_maintenance_info(database, branch)
+            reason = info.get("reason", "Branch maintenance in progress") if info else "Branch maintenance in progress"
+            raise MaintenanceError(f"Branch '{database}/{branch}' is in maintenance mode: {reason}")
+            
+    except MaintenanceError:
+        raise  # Re-raise maintenance errors
+    except Exception:
+        # If we can't check maintenance status, allow the operation to proceed
+        # This prevents maintenance check failures from blocking normal operations
+        pass

cinchdb/core/path_utils.py

@@ -1,7 +1,8 @@
 """Path utilities for CinchDB."""
 
 from pathlib import Path
-from typing import List, Optional
+from typing import List
+from cinchdb.infrastructure.metadata_connection_pool import get_metadata_db
 
 
 def get_project_root(start_path: Path) -> Path:
@@ -119,10 +120,9 @@ def list_databases(project_root: Path) -> List[str]:
     if not metadata_db_path.exists():
         return []
     
-    from cinchdb.infrastructure.metadata_db import MetadataDB
-    with MetadataDB(project_root) as metadata_db:
-        db_records = metadata_db.list_databases()
-        return sorted(record['name'] for record in db_records)
+    metadata_db = get_metadata_db(project_root)
+    db_records = metadata_db.list_databases()
+    return sorted(record['name'] for record in db_records)
 
 
 def list_branches(project_root: Path, database: str) -> List[str]:
@@ -139,13 +139,12 @@ def list_branches(project_root: Path, database: str) -> List[str]:
     if not metadata_db_path.exists():
         return []
     
-    from cinchdb.infrastructure.metadata_db import MetadataDB
-    with MetadataDB(project_root) as metadata_db:
-        db_info = metadata_db.get_database(database)
-        if not db_info:
-            return []
-        branch_records = metadata_db.list_branches(db_info['id'])
-        return sorted(record['name'] for record in branch_records)
+    metadata_db = get_metadata_db(project_root)
+    db_info = metadata_db.get_database(database)
+    if not db_info:
+        return []
+    branch_records = metadata_db.list_branches(db_info['id'])
+    return sorted(record['name'] for record in branch_records)
 
 
 def list_tenants(project_root: Path, database: str, branch: str) -> List[str]:
@@ -163,13 +162,12 @@ def list_tenants(project_root: Path, database: str, branch: str) -> List[str]:
     if not metadata_db_path.exists():
         return []
     
-    from cinchdb.infrastructure.metadata_db import MetadataDB
-    with MetadataDB(project_root) as metadata_db:
-        db_info = metadata_db.get_database(database)
-        if not db_info:
-            return []
-        branch_info = metadata_db.get_branch(db_info['id'], branch)
-        if not branch_info:
-            return []
-        tenant_records = metadata_db.list_tenants(branch_info['id'])
-        return sorted(record['name'] for record in tenant_records)
+    metadata_db = get_metadata_db(project_root)
+    db_info = metadata_db.get_database(database)
+    if not db_info:
+        return []
+    branch_info = metadata_db.get_branch(db_info['id'], branch)
+    if not branch_info:
+        return []
+    tenant_records = metadata_db.list_tenants(branch_info['id'])
+    return sorted(record['name'] for record in tenant_records)