Apache CouchDB Documentation

CouchDB is a web-centric database designed for modern web and mobile applications. It uses JSON documents for data storage and provides access via HTTP.

Key capabilities include:

• Data Access: Interact with documents using HTTP, perform queries, combine views, and transform documents using JavaScript.
• Replication: Efficiently distribute data using incremental replication.
• Distributed Architecture: Supports master-master setups with automatic conflict detection. It is highly available, partition tolerant, and follows an eventually consistent model.
• Real-time Features: Provides real-time change notifications and on-the-fly document transformation.
• Administration: Includes a built-in web administration console.
• Data Safety: Uses a fault-tolerant storage engine designed to prioritize data integrity.

Fabric is a collection of proxy functions designed for CouchDB cluster operations. It acts as a set of remote procedure endpoints executed on each node within a cluster.

Fabric handles complex clustered tasks by ensuring that operations (such as creating a database) are distributed to every node responsible for storing a shard. The node receiving the initial request uses Fabric to execute these functions across the cluster and then compiles the results into a single response for the client. Fabric is intended to be used in conjunction with 'Rexi'.

Rexi is a specialized RPC (Remote Procedure Call) server application designed for sending CouchDB operations to nodes within a cluster. It is optimized for high-performance scenarios where many remote processes need to be spawned.

Key characteristics include:

• Efficiency: Optimized for spawning local processes on the remote server from the remote Rexi server itself, rather than spawning them from the origin. This reduces overhead compared to the standard Erlang/OTP rex server.
• Resilience: The request-handling process does not block when attempting to connect to overloaded or dead nodes. Instead, rexi_DOWN messages are sent to the client eventually, providing a balance of low latency and reliable failure detection.
• Integration: Primarily used in BigCouch to execute Fabric functions on remote cluster nodes, but can be used as a standalone component.

Mem3 is the node membership application used in clustered CouchDB (since version 2.0). It manages two critical cluster components:

1. Member nodes: Tracks which nodes are part of the cluster.
2. Node/shards mappings: Tracks which shards for each database reside on which nodes.

Data is stored in node-local CouchDB databases and synchronized across the cluster via continuous CouchDB replication (acting as a 'gossip' protocol). To ensure low-latency lookups, an ETS cache is maintained for shards, which is kept in sync using membership and database event listeners.

couch_peruser is a CouchDB application designed to automatically manage private, per-user databases. For every document created in the _users database, this application ensures a corresponding private database exists. These databases are writable only by the authenticated user they belong to.

Database naming convention: Databases are named using the format userdb-{hex encoded username}. This hex encoding of the UTF-8 username ensures compatibility with CouchDB database naming restrictions, as CouchDB usernames themselves have no such restrictions.

Ken is a component responsible for the automatic building of views and search indexes in CouchDB.

It operates based on couch_db_update events:

• updated event: Ken spawns indexing jobs for view groups and search indexes. It creates one job per view group shard or search index shard.
• deleted event: Ken removes all jobs associated with the corresponding database shard.

couch_stats is a statistics collection application for Erlang applications. It implements counters, gauges, and histograms using Erlang's counters module.

By default, histograms record data in 10-second windows with a granularity of 1 second. You can retrieve the current values of all counters, gauges, and histogram statistics by calling couch_stats:fetch().

CouchDB uses a schema-free document model designed to mirror real-world data. Unlike relational databases that use abstract references (foreign keys) to link data across tables, CouchDB encourages self-contained documents.

Key concepts include:

• Self-Contained Data: Storing all pertinent information for a record (e.g., an invoice with buyer, seller, and items) within a single document to avoid complex joins.
• Syntax vs. Semantics: Documents of the same type (e.g., business cards) share the same semantics (the type of information carried) but can vary in syntax (the structure of that information). CouchDB's schema-free design allows you to aggregate data after the fact rather than requiring a rigid upfront model.
• Web-Centric Design: The architecture is built around web principles, utilizing HTTP resources, methods, and representations.

Replication in CouchDB is an incremental, one-way process between two databases: a source and a destination.

Key behaviors:

• Goal: Ensures all active documents in the source exist in the destination, and all documents deleted in the source are also deleted in the destination.
• Revision Handling: The process only copies the last revision of a document. Previous revisions that exist only in the source database are not copied to the destination.