0
# PouchDB
1

2
PouchDB is a pocket-sized database designed to run both in web browsers and Node.js environments. It provides a complete database solution with built-in replication functionality that enables seamless data synchronization between local and remote CouchDB-compatible databases. PouchDB allows applications to work reliably offline and online with automatic conflict resolution, incremental data transfer, and comprehensive event handling.
3

4
## Package Information
5

6
- **Package Name**: pouchdb  
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript support)
9
- **Installation**: `npm install pouchdb`
10

11
## Core Imports
12

13
```javascript
14
import PouchDB from 'pouchdb';
15
```
16

17
CommonJS:
18

19
```javascript
20
const PouchDB = require('pouchdb');
21
```
22

23
Browser (via CDN):
24

25
```html
26
<script src="https://cdn.jsdelivr.net/npm/pouchdb@9.0.0/dist/pouchdb.min.js"></script>
27
```
28

29
## Basic Usage
30

31
```javascript
32
import PouchDB from 'pouchdb';
33

34
// Create a local database
35
const localDB = new PouchDB('my-local-database');
36

37
// Create documents
38
await localDB.put({
39
  _id: 'user_001',
40
  name: 'Alice Johnson',
41
  email: 'alice@example.com',
42
  active: true
43
});
44

45
// Retrieve documents
46
const doc = await localDB.get('user_001');
47
console.log(doc.name); // "Alice Johnson"
48

49
// List all documents
50
const allDocs = await localDB.allDocs({
51
  include_docs: true
52
});
53

54
// Set up replication to a remote database
55
const remoteDB = 'https://myserver.com/mydb';
56
const replication = PouchDB.replicate(localDB, remoteDB, {
57
  live: true,
58
  retry: true
59
});
60

61
replication.on('change', (info) => {
62
  console.log('Replication change:', info);
63
});
64
```
65

66
## Architecture
67

68
PouchDB is built around several key architectural components:
69

70
- **Database Constructor**: Creates database instances with automatic adapter selection (LevelDB for Node.js, IndexedDB for browsers)
71
- **Plugin System**: Extensible architecture allowing custom adapters and functionality extensions
72
- **CRUD Operations**: Complete document lifecycle management with conflict detection and resolution
73
- **Replication Engine**: Comprehensive sync system with incremental updates, filtering, and robust error handling
74
- **Changes Feed**: Real-time change notifications with filtering and live update capabilities
75
- **Event System**: EventEmitter-based architecture for monitoring database and replication events
76

77
## Capabilities
78

79
### Database Operations
80

81
Core CRUD operations for document management, including creation, retrieval, updates, and deletion with full conflict resolution.
82

83
```javascript { .api }
84
/**
85
 * PouchDB constructor creates a new database instance
86
 * @param name - Database name (local) or URL (remote)
87
 * @param options - Configuration options
88
 */
89
function PouchDB(name, options);
90

91
/**
92
 * Create or update a document
93
 * @param doc - Document object with _id and optional _rev
94
 * @param options - Optional parameters like batch mode
95
 * @returns Promise resolving to operation result
96
 */
97
db.put(doc, options);
98

99
/**
100
 * Retrieve a document by ID
101
 * @param docId - Document identifier
102
 * @param options - Optional parameters like rev, revs
103
 * @returns Promise resolving to document
104
 */
105
db.get(docId, options);
106

107
/**
108
 * Create a new document with auto-generated ID
109
 * @param doc - Document object without _id
110
 * @param options - Optional parameters
111
 * @returns Promise resolving to operation result with generated ID
112
 */
113
db.post(doc, options);
114

115
/**
116
 * Delete a document
117
 * @param docOrId - Document object or document ID
118
 * @param optsOrRev - Options object or revision string
119
 * @returns Promise resolving to operation result
120
 */
121
db.remove(docOrId, optsOrRev);
122
```
123

124
[Database Operations](./database-operations.md)
125

126
### Replication & Synchronization
127

128
Comprehensive replication system supporting one-way and bidirectional sync with extensive configuration options, filtering, and conflict resolution.
129

130
```javascript { .api }
131
/**
132
 * Static method to replicate from source to target
133
 * @param source - Source database (PouchDB instance or URL)
134
 * @param target - Target database (PouchDB instance or URL)  
135
 * @param options - Replication configuration
136
 * @returns Replication object with event emitter interface
137
 */
138
PouchDB.replicate(source, target, options);
139

140
/**
141
 * Static method for bidirectional synchronization
142
 * @param source - First database (PouchDB instance or URL)
143
 * @param target - Second database (PouchDB instance or URL)
144
 * @param options - Sync configuration
145
 * @returns Sync object with event emitter interface
146
 */
147
PouchDB.sync(source, target, options);
148

149
/**
150
 * Instance method to replicate this database to target
151
 * @param target - Target database (PouchDB instance or URL)
152
 * @param options - Replication configuration
153
 * @returns Replication object with event emitter interface
154
 */
155
db.replicate.to(target, options);
156

157
/**
158
 * Instance method to replicate from source to this database
159
 * @param source - Source database (PouchDB instance or URL)
160
 * @param options - Replication configuration
161
 * @returns Replication object with event emitter interface
162
 */
163
db.replicate.from(source, options);
164

165
/**
166
 * Instance method for bidirectional sync with target
167
 * @param target - Target database (PouchDB instance or URL)
168
 * @param options - Sync configuration
169
 * @returns Sync object with event emitter interface
170
 */
171
db.sync(target, options);
172
```
173

174
[Replication & Synchronization](./replication-sync.md)
175

176
### Changes & Events
177

178
Real-time change monitoring with filtering, live updates, and comprehensive event handling for both database changes and replication events.
179

180
```javascript { .api }
181
/**
182
 * Listen to database changes
183
 * @param options - Changes configuration including live, since, filter
184
 * @returns Changes object with event emitter interface
185
 */
186
db.changes(options);
187

188
/**
189
 * Add event listener
190
 * @param event - Event name (change, complete, error, etc.)
191
 * @param handler - Event handler function
192
 */
193
db.on(event, handler);
194

195
/**
196
 * Add one-time event listener
197
 * @param event - Event name
198
 * @param handler - Event handler function
199
 */
200
db.once(event, handler);
201
```
202

203
[Changes & Events](./changes-events.md)
204

205
### Bulk Operations & Queries
206

207
Efficient bulk document operations and comprehensive querying capabilities including all documents retrieval with extensive filtering options.
208

209
```javascript { .api }
210
/**
211
 * Create, update, or delete multiple documents in a single operation
212
 * @param docs - Array of document objects or object with docs array
213
 * @param options - Bulk operation configuration
214
 * @returns Promise resolving to array of operation results
215
 */
216
db.bulkDocs(docs, options);
217

218
/**
219
 * Retrieve all documents with optional filtering and pagination
220
 * @param options - Query options including keys, limit, skip, include_docs
221
 * @returns Promise resolving to query results
222
 */
223
db.allDocs(options);
224
```
225

226
[Bulk Operations & Queries](./bulk-queries.md)
227

228
### Attachments
229

230
Binary attachment management for storing and retrieving files associated with documents, supporting various content types.
231

232
```javascript { .api }
233
/**
234
 * Attach binary data to a document
235
 * @param docId - Document ID
236
 * @param attachmentId - Attachment identifier
237
 * @param rev - Document revision
238
 * @param blob - Binary data (Blob, Buffer, or string)
239
 * @param type - MIME type
240
 * @returns Promise resolving to operation result
241
 */
242
db.putAttachment(docId, attachmentId, rev, blob, type);
243

244
/**
245
 * Retrieve an attachment
246
 * @param docId - Document ID
247
 * @param attachmentId - Attachment identifier
248
 * @param options - Retrieval options
249
 * @returns Promise resolving to attachment data
250
 */
251
db.getAttachment(docId, attachmentId, options);
252

253
/**
254
 * Remove an attachment from a document
255
 * @param docId - Document ID
256
 * @param attachmentId - Attachment identifier
257
 * @param rev - Document revision
258
 * @returns Promise resolving to operation result
259
 */
260
db.removeAttachment(docId, attachmentId, rev);
261
```
262

263
[Attachments](./attachments.md)
264

265
## Static Properties & Methods
266

267
```javascript { .api }
268
/**
269
 * Registry of available database adapters
270
 */
271
PouchDB.adapters: { [key: string]: any };
272

273
/**
274
 * List of preferred adapters in order of preference
275
 */
276
PouchDB.preferredAdapters: string[];
277

278
/**
279
 * Default prefix for database names
280
 */
281
PouchDB.prefix: string;
282

283
/**
284
 * PouchDB version string
285
 */
286
PouchDB.version: string;
287

288
/**
289
 * Register a database adapter
290
 * @param name - Adapter name
291
 * @param adapter - Adapter implementation
292
 * @param preferred - Add to preferred adapters list
293
 */
294
PouchDB.adapter(name, adapter, preferred);
295

296
/**
297
 * Add plugin functionality
298
 * @param plugin - Plugin function or object
299
 */
300
PouchDB.plugin(plugin);
301

302
/**
303
 * Create PouchDB constructor with default options
304
 * @param defaultOptions - Default configuration
305
 * @returns PouchDB constructor with defaults
306
 */
307
PouchDB.defaults(defaultOptions);
308
```
309

310
## Core Types
311

312
```javascript { .api }
313
interface PouchDBOptions {
314
  /** Database adapter to use */
315
  adapter?: string;
316
  /** Auto-compaction enabled */
317
  auto_compaction?: boolean;
318
  /** Database prefix */
319
  prefix?: string;
320
  /** Additional adapter-specific options */
321
  [key: string]: any;
322
}
323

324
interface DocumentResponse {
325
  /** Operation success status */
326
  ok: boolean;
327
  /** Document ID */
328
  id: string;
329
  /** New document revision */
330
  rev: string;
331
}
332

333
interface AllDocsOptions {
334
  /** Include full document content */
335
  include_docs?: boolean;
336
  /** Array of specific document IDs to retrieve */
337
  keys?: string[];
338
  /** Maximum number of documents to return */
339
  limit?: number;
340
  /** Number of documents to skip */
341
  skip?: number;
342
  /** Reverse result order */
343
  descending?: boolean;
344
  /** Start key for range queries */
345
  startkey?: any;
346
  /** End key for range queries */
347
  endkey?: any;
348
}
349

350
interface ReplicationOptions {
351
  /** Continuous replication */
352
  live?: boolean;
353
  /** Retry on failure */
354
  retry?: boolean;
355
  /** Document filter function */
356
  filter?: string | Function;
357
  /** Specific document IDs to replicate */
358
  doc_ids?: string[];
359
  /** Batch size for replication */
360
  batch_size?: number;
361
  /** Number of batches to process in parallel */
362
  batches_limit?: number;
363
  /** Use checkpoints */
364
  checkpoint?: boolean;
365
}
366
```