Attachments and adapters

PouchORM exposes the underlying PouchDB database and constructor for features that do not need collection-level handling.

Work with attachments

Every collection has a db property:

// Attachment writes require the document's current revision.
await people.db.putAttachment(
  person._id!,
  "avatar.png",
  person._rev!,
  avatarBlob,
  "image/png",
);

const avatar = await people.db.getAttachment(person._id!, "avatar.png");

Use the current _rev when adding, replacing, or removing an attachment. Read the updated document before another write when the attachment operation changes its revision.

Add a PouchDB plugin

PouchDB is a peer dependency, so the application and PouchORM use the same constructor. Add plugins before opening a database:

import myPlugin from "pouchdb-example-plugin";
import { PouchORM } from "pouchorm";

// Install plugins before any collection opens a database.
PouchORM.PouchDB.plugin(myPlugin);

PouchORM installs pouchdb-find itself.

Use a custom PouchDB build

Some platforms use a custom PouchDB constructor or a selected set of adapters:

import CustomPouchDB from "pouchdb-core";
import { PouchORM } from "pouchorm";

// Configure one constructor for all databases managed by PouchORM.
PouchORM.usePouchDB(CustomPouchDB);

Call usePouchDB before any collection or database is opened. PouchORM rejects later changes so existing databases cannot silently use a different constructor.

Configure a local adapter

Set the default adapter before opening a database:

// Register the adapter before selecting it by name.
PouchORM.PouchDB.plugin(memoryAdapter);
PouchORM.adapter = "memory";

Or pass PouchDB options from a collection:

super({
  database: "app-data",
  collection: "people",
  pouch: { adapter: "idb" },
});

The first call that opens a named database determines its constructor options.

Write raw documents carefully

Raw writes bypass collection metadata and validation. Raw deletions also bypass collection ownership checks and may not call onChangeDeleted. If a document must appear in collection queries, set $collectionType to the exact collection.collectionName value. Prefer collection methods for application documents unless the raw operation is intentional.