{"id":13431752,"url":"https://github.com/pouchdb/pouchdb-server","last_synced_at":"2025-05-14T19:02:57.399Z","repository":{"id":6716384,"uuid":"7962111","full_name":"pouchdb/pouchdb-server","owner":"pouchdb","description":"CouchDB-compatible server built on PouchDB and Node","archived":false,"fork":false,"pushed_at":"2023-04-06T06:50:26.000Z","size":4170,"stargazers_count":965,"open_issues_count":149,"forks_count":154,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-03-31T08:03:01.934Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pouchdb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2013-02-01T17:04:19.000Z","updated_at":"2025-03-16T06:37:31.000Z","dependencies_parsed_at":"2024-01-14T20:17:54.530Z","dependency_job_id":"8daa5116-0286-4052-bfc1-54493075fbef","html_url":"https://github.com/pouchdb/pouchdb-server","commit_stats":{"total_commits":948,"total_committers":58,"mean_commits":"16.344827586206897","dds":0.6740506329113924,"last_synced_commit":"975ea2377957223dc828bcdb4f5d403a5cc9f709"},"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb%2Fpouchdb-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb%2Fpouchdb-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb%2Fpouchdb-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb%2Fpouchdb-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pouchdb","download_url":"https://codeload.github.com/pouchdb/pouchdb-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353729,"owners_count":20925329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T02:01:05.607Z","updated_at":"2025-04-08T06:30:16.055Z","avatar_url":"https://github.com/pouchdb.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","others"],"sub_categories":[],"readme":"PouchDB Server [![Build Status](https://travis-ci.org/pouchdb/pouchdb-server.svg)](https://travis-ci.org/pouchdb/pouchdb-server) [![Greenkeeper badge](https://badges.greenkeeper.io/pouchdb/pouchdb-server.svg)](https://greenkeeper.io/)\n=====\n\nPouchDB Server is a drop-in replacement for CouchDB, using PouchDB and\nNode.js. It is modeled after the single-node design of CouchDB 1.x,\nalthough it contains some CouchDB 2.x features such as\n[Mango queries](http://github.com/nolanlawson/pouchdb-find).\n\nPouchDB Server is much less battle-tested than CouchDB, but it does pass the full [PouchDB test suite](https://github.com/pouchdb/pouchdb/tree/master/tests).\n\n_For the `express-pouchdb` sub-package, skip to [express-pouchdb](#express-pouchdb)._\n\nThis git repository is a [monorepo](https://github.com/babel/babel/blob/master/doc/design/monorepo.md), and is the source for many [pouchdb npm packages](https://github.com/pouchdb/pouchdb-server/tree/master/packages/node_modules).\n\nFor information about interacting with a PouchDB, see https://pouchdb.com/.\n\nUsage\n---\n\nInstall:\n\n    npm install -g pouchdb-server\n\nThen run:\n\n    pouchdb-server\n\nNow you can view the [Fauxton](https://github.com/apache/couchdb-fauxton) web\ninterface by opening `http://localhost:5984/_utils` in a browser.  \n\n### Basic options\n\nPouchDB Server's default port is 5984. To change it:\n\n    pouchdb-server --port 3000\n\nBy default, all files are written in the current directory. To use another one:\n\n    pouchdb-server --dir path/to/my/directory\n\nPouchDB Server can run fully in-memory (no changes are saved):\n\n    pouchdb-server --in-memory\n\nOr it can run using SQLite rather than LevelDB:\n\n    pouchdb-server --sqlite\n\n### Full options\n\nMost PouchDB Server options are available via the command line:\n\n```\nUsage: pouchdb-server [options]\n\nOptions:\n   -p, --port             Port on which to run the server. (Defaults to\n                          /_config/httpd/port which defaults to 5984).\n   -d, --dir              Where to store database files. (Defaults to\n                          /_config/couchdb/database_dir which defaults to the\n                          current directory).\n   -c, --config           The location of the configuration file that backs\n                          /_config. (Defaults to ./config.json).\n   -o, --host             The address to bind the server to. (Defaults to\n                          /_config/httpd/bind_address which defaults to\n                          127.0.0.1).\n   -m, --in-memory        Use a pure in-memory database which will be deleted\n                          upon restart. (Defaults to\n                          /_config/pouchdb_server/in_memory which defaults to\n                          false).\n   --sqlite               Use PouchDB over SQLite instead of LevelDOWN.\n                          (Defaults to /_config/pouchdb_server/sqlite which\n                          defaults to false).\n   -r, --proxy            Proxy requests to the specified host. Include a\n                          trailing '/'. (Defaults to\n                          /_config/pouchdb_server/proxy which defaults to\n                          undefined).\n   -n, --no-stdout-logs   Stops the log file from also being written to stdout.\n                          (Defaults to /_config/pouchdb_server/no-stdout-logs\n                          which defaults to false).\n   --no-color             Disable coloring of logging output.\n   --level-backend        Advanced - Alternate LevelDOWN backend (e.g. memdown,\n                          riakdown, redisdown). Note that you'll need to\n                          manually npm install it first. (Defaults to\n                          /_config/pouchdb_server/level_backend which defaults\n                          to undefined).\n   --level-prefix         Advanced - Prefix to use for all database names,\n                          useful for URLs in alternate backends, e.g.\n                          riak://localhost:8087/ for riakdown. (Defaults to\n                          /_config/pouchdb_server/level_prefix which defaults\n                          to undefined).\n\nExamples:\n\n  pouchdb-server --level-backend riakdown --level-prefix riak://localhost:8087\n  Starts up a pouchdb-server that talks to Riak.\n  Requires: npm install riakdown\n\n  pouchdb-server --level-backend redisdown\n  Starts up a pouchdb-server that talks to Redis, on localhost:6379.\n  Requires: npm install redisdown\n\n  pouchdb-server --level-backend sqldown --level-prefix /tmp/\n  Starts up a pouchdb-server using SQLite, with files stored in /tmp/.\n  Requires: npm install sqldown sqlite3\n```\n\n### Configuration\n\nBy default, you can configure PouchDB Server using a `config.json` file, which is\ntypically expected at the root of wherever you run it, but may be specified with the `--config` option.\n\nBelow are some examples of `config.json` options:\n\n#### log.level\n\nTo change the log output level, you can create a `config.json` file containing e.g.:\n\n```json\n{\n  \"log\": {\n    \"level\": \"none\"\n  }\n}\n```\n\nThe available values are `debug`, `info`, `warning`, `error`, and `none`. The default\nis `info`.\n\n#### log.file\n\nTo choose the file where logs are written, you can create a `config.json` file containing e.g.:\n\n```json\n{\n  \"log\": {\n    \"file\": \"/path/to/log.txt\"\n  }\n}\n```\n\nBy default, logs are written to `./log.txt`.\n\n### Automatic port configuration\n\nDue to conventions set by Heroku and others, if you have a `PORT` environment variable,\n`pouchdb-server` will pick up on that and use it instead of `5984` as the default.\n\n```bash\nexport PORT=3000\npouchdb-server # will run on port 3000\n```\n\nexpress-pouchdb\n-----\n\nThe `express-pouchdb` module is a fully qualified [Express](http://expressjs.com/) application with routing defined to\nmimic most of the [CouchDB](http://couchdb.apache.org/) REST API, and whose behavior is handled by\n[PouchDB](http://pouchdb.com/).\n\nThe intention is for `express-pouchdb` to be mounted into Express apps for\nextended usability. A simple example of this is\n[pouchdb-server](https://github.com/pouchdb/pouchdb-server) itself.\n\n### Usage\n\nInstall the necessary packages:\n\n    npm install express-pouchdb pouchdb express\n\nNow here's a sample Express app, which we'll name `app.js`.\n\n```js\nvar PouchDB = require('pouchdb');\nvar express = require('express');\nvar app = express();\n\napp.use('/db', require('express-pouchdb')(PouchDB));\n\napp.listen(3000);\n```\n\nNow we can run this script and find each of `express-pouchdb`'s routes\nat the `/db` path:\n\n    node app.js \u0026\n    curl localhost:3000/db\n\nYou should see:\n\n```json\n{\n    \"express-pouchdb\": \"Welcome!\",\n    \"uuid\": \"c0da32be-957f-4934-861f-d1e3ed10e544\",\n    \"vendor\": {\n        \"name\": \"PouchDB authors\",\n        \"version\": \"2.2.6\"\n    },\n    \"version\": \"2.2.6\"\n}\n```\n\n*Note:* `express-pouchdb` conflicts with some middleware. You can work\naround this by only enabling affected middleware for routes not handled\nby `express-pouchdb`. [body-parser](https://www.npmjs.com/package/body-parser)\nis the most important middleware known to be problematic.\n\n#### API\n\n`express-pouchdb` exports a single function that builds an express [application object](http://expressjs.com/4x/api.html#application). Its function signature is:\n\n``require('express-pouchdb')([PouchDB[, options]])``\n- ``PouchDB``: the PouchDB object used to access databases. Optional.\n- ``options``: Optional. These options are supported:\n - ``configPath``: a path to the configuration file to use. Defaults to './config.json'.\n - ``logPath``: a path to the log file to use. Defaults to './log.txt'.\n - ``inMemoryConfig``: `true` if all configuration should be in-memory. Defaults to `false`.\n - ``mode``: determines which parts of the HTTP API express-pouchdb offers are enabled. There are three values:\n   - ``'fullCouchDB'``: enables every part of the HTTP API, which makes express-pouchdb very close to a full CouchDB replacement. This is the default.\n    - ``'minimumForPouchDB'``: just exposes parts of the HTTP API that map 1-1 to the PouchDB api. This is the minimum required to make the PouchDB test suite run, and a nice start when you just need an HTTP API to replicate with.\n    - ``'custom'``: no parts of the HTTP API are enabled. You can add parts yourself using the ``opts.overrideMode`` discussed below.\n  - ``overrideMode``: Sometimes the preprogrammed modes are insufficient for your needs, or you chose the ``'custom'`` mode. In that case, you can set this to an object. This object can have the following properties:\n    - ``'include'``: a javascript array that specifies parts to include on top of the ones specified by ``opts.mode``. Optional.\n    - ``'exclude'``: a javascript array that specifies parts to exclude from the ones specified by ``opts.mode``. Optional.\n\nThe application object returned contains some extra properties that\noffer additional functionality compared to an ordinary express\napplication:\n\n- ``setPouchDB``: a function that allows changing the ``PouchDB`` object `express-pouchdb` uses on the fly. Takes one argument: the new ``PouchDB`` object to use.\n- ``couchConfig``: an object that provides programmatic access to the configuration file and HTTP API express-pouchdb offers. For an overview of available configuration options, take a look at Fauxton's configuration page. (``/_utils#_config``)\n- ``couchLogger``: an object that provides programmatic access to the log file and HTTP API `express-pouchdb` offers.\n\n#### Examples\n\n##### Example 1\n\nBuilds an HTTP API that exposes a minimal HTTP interface, but adds\nFauxton as a debugging tool.\n\n```javascript\nvar app = require('express-pouchdb')({\n  mode: 'minimumForPouchDB',\n  overrideMode: {\n    include: ['routes/fauxton']\n  }\n});\n// when not specifying PouchDB as an argument to the main function, you\n// need to specify it like this before requests are routed to ``app``\napp.setPouchDB(require('pouchdb'));\n```\n\n##### Example 2\n\nbuilds a full HTTP API but excludes express-pouchdb's authentication\nlogic (say, because it interferes with custom authentication logic used\nin our own express app):\n\n```javascript\nvar app2 = require('express-pouchdb')(require('pouchdb'), {\n  mode: 'fullCouchDB', // specified for clarity. It's the default so not necessary.\n  overrideMode: {\n    exclude: [\n      'routes/authentication',\n      // disabling the above, gives error messages which require you to disable the\n      // following parts too. Which makes sense since they depend on it.\n      'routes/authorization',\n      'routes/session'\n    ]\n  }\n});\n```\n\n#### Using your own PouchDB\n\nSince you pass in the `PouchDB` that you would like to use with\n`express-pouchdb`, you can drop `express-pouchdb` into an existing Node-based\nPouchDB application and get all the benefits of the HTTP interface\nwithout having to change your code.\n\n```js\nvar express = require('express')\n  , app     = express()\n  , PouchDB = require('pouchdb');\n\napp.use('/db', require('express-pouchdb')(PouchDB));\n\nvar myPouch = new PouchDB('foo');\n\n// myPouch is now modifiable in your own code, and it's also\n// available via HTTP at /db/foo\n```\n\n#### PouchDB defaults\n\nWhen you use your own PouchDB code in tandem with `express-pouchdb`, the `PouchDB.defaults()` API can be very convenient for specifying some default settings for how PouchDB databases are created.\n\nFor instance, if you want to use an in-memory [MemDOWN](https://github.com/rvagg/memdown)-backed pouch, you can simply do:\n\n```js\nvar InMemPouchDB = PouchDB.defaults({db: require('memdown')});\n\napp.use('/db', require('express-pouchdb')(InMemPouchDB));\n\nvar myPouch = new InMemPouchDB('foo');\n```\n\nSimilarly, if you want to place all database files in a folder other than the `pwd`, you can do:\n\n```js\nvar TempPouchDB = PouchDB.defaults({prefix: '/tmp/my-temp-pouch/'});\n\napp.use('/db', require('express-pouchdb')(TempPouchDB));\n\nvar myPouch = new TempPouchDB('foo');\n```\n\nIf you want express-pouchdb to proxy requests to another CouchDB-style\nHTTP API, you can use [http-pouchdb](https://www.npmjs.com/package/http-pouchdb):\n\n```javascript\nvar TempPouchDB = require('http-pouchdb')(PouchDB, 'http://localhost:5984');\napp.use('/db', require('express-pouchdb')(TempPouchDB));\n```\n\n#### Functionality\n\nOn top of the exposing everything PouchDB offers through a CouchDB-like\ninterface, `express-pouchdb` also offers the following extra\nfunctionality found in CouchDB but not in PouchDB by default (depending\non the mode used, of course):\n\n- [Fauxton][], a web interface for the HTTP API.\n- [Authentication][] and [authorisation][] support. HTTP basic\n  authentication and cookie authentication are available. Authorisation\n  is handled by [validation functions][] and [security documents][].\n- [Configuration][] support. You can modify configuration values\n  manually in the `config.json` file, or use the HTTP or Fauxton\n  interface.\n- [Replicator database][] support. This allows your replications to\n  persist past a restart of your application.\n- Support for [show][], [list][] and [update][] functions. These allow\n  you to serve non-json content straight from your database.\n- [Rewrite][] and [Virtual Host][] support, for nicer urls.\n\n[fauxton]:              https://www.npmjs.com/package/fauxton\n[authentication]:       http://docs.couchdb.org/en/latest/intro/security.html\n[authorisation]:        http://docs.couchdb.org/en/latest/intro/overview.html#security-and-validation\n[validation functions]: http://docs.couchdb.org/en/latest/couchapp/ddocs.html#vdufun\n[security documents]:   http://docs.couchdb.org/en/latest/api/database/security.html\n[configuration]:        http://docs.couchdb.org/en/latest/config/intro.html#setting-parameters-via-the-http-api\n[replicator database]:  http://docs.couchdb.org/en/latest/replication/replicator.html\n[show]:                 http://guide.couchdb.org/editions/1/en/show.html\n[list]:                 http://guide.couchdb.org/editions/1/en/transforming.html\n[update]:               http://docs.couchdb.org/en/latest/couchapp/ddocs.html#update-functions\n[rewrite]:              http://docs.couchdb.org/en/latest/api/ddoc/rewrites.html\n[virtual host]:         http://docs.couchdb.org/en/latest/config/http.html#vhosts\n\nGetting Help\n------------\n\nThe PouchDB community is active [on Slack](http://slack.pouchdb.com/), [on Freenode IRC](https://www.irccloud.com/invite?channel=pouchdb\u0026hostname=irc.freenode.net\u0026port=6697\u0026ssl=1), [Slack](http://slack.pouchdb.com),in [the Google Groups mailing list](https://groups.google.com/forum/#!forum/pouchdb), and [on StackOverflow](http://stackoverflow.com/questions/tagged/pouchdb). Or you can [tweet @pouchdb](http://twitter.com/pouchdb)!\n\nIf you think you've found a bug in PouchDB, please write a reproducible test case and file [a Github issue](https://github.com/pouchdb/pouchdb/issues). We recommend [bl.ocks.org](http://bl.ocks.org/) for code snippets, because some iframe-based services like JSFiddle and JSBin do not support IndexedDB in all browsers. You can start with [this template](https://gist.github.com/nolanlawson/816f138a51b86785d3e6).\n\n## Contributing\n\nSee the [CONTRIBUTING.md](https://github.com/pouchdb/pouchdb-server/blob/master/CONTRIBUTING.md) file for how to get involved.\n\n## Contributors\n\n[These people](https://github.com/pouchdb/pouchdb-server/graphs/contributors) made PouchDB Server into what it is today!\n\n## Changelog\n\n`pouchdb-server` and `express-pouchdb` follow [semantic versioning](http://semver.org/). To see a changelog with all releases since v2.0.0, check out the [Github releases page](https://github.com/pouchdb/pouchdb-server/releases).\n\n## License\n\nThe Apache 2 License. See [the LICENSE file](https://github.com/pouchdb/pouchdb-server/blob/master/LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpouchdb%2Fpouchdb-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpouchdb%2Fpouchdb-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpouchdb%2Fpouchdb-server/lists"}