fix: Add missing foreign key constraints for project removal (#254)

src/basic_memory/alembic/versions/a1b2c3d4e5f6_fix_project_foreign_keys.py

@@ -0,0 +1,54 @@
+"""fix project foreign keys
+
+Revision ID: a1b2c3d4e5f6
+Revises: 647e7a75e2cd
+Create Date: 2025-08-19 22:06:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "a1b2c3d4e5f6"
+down_revision: Union[str, None] = "647e7a75e2cd"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Re-establish foreign key constraints that were lost during project table recreation.
+
+    The migration 647e7a75e2cd recreated the project table but did not re-establish
+    the foreign key constraint from entity.project_id to project.id, causing
+    foreign key constraint failures when trying to delete projects with related entities.
+    """
+    # SQLite doesn't allow adding foreign key constraints to existing tables easily
+    # We need to be careful and handle the case where the constraint might already exist
+
+    with op.batch_alter_table("entity", schema=None) as batch_op:
+        # Try to drop existing foreign key constraint (may not exist)
+        try:
+            batch_op.drop_constraint("fk_entity_project_id", type_="foreignkey")
+        except Exception:
+            # Constraint may not exist, which is fine - we'll create it next
+            pass
+
+        # Add the foreign key constraint with CASCADE DELETE
+        # This ensures that when a project is deleted, all related entities are also deleted
+        batch_op.create_foreign_key(
+            "fk_entity_project_id", 
+            "project", 
+            ["project_id"], 
+            ["id"],
+            ondelete="CASCADE"
+        )
+
+
+def downgrade() -> None:
+    """Remove the foreign key constraint."""
+    with op.batch_alter_table("entity", schema=None) as batch_op:
+        batch_op.drop_constraint("fk_entity_project_id", type_="foreignkey")

tests/db/test_issue_254_foreign_key_constraints.py

@@ -0,0 +1,154 @@
+"""Test to verify that issue #254 is fixed.
+
+Issue #254: Foreign key constraint failures when deleting projects with related entities.
+
+The issue was that when migration 647e7a75e2cd recreated the project table,
+it did not re-establish the foreign key constraint from entity.project_id to project.id
+with CASCADE DELETE, causing foreign key constraint failures when trying to delete
+projects that have related entities.
+
+Migration a1b2c3d4e5f6 was created to fix this by adding the missing foreign key
+constraint with CASCADE DELETE behavior.
+
+This test file verifies that the fix works correctly in production databases
+that have had the migration applied.
+"""
+from datetime import datetime, timezone
+
+import pytest
+
+from basic_memory.services.project_service import ProjectService
+
+
+#@pytest.mark.skip(reason="Issue #254 not fully resolved yet - foreign key constraint errors still occur")
+@pytest.mark.asyncio
+async def test_issue_254_foreign_key_constraint_fix(project_service: ProjectService, tmp_path):
+    """Test to verify issue #254 is fixed: project removal with foreign key constraints.
+
+    This test reproduces the exact scenario from issue #254:
+    1. Create a project
+    2. Create entities, observations, and relations linked to that project  
+    3. Attempt to remove the project
+    4. Verify it succeeds without "FOREIGN KEY constraint failed" errors
+    5. Verify all related data is properly cleaned up via CASCADE DELETE
+
+    Once issue #254 is fully fixed, remove the @pytest.mark.skip decorator.
+    """
+    test_project_name = "issue-254-verification"
+    test_project_path = str(tmp_path / "issue-254-verification")
+
+    # Step 1: Create test project
+    await project_service.add_project(test_project_name, test_project_path)
+    project = await project_service.get_project(test_project_name)
+    assert project is not None, "Project should be created successfully"
+
+    # Step 2: Create related entities that would cause foreign key constraint issues
+    from basic_memory.repository.entity_repository import EntityRepository
+    from basic_memory.repository.observation_repository import ObservationRepository
+    from basic_memory.repository.relation_repository import RelationRepository
+
+    entity_repo = EntityRepository(project_service.repository.session_maker, project_id=project.id)
+    obs_repo = ObservationRepository(project_service.repository.session_maker, project_id=project.id)
+    rel_repo = RelationRepository(project_service.repository.session_maker, project_id=project.id)
+
+    # Create entity
+    entity_data = {
+        "title": "Issue 254 Test Entity",
+        "entity_type": "note",
+        "content_type": "text/markdown",
+        "project_id": project.id,
+        "permalink": "issue-254-entity",
+        "file_path": "issue-254-entity.md",
+        "checksum": "issue254test",
+        "created_at": datetime.now(timezone.utc),
+        "updated_at": datetime.now(timezone.utc),
+    }
+    entity = await entity_repo.create(entity_data)
+
+    # Create observation linked to entity
+    observation_data = {
+        "entity_id": entity.id,
+        "content": "This observation should be cascade deleted",
+        "category": "test"
+    }
+    observation = await obs_repo.create(observation_data)
+
+    # Create relation involving the entity
+    relation_data = {
+        "from_id": entity.id,
+        "to_name": "some-other-entity",
+        "relation_type": "relates-to"
+    }
+    relation = await rel_repo.create(relation_data)
+
+    # Step 3: Attempt to remove the project
+    # This is where issue #254 manifested - should NOT raise "FOREIGN KEY constraint failed"
+    try:
+        await project_service.remove_project(test_project_name)
+    except Exception as e:
+        if "FOREIGN KEY constraint failed" in str(e):
+            pytest.fail(
+                f"Issue #254 not fixed - foreign key constraint error still occurs: {e}. "
+                f"The migration a1b2c3d4e5f6 may not have been applied correctly or "
+                f"the CASCADE DELETE constraint is not working as expected."
+            )
+        else:
+            # Re-raise unexpected errors
+            raise
+
+    # Step 4: Verify project was successfully removed
+    removed_project = await project_service.get_project(test_project_name)
+    assert removed_project is None, "Project should have been removed"
+
+    # Step 5: Verify related data was cascade deleted
+    remaining_entity = await entity_repo.find_by_id(entity.id)
+    assert remaining_entity is None, "Entity should have been cascade deleted"
+
+    remaining_observation = await obs_repo.find_by_id(observation.id)
+    assert remaining_observation is None, "Observation should have been cascade deleted"
+
+    remaining_relation = await rel_repo.find_by_id(relation.id)
+    assert remaining_relation is None, "Relation should have been cascade deleted"
+
+
+@pytest.mark.asyncio
+async def test_issue_254_reproduction(project_service: ProjectService, tmp_path):
+    """Test that reproduces issue #254 to document the current state.
+
+    This test demonstrates the current behavior and will fail until the issue is fixed.
+    It serves as documentation of what the problem was.
+    """
+    test_project_name = "issue-254-reproduction"
+    test_project_path = str(tmp_path / "issue-254-reproduction")
+
+    # Create project and entity
+    await project_service.add_project(test_project_name, test_project_path)
+    project = await project_service.get_project(test_project_name)
+
+    from basic_memory.repository.entity_repository import EntityRepository
+    entity_repo = EntityRepository(project_service.repository.session_maker, project_id=project.id)
+
+    entity_data = {
+        "title": "Reproduction Entity",
+        "entity_type": "note",
+        "content_type": "text/markdown",
+        "project_id": project.id,
+        "permalink": "reproduction-entity",
+        "file_path": "reproduction-entity.md",
+        "checksum": "repro123",
+        "created_at": datetime.now(timezone.utc),
+        "updated_at": datetime.now(timezone.utc),
+    }
+    entity = await entity_repo.create(entity_data)
+
+    # This should eventually work without errors once issue #254 is fixed
+    #with pytest.raises(Exception) as exc_info:
+    await project_service.remove_project(test_project_name)
+
+    # Document the current error for tracking
+    # error_message = str(exc_info.value)
+    # assert any(keyword in error_message for keyword in [
+    #     "FOREIGN KEY constraint failed",
+    #     "constraint",
+    #     "integrity"
+    # ]), f"Expected foreign key or integrity constraint error, got: {error_message}"

tests/services/test_project_removal_bug.py

@@ -0,0 +1,125 @@
+"""Test for project removal bug #254."""
+
+import os
+from datetime import timezone, datetime
+
+import pytest
+
+from basic_memory.services.project_service import ProjectService
+
+
+@pytest.mark.asyncio
+async def test_remove_project_with_related_entities(project_service: ProjectService, tmp_path):
+    """Test removing a project that has related entities (reproduces issue #254).
+
+    This test verifies that projects with related entities (entities, observations, relations)
+    can be properly deleted without foreign key constraint violations.
+
+    The bug was caused by missing foreign key constraints with CASCADE DELETE after
+    the project table was recreated in migration 647e7a75e2cd.
+    """
+    test_project_name = f"test-remove-with-entities-{os.urandom(4).hex()}"
+    test_project_path = str(tmp_path / "test-remove-with-entities")
+
+    # Make sure the test directory exists
+    os.makedirs(test_project_path, exist_ok=True)
+
+    try:
+        # Step 1: Add the test project
+        await project_service.add_project(test_project_name, test_project_path)
+
+        # Verify project exists
+        project = await project_service.get_project(test_project_name)
+        assert project is not None
+
+        # Step 2: Create related entities for this project
+        from basic_memory.repository.entity_repository import EntityRepository
+        entity_repo = EntityRepository(project_service.repository.session_maker, project_id=project.id)
+
+        entity_data = {
+            "title": "Test Entity for Deletion",
+            "entity_type": "note", 
+            "content_type": "text/markdown",
+            "project_id": project.id,
+            "permalink": "test-deletion-entity",
+            "file_path": "test-deletion-entity.md",
+            "checksum": "test123",
+            "created_at": datetime.now(timezone.utc),
+            "updated_at": datetime.now(timezone.utc),
+        }
+        entity = await entity_repo.create(entity_data)
+        assert entity is not None
+
+        # Step 3: Create observations for the entity
+        from basic_memory.repository.observation_repository import ObservationRepository
+        obs_repo = ObservationRepository(project_service.repository.session_maker, project_id=project.id)
+
+        observation_data = {
+            "entity_id": entity.id,
+            "content": "This is a test observation",
+            "category": "note"
+        }
+        observation = await obs_repo.create(observation_data)
+        assert observation is not None
+
+        # Step 4: Create relations involving the entity 
+        from basic_memory.repository.relation_repository import RelationRepository
+        rel_repo = RelationRepository(project_service.repository.session_maker, project_id=project.id)
+
+        relation_data = {
+            "from_id": entity.id,
+            "to_name": "some-target-entity",
+            "relation_type": "relates-to"
+        }
+        relation = await rel_repo.create(relation_data)
+        assert relation is not None
+
+        # Step 5: Attempt to remove the project
+        # This should work with proper cascade delete, or fail with foreign key constraint
+        await project_service.remove_project(test_project_name)
+
+        # Step 6: Verify everything was properly deleted
+
+        # Project should be gone
+        removed_project = await project_service.get_project(test_project_name)
+        assert removed_project is None, "Project should have been removed"
+
+        # Related entities should be cascade deleted
+        remaining_entity = await entity_repo.find_by_id(entity.id)
+        assert remaining_entity is None, "Entity should have been cascade deleted"
+
+        # Observations should be cascade deleted
+        remaining_obs = await obs_repo.find_by_id(observation.id)
+        assert remaining_obs is None, "Observation should have been cascade deleted"
+
+        # Relations should be cascade deleted  
+        remaining_rel = await rel_repo.find_by_id(relation.id)
+        assert remaining_rel is None, "Relation should have been cascade deleted"
+
+    except Exception as e:
+        # Check if this is the specific foreign key constraint error from the bug report
+        if "FOREIGN KEY constraint failed" in str(e):
+            pytest.fail(
+                f"Bug #254 reproduced: {e}. "
+                "This indicates missing foreign key constraints with CASCADE DELETE. "
+                "Run migration a1b2c3d4e5f6_fix_project_foreign_keys.py to fix this."
+            )
+        else:
+            # Re-raise other unexpected errors
+            raise e
+
+    finally:
+        # Clean up - remove project if it still exists
+        if test_project_name in project_service.projects:
+            try:
+                await project_service.remove_project(test_project_name)
+            except Exception:
+                # Manual cleanup if remove_project fails
+                try:
+                    project_service.config_manager.remove_project(test_project_name)
+                except Exception:
+                    pass
+
+                project = await project_service.get_project(test_project_name)
+                if project:
+                    await project_service.repository.delete(project.id)