{% include anchor.html title="Create/update a document" hash="create_document" %}

### Using db.put()
{% highlight js %}
db.put(doc, [docId], [docRev], [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 an `_id` of `'mydoc'`:

{% include code/start.html id="newDoc" type="callback" %}
{% highlight js %}
db.put({
  _id: 'mydoc',
  title: 'Heroes'
}, function(err, response) {
  if (err) { return console.log(err); }
  // handle response
});
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="newDoc" type="promise" %}
{% highlight js %}
db.put({
  _id: 'mydoc',
  title: 'Heroes'
}).then(function (response) {
  // handle response
}).catch(function (err) {
  console.log(err);
});
{% endhighlight %}
{% include code/end.html %}

You can update an existing doc using `_rev`:

{% include code/start.html id="updateDoc" type="callback" %}
{% highlight js %}
db.get('mydoc', function(err, doc) {
  if (err) { return console.log(err); }
  db.put({
    _id: 'mydoc',
    _rev: doc._rev,
    title: "Let's Dance"
  }, function(err, response) {
    if (err) { return console.log(err); }
    // handle response
  });
});
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="updateDoc" type="promise" %}
{% highlight js %}
db.get('mydoc').then(function(doc) {
  return db.put({
    _id: 'mydoc',
    _rev: doc._rev,
    title: "Let's Dance"
  });
}).then(function(response) {
  // handle response
}).catch(function (err) {
  console.log(err);
});
{% endhighlight %}
{% include code/end.html %}

Instead of including the `_id` and `_rev` in the document, you can 
also pass them in as options:

{% include code/start.html id="updateDoc2" type="callback" %}
{% highlight js %}
db.get('mydoc', function(err, doc) {
  if (err) { return console.log(err); }
  db.put({
    title: "Sound and Vision"
  }, 'mydoc', doc._rev, function(err, response) {
    if (err) { return console.log(err); }
    // handle response
  });
});
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="updateDoc2" type="promise" %}
{% highlight js %}
db.get('mydoc').then(function(doc) {
  return db.put({
    title: "Sound and Vision"
  }, 'mydoc', doc._rev,);
}).then(function(response) {
  // handle response
}).catch(function (err) {
  console.log(err);
});
{% endhighlight %}
{% include code/end.html %}

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

The response contains the `id` of the document, the new `rev`, and an `ok` to reassure
you that everything is okay.

### Using db.post()

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

Create a new document and let PouchDB auto-generate an `_id` for it.

#### Example Usage:

{% include code/start.html id="post_doc" type="callback" %}
{% highlight js %}
db.post({
  title: 'Ziggy Stardust'
}, function (err, response) {
  if (err) { return console.log(err); }
  // handle response
});
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="post_doc" type="promise" %}
{% highlight js %}
db.post({
  title: 'Ziggy Stardust'
}).then(function (response) {
  // handle response
}).catch(function (err) {
  console.log(err);
});
{% endhighlight %}
{% include code/end.html %}

#### Example Response:
{% highlight js %}
{
  "ok" : true,
  "id" : "8A2C3761-FFD5-4770-9B8C-38C33CED300A",
  "rev" : "1-d3a8e0e5aa7c8fff0c376dac2d8a4007"
}
{% endhighlight %}

**Put vs. post**: The basic rule of thumb is: `put()` new documents with an `_id`, `post()` new documents without an `_id`.

You should also prefer `put()` to `post()`, because when you `post()`, you are missing an opportunity to use `allDocs()` to sort documents by `_id` (because your `_id`s are random). For more info, read the [PouchDB pro tips](/2014/06/17/12-pro-tips-for-better-code-with-pouchdb.html).