Инструмент удалённого копирования баз данных для SQLite

1. Обзор

Следующая команда превращает REPLICA в копию ORIGIN:

$ sqlite3_rsync ORIGIN REPLICA ?OPTIONS?

Используйте флаг --help или -?, чтобы увидеть полный список параметров. Флаги параметров могут указываться до, после или между аргументами ORIGIN и REPLICA.

Добавьте параметр -v, чтобы увидеть больше вывода в формате, похожем на «rsync».

2. Возможности

1. Один из аргументов — ORIGIN или REPLICA — может иметь вид "USER@HOST:PATH". Другой аргумент должен быть обычным PATH. Эта утилита превращает REPLICA в копию ORIGIN.

   1. Если REPLICA ещё не существует, он будет создан.

   2. Для связи используется ssh, поэтому "USER@HOST" может быть псевдонимом SSH.

   3. Не требуется, чтобы ORIGIN или REPLICA находились на удалённой машине. Утилита sqlite3_rsync работает и в том случае, если ORIGIN и REPLICA находятся на локальной машине.

2. Пока эта утилита работает, обе базы данных могут оставаться «активными». Другие программы могут поддерживать активные соединения с базами данных на обоих концах во время её работы. Другие программы могут записывать данные в ORIGIN и читать данные из REPLICA, пока работает эта утилита.

   REPLICA становится копией снимка ORIGIN в том состоянии, в котором он находился на момент запуска команды sqlite3_rsync. Если другие процессы изменяют содержимое ORIGIN во время выполнения этой команды, эти изменения будут применены к ORIGIN, но не будут переданы в REPLICA. Таким образом, REPLICA становится полностью согласованным снимком ORIGIN на определённый момент времени.

3. Для синхронизации используется протокол, эффективно расходующий пропускную способность, похожий на rsync (от которого произошло его название).

3. Ограничения

1. Файлы баз данных должны находиться в режиме WAL и иметь одинаковый размер страницы. ← Эти ограничения были сняты в версии 3.50.0 (2025-05-29).

2. Во время работы sqlite3_rsync REPLICA доступен только для чтения. Во время работы этой утилиты к REPLICA можно выполнять запросы, но нельзя выполнять транзакции записи.

3. При каждом запуске этой утилиты синхронизируется только одна база данных. (Пока) нельзя синхронизировать несколько разных баз данных с помощью подстановочных знаков, как это можно делать со стандартным «rsync».

4. Как минимум одна из баз данных — ORIGIN или REPLICA — должна находиться на локальной машине. Обе базы данных не могут находиться на других машинах.

5. В удалённой системе эта утилита должна быть установлена в одном из каталогов, входящих в значение $PATH по умолчанию для SSH. Каталог /usr/local/bin часто является подходящим вариантом. В качестве альтернативы можно использовать флаг --exe NAME, чтобы указать расположение исполняемого файла в удалённой системе, например --exe /opt/bin/sqlite3_rsync.

6. Реплика будет очень близкой, но не точной копией оригинала. Содержимое всех таблиц (и индексов) в реплике будет побайтно идентично оригиналу. Однако в заголовке базы данных могут быть небольшие изменения. В частности, реплика будет отличаться от оригинала следующим:

   1. Счётчик изменений в байтах с 24 по 27 заголовка базы данных может быть увеличен в реплике.

   2. Номер версии, для которой данные действительны, расположенный в байтах с 96 по 99 заголовка базы данных, будет соответствовать версии SQLite программы sqlite3_rsync, создавшей копию, а не версии программы, которая последней записывала данные в базу ORIGIN.

7. В Windows имя HOST из одной буквы без префикса USER@ будет интерпретировано как буква диска Windows, а не как имя хоста.

4. Установка

Чтобы установить sqlite3_rsync, просто поместите исполняемый файл в каталог, указанный в $PATH. Если вы синхронизируете данные с удалённой системой, исполняемый файл sqlite3_rsync необходимо установить и на локальной, и на удалённой системе. При установке исполняемого файла sqlite3_rsync в удалённой системе убедитесь, что он находится в каталоге, доступном через $PATH, используемый SSH. Часто для этого подходит каталог /usr/local/bin.

К сожалению, в MacOS по умолчанию для SSH используется значение PATH "/usr/bin:/bin:/usr/sbin:/sbin", а MacOS не позволяет добавлять новые программы ни в один из этих каталогов. В качестве обходного решения sqlite3_rsync попытается дополнить PATH следующим образом:

PATH=$HOME/bin:/usr/local/bin:/opt/homebrew/bin:$PATH

Поэтому, если вы пытаетесь синхронизировать данные с удалённым Mac, достаточно установить исполняемый файл sqlite3_rsync в любой из трёх новых каталогов PATH:

• $HOME/bin
• /usr/local/bin
• /opt/homebrew/bin

Если вам необходимо установить sqlite3_rsync в другое (нестандартное) место на удалённой машине, просто используйте параметр --exe в командной строке, чтобы указать его точное расположение. Например:

sqlite3_rsync sample.db mac:sample.db --exe /some/weird/place/sqlite3_rsync

Автор этого документа ни разу не смог добиться запуска SSHD в Windows. Возможно, в будущем ему удастся разобраться с этим и предоставить инструкции по синхронизации базы данных с удалённой машиной Windows или с неё.

4.1. Проблемы обратной совместимости

Программа sqlite3_rsync при запуске согласовывает параметры алгоритма синхронизации между оригиналом и репликой и использует наиболее современный алгоритм, доступный на обеих сторонах. Однако из-за ошибки в логике согласования алгоритма (отсутствия вызова fflush()) приложение может зависнуть, если на локальной стороне соединения используется sqlite3_rsync версии 3.50.0 или новее, а на удалённой — версии 3.49.1 или более ранней. Лучшее решение — установить последнюю версию sqlite3_rsync на обеих сторонах. Если это невозможно, проблему можно обойти, добавив параметр "--protocol 1" в командную строку sqlite3_rsync.

5. Пропускная способность сети

Основная идея протокола состоит в том, что реплика отправляет на сторону оригинала криптографические хеши страниц или групп страниц. Оригинал отправляет обратно содержимое отличающихся страниц или запрашивает хеши с более высокой детализацией, если хеш группы страниц не совпадает. Если исходные состояния оригинала и реплики сильно различаются, общий объём сетевого трафика может превысить размер всей базы данных из-за накладных расходов на обмен хешами, но превышение невелико — максимум несколько процентов. С другой стороны, если изначально оригинал и реплика очень похожи (что обычно и бывает), общий трафик часто составляет менее 0,01% от размера базы данных. По результатам тестов, синхронизация базы данных размером 500 МБ обычно требует около 20 КБ сетевого трафика.

До версии 3.50.0 (2025-05-29) протокол отправлял хеши только отдельных страниц, а не групп страниц. Это означало, что требования к пропускной способности обычно составляли не менее примерно 0,5% от размера базы данных, даже если обе стороны изначально были идентичны. В версии 3.50.0 и новее пропускная способность используется эффективнее, если между оригиналом и репликой мало различий. Однако на обеих сторонах соединения должна быть установлена версия sqlite3_rsync 3.50.0 или новее; в противном случае протокол переключается на более старый и менее эффективный алгоритм.

6. Почему нельзя просто использовать обычный rsync?

Обычный rsync не понимает транзакции SQLite. Rsync создаст копию ORIGIN в REPLICA, однако эта копия может оказаться несогласованной. Одни её части могут соответствовать одной транзакции, а другие — другой. Копия базы данных может быть повреждена.

Если на протяжении всего времени работы rsync к базе данных не подключены другие процессы и в базе данных нет горячего журнала, rsync создаст согласованную копию базы данных. Но если нельзя гарантировать выполнение обоих этих условий, rsync может создать повреждённую копию. Утилита sqlite3_rsync, напротив, всегда создаёт согласованную копию.

Эта страница последний раз обновлялась 2025-11-13 07:12:58Z