{"id":16578036,"url":"https://github.com/glynnbird/couchbackup","last_synced_at":"2025-03-21T12:32:04.042Z","repository":{"id":29644617,"uuid":"33186106","full_name":"glynnbird/couchbackup","owner":"glynnbird","description":"CouchDB backup and restore command-line utility.","archived":false,"fork":false,"pushed_at":"2020-03-13T20:41:28.000Z","size":53,"stargazers_count":14,"open_issues_count":12,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-12T22:12:53.685Z","etag":null,"topics":["backup","cloudant","command-line","couchdb","javascript","utility"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"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":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-31T13:11:03.000Z","updated_at":"2022-08-06T11:42:20.000Z","dependencies_parsed_at":"2022-08-26T22:51:54.506Z","dependency_job_id":null,"html_url":"https://github.com/glynnbird/couchbackup","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fcouchbackup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fcouchbackup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fcouchbackup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fcouchbackup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glynnbird","download_url":"https://codeload.github.com/glynnbird/couchbackup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221815219,"owners_count":16885143,"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":["backup","cloudant","command-line","couchdb","javascript","utility"],"created_at":"2024-10-11T22:12:57.276Z","updated_at":"2024-10-28T10:08:45.791Z","avatar_url":"https://github.com/glynnbird.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CouchBackup (deprecated)\n\n# PLEASE USE [@cloudant/couchbackup](https://www.npmjs.com/package/@cloudant/couchbackup) INSTEAD\n\n[![Build Status](https://travis-ci.org/glynnbird/couchbackup.svg?branch=master)](https://travis-ci.org/glynnbird/couchbackup)\n\n```\n _____                  _    ______            _                \n/  __ \\                | |   | ___ \\          | |               \n| /  \\/ ___  _   _  ___| |__ | |_/ / __ _  ___| | ___   _ _ __  \n| |    / _ \\| | | |/ __| '_ \\| ___ \\/ _` |/ __| |/ / | | | '_ \\ \n| \\__/\\ (_) | |_| | (__| | | | |_/ / (_| | (__|   \u003c| |_| | |_) |\n \\____/\\___/ \\__,_|\\___|_| |_\\____/ \\__,_|\\___|_|\\_\\\\__,_| .__/ \n                                                         | |    \n                                                         |_|    \n```\n\nCouchBackup is a command-line utility that allows a CouchDB database to be backed-up to a text file. \nIt comes with a companion command-line utility that can restore the backed up data.\n\n** N.B. couchbackup does not do CouchDB replication as such, it simply streams through a database's _changes feed, and uses `POST /db/_bulk_get` to fetch the documents, storing the documents it finds on disk. **\n\n## Installation\n\nTo install use npm:\n\n    npm install -g couchbackup\n\n## Usage\n\nEither environment variables or command-line options can be used to specify the URL of the CouchDB or Cloudant instance, and the database to work with.\n\n### The URL\n\nTo define the URL of the CouchDB instance set the COUCH_URL environment variable:\n\n    export COUCH_URL=http://localhost:5984\n\nor\n\n    export COUCH_URL=https://myusername:mypassword@myhost.cloudant.com\n\nAlternatively we can use the `--url` command-line parameter.\n\n### The Database name\n\nTo define the name of the database to backup or restore, set the COUCH_DATABASE environment variable:\n\n    export COUCH_DATABASE=animals\n\nAlternatively we can use the `--db` command-line parameter\n\n## Backup\n\nTo backup a database to a text file, use the `couchbackup` command, directing the output to a text file:\n\n    couchbackup \u003e backup.txt\n\nAnother way of backing up is to set the COUCH_URL environment variable only and supply the database name on the command-line:\n\n    couchbackup --db animals \u003e animals.txt\n  \n## Logging \u0026 resuming backups\n\nYou may also create a log file which records the progress of the backup with the `--log` parameter e.g.\n\n    couchbackup --db animals --log animals.log \u003e animals.txt\n\nThis log file can be used to resume backups from where you left off with `--resume true`:\n\n    couchbackup --db animals --log animals.log --resume true \u003e\u003e animals.txt\n\nYou may also specify the name of the output file, rather than directing the backup data to *stdout*:\n\n    couchbackup --db animals --log animals.log --resume true --output animals.txt\n\n## Restore\n\nNow we have our backup text file, we can restore it to an existing database using the `couchrestore`:\n\n    cat animals.txt | couchrestore\n\nor specifying the database name on the command-line:\n\n    cat animals.txt | couchrestore --db animalsdb\n\n## Compressed backups\n\nIf we want to compress the backup data before storing to disk, we can pipe the contents through `gzip`:\n\n    couchbackup --db animals | gzip \u003e animals.txt.gz\n\nand restore the file with:\n\n    cat animals.tar.gz | gunzip | couchdbrestore --db animals2\n\n## What's in a backup file?\n\nA backup file is a text file where each line contains a JSON encoded array of up to 500 objects e.g.\n\n    [{\"a\":1},{\"a\":2}...]\n    [{\"a\":501},{\"a\":502}...]\n\n## What's in a log file?\n\nA log file contains a line:\n\n- for every batch of document ids that need to be fetched e.g. `:t batch56 [{\"id\":\"a\"},{\"id\":\"b\"}]`\n- for every batch that has been fetched and stored e.g. `:d batch56`\n- to indicate that the changes feed was fully consumed e.g. `:changes_complete`\n\n## What is shallow mode?\n\nWhen you run `couchbackup` with `--mode shallow` a simpler backup is performed, only backing up the winning revisions\nof the database. No revision tokens are saved and any conflicting revisions are ignored. This is a faster, but less\ncomplete backup. Shallow backups cannot be resumed because they do not produce a log file.\n\n## Why use CouchBackup?\n\nThe easiest way to backup a CouchDB database is to copy the \".couch\" file. This is fine on a single-node instance, but when running multi-node \nCloudant or using CouchDB 2.0 or greater, the \".couch\" file only contains a single shard of data. This utility allows simple backups of CouchDB\nor Cloudant database using the HTTP API.\n\nThis tool can be used to script the backup of your databases. Move the backup and log files to cheap Object Storage so that you have multiple copies of your precious data.\n\n## Options reference\n\n### Environment variables\n\n* COUCH_URL - the URL of the CouchDB/Cloudant server e.g. http://127.0.0.1:5984\n* COUCH_DATABASE - the name of the database to act upon e.g. mydb (default 'test')\n* COUCH_PARALLELISM - the number of HTTP requests to perform in parallel when restoring a backup e.g. 10 (Default 5)\n* COUCH_BUFFER_SIZE - the number of documents fetched and restored at once e.g. 100 (default 500)\n* COUCH_LOG - the file to store logging information during backup\n* COUCH_RESUME - if 'true', resumes a previous backup from its last known position\n* COUCH_OUTPUT - the file name to store the backup data (defaults to stdout)\n* COUCH_MODE - if 'shallow', only a superfical backup is done, ignoring conflicts and revision tokens. Defaults to 'full' - a full backup.\n\n### Command-line paramters\n\n* --url - same as COUCH_URL environment variable\n* --db - same as COUCH_DATABASE \n* --parallelism - same as COUCH_PARALLELISM\n* --buffer - same as COUCH_BUFFER_SIZE\n* --log - same as COUCH_LOG\n* --resume - same as COUCH_RESUME\n* --output - same as COUCH_OUTPUT\n* --mode - same as COUCH_MODE\n\n## Using programmatically\n\nYou can now use `couchbackup` programatically. First install the `couchbackup` into your project \nwith `npm install --save couchbackup`. Then you can import the library into your code:\n\n\n```\n  var couchbackup = require('couchbackup');\n```\n\nDefine some options, using an object that contains attributes with the same names as the environment \nvariables used to configure the command-line utilities:\n\n```\nvar opts = {\n  \"COUCH_URL\": \"http://127.0.0.1:5984\",\n  \"COUCH_DATABASE\": \"mydb\",\n}\n```\n\nThe you can backup data to a stream:\n\n\n```\ncouchbackup.backupStream(process.stdout, opts, function() {\n  // done!\n});\n```\n\nor to a file\n\n```\ncouchbackup.backupFile(\"backup.txt\", opts, function() {\n  // done!\n});\n```\n\nSimilarly, you can restore from a stream:\n\n```\ncouchbackup.restoreStream(process.stdin, opts, function() {\n  // done!\n});\n```\n\nThe `couchbackup` functions emit events:\n\n* written - when a group of documents is backuped up or restored\n* writecomplete - emitted once when all documents are backed up or restored\n* writeerror - emitted when something goes wrong\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglynnbird%2Fcouchbackup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglynnbird%2Fcouchbackup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglynnbird%2Fcouchbackup/lists"}