docs/_includes/api/purge.html

{% include anchor.html edit="true" title="Purge a document rev" hash="purge" %}

{% highlight js %}
db.purge(docId, rev)
{% endhighlight %}

Purges a specific revision of a document, specified by `docId` and `rev`. `rev` must be a leaf revision.

Purge permanently removes data from the database. Normal deletion with `db.remove()` does not, it only marks the document as `_deleted=true` and creates a new revision. This behaviour ensures that deletes can be replicated across databases, and deleted documents don’t get undeleted by syncing with a database that still has this document.

`db.purge()` is not intended as a regular method for deleting documents, instead, it is meant as an admin function for cases where some secret was erroneously added to the database and must now be removed completely, eg. a credit card or social security number. Purge effectively puts the database in a state where the offending write never happened.

{% include alert/start.html variant="info"%}
{% markdown %}

**Purge is currently only implemented in the `indexeddb` adapter**.

Using Purge with any other adapter will return an error.

{% endmarkdown %}
{% include alert/end.html%}

#### Example Usage:

{% include code/start.html id="purge1" type="callback" %}
{% highlight js %}
db.purge('mydoc', '6-3a24009a9525bde9e4bfa8a99046b00d',
  function (err, result) {
    if (err) { return console.log(err); }
    // handle result
);
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="purge1" type="async" %}
{% highlight js %}
try {
  const result = await db.purge('mydoc', '6-3a24009a9525bde9e4bfa8a99046b00d');
  // handle result
} catch (err) {
  console.log(err);
}
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="purge1" type="promise" %}
{% highlight js %}
db.purge('mydoc', '6-3a24009a9525bde9e4bfa8a99046b00d')
  .then(function (result) {
    // handle result
  }).catch(function (err) {
    console.log(err);
  });
{% endhighlight %}
{% include code/end.html %}

#### Example Response:

{% highlight js %}
  {
    "ok": true,
    "deletedRevs": [
      "6-3a24009a9525bde9e4bfa8a99046b00d",
      "5-df4a81cd21c75c71974d96e88a68fc2f"
    ],
    "documentWasRemovedCompletely": false
  }
{% endhighlight %}

If the document has no conflicts, purging its only leaf rev deletes the document completely, and `purge()` returns `documentWasRemovedCompletely: true` in its result object.

If the document does have conflicts, purging will remove the specified rev and pick a leaf from another rev branch as the winner. Fetching the doc after the purge will return the updated state of the document with the new winning revision in `_rev`.

**Notes:**

* The `rev` specified for purging must be a leaf, otherwise an error will be returned
* Purges do not sync, they only apply to the database they are performed on
* If the document has conflicts, purging a leaf will also remove its ancestors up to the next branching rev, and pick a new winning rev
* Any attachments referenced in the specified rev will also be deleted