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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ic-python-db
-Version: 0.7.9
+Version: 0.8.2
 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.8.2}/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.8.2}/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.8.2"
 __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.8.2}/ic_python_db/db_engine.py

@@ -322,6 +322,50 @@ 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)
+
     def get_audit(
         self, id_from: Optional[int] = None, id_to: Optional[int] = None
     ) -> Dict[str, str]:

{ic_python_db-0.7.9 → ic_python_db-0.8.2}/ic_python_db/entity.py

@@ -334,6 +334,25 @@ class Entity:
             return cls.get_full_type_name() + "_alias"
         return f"{cls.get_full_type_name()}_{field_name}_alias"
 
+    @classmethod
+    def _auto_migrate_defaults(cls, data: dict) -> dict:
+        """Inject default values for new Property fields not present in stored data.
+
+        Called before migrate() during version-mismatch loads so that developers
+        don't need to write migrate() for the trivial case of adding a field
+        with a default value.
+        """
+        from .properties import Property
+
+        for klass in reversed(cls.__mro__):
+            for attr_name, attr_value in klass.__dict__.items():
+                if attr_name.startswith("_"):
+                    continue
+                if isinstance(attr_value, Property) and attr_name not in data:
+                    if attr_value.default is not None:
+                        data[attr_name] = attr_value.default
+        return data
+
     @classmethod
     def migrate(cls, obj: dict, from_version: int, to_version: int) -> dict:
         """Migrate entity data from one version to another.
@@ -404,8 +423,10 @@ class Entity:
                 f"Version mismatch for {type_name}@{entity_id}: "
                 f"stored={stored_version}, current={current_version}"
             )
-            # Apply migration
+            # Apply custom migration first (developer logic takes priority)
             data = cls.migrate(data, stored_version, current_version)
+            # Auto-inject defaults for new fields not handled by migrate()
+            data = cls._auto_migrate_defaults(data)
             data["__version__"] = current_version
             logger.debug(
                 f"Migrated {type_name}@{entity_id} to version {current_version}"

ic_python_db-0.8.2/ic_python_db/schema.py

@@ -0,0 +1,475 @@
+"""Schema introspection, diffing, and upgrade compatibility checking.
+
+Provides tools to:
+- Build a JSON-serializable schema descriptor from Entity subclasses
+- Compare old and new schemas to classify changes as safe or breaking
+- Enforce upgrade compatibility (reject breaking changes without migrate())
+"""
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Type
+
+if TYPE_CHECKING:
+    from .db_engine import Database
+
+
+class ChangeType(Enum):
+    ADDED = "added"
+    REMOVED = "removed"
+    TYPE_CHANGED = "type_changed"
+    DEFAULT_CHANGED = "default_changed"
+    CONSTRAINTS_CHANGED = "constraints_changed"
+    RELATIONSHIP_CHANGED = "relationship_changed"
+    ENTITY_ADDED = "entity_added"
+    ENTITY_REMOVED = "entity_removed"
+    VERSION_CHANGED = "version_changed"
+
+
+@dataclass
+class SchemaChange:
+    """Describes a single change between two schema versions."""
+
+    entity_type: str
+    field: Optional[str]
+    change_type: ChangeType
+    old_value: Any = None
+    new_value: Any = None
+    safe: bool = False
+    reason: str = ""
+
+    def __repr__(self):
+        if self.field:
+            return f"SchemaChange({self.entity_type}.{self.field}: {self.change_type.value}, safe={self.safe})"
+        return f"SchemaChange({self.entity_type}: {self.change_type.value}, safe={self.safe})"
+
+
+def build_field_descriptor(prop) -> Dict[str, Any]:
+    """Build a descriptor dict for a single Property or Relation."""
+    from .properties import (
+        Boolean,
+        Float,
+        Integer,
+        ManyToMany,
+        ManyToOne,
+        OneToMany,
+        OneToOne,
+        Relation,
+        String,
+    )
+
+    desc: Dict[str, Any] = {}
+
+    if isinstance(prop, Relation):
+        desc["kind"] = "relationship"
+        desc["type"] = type(prop).__name__
+        entity_types = prop.entity_types
+        if isinstance(entity_types, list):
+            desc["target"] = entity_types
+        else:
+            desc["target"] = entity_types
+        if prop.reverse_name:
+            desc["inverse"] = prop.reverse_name
+        desc["many"] = prop.many
+        return desc
+
+    desc["kind"] = "property"
+    desc["type"] = type(prop).__name__
+
+    if prop.default is not None:
+        desc["default"] = prop.default
+    elif hasattr(prop, "default"):
+        desc["has_default"] = prop.default is not None
+
+    if isinstance(prop, String):
+        constraints = {}
+        if prop.validator:
+            # Extract min/max length from closure
+            closure_vars = _extract_closure_vars(prop.validator)
+            if closure_vars.get("min_length") is not None:
+                constraints["min_length"] = closure_vars["min_length"]
+            if closure_vars.get("max_length") is not None:
+                constraints["max_length"] = closure_vars["max_length"]
+        if constraints:
+            desc["constraints"] = constraints
+
+    elif isinstance(prop, (Integer, Float)):
+        constraints = {}
+        if prop.validator:
+            closure_vars = _extract_closure_vars(prop.validator)
+            if closure_vars.get("min_value") is not None:
+                constraints["min_value"] = closure_vars["min_value"]
+            if closure_vars.get("max_value") is not None:
+                constraints["max_value"] = closure_vars["max_value"]
+        if constraints:
+            desc["constraints"] = constraints
+
+    return desc
+
+
+def _extract_closure_vars(func) -> Dict[str, Any]:
+    """Extract closure variables from a validator function."""
+    result = {}
+    if hasattr(func, "__code__") and hasattr(func, "__closure__"):
+        if func.__closure__:
+            free_vars = func.__code__.co_freevars
+            for name, cell in zip(free_vars, func.__closure__):
+                try:
+                    result[name] = cell.cell_contents
+                except ValueError:
+                    pass
+    return result
+
+
+def build_schema(entity_types: Dict[str, Type]) -> Dict[str, Any]:
+    """Build a complete schema descriptor from registered entity types.
+
+    Args:
+        entity_types: Dict mapping type names to Entity classes,
+                      typically from Database._entity_types
+
+    Returns:
+        Schema descriptor dict suitable for JSON serialization and comparison.
+    """
+    from .entity import Entity
+    from .properties import Property, Relation
+
+    schema: Dict[str, Any] = {}
+    seen_classes = set()
+
+    for type_name, entity_cls in entity_types.items():
+        if entity_cls in seen_classes:
+            continue
+        if not isinstance(entity_cls, type) or not issubclass(entity_cls, Entity):
+            continue
+        if entity_cls is Entity:
+            continue
+
+        seen_classes.add(entity_cls)
+        full_name = entity_cls.get_full_type_name()
+
+        entity_desc: Dict[str, Any] = {
+            "version": entity_cls.__version__,
+            "fields": {},
+            "relationships": {},
+        }
+
+        has_custom_migrate = _has_custom_migrate(entity_cls)
+        if has_custom_migrate:
+            entity_desc["has_migrate"] = True
+
+        for cls in reversed(entity_cls.__mro__):
+            for attr_name, attr_value in cls.__dict__.items():
+                if attr_name.startswith("_"):
+                    continue
+
+                if isinstance(attr_value, Property):
+                    entity_desc["fields"][attr_name] = build_field_descriptor(
+                        attr_value
+                    )
+                elif isinstance(attr_value, Relation):
+                    entity_desc["relationships"][attr_name] = build_field_descriptor(
+                        attr_value
+                    )
+
+        schema[full_name] = entity_desc
+
+    return schema
+
+
+def _has_custom_migrate(entity_cls: Type) -> bool:
+    """Check if an Entity class has overridden the default migrate() method."""
+    from .entity import Entity
+
+    if "migrate" not in entity_cls.__dict__:
+        return False
+    return entity_cls.migrate is not Entity.migrate
+
+
+def schema_hash(schema: Dict[str, Any]) -> str:
+    """Compute a deterministic hash of a schema descriptor."""
+    canonical = json.dumps(schema, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode()).hexdigest()
+
+
+def diff_schemas(
+    old_schema: Dict[str, Any], new_schema: Dict[str, Any]
+) -> List[SchemaChange]:
+    """Compare two schema descriptors and return a list of changes.
+
+    Changes are classified as safe (auto-migratable) or breaking (requires migrate()).
+    """
+    changes: List[SchemaChange] = []
+
+    all_entity_types = set(old_schema.keys()) | set(new_schema.keys())
+
+    for entity_type in sorted(all_entity_types):
+        old_entity = old_schema.get(entity_type)
+        new_entity = new_schema.get(entity_type)
+
+        if old_entity is None and new_entity is not None:
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=None,
+                    change_type=ChangeType.ENTITY_ADDED,
+                    new_value=new_entity,
+                    safe=True,
+                    reason="New entity type — no existing data to migrate",
+                )
+            )
+            continue
+
+        if old_entity is not None and new_entity is None:
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=None,
+                    change_type=ChangeType.ENTITY_REMOVED,
+                    old_value=old_entity,
+                    safe=True,
+                    reason="Removed entity type — existing data will be orphaned",
+                )
+            )
+            continue
+
+        if old_entity["version"] != new_entity["version"]:
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=None,
+                    change_type=ChangeType.VERSION_CHANGED,
+                    old_value=old_entity["version"],
+                    new_value=new_entity["version"],
+                    safe=True,
+                    reason=f"Version {old_entity['version']} → {new_entity['version']}",
+                )
+            )
+
+        _diff_fields(
+            entity_type,
+            old_entity.get("fields", {}),
+            new_entity.get("fields", {}),
+            changes,
+        )
+        _diff_relationships(
+            entity_type,
+            old_entity.get("relationships", {}),
+            new_entity.get("relationships", {}),
+            changes,
+        )
+
+    return changes
+
+
+def _diff_fields(
+    entity_type: str,
+    old_fields: Dict[str, Any],
+    new_fields: Dict[str, Any],
+    changes: List[SchemaChange],
+) -> None:
+    """Compare fields between old and new entity schemas."""
+    all_field_names = set(old_fields.keys()) | set(new_fields.keys())
+
+    for field_name in sorted(all_field_names):
+        old_field = old_fields.get(field_name)
+        new_field = new_fields.get(field_name)
+
+        if old_field is None and new_field is not None:
+            has_default = new_field.get("default") is not None or new_field.get(
+                "has_default", False
+            )
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=field_name,
+                    change_type=ChangeType.ADDED,
+                    new_value=new_field,
+                    safe=has_default,
+                    reason=(
+                        f"New field with default={new_field.get('default')!r} — auto-migratable"
+                        if has_default
+                        else "New field without default — requires migrate() to provide initial values"
+                    ),
+                )
+            )
+            continue
+
+        if old_field is not None and new_field is None:
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=field_name,
+                    change_type=ChangeType.REMOVED,
+                    old_value=old_field,
+                    safe=True,
+                    reason="Removed field — old data will be ignored on load",
+                )
+            )
+            continue
+
+        if old_field.get("type") != new_field.get("type"):
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=field_name,
+                    change_type=ChangeType.TYPE_CHANGED,
+                    old_value=old_field.get("type"),
+                    new_value=new_field.get("type"),
+                    safe=False,
+                    reason=f"Type changed {old_field.get('type')} → {new_field.get('type')} — requires migrate()",
+                )
+            )
+
+        old_constraints = old_field.get("constraints", {})
+        new_constraints = new_field.get("constraints", {})
+        if old_constraints != new_constraints:
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=field_name,
+                    change_type=ChangeType.CONSTRAINTS_CHANGED,
+                    old_value=old_constraints,
+                    new_value=new_constraints,
+                    safe=True,
+                    reason="Constraints changed — existing data may need validation",
+                )
+            )
+
+
+def _diff_relationships(
+    entity_type: str,
+    old_rels: Dict[str, Any],
+    new_rels: Dict[str, Any],
+    changes: List[SchemaChange],
+) -> None:
+    """Compare relationships between old and new entity schemas."""
+    all_rel_names = set(old_rels.keys()) | set(new_rels.keys())
+
+    for rel_name in sorted(all_rel_names):
+        old_rel = old_rels.get(rel_name)
+        new_rel = new_rels.get(rel_name)
+
+        if old_rel is None and new_rel is not None:
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=rel_name,
+                    change_type=ChangeType.ADDED,
+                    new_value=new_rel,
+                    safe=True,
+                    reason="New relationship — no existing data affected",
+                )
+            )
+            continue
+
+        if old_rel is not None and new_rel is None:
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=rel_name,
+                    change_type=ChangeType.REMOVED,
+                    old_value=old_rel,
+                    safe=True,
+                    reason="Removed relationship — old references will be orphaned",
+                )
+            )
+            continue
+
+        if old_rel.get("type") != new_rel.get("type"):
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=rel_name,
+                    change_type=ChangeType.RELATIONSHIP_CHANGED,
+                    old_value=old_rel,
+                    new_value=new_rel,
+                    safe=False,
+                    reason=(
+                        f"Relationship type changed {old_rel.get('type')} → {new_rel.get('type')} "
+                        f"— requires migrate()"
+                    ),
+                )
+            )
+        elif old_rel.get("target") != new_rel.get("target"):
+            changes.append(
+                SchemaChange(
+                    entity_type=entity_type,
+                    field=rel_name,
+                    change_type=ChangeType.RELATIONSHIP_CHANGED,
+                    old_value=old_rel,
+                    new_value=new_rel,
+                    safe=False,
+                    reason=(
+                        f"Relationship target changed {old_rel.get('target')} → {new_rel.get('target')} "
+                        f"— requires migrate()"
+                    ),
+                )
+            )
+
+
+def check_upgrade_compatibility(
+    db: "Database",
+    raise_on_error: bool = True,
+) -> List[SchemaChange]:
+    """Check that the current Entity definitions are compatible with stored schema.
+
+    Loads the previously stored schema from _system/_schema, builds the current
+    schema from registered Entity classes, diffs them, and verifies that every
+    breaking change has a corresponding migrate() override.
+
+    After successful validation, saves the new schema.
+
+    Args:
+        db: Database instance
+        raise_on_error: If True (default), raise on incompatible changes.
+                        If False, return the changes list without raising.
+
+    Returns:
+        List of SchemaChange objects describing all detected changes.
+
+    Raises:
+        SchemaIncompatibleError: If breaking changes are found without migrate().
+    """
+    old_schema_data = db.load("_system", "_schema")
+
+    current_schema = build_schema(db._entity_types)
+
+    if old_schema_data is None:
+        db.save("_system", "_schema", current_schema)
+        db.save("_system", "_schema_hash", schema_hash(current_schema))
+        return []
+
+    changes = diff_schemas(old_schema_data, current_schema)
+
+    breaking_without_migrate = []
+    for change in changes:
+        if change.safe:
+            continue
+        entity_cls = db._entity_types.get(change.entity_type)
+        if entity_cls and _has_custom_migrate(entity_cls):
+            continue
+        breaking_without_migrate.append(change)
+
+    if breaking_without_migrate and raise_on_error:
+        details = "\n".join(
+            f"  - {c.entity_type}.{c.field}: {c.reason}"
+            for c in breaking_without_migrate
+        )
+        raise SchemaIncompatibleError(
+            f"Upgrade rejected: {len(breaking_without_migrate)} breaking change(s) "
+            f"without migrate() method:\n{details}"
+        )
+
+    db.save("_system", "_schema", current_schema)
+    db.save("_system", "_schema_hash", schema_hash(current_schema))
+
+    return changes
+
+
+class SchemaIncompatibleError(Exception):
+    """Raised when an upgrade contains breaking schema changes without a migrate() method."""
+
+    pass

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ic-python-db
-Version: 0.7.9
+Version: 0.8.2
 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.8.2}/ic_python_db.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ ic_python_db/hooks.py
 ic_python_db/mixins.py
 ic_python_db/properties.py
 ic_python_db/py.typed
+ic_python_db/schema.py
 ic_python_db/storage.py
 ic_python_db/system_time.py
 ic_python_db.egg-info/PKG-INFO

{ic_python_db-0.7.9 → ic_python_db-0.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ic-python-db"
-version = "0.7.9"
+version = "0.8.2"
 description = "A lightweight key-value database written in Python, intended for use on the Internet Computer (IC)"
 readme = "README.md"
 authors = [

{ic_python_db-0.7.9 → ic_python_db-0.8.2}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="ic-python-db",
-    version="0.7.9",
+    version="0.8.2",
     author="Smart Social Contracts",
     author_email="smartsocialcontracts@gmail.com",
     description="A lightweight key-value database with entity relationships and audit logging",