Search:

Manual

Couchbase Server Manual 2.0

Community Wiki and Resources

Download Couchbase Server 2.0

Couchbase Developer Guide 2.0

Client Libraries

Couchbase Server Forum

Additional Resources

Community Forums

Chapters

1 Introduction to Couchbase Server

2 Installing and Upgrading

3 Administration Basics

4 Best Practices

5 Administration Tasks

6 Using the Web Console

7 Command-line Interface for Administration

8 Using the REST API

9 Views and Indexes

10 Monitoring Couchbase

11 Troubleshooting

B Uninstalling Couchbase Server

C Couchbase Sample Buckets

D Troubleshooting Views (Technical Background)

E Release Notes

Couchbase Server Manual 2.0
		Next

Couchbase Server Manual 2.0

Copyright © 2010-2013 Couchbase, Inc. Contact copyright@couchbase.com.

For documentation license information, see Documentation License. For all license information, see Licenses.

Abstract

This manual documents the Couchbase Server 2.0 series, including installation, monitoring, and administration interface and associated tools.

For the corresponding Moxi product, please use the Moxi 1.8 series. See Moxi 1.8 Manual.

External Community Resources.

Download Couchbase Server 2.0

Couchbase Developer Guide 2.0

Client Libraries

Couchbase Server Forum

Last document update: 18 May 2013 00:55; Document built: 18 May 2013 00:55.

Documentation Availability and Formats. This documentation is available for download: HTML Zip, PDF, EPUB . For other documentation from Couchbase, see Couchbase Documentation Library

Contact: editors@couchbase.com or couchbase.com

Table of Contents

1. Best Practice Guides
2. Manual Conventions
3. Contributors

1. Introduction to Couchbase Server

1.1. Couchbase Server and NoSQL

1.2. Architecture and Concepts

1.2.1. Nodes and Clusters
1.2.2. Cluster Manager
1.2.3. Data Storage
1.2.4. RAM Quotas
1.2.5. vBuckets
1.2.6. Caching Layer
1.2.7. Disk Storage
1.2.8. Ejection, Eviction and Working Set Management
1.2.9. Expiration
1.2.10. Server Warmup
1.2.11. Rebalancing
1.2.12. Replicas and Replication
1.2.13. Failover
1.2.14. TAP
1.2.15. Client Interface
1.2.16. Administration Tools
1.2.17. Statistics and Monitoring

1.3. Migration to Couchbase

1.3.1. Migrating for Membase Users
1.3.2. Migrating for CouchDB Users

2. Installing and Upgrading

2.1. Preparation

2.1.1. Supported Platforms
2.1.2. Hardware Requirements
2.1.3. Storage Requirements
2.1.4. Supported Web Browsers
2.1.5. Network Ports

2.2. Installing Couchbase Server

2.2.1. Red Hat Linux Installation
2.2.2. Ubuntu Linux Installation
2.2.3. Microsoft Windows Installation
2.2.4. Mac OS X Installation

2.3. Initial Server Setup

2.4. Using Hostnames with Couchbase Server

2.4.1. Hostnames for Couchbase Server 2.0.1 and Earlier

2.5. Upgrading to Couchbase Server 2.0.x

2.5.1. Online Upgrades
2.5.2. Online Upgrade Using Swap Rebalance
2.5.3. Offline Upgrade Process

2.6. Upgrade Notes 1.8 and Earlier to 2.0

2.7. Upgrades Notes 1.8.1 to 2.0

2.7.1. Linux Upgrade Notes for 1.8.1 to 2.0
2.7.2. Windows Upgrade Notes for 1.8.1 to 2.0
2.7.3. Node Upgrade Process
2.7.4. Upgrading from Community Edition to Enterprise Edition

2.8. Testing Couchbase Server

2.8.1. Testing Couchbase Server using cbworkloadgen
2.8.2. Testing Couchbase Server using Telnet

2.9. Next Steps

3. Administration Basics

3.1. Couchbase Data Files

3.2. Startup and Shutdown of Couchbase Server

3.2.1. Startup and Shutdown on Linux
3.2.2. Startup and Shutdown on Windows
3.2.3. Startup and Shutdown on Mac OS X

4. Best Practices

4.1. Cluster Design Considerations

4.2. Sizing Guidelines

4.2.1. RAM Sizing
4.2.2. Disk Throughput and Sizing
4.2.3. Network Bandwidth
4.2.4. Data Safety

4.3. Deployment Considerations

4.4. Ongoing Monitoring and Maintenance

4.4.1. Important UI Stats to Watch

4.5. Couchbase Behind a Secondary Firewall

4.6. Using Couchbase in the Cloud

4.6.1. Local Storage
4.6.2. Handling Changes in IP Addresses
4.6.3. Security groups/firewall settings
4.6.4. Swap Space

4.7. Deployment Strategies

4.7.1. Using a “smart” (vBucket aware) Client
4.7.2. Client-Side (standalone) Proxy
4.7.3. Using Server-Side (Couchbase Embedded) Proxy

5. Administration Tasks

5.1. Handling Server Warmup

5.1.1. Getting Warmup Information
5.1.2. Changing the Warmup Threshold
5.1.3. Changing Access Scanner Settings

5.2. Handling Replication within a Cluster

5.2.1. Providing Data Replication
5.2.2. Specifying Backoff for Replication

5.3. Ejection and Working Set Management

5.4. Database and View Compaction

5.4.1. Compaction Process
5.4.2. Auto-Compaction Configuration
5.4.3. Auto-compaction Strategies

5.5. Failing Over Nodes

5.5.1. Choosing a Failover Solution
5.5.2. Using Automatic Failover
5.5.3. Initiating a Node Failover
5.5.4. Handling a Failover Situation
5.5.5. Adding Back a Failed Over Node

5.6. Backup and Restore

5.6.1. Backing Up Using cbbackup
5.6.2. Restoring Using cbrestore
5.6.3. Backup and Restore Between Mac OS X and Other Platforms

5.7. Rebalancing

5.7.1. Choosing When to Rebalance
5.7.2. Performing a Rebalance
5.7.3. Swap Rebalance
5.7.4. Monitoring During Rebalance
5.7.5. Common Rebalancing Questions
5.7.6. Rebalance Effect on Bucket Types
5.7.7. Rebalance Behind-the-Scenes

5.8. Cross Datacenter Replication (XDCR)

5.8.1. Use Cases
5.8.2. Basic Topologies
5.8.3. XDCR Architecture
5.8.4. Advanced Topologies
5.8.5. Configuring Replication
5.8.6. Monitoring Replication Status
5.8.7. Cancelling Replication
5.8.8. Behavior and Limitations
5.8.9. Conflict Resolution in XDCR
5.8.10. Modifying XDCR Settings via REST
5.8.11. Changing the XDCR Retry Setting
5.8.12. Securing Data Communication with XDCR
5.8.13. Using XDCR in Cloud Deployments

5.9. Changing Couchbase Quotas

5.10. Changing the Configured Disk Path

6. Using the Web Console

6.1. Viewing Cluster Summary

6.1.1. Viewing Cluster Overview
6.1.2. Viewing Buckets
6.1.3. Viewing Servers

6.2. Viewing Server Nodes

6.2.1. Understanding Server States

6.3. Viewing Data Buckets

6.3.1. Creating and Editing Data Buckets
6.3.2. Bucket Information

6.4. Viewing Bucket and Cluster Statistics

6.4.1. Individual Bucket Monitoring

6.5. Using the Views Editor

6.5.1. Creating and Editing Views
6.5.2. Publishing Views
6.5.3. Getting View Results

6.6. Using the Document Editor

6.8. Settings

6.8.1. Update Notification Settings
6.8.2. Enabling Auto-Failover Settings
6.8.3. Enabling Alerts
6.8.4. Enabling Auto-Compaction
6.8.5. Installing Sample Buckets

6.9. Updating Notifications

6.10. Warnings and Alerts

7. Command-line Interface for Administration

7.1. Command Line Tools and Availability

7.2. Unsupported Tools

7.3. Deprecated and Removed Tools

7.4. couchbase-cli Tool

7.4.1. Flushing Buckets with couchbase-cli
7.4.2. Other couchbase-cli Usage

7.5. cbstats Tool

7.5.1. Getting Server Timings
7.5.2. Getting Warmup Information
7.5.3. Getting TAP Information

7.6. cbepctl Tool

7.6.1. Changing the Disk Cleanup Interval
7.6.2. Changing Disk Write Queue Quotas
7.6.3. Changing Access Log Settings
7.6.4. Changing Thresholds for Ejection
7.6.5. Changing Setting for Out Of Memory Errors
7.6.6. Enabling Flush of Data Buckets - Will be Deprecated
7.6.7. Other cbepctl flush_param

7.7. cbcollect_info Tool

7.8. cbbackup Tool

7.9. cbrestore Tool

7.10. cbtransfer Tool

7.11. cbdocloader Tool

7.12. cbworkloadgen Tool

7.13. cbanalyze-core Tool

7.14. vbuckettool Tool

8. Using the REST API

8.1. Types of Resources

8.2. HTTP Request Headers

8.3. HTTP Status Codes

8.4. Using the Couchbase Administrative Console

8.5. Managing Couchbase Nodes

8.5.1. Retrieving Statistics from Nodes
8.5.2. Provisioning a Node
8.5.3. Configuring Index Path for a Node
8.5.4. Setting Username and Password for a Node
8.5.5. Configuring Node Memory Quota
8.5.6. Providing Hostnames for Nodes
8.5.7. Manually Failing Over a Node

8.6. Managing Buckets

8.6.1. Viewing Buckets and Bucket Operations
8.6.2. Getting Individual Bucket Information
8.6.3. Getting Bucket Statistics
8.6.4. Using the Bucket Streaming URI
8.6.5. Creating and Editing Data Buckets
8.6.6. Getting Bucket Configuration
8.6.7. Modifying Bucket Parameters
8.6.8. Increasing the Memory Quota for a Bucket
8.6.9. Changing Bucket Authentication
8.6.10. Compacting Bucket Data and Indexes
8.6.11. Deleting a Bucket
8.6.12. Flushing a Bucket

8.7. Managing Clusters

8.7.1. Viewing Cluster Details
8.7.2. Adding a Node to a Cluster
8.7.3. Joining a Node into a Cluster
8.7.4. Removing a Node from a Cluster
8.7.5. Initiating a Rebalance
8.7.6. Getting Rebalance Progress
8.7.7. Adjusting Rebalance during Compaction
8.7.8. Retrieving Auto-Failover Settings
8.7.9. Enabling and Disabling Auto-Failover
8.7.10. Resetting Auto-Failover
8.7.11. Setting Maximum Buckets for Clusters
8.7.12. Setting Maximum Parallel Indexers
8.7.13. View Settings for Email Notifications
8.7.14. Enabling and Disabling Email Notifications
8.7.15. Sending Test Emails
8.7.16. Managing Internal Cluster Settings
8.7.17. Disabling Consistent Query Results on Rebalance

8.8. Managing Views with REST

8.9. Managing Cross Data Center Replication (XDCR)

8.9.1. Getting a Destination Cluster Reference
8.9.2. Creating a Destination Cluster Reference
8.9.3. Deleting a Destination Cluster Reference
8.9.4. Creating XDCR Replications
8.9.5. Deleting XDCR Replications
8.9.6. Viewing Internal XDCR Settings
8.9.7. Changing Internal XDCR Settings
8.9.8. Getting XDCR Stats via REST

8.10. Using System Logs

8.11. Client Logging Interface

9. Views and Indexes

9.1. View Basics

9.2. View Operation

9.2.1. How Expiration Impacts Views
9.2.2. How Views Function in a Cluster
9.2.3. View Performance
9.2.4. Index Updates and the stale Parameter
9.2.5. Automated Index Updates

9.3. Views and Stored Data

9.3.1. JSON Basics
9.3.2. Document Metadata
9.3.3. Non-JSON Data
9.3.4. Document Storage and Indexing Sequence

9.4. Development and Production Views

9.5. Writing Views

9.5.1. Map Functions
9.5.2. Reduce Functions
9.5.3. Views on non-JSON Data
9.5.4. Built-in Utility Functions
9.5.5. View Writing Best Practice

9.6. Views in a Schema-less Database

9.7. Design Document REST API

9.7.1. Storing a Design Document
9.7.2. Retrieving a Design Document
9.7.3. Deleting a Design Document

9.8. Querying Views

9.8.1. Querying Using the REST API
9.8.2. Selecting Information
9.8.3. Pagination
9.8.4. Grouping in Queries
9.8.5. Ordering
9.8.6. Understanding Letter Ordering in Views
9.8.7. Error Control

9.9. View and Query Pattern Samples

9.9.1. General Advice
9.9.2. Validating Document Type
9.9.3. Document ID (Primary) Index
9.9.4. Secondary Index
9.9.5. Using Expiration Metadata
9.9.6. Emitting Multiple Rows
9.9.7. Date and Time Selection
9.9.8. Selective Record Output
9.9.9. Sorting on Reduce Values
9.9.10. Solutions for Simulating Joins
9.9.11. Simulating Transactions
9.9.12. Simulating Multi-phase Transactions

9.10. Translating SQL to Map/Reduce

9.10.1. Translating SQL Field Selection (SELECT) to Map/Reduce
9.10.2. Translating SQL WHERE to Map/Reduce
9.10.3. Translating SQL ORDER BY to Map/Reduce
9.10.4. Translating SQL GROUP BY to Map/Reduce
9.10.5. Translating SQL LIMIT and OFFSET

9.11. Writing Geospatial Views

9.11.1. Adding Geometry Data
9.11.2. Views and Queries

10. Monitoring Couchbase

10.1. Underlying Server Processes

10.2. Port numbers and accessing different buckets

10.3. Monitoring startup (warmup)

10.4. Disk Write Queue

10.4.1. Monitoring the Disk Write Queue

10.5. Couchbase Server Statistics

10.5.1. REST Interface Statistics
10.5.2. Couchbase Server Node Statistics

10.6. Couchbase Server Moxi Statistics

11. Troubleshooting

11.1. General Tips
11.2. Responding to Specific Errors
11.3. Logs and Logging
11.4. Common Errors

B. Uninstalling Couchbase Server

B.1. Uninstalling on a RedHat Linux System
B.2. Uninstalling on an Debian/Ubuntu Linux System
B.3. Uninstalling on a Windows System
B.4. Uninstalling on a Mac OS X System

C. Couchbase Sample Buckets

C.1. Game Simulation Sample Bucket

C.1.1. leaderboard View
C.1.2. playerlist View

C.2. Beer Sample Bucket

C.2.1. brewery_beers View
C.2.2. by_location View

D. Troubleshooting Views (Technical Background)

D.1. Timeout errors in query responses
D.2. Blocked indexers, no progress for long periods of time
D.3. Data missing in query response or it's wrong (user issue)
D.4. Wrong documents or rows when querying with include_docs=true
D.5. Expired documents still have their associated Key-Value pairs returned in queries with stale=false
D.6. Data missing in query response or it's wrong (potentially due to server issues)
D.7. Index filesystem structure and meaning
D.8. Design document aliases
D.9. Getting query results from a single node
D.10. Verifying replica index and querying it (debug/testing)
D.11. Expected cases for total_rows with a too high value
D.12. Getting view btree stats for performance and longevity analysis
D.13. Debugging stale=false queries for missing/unexpected data
D.14. What to include in good issue reports (JIRA)

E. Release Notes

E.1. Release Notes for Couchbase Server 2.0.1 GA (March 2013)
E.2. Release Notes for Couchbase Server 2.0.0 GA (December 12 2012)
E.3. Release Notes for Couchbase Server 2.0.0 #1941 Beta (November 13 2012)
E.4. Release Notes for Couchbase Server 2.0.0 build #1870 Beta (1 November 2012)
E.5. Release Notes for Couchbase Server 2.0.0 Beta (18 September 2012)
E.6. Release Notes for Couchbase Server 2.0.0 Build #1672 Developer Preview (10 September 2012)
E.7. Release Notes for Couchbase Server 2.0.0 Build #1554 Developer Preview (10 August 2012)
E.8. Release Notes for Couchbase Server 2.0.0 Build #1495 Developer Preview (26 July 2012)
E.9. Release Notes for Couchbase Server 2.0.0DP4 Developer Preview (21 March 2012)
E.10. Release Notes for Couchbase Server 2.0.0DP3 Developer Preview (13 December 2011)
E.11. Release Notes for Couchbase Server 2.0.0DP2 Developer Preview (23 August 2011)
E.12. Release Notes for Couchbase Server 2.0.0DP Developer Preview (29 July 2011)

F.1. Known Limitations

G. Licenses

G.1. Documentation License
G.2. Couchbase, Inc. Community Edition License Agreement
G.3. Couchbase, Inc. Enterprise License Agreement: Free Edition

List of Figures

1.1. Couchbase Introduction — RAM Quotas
1.2. Couchbase Introduction — vBucket Mapping
1.3. Couchbase Introduction — vBucket Mapping after Rebalance
1.4. Architecture — Bucket Configuration
2.1. Couchbase Server Setup — Step 1 (New Cluster)
2.2. Couchbase Server Setup — Step 2 — Loading Sample Data
2.3. Couchbase Server Setup — Step 3
2.4. Couchbase Server Setup — Completed
2.5. Online Upgrade — Marking a Node for Removal from a Cluster
2.6. Online Upgrade — Starting the Rebalance Process
2.7. Online Upgrade — Cluster with the Node Removed
2.8. Online Upgrade — Adding the Node back to the Cluster
3.1. Couchbase Server on Mac OS X — Menubar Item
4.1. Deployment Strategy — Using a vBucket Aware Client
4.2. Deployment Strategy — Standalone Proxy
4.3. Deployment Strategy — Using the Embedded Proxy
5.1. Replica vBuckets and Replication
5.2. Rebalancing — Servers Pending Rebalance
5.3. Rebalancing — Adding new node during setup
5.4. Rebalancing — Node added during setup
5.5. Rebalancing — Adding new node using the Web Console
5.6. Rebalancing — Adding a new node dialog
5.7. Rebalancing — Starting a Rebalance
5.8. Rebalancing — Monitoring a Rebalance
5.9. Replication within a Cluster
5.10. Cross Data Center Replication
5.11. Replicating Selected Buckets via XDCR
5.12. XDCR Triggered after Disk Persistence
5.13. Conflict Resolution in XDCR
5.14. Replication Chain with Uni-Directional Replication
5.15. Bidirectional and Unidirectional Replication for Selective Replication
5.16. Couchbase Web Console - Replication Cluster Reference
5.17. Couchbase Web Console - Replication Configuration
5.18. Couchbase Web Console - Replication Monitoring
5.19. Errors Panel for XDCR
5.20. XDCR — Using Static VPN Routes
5.21. XDCR — Using Third-party BGP Routing
6.1. Web Console — Cluster Overview
6.2. Web Console — Cluster Overview — Cluster
6.3. Web Console — Cluster Overview — Buckets
6.4. Web Console — Cluster Overview — Servers
6.5. Web Console — Server Nodes
6.6. Web Console — Server Node Detail
6.7. Web Console — Data Bucket/Server view
6.8. Web Console — Server specific view
6.9. Web Console — Down Status
6.10. Web Console — Pend Status
6.11. Web Console — Data Buckets Overview
6.12. Web Console — Create Bucket
6.13. Web Console — Bucket Information
6.14. Web Console — Summary Statistics
6.15. Web Console — vBucket Resources statistics
6.16. Web Console — Disk Queue Statistics
6.17. Web Console — TAP Queue Statistics
6.18. Web Console — Memcached Statistics
6.19. Couchbase Web Console - Ongoing Replications
6.20. Web Console — Outgoing XDCR Statistics
6.21. Couchbase Web Console - XDCR Incoming Replications
6.22. Web Console — Views Statistics
6.23. Web Console — View Manager
6.24. Web Console — View Editing
6.25. Web Console — View Filters
6.26. Web Console — View Detail
6.27. Web Console — Document Overview
6.28. Web Console — Document Create
6.29. Web Console — Document Edit
6.30. Web Console — Log Viewer
6.31. Web Console — Settings — Update Notifications
6.32. Web Console — Settings — Auto-Failover
6.33. Web Console — Settings — Alerts
6.34. Web Console — Settings — Auto-Compaction
6.35. Web Console — Settings — Samble Buckets
6.36. Web Console — Warning Notification
9.1. Views — Basic Overview
9.2. View Indexes — in a Cluster
9.3. Views — Index Updates — Stale OK
9.4. Views — Index Updates — Update Before
9.5. Views — Index Updates — Update After
9.6. Views — Data Storage
9.7. Views — View Type Workflow
9.8. Views — View Building
9.9. Views — Writing Map Functions
9.10. Views — Writing Map Functions with Missing Fields
9.11. Views — Writing Custom Reduce Functions
9.12. Views — Handling Rereduce
9.13. Views — Querying — Flow and Parameter Interaction
9.14. View Grouping

List of Tables

1.1. Couchbase Introduction — Bucket Types
1.2. Couchbase Introduction — Bucket Capabilities
1.3. Couchbase Introduction - Bucket Type Capability Comparison
2.1. Getting Started — Network Ports
4.1. Deployment — Sizing — Input Variables
4.2. Deployment — Sizing — Constants
4.3. Deployment — Sizing — Input Variables
4.4. Deployment — Sizing — Constants
4.5. Deployment — Sizing — Variable Calculations
7.1. Administration — Command-line Tools and Availability
7.2. Administration — Deprecated/Removed Command-line Tools
8.1. REST API — Supported Request Headers
8.2. REST API — HTTP Status Codes
8.3. REST API — Controller Functions
8.4. REST API — Cluster Joining Arguments
8.5. REST API — Cluster Joining Additional Arguments
10.1. Monitoring — Stats
11.1. Troubleshooting — Responses to Specific Errors
11.2. Log File Locations
11.3. Log File Locations
F.1. Couchbase Server Limits

		Next
		Preface

Copyright (c) 2010-2013Couchbase, Inc.