Apache CouchDB - Read the Docs

377 Pages·2014·2.75 MB·English

Apache CouchDB
Release 1.7.0-git
August01,2014

Contents
1 Introduction 1
1.1 TechnicalOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 WhyCouchDB? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 EventualConsistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.4 GettingStarted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.5 TheCoreAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.6 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
1.7 Futon: WebGUIAdministrationPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
1.8 cURL:YourCommandLineFriend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
2 Installation 49
2.1 InstallationonUnix-likesystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
2.2 InstallationonWindows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.3 InstallationonMacOSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
2.4 InstallationonFreeBSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
3 ConfiguringCouchDB 61
3.1 IntroductionIntoConfiguring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
3.2 BaseConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.3 CouchDBHTTPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.4 AuthenticationandAuthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
3.5 CompactionConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.6 Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.7 Replicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.8 QueryServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.9 ExternalProcesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.10 HTTPResourceHandlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
3.11 CouchDBInternalServices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
3.12 MiscellaneousParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
3.13 ProxyingConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
4 Replication 95
4.1 IntroductiontoReplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
4.2 CouchDBReplicationProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
4.3 ReplicatorDatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
4.4 Replicationandconflictmodel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
5 CouchDBMaintenance 115
5.1 Compaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.2 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
6 CouchApp 121
6.1 DesignFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
i
6.2 GuidetoViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
7 CouchDBExternalsAPI 161
7.1 TheNewHotness. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
7.2 Howdoesitwork? -HTTPProxying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
7.3 Howdoesitwork? -OSDaemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
7.4 Neat. ButSoWhat? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
8 QueryServer 165
8.1 QueryServerProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
8.2 JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
8.3 Erlang . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
9 Fauxton 185
9.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
9.2 WrittingAddons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
10 APIReference 191
10.1 APIBasics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
10.2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
10.3 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
10.4 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
10.5 DesignDocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
10.6 Local(non-replicating)Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
11 JSONStructureReference 309
11.1 AllDatabaseDocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
11.2 BulkDocumentResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
11.3 BulkDocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
11.4 Changesinformationforadatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
11.5 CouchDBDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
11.6 CouchDBErrorStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
11.7 CouchDBdatabaseinformationobject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
11.8 DesignDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
11.9 DesignDocumentInformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
11.10 DocumentwithAttachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
11.11 ListofActiveTasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
11.12 ReplicationSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
11.13 ReplicationStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
11.14 Requestobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
11.15 Responseobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
11.16 ReturnedCouchDBDocumentwithDetailedRevisionInfo . . . . . . . . . . . . . . . . . . . . 315
11.17 ReturnedCouchDBDocumentwithRevisionInfo . . . . . . . . . . . . . . . . . . . . . . . . . 315
11.18 ReturnedDocumentwithAttachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
11.19 SecurityObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
11.20 UserContextObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
11.21 ViewHeadInformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
12 ExperimentalFeatures 317
12.1 NodeJSQueryServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
12.2 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
12.3 Content-Security-Policy(CSP)HeaderSupportfor/_utils(Fauxton) . . . . . . . . . . . . . . . . 318
13 ContributingtothisDocumentation 319
14 ReleaseHistory 323
14.1 1.6.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
14.2 1.5.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
14.3 1.4.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
ii
14.4 1.3.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
14.5 1.2.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
14.6 1.1.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
14.7 1.0.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
14.8 0.11.xBranch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
14.9 0.10.xBranch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
14.10 0.9.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
14.11 0.8.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
15 SecurityIssuesInformation 355
15.1 CVE-2010-0009: ApacheCouchDBTimingAttackVulnerability . . . . . . . . . . . . . . . . . 355
15.2 CVE-2010-2234: ApacheCouchDBCrossSiteRequestForgeryAttack . . . . . . . . . . . . . . 355
15.3 CVE-2010-3854: ApacheCouchDBCrossSiteScriptingIssue. . . . . . . . . . . . . . . . . . . 356
15.4 CVE-2012-5641: InformationdisclosureviaunescapedbackslashesinURLsonWindows . . . . 357
15.5 CVE-2012-5649: JSONParbitrarycodeexecutionwithAdobeFlash . . . . . . . . . . . . . . . 358
15.6 CVE-2012-5650: DOMbasedCross-SiteScriptingviaFutonUI . . . . . . . . . . . . . . . . . . 358
15.7 CVE-2014-2668: DoS(CPUandmemoryconsumption)viathecountparameterto/_uuids . . . 359
16 ReportingNewSecurityProblemswithApacheCouchDB 361
17 AboutCouchDBDocumentation 363
17.1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
HTTPAPIReference 367
ConfigurationReference 369
iii
iv
1
CHAPTER
Introduction
CouchDBisadatabasethatcompletelyembracestheweb. StoreyourdatawithJSONdocuments. Accessyour
documentswithyourwebbrowser, viaHTTP.Query, combine, andtransformyourdocumentswithJavaScript.
CouchDBworkswellwithmodernwebandmobileapps. YoucanevenservewebappsdirectlyoutofCouchDB.
Andyoucandistributeyourdata,oryourapps,efficientlyusingCouchDB’sincrementalreplication. CouchDB
supportsmaster-mastersetupswithautomaticconflictdetection.
CouchDBcomeswithasuiteoffeatures,suchason-the-flydocumenttransformationandreal-timechangenotifi-
cations,thatmakeswebappdevelopmentabreeze. Itevencomeswithaneasytousewebadministrationconsole.
Youguessedit,servedupdirectlyoutofCouchDB!Wecarealotaboutdistributedscaling. CouchDBishighly
availableandpartitiontolerant,butisalsoeventuallyconsistent. Andwecarealotaboutyourdata. CouchDBhas
afault-tolerantstorageenginethatputsthesafetyofyourdatafirst.
Inthissectionyou’lllearnabouteverybasicbitofCouchDB,seeuponwhatconceptionsandtechnologiesitbuilt
andwalkthroughshorttutorialthatteachhowtouseCouchDB.
1.1 Technical Overview
1.1.1 Document Storage
A CouchDB server hosts named databases, which store documents. Each document is uniquely named in the
database, and CouchDB provides a RESTful HTTP API for reading and updating (add, edit, delete) database
documents.
DocumentsaretheprimaryunitofdatainCouchDBandconsistofanynumberoffieldsandattachments. Docu-
mentsalsoincludemetadatathat’smaintainedbythedatabasesystem. Documentfieldsareuniquelynamedand
containvaluesofvaryingtypes(text,number,boolean,lists,etc),andthereisnosetlimittotextsizeorelement
count.
TheCouchDBdocumentupdatemodelislocklessandoptimistic. Documenteditsaremadebyclientapplications
loading documents, applying changes, and saving them back to the database. If another client editing the same
documentsavestheirchangesfirst,theclientgetsaneditconflicterroronsave. Toresolvetheupdateconflict,the
latestdocumentversioncanbeopened,theeditsreappliedandtheupdatetriedagain.
Document updates (add, edit, delete) are all or nothing, either succeeding entirely or failing completely. The
databasenevercontainspartiallysavedorediteddocuments.
1.1.2 ACID Properties
TheCouchDBfilelayoutandcommitmentsystemfeaturesallAtomicConsistentIsolatedDurable(ACID)prop-
erties. On-disk,CouchDBneveroverwritescommitteddataorassociatedstructures,ensuringthedatabasefileis
alwaysinaconsistentstate. Thisisa“crash-only”designwheretheCouchDBserverdoesnotgothroughashut
downprocess,it’ssimplyterminated.
1
ApacheCouchDB,Release1.7.0-git
Document updates (add, edit, delete) are serialized, except for binary blobs which are written concurrently.
Databasereadersareneverlockedoutandneverhavetowaitonwritersorotherreaders. Anynumberofclients
canbereadingdocumentswithoutbeinglockedoutorinterruptedbyconcurrentupdates,evenonthesamedocu-
ment. CouchDBreadoperationsuseaMulti-VersionConcurrencyControl(MVCC)modelwhereeachclientsees
aconsistentsnapshotofthedatabasefromthebeginningtotheendofthereadoperation.
DocumentsareindexedinB-treesbytheirname(DocID)andaSequenceID.Eachupdatetoadatabaseinstance
generatesanewsequentialnumber. SequenceIDsareusedlaterforincrementallyfindingchangesinadatabase.
TheseB-treeindexesareupdatedsimultaneouslywhendocumentsaresavedordeleted.Theindexupdatesalways
occurattheendofthefile(append-onlyupdates).
Documentshavetheadvantageofdatabeingalreadyconvenientlypackagedforstorageratherthansplitoutacross
numeroustablesandrowsinmostdatabasesystems. Whendocumentsarecommittedtodisk,thedocumentfields
andmetadataarepackedintobuffers,sequentiallyonedocumentafteranother(helpfullaterforefficientbuilding
ofviews).
WhenCouchDBdocumentsareupdated,alldataandassociatedindexesareflushedtodiskandthetransactional
commitalwaysleavesthedatabaseinacompletelyconsistentstate. Commitsoccurintwosteps:
1. Alldocumentdataandassociatedindexupdatesaresynchronouslyflushedtodisk.
2. Theupdateddatabaseheaderiswrittenintwoconsecutive,identicalchunkstomakeupthefirst4kofthe
file,andthensynchronouslyflushedtodisk.
IntheeventofanOScrashorpowerfailureduringstep1, thepartiallyflushedupdatesaresimplyforgottenon
restart. Ifsuchacrashhappensduringstep2(committingtheheader),asurvivingcopyofthepreviousidentical
headerswillremain,ensuringcoherencyofallpreviouslycommitteddata. Exceptingtheheaderarea,consistency
checksorfix-upsafteracrashorapowerfailurearenevernecessary.
1.1.3 Compaction
Wasted space is recovered by occasional compaction. On schedule, or when the database file exceeds a certain
amountofwastedspace,thecompactionprocessclonesalltheactivedatatoanewfileandthendiscardstheold
file. The database remains completely online the entire time and all updates and reads are allowed to complete
successfully. Theolddatabasefileisdeletedonlywhenallthedatahasbeencopiedandalluserstransitionedto
thenewfile.
1.1.4 Views
ACIDpropertiesonlydealwithstorageandupdates,butwealsoneedtheabilitytoshowourdataininteresting
andusefulways. UnlikeSQLdatabaseswheredatamustbecarefullydecomposedintotables,datainCouchDB
isstoredinsemi-structureddocuments. CouchDBdocumentsareflexibleandeachhasitsownimplicitstructure,
which alleviates the most difficult problems and pitfalls of bi-directionally replicating table schemas and their
containeddata.
Butbeyondacting asafancyfile server, asimpledocumentmodelfor datastorageandsharingis toosimpleto
buildrealapplicationson–itsimplydoesn’tdoenoughofthethingswewantandexpect. Wewanttosliceand
diceandseeourdatainmanydifferentways. Whatisneededisawaytofilter,organizeandreportondatathat
hasn’tbeendecomposedintotables.
Seealso:
GuidetoViews
ViewModel
To address this problem of adding structure back to unstructured and semi-structured data, CouchDB integrates
aviewmodel. Viewsarethemethodofaggregatingandreportingonthedocumentsinadatabase,andarebuilt
on-demandtoaggregate,joinandreportondatabasedocuments. Becauseviewsarebuiltdynamicallyanddon’t
affecttheunderlyingdocument,youcanhaveasmanydifferentviewrepresentationsofthesamedataasyoulike.
2 Chapter1. Introduction
ApacheCouchDB,Release1.7.0-git
View definitions are strictly virtual and only display the documents from the current database instance, making
them separate from the data they display and compatible with replication. CouchDB views are defined inside
special design documents and can replicate across database instances like regular documents, so that not only
datareplicatesinCouchDB,butentireapplicationdesignsreplicatetoo.
JavascriptViewFunctions
Views are defined using Javascript functions acting as the map part in a map-reduce system. A view function
takesaCouchDBdocumentasanargumentandthendoeswhatevercomputationitneedstodotodeterminethe
datathatistobemadeavailablethroughtheview,ifany. Itcanaddmultiplerowstotheviewbasedonasingle
document,oritcanaddnorowsatall.
Seealso:
Viewfunctions
ViewIndexes
Viewsareadynamicrepresentationoftheactualdocumentcontentsofadatabase, andCouchDBmakesiteasy
to create useful views of data. But generating a view of a database with hundreds of thousands or millions of
documentsistimeandresourceconsuming,it’snotsomethingthesystemshoulddofromscratcheachtime.
To keep view querying fast, the view engine maintains indexes of its views, and incrementally updates them
to reflect changes in the database. CouchDB’s core design is largely optimized around the need for efficient,
incrementalcreationofviewsandtheirindexes.
Viewsandtheirfunctionsaredefinedinsidespecial“design”documents,andadesigndocumentmaycontainany
numberofuniquelynamedviewfunctions. Whenauseropensaviewanditsindexisautomaticallyupdated,all
theviewsinthesamedesigndocumentareindexedasasinglegroup.
TheviewbuilderusesthedatabasesequenceIDtodetermineiftheviewgroupisfullyup-to-datewiththedatabase.
Ifnot, theviewengineexaminesthealldatabasedocuments(inpackedsequentialorder)changedsincethelast
refresh. Documentsarereadintheordertheyoccurinthediskfile,reducingthefrequencyandcostofdiskhead
seeks.
Theviewscanbereadandqueriedsimultaneouslywhilealsobeingrefreshed. Ifaclientisslowlystreamingout
thecontentsofalargeview, thesameviewcanbeconcurrentlyopenedandrefreshedforanotherclientwithout
blockingthefirstclient. Thisistrueforanynumberofsimultaneousclientreaders,whocanreadandquerythe
viewwhiletheindexisconcurrentlybeingrefreshedforotherclientswithoutcausingproblemsforthereaders.
As documents are processed by the view engine through your ‘map’ and ‘reduce’ functions, their previous row
values are removed from the view indexes, if they exist. If the document is selected by a view function, the
functionresultsareinsertedintotheviewasanewrow.
Whenviewindexchangesarewrittentodisk, theupdatesarealwaysappendedattheendofthefile, servingto
both reduce disk head seek times during disk commits and to ensure crashes and power failures can not cause
corruptionofindexes. Ifacrashoccurswhileupdatingaviewindex,theincompleteindexupdatesaresimplylost
andrebuiltincrementallyfromitspreviouslycommittedstate.
1.1.5 Security and Validation
Toprotectwhocanreadandupdatedocuments,CouchDBhasasimplereaderaccessandupdatevalidationmodel
thatcanbeextendedtoimplementcustomsecuritymodels.
Seealso:
/db/_security
1.1. TechnicalOverview 3
ApacheCouchDB,Release1.7.0-git
AdministratorAccess
CouchDBdatabaseinstanceshaveadministratoraccounts. Administratoraccountscancreateotheradministrator
accountsandupdatedesigndocuments. Designdocumentsarespecialdocumentscontainingviewdefinitionsand
otherspecialformulas,aswellasregularfieldsandblobs.
UpdateValidation
Asdocumentswrittentodisk,theycanbevalidateddynamicallybyjavascriptfunctionsforbothsecurityanddata
validation. Whenthedocumentpassesalltheformulavalidationcriteria,theupdateisallowedtocontinue. Ifthe
validationfails,theupdateisabortedandtheuserclientgetsanerrorresponse.
Both the user’s credentials and the updated document are given as inputs to the validation formula, and can be
usedtoimplementcustomsecuritymodelsbyvalidatingauser’spermissionstoupdateadocument.
Abasic“authoronly”updatedocumentmodelistrivialtoimplement, wheredocumentupdatesarevalidatedto
checkiftheuserislistedinan“author”fieldintheexistingdocument. Moredynamicmodelsarealsopossible,
likecheckingaseparateuseraccountprofileforpermissionsettings.
Theupdatevalidationsareenforcedforbothliveusageandreplicatedupdates,ensuringsecurityanddatavalida-
tioninashared,distributedsystem.
Seealso:
Validatedocumentupdatefunctions
1.1.6 Distributed Updates and Replication
CouchDBisapeer-baseddistributeddatabasesystem. Itallowsusersandserverstoaccessandupdatethesame
shareddatawhiledisconnected. Thosechangescanthenbereplicatedbi-directionallylater.
The CouchDB document storage, view and security models are designed to work together to make true bi-
directional replication efficient and reliable. Both documents and designs can replicate, allowing full database
applications(includingapplicationdesign,logicanddata)tobereplicatedtolaptopsforofflineuse,orreplicated
toserversinremoteofficeswheresloworunreliableconnectionsmakesharingdatadifficult.
Thereplicationprocessisincremental. Atthedatabaselevel,replicationonlyexaminesdocumentsupdatedsince
thelastreplication.Thenforeachupdateddocument,onlyfieldsandblobsthathavechangedarereplicatedacross
the network. If replication fails at any step, due to network problems or crash for example, the next replication
restartsatthesamedocumentwhereitleftoff.
Partial replicas can be created and maintained. Replication can be filtered by a javascript function, so that only
particulardocumentsorthosemeetingspecificcriteriaarereplicated.Thiscanallowuserstotakesubsetsofalarge
shared database application offline for their own use, while maintaining normal interaction with the application
andthatsubsetofdata.
Conflicts
Conflictdetectionandmanagementarekeyissuesforanydistributededitsystem. TheCouchDBstoragesystem
treatseditconflictsasacommonstate,notanexceptionalone. Theconflicthandlingmodelissimpleand“non-
destructive”whilepreservingsingledocumentsemanticsandallowingfordecentralizedconflictresolution.
CouchDB allows for any number of conflicting documents to exist simultaneously in the database, with each
database instance deterministically deciding which document is the “winner” and which are conflicts. Only the
winning document can appear in views, while “losing” conflicts are still accessible and remain in the database
untildeletedorpurgedduringdatabasecompaction. Becauseconflictdocumentsarestillregulardocuments,they
replicatejustlikeregulardocumentsandaresubjecttothesamesecurityandvalidationrules.
When distributed edit conflicts occur, every database replica sees the same winning revision and each has the
opportunitytoresolvetheconflict. Resolvingconflictscanbedonemanuallyor,dependingonthenatureofthe
4 Chapter1. Introduction