CouchDB: The Definitive Guide

Edition 1

J. Chris Anderson

Jan Lehnardt

Noah Slater

Appingo, Inc.

David Futato

Robert Romano

Karen Montgomery

Copyright © 2010 J. Chris Anderson, Jan Lehnardt, and Noah Slater

Legal Notice

Printed in the United States of America.

Legal Notice

[M]

Legal Notice

This book uses RepKover™, a durable and flexible lay-flat binding.

Legal Notice

O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://my.safaribooksonline.com). For more information, contact our corporate/institutional sales department: 800-998-9938 or .

Legal Notice

O’Reilly and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. CouchDB: The Definitive Guide, the image of a Pomeranian dog, and related trade dress are trademarks of O’Reilly Media, Inc.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps.

Legal Notice

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. This work has been released under the Creative Commons Attribution License. To view a copy of this license, visit http://creativecommons.org/licenses/by/2.0/legalcode or send a letter to Creative Commons, 171 2nd Street, Suite 300, San Francisco, California, 94105, USA.

Dedication

 

For the Web, and all the people who helped me along the way. Thank you.

 
 --J. Chris
 

Für Marita und Kalle.

 
 --Jan
 

For my parents, God and Damien Katz.

 
 --Noah
Foreword
Preface
1. Using Code Examples
2. Conventions Used in This Book
3. Safari® Books Online
4. How to Contact Us
5. Acknowledgments
5.1. J. Chris
5.2. Jan
5.3. Noah
I. Introduction
1. Why CouchDB?
1.1. Relax
1.2. A Different Way to Model Your Data
1.3. A Better Fit for Common Applications
1.3.1. Self-Contained Data
1.3.2. Syntax and Semantics
1.4. Building Blocks for Larger Systems
1.4.1. CouchDB Replication
1.5. Local Data Is King
1.6. Wrapping Up
2. Eventual Consistency
2.1. Working with the Grain
2.2. The CAP Theorem
2.3. Local Consistency
2.3.1. The Key to Your Data
2.3.2. No Locking
2.3.3. Validation
2.4. Distributed Consistency
2.4.1. Incremental Replication
2.4.2. Case Study
2.5. Wrapping Up
3. Getting Started
3.1. All Systems Are Go!
3.2. Welcome to Futon
3.3. Your First Database and Document
3.4. Running a Query Using MapReduce
3.5. Triggering Replication
3.6. Wrapping Up
4. The Core API
4.1. Server
4.2. Databases
4.3. Documents
4.3.1. Revisions
4.3.2. Documents in Detail
4.4. Replication
4.5. Wrapping Up
II. Developing with CouchDB
5. Design Documents
5.1. Document Modeling
5.2. The Query Server
5.3. Applications Are Documents
5.4. A Basic Design Document
5.5. Looking to the Future
6. Finding Your Data with Views
6.1. What Is a View?
6.2. Efficient Lookups
6.2.1. Find One
6.2.2. Find Many
6.2.3. Reversed Results
6.3. The View to Get Comments for Posts
6.4. Reduce/Rereduce
6.4.1. Lessons Learned
6.5. Wrapping Up
7. Validation Functions
7.1. Document Validation Functions
7.2. Validation’s Context
7.3. Writing One
7.3.1. Type
7.3.2. Required Fields
7.3.3. Timestamps
7.3.4. Authorship
7.4. Wrapping Up
8. Show Functions
8.1. The Show Function API
8.2. Side Effect–Free
8.3. Design Documents
8.4. Querying Show Functions
8.4.1. Design Document Resources
8.4.2. Query Parameters
8.4.3. Accept Headers
8.5. Etags
8.6. Functions and Templates
8.6.1. The !json Macro
8.6.2. The !code Macro
8.7. Learning Shows
8.8. Using Templates
8.9. Writing Templates
9. Transforming Views with List Functions
9.1. Arguments to the List Function
9.2. An Example List Function
9.3. List Theory
9.4. Querying Lists
9.5. Lists, Etags, and Caching
III. Example Application
10. Standalone Applications
10.1. Use the Correct Version
10.2. Portable JavaScript
10.3. Applications Are Documents
10.4. Standalone
10.5. In the Wild
10.6. Wrapping Up
11. Managing Design Documents
11.1. Working with the Example Application
11.2. Installing CouchApp
11.3. Using CouchApp
11.4. Download the Sofa Source Code
11.4.1. CouchApp Clone
11.4.2. ZIP and TAR Files
11.4.3. Join the Sofa Development Community on GitHub
11.4.4. The Sofa Source Tree
11.5. Deploying Sofa
11.5.1. Pushing Sofa to Your CouchDB
11.5.2. Visit the Application
11.6. Set Up Your Admin Account
11.6.1. Deploying to a Secure CouchDB
11.7. Configuring CouchApp with .couchapprc
12. Storing Documents
12.1. JSON Document Format
12.2. Beyond _id and _rev: Your Document Data
12.3. The Edit Page
12.3.1. The HTML Scaffold
12.4. Saving a Document
12.4.1. Validation
12.4.2. Save Your First Post
12.5. Wrapping Up
13. Showing Documents in Custom Formats
13.1. Rendering Documents with Show Functions
13.1.1. The Post Page Template
13.2. Dynamic Dates
14. Viewing Lists of Blog Posts
14.1. Map of Recent Blog Posts
14.2. Rendering the View as HTML Using a List Function
14.2.1. Sofa’s List Function
14.2.2. The Final Result
IV. Deploying CouchDB
15. Scaling Basics
15.1. Scaling Read Requests
15.2. Scaling Write Requests
15.3. Scaling Data
15.4. Basics First
16. Replication
16.1. The Magic
16.2. Simple Replication with the Admin Interface
16.3. Replication in Detail
16.4. Continuous Replication
16.5. That’s It?
17. Conflict Management
17.1. The Split Brain
17.2. Conflict Resolution by Example
17.3. Working with Conflicts
17.4. Deterministic Revision IDs
17.5. Wrapping Up
18. Load Balancing
18.1. Having a Backup
19. Clustering
19.1. Introducing CouchDB Lounge
19.2. Consistent Hashing
19.2.1. Redundant Storage
19.2.2. Redundant Proxies
19.2.3. View Merging
19.3. Growing the Cluster
19.3.1. Moving Partitions
19.3.2. Splitting Partitions
V. Reference
20. Change Notifications
20.1. Polling for Changes
20.2. Long Polling
20.3. Continuous Changes
20.4. Filters
20.5. Wrapping Up
21. View Cookbook for SQL Jockeys
21.1. Using Views
21.1.1. Defining a View
21.1.2. Querying a View
21.1.3. MapReduce Functions
21.2. Look Up by Key
21.3. Look Up by Prefix
21.4. Aggregate Functions
21.5. Get Unique Values
21.6. Enforcing Uniqueness
22. Security
22.1. The Admin Party
22.1.1. Creating New Admin Users
22.1.2. Hashing Passwords
22.2. Basic Authentication
22.2.1. Update Validations Again
22.3. Cookie Authentication
22.4. Network Server Security
23. High Performance
23.1. Good Benchmarks Are Non-Trivial
23.2. High Performance CouchDB
23.2.1. Hardware
23.2.2. An Implementation Note
23.3. Bulk Inserts and Mostly Monotonic DocIDs
23.3.1. Optimized Examples: Views and Replication
23.4. Bulk Document Inserts
23.5. Batch Mode
23.6. Single Document Inserts
23.7. Hovercraft
23.8. Trade-Offs
23.8.1. But…My Boss Wants Numbers!
23.8.2. A Call to Arms
24. Recipes
24.1. Banking
24.1.1. Accountants Don’t Use Erasers
24.1.2. Wrapping Up
24.2. Ordering Lists
24.2.1. A List of Integers
24.2.2. A List of Floats
24.3. Pagination
24.3.1. Example Data
24.3.2. A View
24.3.3. Setup
24.3.4. Slow Paging (Do Not Use)
24.3.5. Fast Paging (Do Use)
24.3.6. Jump to Page
VI. Appendixes
A. Installing on Unix-like Systems
A.1. Debian GNU/Linux
A.2. Ubuntu
A.3. Gentoo Linux
A.4. Problems
B. Installing on Mac OS X
B.1. CouchDBX
B.2. Homebrew
B.3. MacPorts
C. Installing on Windows
D. Installing from Source
D.1. Dependencies
D.1.1. Debian-Based (Including Ubuntu) Systems
D.1.2. Mac OS X
D.2. Installing
D.3. Security Considerations
D.4. Running Manually
D.5. Running As a Daemon
D.5.1. SysV/BSD-Style Systems
D.5.2. Mac OS X
D.6. Troubleshooting
E. JSON Primer
E.1. Data Types
E.1.1. Numbers
E.1.2. Strings
E.1.3. Booleans
E.1.4. Arrays
E.1.5. Objects
E.1.6. Nulls
F. The Power of B-trees
Index
n
Next Page
p
Previos Page
h
Book Home
u
Go Up One Level
?
Press ? for Help
esc
Hide Help
Your Ad Here