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 System, сжатая файловая система). Этот модуль предлагает следующую функциональность:

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

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

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

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

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

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

G.1.3. Команды

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

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

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

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

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

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

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

G.1.3.2. estimate

pgpro_datactl estimate --source=исходный_путь [--log-level=уровень_протоколирования] [--help]

Оценивает коэффициенты сжатия для различных алгоритмов сжатия.

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

Указывает путь к несжатому каталогу табличного пространства Postgres Pro.

--log-level=уровень_протоколирования

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

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

pgpro_datactl estimate --source /data/tablespace/PG_17_202409081

Пример оценки сжатия с ведением журнала отладки:

pgpro_datactl estimate --source /path/to/tablespace --log-level debug

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

Source file or directory: /data/tablespace/PG_17_202409081
Compression ratios and timings:
  pglz  : ratio=1.85, time=12.34 block/ms
  zlib  : ratio=2.41, time=3.21 block/ms
  lz4   : ratio=1.92, time=45.67 block/ms
  zstd  : ratio=2.58, time=8.91 block/ms

Best ratio: "zstd" with 2.58
Best speed: "lz4" with 45.67 block/ms

  • ratio — коэффициент сжатия (исходный размер / сжатый размер).

  • time — скорость сжатия в блоках на миллисекунду.

Лучший алгоритм по коэффициенту сжатия и по скорости выводится в конце.

G.1.3.3. 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.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. 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.6. 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=уровень_сжатия

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

  • 0–9 для zlib

  • 1 для pglz

  • 0–12 для lz4

  • -131072–22 для zstd

При значении 0 для всех алгоритмов сжатия устанавливается уровень сжатия по умолчанию, равный 1.

По умолчанию: 1

--zero-on-error

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

--in-place

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

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

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

G.1.3.7. stat

pgpro_datactl stat --source=исходный_путь --cfs
[--log-level=уровень_протоколирования] [--per-file] [--help]

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

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

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

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

Примечание

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

--cfs

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

Примечание

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

--log-level=уровень_протоколирования

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

--per-file

Задаёт вывод подробной статистики (размер блока и количество блоков) для каждого файла. Результат сохраняется в файл с префиксом cfs_per_file_stat_.

G.1.3.8. 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.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 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 map 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 для корректной работы и повышения удобства. Нажимая кнопку «Принять» или продолжая пользоваться сайтом, вы соглашаетесь на их использование в соответствии с Политикой в отношении обработки cookie ООО «ППГ», в том числе на передачу данных из файлов cookie сторонним статистическим и рекламным службам. Вы можете управлять настройками cookie через параметры вашего браузера