Guide: Introduction

TouchDB In A Nutshell

by Jens Alfke

This is a standalone introduction to TouchDB, an embeddable NoSQL database library that's compatible with Apache CouchDB. It doesn't assume any familiarity with CouchDB, just knowledge of writing apps for your platform (iOS or Android). Those who are familiar with CouchdB will want to read section 4, which covers how TouchDB is different.

THIS DOCUMENT IS INCOMPLETE. It's under active development (as of late July 2012); new sections are being added and content is being polished. Your feedback is greatly welcomed.

1. Introduction

TouchDB is a lightweight database library, ready to be linked into mobile and desktop apps. In this way it's similar to the ubiquitous SQLite. (In fact, it's actually built on top of SQLite.) But TouchDB is based on the same architecture as Apache CouchDB, which gives it a number of good features:

• It supports replication with CouchDB-compatible database servers. This gives your app best-of-breed sync capabilities. Not only can the user's data stay in sync across multiple devices, but multiple users' data can be synced together.
• It supports low-latency and even offline access to data. In contrast with the frequent network request/response cycle of a traditional networked app, you work primarily with local data. This means your app remains responsive whether it's on WiFi, or a slow cell network, or even completely offline. The user can even modify data while offline, and it'll be synced to the server as soon as possible.
• It supports peer-to-peer replication too -- by adding an extra HTTP listener component, your app can accept connections from other devices running TouchDB and exchange data with them.
• It's schemaless. (The somewhat-misleading buzzword for this is "NoSQL".) This means that you don't have to define a rigid data layout beforehand, and later go through complex migrations if you need to update it. Data layout is somewhat freeform, and records (called "documents") can have different structures. A sophisticated map/reduce query engine lets you perform efficient queries, even on large data sets, regardless of how you structure your documents' data.
• It's JSON-based. Every document/record is a JSON object consisting of freeform key/value pairs. The values can contain arrays or even nested objects. (If you're familiar with Cocoa's property-list format, JSON is almost identical.) This lets you structure your data in a way that's natural to your app, without having to deal with complex data normalization or joins.
• It gives you a choice of APIs. There are high-level object-oriented APIs that integrate with your app framework (CouchCocoa on iOS and Mac OS, Ektorp on Android.) These APIs can map database documents to your own object model, or let you work directly with JSON structures, or both. Or apps based on Web technologies like PhoneGap can interact with TouchDB by calling a CouchDB-compatible REST API from JavaScript.
• It's open. TouchDB is open-source, as is CouchDB. The replication protocol is documented. You can use a hosted server or run your own. This is in contrast to similar technologies like iCloud, DropBox and Simperium.