Document Expiration

Document expiration is a new feature of Couchbase Lite 1.3. It is available on all platforms, but this document describes the Objective-C/Swift API.

Functionality

Documents in a local database can now have an expiration time. After that time, they are automatically purged from the database — this completely removes them, freeing the space they occupied.

Note: As with the existing explicit purge mechanism, this applies only to the local database; it has nothing to do with replication. The expiration time is not propagated when the document is replicated. The purge of the document does not cause it to be deleted on any other database. If the document is later updated on a remote database that the local database pulls from, the new revision will be pulled and the document will reappear.

Expiration timing is not highly precise. The times are stored with one-second granularity, and the timer that triggers expiration may be delayed slightly by the operating system or by other activity on the database thread. Expiration won't happen on iOS while an app is inactive, and of course it can't happen while the app is not running; this means it may be triggered soon after the app is activated or launched, to catch up with expiration times that have already passed.

API

Expiration Date

There is one new property on the CBLDocument class:

/** A date/time after which this document will be automatically purged. */
@property (strong, nullable) NSDate* expirationDate;

The default value is nil, meaning no expiration. Setting the property value to a date will cause the document to be purged as soon as possible after that date. (If the date is in the past, the document will be purged within seconds.)

The expiration date can be changed at any time before the purge takes place, and the new date takes effect immediately. Setting the property to nil cancels the purge.

Notifications

When a document is purged, either through expiration or via the existing purgeDocument: method, Couchbase Lite now posts notifications, just as it does for other document changes. The only difference is that, in the CBLDocumentChange object in the notification userInfo, the revisionID property is nil.