Apache CouchDB

383 Pages·2016·2.78 MB·English

Apache CouchDB
Release 1.6.1
Jun 07, 2017

Contents
1 Introduction 1
1.1 TechnicalOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.1 DocumentStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.2 ACIDProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.3 Compaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.4 Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.5 SecurityandValidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.6 DistributedUpdatesandReplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.7 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 WhyCouchDB? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2.1 Relax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2.2 ADifferentWaytoModelYourData. . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2.3 ABetterFitforCommonApplications . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2.4 BuildingBlocksforLargerSystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.2.5 CouchDBReplication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.2.6 LocalDataIsKing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.2.7 WrappingUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3 EventualConsistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.1 WorkingwiththeGrain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.2 TheCAPTheorem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.3 LocalConsistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.3.4 Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.3.5 DistributedConsistency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.3.6 IncrementalReplication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.3.7 CaseStudy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.3.8 WrappingUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.4 GettingStarted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4.1 AllSystemsAreGo! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4.2 WelcometoFuton. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.4.3 YourFirstDatabaseandDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.4.4 RunningaQueryUsingMapReduce . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.4.5 TriggeringReplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.4.6 WrappingUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.5 TheCoreAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.5.1 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.5.2 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.5.3 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
1.5.4 Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
1.5.5 WrappingUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
1.6 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
i
1.6.1 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
1.6.2 AuthenticationDatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
1.6.3 Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
1.7 Futon: WebGUIAdministrationPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
1.7.1 ManagingDatabasesandDocuments. . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
1.7.2 ConfiguringReplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
1.8 cURL:YourCommandLineFriend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
2 Installation 51
2.1 InstallationonUnix-likesystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
2.1.1 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
2.1.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
2.1.3 Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.1.4 FirstRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.1.5 SecurityConsiderations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.1.6 RunningasaDaemon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
2.2 InstallationonWindows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
2.2.1 Installationfrombinaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
2.2.2 Installationfromsources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
2.3 InstallationonMacOSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.3.1 InstallationusingtheApacheCouchDBnativeapplication . . . . . . . . . . . . . . . . 59
2.3.2 InstallationwithHomeBrew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.3.3 InstallationfromMacPorts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
2.4 InstallationonFreeBSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2.4.1 Installationfromports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
3 ConfiguringCouchDB 63
3.1 IntroductionIntoConfiguring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.1.1 Configurationfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.1.2 Parameternamesandvalues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.1.3 Settingparametersviatheconfigurationfile . . . . . . . . . . . . . . . . . . . . . . . . 64
3.1.4 SettingparametersviatheHTTPAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.2 BaseConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.2.1 BaseCouchDBOptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.3 CouchDBHTTPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.3.1 HTTPServerOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.3.2 SecureSocketLevelOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
3.3.3 Cross-OriginResourceSharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
3.3.4 VirtualHosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.4 AuthenticationandAuthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
3.4.1 ServerAdministrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
3.4.2 AuthenticationConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.4.3 HTTPOAuthConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.4.4 OAuthConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.5 CompactionConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.5.1 DatabaseCompactionOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.5.2 CompactionDaemonRules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.5.3 ConfigurationofCompactionDaemon . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.5.4 ViewsCompactionOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.6 Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.6.1 Loggingoptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.6.2 Permodulelogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.7 Replicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.7.1 ReplicatorDatabaseConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.8 QueryServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
3.8.1 QueryServersDefinition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
3.8.2 QueryServersConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
3.8.3 NativeErlangQueryServer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
ii
3.9 ExternalProcesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.9.1 OSDaemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.9.2 OSDaemonssettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
3.9.3 Updatenotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
3.10 HTTPResourceHandlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
3.10.1 GlobalHTTPHandlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
3.10.2 DatabaseHTTPHandlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
3.10.3 DesignDocumentsHTTPHandlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
3.11 CouchDBInternalServices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
3.11.1 CouchDBDaemonizedMiniApps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
3.12 MiscellaneousParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
3.12.1 ConfigurationofAttachmentStorage. . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
3.12.2 StatisticCalculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
3.12.3 UUIDsConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
3.12.4 Vendorinformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
3.12.5 Content-Security-Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
3.13 ProxyingConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
3.13.1 CouchDBAsProxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
4 Replication 99
4.1 IntroductiontoReplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.1.1 TriggeringReplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.1.2 ReplicationProcedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.1.3 Master-Masterreplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.1.4 ControllingwhichDocumentstoReplicate . . . . . . . . . . . . . . . . . . . . . . . . 100
4.1.5 MigratingDatatoClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.2 CouchDBReplicationProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.2.1 Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.2.2 Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.2.3 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.2.4 Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.2.5 Filterreplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.2.6 Optimisations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.2.7 APIReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.2.8 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.3 ReplicatorDatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
4.3.1 Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
4.3.2 Documentsdescribingthesamereplication . . . . . . . . . . . . . . . . . . . . . . . . 104
4.3.3 Cancelingreplications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
4.3.4 Serverrestart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
4.3.5 ChangingtheReplicatorDatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
4.3.6 Replicatingthereplicatordatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.3.7 Delegations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.4 Replicationandconflictmodel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4.4.1 CouchDBreplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4.4.2 Conflictavoidance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
4.4.3 Conflictsinbatches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
4.4.4 Revisiontree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
4.4.5 Workingwithconflictingdocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
4.4.6 MultipledocumentAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
4.4.7 Viewmapfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
4.4.8 Mergingandrevisionhistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
4.4.9 Comparisonwithotherreplicatingdatastores . . . . . . . . . . . . . . . . . . . . . . . 115
5 CouchDBMaintenance 119
5.1 Compaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
5.1.1 DatabaseCompaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
5.1.2 ViewsCompaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
iii
5.1.3 AutomaticCompaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
5.2 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
5.2.1 DiskI/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
5.2.2 SystemResourceLimits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.2.3 Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
5.2.4 CouchDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
5.2.5 Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
6 CouchApp 127
6.1 DesignFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
6.1.1 Viewfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
6.1.2 Showfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.1.3 Listfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.1.4 Updatefunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.1.5 Filterfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.1.6 Validatedocumentupdatefunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.2 GuidetoViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
6.2.1 IntroductionIntoTheViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
6.2.2 ViewsCollation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
6.2.3 JoinsWithViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.2.4 ViewCookbookforSQLJockeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
6.2.5 PaginationRecipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7 CouchDBExternalsAPI 167
7.1 TheNewHotness. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
7.2 Howdoesitwork? -HTTPProxying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
7.3 Howdoesitwork? -OSDaemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
7.3.1 ConfigurationAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
7.3.2 LoggingAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
7.3.3 DynamicDaemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
7.4 Neat. ButSoWhat? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
8 QueryServer 171
8.1 QueryServerProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
8.1.1 reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
8.1.2 add_lib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
8.1.3 map_doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
8.1.4 reduce. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
8.1.5 rereduce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
8.1.6 ddoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
8.1.7 Raisingerrors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
8.1.8 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
8.2 JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
8.2.1 Designfunctionscontext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
8.2.2 CommonJSModules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
8.3 Erlang . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9 Fauxton 193
9.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
9.1.1 Getthesource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
9.1.2 FauxtonSetup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
9.1.3 DevServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
9.1.4 DeployFauxton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
9.2 WrittingAddons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
9.2.1 GeneratinganAddon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
9.2.2 Routesandhooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
9.2.3 HelloworldAddon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
10 APIReference 199
iv
10.1 APIBasics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
10.1.1 RequestFormatandResponses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
10.1.2 HTTPHeaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
10.1.3 JSONBasics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
10.1.4 HTTPStatusCodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
10.2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
10.2.1 /. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
10.2.2 /_active_tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
10.2.3 /_all_dbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
10.2.4 /_db_updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
10.2.5 /_log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
10.2.6 /_replicate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
10.2.7 /_restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
10.2.8 /_stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
10.2.9 /_utils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
10.2.10 /_uuids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
10.2.11 /favicon.ico . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
10.2.12 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
10.2.13 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
10.3 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
10.3.1 /db . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
10.3.2 /db/_all_docs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
10.3.3 /db/_bulk_docs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
10.3.4 /db/_changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
10.3.5 /db/_compact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
10.3.6 /db/_compact/design-doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
10.3.7 /db/_ensure_full_commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
10.3.8 /db/_view_cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
10.3.9 /db/_security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
10.3.10 /db/_temp_view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
10.3.11 /db/_purge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
10.3.12 /db/_missing_revs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
10.3.13 /db/_revs_diff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
10.3.14 /db/_revs_limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
10.4 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
10.4.1 /db/doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
10.4.2 /db/doc/attachment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
10.5 DesignDocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
10.5.1 /db/_design/design-doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
10.5.2 /db/_design/design-doc/attachment . . . . . . . . . . . . . . . . . . . . . 297
10.5.3 /db/_design/design-doc/_info . . . . . . . . . . . . . . . . . . . . . . . . . 298
10.5.4 /db/_design/design-doc/_view/view-name . . . . . . . . . . . . . . . . . 299
10.5.5 /db/_design/design-doc/_show/show-name . . . . . . . . . . . . . . . . . 311
10.5.6 /db/_design/design-doc/_show/show-name/doc-id . . . . . . . . . . . 312
10.5.7 /db/_design/design-doc/_list/list-name/view-name . . . . . . . . . 312
10.5.8 /db/_design/design-doc/_list/list-name/other-ddoc/view-name 313
10.5.9 /db/_design/design-doc/_update/update-name . . . . . . . . . . . . . . 315
10.5.10 /db/_design/design-doc/_update/update-name/doc-id . . . . . . . . 316
10.5.11 /db/_design/design-doc/_rewrite/path. . . . . . . . . . . . . . . . . . . 317
10.6 Local(non-replicating)Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
10.6.1 /db/_local/id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
11 JSONStructureReference 319
11.1 AllDatabaseDocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
11.2 BulkDocumentResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
11.3 BulkDocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
11.4 Changesinformationforadatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
11.5 CouchDBDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
v
11.6 CouchDBErrorStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
11.7 CouchDBdatabaseinformationobject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
11.8 DesignDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
11.9 DesignDocumentInformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
11.10 DocumentwithAttachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
11.11 ListofActiveTasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
11.12 ReplicationSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
11.13 ReplicationStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
11.14 Requestobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
11.15 Responseobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
11.16 ReturnedCouchDBDocumentwithDetailedRevisionInfo . . . . . . . . . . . . . . . . . . . . 325
11.17 ReturnedCouchDBDocumentwithRevisionInfo . . . . . . . . . . . . . . . . . . . . . . . . . 325
11.18 ReturnedDocumentwithAttachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
11.19 SecurityObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
11.20 UserContextObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
11.21 ViewHeadInformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
12 ExperimentalFeatures 327
12.1 NodeJSQueryServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
12.1.1 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
12.1.2 DifferencesfromtheSpiderMonkeyQueryServer . . . . . . . . . . . . . . . . . . . . . 328
12.2 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
12.3 Content-Security-Policy(CSP)HeaderSupportfor/_utils(Fauxton) . . . . . . . . . . . . . . . . 328
13 ContributingtothisDocumentation 329
14 ReleaseHistory 333
14.1 1.6.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
14.1.1 Deprecations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
14.1.2 Version1.6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
14.1.3 Version1.6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
14.2 1.5.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
14.2.1 Version1.5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
14.2.2 Version1.5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
14.3 1.4.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
14.3.1 UpgradeNotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
14.3.2 Version1.4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
14.4 1.3.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
14.4.1 UpgradeNotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
14.4.2 Version1.3.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
14.4.3 Version1.3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
14.5 1.2.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
14.5.1 UpgradeNotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
14.5.2 Version1.2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
14.5.3 Version1.2.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
14.5.4 Version1.2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
14.6 1.1.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
14.6.1 UpgradeNotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
14.6.2 Version1.1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
14.6.3 Version1.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
14.6.4 Version1.1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
14.7 1.0.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
14.7.1 UpgradeNotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
14.7.2 Version1.0.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
14.7.3 Version1.0.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
14.7.4 Version1.0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
14.7.5 Version1.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
14.7.6 Version1.0.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
14.8 0.11.xBranch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
vi
14.8.1 UpgradeNotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
14.8.2 Version0.11.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
14.8.3 Version0.11.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
14.8.4 Version0.11.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
14.9 0.10.xBranch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
14.9.1 UpgradeNotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
14.9.2 Version0.10.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
14.9.3 Version0.10.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
14.9.4 Version0.10.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
14.10 0.9.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
14.10.1 UpgradeNotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
14.10.2 Version0.9.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
14.10.3 Version0.9.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
14.10.4 Version0.9.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
14.11 0.8.xBranch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
14.11.1 Version0.8.1-incubating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
14.11.2 Version0.8.0-incubating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
15 SecurityIssuesInformation 367
15.1 CVE-2010-0009: ApacheCouchDBTimingAttackVulnerability . . . . . . . . . . . . . . . . . 367
15.1.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
15.1.2 Mitigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
15.1.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
15.1.4 Credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
15.2 CVE-2010-2234: ApacheCouchDBCrossSiteRequestForgeryAttack . . . . . . . . . . . . . . 368
15.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
15.2.2 Mitigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
15.2.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
15.2.4 Credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
15.3 CVE-2010-3854: ApacheCouchDBCrossSiteScriptingIssue. . . . . . . . . . . . . . . . . . . 368
15.3.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
15.3.2 Mitigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
15.3.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
15.3.4 Credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
15.4 CVE-2012-5641: InformationdisclosureviaunescapedbackslashesinURLsonWindows . . . . 369
15.4.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
15.4.2 Mitigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
15.4.3 Work-Around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
15.4.4 Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
15.4.5 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
15.5 CVE-2012-5649: JSONParbitrarycodeexecutionwithAdobeFlash . . . . . . . . . . . . . . . 370
15.5.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
15.5.2 Mitigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
15.5.3 Work-Around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
15.6 CVE-2012-5650: DOMbasedCross-SiteScriptingviaFutonUI . . . . . . . . . . . . . . . . . . 370
15.6.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
15.6.2 Mitigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
15.6.3 Work-Around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
15.6.4 Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
15.7 CVE-2014-2668: DoS(CPUandmemoryconsumption)viathecountparameterto/_uuids . . . 371
15.7.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
15.7.2 Mitigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
15.7.3 Work-Around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
16 ReportingNewSecurityProblemswithApacheCouchDB 373
17 AboutCouchDBDocumentation 375
17.1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
vii
HTTPAPIReference 379
ConfigurationReference 381
viii