{"id":13555386,"url":"https://github.com/pouchdb-community/pouchdb-load","last_synced_at":"2026-03-09T08:02:04.213Z","repository":{"id":22720198,"uuid":"26064732","full_name":"pouchdb-community/pouchdb-load","owner":"pouchdb-community","description":"Load documents into CouchDB/PouchDB from a dumpfile","archived":false,"fork":false,"pushed_at":"2025-12-09T15:43:13.000Z","size":31703,"stargazers_count":122,"open_issues_count":18,"forks_count":31,"subscribers_count":5,"default_branch":"master","last_synced_at":"2026-02-19T23:53:14.509Z","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-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-11-01T22:09:12.000Z","updated_at":"2026-02-08T17:29:40.000Z","dependencies_parsed_at":"2022-09-01T11:41:00.559Z","dependency_job_id":null,"html_url":"https://github.com/pouchdb-community/pouchdb-load","commit_stats":null,"previous_names":["nolanlawson/pouchdb-load"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/pouchdb-community/pouchdb-load","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb-community%2Fpouchdb-load","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb-community%2Fpouchdb-load/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb-community%2Fpouchdb-load/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb-community%2Fpouchdb-load/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pouchdb-community","download_url":"https://codeload.github.com/pouchdb-community/pouchdb-load/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb-community%2Fpouchdb-load/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30287446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-08-01T12:03:11.072Z","updated_at":"2026-03-09T08:02:04.184Z","avatar_url":"https://github.com/pouchdb-community.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","others"],"sub_categories":[],"readme":"PouchDB Load\n=====\n\n[![Build Status](https://travis-ci.org/nolanlawson/pouchdb-load.svg)](https://travis-ci.org/nolanlawson/pouchdb-load)\n\nClient-side tools for loading a dump from a CouchDB/PouchDB database.\n\nFor dumping, check out [pouchdb-dump-cli](https://github.com/nolanlawson/pouchdb-dump-cli) to dump from the command line, or [pouchdb-replication-stream](https://github.com/nolanlawson/pouchdb-replication-stream) to dump from within your Node.js application.\n\nThis method is typically much faster than standard replication, because it uses fewer HTTP requests. So it's a great way to quickly load an initial state for your database. \n\nUsage\n--------\n\nTo use this plugin, include it after `pouchdb.js` in your HTML page:\n\n```html\n\u003cscript src=\"pouchdb.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"pouchdb.load.js\"\u003e\u003c/script\u003e\n```\n\nOr install from Bower:\n\n```\nbower install pouchdb-load\n```\n\nOr to use it in Node.js, just npm install it:\n\n```\nnpm install pouchdb-load\n```\n\nAnd then attach it to the `PouchDB` object:\n\n```js\nvar PouchDB = require('pouchdb');\nPouchDB.plugin(require('pouchdb-load'));\n```\n\nAPI\n----------\n\nThis plugin exposes a single method on your database, `load()`:\n\n### db.load(urlOrString [, options] [, callback])\n\nThis method returns a Promise or calls your callback, if you prefer the callback style.\n\nYou can give it a URL pointing to a single dump file:\n\n```js\nvar db = new PouchDB('my-awesome-db');\ndb.load('http://example.com/my-dump-file.txt').then(function () {\n  // done loading!\n}).catch(function (err) {\n  // HTTP error or something like that\n});\n```\n\nThis will read the entire file into memory, though. Assuming you used the `--split` option when you dumped your database, you can also load multiple files by using `Promise.all`. For instance, let's say you had 5 files, named \n`'my-dump-file_00000000.txt'` through `'my-dump-file_00000004.txt'`. You would do:\n\n```js\nvar dumpFiles = [\n  'my-dump-file_00000000.txt',\n  'my-dump-file_00000001.txt',\n  'my-dump-file_00000002.txt',\n  'my-dump-file_00000003.txt',\n  'my-dump-file_00000004.txt',\n];\n\nPouchDB.utils.Promise.all(dumpFiles.map(function (dumpFile) {\n  return db.load('http://example.com/' + dumpFile);\n})).then(function () {\n  // done loading!\n}).catch(function (err) {\n  // HTTP error or something like that\n});\n```\n\nThis will load them all simultaneously. You can also load them all in a series:\n\n```js\nvar series = PouchDB.utils.Promise.resolve();\n\ndumpFiles.forEach(function (dumpFile) {\n  series = series.then(function () {\n    return db.load('http://example.com/' + dumpFile);\n  });\n});\n\nseries.then(function () {\n  // done loading!\n}).catch(function (err) {\n  // HTTP error or something like that\n});\n```\n\n#### Loading from a string rather than a URL\n\nInstead of a URL, you can also load directly from a string. This is useful if you used [`pouchdb-replication-stream`](https://github.com/nolanlawson/pouchdb-replication-stream) to dump directly to a string, or if you are loading your dumpfile through some other mechanism than ajax (websockets, WebRTC, etc.):\n\n```js\nvar db = new PouchDB('my-awesome-db');\nvar myDumpedString = getDumpedStringSomehow();\n\ndb.load(myDumpedString).then(function () {\n  // done loading!\n}).catch(function (err) {\n  // any possible errors\n});\n```\n\n#### Handoff to regular replication\n\nNormally the `load()` operation doesn't write any *checkpoints*, meaning that if you switch from `load()` to normal replication, then it will start reading all the changes from the remote CouchDB from the beginning of time. This is slow, so to avoid it, use the `proxy` option:\n\n```js\ndb.load('http://example.com/my-dump-file.txt', {\n  proxy: 'http://mysite.com/mydb'\n}).then(function () {\n  // done loading! handoff to regular replication\n  return db.replicate.from('http://mysite.com/mydb');\n}).catch(function (err) {\n  // HTTP error or something like that\n});\n```\n\nThis will tell the plugin that the dumpfile `'http://example.com/my-dump-file.txt'` is just a proxy for `'http://mysite.com/mydb'`. So when you pick up replication again, it won't start from 0 but rather will start from the last checkpoint reported by the dump file.\n\nIf your replication also involves a `filter` function, you should pass that in as `filter` as well (so that the correct checkpoint can be written):\n\n```js\nfunction filterFun(doc) {\n  /* your cool filter function here */ \n}\n\ndb.load('http://example.com/my-dump-file.txt', {\n  proxy: 'http://mysite.com/mydb',\n  filter: filterFun\n}).then(function () {\n  // done loading! handoff to regular replication\n  return db.replicate.from('http://mysite.com/mydb', {filter: filterFun});\n}).catch(function (err) {\n  // HTTP error or something like that\n});\n```\n\nThe same goes for `view` and `query_params`.\n\n#### Custom ajax options\n\nYou can also include ajax options in the `options`:\n\n```js\ndb.load('myfile.txt', {\n  ajax: {\n    timeout: 30000\n  }\n});\n```\n\nThe ajax options themselves are described in [the PouchDB documentation](http://pouchdb.com/api.html#create_database).\n\n#### Live demo\n\n[NPM Browser](http://npm-browser.com) uses pouchdb-load to load a bunch of static files from Amazon S3, which is how it's able to replicate all of NPM so quickly. Here is [the relevant code](https://github.com/pouchdb/npm-browser/blob/c16ada690be45df0af80336aedd69f308d3f105b/scripts/services/pouch-service.js#L72-L108), which does the dump, checkpointing, and handoff to regular replication (as described above).\n\n#### Notes on idempotency\n\nThe `load()` operation is *idempotent*, meaning that you can run it over and over again, and it won't create duplicate documents in the target database.\n\nHowever, it's inefficient to run the `load()` every time the user starts your app. So if you'd like, you can use \"local documents\" to remember whether or not this database has already been loaded:\n\n```js\ndb.get('_local/initial_load_complete').catch(function (err) {\n  if (err.status !== 404) { // 404 means not found\n    throw err;\n  }\n  db.load(/* ... */).then(function () {\n    return db.put({_id: '_local/initial_load_complete'});\n  });\n}).then(function () {\n  // at this point, we are sure that \n  // initial replication is complete\n}).catch(function (err) {\n  // handle unexpected errors\n});\n```\n\nThis code first checks for a local document called `'_local/initial_load_complete'`. If the document is not found, then it calls `dump()`, then puts the local doc to mark that it's complete. Else it finishes.\n\n(*Local documents* are non-replicated PouchDB/CouchDB documents that are useful for storing local state or configuration files. To create a local document, you simply prefix `'_local/'` to the document `_id`.)\n\nBuilding\n----\n    npm install\n    npm run build\n\nTesting\n----\n\n### In Node\n\nThis will run the tests in Node using LevelDB:\n\n    npm test\n    \nYou can also check for 100% code coverage using:\n\n    npm run coverage\n\n### Automated browser tests with Playwright\n\n- Run `npm run dev-server` \n- On another console, run `npm run test-browser-playwright`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpouchdb-community%2Fpouchdb-load","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpouchdb-community%2Fpouchdb-load","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpouchdb-community%2Fpouchdb-load/lists"}