cinchdb 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

cinchdb/config.py

@@ -9,7 +9,7 @@ from pydantic import BaseModel, Field, ConfigDict
 
 class RemoteConfig(BaseModel):
     """Configuration for a remote CinchDB instance."""
-    
+
     url: str = Field(description="Base URL of the remote CinchDB API")
     key: str = Field(description="API key for authentication")
 
@@ -50,7 +50,7 @@ class Config:
             env_dir = os.environ.get("CINCHDB_PROJECT_DIR")
             if env_dir:
                 project_dir = Path(env_dir)
-        
+
         self.project_dir = Path(project_dir) if project_dir else Path.cwd()
         self.config_dir = self.project_dir / ".cinchdb"
         self.config_path = self.config_dir / "config.toml"
@@ -86,24 +86,24 @@ class Config:
         # Override database and branch
         if env_db := os.environ.get("CINCHDB_DATABASE"):
             data["active_database"] = env_db
-        
+
         if env_branch := os.environ.get("CINCHDB_BRANCH"):
             data["active_branch"] = env_branch
-        
+
         # Override or create remote configuration
         env_url = os.environ.get("CINCHDB_REMOTE_URL")
         env_key = os.environ.get("CINCHDB_API_KEY")
-        
+
         if env_url and env_key:
             # Create or update "env" remote
             if "remotes" not in data:
                 data["remotes"] = {}
-            
+
             data["remotes"]["env"] = {
                 "url": env_url.rstrip("/"),  # Remove trailing slash
-                "key": env_key
+                "key": env_key,
             }
-            
+
             # Make it active if no other remote is set
             if not data.get("active_remote"):
                 data["active_remote"] = "env"
@@ -130,48 +130,21 @@ class Config:
             for alias, remote in config_dict["remotes"].items():
                 if isinstance(remote, dict):
                     config_dict["remotes"][alias] = remote
-        
+
         with open(self.config_path, "w") as f:
             toml.dump(config_dict, f)
 
     def init_project(self) -> ProjectConfig:
-        """Initialize a new CinchDB project with default configuration."""
-        if self.exists:
-            raise FileExistsError(f"Project already exists at {self.config_dir}")
+        """Initialize a new CinchDB project with default configuration.
 
-        # Create default config
-        config = ProjectConfig()
-        self.save(config)
+        This method now delegates to the ProjectInitializer for the actual
+        initialization logic.
+        """
+        from cinchdb.core.initializer import ProjectInitializer
 
-        # Create default database structure
-        self._create_default_structure()
+        initializer = ProjectInitializer(self.project_dir)
+        config = initializer.init_project()
 
+        # Load the config into this instance
+        self._config = config
         return config
-
-    def _create_default_structure(self) -> None:
-        """Create default project structure."""
-        # Create main database with main branch
-        db_path = self.config_dir / "databases" / "main" / "branches" / "main"
-        db_path.mkdir(parents=True, exist_ok=True)
-
-        # Create metadata files
-        from datetime import datetime, timezone
-
-        metadata = {"created_at": datetime.now(timezone.utc).isoformat()}
-
-        import json
-
-        with open(db_path / "metadata.json", "w") as f:
-            json.dump(metadata, f, indent=2)
-
-        # Create empty changes file
-        with open(db_path / "changes.json", "w") as f:
-            json.dump([], f, indent=2)
-
-        # Create main tenant directory and database
-        tenant_dir = db_path / "tenants"
-        tenant_dir.mkdir(exist_ok=True)
-
-        # Create main tenant database file
-        main_db = tenant_dir / "main.db"
-        main_db.touch()

cinchdb/core/__init__.py

@@ -1,5 +1,6 @@
 """Core CinchDB functionality."""
 
 from cinchdb.core.database import CinchDB, connect, connect_api
+from cinchdb.core.initializer import init_project, init_database
 
-__all__ = ["CinchDB", "connect", "connect_api"]
+__all__ = ["CinchDB", "connect", "connect_api", "init_project", "init_database"]

cinchdb/core/database.py

@@ -3,10 +3,9 @@
 from pathlib import Path
 from typing import List, Dict, Any, Optional, TYPE_CHECKING
 
-from cinchdb.config import Config
 from cinchdb.models import Column, Change
 from cinchdb.core.path_utils import get_project_root
-from cinchdb.utils import validate_query_safe, SQLValidationError
+from cinchdb.utils import validate_query_safe
 
 if TYPE_CHECKING:
     from cinchdb.managers.table import TableManager
@@ -307,7 +306,10 @@ class CinchDB:
     # Convenience methods for common operations
 
     def query(
-        self, sql: str, params: Optional[List[Any]] = None, skip_validation: bool = False
+        self,
+        sql: str,
+        params: Optional[List[Any]] = None,
+        skip_validation: bool = False,
     ) -> List[Dict[str, Any]]:
         """Execute a SQL query.
 
@@ -318,14 +320,14 @@ class CinchDB:
 
         Returns:
             List of result rows as dictionaries
-            
+
         Raises:
             SQLValidationError: If the query contains restricted operations
         """
         # Validate query unless explicitly skipped
         if not skip_validation:
             validate_query_safe(sql)
-            
+
         if self.is_local:
             if self._query_manager is None:
                 from cinchdb.managers.query import QueryManager
@@ -369,10 +371,24 @@ class CinchDB:
             data: Record data as dictionary
 
         Returns:
-            Inserted record with generated fields
+            Inserted record with generated fields (id, created_at, updated_at)
+
+        Examples:
+            # Simple insert
+            db.insert("users", {"name": "John", "email": "john@example.com"})
+            
+            # Insert with custom ID
+            db.insert("products", {"id": "prod-123", "name": "Widget", "price": 9.99})
         """
         if self.is_local:
-            return self.data.create(table, data)
+            # Initialize data manager if needed
+            if self._data_manager is None:
+                from cinchdb.managers.data import DataManager
+                self._data_manager = DataManager(
+                    self.project_dir, self.database, self.branch, self.tenant
+                )
+            # Use the new create_from_dict method
+            return self._data_manager.create_from_dict(table, data)
         else:
             # Remote insert - use new data CRUD endpoint
             result = self._make_request(
@@ -427,6 +443,7 @@ class CinchDB:
         """
         if self.is_local:
             from cinchdb.managers.change_tracker import ChangeTracker
+
             tracker = ChangeTracker(self.project_dir, self.database, self.branch)
             return tracker.get_changes()
         else:
@@ -435,6 +452,7 @@ class CinchDB:
             # Convert API response to Change objects
             from cinchdb.models import Change
             from datetime import datetime
+
             changes = []
             for data in result.get("changes", []):
                 # Convert string dates back to datetime if present

cinchdb/core/initializer.py

@@ -0,0 +1,214 @@
+"""Project initialization for CinchDB."""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from cinchdb.core.connection import DatabaseConnection
+from cinchdb.config import ProjectConfig
+
+
+class ProjectInitializer:
+    """Handles initialization of CinchDB projects."""
+
+    def __init__(self, project_dir: Optional[Path] = None):
+        """Initialize the project initializer.
+
+        Args:
+            project_dir: Path to project directory. If None, uses current directory.
+        """
+        self.project_dir = Path(project_dir) if project_dir else Path.cwd()
+        self.config_dir = self.project_dir / ".cinchdb"
+        self.config_path = self.config_dir / "config.toml"
+
+    def init_project(
+        self, database_name: str = "main", branch_name: str = "main"
+    ) -> ProjectConfig:
+        """Initialize a new CinchDB project with default configuration.
+
+        Args:
+            database_name: Name for the initial database (default: "main")
+            branch_name: Name for the initial branch (default: "main")
+
+        Returns:
+            The created ProjectConfig
+
+        Raises:
+            FileExistsError: If project already exists at the location
+        """
+        if self.config_path.exists():
+            raise FileExistsError(f"Project already exists at {self.config_dir}")
+
+        # Create config directory
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+
+        # Create default config
+        config = ProjectConfig(active_database=database_name, active_branch=branch_name)
+
+        # Save config
+        self._save_config(config)
+
+        # Create default database structure
+        self._create_database_structure(database_name, branch_name)
+
+        return config
+
+    def init_database(
+        self,
+        database_name: str,
+        branch_name: str = "main",
+        description: Optional[str] = None,
+    ) -> None:
+        """Initialize a new database within an existing project.
+
+        Args:
+            database_name: Name for the database
+            branch_name: Initial branch name (default: "main")
+            description: Optional description for the database
+
+        Raises:
+            FileNotFoundError: If project doesn't exist
+            FileExistsError: If database already exists
+        """
+        if not self.config_path.exists():
+            raise FileNotFoundError(f"No CinchDB project found at {self.config_dir}")
+
+        db_path = self.config_dir / "databases" / database_name
+        if db_path.exists():
+            raise FileExistsError(f"Database '{database_name}' already exists")
+
+        # Create database structure
+        self._create_database_structure(database_name, branch_name, description)
+
+    def _create_database_structure(
+        self,
+        database_name: str,
+        branch_name: str = "main",
+        description: Optional[str] = None,
+    ) -> None:
+        """Create the directory structure for a database.
+
+        Args:
+            database_name: Name of the database
+            branch_name: Name of the initial branch
+            description: Optional description
+        """
+        # Create database branch path
+        branch_path = (
+            self.config_dir / "databases" / database_name / "branches" / branch_name
+        )
+        branch_path.mkdir(parents=True, exist_ok=True)
+
+        # Create metadata file
+        metadata = {
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "name": branch_name,
+            "parent": None,
+            "description": description,
+        }
+
+        with open(branch_path / "metadata.json", "w") as f:
+            json.dump(metadata, f, indent=2)
+
+        # Create empty changes file
+        with open(branch_path / "changes.json", "w") as f:
+            json.dump([], f, indent=2)
+
+        # Create tenants directory
+        tenant_dir = branch_path / "tenants"
+        tenant_dir.mkdir(exist_ok=True)
+
+        # Create and initialize main tenant database
+        self._init_tenant_database(tenant_dir / "main.db")
+
+    def _init_tenant_database(self, db_path: Path) -> None:
+        """Initialize a tenant database with proper PRAGMAs.
+
+        Args:
+            db_path: Path to the database file
+        """
+        # Create the database file
+        db_path.touch()
+
+        # Initialize with proper PRAGMAs
+        with DatabaseConnection(db_path):
+            # The connection automatically sets up PRAGMAs in _connect():
+            # - journal_mode = WAL
+            # - synchronous = NORMAL
+            # - wal_autocheckpoint = 0
+            # - foreign_keys = ON
+            pass
+
+    def _save_config(self, config: ProjectConfig) -> None:
+        """Save configuration to disk.
+
+        Args:
+            config: Configuration to save
+        """
+        import toml
+
+        # Ensure config directory exists
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+
+        # Convert to dict for TOML serialization
+        config_dict = config.model_dump()
+
+        # Convert RemoteConfig objects to dicts if present
+        if "remotes" in config_dict:
+            for alias, remote in config_dict["remotes"].items():
+                if isinstance(remote, dict):
+                    config_dict["remotes"][alias] = remote
+
+        with open(self.config_path, "w") as f:
+            toml.dump(config_dict, f)
+
+
+def init_project(
+    project_dir: Optional[Path] = None,
+    database_name: str = "main",
+    branch_name: str = "main",
+) -> ProjectConfig:
+    """Initialize a new CinchDB project.
+
+    This is a convenience function that creates a ProjectInitializer
+    and initializes a project.
+
+    Args:
+        project_dir: Directory to initialize in (default: current directory)
+        database_name: Name for initial database (default: "main")
+        branch_name: Name for initial branch (default: "main")
+
+    Returns:
+        The created ProjectConfig
+
+    Raises:
+        FileExistsError: If project already exists
+    """
+    initializer = ProjectInitializer(project_dir)
+    return initializer.init_project(database_name, branch_name)
+
+
+def init_database(
+    project_dir: Optional[Path] = None,
+    database_name: str = "main",
+    branch_name: str = "main",
+    description: Optional[str] = None,
+) -> None:
+    """Initialize a new database within an existing project.
+
+    This is a convenience function that creates a ProjectInitializer
+    and initializes a database.
+
+    Args:
+        project_dir: Project directory (default: current directory)
+        database_name: Name for the database
+        branch_name: Initial branch name (default: "main")
+        description: Optional description
+
+    Raises:
+        FileNotFoundError: If project doesn't exist
+        FileExistsError: If database already exists
+    """
+    initializer = ProjectInitializer(project_dir)
+    initializer.init_database(database_name, branch_name, description)

cinchdb/managers/branch.py

@@ -6,7 +6,6 @@ from pathlib import Path
 from typing import List, Dict, Any
 from datetime import datetime, timezone
 
-from cinchdb.config import Config
 from cinchdb.models import Branch
 from cinchdb.core.path_utils import (
     get_database_path,
@@ -68,7 +67,7 @@ class BranchManager:
         """
         # Validate new branch name
         validate_name(new_branch_name, "branch")
-        
+
         # Validate source branch exists
         if source_branch not in list_branches(self.project_root, self.database):
             raise ValueError(f"Source branch '{source_branch}' does not exist")
@@ -122,7 +121,6 @@ class BranchManager:
         branch_path = get_branch_path(self.project_root, self.database, branch_name)
         shutil.rmtree(branch_path)
 
-
     def get_branch_metadata(self, branch_name: str) -> Dict[str, Any]:
         """Get metadata for a branch.
 

cinchdb/managers/column.py

@@ -439,16 +439,20 @@ class ColumnManager:
             conn.commit()
 
     def alter_column_nullable(
-        self, table_name: str, column_name: str, nullable: bool, fill_value: Optional[Any] = None
+        self,
+        table_name: str,
+        column_name: str,
+        nullable: bool,
+        fill_value: Optional[Any] = None,
     ) -> None:
         """Change the nullable constraint on a column.
-        
+
         Args:
             table_name: Name of the table
             column_name: Name of the column to modify
             nullable: Whether the column should allow NULL values
             fill_value: Value to use for existing NULL values when making column NOT NULL
-        
+
         Raises:
             ValueError: If table/column doesn't exist or column is protected
             ValueError: If making NOT NULL and column has NULL values without fill_value
@@ -469,13 +473,13 @@ class ColumnManager:
         existing_columns = self.list_columns(table_name)
         column_found = False
         old_column = None
-        
+
         for col in existing_columns:
             if col.name == column_name:
                 column_found = True
                 old_column = col
                 break
-                
+
         if not column_found:
             raise ValueError(
                 f"Column '{column_name}' does not exist in table '{table_name}'"
@@ -494,7 +498,7 @@ class ColumnManager:
                     f"SELECT COUNT(*) FROM {table_name} WHERE {column_name} IS NULL"
                 )
                 null_count = cursor.fetchone()[0]
-                
+
                 if null_count > 0 and fill_value is None:
                     raise ValueError(
                         f"Column '{column_name}' has {null_count} NULL values. "
@@ -503,7 +507,7 @@ class ColumnManager:
 
         # Build SQL statements for table recreation
         temp_table = f"{table_name}_temp"
-        
+
         # Create new table with modified column
         col_defs = []
         for col in existing_columns:
@@ -527,7 +531,7 @@ class ColumnManager:
         # Column names for copying
         col_names = [col.name for col in existing_columns]
         col_list = ", ".join(col_names)
-        
+
         # Build copy SQL with COALESCE if needed
         if not nullable and fill_value is not None:
             # Build select list with COALESCE for the target column
@@ -545,7 +549,7 @@ class ColumnManager:
             copy_sql = f"INSERT INTO {temp_table} ({col_list}) SELECT {select_list} FROM {table_name}"
         else:
             copy_sql = f"INSERT INTO {temp_table} ({col_list}) SELECT {col_list} FROM {table_name}"
-            
+
         drop_sql = f"DROP TABLE {table_name}"
         rename_sql = f"ALTER TABLE {temp_table} RENAME TO {table_name}"
 

cinchdb/managers/data.py

@@ -93,14 +93,15 @@ class DataManager:
         results = self.select(model_class, limit=1, id=record_id)
         return results[0] if results else None
 
-    def create(self, instance: T) -> T:
-        """Create a new record.
+    def create_from_dict(self, table_name: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Create a new record from a dictionary.
 
         Args:
-            instance: Model instance to create
+            table_name: Name of the table to insert into
+            data: Dictionary containing the record data
 
         Returns:
-            Created model instance with populated ID and timestamps
+            Dictionary with created record including generated ID and timestamps
 
         Raises:
             ValueError: If record with same ID already exists
@@ -109,22 +110,20 @@ class DataManager:
         # Check maintenance mode
         check_maintenance_mode(self.project_root, self.database, self.branch)
 
-        table_name = self._get_table_name(type(instance))
-
-        # Prepare data for insertion
-        data = instance.model_dump()
+        # Make a copy to avoid modifying the original
+        record_data = data.copy()
 
         # Generate ID if not provided
-        if not data.get("id"):
-            data["id"] = str(uuid.uuid4())
+        if not record_data.get("id"):
+            record_data["id"] = str(uuid.uuid4())
 
         # Set timestamps
         now = datetime.now()
-        data["created_at"] = now
-        data["updated_at"] = now
+        record_data["created_at"] = now
+        record_data["updated_at"] = now
 
         # Build INSERT query
-        columns = list(data.keys())
+        columns = list(record_data.keys())
         placeholders = [f":{col}" for col in columns]
         query = f"""
             INSERT INTO {table_name} ({", ".join(columns)}) 
@@ -133,17 +132,39 @@ class DataManager:
 
         with DatabaseConnection(self.db_path) as conn:
             try:
-                conn.execute(query, data)
+                conn.execute(query, record_data)
                 conn.commit()
 
-                # Return updated instance
-                return type(instance)(**data)
+                # Return the created record data
+                return record_data
             except Exception as e:
                 conn.rollback()
                 if "UNIQUE constraint failed" in str(e):
-                    raise ValueError(f"Record with ID {data['id']} already exists")
+                    raise ValueError(f"Record with ID {record_data['id']} already exists")
                 raise
 
+    def create(self, instance: T) -> T:
+        """Create a new record from a model instance.
+
+        Args:
+            instance: Model instance to create
+
+        Returns:
+            Created model instance with populated ID and timestamps
+
+        Raises:
+            ValueError: If record with same ID already exists
+            MaintenanceError: If branch is in maintenance mode
+        """
+        table_name = self._get_table_name(type(instance))
+        data = instance.model_dump()
+        
+        # Use the new create_from_dict method
+        created_data = self.create_from_dict(table_name, data)
+        
+        # Return updated instance
+        return type(instance)(**created_data)
+
     def save(self, instance: T) -> T:
         """Save (upsert) a record - insert if new, update if exists.
 

cinchdb/managers/query.py

@@ -7,7 +7,7 @@ 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, SQLValidationError
+from cinchdb.utils import validate_query_safe
 
 T = TypeVar("T", bound=BaseModel)
 
@@ -33,7 +33,10 @@ class QueryManager:
         self.db_path = get_tenant_db_path(project_root, database, branch, tenant)
 
     def execute(
-        self, sql: str, params: Optional[Union[tuple, dict]] = None, skip_validation: bool = False
+        self,
+        sql: str,
+        params: Optional[Union[tuple, dict]] = None,
+        skip_validation: bool = False,
     ) -> List[Dict[str, Any]]:
         """Execute a SQL query and return results as dictionaries.
 
@@ -52,7 +55,7 @@ class QueryManager:
         # Validate query unless explicitly skipped
         if not skip_validation:
             validate_query_safe(sql)
-            
+
         # Note: The original code had SELECT-only validation, but we're now more permissive
         if not sql.strip().upper().startswith("SELECT"):
             raise ValueError(
@@ -161,7 +164,10 @@ class QueryManager:
         return results[0] if results else None
 
     def execute_non_query(
-        self, sql: str, params: Optional[Union[tuple, dict]] = None, skip_validation: bool = False
+        self,
+        sql: str,
+        params: Optional[Union[tuple, dict]] = None,
+        skip_validation: bool = False,
     ) -> int:
         """Execute a non-SELECT SQL query (INSERT, UPDATE, DELETE, etc.).
 
@@ -172,7 +178,7 @@ class QueryManager:
 
         Returns:
             Number of rows affected
-            
+
         Raises:
             SQLValidationError: If query contains restricted operations
             Exception: If query execution fails
@@ -180,7 +186,7 @@ class QueryManager:
         # Validate query unless explicitly skipped
         if not skip_validation:
             validate_query_safe(sql)
-            
+
         with DatabaseConnection(self.db_path) as conn:
             cursor = conn.execute(sql, params)
             affected_rows = cursor.rowcount