Breaking changes

PouchDB follows semantic versioning. Major version releases indicate breaking changes.

Migrations: PouchDB does automatic schema migrations, even across major versions. In other words, a PouchDB database that was written to disk using 1.x can also be opened with 6.x. However, you cannot downgrade once you have upgraded.

Overview

• PouchDB 6.0.0 (blog post)
  • Removed db.put(doc, id, rev), use db.put({_id: id, _rev: rev, data: 'foo'}) instead
  • Removed new PouchDB(dbName).then and new PouchDB(dbName, callback), use db.info() instead to check for initialization errors
  • Removed SQLite Plugin support, use pouchdb-adapter-cordova-sqlite instead
  • Removed extras API, use custom builds instead
  • Removed getUrl(), getHeaders(), use db.name instead
  • Removed node-websql, use pouchdb-adapter-node-websql instead
  • Removed optional dependencies, use custom builds instead
  • View and filter functions are now executed in strict mode, use strict mode
  • PouchDB.utils (non-standard undocumented API) was removed in 5.4.0. Use custom builds instead
• PouchDB 5.0.0 (blog post)
  • Removed PouchDB.destroy(); use db.destroy() instead
  • Removed 'create', 'update', 'delete' events; use 'change' instead
  • Removed idb-alt adapter
• PouchDB 4.0.0 (blog post)
  • PouchDB promises: bluebird is now lie
  • Removed local_seq
  • Removed onChange and complete callbacks
  • Removed uptodate event
• PouchDB 3.0.0 (blog post)
  • Renamed pouchdb-nightly.js to pouchdb.js
  • Removed opts.server
  • Removed error.name; use error.status instead
• PouchDB 2.0.0 (blog post)
  • Removed PouchDB.allDbs()
  • Prototype-based db objects
  • Prototype-based plugins API

PouchDB 6.0.0

See blog post for details.

PouchDB 5.0.0

• Remove PouchDB.destroy() (#4223)

Having a destroy() function on the PouchDB object was always a little awkward, which is why we introduced the db.destroy() alternative. So now that PouchDB.destroy() is out, upgrading your code should look like this:

PouchDB.destroy('mydb');

becomes:

new PouchDB('mydb').destroy();

Keep in mind that the PouchDB object is no longer usable after you destroy() it. So you should call new PouchDB() again if you want to re-use it.

• Remove CRUD events (#4224)

These events ('create', 'update', and 'delete') were intended to make the changes() API easier to work with, but they ended up being too ambitious and confusing, so 5.0.0 removes them.

If you are relying on these events, then you can upgrade like so:

db.changes({live: true})
  .on('create', createListener)
  .on('update', updateListener)
  .on('delete', deleteListener);

becomes:

db.changes({live: true})
  .on('change', function (change) {
    if (change.deleted) {
      deleteListener(change);
    } else if (change.changes.length === 1 &&
               /^1-/.test(change.changes[0].rev)) {
      createListener(change);
    } else {
      updateListener(change);
    }
  });

Keep in mind that this "update vs. create" test is not foolproof (what happens if a 2- document is the first version that gets synced? what happens if two conflicting 1- revisions are synced?), but it will match the old behavior.

Most of the time, your UI should be able to handle document "updates" or "creates" equivalently, so change.deleted becomes the only special case. See Efficiently managing UI state with PouchDB for some details about how to do this.

• Remove idb-alt plugin (#4222)

This was an alternative IndexedDB adapter based on Level.js, which was experimental and probably unused by anyone except the PouchDB developers themselves.

PouchDB 4.0.0

• Removed bluebird and used lie as only Promise polyfill - (#3839)

We previously used bluebird as our Promise polyfill in node.js because it is a fast library. However bluebird contains a lot of non-standard Promise functionality, which authors could use and then have their code break in browsers as well as iojs and future versions of node.js, which have introduced a standard Promise implementation.

PouchDB will always use the globally available Promise object where available, so if you have only used standard Promise functionality, this change will not break anything. If you require the extra functionality provided by bluebird, then you can have PouchDB use it with

global.Promise = require('bluebird');

• Removed local_seq - (#4080)

This was a little-used functionality whose semantics are due to change in CouchDB 2.0.

• Removed onChange and complete callbacks - (#4098)

These callbacks have long been replaced with the EventEmitter-style changes(), replicate() and sync() APIs, and are finally being removed. If you still have:

db.changes({
  onChange: changeFun,
  complete: completeFun
});

You can replace them with:

db.changes()
  .on('change', changeFun)
  .on('complete', completeFun);

• Removed uptodate event - (#4100)

uptodate was an event introduced to indicate when a live replication had finished processing all current changes and was waiting on future changes. It has since been replaced by the paused event, which will do the same and additionally indicate whether the replication was paused due to an error. If you have:

replication.on('uptodate', doneFun);

You can replace it with:

replication.on('paused', doneFun);

PouchDB 3.0.0

• The browser build pouchdb-nightly.js has been renamed to pouchdb.js. It was never really a nightly anyway. (#2146)
• opts.server has been deprecated from the replicate() and sync() APIs. You can still replicate from one HTTP server to another, but the data will flow through PouchDB rather than being server-initiated. (#2313)
• You can no longer rely on errors to have an identifying name. Instead, rely on CouchDB-centric errors to have a status (i.e. err.status instead of err.name). There are some that still have an identifying name, but these could be removed at any time. The upside of this is that stack traces should be more consistently helpful. (#2545)

Release blog post

PouchDB 2.0.0

• Removed PouchDB.allDbs() (available as a plugin instead) #1352
• Prototype-based db objects. This means that var get = db.get will blow up, so write var get = db.get.bind(db) instead. #1150
• Prototype-based plugins API. Ditto for plugins. #1387

Release blog post