Готовые движки: WatermelonDB и PowerSync

У WatermelonDB нет журнала операций. Совсем: ни таблицы изменений, ни очереди — есть записи, у которых две служебные колонки. Они объявлены в RawRecord/index.d.ts и стоят у каждой записи любой таблицы: _status — что с записью случилось с прошлой синхронизации, _changed — имена изменённых колонок через запятую. Удаление тоже состояние: markAsDeleted() помечает запись, и в типах рядом с ним стоит примечание авторов «Use this only with Sync», а рядом с destroyPermanently() — обратное, «Don't use this when using Sync». Это наше надгробие из статьи «Удаление — это запись», только служебное и спрятанное от вас.

Синхронизация здесь — одна функция, и вся её форма видна в типах:

// @nozbe/watermelondb 0.28.0 — сокращено до того, чем пользуются

// две служебные колонки есть у каждой записи любой таблицы (RawRecord/index.d.ts)
type SyncStatus = "synced" | "created" | "updated" | "deleted" | "disposable";
type RawRecord = { id: string; _status: SyncStatus; _changed: string };

// то, что едет по сети: три ключа на таблицу, у удалённых — одни идентификаторы
type SyncTableChangeSet = { created: DirtyRaw[]; updated: DirtyRaw[]; deleted: string[] };
type SyncDatabaseChangeSet = { [table: string]: SyncTableChangeSet };

declare function synchronize(args: {
  database: Database;
  // курсор — время сервера: он же возвращает новое в timestamp
  pullChanges: (args: {
    lastPulledAt?: number;
    schemaVersion: number;
    migration: MigrationSyncChanges;
  }) => Promise<{ changes: SyncDatabaseChangeSet; timestamp: number }>;
  // весь ответ на пачку — список отвергнутых id записей, без причин
  pushChanges?: (args: {
    changes: SyncDatabaseChangeSet;
    lastPulledAt: number;
  }) => Promise<{ experimentalRejectedIds?: { [table: string]: string[] } } | undefined | void>;
  migrationsEnabledAtVersion?: number;
  conflictResolver?: (table: string, local: DirtyRaw, remote: DirtyRaw, resolved: DirtyRaw) => DirtyRaw;
}): Promise<void>;

Узнаваемого много. pullChanges — это sync.pull, только курсор у него не номер сервера, а время: lastPulledAt приходит из прошлого ответа, новое сервер возвращает в timestamp. Чем опасно время вместо номера, глава разобрала в первой же статье, «Сервер — партнёр, а не хозяин»; спасает тут ровно одно — что время это серверное, одно на всех, а не показания часов телефона. pushChanges — это sync.push, но ответ у него куда беднее: experimentalRejectedIds, список отвергнутых идентификаторов записей по таблицам. Ни причины, ни вердикта по каждой операции — потому что операций здесь нет вовсе, и слово «experimental» в имени стоит не случайно.

Переведём журнал «Подхода» в этот формат. Телефон записал два подхода и синхронизировался; потом, уже без сети, поправил вес в первом, добавил третий и удалил второй. Переходнику достаются журнал, исходящая очередь и хранилище. Прогноз: в какой из трёх ключей попадёт каждая строка, что окажется внутри updated — одно поле или целая строка — и найдутся ли в changes имя операции и отметка времени?

type Fields = Record<string, string | number | boolean>;
type Row = Fields & { id: string };
type Op = { opId: string; rowId: string; fields: Fields; at: number };
interface Store {
  get(id: string): Row | undefined;
  visible(): Row[];
}
interface Journal {
  newId(): string;
  change(rowId: string, fields: Fields): void;
  remove(rowId: string): void;
  outbox(): Op[];
}
interface Client {
  store: Store;
  journal: Journal;
  queue(): Op[];
  sync(): unknown[];
}
interface Server {
  rows: Map<string, Row>;
  net: { offline: boolean; loseResponse: boolean; unauthorized: boolean };
}
declare function createServer(): Server;
declare function createClient(device: string, server: Server): Client;

// формат WatermelonDB: журнала нет, отметки лежат в самой записи
type Dirty = Row & { _status: "created" | "updated"; _changed: string };
type Changes = { created: Dirty[]; updated: Dirty[]; deleted: string[] };

function toWatermelon(log: Op[], queue: Op[], store: Store): Changes {
  const created: Dirty[] = [];
  const updated: Dirty[] = [];
  const deleted: string[] = [];
  for (const rowId of [...new Set(queue.map((op) => op.rowId))]) {
    const row = store.get(rowId) as Row;
    if (row.deleted) {
      deleted.push(rowId);
      continue;
    }
    const mine = queue.filter((op) => op.rowId === rowId);
    // «новая» — та, чья первая операция ещё не уехала: у Watermelon это _status
    const birth = log.find((op) => op.rowId === rowId) as Op;
    const status = mine.some((op) => op.opId === birth.opId) ? "created" : "updated";
    const changed = [...new Set(mine.flatMap((op) => Object.keys(op.fields)))];
    (status === "created" ? created : updated).push({
      ...row,
      _status: status,
      _changed: status === "created" ? "" : changed.join(","),
    });
  }
  return { created, updated, deleted };
}

const server = createServer();
const phone = createClient("A", server);
const bench = phone.journal.newId();
phone.journal.change(bench, { exercise: "жим", weightKg: 80, reps: 5 });
const squat = phone.journal.newId();
phone.journal.change(squat, { exercise: "присед", weightKg: 100, reps: 5 });
phone.sync();

// после синхронизации: правка старого подхода, новый подход и удаление
phone.journal.change(bench, { weightKg: 82.5 });
const deadlift = phone.journal.newId();
phone.journal.change(deadlift, { exercise: "тяга", weightKg: 120, reps: 3 });
phone.journal.remove(squat);

const changes = toWatermelon(phone.journal.outbox(), phone.queue(), phone.store);
console.log("created:", JSON.stringify(changes.created));
console.log("updated:", JSON.stringify(changes.updated));
console.log("deleted:", JSON.stringify(changes.deleted));
console.log("операций в очереди:", phone.queue().length);
const edit = changes.updated[0];
console.log("у правки есть opId:", "opId" in edit, "| есть at:", "at" in edit);

Три строки разошлись по трём ключам ровно так, как ждёт synchronize: новая — в created, правленая — в updated, удалённая — в deleted, и там только идентификатор. А дальше начинается цена. В updated уехала вся строка целиком — упражнение, вес и повторы, — хотя человек трогал один вес. Это не вольность переходника: в исходнике sync/impl/fetchLocal.js так и написано, changeSet.updated.push(Object.assign({}, record._raw)), а рядом честный TODO авторов: «It would probably also be good to only send to server locally changed fields, not full records».

Вторая половина цены — в последней строке прогона. Ни opId, ни at в changes нет, и положить их некуда: формат описывает состояние записи, а не изменение. Значит, всё, что глава на них построила, придётся строить заново и снаружи. Память вердиктов из статьи «Ответ потерялся» ключевать нечем: у повторной пачки те же идентификаторы записей, что у первой, и отличить повтор от новой правки сервер не сможет. Слияние по отметкам полей из статьи «Кто прав, если оба правы» серверу тоже не из чего собрать — он получает готовую строку.

Служебные колонки всё-таки уезжают на сервер: в том же fetchLocal.js стоит TODO «It would be best to omit _status, _changed fields». А вот присылать их обратно нельзя — applyRemote.js проверяет пришедшее и ругается, что записи «must NOT have a '_status' or '_changed' fields». Мелочь, на которой спотыкается первый же самописный сервер к WatermelonDB.

Кажется, что модель «по состоянию» обязана решать споры целой строкой — тем самым «последняя запись побеждает», которое статья «Кто прав, если оба правы» разобрала как худшее из правил. Это не так, и сказать об этом надо честно: у WatermelonDB слияние тоже по полям. Алгоритм лежит в sync/impl/helpers.js, и авторы описали его комментарием прямо над функцией: «This is a per-column resolution algorithm. All columns that were changed locally win and will be applied on top of the remote version».

Вот в этом «changed locally win» и разница. Наше правило сравнивает отметки [at, opId] и работает одинаково на обеих сторонах. Правило WatermelonDB спрашивает не «когда», а «моё ли»: колонки, перечисленные в _changed, ложатся поверх пришедшей версии. Проверим на одном случае: на телефоне поправили вес, а на сервере лежит версия, где чужие руки поправили и повторы, и тот же вес — причём позже. Прогноз: что получится каждым правилом и в чём они сойдутся?

type Fields = Record<string, string | number | boolean>;
type Row = Fields & { id: string };
type Op = { opId: string; rowId: string; fields: Fields; at: number };
type Mark = { at: number; opId: string };
declare function merge(row: Row | undefined, op: Op, mark: Record<string, Mark>): Row;

// разрешение конфликта WatermelonDB: колонки из _changed ложатся поверх пришедшей версии
type Local = Row & { _changed: string };
function resolveConflict(local: Local, remote: Row): Row {
  const resolved: Row = { ...local, ...remote, id: local.id };
  local._changed.split(",").forEach((column) => {
    resolved[column] = local[column];
  });
  return resolved;
}

// на телефоне поправили вес, на сервере лежит версия с чужими повторами и чужим весом
const local: Local = { id: "A-1", exercise: "жим", weightKg: 82.5, reps: 5, _changed: "weightKg" };
const remote: Row = { id: "A-1", exercise: "жим", weightKg: 85, reps: 12 };
const byChanged = resolveConflict(local, remote);
console.log("по _changed:", JSON.stringify(byChanged));

// те же четыре правки, сложенные нашим правилом: вес с телефона раньше чужого
const ops: Op[] = [
  { opId: "A:1", rowId: "A-1", fields: { exercise: "жим", weightKg: 80, reps: 5 }, at: 1 },
  { opId: "A:2", rowId: "A-1", fields: { weightKg: 82.5 }, at: 2 },
  { opId: "B:1", rowId: "A-1", fields: { reps: 12 }, at: 3 },
  { opId: "B:2", rowId: "A-1", fields: { weightKg: 85 }, at: 4 },
];
const marks: Record<string, Mark> = {};
let row: Row | undefined;
for (const op of ops) row = merge(row, op, marks);
console.log("по отметкам [at, opId]:", JSON.stringify(row));
console.log("вес: по _changed", byChanged.weightKg, "| по отметкам", (row as Row).weightKg);
console.log("повторы: по _changed", byChanged.reps, "| по отметкам", (row as Row).reps);

Сошлись в главном: оба сохранили чужие повторы 12 вместе со своим весом — это и есть слияние по полям, ни одна правка не пропала целиком. Разошлись в спорном поле. По _changed победил местный вес 82.5, хотя сделан он раньше чужого: про время это правило не спрашивает вовсе. По отметкам победила более поздняя правка, 85.

Правильного ответа тут нет: «моё побеждает» — осмысленный выбор, пока активное устройство одно, и он заметно дешевле, потому что отметку на каждое поле хранить не надо. Важно другое — где это правило живёт. У нас оно общее для телефона и сервера, поэтому итог у всех один. У WatermelonDB оно клиентское: сервер получает целую строку и решает чем угодно. Значит, «одно правило для обеих сторон» вы всё равно пишете руками, просто теперь только на своей стороне сервера.

Место, куда своё правило вписать на клиенте, у библиотеки есть — conflictResolver из тех же типов: (table, local, remote, resolved) => DirtyRaw. Рядом предупреждение авторов: это «Advanced (unsafe) customization point», зовётся он для каждой обновляемой записи, «so be sure that this function is FAST».

Ещё одна деталь, в которой видно нашу очередь: после удачной отправки WatermelonDB ставит записям _status: "synced" и _changed: "" — то есть «что менял» помнится ровно до подтверждения, как у нас операция лежит в очереди до вердикта. Разница в том, что у нас вердикт приходит по имени операции, а тут подтверждение молчаливое: пачка прошла целиком.

PowerSync подходит с другой стороны. У него есть настоящая очередь изменений, и она отдана вам в руки: getCrudBatch(limit?) — пачка записей, getNextCrudTransaction() — ровно одна транзакция целиком, и у обеих complete(), который убирает отправленное из очереди. В типах это сказано прямым текстом: «Once the data have been successfully uploaded, call CrudBatch.complete before requesting the next batch». Это наш цикл слово в слово: пачка уходит, очередь пустеет только по подтверждению.

Единица очереди — CrudEntry: clientId, id строки, table, op и opData. У op три значения, и описаны они в CrudEntry.d.ts так: PUT — «Insert or replace existing row. All non-null columns are included in the data», PATCH — «Contains the id, and value of each changed column», DELETE — «Contains the id». Средняя строка и есть наша операция: имя строки плюс изменённые поля.

Наверх при этом пишете вы сами. Коннектор — два метода:

// @powersync/react-native 2.3.0 и @powersync/common 2.3.0
import { PowerSyncDatabase, type PowerSyncBackendConnector } from "@powersync/react-native";

export const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: { dbFilename: "podhod.db" },
});

const connector: PowerSyncBackendConnector = {
  // этот токен нужен сервису PowerSync, который отдаёт телефону чужие изменения
  async fetchCredentials() {
    const token = await readToken();
    return token ? { endpoint: POWERSYNC_URL, token } : null;
  },
  // а наверх пишете вы сами — на свой сервер, тот самый sync.push
  async uploadData(database) {
    const tx = await database.getNextCrudTransaction();
    if (!tx) return;
    await syncPush(tx.crud);
    // очередь пустеет только здесь
    await tx.complete();
  },
};

await db.connect(connector);

Переведём в этот формат ту же очередь, что и в прошлый раз: правка старого подхода, новый подход и удаление. Прогноз: что окажется в opData у правки, чем станет надгробие и с каких чисел пойдёт clientId?

type Fields = Record<string, string | number | boolean>;
type Row = Fields & { id: string };
type Op = { opId: string; rowId: string; fields: Fields; at: number };
interface Store {
  get(id: string): Row | undefined;
}
interface Journal {
  newId(): string;
  change(rowId: string, fields: Fields): void;
  remove(rowId: string): void;
  outbox(): Op[];
}
interface Client {
  store: Store;
  journal: Journal;
  queue(): Op[];
  sync(): unknown[];
}
interface Server {
  rows: Map<string, Row>;
  net: { offline: boolean; loseResponse: boolean; unauthorized: boolean };
}
declare function createServer(): Server;
declare function createClient(device: string, server: Server): Client;

// формат очереди PowerSync: запись на каждое изменение, а не на строку
type UpdateType = "PUT" | "PATCH" | "DELETE";
type CrudEntry = { clientId: number; id: string; op: UpdateType; table: string; opData?: Fields };

function toCrud(log: Op[], queue: Op[]): CrudEntry[] {
  return queue.map((op): CrudEntry => {
    const clientId = log.indexOf(op) + 1;
    const birth = (log.find((entry) => entry.rowId === op.rowId) as Op).opId === op.opId;
    if (op.fields.deleted === true) return { clientId, id: op.rowId, op: "DELETE", table: "sets" };
    return { clientId, id: op.rowId, op: birth ? "PUT" : "PATCH", table: "sets", opData: { ...op.fields } };
  });
}

const server = createServer();
const phone = createClient("A", server);
const bench = phone.journal.newId();
phone.journal.change(bench, { exercise: "жим", weightKg: 80, reps: 5 });
const squat = phone.journal.newId();
phone.journal.change(squat, { exercise: "присед", weightKg: 100, reps: 5 });
phone.sync();

phone.journal.change(bench, { weightKg: 82.5 });
const deadlift = phone.journal.newId();
phone.journal.change(deadlift, { exercise: "тяга", weightKg: 120, reps: 3 });
phone.journal.remove(squat);

const crud = toCrud(phone.journal.outbox(), phone.queue());
crud.forEach((entry) => {
  console.log(entry.clientId + " " + entry.op + " " + entry.id + " " + JSON.stringify(entry.opData ?? {}));
});
console.log("имена операций:", JSON.stringify(phone.queue().map((op) => op.opId)));
console.log("clientId:", JSON.stringify(crud.map((entry) => entry.clientId)));

Правка уехала как PATCH с единственным полем weightKg — то самое, за что глава держалась: слияние по полям на той стороне остаётся возможным. Надгробие стало DELETE с одним идентификатором: удаление здесь служебное, как у WatermelonDB, а надо ли вам своё поле deleted со сроком хранения, решает ваш сервер — «Удаление — это запись». А clientId — авто-инкремент на устройстве: он продолжил счёт с трёх, а не начался заново вместе с пачкой. Внутри телефона он уникален, между телефонами — нет, поэтому ключ, по которому ваш сервер узнаёт повтор, складывается ровно как в главе 6: имя устройства плюс этот номер.

Цена — нативная. На React Native PowerSync работает поверх @op-engineering/op-sqlite, и в package.json он записан жёстко: >=17.1.0 <19.0.0. Это нативный модуль, которого в готовом клиенте Expo Go нет, — значит, свой dev client, «Где кончается готовый клиент: свой dev client». В README пакета так и написано: ставится npx expo install @powersync/react-native @op-engineering/op-sqlite, запускается npx expo run:ios, а Expo-проектам вдобавок нужны полифил @azure/core-asynciterator-polyfill и плагин @babel/plugin-transform-async-generator-functions, иначе живые запросы и getCrudTransactions() не заработают.

Две половины синхронизации здесь разъехались по ответственности, и понимать это лучше до выбора: вниз, к телефону, изменения идут от сервиса PowerSync, которому fetchCredentials выдаёт токен; вверх, от телефона, — вашим uploadData на ваш бэкенд. Сервер из части VI никуда не девается, сервис добавляется сверх него.

Теперь про то, чем движок синхронизации не является, — потому что путают их постоянно, и в мобильном проекте роль «того, что у нас вместо синхронизации» обычно достаётся TanStack Query. Вот как он настроен в настоящем приложении автора, и настроен правильно:

// stack-starter/apps/mobile/src/app/providers/providers.tsx — это кеш, а не движок
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 0,
      refetchOnWindowFocus: true,
      refetchOnMount: true,
      gcTime: 30 * 60 * 1000,
      retry: 1,
    },
  },
});

const onUnauthorized = () => {
  useSession.getState().signOut();
  // кэш переживает выход (gcTime — полчаса), поэтому чистим его руками:
  // иначе первый кадр после входа другим пользователем — чужие данные
  queryClient.clear();
};

// фокуса окна в React Native нет — его сообщают руками из AppState
AppState.addEventListener("change", (status) => focusManager.setFocused(status === "active"));

Каждая строка тут — про копию. staleTime: 0: данные устарели сразу, потому что оригинал на сервере. gcTime в полчаса: копию можно выбросить, она восстановима. refetchOnWindowFocus: вернулись — сходим за свежим (фокус окна в React Native приходится сообщать руками из AppState, «Свернули и вернулись»). И clear() при UNAUTHORIZED обязателен: иначе первый кадр после входа другим человеком покажет чужие данные.

В local-first та же самая уборка стирает единственный экземпляр тренировки: прогон в статье «Свернули и вернулись» напечатал «на экране 0 | ждут отправки 0 | у сервера строк 0». Дело не в качестве библиотеки, а в том, чем она владеет:

Лишним кеш от этого не становится. Как только у «Подхода» появится что-то не ваше — общий справочник упражнений с сервера, чужие программы тренировок, — это будут данные, оригинал которых на сервере, и держать их надо именно кешем со сроком годности. Кеш изнутри мы собирали в части IV, в статье «Свой кеш: ключ из входа, метка вместо списка адресов»: запись лежит под ключом из входа, по метке её выбрасывают, и следующее чтение считает её заново. Кеш там серверный, у Next, а не в телефоне, но и он — восстановимая копия. Дневник в этот список не входит: его оригинал в телефоне.

Проверка на один вопрос: что случится с этими данными, если телефон уронить в реку? Если ответ «ничего, они на сервере» — это кеш, и чистить его можно когда угодно. Если «пропадёт всё, что не успело уехать» — это оригинал, и кешем управлять им нельзя.

Соберём всё вместе. Колонки в таблице — это не «лучше или хуже», а «что придётся дописать самому»:

Строка «живой снимок» стоит отдельного взгляда: это единственное место, где движок вообще трогает разметку.

// наш: снимок хранилища через useSyncExternalStore
const rows = React.useSyncExternalStore(store.subscribe, store.visible);

// WatermelonDB: запрос наблюдаемый, компонент подписывает withObservables
const enhance = withObservables([], () => ({
  sets: database.collections.get("sets").query().observe(),
}));

// PowerSync: живой SQL и состояние соединения
const { data: sets } = useQuery("select * from sets");
const status = useStatus();

Ни один из трёх вариантов не меняет того, что вы знаете про React: это подписка на внешний источник, просто отданная библиотеке. Свой хук на useSyncExternalStore объяснён в части IV («Свой хук: логика без разметки»), и остальные два делают ровно то же — withObservables через наблюдаемый запрос, useQuery через живой SQL. Ни спиннера, ни трёх состояний запроса тут по-прежнему нет: данные на устройстве.

И две честные оговорки напоследок. Первая — про WatermelonDB: последний стабильный выпуск 0.28.0 вышел 7 апреля 2025 года и на момент написания остаётся последним, а после 11 августа 2025 года в основной ветке репозитория не было ни одного коммита. Законченный это пакет или брошенный, по датам не решить — как их отличают, разобрано в статье «Живой ли пакет». Поля peerDependencies в пакете нет вовсе, то есть диапазон совместимых версий React Native им не заявлен; линкуется он автолинком (react-native.config.js, папка native/android, свой podspec), а значит, это тоже нативный модуль и тоже свой dev client. Совместимость с React Native 0.86 проверяется на устройстве, а не по числам в package.json.

Вторая — про то, чего не отменяет ни один движок: горизонт курсора, срок жизни надгробий, размер памяти вердиктов, снимок для нового телефона. Всё это просто переезжает на вашу сторону сервера — в часть VI, где на место миниатюры встанет настоящий сервер с теми же именами sync.push и sync.pull. Зато их документация теперь читается как перевод знакомого: pullChanges — это pull с курсором, pushChanges — push с вердиктами, getCrudBatch — исходящая очередь, complete() — «убрать по вердикту», markAsDeleted — надгробие.

Чем бы вы ни синхронизировались, проверять это надо теми же двумя рубильниками: «сети нет» и «сервер всё сделал, а ответ потерялся». Если в документации движка про повтор пачки не сказано ничего, значит, его просто не проверяли, — и проверять придётся вам.