{"id":16578034,"url":"https://github.com/glynnbird/couchdeconflict","last_synced_at":"2025-08-18T06:33:26.229Z","repository":{"id":32709393,"uuid":"139971168","full_name":"glynnbird/couchdeconflict","owner":"glynnbird","description":"Command-line utility to remove conflicts from CouchDB/Cloudant documents","archived":false,"fork":false,"pushed_at":"2024-07-31T11:48:23.000Z","size":151,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-14T09:41:19.016Z","etag":null,"topics":["cli","cloudant","couchdb","database"],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/glynnbird.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}},"created_at":"2018-07-06T10:34:56.000Z","updated_at":"2024-07-31T11:48:27.000Z","dependencies_parsed_at":"2024-07-30T18:43:39.717Z","dependency_job_id":null,"html_url":"https://github.com/glynnbird/couchdeconflict","commit_stats":{"total_commits":9,"total_committers":1,"mean_commits":9.0,"dds":0.0,"last_synced_commit":"9bf54a9e3cc5e155030ea951d961af6ecaca8a34"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fcouchdeconflict","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fcouchdeconflict/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fcouchdeconflict/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fcouchdeconflict/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glynnbird","download_url":"https://codeload.github.com/glynnbird/couchdeconflict/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230210291,"owners_count":18190666,"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":["cli","cloudant","couchdb","database"],"created_at":"2024-10-11T22:12:57.221Z","updated_at":"2024-12-18T02:43:21.112Z","avatar_url":"https://github.com/glynnbird.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# couchdeconflict\n\nA command-line utility to remove conflicts from Apache CouchDB or IBM Cloudant documents. It works by fetching the document to be treated and then deleting all of the non-winning revisions with futher bulk API calls. You may choose the revision you wish to keep if the current winning revision isn't your chosen winner.\n\nThis tool is designed to \"fix\" a document that contains multiple conflicts using the *brute force* method of deleting all but one revision. This method results in the loss of data - you may wish to examine the bodies of the conflicting revisions before using this tool.\n\n## Installation\n\nThe package is installed using npm. [Node.js required](https://nodejs.org/en/download/):\n\n```sh\nnpm install -g couchdeconflict\n```\n\n## Running\n\nIf you have a the URL of the document that needs deconflicting, simply pass that to `couchdeconflict` as the `-u`/`--url` parameter:\n\n```sh\n\u003e couchdeconflict -u http://localhost:5984/mydb/mydoc\ncouchdeconflict\n---------------\noptions: {\"url\":\"http://localhost:5984/mydb/mydoc\",\"keep\":null,\"batch\":100}\nFetching document\n217 conflicts\n  [==================================================] 100% 217/217           \n217 conflicts deleted\n```\n\nYou may also supply a URL with credentials e.g. `https://U:P@host.cloudant.com/mydb/mydoc`.\n\nAlternatively, if you are using IAM authentication with IBM Cloudant, then supply an `IAM_API_KEY`  environment variable containing your IAM API KEY. Your URK (without credentials) will be supplied as the `-u`/`--url` parameter.\n\nIf you wish to keep a revision other than the current winning revision, simply pass the revision token as a `-k`/`--keep` parameter:\n\n```sh\n\u003e couchdeconflict --url http://localhost:5984/mydb/mydoc  --keep 1-111\ncouchdeconflict\n---------------\noptions: {\"url\":\"http://###:###@localhost:5984/mydb/mydoc\",\"keep\":\"1-111\",\"batch\":100}\nFetching document\n217 conflicts\nKeeping revision 1-111\n  [==================================================] 100% 217/217           \n217 conflicts deleted\n```\n\nDeletions are processed in batches of 100, although this can be overridden with the `-b`/`--batch` parameter.\n\n## Parameter Reference\n\n* `-u`/`--url` (required) - the URL of the document to treat e.g. `https://U:P@host.cloudant.com/mydb/mydoc` or `http://localhost:5984/mydb/mydoc`\n* `-k`/`--keep` - the revision token that is to be left as the winner at the end of the process. If not supplied, the current winning revision is chosen.\n* `-b`/`--batch` - the number of deletions processed per API call. Defaults to 100.\n* `-d`/`--dryrun` - output the revisions that *would* be deleted, but don't actually delete them.\n* `-v`/`--verbose` - display verbose output. Default to true\n* `--help` - display help\n* `--version` - display current version\n\n## Using programmatically\n\nYou may use this library in your own Node.js code:\n\n```js\nvar decon = require('couchdeconflict')\nvar opts = {\n  url: 'http://localhost:5984/mydb/mydoc'\n}\ndecon(opts).then((data) =\u003e {\n  console.log('Done', data)\n})\n```\n\n## What are conflicts?\n\nThis is discussed in more detail in this [three](https://developer.ibm.com/dwblog/2015/cloudant-document-conflicts-one/) [part](https://developer.ibm.com/dwblog/2015/cloudant-document-conflicts-two/) [blog](https://developer.ibm.com/dwblog/2015/cloudant-document-conflicts-three/) series, but essentially they occur when the same document is written to in different ways in separate copies of the database. This can occur when there is:\n\n- a mobile app and a server-side replica.\n- two databases that are replicated together.\n- a single, multi-node database that has mulitple writes to the same document at the same time.\n\nConflicts are not an error condition - it's just the database's way of preventing you from losing data. It is your app's responsibility to resolve them.\n\nThis tool provides a simplistic solution to fix documents that have become conflicted and need all but one revision deleting. A document with two many conflicts can cause performance problems for a database, so it's good practice to resolve them.\n\n## Making conflicts \n\nThe easiest way to create a conflicted document is to write multiple revisions with `new_edits: false` using the `POST /db/_bulk_docs` method:\n\n```sh\n# Your CouchDB/Cloudant URL goes here\nURL='http://localhost:5984/mydb'\n# Create the database\ncurl -X PUT \"$URL\"\n# JSON to create multiple revisons of the same document\nJSON='{\"new_edits\":false,\"docs\":[{\"_id\":\"mydoc\",\"_rev\":\"1-1\",\"a\":0},{\"_id\":\"mydoc\",\"_rev\":\"1-2\",\"a\":1},{\"_id\":\"mydoc\",\"_rev\":\"1-3\",\"a\":2}]}'\n# Make _bulk_docs request\ncurl -v -X POST -H 'Content-type:application/json' -d \"$JSON\" \"$URL/_bulk_docs\"\n```\n\n## Further reading\n\n- [CouchDB docs](http://docs.couchdb.org/en/2.1.1/replication/conflicts.html?highlight=conflict)\n- [The tree behind Cloudant's documents](https://dx13.co.uk/articles/2017/1/1/the-tree-behind-cloudants-documents-and-how-to-use-it.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglynnbird%2Fcouchdeconflict","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglynnbird%2Fcouchdeconflict","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglynnbird%2Fcouchdeconflict/lists"}