Жизненный цикл инстанса

Как AngaraBase понимает «кто владеет этими файлами данных»: идентичность инстанса, аренда (Instance Lease) и порядок запуска. Аренда — это то, что даёт безопасное восстановление после аварии и переносимость хранилища между хостами без дампа/восстановления.

Идентичность инстанса

При инициализации инстанс получает устойчивую идентичность:

• cluster_id — UUID логического кластера БД.
• instance_id — UUID конкретного инстанса.
• Каталог данных и каталог журнала транзакций — физическое расположение файлов.

Идентичность хранится в двух местах, чтобы пережить как сбой файла, так и сбой каталога:

1. VERSION-маркер — бинарный файл с версией формата и идентификаторами.
2. Страницы системного каталога — в зарезервированных страницах base.adb с полными метаданными.

Аренда инстанса (Instance Lease)

Аренда не даёт двум инстансам одновременно писать в одни и те же файлы — а это прямой путь к повреждению данных. Запись аренды лежит в SysCatalogMetaV0 внутри страниц base.adb и обновляется атомарно полным образом страницы. Поэтому механизм работает на NFS/SAN, где flock() ненадёжен.

Что записано в аренде

Состояния аренды

 [Нет]  ──acquire──▶  [Held]  ──heartbeat──▶  [Held]
   ▲                    │
   └──release/expired───┘
                        │ heartbeat прекратился (краш, разрыв сети)
                        ▼
                  [Expired]  ──takeover──▶  [Held новым инстансом]

• Нет → Held — первый запуск или запуск после штатной остановки.
• Held → Held — периодический heartbeat (по умолчанию каждые 10 с) сдвигает expires_at.
• Held → Нет — штатная остановка немедленно освобождает аренду.
• Held → Expired — heartbeat прекратился (краш, сетевой разрыв); аренда «протухает» по истечении TTL.
• Expired → Held — новый инстанс перехватывает аренду после истечения TTL.

Порядок запуска

1. Pre-flight — каталог данных существует и инициализирован, VERSION-маркер совместим, размер страницы совпадает со сборкой бинаря.
2. Захват аренды — загрузка системного каталога из base.adb, затем:
   • аренды нет → захватить сразу;
   • аренда истекла → перехватить (с предупреждением в лог);
   • аренда активна → fail-closed с информативной ошибкой (см. ниже);
   • принудительный перехват → переопределить активную аренду (опасно).
3. Восстановление — проигрывание WAL (backend file_bin), восстановление in-memory состояния MVCC, запуск heartbeat.
4. Готов к подключениям — поднимаются слушатели (pgwire, admin), сервер принимает клиентов и продолжает heartbeat до остановки.

Режимы восстановления

recovery_mode виден в sys.identity и принимает три значения:

Разделяемое хранилище (NFS/SAN)

Аренда позволяет нескольким хостам видеть одни и те же файлы, но писать — только одному:

Host A ──┐
         ├── NFS/SAN ──▶ [data/] [txlog/] [base.adb с арендой]
Host B ──┘

• Failover — Host B перехватывает аренду, если Host A упал.
• Обслуживание/миграция — перенос инстанса между хостами без дампа.
• Тестирование — безопасный прогон на копии боевых данных.

Ограничения: единственный писатель в каждый момент; сетевые разрывы могут вызвать ложное истечение аренды; латентность сетевого хранилища влияет на пропускную способность.

Управление арендой (env-переменные)

Аренда настраивается только переменными окружения — отдельных config-ключей для неё нет.

Рекомендации: в сети с нестабильной задержкой увеличьте TTL и heartbeat (например, 60/20); для быстрой итерации в dev — уменьшите (15/5). Heartbeat должен оставаться заметно меньше TTL.

⚠️ ANGARABASE_FORCE_LEASE_TAKEOVER=1 опасен. Он переопределяет активную аренду, игнорируя живого владельца. Если прежний инстанс на самом деле жив, вы получите двух писателей в одни файлы и повреждение данных. Включайте только когда владелец подтверждённо мёртв (процесс не запущен, хост недоступен). В норме просто дождитесь истечения TTL — перехват произойдёт сам.

Наблюдаемость и диагностика

-- Текущий владелец аренды и режим восстановления
SELECT lease_holder_id, lease_holder_hostname, lease_expires_at, recovery_mode
FROM sys.identity;

-- Здоровье инстанса
SELECT uptime_seconds, txn_commit_epoch_current
FROM sys.health;

События аренды пишутся в лог сервера: захват, перехват, отказ heartbeat, освобождение.

Типичные проблемы

Безопасность: аренда не аутентифицирует — права доступа ФС и сетевые ограничения по-прежнему обязательны, особенно на разделяемом хранилище.

Связанные разделы

Концепции

• Хранение данных — datadir, который защищает аренда.
• Транзакции и MVCC — что происходит с активными транзакциями при forced_takeover.

How-to

• Crash recovery — операционные процедуры восстановления после аварии.
• Резервное копирование и восстановление — как защитить datadir и снять снапшот.

Справочник

• Системные представления sys.* — sys.identity, sys.health для диагностики аренды.
• Известные ограничения и SQLSTATE — раздел ошибок INSTANCE_*.