Expiration

Bucket TTL is a non-negative integer-value, specified per bucket, that determines the maximum expiration times of individual items: if Bucket TTL is enabled, each newly created item lives for the number of seconds specified by Bucket TTL, following the item’s creation. After its expiration time is reached, the item will be deleted by Couchbase Server. Deleted items and their contents are no longer available: access-attempts are treated as if the items never existed.

The maximum value for Bucket TTL is MAX32INT seconds (2147483648, or 68.096 years). The default value is 0, which indicates that Bucket TTL is disabled. If Bucket TTL is changed from the default, it is thereby enabled.

Whenever Bucket TTL is modified, items that existed prior to the modification:

Items created or modified following the modification of Bucket TTL are subject to the modified Bucket TTL.

Bucket TTL can be established on Couchbase and Ephemeral buckets. It cannot be established on Memcached buckets. Note that Bucket TTL is only available in the Enterprise Edition of Couchbase Server.

As described in the Expiration Overview section of java-sdk::core-operations.adoc#expiry, an expiration time can be specified per item, by means of Couchbase SDK APIs: this is referred to as the item’s TTL. If a new item’s TTL is specified to be:

Bucket TTL is intended for use with buckets containing data that either must or can be permitted to expire after a certain period of time.

Bucket TTL must not be used with buckets whose data is required not to expire: for example, the buckets that support Couchbase Eventing and Couchbase Mobile. If Bucket TTL is used with such buckets, system failures may result.

When its expiration time is reached, an item is deleted as soon as one of the following occurs:

As described in Storage, for each item that is deleted, a tombstone, which includes key and metadata, continues to be maintained by Couchbase Server for some period of time, as a record: this applies to all instances of item-deletion, including those achieved by specifying Bucket TTL. To ensure that no trace of deleted items remains, tombstones are removed through a Metadata Purge. This is an automatic, non-disruptive background-process, which can be scheduled if necessary by means of Couchbase Web Console; as described in Auto-Compaction. Note that the console allows the intervals between purges to be established as appropriately low, so that tombstones are removed promptly.

When Cross Data-Center Replication occurs, the Bucket TTL setting does not get propagated from the source bucket to the target. However, items within the source bucket that have individual expiration times, including ones derived from the source Bucket TTL setting, are replicated to the target along with their individual expiration times.

Buckets in the target cluster can have their own Bucket TTL settings, which may differ from those of the buckets in the source. If, on the target cluster, the TTL of a replicated item is:

Note that in cases where the TTL of the replicated item is above that of Bucket TTL or is 0, if bi-directional XDCR has been set up, the TTL of the item at the source is eventually also either reduced or reset to the value of the target’s Bucket TTL.

Note also that when an item is replicated by XDCR, its expiration time is communicated to the target as absolute. This requires that the system clocks of the respective clusters be fully synchronized; otherwise, inconsistent behavior may result (as, for example, in the case where an item arrives at the target-cluster with an absolute expiration time that is earlier than the current time acknowledged by the target-cluster). See Clock Sync with NTP.

An expiration time can be set for a bucket by means of any of the following:

For information on roles that allow modification of bucket-settings, see Roles.

If auditing is switched on, changes to each bucket’s expiration time are recorded, and can be subsequently viewed. See Auditing.