G.1. pgpro_datactl — управление файлами данных Postgres Pro Enterprise
Пред. НаверхПриложение G. Модули и расширения Postgres Pro, поставляемые в виде отдельных пакетовНачало След.

G.1. pgpro_datactl — управление файлами данных Postgres Pro Enterprise

G.1.1. Обзор
G.1.2. Установка
G.1.3. Команды
G.1.4. Коды ошибок pgpro_datactl

G.1.1. Обзор

Утилита pgpro_datactl предоставляет инструменты для управления файлами данных Postgres Pro Enterprise и включает в себя модуль для работы с CFS (Compressed File Storage, сжатая файловая система). Этот модуль предлагает следующую функциональность:

  • Получение метаданных сжатых файлов, включая алгоритм сжатия и их расположение.

  • Распаковка файлов CFS для дальнейшего анализа.

  • Перепаковка сжатых файлов и изменение их уровня сжатия.

  • Предотвращение потенциальных сбоев, вызванных повреждёнными файлами.

G.1.2. Установка

pgpro_datactl поставляется вместе с Postgres Pro Enterprise в виде отдельного пакета pgpro-datactl-ent-13 (подробные инструкции по установке приведены в Главе 17).

G.1.3. Команды

pgpro_datactl поддерживает следующие команды:

G.1.3.1. Важные замечания

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

  • Операции repack и unpack требуют остановки кластера Postgres Pro Enterprise. Это необходимо для того, чтобы избежать повреждения данных и обеспечить целостность файлов.

  • При использовании параметра --in-place с командой repack следует учитывать следующее:

    • Табличное пространство будет перезаписано непосредственно в процессе работы.

    • Все существующие данные в целевом табличном пространстве будут заменены.

G.1.3.2. unpack

pgpro_datactl unpack --source=исходный_путь --target=целевой_путь
[--calg=алгоритм_сжатия] [--zero-on-error] [--log-level=уровень_сообщений] [--help]

Распаковывает файлы CFS.

-s=исходный_путь
--source=исходный_путь

Указывает путь к сжатому файлу или каталогу.

Примечание

Путь должен находиться в каталоге с именем PG_версия_дата, содержащем файл pg_compression.

-t=целевой_путь
--target=целевой_путь

Указывает путь к каталогу, в который будут помещены распакованные файлы.

Если исходный и целевой каталоги совпадают, файлы распаковываются с расширением .dec.

-c=алгоритм_сжатия
--calg=алгоритм_сжатия

Указывает используемый алгоритм сжатия. Если параметр не указан, команда unpack возьмёт это значение из файла pg_compression.

--zero-on-error

При указании этого параметра все повреждённые блоки заменяются нулями, что предотвращает аварийное завершение процесса или появление сообщений об ошибках.

--log-level=уровень_сообщений

Устанавливает уровень сообщений. Возможные значения: debug, info, warning и error.

Пример:

pgpro_datactl unpack -s /path/to/archive.cfs -t /path/to/destination -c zstd

В этом примере unpack извлекает файл archive.cfs, сжатый алгоритмом zstd, в каталог /path/to/destination.

G.1.3.3. probe

pgpro_datactl probe --source=исходный_путь [--log-level=уровень_сообщений] [--help]

Анализирует указанный файл и определяет следующее:

  • Тип сжатия. Алгоритм сжатия zlib или zstd.

  • Уровень фрагментации. Анализирует соответствующий файл *.cfm (при его наличии) и сообщает процент неиспользуемого пространства в физическом файле.

  • Принадлежность файла к CFS. Проверяет наличие связанного файла *.cfm, что указывает на принадлежность файла к архиву CFS.

-s=исходный_путь
--source=исходный_путь

Указывает путь к нужному файлу.

--log-level=уровень_сообщений

Устанавливает уровень сообщений. Возможные значения: debug, info, warning и error.

Пример вывода:

Probing path: /data/sample.dat
Has cfm file: Yes
pg_compression: zstd
Actual compression: zstd
Fragmentation: 5%

В этом примере файл сжат алгоритмом zstd, является частью архива CFS и имеет уровень фрагментации пять процентов.

G.1.3.4. info

pgpro_datactl info --source=исходный_путь [--log-level=уровень_сообщений] [--help]

Анализирует файл и отображает следующую информацию:

  • Физический и виртуальный размер файла, а также используемое им пространство в байтах.

  • Включён ли сборщик мусора (GC).

  • Наличие и доступность файла *.cfm.

-s=исходный_путь
--source=исходный_путь

Указывает путь к нужному файлу.

--log-level=уровень_сообщений

Устанавливает уровень сообщений. Возможные значения: debug, info, warning и error.

Пример вывода:

Physical size: 10485760
Virtual size: 9437184
Used size: 7864320
GC active: Yes

G.1.3.5. repack

pgpro_datactl repack --source=исходный_путь --t-calg=целевой_алгоритм_сжатия --target=целевой_путь
[--calg=алгоритм_сжатия] [--clevel=уровень_сжатия]
[--zero-on-error] [--log-level=уровень_сообщений] [--help]

Меняет алгоритм сжатия и/или уровень сжатия файлов CFS.

Возвращает следующую информацию:

  • Идентификатор алгоритма сжатия

  • Уровень сжатия

  • Результат копирования: 1 (завершено) или 0 (не завершено).

Если операция была прервана, при повторном выполнении команды с теми же параметрами сжатия (значения --t-calg и --calg) перепаковка продолжится с момента прерывания благодаря наличию соответствующего каждому файлу данных файла .status.

-s=исходный_путь
--source=исходный_путь

Указывает путь к сжатому файлу или каталогу.

Примечание

Путь должен находиться в каталоге с именем PG_версия_дата, содержащем файл pg_compression.

--t-calg=целевой_алгоритм_сжатия

Указывает целевой алгоритм сжатия. Если параметр опущен, файлы будут распакованы.

-t=целевой_путь
--target=целевой_путь

Указывает путь к каталогу для перепакованных файлов.

-c=алгоритм_сжатия
--calg=алгоритм_сжатия

Указывает текущий алгоритм сжатия. Если параметр не указан, команда repack возьмёт это значение из файла pg_compression.

--log-level=уровень_сообщений

Устанавливает уровень сообщений. Возможные значения: debug, info, warning и error.

--clevel=уровень_сжатия

Определяет уровень сжатия для выбранного алгоритма. Значение по умолчанию — 1.

--zero-on-error

При указании этого параметра все повреждённые блоки заменяются нулями, что предотвращает аварийное завершение процесса или появление сообщений об ошибках.

--in-place

Если указать этот параметр без целевого_пути, перепакованные файлы будут размещены в исходном каталоге.

Предупреждение

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

G.1.3.6. ground

pgpro_datactl ground --source=исходный_путь --block-num=номер_блока
[--calg=алгоритм_сжатия] [--log-level=уровень_сообщений] [--help]

Заменяет нулями указанные повреждённые блоки, которые могут появиться при распаковке.

-s=исходный_путь
--source=исходный_путь

Указывает путь к нужному файлу.

--block-num=номер_блока

Указывает номер блока, который нужно заменить.

-c=алгоритм_сжатия
--calg=алгоритм_сжатия

Определяет текущий алгоритм сжатия. Если значение не соответствует алгоритму сжатия табличного пространства CFS, операция завершится ошибкой.

--log-level=уровень_сообщений

Устанавливает уровень сообщений. Возможные значения: debug, info, warning и error.

Пример:

pgpro_datactl ground -s /path/to/archive.cfs --block-num 4 --calg pglz

В этом примере команда ground заменяет блок номер 4 нулём и использует алгоритм pglz для его сжатия.

G.1.3.7. stat

pgpro_datactl stat --source=исходный_путь --cfs
[--log-level=уровень_сообщений] [--help]

Собирает статистику табличного пространства и выводит результат в виде CSV-файла.

Эта команда не вносит изменений в файлы (режим только для чтения). Блокировки не устанавливаются.

-s=исходный_путь
--source=исходный_путь

Указывает путь к сжатому файлу или каталогу.

Примечание

Путь должен находиться в каталоге с именем PG_версия_дата, содержащем файл pg_compression.

--cfs

Указывает тип табличного пространства.

Примечание

В настоящее время реализована поддержка только типа CFS.

--log-level=уровень_сообщений

Устанавливает уровень сообщений. Возможные значения: debug, info, warning и error.

G.1.4. Коды ошибок pgpro_datactl

В Таблице G.1 показаны диапазоны кодов ошибок утилиты pgpro_datactl.

Согласно стандарту SQL, первые два символа кода ошибки обозначают класс ошибок, а последние три — определённое условие в этом классе.

Таблица G.1. Диапазоны кодов ошибок pgpro_datactl

Код ошибкиУсловие
00XXXУспех
10XXXПредупреждение
20XXXОшибка командной строки
30XXXОшибка базы данных
40XXXОшибка исходных данных
50XXXОшибка целевых данных
60XXXОшибка файловой системы/ввода-вывода
70XXXОшибка времени выполнения

В Таблице G.2 перечислены все конкретные коды ошибок и действия, которые следует выполнить при их возникновении.

В утилите pgpro_datactl используется формат PRODCTL-XXXXX. Предупреждения возвращают ненулевой код выхода, но работа продолжается. Ошибки приводят к остановке текущей операции.

Таблица G.2. Коды ошибок pgpro_datactl

Код ошибкиСообщениеПричинаДействие
PRODCTL-00000УспехОперация успешно завершена.Никаких действий не требуется.
PRODCTL-10001File not found.Отсутствует необязательный входной файл.Проверьте путь. Если отсутствие файла ожидаемо, предупреждение можно игнорировать.
PRODCTL-10002Failed to read file.Частичное чтение, ошибка прав доступа или временная проблема ввода-вывода.Повторите операцию. Проверьте права доступа пользователя и состояние диска.
PRODCTL-10003Invalid parameter.Неверное значение или формат некритического аргумента.Введите допустимое значение, иначе будет применено значение по умолчанию.
PRODCTL-10004Failed to allocate memory.Нехватка памяти в системе на некритическом этапе.Уменьшите параллелизм или размер данных.
PRODCTL-10005Failed to create working directory.Не удалось определить текущий или рабочий каталог.Проверьте путь, права доступа и свободное место на диске.
PRODCTL-10006File contains invalid content.Необязательный файл не прошёл проверку.Замените или пропустите файл.
PRODCTL-10007Failed to remove file.Файл заблокирован, или отсутствуют права доступа.Закройте все дескрипторы файла и настройте права доступа.
PRODCTL-10008Parameter required but not set.Для необязательной подзадачи не предоставлено обязательное значение, поэтому использовано значение по умолчанию.Укажите отсутствующий параметр, чтобы не использовать резервный вариант.
PRODCTL-20001Required parameter is missing.Отсутствует обязательный параметр командной строки.Добавьте необходимый параметр и перезапустите команду.
PRODCTL-20002Invalid parameter.У параметра командной строки недопустимое значение.Укажите корректное значение согласно документации.
PRODCTL-30001Database connection failed.Возникла ошибка сети, аутентификации или DSN.Проверьте аутентификацию, сетевое соединение и конфигурацию SSL.
PRODCTL-30002Database query failed.Ошибка SQL, тайм-аут или проблема прав доступа.Проверьте SQL и журналы. Поправьте схему или права доступа.
PRODCTL-40001Failed to read source file.Ошибка ввода-вывода входных данных.Убедитесь, что путь существует и пользователь имеет к нему доступ. Повторите попытку.
PRODCTL-40002Source file not found.Требуемый входной файл отсутствует.Укажите верный файл или исправьте путь.
PRODCTL-40003Failed to construct source path.Некорректный корневой путь, переменная окружения или шаблон.Исправьте конфигурацию и шаблон пути.
PRODCTL-40004File contains invalid content.Ошибка проверки обязательных входных данные или несоответствие контрольной суммы.Замените файл или исправьте его формат.
PRODCTL-50001Target file write failed.Ошибка прав доступа, дисковой квоты или диска.Освободите место на диске, исправьте права доступа и повторите попытку.
PRODCTL-50002Target file not found.Отсутствует ожидаемый выходной путь или родительский каталог.Создайте необходимые каталоги, проверьте целевой путь.
PRODCTL-60001File remove failed.Доступ запрещён, или файл используется.Снимите все блокировки с файла, настройте права доступа.
PRODCTL-60002Open file failed.Файл не найден, или доступ был запрещён.Убедитесь, что файл существует, проверьте права доступа.
PRODCTL-60003Open stream failed.Канал, сокет или файловый дескриптор недоступен.Проверьте конечную точку и права доступа.
PRODCTL-60004File write failed.Досрочное завершение записи или общая ошибка ввода-вывода.Повторите попытку. Проверьте состояние диска и файловой системы.
PRODCTL-60005File fsync failed.Не удалось сбросить данные в постоянное хранилище.Проверьте диск, параметры монтирования и журналы ядра (dmesg).
PRODCTL-60006File create failed.Родительский каталог отсутствует, или выданы неверные права доступа.Убедитесь, что родительский каталог существует, исправьте umask или права доступа.
PRODCTL-60007File rename failed.Исходный файл не существует, или прав доступа недостаточно.Убедитесь, что исходный файл существует, проверьте права доступа. Повторите попытку.
PRODCTL-60008Failed to mmap file.Ошибка mmap или нехватка адресного пространства.Переключитесь на буферизованный ввод-вывод или уменьшите размер отображаемых данных.
PRODCTL-60009Failed to stat file.Путь некорректен, или прав доступа недостаточно.Проверьте путь и права доступа пользователя.
PRODCTL-70001Memory allocation failed.Нехватка памяти в системе на критическом этапе.Уменьшите параллелизм или увеличьте системные ограничения памяти.
PRODCTL-70002Failed to create directory.Отсутствует родительский каталог, или прав доступа недостаточно.Создайте родительский каталог, проверьте права доступа.
PRODCTL-70003Failed to open directory.Указанный путь не ведёт к каталогу, или доступ запрещён.Убедитесь, что путь указывает на каталог и доступ к нему разрешён.

Пред. Наверх След.
Приложение G. Модули и расширения Postgres Pro, поставляемые в виде отдельных пакетов Начало G.2. pgpro_pwr — отчёты о нагрузке

Чтобы сделать работу с сайтом удобнее, мы используем cookie и аналитический сервис «Яндекс.Метрика». Продолжая пользоваться сайтом, вы соглашаетесь с их использованием.