Breaking changes

This page documents backwards-incompatible changes made during the evolution of CouchDB. While not all such changes will necessarily affect all users, most of them probably will. This page should show you what changed and how you'll need to adapt your code.

Changes Between 0.9.x and ???

Modular Configuration Directories

CouchDB now loads configuration from the following places (glob(7) syntax) in order:

The configuration options for couchdb script have changed to: 

  -a FILE     add configuration FILE to chain
  -A DIR      add configuration DIR to chain
  -n          reset configuration file chain (including system default)
  -c          print configuration file chain and exit

Changes Between 0.8.x and 0.9.0

Response to Bulk Creation/Updates

The response to a bulk creation / update now looks like this 

[
    {"id": "0", "rev": "3682408536"},
    {"id": "1", "rev": "3206753266"},
    {"id": "2", "error": "conflict", "reason": "Document update conflict."}
]

Database File Format

The database file format has changed. CouchDB itself does yet not provide any tools for migrating your data. In the meantime, you can use third-party scripts to deal with the migration, such as the dump/load tools that come with the development version (trunk) of [WWW] couchdb-python.

If you are running a version of trunk prior to revision 753448, have a look at the BreakingChangesUpdateTrunkTo0Dot9 page.

Renamed "count" to "limit"

As of r731159 the view query API has been changed: "count" has become "limit". This is a better description of what the parameter does, and should be a simple update in any client code.

Moved View URLs

The view URLs have been moved to design document resources. This means that paths that used to be like http://hostname:5984/mydb/_view/designname/viewname?limit=10 will now look like http://hostname:5984/mydb/_design/designname/_view/viewname?limit=10. See the [WWW] REST, Hypermedia, and CouchApps thread on dev for details.

Attachments

Names of attachments are no longer allowed to start with an underscore.

Error Codes

Some refinements have been made to error handling. CouchDB will send 400 instead of 500 on invalid query parameters. Most notably, document update conflicts now respond with 409 Conflict instead of 412 Precondition Failed. The error code for when attempting to create a database that already exists is now 412 instead of 409.

ini file format

CouchDB 0.9 changes sections and configuration variable names in configuration files. Old .ini files won't work. See [WWW] local.ini for an example .ini file. Also note that CouchDB now ships with two .ini files where 0.8 used couch.ini there are now default.ini and local.ini. default.ini contains CouchDB's standard configuration values. local.ini is meant for local changes. local.ini is not overwritten on CouchDB updates, so your edits are safe. In addition, the new runtime configuration system persists changes to the configuration in local.ini.

Changes Between 0.7.x and 0.8.0

Database File Format

The database file format has changed. CouchDB itself does yet not provide any tools for migrating your data. In the meantime, you can use third-party scripts to deal with the migration, such as the dump/load tools that come with the development version (trunk) of [WWW] couchdb-python.

Migration Using the couchdb-python `dump`/`load` Tools

First, some important notes on the way these tools operate:

Note: Do not upgrade CouchDB until you've gotten your data out using the procedure described below!

Also note: Please keep backups of both the original database files and the dump files, at least until you've verified that the migration worked completely.

To use the tools, you'll have to install couchdb-python (currently from trunk), which in turn requires [WWW] Python 2.4 and the [WWW] httplib2 and [WWW] simplejson packages.

On the shell, enter the directory into which you checked out the couchdb-python code. First run to make sure the package is installed: 

  ./setup.py install

Now, to dump the contents of a particular database into a file, run the following command: 

  python couchdb/tools/dump.py http://127.0.0.1:5984/dbname > dbname.dump

Replace dbname with the name of the database to dump. This will create a file called dbname.dump in the current directory.

After you've done this for all the databases you want to migrate, you can upgrade CouchDB. You will need to completely clear the directory where CouchDB stored the old databases, as it will probably choke on files using the old format.

After the upgrade you can import all the data you previously exported. First, you'll need to create an empty database for every database dump you want to import. Then you execute the load.py script from the command-line as follows: 

  python couchdb/tools/load.py http://127.0.0.1:5984/dbname < dbname.dump

Do that for all your databases, and you should be set. Please report any bugs in those scripts [WWW] here.

Document Structure Changes

In the JSON structure for attachments, the member name content-type has been changed to content_type (note the underscore). This change was made for consistency with the general naming scheme in CouchDB, and enable easier access from Javascript code.

View Definition Changes

Views now support optional reduce. For this to work, the structure of view definitions in design documents had to change. An example is probably the best way to illustrate this: 

  {
    "_id":"_design/foo",
    "language":"javascript",
    "views": {
      "bar": {
        "map":"function... ",
        "reduce":"function..."
      }
    }
  }

Notable changes are the usage of a JSON object to define both the map and the reduce function instead of just a string for the map function. The reduce member may be omitted.

The language member is no longer a MIME type, instead, only the language name is specified. The language name maps exactly to the name chosen for a view server registration in couch.ini.

The map(key, value) function that map functions would use to produce output has been renamed to emit(key, value) to avoid confusion. 

  function(doc) {
    emit(doc.foo, doc.bar);
  }

Temporary views now need to get POSTed a JSON document with map and reduce members instead of just POSTing the raw source of the map function: 

  {
    "map":"function...",
    "reduce":"function..."
  }

Note that the language of the temporary view is no longer determined by the Content-Type header of the HTTP request. Since the definition is a JSON object, the Content-Type is always application/json. The view language is now specified via an optional language member in the JSON request body. If omitted, the language defaults to "javascript". 

  {
    "language":"javascript"
    "map":"function...",
    "reduce":"function..."
  }

HTTP API Changes

DELETE Status Code

Successful deletion of a database or document using the DELETE HTTP method now results in a 200 OK response instead of the 202 Accepted response used before. The rationale for this change is that the deletion is performed immediately, while a 202 status code implies that the action has been triggered but may not have completed at the time of the response.

Bulk Updates

The JSON structure for bulk updates has been changed slightly for both requests and responses.

For requests, you previously posted a JSON array of document rows. Now, you post a JSON object with a docs member containing that array: 

  {
    "docs": [
      {"_id": "foo", "_rev": "123456", "title": "Foo"},
      {"_id": "bar", "_rev": "234567", "title": "Bar"}
    ]
  }

Responses used to have a JSON object with a results member. Now, the response JSON structure looks as follows: 

  {
    "ok": true,
    "new_revs": [
      {"_id": "foo", "rev": "345678"},
      {"_id": "bar", "rev": "456789"}
    ]
  }

Note that bulk updates are now transactional: either all updates succeed or all fail. That's why the ok member moved to the top-level of the response.

last edited 2009-04-21 16:24:22 by NoahSlater