cinchdb 0.1.15__tar.gz → 0.1.18__tar.gz

{cinchdb-0.1.15 → cinchdb-0.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cinchdb
-Version: 0.1.15
+Version: 0.1.18
 Summary: A Git-like SQLite database management system with branching and multi-tenancy
 Project-URL: Homepage, https://github.com/russellromney/cinchdb
 Project-URL: Documentation, https://russellromney.github.io/cinchdb
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: requests>=2.28.0
 Requires-Dist: rich>=13.0.0
@@ -31,6 +32,10 @@ Description-Content-Type: text/markdown
 
 **Git-like SQLite database management with branching and multi-tenancy**
 
+[![PyPI version](https://badge.fury.io/py/cinchdb.svg)](https://badge.fury.io/py/cinchdb)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+
 NOTE: CinchDB is in early alpha. This is project to test out an idea. Do not use this in production.
 
 CinchDB is for projects that need fast queries, isolated data per-tenant [or even per-user](https://turso.tech/blog/give-each-of-your-users-their-own-sqlite-database-b74445f4), and a branchable database that makes it easy to merge changes between branches.
@@ -64,6 +69,10 @@ cinch branch merge-into-main feature
 cinch tenant create customer_a
 cinch query "SELECT * FROM users" --tenant customer_a
 
+# Tenant encryption (bring your own keys)
+cinch tenant create secure_customer --encrypt --key="your-secret-key"
+cinch query "SELECT * FROM users" --tenant secure_customer --key="your-secret-key"
+
 # Future: Remote connectivity planned for production deployment
 
 # Autogenerate Python SDK from database
@@ -153,6 +162,35 @@ db.update("posts", post_id, {"content": "Updated content"})
 
 ## Architecture
 
+### Storage Architecture
+
+CinchDB uses a **tenant-first storage model** where database and branch are organizational metadata concepts, while tenants represent the actual isolated data stores:
+
+```
+.cinchdb/
+├── metadata.db                    # Organizational metadata
+└── {database}-{branch}/           # Context root (e.g., main-main, prod-feature)
+    ├── {shard}/                   # SHA256-based sharding (first 2 chars)
+    │   ├── {tenant}.db            # Actual SQLite database
+    │   └── {tenant}.db-wal        # WAL file
+    └── ...
+```
+
+**Key Design Decisions:**
+- **Tenant-first**: Each tenant gets its own SQLite database file
+- **Flat hierarchy**: Database/branch form a single context root, avoiding deep nesting
+- **Hash sharding**: Tenants are distributed across 256 shards using SHA256 for scalability
+- **Lazy initialization**: Tenant databases are created on first access, not on tenant creation
+- **WAL mode**: All databases use Write-Ahead Logging for better concurrency
+
+This architecture enables:
+- True multi-tenant isolation at the file system level
+- Efficient branching without duplicating tenant data
+- Simple backup/restore per tenant
+- Horizontal scaling through sharding
+
+### Components
+
 - **Python SDK**: Core functionality for local development
 - **CLI**: Full-featured command-line interface
 

{cinchdb-0.1.15 → cinchdb-0.1.18}/README.md

@@ -2,6 +2,10 @@
 
 **Git-like SQLite database management with branching and multi-tenancy**
 
+[![PyPI version](https://badge.fury.io/py/cinchdb.svg)](https://badge.fury.io/py/cinchdb)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+
 NOTE: CinchDB is in early alpha. This is project to test out an idea. Do not use this in production.
 
 CinchDB is for projects that need fast queries, isolated data per-tenant [or even per-user](https://turso.tech/blog/give-each-of-your-users-their-own-sqlite-database-b74445f4), and a branchable database that makes it easy to merge changes between branches.
@@ -35,6 +39,10 @@ cinch branch merge-into-main feature
 cinch tenant create customer_a
 cinch query "SELECT * FROM users" --tenant customer_a
 
+# Tenant encryption (bring your own keys)
+cinch tenant create secure_customer --encrypt --key="your-secret-key"
+cinch query "SELECT * FROM users" --tenant secure_customer --key="your-secret-key"
+
 # Future: Remote connectivity planned for production deployment
 
 # Autogenerate Python SDK from database
@@ -124,6 +132,35 @@ db.update("posts", post_id, {"content": "Updated content"})
 
 ## Architecture
 
+### Storage Architecture
+
+CinchDB uses a **tenant-first storage model** where database and branch are organizational metadata concepts, while tenants represent the actual isolated data stores:
+
+```
+.cinchdb/
+├── metadata.db                    # Organizational metadata
+└── {database}-{branch}/           # Context root (e.g., main-main, prod-feature)
+    ├── {shard}/                   # SHA256-based sharding (first 2 chars)
+    │   ├── {tenant}.db            # Actual SQLite database
+    │   └── {tenant}.db-wal        # WAL file
+    └── ...
+```
+
+**Key Design Decisions:**
+- **Tenant-first**: Each tenant gets its own SQLite database file
+- **Flat hierarchy**: Database/branch form a single context root, avoiding deep nesting
+- **Hash sharding**: Tenants are distributed across 256 shards using SHA256 for scalability
+- **Lazy initialization**: Tenant databases are created on first access, not on tenant creation
+- **WAL mode**: All databases use Write-Ahead Logging for better concurrency
+
+This architecture enables:
+- True multi-tenant isolation at the file system level
+- Efficient branching without duplicating tenant data
+- Simple backup/restore per tenant
+- Horizontal scaling through sharding
+
+### Components
+
 - **Python SDK**: Core functionality for local development
 - **CLI**: Full-featured command-line interface
 

{cinchdb-0.1.15 → cinchdb-0.1.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cinchdb"
-version = "0.1.15"
+version = "0.1.18"
 description = "A Git-like SQLite database management system with branching and multi-tenancy"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,7 @@ dependencies = [
     "typer>=0.9.0",
     "rich>=13.0.0",
     "requests>=2.28.0",
+    "httpx>=0.25.0",
 ]
 
 [project.optional-dependencies]
@@ -80,7 +81,14 @@ packages = ["src/cinchdb"]
 dev-dependencies = [
     "pytest>=8.0.0",
     "pytest-cov>=4.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-timeout>=2.4.0",
     "ruff>=0.5.0",
     "mypy>=1.0.0",
     "responses>=0.23.0",
 ]
+
+[tool.pytest.ini_options]
+timeout = 5
+timeout_method = "thread"
+addopts = "--timeout=5 --timeout-method=thread"

{cinchdb-0.1.15 → cinchdb-0.1.18}/src/cinchdb/cli/commands/tenant.py

@@ -68,10 +68,25 @@ def create(
     description: Optional[str] = typer.Option(
         None, "--description", "-d", help="Tenant description"
     ),
+    encrypt: bool = typer.Option(
+        False, "--encrypt", help="Create encrypted tenant database"
+    ),
+    key: Optional[str] = typer.Option(
+        None, "--key", help="Encryption key for encrypted tenant (required with --encrypt)"
+    ),
 ):
     """Create a new tenant."""
     name = validate_required_arg(name, "name", ctx)
 
+    # Validate encryption parameters
+    if encrypt and not key:
+        console.print("[red]❌ --key is required when using --encrypt[/red]")
+        raise typer.Exit(1)
+    
+    if key and not encrypt:
+        console.print("[red]❌ --encrypt is required when using --key[/red]")
+        raise typer.Exit(1)
+
     # Validate tenant name
     try:
         validate_name(name, "tenant")
@@ -85,8 +100,13 @@ def create(
 
     try:
         tenant_mgr = TenantManager(config.project_dir, db_name, branch_name)
-        tenant_mgr.create_tenant(name, description)
-        console.print(f"[green]✅ Created tenant '{name}'[/green]")
+        tenant_mgr.create_tenant(name, description, encrypt=encrypt, encryption_key=key)
+        
+        if encrypt:
+            console.print(f"[green]✅ Created encrypted tenant '{name}'[/green]")
+            console.print("[yellow]Note: Keep your encryption key secure - losing it means losing your data[/yellow]")
+        else:
+            console.print(f"[green]✅ Created tenant '{name}'[/green]")
         console.print("[yellow]Note: Tenant has same schema as main tenant[/yellow]")
 
     except ValueError as e:
@@ -235,3 +255,31 @@ def vacuum(
     except ValueError as e:
         console.print(f"[red]❌ {e}[/red]")
         raise typer.Exit(1)
+
+
+@app.command(name="rotate-key")
+def rotate_key(
+    tenant_name: str = typer.Argument(..., help="Name of the tenant to rotate encryption key for"),
+):
+    """Rotate encryption key for a tenant (requires plugged extension)."""
+    validate_required_arg(tenant_name, "tenant name")
+    
+    config, config_data = get_config_with_data()
+    db_name = config_data.active_database
+    branch_name = config_data.active_branch
+
+    try:
+        tenant_mgr = TenantManager(config.project_dir, db_name, branch_name)
+        
+        console.print(f"[yellow]🔐 Rotating encryption key for tenant '{tenant_name}'...[/yellow]")
+        
+        new_key = tenant_mgr.rotate_tenant_key(tenant_name)
+        
+        console.print("[green]✅ Encryption key rotated successfully[/green]")
+        console.print(f"  Tenant: {tenant_name}")
+        console.print(f"  New key generated (version incremented)")
+        console.print("[blue]ℹ️  Historical data remains accessible with previous key versions[/blue]")
+        
+    except ValueError as e:
+        console.print(f"[red]❌ {e}[/red]")
+        raise typer.Exit(1)

{cinchdb-0.1.15 → cinchdb-0.1.18}/src/cinchdb/config.py

@@ -134,17 +134,8 @@ class Config:
         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.
-
-        This method now delegates to the ProjectInitializer for the actual
-        initialization logic.
-        """
-        from cinchdb.core.initializer import ProjectInitializer
-
-        initializer = ProjectInitializer(self.project_dir)
-        config = initializer.init_project()
+    @property
+    def base_dir(self) -> Path:
+        """Get the base project directory."""
+        return self.project_dir
 
-        # Load the config into this instance
-        self._config = config
-        return config

{cinchdb-0.1.15 → cinchdb-0.1.18}/src/cinchdb/core/connection.py

@@ -1,8 +1,9 @@
 """SQLite connection management for CinchDB."""
 
+import os
 import sqlite3
 from pathlib import Path
-from typing import Optional, Dict, List
+from typing import Optional, Dict, List, Any
 from contextlib import contextmanager
 from datetime import datetime
 
@@ -28,13 +29,19 @@ sqlite3.register_converter("DATETIME", convert_datetime)
 class DatabaseConnection:
     """Manages a SQLite database connection with WAL mode."""
 
-    def __init__(self, path: Path):
+    def __init__(self, path: Path, tenant_id: Optional[str] = None, encryption_manager=None, encryption_key: Optional[str] = None):
         """Initialize database connection.
 
         Args:
             path: Path to SQLite database file
+            tenant_id: Tenant ID for per-tenant encryption
+            encryption_manager: EncryptionManager instance for encrypted connections
+            encryption_key: Encryption key for encrypted databases
         """
         self.path = Path(path)
+        self.tenant_id = tenant_id
+        self.encryption_manager = encryption_manager
+        self.encryption_key = encryption_key
         self._conn: Optional[sqlite3.Connection] = None
         self._connect()
 
@@ -43,19 +50,45 @@ class DatabaseConnection:
         # Ensure directory exists
         self.path.parent.mkdir(parents=True, exist_ok=True)
 
-        # Connect with row factory for dict-like access
-        # detect_types=PARSE_DECLTYPES tells SQLite to use our registered converters
-        self._conn = sqlite3.connect(
-            str(self.path),
-            detect_types=sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES,
-        )
+        # Use EncryptionManager if available
+        if self.encryption_manager:
+            self._conn = self.encryption_manager.get_connection(self.path, tenant_id=self.tenant_id)
+        elif self.encryption_key:
+            # Direct encryption key provided - use SQLCipher
+            self._conn = sqlite3.connect(
+                str(self.path),
+                detect_types=sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES,
+            )
+            
+            # Try to set encryption key (this will fail if SQLCipher is not available)
+            try:
+                self._conn.execute(f"PRAGMA key = '{self.encryption_key}'")
+            except sqlite3.OperationalError as e:
+                self._conn.close()
+                raise ValueError(
+                    "SQLCipher is required for encryption but not available. "
+                    "Please install pysqlcipher3 or sqlite3 with SQLCipher support."
+                ) from e
+            
+            # Configure WAL mode and settings
+            self._conn.execute("PRAGMA journal_mode = WAL")
+            self._conn.execute("PRAGMA synchronous = NORMAL")
+            self._conn.execute("PRAGMA wal_autocheckpoint = 0")
+        else:
+            # Fallback to standard SQLite connection
+            # Connect with row factory for dict-like access
+            # detect_types=PARSE_DECLTYPES tells SQLite to use our registered converters
+            self._conn = sqlite3.connect(
+                str(self.path),
+                detect_types=sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES,
+            )
+            
+            # Configure WAL mode and settings
+            self._conn.execute("PRAGMA journal_mode = WAL")
+            self._conn.execute("PRAGMA synchronous = NORMAL")
+            self._conn.execute("PRAGMA wal_autocheckpoint = 0")
         
-        # Configure WAL mode and settings
-        self._conn.execute("PRAGMA journal_mode = WAL")
-        self._conn.execute("PRAGMA synchronous = NORMAL")
-        self._conn.execute("PRAGMA wal_autocheckpoint = 0")
-        
-        # Set row factory and foreign keys
+        # Set row factory and foreign keys (both encrypted and unencrypted)
         self._conn.row_factory = sqlite3.Row
         self._conn.execute("PRAGMA foreign_keys = ON")
         self._conn.commit()
@@ -141,23 +174,28 @@ class ConnectionPool:
 
     def __init__(self):
         """Initialize connection pool."""
-        self._connections: Dict[Path, DatabaseConnection] = {}
+        self._connections: Dict[Any, DatabaseConnection] = {}
 
-    def get_connection(self, path: Path) -> DatabaseConnection:
+    def get_connection(self, path: Path, tenant_id: Optional[str] = None, encryption_manager=None) -> DatabaseConnection:
         """Get or create a connection for the given path.
 
         Args:
             path: Database file path
+            tenant_id: Tenant ID for per-tenant encryption
+            encryption_manager: EncryptionManager instance for encrypted connections
 
         Returns:
             Database connection
         """
         path = Path(path).resolve()
+        
+        # Create a cache key that includes tenant_id to handle per-tenant connections
+        cache_key = (str(path), tenant_id) if tenant_id else str(path)
 
-        if path not in self._connections:
-            self._connections[path] = DatabaseConnection(path)
+        if cache_key not in self._connections:
+            self._connections[cache_key] = DatabaseConnection(path, tenant_id=tenant_id, encryption_manager=encryption_manager)
 
-        return self._connections[path]
+        return self._connections[cache_key]
 
     def close_connection(self, path: Path) -> None:
         """Close and remove a specific connection.

{cinchdb-0.1.15 → cinchdb-0.1.18}/src/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
@@ -61,6 +63,8 @@ class CinchDB:
         project_dir: Optional[Path] = None,
         api_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        encryption_manager=None,
+        encryption_key: Optional[str] = None,
     ):
         """Initialize CinchDB connection.
 
@@ -71,6 +75,8 @@ class CinchDB:
             project_dir: Path to project directory for local connection
             api_url: Base URL for remote API connection
             api_key: API key for remote connection
+            encryption_manager: EncryptionManager instance for encrypted connections
+            encryption_key: Encryption key for encrypted tenant databases
 
         Raises:
             ValueError: If neither local nor remote connection params provided
@@ -78,7 +84,9 @@ class CinchDB:
         self.database = database
         self.branch = branch
         self.tenant = tenant
-
+        self.encryption_manager = encryption_manager
+        self.encryption_key = encryption_key
+        
         # Determine connection type
         if project_dir is not None:
             # Local connection
@@ -120,16 +128,29 @@ 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, tenant_id: Optional[str] = None, encryption_manager=None, encryption_key: Optional[str] = None) -> "DatabaseConnection":
+        """Get a database connection.
+        
+        Args:
+            db_path: Path to database file
+            tenant_id: Tenant ID for per-tenant encryption
+            encryption_manager: EncryptionManager instance for encrypted connections
+            encryption_key: Encryption key for encrypted databases
+            
+        Returns:
+            DatabaseConnection instance
+        """
+        from cinchdb.core.connection import DatabaseConnection
+        return DatabaseConnection(db_path, tenant_id=tenant_id, encryption_manager=encryption_manager, encryption_key=encryption_key)
 
     @property
     def session(self):
@@ -220,7 +241,7 @@ class CinchDB:
             from cinchdb.managers.table import TableManager
 
             self._table_manager = TableManager(
-                self.project_dir, self.database, self.branch, self.tenant
+                self.project_dir, self.database, self.branch, self.tenant, self.encryption_manager
             )
         return self._table_manager
 
@@ -235,7 +256,7 @@ class CinchDB:
             from cinchdb.managers.column import ColumnManager
 
             self._column_manager = ColumnManager(
-                self.project_dir, self.database, self.branch, self.tenant
+                self.project_dir, self.database, self.branch, self.tenant, self.encryption_manager
             )
         return self._column_manager
 
@@ -278,7 +299,7 @@ class CinchDB:
             from cinchdb.managers.tenant import TenantManager
 
             self._tenant_manager = TenantManager(
-                self.project_dir, self.database, self.branch
+                self.project_dir, self.database, self.branch, self.encryption_manager
             )
         return self._tenant_manager
 
@@ -293,7 +314,7 @@ class CinchDB:
             from cinchdb.managers.data import DataManager
 
             self._data_manager = DataManager(
-                self.project_dir, self.database, self.branch, self.tenant
+                self.project_dir, self.database, self.branch, self.tenant, self.encryption_manager
             )
         return self._data_manager
 
@@ -370,9 +391,9 @@ class CinchDB:
                 from cinchdb.managers.query import QueryManager
 
                 self._query_manager = QueryManager(
-                    self.project_dir, self.database, self.branch, self.tenant
+                    self.project_dir, self.database, self.branch, self.tenant, self.encryption_manager
                 )
-            return self._query_manager.execute(sql, params)
+            return self._query_manager.execute(sql, params, skip_validation)
         else:
             # Remote query
             data = {"sql": sql}
@@ -854,6 +875,7 @@ def connect(
     branch: str = "main",
     tenant: str = "main",
     project_dir: Optional[Path] = None,
+    encryption_key: Optional[str] = None,
 ) -> CinchDB:
     """Connect to a local CinchDB database.
 
@@ -862,6 +884,7 @@ def connect(
         branch: Branch name (default: main)
         tenant: Tenant name (default: main)
         project_dir: Path to project directory (optional, will search for .cinchdb)
+        encryption_key: Encryption key for encrypted tenant databases
 
     Returns:
         CinchDB connection instance
@@ -873,6 +896,9 @@ def connect(
         # Connect to specific branch
         db = connect("mydb", "feature-branch")
 
+        # Connect to encrypted tenant
+        db = connect("mydb", tenant="customer_a", encryption_key="my-secret-key")
+
         # Connect with explicit project directory
         db = connect("mydb", project_dir=Path("/path/to/project"))
     """
@@ -883,7 +909,8 @@ def connect(
             raise ValueError("No .cinchdb directory found. Run 'cinchdb init' first.")
 
     return CinchDB(
-        database=database, branch=branch, tenant=tenant, project_dir=project_dir
+        database=database, branch=branch, tenant=tenant, project_dir=project_dir,
+        encryption_key=encryption_key
     )
 
 

{cinchdb-0.1.15 → cinchdb-0.1.18}/src/cinchdb/core/initializer.py

@@ -1,6 +1,5 @@
 """Project initialization for CinchDB."""
 
-import hashlib
 import json
 import uuid
 from datetime import datetime, timezone
@@ -11,19 +10,12 @@ from cinchdb.core.connection import DatabaseConnection
 from cinchdb.config import ProjectConfig
 from cinchdb.infrastructure.metadata_db import MetadataDB
 from cinchdb.infrastructure.metadata_connection_pool import get_metadata_db
-
-
-def _calculate_shard(tenant_name: str) -> str:
-    """Calculate the shard directory for a tenant using SHA256 hash.
-    
-    Args:
-        tenant_name: Name of the tenant
-        
-    Returns:
-        Two-character hex string (e.g., "a0", "ff")
-    """
-    hash_val = hashlib.sha256(tenant_name.encode('utf-8')).hexdigest()
-    return hash_val[:2]
+from cinchdb.core.path_utils import (
+    calculate_shard,
+    ensure_tenant_db_path,
+    get_context_root,
+    ensure_context_directory,
+)
 
 
 class ProjectInitializer:
@@ -106,7 +98,7 @@ class ProjectInitializer:
         
         # Also create main tenant in metadata
         tenant_id = str(uuid.uuid4())
-        main_shard = _calculate_shard("main")
+        main_shard = calculate_shard("main")
         self.metadata_db.create_tenant(
             tenant_id, branch_id, "main", main_shard,
             metadata={"created_at": datetime.now(timezone.utc).isoformat()}
@@ -115,7 +107,7 @@ class ProjectInitializer:
         
         # Create __empty__ tenant in metadata (for lazy tenant reads)
         empty_tenant_id = str(uuid.uuid4())
-        empty_shard = _calculate_shard("__empty__")
+        empty_shard = calculate_shard("__empty__")
         self.metadata_db.create_tenant(
             empty_tenant_id, branch_id, "__empty__", empty_shard,
             metadata={
@@ -188,7 +180,7 @@ class ProjectInitializer:
         
         # Create main tenant entry in metadata (will be materialized if database is not lazy)
         main_tenant_id = str(uuid.uuid4())
-        main_shard = _calculate_shard("main")
+        main_shard = calculate_shard("main")
         self.metadata_db.create_tenant(
             main_tenant_id, branch_id, "main", main_shard,
             metadata={"description": "Default tenant", "created_at": datetime.now(timezone.utc).isoformat()}
@@ -197,7 +189,7 @@ class ProjectInitializer:
         # Create __empty__ tenant entry in metadata (lazy)
         # This serves as a template for all lazy tenants in this branch
         empty_tenant_id = str(uuid.uuid4())
-        empty_shard = _calculate_shard("__empty__")
+        empty_shard = calculate_shard("__empty__")
         self.metadata_db.create_tenant(
             empty_tenant_id, branch_id, "__empty__", empty_shard,
             metadata={"system": True, "description": "Template for lazy tenants"}
@@ -219,44 +211,37 @@ class ProjectInitializer:
         description: Optional[str] = None,
         create_tenant_files: bool = False,
     ) -> None:
-        """Create the directory structure for a database.
+        """Create the directory structure for a database using tenant-first storage.
 
         Args:
             database_name: Name of the database
             branch_name: Name of the initial branch
             description: Optional description
+            create_tenant_files: Whether to create actual tenant files
         """
-        # 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
+        # Use tenant-first structure: .cinchdb/{database}-{branch}/
+        context_root = ensure_context_directory(self.project_dir, database_name, branch_name)
+        
+        # Create metadata file in context root
         metadata = {
             "created_at": datetime.now(timezone.utc).isoformat(),
-            "name": branch_name,
+            "database": database_name,
+            "branch": branch_name,
             "parent": None,
             "description": description,
         }
-
-        with open(branch_path / "metadata.json", "w") as f:
+        
+        with open(context_root / "metadata.json", "w") as f:
             json.dump(metadata, f, indent=2)
-
+        
         # Create empty changes file
-        with open(branch_path / "changes.json", "w") as f:
+        with open(context_root / "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 main tenant database in sharded directory (only if requested)
         if create_tenant_files:
-            main_shard = _calculate_shard("main")
-            main_shard_dir = tenant_dir / main_shard
-            main_shard_dir.mkdir(parents=True, exist_ok=True)
-            self._init_tenant_database(main_shard_dir / "main.db")
+            main_db_path = ensure_tenant_db_path(self.project_dir, database_name, branch_name, "main")
+            self._init_tenant_database(main_db_path)
 
     def _init_tenant_database(self, db_path: Path) -> None:
         """Initialize a tenant database with proper PRAGMAs.