[ENH]: soft delete databases, add FinishDatabaseDeletion gRPC method to hard delete databases

[codetheweb]

Description of changes

Databases are now always soft deleted instead of being hard deleted. Databases are hard deleted when the new FinishDatabaseDeletion method is called (the garbage collector calls this in the next PR).

Test plan

How are these changes tested?

• Tests pass locally with pytest for python, yarn test for js, cargo test for rust

Updated existing test to cover soft delete behavior.

Documentation Changes

Are all docstrings for user-facing APIs updated if required? Do we need to make documentation changes in the docs section?

n/a

[github-actions]

Reviewer Checklist

Please leverage this checklist to ensure your code review is thorough before approving

Testing, Bugs, Errors, Logs, Documentation

• Can you think of any use case in which the code does not behave as intended? Have they been tested?
• Can you think of any inputs or external events that could break the code? Is user input validated and safe? Have they been tested?
• If appropriate, are there adequate property based tests?
• If appropriate, are there adequate unit tests?
• Should any logging, debugging, tracing information be added or removed?
• Are error messages user-friendly?
• Have all documentation changes needed been made?
• Have all non-obvious changes been commented?

System Compatibility

• Are there any potential impacts on other parts of the system or backward compatibility?
• Does this change intersect with any items on our roadmap, and if so, is there a plan for fitting them together?

Quality

• Is this code of a unexpectedly high quality (Readability, Modularity, Intuitiveness)

[codetheweb]

• [ENH]: wire GC v2 to new cleanup modes & call FinishDatabaseDeletion from garbage collector #4671
• [ENH]: soft delete databases, add FinishDatabaseDeletion gRPC method to hard delete databases #4627 👈 (View in Graphite)
• [ENH]: perform collection hard deletes from garbage collector #4605
• [ENH]: sysdb changes to support moving collection hard deletes to garbage collector #4607
• [ENH]: add validation during garbage collection for empty file paths #4586
• [ENH]: garbage collector v2 orchestrator (supports forking) #4468
• [ENH]: allow deleting v0 from version file & correctly propagate errors on DeleteCollectionVersion #4579
• [ENH]: add operator for garbage collection to list all files used by collection version #4466
• [ENH]: add operator to compute versions to garbage collect from version graph #4464
• [ENH]: add orchestrator to construct version graph for garbage collection #4463
• [ENH]: add batch get version file paths method to Sysdb #4432 : 1 other dependent PR (#4447 )
• [ENH]: SysDb should return lineage, version file paths and root collection ID on collections #4557
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[codetheweb]

this method was never used

[propel-code-bot]

Implement Soft Delete for Databases with Hard Delete via New gRPC Method

This PR transitions database deletion in the system to a soft delete model, where databases are marked as deleted but remain in storage. A new gRPC method FinishDatabaseDeletion is introduced, allowing for controlled hard deletion (permanent removal), which will typically be invoked by the garbage collector. Associated collection deletions are also soft, and tests are updated to verify the new workflow. All major components and gRPC/protobuf definitions are updated to support these changes.

Key Changes:
• Adds an is_deleted flag to database model and transitions all deletions to soft delete (set flag, do not drop row).
• Removes existing methods and code logic for direct/hard deletes, replacing with soft delete logic.
• Introduces FinishDatabaseDeletion gRPC/proto endpoint (and implementation through all layers) to perform hard deletes on eligible databases (i.e., those soft-deleted and without collections, after a cutoff time).
• Propagates soft delete logic to database-listing and get methods (filters out deleted DBs).
• Updates and expands test cases to validate both soft and hard database deletion behaviors.
• Adjusts Rust API (chroma_types) and sysdb backend to support new deletion flow and error types.

Affected Areas:
• Go: sysdb coordinator, dao/database.go, dbmodel/database.go, collection and coordinator services
• Rust: sysdb.rs, api_types.rs
• Protobuf IDL: coordinator.proto
• Tests: tenant_database_service_test.go

Potential Impact:

Functionality: All client- and internal-facing database deletions become soft deletes; actual data persists until explicitly purged by hard delete. Deletion visibility (list/lookup) is changed: soft-deleted DBs become invisible to normal operations.

Performance: Negligible change under normal operation; possible minor overhead in list/get queries due to filtering. Hard deletion operates in batches to avoid transaction limits.

Security: Soft deleted databases remain recoverable and might be accessible via manual DB manipulation; eventual hard delete cleans them up as expected.

Scalability: Batch-oriented hard delete in FinishDatabaseDeletion supports cleaning up many entries at once without running into DB limits. Soft delete avoids immediate DB/IO cost.

Review Focus:
• Correctness and transactionality of soft and hard delete logic in both Go and Rust layers.
• Query correctness: only non-deleted databases are returned by list/get methods.
• Thoroughness of test coverage for new behavior and edge cases.
• Proto/gRPC compatibility between Go and Rust.
• Potential backward compatibility issues for existing API clients.

Testing Needed

• Run API and system tests to verify database and collection deletion workflows (deletion, attempted access, and garbage collection).
• Test edge cases where a database is soft deleted but contains soft- or hard-deleted collections.
• Validate new gRPC endpoint FinishDatabaseDeletion from client/garbage-collector perspective.
• Check list/get endpoints filter soft-deleted resources as intended.

Code Quality Assessment

go/pkg/sysdb/coordinator/table_catalog.go: Removed unused methods, updated workflow for soft delete and ensured cascading soft deletes for collections.

go/pkg/sysdb/metastore/db/dbmodel/database.go: Interface updated cleanly; model change (is_deleted) matches DB expectations.

rust/sysdb/src/sysdb.rs: New trait implementations for hard deletion; error handling for new workflows; consistent with existing structure.

rust/types/src/api_types.rs: New error types and trait implementations; maintains idiomatic usage.

idl/chromadb/proto/coordinator.proto: Backward-compatible addition of new methods/messages; comments are clear.

go/pkg/sysdb/metastore/db/dao/database.go: Refactored and extended with new methods; clear separation between soft and hard delete; code is readable and robust.

Best Practices

Database Schema:
• Uses soft delete flags instead of immediate row removal
• Batch operations for safe deletion

API Design:
• Adds new endpoints in a backward-compatible way
• Updates error handling and surface across service boundaries

Test Coverage:
• Expands tests for both normal and edge cases
• Aligned with updated business logic

Error Handling:
• Introduces specific errors/types for new workflows

Potential Issues

• Soft-deleted databases still exist at the storage layer until the hard delete runs; operators should be aware this may affect storage utilization.
• Hard deletion runs in batches (limit 1000 per call); there may be a delay between soft and hard deletion depending on how/when GC runs.
• If soft-deleted databases have lingering collections or if collection deletion fails, hard deletion is deferred.
• API clients relying on immediate delete behavior should verify/updatetheir expectations.

This summary was automatically generated by @propel-code-bot

[Sicheng-Pan]

Lgtm

[codetheweb]

Merge activity

• May 29, 11:24 PM UTC: @codetheweb merged this pull request with Graphite.