¶ Агбис Конвертор БД
Агбис Конвертор БД обслуживает локальные базы Firebird: выполняет отдельную проверку, оптимизацию Backup/Restore и конвертацию на новую версию Firebird. Цель основной операции -- сохранить для приложений прежние путь и порт подключения, но перевести их на проверенную новую базу и, при выбранной опции, на новую службу Firebird.
¶ Что делает программа
| Режим | Что происходит | Что не меняется |
|---|---|---|
| Проверка БД | Запускается GFIX-проверка. | Файл базы, службы и порты. |
| Оптимизация B/R | База пересоздается средствами текущей версии Firebird. | Версия и схема подключения. |
| Конвертация | База восстанавливается средствами выбранной версии Firebird. | Исходный путь к рабочей базе; при переключении сохраняется и старый порт. |
¶ Основные возможности
- отдельная Проверка БД без замены файла и службы;
- опция Исправление ошибок БД: GFIX mend перед основной операцией;
- оптимизация B/R в пределах текущей версии Firebird;
- конвертация на Firebird 2.5, 3.0 или 5.0;
- проверка структуры, GFIX и реальное подключение к новой базе до переключения;
- сохранение исходной базы с версией Firebird, датой и временем в имени;
- автоматическое переключение служб и портов при включенной опции;
- запуск с главным GUI, без окна или с компактным окном этапов;
- подробные журналы и итоговое уведомление Bitrix24.
¶ Перед запуском
¶ Обязательные условия
- Файл базы должен быть доступен локально. Конвертор работает с самим файлом базы и Embedded Firebird.
- Программу нужно запускать от имени администратора: это требуется для установки, остановки, запуска, смены портов и удаления служб Firebird.
- На диске должно быть свободно не менее 2,5 размера исходной базы. Место нужно для исходной базы, результата и служебных файлов.
- Для одной базы нельзя параллельно запускать второй Конвертор, GBAK или GFIX.
- Перед основной операцией нужно завершить программы, использующие эту базу. Конвертор останавливает связанные службы и соединения на время работы.
¶ Что подготовить заранее
- Отдельную резервную копию базы, созданную вне Конвертора.
- Понимание, нужна ли только оптимизация или конвертация на другую версию Firebird.
- Решение о переключении службы: оставлять старую версию на ее порту или заменить ее новой.
- Доступ к папке Logs: она нужна для контроля длительной операции и разбора ошибок.
¶ Расположение и настройки
Рекомендуемое размещение Конвертора: E:\Agbis\Temp\agbDBConvertor.exe.
Основной файл параметров базы ищется на уровень выше, например для E:\Agbis\Temp\agbDBConvertor.exe используется E:\Agbis\agbis.xml. Дополнительные параметры задаются в agbDBConvertor.ini или командной строке. Параметры командной строки имеют приоритет над INI.
¶ Работа в главном окне
Запуск без параметров открывает главное окно:
agbDBConvertor.exe
¶ Исходная и новая база
В верхней части выбирается файл исходной базы и ее порт. После проверки отображаются путь, свободное место, размер файла, версия Firebird и кодировка базы.
Блок Новая база данных используется, когда требуется указать отдельное расположение результата. Если не задано иное, новая база после всех проверок занимает имя и расположение исходной рабочей базы, а прежняя база сохраняется рядом.
¶ Проверка, исправление и основная операция
- Проверка БД запускает только GFIX-проверку. Ее можно выполнять заранее, без Backup/Restore, без смены службы и без замены файлов.
- Исправление ошибок БД применяется только к основной операции. Перед Backup/Restore выполняется GFIX mend.
- Оптимизация БД (B/R) появляется, когда выбрана исходная версия Firebird. Она пересоздает базу без смены версии.
- Конвертация БД появляется, когда выбрана другая версия Firebird. Backup делает текущая версия, а Restore -- целевая.
¶ Опция переключения службы
Опция Заменить версию службы Firebird на новую управляет тем, что происходит после успешной конвертации.
| Опция | Результат после успеха |
|---|---|
| Включена | Новая служба занимает прежний порт, получает автоматический запуск, проверяется подключением. Затем старая служба удаляется. |
| Выключена | Новая служба остается на собственном порту. Старая служба и ее порт не меняются. |
В главном GUI файлы agbis.xml не меняются: этот сценарий предназначен для контролируемой интерактивной работы администратора.
¶ Запуск из командной строки
¶ Без главного окна
agbDBConvertor.exe /run AliasBase="Agbis" FirebirdNum=5 timeout=1
Операция запускается сразу. Текущие этапы, команды и итог записываются в папке Logs.
¶ Компактное окно этапов
agbDBConvertor.exe /run AliasBase="Agbis" FirebirdNum=5 ConvertFrom="Him"
Параметр ConvertFrom включает небольшое окно с названием текущего этапа и фиксированной полосой прогресса. В этом окне нет технического журнала: подробности остаются в файлах Logs.
¶ Параметры
| Параметр | Назначение |
|---|---|
| /run | Немедленно запускает основную операцию без главного GUI. |
| AliasBase | Алиас исходной базы из agbis.xml. Если не задан, выбирается запись WasLast=1. |
| FirebirdNum | Целевая главная версия Firebird. Если не задан, выполняется оптимизация B/R. |
| timeout | Пауза в секундах до основной операции. Нужна, например, чтобы ReplIn завершил работу. |
| ConvertFrom | Имя вызывающего модуля. Включает компактное окно этапов. |
| CLIENT_DEP_ID | Идентификатор для существующего отчета в PC. |
| Agent_GUID | GUID агента для определения клиента в Bitrix24. |
| DEP_ID | Идентификатор подразделения конвертируемой базы для Bitrix24. |
Пример запуска из ReplIn:
agbDBConvertor.exe /run AliasBase="Agbis" FirebirdNum=5 ConvertFrom="ReplIn" Agent_GUID="{GUID}" DEP_ID=123
¶ Этапы основной операции
¶ 1. Подготовка
Конвертор определяет исходную базу, версию и службу Firebird, фактический порт, размер файла и свободное место. Затем фиксирует список приложений и служб, которые нужно остановить и позже вернуть в работу.
¶ 2. Проверка и исправление
Если включено исправление, выполняется GFIX mend. Во время длительной проверки в журнал периодически пишется heartbeat: это означает, что процесс не завис и его нужно дождаться.
¶ 3. Backup/Restore
Backup и Restore выполняются последовательно. При оптимизации оба действия используют текущую версию Firebird. При конвертации Backup делает исходная версия, а Restore -- выбранная целевая. Промежуточная база и журналы не скрываются: их можно использовать для диагностики.
¶ 4. Проверка результата
До замены рабочей базы Конвертор проверяет структуру результата, запускает GFIX и делает фактическое подключение к новой базе. Пока эти проверки не прошли, исходная база и исходная служба считаются рабочим вариантом для отката.
¶ 5. Замена базы
После успешной проверки новая база получает рабочее имя. Прежняя база сохраняется рядом, например:
ARM_FB3_20260928_153000.FDB
В имени присутствуют прежняя версия Firebird, дата и время. Не удаляйте этот файл до подтверждения нормальной работы всех программ.
¶ 6. Переключение Firebird
Только при включенной опции переключения Конвертор останавливает обе службы, переводит новую службу на прежний порт, запускает ее и проверяет подключение к базе уже через новый Firebird. Только после этой проверки удаляется исходная служба.
¶ 7. Возврат служб
Ранее остановленные службы запускаются снова. Итог операции и важные пути фиксируются в журнале.
¶ Обновление agbis.xml
Этот этап работает только в командных режимах и только после полной успешной конвертации с переключением Firebird. В главном GUI XML не изменяется.
Проверяются исключительно:
- Agbis\agbis.xml;
- Agbis\agent\agbis.xml;
- Agbis\repl\agbis.xml.
В каждом файле обрабатываются только элементы Base, у которых FilePath совпадает с путем конвертированной базы. Для таких записей меняется только firebird_ver.
Не изменяются AliasBase, WasLast, Port, Server, FilePath, учетные данные и прочие параметры. Записи с суффиксом _old не создаются.
Если XML отсутствует, поврежден или не содержит совпадений, это фиксируется в журнале, но конвертация продолжается. Если XML с совпавшей базой невозможно записать или перепроверить, файл восстанавливается из временной копии, а исходная служба Firebird не удаляется.
¶ Ошибки и автоматический откат
При ошибке задача Конвертора -- вернуть систему к состоянию до начала работы:
- Исходная база возвращается на рабочее место.
- Созданная новая база сохраняется для диагностики.
- Службы Firebird возвращаются на исходные порты.
- Ранее остановленные службы запускаются.
- В журнал попадают этап, причина, пути к файлам и результат каждого действия восстановления.
Если новая база уже была активирована, но следующий этап не завершился, не удаляйте сохраненную исходную базу и диагностический файл. Передайте в поддержку журнал операции и оба файла.
¶ Ручной откат после успешной конвертации
Ручной откат нужен только по решению администратора, если после успешной конвертации выявлена прикладная проблема:
- Остановите новую службу Firebird.
- Верните старой службе ее прежний порт и тип запуска.
- Если исходная служба была удалена, установите ее через форму «Настройка Firebird» или штатный установщик.
- Переименуйте текущую рабочую базу, не удаляя ее.
- Переименуйте сохраненную исходную базу с суффиксом версии и даты в исходное имя.
- Запустите исходную службу и проверьте подключение.
[Скриншот: актуальная форма «Настройка Firebird» со списком служб, портом, статусом и карточкой выбранной службы.]
¶ Настройка Firebird
Форма Настройка Firebird показывает найденные службы Firebird 2.5, 3.0 и 5.0, их версию, состояние, тип запуска, порт и каталог установки. Пустой список служб является нормальной ситуацией, когда Firebird на компьютере не установлен: действия, требующие выбранной службы, недоступны.
Через форму можно обновить список служб, изменить тип запуска и порт выбранной службы, запустить или остановить ее, установить или удалить Firebird. Перед удалением программа убеждается, что служба снята с регистрации; каталог установки не должен удаляться преждевременно.
¶ Журналы и диагностика
Журналы хранятся в папке Logs рядом с Конвертором. Они содержат:
- начало и завершение каждого этапа;
- причины пропуска этапов;
- команды Backup/Restore и результат запуска;
- регулярные сообщения GFIX о продолжении проверки;
- остановку и запуск служб;
- смену портов Firebird;
- проверку и подключение к новой базе;
- пути сохраненной исходной и диагностической баз;
- изменение agbis.xml;
- итог отправки в Bitrix24.
Старые backup.log и restore.log не уничтожаются, а переименовываются перед новым запуском. При обращении в поддержку приложите журнал операции и сохраненные базы, если они были созданы.
¶ Уведомления Bitrix24
После полной операции Конвертор отправляет сообщение в чат 36309. Ошибка доставки этого уведомления не меняет результат конвертации.
Agent_GUID определяет клиента, а DEP_ID однозначно указывает подразделение и базу.
При успехе сообщение содержит операцию, базу, исходную и целевую версии Firebird, а также путь сохраненной исходной базы. При ошибке дополнительно передаются режим и источник запуска, параметры переключения, службы и порты, результат восстановления базы и служб, пути диагностических файлов и текст последней ошибки.
¶ Рекомендуемый порядок
- Сделайте независимую резервную копию базы.
- Проверьте свободное место и предупредите пользователей о кратковременной недоступности.
- При сомнениях сначала выполните отдельную Проверку БД.
- Для обновления файлов в рамках текущей версии используйте оптимизацию B/R.
- Для перехода на новую версию используйте конвертацию.
- После успеха проверьте запуск основных программ и подключение к базе.
- Не удаляйте сохраненную исходную базу до подтверждения нормальной работы.