<commit_before>---
layout: learn
title: API Reference - PouchDB
---

# API Reference

Most of the PouchDB API is exposed as `fun(arg, [options], [callback])` Where both the options and the callback are optional. Callbacks use the `function(err, result)` idiom where the first argument will be undefined unless there is an error, the second argument holds the result.

## Create database<a id="create_database"></a>

{% highlight js %}
new PouchDB([name], [options])
{% endhighlight %}

This method creates a database or opens an existing one. If you use a `http://domain.com/dbname` then PouchDB will work as a client to an online CouchDB instance, otherwise it will create a local database using a backend that is present.

**Notes:** 

1. If you are also using indexedDB directly, PouchDB will use `_pouch_` to prefix the internal database names, dont manually create databases with the same prefix.
2. When acting as a client on Node any other options given will be passed to [request](https://github.com/mikeal/request).

* `options.name`: You can omit the name argument and specify it via options.
* `options.auto_compaction`: This turns on auto compaction (experimental).


#### Example Usage:
{% highlight js %}
var db = new PouchDB('dbname');
// or
var db = new PouchDB('http://localhost:5984/dbname');
{% endhighlight %}

## Delete database<a id="delete_database"></a>

{% highlight js %}
PouchDB.destroy(name, [options], [callback])
{% endhighlight %}

Delete database with given name

**Notes:** With a remote couch on node options are passed to [request](https://github.com/mikeal/request).

#### Example Usage:
{% highlight js %}
PouchDB.destroy('dbname', function(err, info) { });
{% endhighlight %}

## Create / Update a document<a id="create_document"></a>

### Using db.put()
{% highlight js %}
db.put(doc, [options], [callback])
{% endhighlight %}

Create a new document or update an existing document. If the document already exists
you must specify its revision `_rev`, otherwise a conflict will occur.

There are some restrictions on valid property names of the documents, these are explained [here](http://wiki.apache.org/couchdb/HTTP_Document_API#Special_Fields).

#### Example Usage:
{% highlight js %}
db.put({
  _id: 'mydoc',
  title: 'Heroes'
}, function(err, response) { });

db.put({
  _id: 'mydoc',
  _rev: '1-A6157A5EA545C99B00FF904EEF05FD9F',
  title: 'Lets Dance',
}, function(err, response) { })
{% endhighlight %}

#### Example Response:
{% highlight js %}
{
  "ok": true,
  "id": "mydoc",
  "rev": "1-A6157A5EA545C99B00FF904EEF05FD9F"
}
{% endhighlight %}
<commit_msg>(#1212) - clarify put example<commit_after>---
layout: learn
title: API Reference - PouchDB
---

# API Reference

Most of the PouchDB API is exposed as `fun(arg, [options], [callback])` Where both the options and the callback are optional. Callbacks use the `function(err, result)` idiom where the first argument will be undefined unless there is an error, the second argument holds the result.

## Create database<a id="create_database"></a>

{% highlight js %}
new PouchDB([name], [options])
{% endhighlight %}

This method creates a database or opens an existing one. If you use a `http://domain.com/dbname` then PouchDB will work as a client to an online CouchDB instance, otherwise it will create a local database using a backend that is present.

**Notes:** 

1. If you are also using indexedDB directly, PouchDB will use `_pouch_` to prefix the internal database names, dont manually create databases with the same prefix.
2. When acting as a client on Node any other options given will be passed to [request](https://github.com/mikeal/request).

* `options.name`: You can omit the name argument and specify it via options.
* `options.auto_compaction`: This turns on auto compaction (experimental).


#### Example Usage:
{% highlight js %}
var db = new PouchDB('dbname');
// or
var db = new PouchDB('http://localhost:5984/dbname');
{% endhighlight %}

## Delete database<a id="delete_database"></a>

{% highlight js %}
PouchDB.destroy(name, [options], [callback])
{% endhighlight %}

Delete database with given name

**Notes:** With a remote couch on node options are passed to [request](https://github.com/mikeal/request).

#### Example Usage:
{% highlight js %}
PouchDB.destroy('dbname', function(err, info) { });
{% endhighlight %}

## Create / Update a document<a id="create_document"></a>

### Using db.put()
{% highlight js %}
db.put(doc, [options], [callback])
{% endhighlight %}

Create a new document or update an existing document. If the document already exists you must specify its revision `_rev`, otherwise a conflict will occur.

There are some restrictions on valid property names of the documents, these are explained [here](http://wiki.apache.org/couchdb/HTTP_Document_API#Special_Fields).

#### Example Usage:

## Create a new doc with id.
{% highlight js %}
db.put({
  _id: 'mydoc',
  title: 'Heroes'
}, function(err, response) { });
{% endhighlight %}

## Update an existing doc
{% highlight js %}
db.get('myOtherDoc', function(err, resp) {
  db.put({
    _id: 'myOtherDoc',
    _rev: resp._rev,
    title: 'Lets Dance',
  }, function(err, response) { });
});

{% endhighlight %}

#### Example Response:
{% highlight js %}
{
  "ok": true,
  "id": "mydoc",
  "rev": "1-A6157A5EA545C99B00FF904EEF05FD9F"
}
{% endhighlight %}

{'fraction_non_alphanumeric': 0.13333333333333333, 'fraction_numerical': 0.013632119514472456, 'mean_word_length': 4.637894736842105, 'pattern_counts': {'":': 6, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2296834', 'n_tokens_mistral': 1713, 'n_tokens_neox': 1580, 'n_words': 617}