Issue 2857 Repair Tool

Documentation for the repair tool developed in Issue #2857 to fix issue introduced in issues #2651.

Step: Determine if your Sync Gateway version is affected

If you have one of these versions, you might have been affected, depending on your revs_limit parameter value and exact usage.

• 1.3.1.2
• 1.4.1.1

To verify whether or not you are affected, use the Dry Run mechanism described below.

Step: Backup your data

Please backup your data before running this tool. If you run into errors please restore the data from your backup and contact support

Step: Enable CRUD log key

Make sure the Sync Gateway config has CRUD logging enabled.

Step: Perform a dry run

curl -X POST \
  http://localhost:4985/db/_repair \
  -H 'content-type: application/json' \
  -d '{
  "dry_run": true,
  "repair_jobs": [
     {
     	"type": "RepairRevTreeCycles"
     }	
  ]
}'

The response JSON will return:

[
    {
        "dry_run": true,
        "backup_or_dryrun_doc_id": "_sync:repair:dryrun:data_for_test",
        "id": "data_for_test",
        "repair_job_type": [
            "RepairRevTreeCycles"
        ]
    }
]

• The doc IDs that would have been repaired by the dry run.
• The doc ID of the "dry run doc", which shows what the actual transformed doc will look like when an actual repair takes place. The doc ID will have the form _sync:repair:dryrun:[key], and will auto-delete in 24 hours.

Step: Repair Bucket

Assuming the dry run output looks good, repair the bucket using this command:

curl -X POST \
  http://localhost:4985/db/_repair \
  -H 'content-type: application/json' \
  -d '{
  "dry_run": false,
  "repair_jobs": [
     {
     	"type": "RepairRevTreeCycles"
     }	
  ]
}'

Expected JSON response:

[
    {
        "dry_run": false,
        "backup_or_dryrun_doc_id": "_sync:repair:backup:data_for_test",
        "id": "data_for_test",
        "repair_job_type": [
            "RepairRevTreeCycles"
        ]
    }
]

• backup_or_dryrun_doc_id will contain the backup copy of the document before it was repaired. This will auto-delete in 24 hours.

Step: Verify

Verify that the doc no longer has cycles in the revtree by running:

curl http://{{host}}:{{port_admin}}/{{db}}/your_doc_id?revs=true

And replace your_doc_id with a doc that had known issues, and verify that you do not see the error: "reason": "Internal error: getHistory found cycle in revision tree

Step: Restart Sync Gateway

This is required to flush out any stale values that might be in the Revision Cache.

Step: (optional) Restore from backup

Repaired docs will be backed up in a temporary Couchbase Server document named _sync:repair:backup:[key] for 24 hours.

If something goes wrong, you can restore back to the original docs using these backup copies.

Step: (optional) Additional configuration options

The following optional properties can be set for a repair or dry run.

Property	Description
view_query_page_size	Batch size used when processing results. Default value is 5000.
repair_output_ttl_seconds	Time to retain repair output documents - either dry run docs or repair backups. If set to zero, these documents are not stored. Default value is 24 hours.

Sample curl showing usage of these properties:

curl -X POST \
  http://localhost:4985/db/_repair \
  -H 'content-type: application/json' \
  -d '{
  "dry_run": true,
  "view_query_page_size": 10000,
  "repair_output_ttl_seconds": 3600,
  "repair_jobs": [
     {
     	"type": "RepairRevTreeCycles"
     }	
  ]
}'