API reference › @evolu/common › local‑first/Schema › QuarantineReason

const QuarantineReason: {
  Schema: 0;
  TimestampDrift: 1;
};

Defined in: packages/common/src/local-first/Schema.ts:349

Why a message is stored in evolu_message_quarantine instead of being applied to its table. Persisted codes: names may change, but numbers must not be reassigned.

Quarantine is queryable state, not an error. An application subscribes to a query over evolu_message_quarantine to tell the user what is waiting. Each row is one column of a message, so distinct ownerId and timestamp pairs count messages. origin records whether this database stamped the message for a local mutation or received it from sync, see QuarantineOrigin. quarantinedAt is the system time captured for the request that quarantined the row, in milliseconds; it is null for rows written before Evolu recorded it. The clock-drift rules are described in the Timestamp module.

Example

import {
  assertType,
  createQueryBuilder,
  type Millis,
  type OwnerIdBytes,
  type QuarantineOrigin,
  QuarantineReason,
  testEvoluSchema,
  type TimestampBytes,
} from "@evolu/common";

const createQuery = createQueryBuilder(testEvoluSchema);

// Messages waiting in drift quarantine, one row per message.
const driftQuarantineQuery = createQuery((db) =>
  db
    .selectFrom("evolu_message_quarantine")
    .select(["ownerId", "timestamp", "origin", "quarantinedAt"])
    .where("reason", "=", QuarantineReason.TimestampDrift)
    .distinct(),
);

assertType<
  typeof driftQuarantineQuery.Row,
  {
    ownerId: OwnerIdBytes;
    timestamp: TimestampBytes;
    origin: QuarantineOrigin;
    quarantinedAt: Millis | null;
  }
>();

Type Declaration

NameTypeDefault valueDescriptionDefined in
Schema00The message has a table or column the current schema does not define. It is applied automatically once a schema update defines them.packages/common/src/local-first/Schema.ts:354
TimestampDrift11The message's timestamp exceeded the drift limit when it was stored. It is applied when the database worker starts, once system time comes within the limit of the timestamp.packages/common/src/local-first/Schema.ts:360
Markdown for LLMs