ic-python-db 0.7.9__tar.gz → 0.9.0__tar.gz

{ic_python_db-0.7.9/ic_python_db.egg-info → ic_python_db-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ic-python-db
-Version: 0.7.9
+Version: 0.9.0
 Summary: A lightweight key-value database written in Python, intended for use on the Internet Computer (IC)
 Home-page: https://github.com/smart-social-contracts/ic-python-db
 Author: Smart Social Contracts
@@ -61,6 +61,7 @@ A lightweight key-value database with entity relationships and audit logging cap
 
 - **Persistent Storage**: Works with StableBTreeMap stable structure for persistent storage on your canister's stable memory so your data persists automatically across canister upgrades.
 - **Entity-Relational Database**: Create, read and write entities with OneToOne, OneToMany, ManyToOne, and ManyToMany relationships.
+- **Schema Versioning & Upgrade Safety**: Automatic schema introspection, compatibility checking, and auto-migration for safe changes. Breaking changes without a `migrate()` method are rejected, preventing data corruption on canister upgrades.
 - **Entity Hooks**: Intercept and control entity lifecycle events (create, modify, delete) with `on_event` hooks.
 - **Access Control**: Thread-safe context management for user identity tracking and ownership-based permissions.
 - **Namespaces**: Organize entities into namespaces to avoid type conflicts when you have multiple entities with the same class name.
@@ -256,7 +257,7 @@ See [docs/HOOKS.md](docs/HOOKS.md) for more patterns.
 
 ## Access Control
 
-Thread-safe user context management with `as_user()`:
+User context management with `as_user()`:
 
 ```python
 from ic_python_db import Database, Entity, String, ACTION_MODIFY, ACTION_DELETE
@@ -316,6 +317,92 @@ class User(Entity):
     profile: Optional["Profile"] = OneToOne("Profile", "user")
 ```
 
+## Schema Versioning & Upgrade Safety
+
+ic-python-db includes built-in upgrade compatibility checking. The system introspects your Entity class definitions to detect schema changes and ensure safe upgrades.
+
+### Auto-migration for safe changes
+
+Adding a field with a default value requires no migration code — the system handles it automatically:
+
+```python
+# v1
+class Product(Entity):
+    __version__ = 1
+    name = String()
+
+# v2 — just add the field with a default, no migrate() needed
+class Product(Entity):
+    __version__ = 2
+    name = String()
+    price = Float(default=0.0)    # auto-injected for existing entities
+    active = Boolean(default=True) # auto-injected for existing entities
+```
+
+### Custom migration for breaking changes
+
+For type changes, field renames, or data transformations, override `migrate()`:
+
+```python
+class Product(Entity):
+    __version__ = 2
+    name = String()
+    price_dollars = Float()  # was price_cents: Integer in v1
+
+    @classmethod
+    def migrate(cls, obj, from_version, to_version):
+        if from_version == 1:
+            obj["price_dollars"] = obj.pop("price_cents") / 100.0
+        return obj
+```
+
+### Upgrade compatibility enforcement
+
+Call `check_upgrade_compatibility()` from your canister's `post_upgrade` to reject incompatible upgrades before they corrupt data:
+
+```python
+from basilisk import post_upgrade
+from ic_python_db import Database
+
+@post_upgrade
+def on_post_upgrade():
+    db = Database.get_instance()
+    db.check_upgrade_compatibility()
+    # If a breaking change lacks migrate(), this raises SchemaIncompatibleError
+    # which traps post_upgrade, causing the IC to roll back the upgrade
+```
+
+The system classifies schema changes as:
+
+| Change | Safety | Action |
+|--------|--------|--------|
+| Add field with `default=` | Safe | Auto-migrated |
+| Remove field | Safe | Old data ignored |
+| Add new Entity type | Safe | No migration needed |
+| Change field type | Breaking | Requires `migrate()` |
+| Add field without default | Breaking | Requires `migrate()` |
+| Change relationship type | Breaking | Requires `migrate()` |
+
+### Schema introspection
+
+You can inspect and compare schemas programmatically:
+
+```python
+from ic_python_db import Database, build_schema, diff_schemas
+
+db = Database.get_instance()
+
+# Build current schema from Entity definitions
+schema = db.build_schema_from_entities()
+
+# Compare two schemas
+changes = diff_schemas(old_schema, new_schema)
+for change in changes:
+    print(f"{change.entity_type}.{change.field}: {change.reason}")
+```
+
+See [docs/SCHEMA_VERSIONING.md](docs/SCHEMA_VERSIONING.md) for the full reference.
+
 ## API Reference
 
 - **Core**: `Database`, `Entity`
@@ -324,6 +411,7 @@ class User(Entity):
 - **Mixins**: `TimestampedMixin` (timestamps and ownership tracking)
 - **Hooks**: `ACTION_CREATE`, `ACTION_MODIFY`, `ACTION_DELETE`
 - **Context**: `get_caller_id()`, `set_caller_id()`, `Database.as_user()`
+- **Schema**: `build_schema`, `diff_schemas`, `schema_hash`, `SchemaIncompatibleError`
 
 ## Development
 

{ic_python_db-0.7.9 → ic_python_db-0.9.0}/README.md

@@ -12,6 +12,7 @@ A lightweight key-value database with entity relationships and audit logging cap
 
 - **Persistent Storage**: Works with StableBTreeMap stable structure for persistent storage on your canister's stable memory so your data persists automatically across canister upgrades.
 - **Entity-Relational Database**: Create, read and write entities with OneToOne, OneToMany, ManyToOne, and ManyToMany relationships.
+- **Schema Versioning & Upgrade Safety**: Automatic schema introspection, compatibility checking, and auto-migration for safe changes. Breaking changes without a `migrate()` method are rejected, preventing data corruption on canister upgrades.
 - **Entity Hooks**: Intercept and control entity lifecycle events (create, modify, delete) with `on_event` hooks.
 - **Access Control**: Thread-safe context management for user identity tracking and ownership-based permissions.
 - **Namespaces**: Organize entities into namespaces to avoid type conflicts when you have multiple entities with the same class name.
@@ -207,7 +208,7 @@ See [docs/HOOKS.md](docs/HOOKS.md) for more patterns.
 
 ## Access Control
 
-Thread-safe user context management with `as_user()`:
+User context management with `as_user()`:
 
 ```python
 from ic_python_db import Database, Entity, String, ACTION_MODIFY, ACTION_DELETE
@@ -267,6 +268,92 @@ class User(Entity):
     profile: Optional["Profile"] = OneToOne("Profile", "user")
 ```
 
+## Schema Versioning & Upgrade Safety
+
+ic-python-db includes built-in upgrade compatibility checking. The system introspects your Entity class definitions to detect schema changes and ensure safe upgrades.
+
+### Auto-migration for safe changes
+
+Adding a field with a default value requires no migration code — the system handles it automatically:
+
+```python
+# v1
+class Product(Entity):
+    __version__ = 1
+    name = String()
+
+# v2 — just add the field with a default, no migrate() needed
+class Product(Entity):
+    __version__ = 2
+    name = String()
+    price = Float(default=0.0)    # auto-injected for existing entities
+    active = Boolean(default=True) # auto-injected for existing entities
+```
+
+### Custom migration for breaking changes
+
+For type changes, field renames, or data transformations, override `migrate()`:
+
+```python
+class Product(Entity):
+    __version__ = 2
+    name = String()
+    price_dollars = Float()  # was price_cents: Integer in v1
+
+    @classmethod
+    def migrate(cls, obj, from_version, to_version):
+        if from_version == 1:
+            obj["price_dollars"] = obj.pop("price_cents") / 100.0
+        return obj
+```
+
+### Upgrade compatibility enforcement
+
+Call `check_upgrade_compatibility()` from your canister's `post_upgrade` to reject incompatible upgrades before they corrupt data:
+
+```python
+from basilisk import post_upgrade
+from ic_python_db import Database
+
+@post_upgrade
+def on_post_upgrade():
+    db = Database.get_instance()
+    db.check_upgrade_compatibility()
+    # If a breaking change lacks migrate(), this raises SchemaIncompatibleError
+    # which traps post_upgrade, causing the IC to roll back the upgrade
+```
+
+The system classifies schema changes as:
+
+| Change | Safety | Action |
+|--------|--------|--------|
+| Add field with `default=` | Safe | Auto-migrated |
+| Remove field | Safe | Old data ignored |
+| Add new Entity type | Safe | No migration needed |
+| Change field type | Breaking | Requires `migrate()` |
+| Add field without default | Breaking | Requires `migrate()` |
+| Change relationship type | Breaking | Requires `migrate()` |
+
+### Schema introspection
+
+You can inspect and compare schemas programmatically:
+
+```python
+from ic_python_db import Database, build_schema, diff_schemas
+
+db = Database.get_instance()
+
+# Build current schema from Entity definitions
+schema = db.build_schema_from_entities()
+
+# Compare two schemas
+changes = diff_schemas(old_schema, new_schema)
+for change in changes:
+    print(f"{change.entity_type}.{change.field}: {change.reason}")
+```
+
+See [docs/SCHEMA_VERSIONING.md](docs/SCHEMA_VERSIONING.md) for the full reference.
+
 ## API Reference
 
 - **Core**: `Database`, `Entity`
@@ -275,6 +362,7 @@ class User(Entity):
 - **Mixins**: `TimestampedMixin` (timestamps and ownership tracking)
 - **Hooks**: `ACTION_CREATE`, `ACTION_MODIFY`, `ACTION_DELETE`
 - **Context**: `get_caller_id()`, `set_caller_id()`, `Database.as_user()`
+- **Schema**: `build_schema`, `diff_schemas`, `schema_hash`, `SchemaIncompatibleError`
 
 ## Development
 

{ic_python_db-0.7.9 → ic_python_db-0.9.0}/ic_python_db/__init__.py

@@ -16,10 +16,11 @@ from .properties import (
     OneToOne,
     String,
 )
+from .schema import SchemaIncompatibleError, build_schema, diff_schemas, schema_hash
 from .storage import MemoryStorage, Storage
 from .system_time import SystemTime
 
-__version__ = "0.7.9"
+__version__ = "0.9.0"
 __all__ = [
     "Database",
     "Entity",
@@ -38,4 +39,8 @@ __all__ = [
     "ACTION_CREATE",
     "ACTION_MODIFY",
     "ACTION_DELETE",
+    "SchemaIncompatibleError",
+    "build_schema",
+    "diff_schemas",
+    "schema_hash",
 ]

{ic_python_db-0.7.9 → ic_python_db-0.9.0}/ic_python_db/db_engine.py

@@ -322,6 +322,110 @@ class Database:
             return json.dumps(result, indent=2)
         return json.dumps(result)
 
+    def build_schema_from_entities(self) -> Dict[str, Any]:
+        """Build a schema descriptor from all registered entity types.
+
+        Returns:
+            Dict describing every entity type's fields, types, defaults,
+            constraints, and relationships.
+        """
+        from .schema import build_schema
+
+        return build_schema(self._entity_types)
+
+    def get_schema_hash(self) -> Optional[str]:
+        """Return the stored schema hash, or None if no schema has been saved."""
+        return self.load("_system", "_schema_hash")
+
+    def save_schema(self) -> None:
+        """Persist the current schema descriptor and its hash."""
+        from .schema import schema_hash
+
+        current = self.build_schema_from_entities()
+        self.save("_system", "_schema", current)
+        self.save("_system", "_schema_hash", schema_hash(current))
+
+    def check_upgrade_compatibility(self, raise_on_error: bool = True):
+        """Check that current Entity definitions are compatible with stored schema.
+
+        Compares the previously stored schema against the live class definitions.
+        Breaking changes (type changes, new fields without defaults, relationship
+        cardinality changes) require the Entity to define a migrate() override.
+
+        On success, saves the new schema. On failure (with raise_on_error=True),
+        raises SchemaIncompatibleError — designed to be called from post_upgrade
+        so the IC rolls back the upgrade.
+
+        Returns:
+            List of SchemaChange objects.
+
+        Raises:
+            SchemaIncompatibleError: if incompatible and raise_on_error is True.
+        """
+        from .schema import check_upgrade_compatibility
+
+        return check_upgrade_compatibility(self, raise_on_error=raise_on_error)
+
+    # ── Reverse Index API ──────────────────────────────────────────────────────
+    #
+    # Reverse indexes allow OneToMany / ManyToMany / inverse-OneToOne relations
+    # to be resolved without scanning all child entities.
+    #
+    # Key format: _ri:{ParentType}:{parent_id}:{relation_name}
+    # Value: JSON array of child entity IDs, e.g. ["1", "2", "3"]
+
+    def _ri_key(self, parent_type: str, parent_id: str, relation_name: str) -> str:
+        return f"_ri:{parent_type}:{parent_id}:{relation_name}"
+
+    def reverse_index_get(
+        self, parent_type: str, parent_id: str, relation_name: str
+    ) -> List[str]:
+        """Read the reverse index for a parent entity's relation.
+
+        Returns:
+            List of child entity IDs, or empty list if no index exists.
+        """
+        key = self._ri_key(parent_type, parent_id, relation_name)
+        raw = self._db_storage.get(key)
+        if raw:
+            return json.loads(raw)
+        return []
+
+    def reverse_index_add(
+        self, parent_type: str, parent_id: str, relation_name: str, child_id: str
+    ) -> None:
+        """Add a child ID to a parent's reverse index."""
+        key = self._ri_key(parent_type, parent_id, relation_name)
+        raw = self._db_storage.get(key)
+        ids = json.loads(raw) if raw else []
+        if child_id not in ids:
+            ids.append(child_id)
+            self._db_storage.insert(key, json.dumps(ids))
+
+    def reverse_index_remove(
+        self, parent_type: str, parent_id: str, relation_name: str, child_id: str
+    ) -> None:
+        """Remove a child ID from a parent's reverse index."""
+        key = self._ri_key(parent_type, parent_id, relation_name)
+        raw = self._db_storage.get(key)
+        if not raw:
+            return
+        ids = json.loads(raw)
+        if child_id in ids:
+            ids.remove(child_id)
+            if ids:
+                self._db_storage.insert(key, json.dumps(ids))
+            else:
+                self._db_storage.remove(key)
+
+    def reverse_index_delete(
+        self, parent_type: str, parent_id: str, relation_name: str
+    ) -> None:
+        """Delete an entire reverse index entry (used when parent is deleted)."""
+        key = self._ri_key(parent_type, parent_id, relation_name)
+        if self._db_storage.get(key) is not None:
+            self._db_storage.remove(key)
+
     def get_audit(
         self, id_from: Optional[int] = None, id_to: Optional[int] = None
     ) -> Dict[str, str]: