The Complete Production SOP: How to Deploy and Run PouchDB In-Browser Database & Cloud Sync in Autonomous AI Agents

---
name: "pouchdb-offline-sync-replication"
description: "Store data locally in IndexedDB and synchronize bi-directionally with remote CouchDB."
metadata:
  author: "PouchDB"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "sync pouchdb with couchdb"
  - "query pouchdb with mango find"
  - "handle offline pouchdb sync"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# PouchDB In-Browser Database & Cloud Sync SOP
1. Initialize: const localDB = new PouchDB('app_data', { auto_compaction: true });
2. Replicate: localDB.sync(remoteDB, { live: true, retry: true, back_off_function: (delay) => (delay === 0 ? 1000 : Math.min(delay * 3, 60000)) });
3. Index: await localDB.createIndex({ index: { fields: ['status', 'createdAt'] } });
4. Query: await localDB.find({ selector: { status: 'active' }, sort: ['createdAt'] });

import PouchDB from 'pouchdb-browser';
import PouchDBFind from 'pouchdb-find';

PouchDB.plugin(PouchDBFind);

export interface TaskDocument {
  _id: string;
  _rev?: string;
  status: 'active' | 'completed';
  createdAt: string;
  title: string;
}

export const localDB = new PouchDB<TaskDocument>('tasks_local', { auto_compaction: true });
export const remoteDB = new PouchDB<TaskDocument>(process.env.VITE_COUCHDB_REMOTE_URL || '');

export function initializeSync() {
  return localDB.sync(remoteDB, {
    live: true,
    retry: true
  }).on('change', (info) => {
    console.info('PouchDB sync change:', info);
  }).on('paused', (err) => {
    console.info('PouchDB sync paused', err ? 'due to network error' : 'idle');
  }).on('active', () => {
    console.info('PouchDB sync resumed');
  }).on('error', (err) => {
    console.error('Fatal PouchDB sync error:', err);
  });
}

import { describe, it, expect, beforeEach } from 'vitest';
import PouchDB from 'pouchdb';
import PouchDBAdapterMemory from 'pouchdb-adapter-memory';
import PouchDBFind from 'pouchdb-find';

PouchDB.plugin(PouchDBAdapterMemory);
PouchDB.plugin(PouchDBFind);

describe('PouchDB Offline-First SOP Verification', () => {
  let testDB: PouchDB.Database;

  beforeEach(async () => {
    testDB = new PouchDB('test_mem_db', { adapter: 'memory' });
    await testDB.createIndex({ index: { fields: ['status', 'createdAt'] } });
  });

  it('creates and executes mango find queries offline', async () => {
    await testDB.put({ _id: 'task_001', status: 'active', createdAt: '2026-03-30T10:00:00Z', title: 'Verify SOP' });
    const result = await testDB.find({
      selector: { status: 'active' },
      sort: ['status', 'createdAt']
    });
    expect(result.docs).toHaveLength(1);
    expect(result.docs[0]._id).toBe('task_001');
  });
});