Инициализация приложения и справочная информация

Сведения

В текущей версии утилитаcopywala была переименована. При ручном вызове необходимо использовать новое имя исполняемого файла – pangolin-copywala.

• Инициализация приложения
• Инициализация репозитория для хранения служебной информации в БД
• Вывод информации об экземпляре БД
• Вывод списка с именами экземпляров баз данных, доступных в хранилище
• Работоспособность сервиса Copywala
• Вывод версии Copywala

Инициализация приложения

подсказка

Исполнять сценарий необходимо от имени пользователя postgres.

Описание сценария

Инициализация выполняется через CLI компонента copywala командой:

copywala init <agent_name>

Где agent_name – уникальное имя агента (задается самостоятельно администратором).

При первичной инициализации:

1. Утилита copywala генерирует уникальный идентификатор agent_id.

2. На основании agent_name и agent_id автоматически формируется значение уникального имени агента instance_name по принципу: agent_name+_+agent_id.

   Пример:

   $ copywala init test_agent
   
   2026-04-07 11:41:02.712 [522766] INF copywala 1.2.3 (ab60aae1) compiled at 2026-04-03_12:38:14
   2026-04-07 11:41:02.733 [522766] INF copywala initialization complete: name="test_agent" id="019d671a-300d-7049-b98a-bcd917e545d2"

   На основе этих данных формируется instance_name:

   test_agent_019d671a-300d-7049-b98a-bcd917e545d2

Подсказка

Узнать значенияinstance_name, agent_name и agent_id можно с помощью команды:

$ copywala db info

dbuser: backup_user
dbname: postgres
version: "15.15"
db_list: First_db, demo, demo_temp, postgres, template0, template1
edition: Platform V Pangolin DB 6.7.0
system_id: "7624074065519217763"
instance_name: dbname_0198a248-0f5c-7339-b454-7301bb98ef3e
replication: standalone
replication_partners: ""
leader: ""
home: /pgdata/06/data
archive_mode: "off"
archive_command: (disabled)
wal_level: replica
user: postgres
status: stopped
size: 351539988
port: 5433

В данном примере:

$$\overbrace{\underbrace{\text{dbname}}_{\mathrm{agent\_name}}\_\underbrace{\text{10198a248-0f5c-7339-b454-7301bb98ef3e}}_{\mathrm{agent\_id}}}^{\mathrm{instance\_name}}$$

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

Идентификатор сохраняется в файле /etc/pangolin-copywala/pbr.agent.id (задается в copywala.yaml, параметр app.agent_id_file_path) и далее используется для однозначного распознавания конкретного экземпляра базы данных и агентского приложения. Например, все резервные копии и WAL-файлы этого экземпляра будут сохраняться в отдельной подпапке хранилища с названием, соответствующим instance_name.

Если пользователи pbr-agent и copywala разные, то нужно настроить права доступа к файлу pbr.agent.id (при инициализации — на запись и чтение, для работы — на чтение).

app:
  agent_id_file_path: "path/to/id/file"

Последовательность выполнения

Выполните инициализацию приложения через CLI компонента copywala командой copywala init <наименование агента / экземпляра БД>.

Результат

В результате выполнения команды будет выведено:

$ copywala init dbmain
2025-08-08 17:24:53.876 INF copywala initialization complete: name="dbmain" id="01988a12-06bf-7f0b-87f8-e290972fe614"

Исключительные сценарии

Будет выведено соответствующее сообщение для случаев:

• Ошибка при повторной инициализации — идентификатор экземпляру уже был сгенерирован ранее:

  $ copywala init db1
  2025-08-08 17:23:24.162 ERR app: init app id info failed err="app id already initialized"
  2025-08-08 17:23:24.273 WRN copywala already initialized: name="db1" id="01988444-1801-77b8-90de-bf03df71df55"

• Ошибка при загрузке файла конфигурации.

• Ошибка при инициализации логера.

Инициализация репозитория для хранения служебной информации в БД

Описание сценария

CopyWala в экземпляре базы данных хранит информацию о задачах и результатах резервного копирования данного экземпляра. Информация сохраняется в базе данных, которая указана в конфигурационном файле copywala.yaml в параметре pbra_db. Если этот параметр отсутствует, используется база данных target_db. Рекомендуется размещать данную служебную информацию в специальной служебной базе данных postgres, выделив отдельную схему с названием pbr.

Для правильной организации структуры репозитория для хранения служебной информации существует команда copywala db init-repository.

примечание

Инициализация репозитория не является обязательной процедурой и происходит автоматически при запуске первого снятия резервной копии обслуживаемого экземпляра БД (команда create-backup).

Последовательность выполнения

Инициируйте создание репозитория для хранения служебной информации через CLI компонента Copywala командой copywala db init-repository.

Результат

При выполнении команды отображаются две ключевые части информации:

• текущая версия миграций репозитория
• информационное сообщение

2025-11-11 14:01:43.124 INF init-repository: migrations version: 2025092616200017
2025-11-11 14:01:43.235 INF init-repository: backups repository is ready

Исключительные сценарии

• Ошибка подключения к БД

  2025-11-11 14:01:36.761 ERR failed to init repository in db err="db: open connection failed: failed to connect to `user=username database=postgres`: 127.0.0.1:5433 (localhost): server error: FATAL: no pg_hba.conf entry for host \"127.0.0.1\", user \"username\", database \"postgres\", SSL encryption (SQLSTATE 28000)"

  Решение

  1. Некорректно указаны учетные данные; их следует перепроверить.
  2. Отсутствие разрешений на подключение текущего клиента в конфигурационном файле базы данных (pg_hba.conf). Для устранения неполадки необходимо добавить разрешение на подключение указанного клиента в файл конфигурации pg_hba.conf.

• Ошибка получения версии миграций (поврежденная таблица db_migrations)

  2025-11-11 14:14:39.198 ERR failed to init repository in db err="failed to get schema version: ERROR: column \"version\" does not exist (SQLSTATE 42703) in line 0: SELECT version, dirty FROM \"pbr\".\"db_migrations\" LIMIT 1"

  Решение:

  Пересоздайте базу данных pbr, а затем повторно инициализируйте репозиторий.

• Ошибка удаления таблицы после инициализации

  ERR failed to init repository in db err=«failed to apply database migrations: Dirty database version 2025011414280010. Fix and force version.»

  Решение:

  Удалите и заново создайте базу данных pbra (или удалите схему вместе со всеми таблицами в ней каскадом и вновь создайте ее). Затем проведите повторную инициализацию репозитория.

• Ошибка нехватки прав на чтение служебных таблиц

  [postgres@pbra-9a0b3b80 pbr] $ copywala db init-repository
  2025-12-11 07:26:41.345 INF copywala v1.2.1 (870e6c7) compiled at 2025-12-09_11:28:41
  2025-12-11 07:26:41.451 ERR failed to get schema version package=repository err=“ERROR: permission denied for table db_migrations (SQLSTATE 42501) in line 0: SELECT version, dirty FROM \”pbr\”.\”db_migrations\” LIMIT 1”
  2025-12-11 07:26:41.672 ERR failed to init repository in db err=“failed to get schema version: ERROR: permission denied for table db_migrations (SQLSTATE 42501) in line 0: SELECT version, dirty FROM \”pbr\”.\”db_migrations\” LIMIT 1”

  Решение:

  Выдайте права на чтение и изменение данных пользователю backup_user на созданные технические таблицы:

  • db_migrations;
  • pbr_backup_policies;
  • pbr_backup_tasks;
  • pbr_backups;
  • pbr_recovery_tasks;
  • pbr_retention_policies;
  • pbr_sync_backups;
  • pbr_sync_tasks.

Вывод информации об экземпляре БД

Описание сценария

Команда для вывода информации об экземпляре базы данных, к которому подключена copywala (в формате YAML и JSON).

Последовательность выполнения

Инициируйте просмотр информации об экземпляре базы данных через CLI компонента Copywala командой copywala db info.

Флаг --json

Если флаг--json не был указан, вывод осуществляется по умолчанию в формате YAML. При передаче флага --json информация отображается в формате JSON.

Результат

В результате выполнения команды будет выведена следующая информация об экземпляре БД:

$ copywala db info

dbuser: postgres
dbname: postgres
version: "15.5"
db_list: postgres, pbra, template1, template0
edition: Platform V Pangolin 6.2.0
instance_name: dbname_0198a248-0f5c-7339-b454-7301bb98ef3e
system_id: "7537245768605270048"
replication: standalone
replication_partners: ""
leader: ""
home: /pgdata/06/data
archive_mode: off
archive_command: (disabled)
user: username
status: unknown
size: 36845444
port: 15433

Поле	Описание	Пример значения
dbuser	Имя пользователя, который подключается к экземпляру БД	postgres
dbname	Наименование БД, к которой осуществляется подключение	postgres
version	Версия PostgreSQL	15.5
db_list	Список баз данных, входящих в состав экземпляра	postgres, pbra, template1, template0
edition	Редакция или версия продукта	Platform V Pangolin 6.2.0
instance_name	Полное наименование экземпляра агента для снятия резервных копий и восстановления	dbname_0198a248-0f5c-7339-b454-7301bb98ef3e
system_id	SystemID экземпляра БД	7537245768605270048
replication	Определяет роль экземпляра в репликационной схеме: standalone, leader или replica	standalone
replication_partners	Список IP-адресов, с которыми настроена репликация	192.0.2.0, 192.0.2.1
leader	IP-адрес главного сервера (лидера), от которого получает данные реплика. В поле может быть указано пустое значение в случаях, если: replication: standalone, replication: leader или для реплики, если лидер не доступен	192.0.2.3:5433
home	Путь к каталогу PGDATA	/pgdata/06/data
archive_mode	Настройка архивирования WAL: always, on или off	off
archive_command	Настройка команды архивирования WAL	(disabled)
user	Username текущего пользователя ОС	postgres
status	Статус работы Сopywala. Определяется по статусу последней задачи на создание РК, сохраненной в PBRA DB: - started – задача создана или запущена; - stopped – задача завершена или произошла ошибка; - unknown – задачи отсутствуют.	unknown
size	Общий размер всех баз данных экземпляра	36845444
port	Порт для подключения к БД	5433

Исключительные сценарии

Не удалось установить подключение к целевой базе данных.

Вывод списка с именами экземпляров баз данных, доступных в хранилище

подсказка

Исполнять сценарий необходимо от имени пользователя postgres.

Описание сценария

Команда для просмотра списка экземпляров баз данных, для которых имеются резервные копии в хранилище.

Последовательность выполнения

Инициируйте просмотр списка экземпляров баз данных через CLI компонента Copywala командой: copywala storage instances.

Результат

В результате выполнения команды будет выведен список экземпляров баз данных:

$ copywala storage instances
+---+--------------------------------------------------------+
| # | INSTANCE NAME                                          |
+---+--------------------------------------------------------+
| 1 | db-test-localhost_0198a75f-d0b1-7e66-ab4a-6f9b1f0ad230 |
| 2 | testdb_0198a21b-a76f-7c06-b071-9c35cc9fc181            |
+---+--------------------------------------------------------+

Исключительные сценарии

• Не удалось установить подключение к удаленному хранилищу.
• Не удалось получить доступ к локальному хранилищу.

Работоспособность сервиса Copywala

Описание сценария

Проверка пользователем работоспособности сервиса Copywala.

Последовательность выполнения

Инициируйте проверку работоспособности Copywala через CLI компонента Copywala командой copywala healthcheck.

Результат

В результате выполнения команды будет выведено сообщение, которое отобразит статус работоспособности компонента Copywala:

$ copywala healthcheck
Config                   [OK]
Logging                  [OK]
Target DB                [OK]
PBRA DB                  [OK]
________________________________________
Overall System           [OK]

Исключительный сценарий

1. Если одна из проверок не пройдет, то вместо OK будет выведено FAILED:

   $ copywala healthcheck
   Config                   [OK]
   Logging                  [OK]
   Target DB                [FAILED]
   2025-03-26 15:53:35.418 ERR Target DB err="cannot parse `postgres://postgres:xxxxxx@local host:15432/?application_name=copywala`: failed to parse as URL (invalid character \" \" in host name)"
   PBRA DB                  [OK]
   ________________________________________
   Overall System           [FAILED]
   
   Error: copywala healthcheck failed

2. В случае неудачной проверки конфигурационного файла (например, отсутствуют необходимые параметры или неверно указаны), будет выведено:

   $ copywala healthcheck --config .local/bad-config.yaml
   Config                   [FAILED]
   Error: open .local/bad-config.yaml: no such file or directory

Вывод версии Copywala

Описание сценария

Вывод версии Copywala.

Последовательность выполнения

Инициируйте просмотр текущей версии через CLI компонента Copywala командой copywala version.

Результат

Пользователь получает доступ к информации о версии Copywala.

Исключительный сценарий

Не предусмотрено.