Обзор синтаксиса gpbackup

Павел Семёнов

Contents

Опции
Коды возврата

Утилита gpbackup имеет следующий синтаксис:

gpbackup --dbname <database_name>
[--backup-dir <directory>]
[--compression-level <level>]
[--compression-type <type>]
[--copy-queue-size <int>]
[--data-only]
[--debug]
[--exclude-schema <schema> [--exclude-schema <schema> ...]]
[--exclude-table <schema.table> [--exclude-table <schema.table> ...]]
[--exclude-schema-file <file_name>]
[--exclude-table-file <file_name>]
[--include-schema <schema> [--include-schema <schema> ...]]
[--include-table <schema.table> [--include-table <schema.table> ...]]
[--include-schema-file <file_name>]
[--include-table-file <file_name>]
[--incremental [--from-timestamp <backup-timestamp>]]
[--jobs <int>]
[--leaf-partition-data]
[--metadata-only]
[--no-compression]
[--no-inherits]
[--no-history]
[--plugin-config <config_file_location>]
[--quiet]
[--single-data-file]
[--single-backup-dir]
[--verbose]
[--with-stats]
[--without-globals]

gpbackup --help

gpbackup --version

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

Опция	Описание
--dbname <dbname>	Имя базы данных для создания бэкапа. Обязательная опция
--backup-dir <directory>	Каталог для сохранения файлов бэкапа. Значение должно быть абсолютным путем. По умолчанию бэкапы создаются в каталоге backups, расположенном: в $MASTER_DATA_DIRECTORY для мастера; в соответствующих каталогах данных для сегментов. Каждый бэкап сохраняется в отдельном подкаталоге с датой и меткой времени в названии: YYYYMMDD/YYYYMMDDHHMMSS/. Подробнее см. в разделе Настройка расположения бэкапа
--compression-level <level>	Уровень сжатия от `1` до `9`, применяемый к файлам данных бэкапа. По умолчанию используется уровень `1`. Более высокие уровни обеспечивают лучшее сжатие, но увеличивают потребление ресурсов и время выполнения. Чтобы создать бэкап с данными в формате CSV без сжатия, используйте опцию `--no-compression` Подробнее см. в разделе Настройка сжатия бэкапов
--compression-type <type>	Алгоритм сжатия файлов данных: `gzip` (по умолчанию) или `zstd`. Для сжатия `zstd` требуется установленная библиотека Zstandard. Проверить ее наличие можно командой: `$ zstd --version` Подробнее см. в разделе Настройка сжатия бэкапов
--copy-queue-size <int>	При использовании опции `--single-data-file` можно задать число предварительно инициализированных команд COPY для записи данных в бэкап. Это ускоряет работу с большим числом небольших таблиц за счет уменьшения накладных расходов на инициализацию команд `COPY`. Нельзя использовать вместе с `--jobs`
--data-only	Создает бэкап только данных таблиц, без метаданных (SQL-команд для создания объектов)
--debug	Добавляет подробные отладочные сообщения уровней `verbose` и `debug` в вывод `gpbackup`
--exclude-schema <schema>	Исключает указанную схему из бэкапа. Опцию можно указать несколько раз. Если имя схемы содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках. Опция несовместима с другими опциями фильтрации схем (`--exclude-schema-file`, `--include-schema`, `--include-schema-file`) и таблиц (`--include-table` и др.). Партиции в исключаемых схемах Если конечные партиции и родительская таблица хранятся в разных схемах, поведение зависит от параметра `--leaf-partition-data`: При указании `--leaf-partition-data` данные конечных партиций включаются, даже если их схема исключена. Без `--leaf-partition-data` данные таких партиций не попадают в бэкап. Независимо от `--leaf-partition-data`, метаданные всех конечных партиций включаются в бэкап. Подробнее см. в разделе Частичное резервное копирование
--exclude-schema-file <file_name>	Исключает из бэкапа схемы, перечисленные в файле. Файл должен содержать по одной схеме в каждой строке, без пустых строк в конце. Если имя схемы содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках. Опция несовместима с другими опциями фильтрации схем (`--exclude-schema-file`, `--include-schema`, `--include-schema-file`) и таблиц (`--include-table` и др.). Подробнее см. в разделе Частичное резервное копирование
--exclude-table <schema.table>	Исключает из бэкапа указанную таблицу или другой объект — последовательность, представление или материализованное представление. Опцию можно указать несколько раз. Имя объекта должно быть в формате `<schema>.<table>`. Если имя содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках. Опция несовместима с опциями исключения схем (`--exclude-schema` и `--exclude-schema-file`) и фильтрации таблиц (`--include-table` и др.). Исключение таблиц и партиций Для партиционированных таблиц можно исключить только родительскую таблицу и конечные партиции, но не промежуточные. Чтобы исключить конечную партицию, нужно также указать `--leaf-partition-data`. Подробнее см. в разделе Частичное резервное копирование
--exclude-table-file <file_name>	Исключает из бэкапа таблицы и другие объекты — последовательности, представления, материализованные представления — перечисленные в файле. Файл должен содержать по одному объекту в каждой строке, без пустых строк в конце. Имя объекта должно быть в формате `<schema>.<table>`. Если имя содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках. Опция несовместима с опциями исключения схем (`--exclude-schema` и `--exclude-schema-file`) и фильтрации таблиц (`--include-table` и др.). Подробнее см. в разделе Частичное резервное копирование
--include-schema <schema>	Включает в бэкап только указанную схему. Опцию можно указать несколько раз. Если имя схемы содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках. Опция несовместима с другими опциями фильтрации схем (`--exclude-schema`, `--exclude-schema-file`, `--include-schema-file`) и включения таблиц (`--include-table` и `--include-table-file`). Подробнее см. в разделе Частичное резервное копирование
--include-schema-file <file_name>	Включает в бэкап только схемы, перечисленные в файле. Файл должен содержать по одной схеме в строке, без пустых строк в конце. Если имя схемы содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках. Опция несовместима с другими опциями фильтрации схем (`--exclude-schema`, `--exclude-schema-file`, `--include-schema-file`) и включения таблиц (`--include-table` и `--include-table-file`). Подробнее см. в разделе Частичное резервное копирование
--include-table <schema.table>	Включает в бэкап только указанную таблицу или другой объект — последовательность, представление или материализованное представление. Опцию можно указать несколько раз. Имя объекта должно быть в формате `<schema>.<table>`. Если имя содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках. Опция несовместима с другими опциями фильтрации таблиц (`--exclude-table` и др.) и схем (`--exclude-schema` и др.). `gpbackup` не включает автоматически объекты, от которых зависит указанный объект. Например: Если таблица использует последовательность, ее нужно включить отдельно. Для материализованного представления нужно включить таблицы, которые оно использует. Включение партиционированных таблиц Для партиционированных таблиц можно включить только родительскую таблицу и конечные партиции, но не промежуточные. Чтобы включить конечную партицию, нужно также указать `--leaf-partition-data`. В этом случае сохраняются данные партиции и метаданные родительской таблицы. Подробнее см. в разделе Частичное резервное копирование
--include-table-file <file_name>	Включает в бэкап только таблицы или другие объекты — последовательности, представления, материализованные представления — перечисленные в файле. Имя объекта должно быть в формате `<schema>.<table>`. Файл должен содержать по одному объекту в строке, без пустых строк в конце. Если имя содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках. Опция несовместима с другими опциями фильтрации таблиц (`--exclude-table` и др.) и схем (`--exclude-schema` и др.). `gpbackup` не включает автоматически объекты, от которых зависит указанный объект. Например: Если таблица использует последовательность, ее нужно включить отдельно. Для материализованного представления нужно включить таблицы, которые оно использует. Подробнее см. в разделе Частичное резервное копирование
--incremental	Создает инкрементальный бэкап для включения в инкрементальный набор бэкапов. Набор включает один полный бэкап и один или несколько инкрементальных. При использовании `--incremental` утилита ищет последний совместимый бэкап и использует его как основу для нового инкрементального бэкапа. Также можно создать инкрементальный бэкап от конкретного момента с помощью опции `--from-timestamp`. Опция требует обязательного указания `--leaf-partition-data` и несовместима с `--data-only` и `--metadata-only`. Подробнее см. в разделе Инкрементальное резервное копирование
--from-timestamp <backup-timestamp>	Указывает метку времени существующего бэкапа, который используется как базовый для создаваемого инкрементального бэкапа. Этот бэкап должен быть создан с совместимым набором опций. Можно использовать только вместе с `--incremental`. Подробнее см. в разделе Инкрементальное резервное копирование
--jobs <int>	Количество задач для параллельного бэкапа. По умолчанию используется одна задача, и объекты сохраняются последовательно. При увеличении числа задач каждая из них сохраняет таблицы в отдельной транзакции, что ускоряет процесс. Это приводит к увеличению числа блокировок таблиц. Если блокировка не может быть установлена, `gpbackup` завершает работу. Рекомендуется использовать параллельные бэкапы в периоды низкой активности. Опция несовместима с `--metadata-only` и `--single-data-file`. Подробнее см. в разделе Параллельное резервное копирование и восстановление
--leaf-partition-data	Создает отдельный файл данных для каждой конечной партиции партиционированной таблицы. Без `--leaf-partition-data` (по умолчанию) вся таблица сохраняется в одном файле данных на каждом сегменте. Опция используется для фильтрации на уровне партиций при включении и исключении объектов, например, с помощью `--include-table` Подробнее см. в разделе Партиционированные таблицы
--metadata-only	Создает бэкап только метаданных (SQL-команд для создания объектов), без данных таблиц
--no-compression	Отключает сжатие файлов данных бэкапа. Подробнее см. в разделе Настройка сжатия бэкапов
--no-inherits	При использовании `--include-table` или `--include-table-file` в бэкап также включаются таблицы, связанные с указанными отношением наследования. С опцией `--no-inherits` такие связи игнорируются и сохраняются только указанные таблицы
--no-history	Не записывает информацию об операции в служебную базу данных истории бэкапов (`gpbackup_history.db` в каталоге данных мастера)
--plugin-config <config_file_location>	Путь к файлу конфигурации плагина `gpbackup`. Плагины расширяют функциональность утилиты, например, позволяют сохранять бэкапы на удаленные хранилища. Файл конфигурации плагина — это YAML-файл, который содержит информацию о плагине и его настройки, используемые при создании бэкапа. Для восстановления бэкапа, созданного с плагином, требуется тот же плагин. Опция несовместима с `--backup-dir`
--quiet	Сокращает вывод до предупреждений и ошибок
--single-data-file	Создает по одному файлу данных для каждого сегмента со всеми его данными. Без этой опции (по умолчанию) создается отдельный CSV-файл на каждую таблицу сегмента. Бэкапы, созданные с этой опцией, нельзя восстанавливать параллельно через `gprestore --jobs`. Подробнее см. в разделе Настройка структуры бэкапа
--single-backup-dir	Сохраняет все файлы на хосте в одном каталоге, вместо отдельного каталога для каждого сегмента. При этом обязательно указывается `--backup-dir`. Файлы сохраняются в <backup-dir>/backups/YYYYMMDD/YYYYMMDDHHMMSS. Подробнее см. в разделе Настройка структуры бэкапа
--verbose	Добавляет подробные сообщения уровня `verbose` в вывод `gpbackup`
--with-stats	Включает статистику базы данных в бэкап
--without-globals	Исключает глобальные объекты Greengage DB — роли, табличные пространства, ресурсные очереди и группы и другие объекты — из бэкапа
--version	Выводит версию `gpbackup`
--help	Показывает справочную информацию о `gpbackup`

--dbname <dbname>

Имя базы данных для создания бэкапа. Обязательная опция

--backup-dir <directory>

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

По умолчанию бэкапы создаются в каталоге backups, расположенном:

в $MASTER_DATA_DIRECTORY для мастера;
в соответствующих каталогах данных для сегментов.

Каждый бэкап сохраняется в отдельном подкаталоге с датой и меткой времени в названии: YYYYMMDD/YYYYMMDDHHMMSS/.

Подробнее см. в разделе Настройка расположения бэкапа

--compression-level <level>

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

Чтобы создать бэкап с данными в формате CSV без сжатия, используйте опцию --no-compression

Подробнее см. в разделе Настройка сжатия бэкапов

--compression-type <type>

Алгоритм сжатия файлов данных: gzip (по умолчанию) или zstd.

Для сжатия zstd требуется установленная библиотека Zstandard. Проверить ее наличие можно командой:

$ zstd --version

Подробнее см. в разделе Настройка сжатия бэкапов

--copy-queue-size <int>

При использовании опции --single-data-file можно задать число предварительно инициализированных команд COPY для записи данных в бэкап. Это ускоряет работу с большим числом небольших таблиц за счет уменьшения накладных расходов на инициализацию команд COPY.

Нельзя использовать вместе с --jobs

--data-only

Создает бэкап только данных таблиц, без метаданных (SQL-команд для создания объектов)

--debug

Добавляет подробные отладочные сообщения уровней verbose и debug в вывод gpbackup

--exclude-schema <schema>

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

Опция несовместима с другими опциями фильтрации схем (--exclude-schema-file, --include-schema, --include-schema-file) и таблиц (--include-table и др.).

Партиции в исключаемых схемах

Если конечные партиции и родительская таблица хранятся в разных схемах, поведение зависит от параметра --leaf-partition-data:

При указании --leaf-partition-data данные конечных партиций включаются, даже если их схема исключена.
Без --leaf-partition-data данные таких партиций не попадают в бэкап.

Независимо от --leaf-partition-data, метаданные всех конечных партиций включаются в бэкап.

Подробнее см. в разделе Частичное резервное копирование

--exclude-schema-file <file_name>

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

Подробнее см. в разделе Частичное резервное копирование

--exclude-table <schema.table>

Исключает из бэкапа указанную таблицу или другой объект — последовательность, представление или материализованное представление. Опцию можно указать несколько раз. Имя объекта должно быть в формате <schema>.<table>. Если имя содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках.

Опция несовместима с опциями исключения схем (--exclude-schema и --exclude-schema-file) и фильтрации таблиц (--include-table и др.).

Исключение таблиц и партиций

Для партиционированных таблиц можно исключить только родительскую таблицу и конечные партиции, но не промежуточные. Чтобы исключить конечную партицию, нужно также указать --leaf-partition-data.

Подробнее см. в разделе Частичное резервное копирование

--exclude-table-file <file_name>

Исключает из бэкапа таблицы и другие объекты — последовательности, представления, материализованные представления — перечисленные в файле. Файл должен содержать по одному объекту в каждой строке, без пустых строк в конце. Имя объекта должно быть в формате <schema>.<table>. Если имя содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках.

Опция несовместима с опциями исключения схем (--exclude-schema и --exclude-schema-file) и фильтрации таблиц (--include-table и др.).

Подробнее см. в разделе Частичное резервное копирование

--include-schema <schema>

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

Опция несовместима с другими опциями фильтрации схем (--exclude-schema, --exclude-schema-file, --include-schema-file) и включения таблиц (--include-table и --include-table-file).

Подробнее см. в разделе Частичное резервное копирование

--include-schema-file <file_name>

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

Подробнее см. в разделе Частичное резервное копирование

--include-table <schema.table>

Включает в бэкап только указанную таблицу или другой объект — последовательность, представление или материализованное представление. Опцию можно указать несколько раз. Имя объекта должно быть в формате <schema>.<table>. Если имя содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках.

Опция несовместима с другими опциями фильтрации таблиц (--exclude-table и др.) и схем (--exclude-schema и др.).

gpbackup не включает автоматически объекты, от которых зависит указанный объект. Например:

Если таблица использует последовательность, ее нужно включить отдельно.
Для материализованного представления нужно включить таблицы, которые оно использует.

Включение партиционированных таблиц

Для партиционированных таблиц можно включить только родительскую таблицу и конечные партиции, но не промежуточные. Чтобы включить конечную партицию, нужно также указать --leaf-partition-data. В этом случае сохраняются данные партиции и метаданные родительской таблицы.

Подробнее см. в разделе Частичное резервное копирование

--include-table-file <file_name>

Включает в бэкап только таблицы или другие объекты — последовательности, представления, материализованные представления — перечисленные в файле. Имя объекта должно быть в формате <schema>.<table>. Файл должен содержать по одному объекту в строке, без пустых строк в конце. Если имя содержит символы, отличные от строчных букв, цифр или подчеркиваний, укажите его в двойных кавычках.

Опция несовместима с другими опциями фильтрации таблиц (--exclude-table и др.) и схем (--exclude-schema и др.).

gpbackup не включает автоматически объекты, от которых зависит указанный объект. Например:

Если таблица использует последовательность, ее нужно включить отдельно.
Для материализованного представления нужно включить таблицы, которые оно использует.

Подробнее см. в разделе Частичное резервное копирование

--incremental

Создает инкрементальный бэкап для включения в инкрементальный набор бэкапов. Набор включает один полный бэкап и один или несколько инкрементальных.

При использовании --incremental утилита ищет последний совместимый бэкап и использует его как основу для нового инкрементального бэкапа. Также можно создать инкрементальный бэкап от конкретного момента с помощью опции --from-timestamp.

Опция требует обязательного указания --leaf-partition-data и несовместима с --data-only и --metadata-only.

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

--from-timestamp <backup-timestamp>

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

Можно использовать только вместе с --incremental.

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

--jobs <int>

Количество задач для параллельного бэкапа. По умолчанию используется одна задача, и объекты сохраняются последовательно. При увеличении числа задач каждая из них сохраняет таблицы в отдельной транзакции, что ускоряет процесс. Это приводит к увеличению числа блокировок таблиц. Если блокировка не может быть установлена, gpbackup завершает работу. Рекомендуется использовать параллельные бэкапы в периоды низкой активности.

Опция несовместима с --metadata-only и --single-data-file.

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

--leaf-partition-data

Создает отдельный файл данных для каждой конечной партиции партиционированной таблицы. Без --leaf-partition-data (по умолчанию) вся таблица сохраняется в одном файле данных на каждом сегменте.

Опция используется для фильтрации на уровне партиций при включении и исключении объектов, например, с помощью --include-table

Подробнее см. в разделе Партиционированные таблицы

--metadata-only

Создает бэкап только метаданных (SQL-команд для создания объектов), без данных таблиц

--no-compression

Отключает сжатие файлов данных бэкапа.

Подробнее см. в разделе Настройка сжатия бэкапов

--no-inherits

При использовании --include-table или --include-table-file в бэкап также включаются таблицы, связанные с указанными отношением наследования. С опцией --no-inherits такие связи игнорируются и сохраняются только указанные таблицы

--no-history

Не записывает информацию об операции в служебную базу данных истории бэкапов (gpbackup_history.db в каталоге данных мастера)

--plugin-config <config_file_location>

Путь к файлу конфигурации плагина gpbackup.

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

Для восстановления бэкапа, созданного с плагином, требуется тот же плагин.

Опция несовместима с --backup-dir

--quiet

Сокращает вывод до предупреждений и ошибок

--single-data-file

Создает по одному файлу данных для каждого сегмента со всеми его данными. Без этой опции (по умолчанию) создается отдельный CSV-файл на каждую таблицу сегмента.

Бэкапы, созданные с этой опцией, нельзя восстанавливать параллельно через gprestore --jobs.

Подробнее см. в разделе Настройка структуры бэкапа

--single-backup-dir

Сохраняет все файлы на хосте в одном каталоге, вместо отдельного каталога для каждого сегмента. При этом обязательно указывается --backup-dir. Файлы сохраняются в <backup-dir>/backups/YYYYMMDD/YYYYMMDDHHMMSS.

Подробнее см. в разделе Настройка структуры бэкапа

--verbose

Добавляет подробные сообщения уровня verbose в вывод gpbackup

--with-stats

Включает статистику базы данных в бэкап

--without-globals

Исключает глобальные объекты Greengage DB — роли, табличные пространства, ресурсные очереди и группы и другие объекты — из бэкапа

--version

Выводит версию gpbackup

--help

Показывает справочную информацию о gpbackup

gpbackup возвращает следующие коды:

0 — бэкап успешно завершен.
1 — бэкап завершен с некритичными ошибками.
2 — бэкап завершился с ошибкой.

Плагин для хранения в S3

gprestore

Обзор синтаксиса gpbackup

Опции

Коды возврата