Режим агента

Агент Databasus умеет делать физические и инкрементальные бекапы, архивировать WAL и выполнять Point-in-Time Recovery (PITR) для баз данных PostgreSQL.

Когда нужен агент

Для большинства баз удаленные бекапы — самый простой вариант. Databasus подключается к базе напрямую по сети, делает логические бекапы через pg_dump и не требует дополнительного ПО на сервере базы данных. Удаленные бекапы работают и с облачными управляемыми базами (RDS, Cloud SQL, Supabase), и с self-hosted-инстансами.

Агент рассчитан на случаи, когда удаленных бекапов недостаточно:

• Аварийное восстановление с PITR — восстановление на любую секунду между бекапами с почти нулевой потерей данных
• Физические бекапы — копия всего кластера базы на уровне файлов: на больших объемах данных быстрее и бекап, и восстановление
• Базы, недоступные снаружи — агент сам подключается к Databasus в исходящем направлении, поэтому базе не нужен публичный адрес
• Инкрементальные бекапы — непрерывное архивирование WAL-сегментов в сочетании с периодическими базовыми бекапами

Пошаговая настройка в интерфейсе

Databasus показывает интерактивные инструкции по установке и восстановлению прямо в интерфейсе. Когда вы открываете настройки агента для базы, все команды уже заполнены вашими значениями: архитектурой, ID базы, токеном агента, адресом Databasus и типом развертывания PostgreSQL. Остается скопировать каждую команду и выполнить ее на своем сервере.

Документация ниже описывает те же шаги — как справочник и для тех, кому удобнее идти по руководству вне интерфейса.

Требования

• PostgreSQL 15 или новее
• Linux (amd64 или arm64)
• Сетевой доступ от агента к вашему инстансу Databasus (только исходящий — базе не нужно быть доступной со стороны Databasus)

Установка

Шаг 1 — скачайте агент

Скачайте бинарный файл агента на сервер, где работает PostgreSQL. Замените <DATABASUS_HOST> на URL вашего инстанса Databasus, а <ARCH> — на amd64 или arm64.

curl -L -o databasus-agent "<DATABASUS_HOST>/api/v1/system/agent?arch=<ARCH>" && chmod +x databasus-agent

Шаг 2 — настройте postgresql.conf

Добавьте или обновите эти настройки в postgresql.conf, затем перезапустите PostgreSQL.

Для установки на хосте (замените <WAL_QUEUE_DIR> на реальный путь, например /opt/databasus/wal-queue):

wal_level = replica
archive_mode = on
archive_command = 'cp %p <WAL_QUEUE_DIR>/%f.tmp && mv <WAL_QUEUE_DIR>/%f.tmp <WAL_QUEUE_DIR>/%f'

Для установки в Docker путь в archive_command (/wal-queue) — это путь внутри контейнера. Он должен совпадать с точкой монтирования тома — см. шаг 5.

wal_level = replica
archive_mode = on
archive_command = 'cp %p /wal-queue/%f.tmp && mv /wal-queue/%f.tmp /wal-queue/%f'

Шаг 3 — настройте pg_hba.conf

Добавьте эту строку в pg_hba.conf. Она нужна, чтобы pg_basebackup мог снимать полные бекапы, а не для потоковой репликации. При необходимости поправьте адрес и метод аутентификации, затем перечитайте конфигурацию PostgreSQL.

host    replication   all   127.0.0.1/32   md5

Шаг 4 — выдайте право репликации

Это требование PostgreSQL для запуска pg_basebackup — реплика при этом не создается.

ALTER ROLE <YOUR_PG_USER> WITH REPLICATION;

Шаг 5 — создайте каталог очереди WAL

Сюда PostgreSQL складывает архивные WAL-файлы, а агент их загружает.

mkdir -p /opt/databasus/wal-queue

Убедитесь, что PostgreSQL может писать в каталог, а агент — читать из него:

chown postgres:postgres /opt/databasus/wal-queue
chmod 755 /opt/databasus/wal-queue

Для установки в Docker каталог очереди WAL должен быть томом, общим для контейнера PostgreSQL и хоста. Агент читает WAL-файлы по пути на хосте, а PostgreSQL пишет по пути внутри контейнера через archive_command.

# In your docker run command:
docker run ... -v /opt/databasus/wal-queue:/wal-queue ...

# Or in docker-compose.yml:
volumes:
  - /opt/databasus/wal-queue:/wal-queue

Убедитесь, что каталог внутри контейнера принадлежит пользователю postgres:

# Inside the container (or via docker exec):
chown postgres:postgres /wal-queue

Шаг 6 — запустите агент

Замените плейсхолдеры в <ANGLE_BRACKETS> на реальные значения.

PostgreSQL, установленный в систему (pg_basebackup доступен в PATH):

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=host \
  --pg-wal-dir=/opt/databasus/wal-queue

PostgreSQL в отдельном каталоге (например /usr/lib/postgresql/17/bin):

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=host \
  --pg-host-bin-dir=<PATH_TO_PG_BIN_DIR> \
  --pg-wal-dir=/opt/databasus/wal-queue

Docker (используйте порт PostgreSQL внутри контейнера, обычно 5432, а не порт, проброшенный на хост):

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=docker \
  --pg-docker-container-name=<CONTAINER_NAME> \
  --pg-wal-dir=/opt/databasus/wal-queue

После установки

• После команды start агент работает в фоне
• Проверить статус: ./databasus-agent status
• Посмотреть логи: файл databasus.log в рабочем каталоге
• Остановить агент: ./databasus-agent stop

Восстановление из бекапа агента

Восстановите физический или инкрементальный бекап в целевой каталог. Для Point-in-Time Recovery добавьте флаг --target-time, чтобы восстановиться на конкретный момент.

Шаг 1 — скачайте агент

Скачайте бинарный файл агента на сервер, где будете восстанавливать базу (та же команда, что и в шаге 1 установки).

curl -L -o databasus-agent "<DATABASUS_HOST>/api/v1/system/agent?arch=<ARCH>" && chmod +x databasus-agent

Шаг 2 — остановите PostgreSQL

Перед восстановлением PostgreSQL должен быть остановлен, а целевой каталог — пуст.

pg_ctl -D <PGDATA_DIR> stop

Для Docker:

docker stop <CONTAINER_NAME>

Шаг 3 — запустите восстановление

Замените <YOUR_AGENT_TOKEN> на токен агента, а <PGDATA_DIR> — на путь к пустому каталогу данных PostgreSQL.

Установка на хосте:

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --target-dir=<PGDATA_DIR>

Установка в Docker (<HOST_PGDATA_PATH> — путь на хосте, который будет смонтирован как том pgdata контейнера):

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --pg-type=docker \
  --target-dir=<HOST_PGDATA_PATH>

Смонтируйте <HOST_PGDATA_PATH> в путь PGDATA при (пере)создании контейнера postgres. Путь зависит от мажорной версии: PostgreSQL 18+ использует /var/lib/postgresql/<major>/docker; PostgreSQL 17 и старее — /var/lib/postgresql/data.

# PostgreSQL 17 and earlier
docker run -d -v <HOST_PGDATA_PATH>:/var/lib/postgresql/data postgres:17

# PostgreSQL 18+
docker run -d -v <HOST_PGDATA_PATH>:/var/lib/postgresql/18/docker postgres:18

Для Point-in-Time Recovery (PITR) добавьте --target-time с меткой времени RFC 3339 (например 2025-01-15T14:30:00Z):

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --target-dir=<PGDATA_DIR> \
  --target-time=<RFC3339_TIMESTAMP>

Шаг 4 — разберитесь с archive_command

Восстановленный бекап включает исходную конфигурацию archive_command. После восстановления PostgreSQL не сможет архивировать WAL-файлы, пока вы не сделаете одно из двух:

• Снова подключите агент — смонтируйте каталог очереди WAL и запустите агент Databasus на восстановленном инстансе, так же как в исходной настройке.
• Отключите архивирование — если непрерывные бекапы пока не нужны, закомментируйте или сбросьте настройки архивирования в postgresql.auto.conf:

# In <PGDATA_DIR>/postgresql.auto.conf, remove or comment out:
# archive_mode = on
# archive_command = '...'

Шаг 5 — запустите PostgreSQL

Запустите PostgreSQL, чтобы началось восстановление по WAL. Он автоматически проиграет WAL-сегменты.

pg_ctl -D <PGDATA_DIR> start

Для Docker:

docker start <CONTAINER_NAME>

Шаг 6 — приберитесь

Когда восстановление завершится, удалите каталог восстановления WAL:

rm -rf <PGDATA_DIR>/databasus-wal-restore/

Как это работает

Агент Databasus — легкий бинарник на Go, который запускает два параллельных процесса:

• Передача WAL — примерно каждые 10 секунд забирает WAL-сегменты из каталога очереди и загружает их в Databasus
• Периодические базовые бекапы — запускает pg_basebackup по настроенному расписанию, создавая полные физические бекапы кластера

При восстановлении агент скачивает базовый бекап и все нужные WAL-сегменты, затем настраивает recovery.signal и restore_command в postgresql.auto.conf. Когда PostgreSQL стартует, он проигрывает WAL-сегменты до целевой точки восстановления.

Соединение с Databasus всегда инициирует агент (исходящее). Серверу базы данных не нужно принимать входящие соединения от Databasus, поэтому агент подходит для приватных сетей и окружений за файрволом.