Couchbase Server 3.

0 Documentation

Contents

Introduction

Couchbase benefits

Couchbase Server and NoSQL

What's new in 3.0

New features

Installation and upgrade

Couchbase setup overview

Table 1: Example deployments

Pre-installation

Resource requirements

Supported platforms

Network ports

Supported web browsers

Red Hat/CentOS installation

Prerequisites

OpenSSL dependency checking

OpenSSL 0983 installation

Installing on RHEL

Using user-defined ports

Setting up Couchbase with user-defined ports

Ports to change

Installing as non-root, non-sudo

Installing multiple instances

Requirements

Recommendations

Setting up multiple instances

Troubleshooting

Limitations

Uninstalling on RHEL

Upgrading on RHEL

Ubuntu/Debian installation

Installing on Ubuntu or Debian

Installing as non-root, non-sudo

Uninstalling on Ubuntu Linux

Upgrading on Ubuntu

Microsoft Windows installation

Installation wizard

Unattended installation

Uninstalling on Windows

Upgrading on Windows

Mac OS X installation

Installing on Mac OS X

Installing as non-root, non-sudo

Uninstalling on Mac OS X

Upgrading on Mac OS X

Post-installation

Initial server setup

Using hostnames

Hostname errors

Startup and shutdown on Linux

Startup and shutdown on Windows

Via Windows Task Manager

Via Windows system

Via Couchbase-supplied

command

scripts

Startup and shutdown on Mac OS X

Testing Couchbase Server

Testing with cbworkloadgen

Testing installation with telnet

Upgrading

Upgrading from Community Edition to Enterprise Edition

Upgrading to 3.0

Upgrading to 2.5

Online upgrades

Offline upgrade

Offline upgrade process

Offline upgrade to Enterprise Edition

Upgrading servers

Upgrading with XDCR

Upgrade scenarios

Migrating

Migrating for CouchDB users

Term and concept differences

Consistent functionality

Changed functionality

Operational and deployment differences

Client and application changes

Migrating for Membase users

Term and concept differences

Consistent functionality

Changed functionality

Operational and deployment differences

Client and application ahanges

Administration

Administration basics

Accessing Couchbase Server directly

Accessing Couchbase Server through a client

Encrypted admin access

SSL certificate

Using REST for encrypted access

Encrypted data access

Common admin tasks

Increasing or reducing your cluster size

Warming up a server

Handling a failover situation

Managing database and view fragmentation

Backing up and restoring your cluster data

Starting and stopping Couchbase

Table 2: Starting and stopping Couchbase

Data file location

Changing the data file path

CLI example

Installation location

Limits

Cluster-wide diagnostics

Architecture and concepts

Cluster Manager

Nodes and clusters

Rack Awareness

Distribution of vBuckets and replica vBuckets

Figure 1: Rack Awareness

Distribution with additional server

Figure 2: Rack Awareness with additional server

Distribution with unavailable server

Figure 3: Rack Awareness with unavailable server

Data storage

RAM quotas

vBuckets

Caching layer

Disk storage

Multiple readers and writers

Document deletion

Tombstone purging

Shared thread pool

Viewing thread status

Disk I/O priority

Backward compatibility

Tunable memory

Backward compatibility

Working set management and ejection

Working set management process

Not Frequently Used (NFU) items

Understanding the item pager

Expiration

Server warmup

Replicas and replication

TAP

Database Change Protocol

Client interface

Create

Retrieve

Update

Delete

Statistics and monitoring

Deployment considerations

Cluster design considerations

Sizing guidelines

RAM sizing

Working set

Memory quota

Disk throughput and sizing

Network bandwidth

Data safety

Data distribution

Replication

Hardware requirements

Considerations for Cloud environments (i.e. Amazon EC2)

Deployment strategies

Using a smart (vBucket-aware) client

Client-side (standalone) proxy

Using server-side (Couchbase embedded) proxy

Ongoing monitoring and maintenance

Important UI stats to watch

Couchbase behind a secondary firewall

Couchbase in the cloud

Handling instance reboot in cloud

Local storage

Handling changes in IP addresses

Security groups/firewall settings

Swap space

Using Couchbase Server on RightScale

XDCR in cloud deployments

Cluster management

Handling server warmup

Getting warmup information

Changing the warmup threshold

Changing access scanner settings

Handling replication

Providing data replication

Specifying backoff for replication

Compacting data files

Compaction process

Auto-compaction configuration

Auto-compaction strategies

Cluster maintenance

Adding nodes

Adding nodes via UI

Adding nodes via REST

Adding nodes via CLI

Removing nodes

Web Console

Using the Command-line

Rebalancing

Rebalancing

Performing a rebalance

Rebalancing via UI

Rebalancing via CLI

Rebalance behind-the-scenes

Changing vBucket moves with REST

Rebalance effect on bucket types

Swap rebalance

Rebalancing factors

When to expand your cluster

When to shrink your cluster

When to rebalance your cluster

Common rebalancing questions

How long will rebalancing take?

How many nodes can be added or removed?

Will cluster performance be affected during a rebalance?

Can I stop a rebalance operation?

Server maintenance

Failing over nodes

Failover considerations

Choosing a failover solution

Using automatic failover

Initiating a node failover

Handling a failover situation

Adding back a failed over node

Graceful failover

Hard failover

Recovering failed over nodes

Delta node recovery

Delta node recovery failure scenarios

Full recovery

Rebalancing after failover

Backup and restore

Backing up with

Backup all nodes and all buckets

Backup all nodes, single bucket

Backup single node, all buckets

Backup single node, single bucket

Backup single node, single bucket; backup files stored on same node

Filter keys during backup

Backup using file copies

Restoring with

Filtering keys during restore

Restoring using file copies

Incremental backup and restore

Differential incremental backup

Cumulative incremental backup

Combining incremental backup types

Backing up and restoring between platforms

Backing up Mac OS X and restoring on Linux/Windows

Backing up Linux/Windows and restoring on Mac OS X

Transferring data directly

Transferring desing documents

Managing XDCR

Configuring XDCR replications

Conflict resolution in XDCR

Securing data communication

Tuning XDCR performance

Changing the document threshold

Monitoring optimistic replication

Configuring bi-directional replication

Modifying XDCR settings

Data recovery from remote clusters

Stream-based XDCR

Backward compatibility

Monitoring

Underlying server processes

Port numbers and accessing different buckets

Disk write queue

Monitoring the disk write queue

Couchbase Server statistics

REST interface statistics

Couchbase Server node statistics

stats command

dispatcher command

Changing statistics collection

Changing the stats file location

Couchbase Server Moxi statistics

Monitoring startup (warmup)

Monitoring a rebalance

Views and indexes

View basics

Stream-based views

Views operation

How expiration impacts views

How views function in a cluster

View performance

Index updates and the stale parameter

Automated index updates

Views and stored data

JSON basics

Document metadata

Non-JSON data

Document storage and indexing sequence

Development views

Production views

Writing views

Map functions

Reduce functions

Built-in _count

Built-in _sum

Built-in _stats

Writing custom reduce functions

Re-writing the built-in reduce functions

Handling re-reduce

Views on non-JSON data

Built-in utility functions

View writing best practice

Writing geospatial views

Adding geometry data

Views and queries

Querying views

Querying using the REST API

Selecting information

Selecting compound information by key or keys

Partial selection and key ranges

Partial selection with compound keys

Pagination

Grouping in queries

Selection when grouping

Ordering

Understanding letter ordering in views

Error control

Views in a schema-less database

Translating SQL to map/reduce

Translating SQL SELECT to map/reduce

Translating SQL WHERE to map/reduce

Translating SQL ORDER BY to map/reduce

Translating SQL GROUP BY to map/reduce

Translating SQL LIMIT and OFFSET

View and query pattern samples

General advice

Validating document type

Document ID (primary) index

Secondary index

Using expiration metadata

Emitting multiple rows

Date and time selection

Selective record output

Sorting on reduce values

Solutions for simulating joins

Simulating transactions

Simulating multi-phase transactions

Cross Datacenter Replication (XDCR)

XDCR use cases

XDCR architecture

Stream-based XDCR

Backward compatibility

XDCR basic topologies

XDCR advanced topologies

XDCR replication via memcached protocol

XDCR and network or system outages

XDCR document handling

XDCR flush requests

XDCR stream management

XDCR pause and resume replication

XDCR data encryption

Web console

Cluster Overview

Viewing cluster overview

Viewing buckets

Viewing servers

Managing Rack Awareness

Figure 4: Server Nodes tab

Figure 5: Server Groups

Creating server groups

Figure 6: Create server group

Deleting server groups

Moving servers between server groups

Figure 7: Apply changes to server group

Adding servers to server groups

Figure 8: Add server to server group

Removing servers from server groups

Renaming server groups

Figure 9: Edit server group

Server Nodes

Understanding server states

Viewing DCP queues

Failing over a node

Recovering a node

Data Buckets

Creating and editing data buckets

Editing Couchbase buckets

Editing Memcached buckets

Bucket information

Using multi-readers and writers

Specifying read-write for new buckets

Specifying read-write for existing buckets

Viewing the impact of read-write changes

Managing disk I/O priority

Managing metadata in memory

Managing documents

Monitoring statistics

Individual bucket monitoring

Bucket monitoring summary statistics

Monitoring vBucket resources

Monitoring disk queues

Monitoring TAP queues

Memcached buckets

Monitoring outgoing XDCR

Monitoring incoming XDCR

Monitoring view statistics

Views

Creating and editing views

Publishing views

Getting view results

XDCR

Create cluster reference

Create replication

Creating replications

Specifying a destination cluster

Specifying XDCR settings

XDCR advanced settings

Managing XDCR data encryption

XDCR data encryption prerequisites

To enable XDCR data security

To change XDCR data encryption

SSL certificate

Create Cluster Reference

XDCR data security error messages

Monitoring replication status

Pausing XDCR replication

Canceling replication

Log

Log

Collect Information

Managing diagnostics

Collecting and uploading log information

Canceling information collection

Hiding the collection results window

Showing the collection results window

Settings

Cluster tab

Update Notifications tab

Auto-Failover tab

Alerts tab

Email Server Settings

Table 3: Email Server settings

Email Settings
Table 4: Email settings

Available Alerts

Table 5: Available alerts

Auto-Compaction tab

Table 6: Auto-compaction parameters

Sample Buckets tab

Account Management tab

Creating a read-only user

FAQs

Sample buckets

Beer sample bucket

brewery_beers view

by_location view

Game Simulation sample bucket

leaderboard view

playerlist view

Troubleshooting

Common errors

Problems Starting Couchbase Server for the first time

General tips

Logs and logging

Changing log file location

Changing logging levels

Changing logging levels to be persistent

Changing logging levels dynamically

Reporting issues

Beam.smp

Blocked indexer

Server issues

Incorrect or missing data (server issue)

Incorrect or missing data (user issue)

Design document aliases

Expired documents issue

Index filesystem structure

Index results for a single node

Debugging replica index

Debugging stale=false queries

Timeout errors

total_rows values are too high

Wrong documents or rows issue

Deprecated items

Platforms

Table 7: Deprecated operating systems

REST API

Table 8: Deprecated REST API URIs or parameters

CLI tools and parameters

Table 9: Deprecated tools

Table 10: Deprecated CLI parameter

Miscellaneous

CLI reference

CLI overview

Command line tools and availability

Unsupported tools

Deprecated and removed tools

Managing diagnostics

couchbase-cli tool

couchbase-cli commands

couchbase-cli command options

server-list option

server-add options

server-readd options

group-manage options (Enterprise Edition only)

rebalance options

failover option

cluster-* options

node-init options

bucket-* options

setting-compaction options

setting-alert and notification options

setting-autofailover options

setting-xdcr options

xdcr-setup options

xdcr-replicate options

ssl-manage options

Rack-zone awareness

Creating server groups

Adding servers to server groups

Moving servers from server groups

Buckets

Listing bucketss

Creating buckets

Modifying buckets

Deleting buckets

Flushing buckets

Compacting buckets

Setting bucket priority

Creating a bucket and setting high priority

Setting high priority

Setting metadata ejection policy

Bucket ejection policy

Server nodes

Retrieving server information

Adding nodes to clusters

Removing nodes

Stopping rebalance

Setting cluster parameters

Changing data paths

Failing over nodes

Syntax

Setting failover, readd, recovery, and rebalance operations

Failing over a node immediately

Recovering nodes

Table 11: Recovery type

Syntax

Setting recovery type

Setting failover, readd, recovery, and rebalance operations

XDCR

Managing XDCR replication streams

Managing remote clusters

Managing XDCR data encryption

Managing SSL certificates

Pausing XDCR replication streams

Table 12: xdcr-replicate options

Syntax

Pausing a running replication stream

Resuming a paused replication stream

Updating settings for a replication stream

Diagnostics with couchbase-cli

Start log collection command

Stop log collection command

Report log collection status command

cbanalyze-core tool

cbbackup tool

Backing up design documents

Backing up incrementally

cbcollect_info tool

Diagnostics with cbcollect_info

cbdocloader tool

cbepctl tool

cbepctl set checkpoint_param

cbepctl set flush_param

cbepctl set tap_param

Changing thresholds for ejection

Setting the low water mark

Setting the high water mark

Setting percentage of ejected items

Changing access log settings

Changing disk cleanup interval

Changing disk write queue quotas

Changing setting for out of memory errors

cbhealthchecker tool

Sample Commands

HTML Report

cbreset_password tool

cbrestore tool

Restoring design documents

Using cbrestore for design documents

Restoring incrementally

cbstats tool

Toplevel stats

vBucket total stats

Replica vBucket stats

Pending vBucket stats

Timing stats

General form

Available stats

Hash stats

Checkpoint stats

Memory stats

Stats key and Vkey

Warmup

KV store stats

Dispatcher stats and job logs

Stats reset

Getting server timings

Getting warmup information

DCP statistics

Table 13: DCP statistics

Syntax

Example: request all DCP statistics

Example: request aggregated DCP statistics

Example: request failover logs

DCP statistics by connection type

Table 14: Consumer connection statistics

Table 15: Consumer connection per-stream statistics

Table 16: Producer and notifier connection statistics

Table 17: Producer and notifier connection per-stream statistics

Aggregated DCP statistics

Table 18: Aggregated DCP statistics

Tap stats

Per Tap client stats

Tap aggregated stats

Getting TAP information

Read-write thread stats

Example

cbtransfer tool

Exporting and Importing CSV Files

Transferring Design Documents Only

cbworkloadgen tool

REST API reference

REST API overview

Types of resources

HTTP request headers

HTTP status codes

Cluster API

Description

Table 19: Cluster endpoints

Retrieving cluster information

HTTP method and URI

Syntax

Example

Response

Viewing cluster details

Description

HTTP method and URI

Table 20: Controller parameters

Syntax

Example

Response

Adding nodes to clusters

HTTP method and URI

Syntax

Example

Response

Joining nodes into clusters

Description

HTTP method and URI

Table 21: /node/controller/doJoinCluster parameters

Syntax

Example

Response codes

Removing nodes from clusters

HTTP method and URI

Syntax

Example

Response codes

Rebalancing nodes

Description

HTTP method and URI

Syntax

Example

Response codes

Getting rebalance progress

HTTP method and URI

Syntax

Example

Response

Example: detailed

Response: detailed

Adjusting rebalance during compaction

Description

HTTP method and URI

Syntax

Example

Viewing internal settings

Description

Response codes

Getting internal settings

HTTP method and URI

Syntax

Example

Response

Changing internal settings

HTTP method and URI

Syntax

Example

Response

Setting maximum parallel indexers

HTTP method and URI

Syntax

Example: GET

Response

Example: POST

Response

Managing auto-failover
Description

Retrieving auto-failover settings

Enabling and disabling auto-failover

Resetting auto-failover
HTTP method and URI

Syntax

Example

Response codes

Disabling consistent query results on rebalance

View settings for email notifications

Enabling and disabling email notifications

Sending test emails

Server groups API

Description

Table 22: Server group endpoints

Getting server group information

HTTP method and URI

Syntax

Example

Response

Creating server groups

HTTP method and URI

Syntax

Example

Adding servers to server groups

HTTP method and URI

Syntax

Example

Renaming server groups

HTTP method and URI

Syntax

Example

Updating server group memberships

HTTP method and URI

Syntax

Example

Deleting server groups

HTTP method and URI

Syntax

Example

Server nodes API

Description

Table 23: Server node endpoints

Getting server node information

HTTP method and URI

Syntax

Example

Response

Provisioning nodes

Description

Failing over nodes

HTTP method and URI

Syntax

Example

Response codes

Setting recovery type

HTTP method and URI

Syntax

Response codes

Setting graceful failover

HTTP method and URI

Syntax

Setting host names

Description

Response

Setting usernames and passwords

HTTP method and URI

Syntax

Example

Response

Setting memory quota

HTTP method and URI

Syntax

Example

Response codes

Setting index paths

HTTP method and URI

Syntax

Example

Response codes

Retrieving statistics

HTTP method and URI

Syntax

Example

Response

Buckets API

Description

Table 24: Bucket endpoints

Setting disk I/O priority

Disk I/O priority

Setting metadata ejection

Bucket metadata ejection

Getting single bucket information

Getting bucket configuration

Getting bucket statistics

Getting bucket streaming URI

HTTP method and URI

Syntax

Example

Response

Viewing buckets and bucket operations

Creating and editing buckets

Deleting buckets

Flushing buckets

Changing bucket authentication

Changing bucket read-write threads

View bucket read-write threads

Change bucket read-write threads

Request

Successful response:

Unsuccessful response

Increasing bucket memory quota

Modifying bucket parameters

Views API

Description

Table 25: Views endpoints

Managing design documents

Storing design documents

Retrieving design documents

Deleting design documents

Querying views

Views requests

XDCR API

Description

Table 26: XDCR endpoints

Creating XDCR replications

Creating a destination cluster reference

Getting a destination cluster reference

Deleting a destination cluster reference

Managing XDCR data encryption

Retrieving certificates

Regenerating certificates

Configuring XDCR with data encryption

Disabling data encryption

Deleting XDCR replications

Managing advanced XDCR settings

Table 27: XDCR URI paths for settings

GET /settings/replications

Table 28: XDCR advanced settings

Pausing XDCR replication streams

HTTP method and URI

Table 29: XDCR URI paths for settings

Table 30: XDCR advanced settings

Syntax

Example

Getting XDCR stats

Description

HTTP method and URI

Getting destination cluster info

Retrieving
HTTP method and URI

Syntax

stats

Example

Response

Retrieving
HTTP method and URI

Syntax

Example

stats

Response

Retrieving

stats

HTTP method and URI

Syntax: get replication id

Example: get replication id

Response

Example: get docs_opt_repd stats

Response

Retrieving incoming write operations

HTTP method and URI

Syntax

Example

Response

Compaction API

Description

Table 31: Compaction endpoints

Auto-compaction description

Table 32: Auto-compaction endpoints

Table 33: Auto-compaction parameters

Compacting buckets
HTTP method and URI

Syntax for compaction

Syntax for cancelling compaction

Compacting spatial views

Description

HTTP method and URI

Syntax

Example

Getting auto-compaction settings

HTTP method and URI

Cluster-wide syntax

Cluster-wide example

Cluster-wide response

Bucket-level syntax

Bucket-level example

Bucket-level response

Logs API

Description

Table 34: Log endpoints

Retrieving log information

GET /diag

GET /sasl_logs

GET /sasl_logs/[log_name]

Creating client logs

POST /logClientError

Syntax

Response

User API

Description
Table 35: User endpoints

Table 36: User return codes

POST /settings/readOnlyUser

PUT /settings/readOnlyUser

DELETE /settings/readOnlyUser

GET /settings/readOnlyAdminName

Release notes

Couchbase .NET incompatibility

Views behavior change

Known issues

Fixed issues