pouchdb-server

A standalone REST interface server for PouchDB.

Introduction

pouchdb-server is a simple Node.js server that presents a simple REST API, which mimics that of CouchDB, on top of PouchDB. Among other things, this allows users to replicate IndexedDB stores to LevelDB, or to spin up a quick and dirty drop-in replacement for CouchDB to get things moving quickly.

Installation

$ npm install -g pouchdb-server

Usage

Usage: pouchdb-server [options]

Options:
   -p, --port             Port on which to run the server. (Defaults to
                          /_config/httpd/port which defaults to 5984).
   -d, --dir              Where to store database files. (Defaults to
                          /_config/couchdb/database_dir which defaults to the
                          current directory).
   -c, --config           The location of the configuration file that backs
                          /_config. (Defaults to ./config.json).
   -o, --host             The address to bind the server to. (Defaults to
                          /_config/httpd/bind_address which defaults to
                          127.0.0.1).
   -m, --in-memory        Use a pure in-memory database which will be deleted
                          upon restart. (Defaults to
                          /_config/pouchdb_server/in_memory which defaults to
                          false).
   --sqlite               Use PouchDB over SQLite instead of LevelDOWN.
                          (Defaults to /_config/pouchdb_server/sqlite which
                          defaults to false).
   -r, --proxy            Proxy requests to the specified host. Include a
                          trailing '/'. (Defaults to
                          /_config/pouchdb_server/proxy which defaults to
                          undefined).
   -n, --no-stdout-logs   Stops the log file from also being written to stdout.
                          (Defaults to /_config/pouchdb_server/no-stdout-logs
                          which defaults to false).
   --no-color             Disable coloring of logging output.
   --level-backend        Advanced - Alternate LevelDOWN backend (e.g. memdown,
                          riakdown, redisdown). Note that you'll need to
                          manually npm install it first. (Defaults to
                          /_config/pouchdb_server/level_backend which defaults
                          to undefined).
   --level-prefix         Advanced - Prefix to use for all database names,
                          useful for URLs in alternate backends, e.g.
                          riak://localhost:8087/ for riakdown. (Defaults to
                          /_config/pouchdb_server/level_prefix which defaults
                          to undefined).

Examples:

  pouchdb-server --level-backend riakdown --level-prefix riak://localhost:8087
  Starts up a pouchdb-server that talks to Riak.
  Requires: npm install riakdown

  pouchdb-server --level-backend redisdown
  Starts up a pouchdb-server that talks to Redis, on localhost:6379.
  Requires: npm install redisdown

  pouchdb-server --level-backend sqldown --level-prefix /tmp/
  Starts up a pouchdb-server using SQLite, with files stored in /tmp/.
  Requires: npm install sqldown sqlite3

A simple example might be,

$ pouchdb-server -p 15984
pouchdb-server listening on port 15984.

Alternatively, pouchdb-server's functionality can be mounted into other Express web apps. For more information on that, check out express-pouchdb.

Fauxton

pouchdb-server currently supports an experimental version of CouchDB's Fauxton. Fauxton, the successor to CouchDB's original Futon, is a simple web UI for interacting with your databases. With your server running, navigate to /_utils to check it out!

Configuration

By default, you can configure pouchdb-server using a config.json file, which is typically expected at the root of wherever you run pouchdb-server, but may be specified with the --config option.

Below are some examples of config.json options:

log.level

To change the log output level, you can create a config.json file containing e.g.:

{
  "log": {
    "level": "none"
  }
}

The available values are debug, info, warning, error, and none. The default is info.

log.file

To choose the file where logs are written, you can create a config.json file containing e.g.:

{
  "log": {
    "file": "/path/to/log.txt"
  }
}

By default, logs are written to ./log.txt.

Automatic port configuration

Due to conventions set by Heroku and others, if you have a PORT environment variable, pouchdb-server will pick up on that and use it instead of 5984 as the default.

export PORT=3000
pouchdb-server # will run on port 3000

Testing

One of the primary benefits of pouchdb-server is the ability to run PouchDB's Node test suite against itself. To do that, you can simply,

$ npm run test-pouchdb

Whatever args you provide as SERVER_ARGS will be passed to pouchdb-server itself:

$ SERVER_ARGS='--in-memory' npm run test-pouchdb

Or to test in Firefox (IndexedDB):

$ CLIENT=selenium:firefox npm run test-pouchdb

Or to test in PhantomJS (WebSQL):

$ CLIENT=selenium:phantomjs ES5_SHIM=true npm run test-pouchdb

Additionally, we've started porting CouchDB's JavaScript test harness to a simple Node module, which can be run against PouchDB via pouchdb-server.

$ npm run test-couchdb

Contributing

Want to help me make this thing awesome? Great! Here's how you should get started.

1. First, make sure that the bugfix or feature you're looking to implement isn't better fit for express-pouchdb.
2. PouchDB is still developing rapidly. If you need bleeding egde versions, you should first read how to set up express-pouchdb for local development. (Make sure that, afterwards, you npm link express-pouchdb).
3. Go ahead and fork pouchdb-server, clone it to your machine.
4. Now you'll want to, from the root of pouchdb-server, npm link express-pouchdb.
5. npm install the rest of the dependencies.

Please make your changes on a separate branch whose name reflects your changes, push them to your fork, and open a pull request!

For commit message style guidelines, please refer to PouchDB CONTRIBUTING.md.

Contributors

These people made pouchdb-server into what it is today!

License

The MIT License. See the LICENSE file for more information.