Breaking changes

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

Note on auto-migration: Persisted data is automatically migrated from old schemas to new schemas. In other words, a PouchDB database created in 1.x can be used in 4.x. However, you cannot downgrade once you have upgraded.

Overview

• PouchDB 5.0.0
  • Removed PouchDB.destroy(); use db.destroy() instead
  • Removed 'create', 'update', 'delete' events; use 'change' instead
  • Removed idb-alt adapter
• PouchDB 4.0.0
  • PouchDB promises: bluebird is now lie
  • Removed local_seq
  • Removed onChange and complete callbacks
  • Removed uptodate event
• PouchDB 3.0.0
  • Renamed pouchdb-nightly.js to pouchdb.js
  • Removed opts.server
  • Removed error.name; use error.status instead
• PouchDB 2.0.0
  • Removed PouchDB.allDbs()
  • Prototype-based db objects
  • Prototype-based plugins API

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