Apache CouchDB® Release 3.2.0 Oct 01, 2021 User Guides 1 Introduction 1 1.1 Technical Overview.........................................1 1.1.1 Document Storage.....................................1 1.1.2 ACID Properties......................................2 1.1.3 Compaction.........................................2 1.1.4 Views............................................2 1.1.5 Security and Validation...................................3 1.1.6 Distributed Updates and Replication............................4 1.1.7 Implementation.......................................5 1.2 Why CouchDB?...........................................5 1.2.1 Relax............................................6 1.2.2 A Different Way to Model Your Data............................6 1.2.3 A Better Fit for Common Applications...........................7 1.2.4 Building Blocks for Larger Systems............................8 1.2.5 CouchDB Replication....................................9 1.2.6 Local Data Is King.....................................9 1.2.7 Wrapping Up........................................ 10 1.3 Eventual Consistency........................................ 10 1.3.1 Working with the Grain................................... 10 1.3.2 The CAP Theorem..................................... 10 1.3.3 Local Consistency..................................... 11 1.3.4 Validation.......................................... 13 1.3.5 Distributed Consistency................................... 13 1.3.6 Incremental Replication................................... 13 1.3.7 Case Study......................................... 14 1.3.8 Wrapping Up........................................ 16 1.4 cURL: Your Command Line Friend................................. 16 1.5 Security................................................ 18 1.5.1 Authentication....................................... 18 1.5.2 Authentication Database.................................. 21 1.5.3 Authorization........................................ 24 1.6 Getting Started............................................ 25 1.6.1 All Systems Are Go!.................................... 25 1.6.2 Welcome to Fauxton.................................... 27 1.6.3 Your First Database and Document............................. 28 1.6.4 Running a Mango Query.................................. 28 1.6.5 Triggering Replication................................... 30 1.6.6 Wrapping Up........................................ 30 1.7 The Core API............................................. 30 1.7.1 Server............................................ 31 i 1.7.2 Databases.......................................... 31 1.7.3 Documents......................................... 35 1.7.4 Replication......................................... 38 1.7.5 Wrapping Up........................................ 40 2 Replication 41 2.1 Introduction to Replication...................................... 41 2.1.1 Transient and Persistent Replication............................ 41 2.1.2 Triggering, Stopping and Monitoring Replications..................... 41 2.1.3 Replication Procedure................................... 42 2.1.4 Master - Master replication................................. 42 2.1.5 Controlling which Documents to Replicate........................ 42 2.1.6 Migrating Data to Clients.................................. 43 2.2 Replicator Database......................................... 43 2.2.1 Basics............................................ 43 2.2.2 Documents describing the same replication........................ 46 2.2.3 Replication Scheduler.................................... 47 2.2.4 Replication states...................................... 47 2.2.5 Compatibility Mode..................................... 49 2.2.6 Canceling replications................................... 49 2.2.7 Server restart........................................ 49 2.2.8 Clustering.......................................... 49 2.2.9 Additional Replicator Databases.............................. 49 2.2.10 Fair Share Job Scheduling................................. 51 2.2.11 Replicating the replicator database............................. 51 2.2.12 Delegations......................................... 51 2.2.13 Selector Objects....................................... 52 2.2.14 Specifying Usernames and Passwords........................... 52 2.3 Replication and conflict model.................................... 53 2.3.1 CouchDB replication.................................... 54 2.3.2 Conflict avoidance..................................... 55 2.3.3 Revision tree........................................ 55 2.3.4 Working with conflicting documents............................ 56 2.3.5 Multiple document API................................... 57 2.3.6 View map functions..................................... 58 2.3.7 Merging and revision history................................ 60 2.3.8 Comparison with other replicating data stores....................... 61 2.4 CouchDB Replication Protocol................................... 64 2.4.1 Preface........................................... 64 2.4.2 Replication Protocol Algorithm.............................. 65 2.4.3 Protocol Robustness.................................... 89 2.4.4 Error Responses....................................... 89 2.4.5 Optimisations........................................ 91 2.4.6 API Reference....................................... 91 2.4.7 Reference.......................................... 91 3 Design Documents 93 3.1 Design Documents.......................................... 93 3.1.1 Creation and Structure................................... 93 3.1.2 View Functions....................................... 94 3.1.3 Show Functions....................................... 98 3.1.4 List Functions........................................ 99 3.1.5 Update Functions...................................... 100 3.1.6 Filter Functions....................................... 101 3.1.7 Validate Document Update Functions........................... 103 3.2 Guide to Views............................................ 106 3.2.1 Introduction to Views.................................... 106 3.2.2 Views Collation....................................... 116 ii 3.2.3 Joins With Views...................................... 120 3.2.4 View Cookbook for SQL Jockeys............................. 126 3.2.5 Pagination Recipe...................................... 132 3.3 Search................................................ 136 3.3.1 Index functions....................................... 137 3.3.2 Analyzers.......................................... 139 3.3.3 Queries........................................... 142 3.3.4 Query syntax........................................ 144 3.3.5 Geographical searches................................... 147 3.3.6 Highlighting search terms.................................. 149 4 Best Practices 151 4.1 Document Design Considerations.................................. 151 4.1.1 Don’t rely on CouchDB’s auto-UUID generation..................... 151 4.1.2 Alternatives to auto-incrementing sequences........................ 151 4.1.3 Pre-aggregating your data.................................. 152 4.1.4 Designing an application to work with replication..................... 152 4.1.5 Adding client-side security with a translucent database.................. 155 4.2 Document submission using HTML Forms............................. 155 4.2.1 The HTML form...................................... 156 4.2.2 The update function..................................... 156 4.2.3 Example output....................................... 157 4.3 Using an ISO Formatted Date for Document IDs.......................... 157 4.4 JavaScript development tips..................................... 158 4.5 View recommendations....................................... 158 4.5.1 Deploying a view change in a live environment...................... 159 4.6 Reverse Proxies........................................... 159 4.6.1 Reverse proxying with HAProxy.............................. 159 4.6.2 Reverse proxying with nginx................................ 160 4.6.3 Reverse Proxying with Caddy 2.............................. 161 4.6.4 Reverse Proxying with Apache HTTP Server....................... 163 5 Installation 165 5.1 Installation on Unix-like systems.................................. 165 5.1.1 Installation using the Apache CouchDB convenience binary packages.......... 165 5.1.2 Installation from source................................... 166 5.1.3 Dependencies........................................ 167 5.1.4 Installing.......................................... 168 5.1.5 User Registration and Security............................... 169 5.1.6 First Run.......................................... 169 5.1.7 Running as a Daemon.................................... 170 5.2 Installation on Windows....................................... 171 5.2.1 Installation from binaries.................................. 171 5.2.2 Installation from sources.................................. 172 5.3 Installation on macOS........................................ 172 5.3.1 Installation using the Apache CouchDB native application................ 172 5.3.2 Installation with Homebrew................................ 173 5.3.3 Installation from source................................... 173 5.4 Installation on FreeBSD....................................... 173 5.4.1 Installation from ports................................... 173 5.5 Installation via Docker........................................ 174 5.6 Installation