0
# PouchDB
1
2
PouchDB is an open-source JavaScript database inspired by Apache CouchDB that is designed to run well within the browser and Node.js. PouchDB was created to help web developers build applications that work as well offline as they do online, providing seamless data synchronization between local and remote databases.
3
4
## Package Information
5
6
- **Package Name**: pouchdb
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install pouchdb`
10
11
## Core Imports
12
13
For Node.js environments:
14
15
```javascript
16
const PouchDB = require('pouchdb');
17
```
18
19
For ES modules:
20
21
```javascript
22
import PouchDB from 'pouchdb';
23
```
24
25
For browsers, include the script:
26
27
```html
28
<script src="pouchdb.js"></script>
29
<!-- PouchDB is available as global variable -->
30
```
31
32
## Basic Usage
33
34
```javascript
35
const PouchDB = require('pouchdb');
36
37
// Create a database
38
const db = new PouchDB('my-database');
39
40
// Create a document
41
await db.put({
42
_id: 'user1',
43
name: 'Alice',
44
email: 'alice@example.com'
45
});
46
47
// Retrieve a document
48
const user = await db.get('user1');
49
console.log(user.name); // 'Alice'
50
51
// Get all documents
52
const result = await db.allDocs({ include_docs: true });
53
console.log(result.rows);
54
55
// Listen for changes
56
const changes = db.changes({
57
since: 'now',
58
live: true,
59
include_docs: true
60
}).on('change', function(info) {
61
console.log('Change detected:', info);
62
});
63
64
// Replicate with remote database
65
const sync = PouchDB.sync(db, 'http://localhost:5984/remote-db', {
66
live: true,
67
retry: true
68
}).on('change', function(info) {
69
console.log('Sync change:', info);
70
});
71
```
72
73
## Architecture
74
75
PouchDB is built around several key architectural components:
76
77
- **Adapter System**: Pluggable storage backends for different environments (LevelDB for Node.js, IndexedDB for browsers, HTTP for remote CouchDB)
78
- **Plugin Architecture**: Extensible system allowing additional functionality through plugins
79
- **Event-Driven**: EventEmitter-based architecture for changes, replication, and database lifecycle events
80
- **Promise-Based API**: Modern async API with Promise support and callback compatibility
81
- **CouchDB Compatibility**: Full compatibility with CouchDB's HTTP API and replication protocol
82
- **Offline-First Design**: Built for applications that work equally well online and offline
83
84
The adapter system allows PouchDB to automatically choose the best storage mechanism for each environment while maintaining a consistent API across all platforms.
85
86
## Capabilities
87
88
### Database Creation and Management
89
90
Core database lifecycle operations including creation, configuration, information retrieval, and cleanup.
91
92
```javascript { .api }
93
// Constructor
94
new PouchDB(name: string, options?: PouchDBOptions): PouchDB;
95
96
// Database information and management
97
db.info(): Promise<DatabaseInfo>;
98
db.destroy(options?: DestroyOptions): Promise<void>;
99
db.close(): Promise<void>;
100
db.compact(options?: CompactOptions): Promise<CompactResponse>;
101
```
102
103
[Database Management](./database-management.md)
104
105
### Document Operations
106
107
Complete CRUD operations for documents including creation, retrieval, updates, deletions, and bulk operations.
108
109
```javascript { .api }
110
db.put(document: Document, options?: PutOptions): Promise<PutResponse>;
111
db.get(docId: string, options?: GetOptions): Promise<Document>;
112
db.post(document: Document, options?: PostOptions): Promise<PostResponse>;
113
db.remove(document: Document | string, options?: RemoveOptions): Promise<RemoveResponse>;
114
db.bulkDocs(documents: Document[], options?: BulkDocsOptions): Promise<BulkResponse[]>;
115
db.allDocs(options?: AllDocsOptions): Promise<AllDocsResponse>;
116
```
117
118
[Document Operations](./document-operations.md)
119
120
### Changes and Monitoring
121
122
Real-time monitoring of database changes with filtering, continuous feeds, and event-driven updates.
123
124
```javascript { .api }
125
db.changes(options?: ChangesOptions): Changes;
126
```
127
128
[Changes and Monitoring](./changes-monitoring.md)
129
130
### Replication and Synchronization
131
132
Bidirectional synchronization with remote databases, including continuous replication and conflict resolution.
133
134
```javascript { .api }
135
// Instance methods
136
db.replicate.from(source: string | PouchDB, options?: ReplicationOptions): Replication;
137
db.replicate.to(target: string | PouchDB, options?: ReplicationOptions): Replication;
138
db.sync(remoteDB: string | PouchDB, options?: SyncOptions): Sync;
139
140
// Static methods
141
PouchDB.replicate(source: string | PouchDB, target: string | PouchDB, options?: ReplicationOptions): Replication;
142
PouchDB.sync(source: string | PouchDB, target: string | PouchDB, options?: SyncOptions): Sync;
143
```
144
145
[Replication and Synchronization](./replication-sync.md)
146
147
### Plugin and Adapter System
148
149
Extensible architecture for adding functionality and storage backends.
150
151
```javascript { .api }
152
// Plugin system
153
PouchDB.plugin(plugin: Plugin): typeof PouchDB;
154
155
// Adapter management
156
PouchDB.adapter(name: string, adapter: Adapter, addToPreferred?: boolean): void;
157
PouchDB.defaults(options: PouchDBOptions): typeof PouchDB;
158
```
159
160
[Plugins and Adapters](./plugins-adapters.md)
161
162
## Types
163
164
```javascript { .api }
165
interface PouchDBOptions {
166
adapter?: string;
167
auto_compaction?: boolean;
168
revs_limit?: number;
169
view_adapter?: string;
170
purged_infos_limit?: number;
171
[key: string]: any;
172
}
173
174
interface Document {
175
_id: string;
176
_rev?: string;
177
_attachments?: { [name: string]: Attachment };
178
_deleted?: boolean;
179
[key: string]: any;
180
}
181
182
interface DatabaseInfo {
183
db_name: string;
184
doc_count: number;
185
update_seq: number | string;
186
purge_seq?: number | string;
187
compact_running: boolean;
188
disk_size?: number;
189
data_size?: number;
190
instance_start_time: string;
191
host: string;
192
auto_compaction?: boolean;
193
}
194
195
interface PutResponse {
196
ok: boolean;
197
id: string;
198
rev: string;
199
}
200
201
interface GetOptions {
202
rev?: string;
203
revs?: boolean;
204
revs_info?: boolean;
205
conflicts?: boolean;
206
attachments?: boolean;
207
binary?: boolean;
208
}
209
210
interface AllDocsOptions {
211
include_docs?: boolean;
212
startkey?: string;
213
endkey?: string;
214
limit?: number;
215
skip?: number;
216
descending?: boolean;
217
keys?: string[];
218
}
219
220
interface ChangesOptions {
221
since?: number | string;
222
limit?: number;
223
descending?: boolean;
224
include_docs?: boolean;
225
conflicts?: boolean;
226
attachments?: boolean;
227
live?: boolean;
228
continuous?: boolean;
229
heartbeat?: number;
230
timeout?: number;
231
filter?: string | Function;
232
view?: string;
233
doc_ids?: string[];
234
}
235
236
interface ReplicationOptions {
237
continuous?: boolean;
238
retry?: boolean;
239
filter?: string | Function;
240
query_params?: object;
241
doc_ids?: string[];
242
checkpoint?: string | boolean;
243
batch_size?: number;
244
batches_limit?: number;
245
}
246
```