[CBL-6817] Couchbase Lite Enhancement on Save and Delete Support Across Multiple Collection Instances

Product: Couchbase Lite
Component: mobile
Issue Link: CBL-6817
Affects Version(s): 3.2.2
Fix Version(s): 3.2.3

Summary

• In Couchbase Lite versions prior to 3.2.3, attempting to save or delete a document using a different CBLCollection* instance than the one used to obtain or create the document triggered an error. This limitation affected all collections, including default collections (CBLDatabase_DefaultCollection) and named collections (CBLDatabase_Collection), whether in the default or custom scopes.
• Starting from version 3.2.3 (through CBL-6817), Couchbase Lite allows save and delete operations on a document using any collection instance pointing to the same collection and database, regardless of whether it is the same pointer instance or not.
• The error message was also improved to clarify the cause when the problem does occur.

Symptoms 

• Error occurs when saving or deleting a document using a collection instance different from the one used to obtain the document, even if both refer to the same collection name in the same database.
• Prior to 3.2.3, error message: "Use document on a wrong collection"
• From 3.2.3 onwards, error message updated to: "The collection for save or delete does not match the document’s collection or belongs to a different database instance."
• Both CBLCollection_SaveDocument and CBLCollection_DeleteDocument calls fail under these conditions on versions < 3.2.3.

Triggers

• Obtain a document from one instance of a collection (e.g., coll_1 obtained by CBLDatabase_DefaultCollection or CBLDatabase_Collection).
• Later, acquire another instance of the same collection (e.g., coll_2) from the same database.
• Attempt to save or delete the original document using coll_2.
• On Couchbase Lite versions earlier than 3.2.3, this triggers the error.

Verification

Reproduce the error with either operation - delete or save - as follows:

// Create document using one collection instance
CBLCollection* coll_1 = CBLDatabase_DefaultCollection(db, &error);
CBLDocument* doc = CBLDocument_CreateWithID(document_id);

// Save (will succeed)
bool saved = CBLCollection_SaveDocument(coll_1, doc, &error);

CBLDocument_Release(doc);

// Retrieve the document again through coll_1 (will succeed)
doc = CBLCollection_GetDocument(coll_1, document_id, &error);

// Later, retrieve a second collection instance
CBLCollection* coll_2 = CBLDatabase_DefaultCollection(db, &error);

// Try to save or delete using the second collection instance with doc instance acquired from the first
bool saved_again = CBLCollection_SaveDocument(coll_2, doc, &error);  // fails < 3.2.3
bool deleted = CBLCollection_DeleteDocument(coll_2, doc, &error);    // fails < 3.2.3

• In Couchbase Lite < 3.2.3, these operations fail with Use document on a wrong collection message.
• In 3.2.3 and later, they succeed, as long as the collection and document are from the same database

Workarounds

If using Couchbase Lite < 3.2.3:

• Reuse the same default collection instance (singleton pattern): Always operate with the same collection pointer, especially for creating, retrieving, saving, or deleting documents.
• Re-fetch the document from the collection instance on which you’ll operate:

CBLCollection* coll_2 = CBLDatabase_DefaultCollection(db, &error);
CBLDocument* doc_2 = CBLCollection_GetDocument(coll_2, document_id, &error);

// Use on this collection instance
bool saved = CBLCollection_SaveDocument(coll_2, doc_2, &error);
bool deleted = CBLCollection_DeleteDocument(coll_2, doc_2, &error);

• Upgrade Couchbase Lite: Move to version 3.2.3 or later to avoid the restriction entirely.

Best Practice

• For all Couchbase Lite versions, avoid recreating/duplicating collection instances unnecessarily.
• Always retrieve or create a document from the collection instance that you intend to save or delete it with.
• Prefer upgrading to Couchbase Lite 3.2.3+ for seamless cross-instance document operations within the same collection and database.