Luxms BI Sync

luxmsbi-sync – CLI-утилита для переноса атласов между инсталляциями Luxms BI. Позволяет создавать копии схем системы Luxms BI, с возможностью последующего восстановления на другом сервере. Основное назначение – полный перенос схем с префиксом ds_.

Использование

$ luxmsbi-sync [команда] [параметры...]

Команды

• dump – снятие копий схем в текстовом формате, выполненных с использованием pg_dump;
• restore – создание резервных копий схем (при необходимости) и восстановление данных, выгруженных при выполнении dump;
• revert – удаление схем созданных после выполнения команды restore и восстановление их резервных копий (при наличии);
• cleanup – удаление резервных копий схем, созданных программой при выполнении restore (при наличии таковых).

Команда dump

Создание копий схем производится путём вызова утилиты pg_dump для каждой схемы отдельно. Данные выгружаются в текстовых файлах <имя схемы>/restore.sql, содержащих SQL-команды, необходимые для воссоздания схем на момент создания скриптов и помещаются в сжатый архив вместе с метаданными о текущем сервере, которые будут использованы при выполнении восстановления. Сами скрипты при необходимости можно извлечь из архива и передать на выполнение psql.

к сведению

Утилита pg_dump может быть вызвана как на локальной, так и на удалённой машине через встроенный SSH-клиент. При указании параметра --remote-host pg_dump будет исполняться на удалённой машине.

При выполнении команды dump для схем так же генерируются дополнительные скрипты с постфиксами _pre и _post, которые будут выполняться перед и после основного скрипта команды restore соответственно:

• <имя схемы>/restore_pre.sql содержит скрипт создания резервной копии схемы в случае, если схема уже существует;
• <имя схемы>/restore_post.sql содержит скрипт для вставки записи в таблицу adm.datasets, а так же вызов функции, которая проверит и при необходимости исправит структуру восстановленной схемы.

к сведению

Последний файл генерируется только для схем с префиксом ds_, и только если не указан параметр --no-luxms.

Команда restore

При выполнении restore на вход программе подаётся архив, полученный после успешного завершения dump.

Для каждой схемы поочерёдно производится генерация файлов <имя схемы>/revert.sql и <имя схемы>/cleanup.sql, которые вернут исходное состояние схемы или удалят резервную копию, при выполнении одной из следующих команд, затем из архива извлекаются и по очереди исполняются необходимые файлы. Все вновь сгенерированные файлы добавляются в архив, а файл метаданных дополняется данными о результатах выполнения команды на текущем сервере.

к сведению

Каждая схема восстанавливается в рамках отдельной транзакции. При указании параметра --disable-tx транзакции не будут использованы. Актуально так же для команд revert и cleanup.

Для схем с префиксом ds_ (при отсутствии параметра --no-luxms) генерируются дополнительные скрипты:

• <имя схемы>/revert_pre.sql удаляет текущую запись схемы из adm.datasets;
• <имя схемы>/revert_post.sql возвращает предыдущую запись в adm.datasets.

к сведению

Последний файл генерируется, только если предыдущая запись существовала.

Команда revert

При выполнении revert на вход программе подаётся архив, полученный после успешного завершения restore.

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

Команда cleanup

При выполнении cleanup на вход программе подаётся архив, полученный после успешного завершения restore.

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

осторожно

Команды revert и cleanup взаимоисключающие. Для схем с одним именем не предполагается выполнение обеих команд.

Параметры

Основные параметры

--conn-name=имя – читать настройки SSH-соединения и подключения к PostgreSQL из конфигурационного файла. Использовать зарезервированное имя general в качестве имени подключения не разрешается.

--color=когда – auto, always, never - включает оформление текста управляющими ANSI-последовательностями. Любое значение, кроме auto и always равносильно never. В режиме auto ANSI-последовательности будут или не будут выводиться в зависимости от того, является ли стандартный вывод и/или вывод лога символьным устройством. По умолчанию принимается: never.

--help, -? – показать справку по аргументам командной строки и выйти.

--log-level=уровень, -l уровень – уровень логирования. Допустимые значения: error, warn, info, debug. Значение по умолчанию: info.

--log-flags=флаг – список флагов, разделённый запятыми, который управляет отображением записей в логе. Допустимые значения: date, time, micro, long, short, UTC, msgprefix, prefix, hidelevels. Значение по умолчанию: hidelevels.

--log-output=путь – задаёт куда выводить сообщения лога. Специальные значения: stdout - выводить лог в стандартный вывод, stderr - выводить лог в стандартную ошибку, discard - полностью отключает логирование. Любые другие значения будут восприниматься как путь, по которому будет создан (или продолжен) файл логов. При этом последовательность %date% будет заменена на текущую дату в формате YYYY-MM-DD, например: 2023-02-19. Значение по умолчанию: stdout.

--silent, -S – неинтерактивный режим, отключает вопросы от программы, а так же ввод пароля в стандартный ввод.

--version, -V – показать версию и выйти.

--password, -W – принудительно запрашивать ввод паролей в стандартном вводе.

--temp-dir=путь – путь до директории для хранения временных файлов.

--assume-yes, -y – автоматически отвечать “да” на все вопросы программы.

Параметры подключения к БД

--dbname=имя, -d имя – задаёт имя базы данных для подключения. Вместо имени может быть передана строка подключения. Значение по умолчанию: mi.

к сведению

Переданное явно пустое значение (например: --dbname "") сбрасывается на имя пользователя, заданное с помощью -U имя, в случае, если и оно пустое, то на имя текущего пользователя системы.

--db-timeout=время – задаёт таймаут для соединений с БД. Значение по умолчанию: 1m0s.

--host=сервер, -h сервер – задаёт имя компьютера, на котором работает сервер. Значение берётся из переменной окружения PGHOST, если она установлена. Значение по умолчанию: localhost.

--port=порт, -p порт – задаёт TCP-порт, через который сервер принимает подключения. Значение определяется переменной окружения PGPORT, если она установлена. Значение по умолчанию: 5432.

--user=имя, -U имя – имя пользователя, под которым производится подключение. Значение по умолчанию: bi.

к сведению

Переданное явно пустое значение (например: -U "") сбрасывается на имя текущего пользователя системы.

--trace – включить подробное логирование соединений с БД. Дополнительно включает логирование сообщений БД с уровнем NOTICE.

осторожно

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

Параметры SSH-соединения

--known-hosts-check=режим – задаёт режим проверки файла known_hosts. Допустимые значения: strict и ignore. В режиме strict при первом соединении с сервером пользователю будет выведен запрос на подтверждение добавления нового ключа, в случае несовпадения ключа при следующем соединении, будет выведено сообщение об ошибке. В режиме ignore файл known_hosts полностью игнорируется. Значение по умолчанию: strict.

--network=сеть – использовать указанный тип сети. Допустимые значения: tcp, tcp4, tcp6. Значение по умолчанию: tcp.

--remote-host=сервер, -r сервер – задаёт имя компьютера к которому будет осуществляться SSH-соединение. Если не задано, SSH-соединение не будет использоваться.

--remote-port=порт – задаёт TCP-порт, через который сервер принимает подключения. Значение по умолчанию: 22.

--remote-user=имя, -u имя – имя пользователя, под которым производится подключение. Значение по умолчанию: текущий пользователь системы.

--ssh-auth=метод – задаёт метод аутентификации. Допустимые значения: auto, agent, encoded-private-key, password, private-key, prompt-password, keyboard-interactive. Значение по умолчанию auto.

--ssh-timeout – таймаут для установления SSH-соединения. Значение по умолчанию:1m0s.

Далее перечислены параметры каждой из команд.

Параметры dump

--file=файл, -f файл – имя, которое будет использовано при создании выходного файла. Значение по умолчанию: luxmsbi_sync_dump.tar.gz.

--column-inserts – выгружать данные таблиц в виде команд INSERT с явным указанием столбцов (INSERT INTO таблица (столбец, …) VALUES …). Скорость восстановления при этом значительно снизится. Данный параметр не используется программой и передаётся pg_dump.

--inserts – выгружать данные таблиц в виде команд INSERT вместо COPY. Скорость восстановления при этом значительно снизится. Восстановление может провалиться полностью, если у таблицы изменён порядок столбцов. В такой ситуации можно использовать параметр --column-inserts, для которого порядок столбцов не важен, но он работает ещё медленнее. Данный параметр не используется программой и передаётся pg_dump.

--no-luxms – не генерировать скрипты специфичные для инсталляций Luxms BI. Пропускает генерацию restore_post.sql. В данный момент влияет только на схемы с префиксом ds_.

--no-owner, -O – не формировать команды, устанавливающие владельца объектов базы данных. По умолчанию pg_dump генерирует команды ALTER OWNER или SET SESSION AUTHORIZATION для назначения владельцев объектов базы. Эти команды завершатся неудачно, если скрипт будет запущен не суперпользователем или не владельцем объектов. Чтобы создать скрипт, который можно выполнить при восстановлении от лица произвольного пользователя и назначить его в качестве владельца объектов восстанавливаемой базы, необходимо указать данный параметр.

--schema-only, -s – выгружать только определение объектов (схемы), без данных.

--schema=имя, -n имя – выгрузить только схемы, соответствующие указанным именам; вместе с этими схемами будут выгружены и все содержащиеся в них объекты. При отсутствии этого параметра, будут выгружены все схемы с префиксом ds_, исключая ds_import_stat, ds_master_4_0 и ds_res. Чтобы выгрузить несколько схем, ключ -n можно указать несколько раз.

--exclude-schema=имя, -N имя – не выгружать схемы, соответствующие имени. Параметр -N можно использовать в команде несколько раз для исключения нескольких схем. При одновременном использовании параметров -n и -N значения второго будут проигнорированы.

-x, --no-privileges – не выгружать права (назначение/отзыв). Данный параметр не используется программой и передаётся pg_dump.

Параметры restore

--buffer-size=размер – размер буфера при чтении инструкций. Значение по умолчанию: 4096.

--file=файл, -f файл – имя файла, подаваемого на вход. Значение по умолчанию: luxmsbi_sync_dump.tar.gz.

--force – не завершать выполнение с ошибкой при выполнении потенциально необратимых действий. Актуально только в неинтерактивном режиме (при использовании --silent).

--disable-tx – не использовать транзакции.

--schema=имя, -n имя – восстановить только схемы, соответствующие указанным именам. При отсутствии этого параметра, будут восстановлены все схемы из архива. Чтобы восстановить несколько схем, ключ -n можно указать несколько раз.

--exclude-schema=имя, -N имя – не восстанавливать схемы, соответствующие имени. Параметр -N можно использовать в команде несколько раз для исключения нескольких схем. При одновременном использовании параметров -n и -N значения второго будут проигнорированы.

--no-luxms – не генерировать и не выполнять скрипты специфичные для инсталляций Luxms BI. Пропускает выполнение restore_post.sql и генерацию revert_pre.sql и revert_post.sql. В данный момент влияет только на схемы с префиксом ds_.

Параметры revert

--buffer-size=размер – размер буфера при чтении инструкций. Значение по умолчанию: 4096.

--file=файл, -f файл – имя файла, подаваемого на вход. Значение по умолчанию: luxmsbi_sync_dump.tar.gz.

--force – не завершать выполнение с ошибкой при выполнении потенциально необратимых действий. Актуально только в неинтерактивном режиме (при использовании --silent).

--disable-tx – не использовать транзакции.

--schema=имя, -n имя – восстановить резервные копии только для схем, соответствующих указанным именам. При отсутствии этого параметра, будут восстановлены резервные копии для всех восстановленных ранее схем из архива. Чтобы восстановить резервные копии нескольких схем, ключ -n можно указать несколько раз.

--exclude-schema=имя, -N имя – не восстанавливать резервные копии схем, соответствующих имени. Параметр -N можно использовать в команде несколько раз для исключения нескольких схем. При одновременном использовании параметров -n и -N значения второго будут проигнорированы.

--no-luxms – не выполнять скрипты специфичные для инсталляций Luxms BI. Пропускает выполнение revert_pre.sql и revert_post.sql. В данный момент влияет только на схемы с префиксом ds_.

Параметры cleanup

--buffer-size=размер – размер буфера при чтении инструкций. Значение по умолчанию: 4096.

--file=файл, -f файл – имя файла, подаваемого на вход. Значение по умолчанию: luxmsbi_sync_dump.tar.gz.

--force – не завершать выполнение с ошибкой при выполнении потенциально необратимых действий. Актуально только в неинтерактивном режиме (при использовании --silent).

--disable-tx – не использовать транзакции.

--schema=имя, -n имя – удалить резервные копии только для схем, соответствующих указанным именам. При отсутствии этого параметра, будут удалены резервные копии для всех восстановленных ранее схем из архива. Чтобы удалить резервные копии нескольких схем, ключ -n можно указать несколько раз.

--exclude-schema=имя, -N имя – не удалять резервные копии схем, соответствующих имени. Параметр -N можно использовать в команде несколько раз для исключения нескольких схем. При одновременном использовании параметров -n и -N значения второго будут проигнорированы.

Устаревшие параметры

Ранее для команд restore, revert и cleanup существовали следующие параметры:

--initial-buffer=размер – начальное значение буфера для чтения SQL-команд в байтах.

--max-buffer=размер – максимальное значение буфера для чтения SQL-команд в байтах.

В данный момент оба параметра считаются устаревшими и более не используются.

На смену им введён --buffer-size=размер, который выступает как компромисс между использованием ресурсов ЦПУ/ОЗУ, значение по умолчанию (4096) должно быть приемлемым для работы на большинстве систем.

к сведению

Для сохранения обратной совместимости, программа всё ещё будет принимать оба значения передаваемые с помощью --initial-buffer и --max-buffer, само значение при этом будет проигнорировано и не будет влиять на --buffer-size.

Переменные окружения

PGDATABASE – действует так же, как параметр соединения --dbname.

PGHOST – действует так же, как параметр соединения --host.

PGPASSWORD – задаёт пароль пользователя БД.

PGPORT – действует так же, как параметр соединения --port.

PGUSER – действует так же, как параметр соединения --user.

SSH_AUTH_PASSWORD – пароль пользователя для SSH-соединения.

SSH_AUTH_SOCK – указывает на путь к unix-сокету, который будет использоваться для коммуникации с SSH-агентом.

SSH_KNOWN_HOSTS – устанавливает путь к файлу known_hosts пользователя, по умолчанию: $HOME/.ssh/known_hosts.

к сведению

Если файла known_hosts не существует, то он будет создан с модификаторами доступа 0600. Если папки .ssh не существует, она будет создана с модификаторами доступа 0700.

SSH_PRIVATE_KEY – устанавливает путь к ключу пользователя, по умолчанию: $HOME/.ssh/id_rsa.

SSH_KEY_PASSPHRASE – в режиме encoded-private-key устанавливает пароль для файла ключа выше.

LUXMSBI_SYNC_COLOR – auto, always, never - включает оформление текста управляющими ANSI-последовательностями. Любое значение, кроме auto и always равносильно never. В режиме auto ANSI-последовательности будут или не будут выводиться в зависимости от того, является ли стандартный вывод и/или вывод лога символьным устройством. По умолчанию принимается: never.

LUXMSBI_SYNC_CONFIG – задаёт путь конфигурационного файла. По умолчанию путь конфигурационного файла: $HOME/.config/luxmsbi-sync/config.toml.

LUXMSBI_SYNC_TEMP_DIR – действует так же, как параметр--temp-dir.

к сведению

При отсутствии значения в параметре командной строки и переменной окружения, на unix-подобных системах, будет использована переменная TMPDIR, если же и она пустая, то временные файлы будут сохраненяться по пути /tmp/.

Следующие четыре переменные окружения принимаются pg_dump и SQL-драйвером pgx, который использован в программе, и отвечают за конфигурацию зашифрованного соединения с БД:
PGSSLMODE, PGSSLCERT, PGSSLKEY, PGSSLROOTCERT

Следует учитывать, что при использовании SSH ни одна из четырёх переменных не передаётся pg_dump.
Более того, при использовании SSH TLS полностью отключается.

Конфигурационный файл

По умолчанию путь конфигурационного файла принят как: $HOME/.config/luxmsbi-sync/config.toml. Отсутствие файла по данному пути или по пути переменной LUXMSBI_SYNC_CONFIG само по себе к ошибке не приведёт.

При чтении параметров из конфига, на экран и/или в логе будет выведено сообщение:

read options from: "$HOME/.config/luxmsbi-sync/config.toml"

Структура файла:

[general]
color = "auto"
log-level = "debug"
log-flags = "micro,prefix"
log-output = "discard"
silent = false
prompt-passwords = true
assume-yes = false
temp-dir = "/tmp/"

[conn_name]
database = "dbname"
host = "dbhost"
port = 5432
user = "dbuser"
password = "secret"
remote-host = "remote-host"
remote-port = 22
remote-user = "admin"
remote-auth = "encoded-private-key"
remote-password = "another secret"
key-path = "/home/<user>/.ssh/id_rsa"
key-passphrase = "third secret"

В секции general указываются основные параметры программы. В остальных секциях с помощью перечисленных выше полей указываются настройки соединения. Имя general зарезервировано для настроек самой программы и не может быть использовано в качестве имени соединения.

Имя секции с помощью параметра --conn-name передаётся при запуске программы как:

$ luxmsbi-sync dump --conn-name conn_name

Логи

Внешний вид сообщений лога конфигурируется с помощью параметра --log-flags. Ниже приведены примеры использования:

date – отобразить дату перед сообщением:

$ luxmsbi-sync dump --log-flags date
2023/02/19 [INFO ] started

time – отобразить время:

$ luxmsbi-sync dump --log-flags time
14:42:41 [INFO ] started

micro – отобразить время и миллисекунды, подразумевает time:

$ luxmsbi-sync dump --log-flags micro
14:43:56.816791 [INFO ] started

long – отобразить полный путь до файла исходного кода со строкой, на которой вызвана функция записи в лог:

$ luxmsbi-sync dump --log-flags long
luxmsbi-sync/cmd/luxmsbi-sync/main.go:1077: [INFO ] started

short – отобразить только имя файла исходного кода со строкой:

$ luxmsbi-sync dump --log-flags short
main.go:1077: [INFO ] started

UTC – отобразить время в UTC, требует time или micro:

$ luxmsbi-sync dump --log-flags UTC,micro
11:51:20.253903 [INFO ] started

prefix – отобразить текстовый префикс фиксированной ширины:

$ luxmsbi-sync dump --log-flags prefix,time
verbose msg  14:53:12 [INFO ] started

msgprefix – отобразить префикс перед сообщением, а не в начале строки, предполагает prefix:

$ luxmsbi-sync dump --log-flags msgprefix,time
14:54:33 verbose msg  [INFO ] started

hidelevels – скрыть сам уровень логирования из сообщения:

$ luxmsbi-sync dump --log-flags hidelevels
started

Замечания

При использовании SSH-соединения адрес БД указывается относительно машины, с которой устанавливается SSH-соединение.

Одновременная работа с SSH и TLS невозможна.

Luxms BI Sync не имеет зависимостей, но для снятия копий схем требует pg_dump. Так как имеется возможность удалённого вызова утилиты на машине, где установлена БД, то эта зависимость не задана жёстко.

Для Luxms BI Sync действуют те же ограничения, что и для pg_dump. Так как pg_dump применяется для переноса данных в новые версии PostgreSQL, предполагается, что вывод pg_dump можно загрузить на сервер PostgreSQL более новой версии, чем версия pg_dump. pg_dump может также выгружать данные серверов PostgreSQL более старых версий, чем его собственная. Однако утилита pg_dump не может выгружать данные с серверов PostgreSQL более новых основных версий; она не будет даже пытаться делать это, во избежание некорректной выгрузки. Также не гарантируется, что вывод pg_dump может быть загружен на сервере более старой основной версии — даже если данные были выгружены с сервера той же версии.

Примерно то же справедливо и для версии luxmsbi-pg: перенос с более старой версии на новую возможен, перенос с более новой версии на старую - не гарантируется.

Связанные внешние объекты схем ds_* (например кубы, размерности и источники данных) в данный момент автоматически не собираются.

Выбор параметров для команды dump обусловлен минимально поддерживаемой (на момент написания) версией PostgreSQL - 11.

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

Примеры

Снять копии схем ds_example001 и ds_example002 с локальной базы (localhost:5432):

$ luxmsbi-sync dump -n ds_example001 -n ds_example002

Восстановить обе снятые копии из архива на сервере example.org:

$ luxmsbi-sync restore -h example.org

Вернуть ds_example001 к исходному состоянию:

$ luxmsbi-sync revert -h example.org -n ds_example001

Удалить бекап ds_example002:

$ luxmsbi-sync cleanup -h example.org -n ds_example002

Снять копии всех схем с префиксом ds_, кроме ds_master_4_0, ds_import_stat и ds_res на сервере example.org, использовать SSH-соединение на порту 23900 от имени пользователя admin:

$ luxmsbi-sync dump -r example.org -u admin --remote-port 23900

Восстановить все копии на сервере назначения, прочитав параметры подключения из секции конфигурационного файла destination, не задавать вопросов, но запрашивать ввод паролей в стандартном вводе:

$ luxmsbi-sync restore --conn-name destination -y -W

Удалить бекапы всех схем на сервере, кроме схемы ds_important, прочитать параметры подключения из секции конфигурационного файла destination, сохранить логи в файле с именем cleanup_<текущая дата>.txt, использовать формат логов: дата + время в UTC с указанием миллисекунд + сообщение:

$ luxmsbi-sync cleanup -N ds_important --conn-name destination --log-output cleanup_%date%.txt --log-flags UTC,date,micro

Сохранить копии схем ds_example003 и ds_example004 с локальной базы (localhost:5432) в файле dump.tar.gz:

$ luxmsbi-sync dump -n ds_example003 -n ds_example004 -f dump.tar.gz

Восстановить схему ds_example003 на сервере example.org:

$ luxmsbi-sync restore -f dump.tar.gz -n ds_example003 -h example.org

Восстановить схему ds_example004 на сервере example.org:

$ luxmsbi-sync restore -f dump.tar.gz -n ds_example004 -h example.org

Удалить бекапы обеих схем:

$ luxmsbi-sync cleanup -f dump.tar.gz -h example.org