# Список команд (по алфавиту) с подробным описанием их действий.

Опциональные параметры указаны в квадратных скобках.

В каждой команде есть проверки на аргументы и переменные окружения.

Каждая из этих команд имеет API, чтобы подключать её програмно,
делая require файлов отсюда:
https://github.com/Dzenly/db-presets/tree/master/cmds

## Установка переменных окружения

См. [переменные окружения](env-vars.md)

## Выдача хелпа

`db-p` или `dp-b -h` - выдает хелп.

--------------

## Добавление нового пресета

`db-p add name=<preset-name> creator=<user-name> desc="<preset-description>"`

### Параметры:

* name - имя пресета.
* creator - имя человека, создающего пресет.
* desc - описание пресета, используйте кавычки, если описание содержит пробелы.

### Шаги:

* Проверки аргументов и переменных окружения.
* Проверка что локально нет такого файла, если есть ругнуться, предложить "update" и выйти.
* Проверка, что на Amazon S3 нет такого файла. Есть есть - ругнуться и выйти.
* `pg_dumpall -h 127.0.0.1 -U postgres --clean > <директория для sql дампов>`
в папку с пресетами.
* Приtarивание к файлу лога изменений в той же временной папке.
* xz файла (кол-во потоков и уровень сжатия задаются в `XZ_OPT`).
* криптование симметричным ключом.
* заливка на amazon S3.
* Сохранение бинарного пресета с помощью pg_basebackup.
* Пометка во внутреннем файле, что выбран пресет `<preset-name>` и `clean` у него `true`.

### Результат:

* Созданы следующие файлы внутри директории указанной в системной переменной `DBP_PRESETS_DIR`:
sql дамп, changelog, бинарный дамп.
* Текущее состояние БД сохранено на Amazon S3 в виде нового зашифрованного пресета.
* Внутри объекта - два файла: пресет и текстовый файл с логом изменений, в который занесен description.

### Замечания

* Алгоритм неустойчив, если два человека одинаковый пресет в один момент времени решили создать.

--------------

## Генерация ключа шифрования (только один раз всех пресетов для одного "ведра" Amazon S3)

`db-p gen-key`

### Параметры

* Отсутствуют.

### Шаги:

* Проверяет переменную окружения DBP_AESKEY_PATH, если её нет - ругается и выходит.
* Если ключ существует - ругается и выходит.
* Если нет, генерит ключ  и сохраняет его по пути, указанному в DBP_AESKEY_PATH.

### Результат:

В системе лежит ключ шифрования.

### Замечания

* Для одного Amazon S3 "ведра", эта команда выполняется один раз.
Если нужно наладить систему на другой машине - нужно скопировать этот ключ на все машины.

--------------

## Стянуть все пресеты для заданного репозитория и ветки.

`db-p get [only=name1,name2,...] [start-app]`

### Параметры:

* only (опциональный) - задает список пресетов, которые нужно взять с Amazon S3.
Последний в списке останется выбранным пресетом.
Обратите внимание, что пробелов перед и после запятых - нет.
* start-app - нужно ли стартануть приложение после операции.
При проверке, что приложение запустилось, будет использоваться дефолтный URL (DBP_APP_DEF_URL).

### Шаги:

* Если есть параметр `only`, убеждается, что все пресеты из `only` есть на Amazon S3.
* Останавливается приложение.
* Делается `aws s3 sync`, и на локальную машину стягиваются либо все, либо указанные в `only`
пресеты из Amazon S3, которые изменились. Т.е. если какие-то пресеты у вас уже есть, и они не менялись,
они тянуться не будут.
* Все файлы (и стянутые с Amazon S3 и те, которые были раньше в папке с архивами) расшифровываются.
* Раз-xz-уются.
* И дальше в цикле по всем пресетам накатываются `psql -h 127.0.0.1 -U postgres -f name`,
накатываются миграции, сохраняются бинарные пресеты с помощью `pg_basebackup`,
при этом на бинарных пресетах фиксятся права доступа, чтобы PostgreSQL мог с ними работать.
* Команда выполняется таким образом, что последний пресет из указанных в `only`,
или последний в папке с архивами (если `only` не задали), оказывается актуальным.
* Во внутренних данных запоминается выбранный пресет, и у него проставляется флаг `clean`,
означающий, что с ним ещё не работали в тестах.
* Если start-app true - стартуем приложение.

### Результат:

* В системе есть все пресеты, в том числе в виде бинарных данных, чтобы можно было быстро переключаться между ними.
* Приложение запущено если использовали start-app.

### Замечания:

* **Важно**: Если у вас были несохраненные изменения в каком-то пресете - они исчезнут, т.к. пресет заново
восстановится из архива, и на него накатятся миграции и локализация.
* При совместной работе время от времени важно делать `get`, чтобы подкачивать изменения других
или чтобы просто накатить новые миграции и локализации на существующие пресеты.
* Особенно это важно при редактировании пресетов. Команда `set-lock` завершится с ошибкой, если
на Amazon S3 есть пресет свежее, чем на вашей машине.

--------------

## Проверка блокировки пресета на запись на amazon S3.

`db-p get-lock name=<preset-name>`

### Параметры:

* name - имя пресета.

### Шаги / Результат:

* Выводится инфа, кто когда и зачем заблокировал пресет.

### Замечания

* Выводится вся инфа, кроме ключа.

--------------

## Действия при смене конфигов (переменных окружения).

Например, при смене ветки.

`db-p init`

### Параметры:

* Отсутствуют.

### Шаги / Результат:

* Создает все нужные директории.

--------------

## Посмотреть какие есть пресеты для заданных (в [переменных окружения](env-vars.md) ) репозитория и ветки.

`db-p ls where=<local | s3> [short]`

### Параметры:

* where - откуда считывать пресеты: local - из локальной директории, s3 - на Amazon S3.
* short (опциональный) - краткая форма (без указания дат и размеров).
Работает только для where === s3.

### Шаги:

* Если where === local - просто читаем директорию с архивами пресетов и выдаем содержимое.
* Если where === s3 - запрашивает содержимое ведра с Amazon S3 и выдаем вывод от `aws s3 ls`.
* Если указан параметр short, то выводится просто список файлов без дат и размеров.

--------------

## Сброс блокировки пресета на запись на amazon S3.

`db-p reset-lock name=<preset-name> key=<lock-key>`

### Шаги / результат:

* Проверяется заблокирован ли пресет.
* Проверяется правильный ли ключ.
* Снимается лок пресета.

### Замечания:

* Команда нужна, если вы передумали править пресет.
* Команда `set-lock` возвращает ключ. Только тот, кто знает этот ключ, может разлочить пресет.
* Если забыли ключ, можно посмотреть в логах, или на крайняк в GUI Amazon S3.
* Лок снимается автоматически при `update`.

--------------

## Выбор пресета

`db-p select name=<preset-name> [url=<APPLICATION_URL> [clean] [quietly]`

### Параметры:

* name - имя пресета
* url (опциональный) - URL приложения, в виде протокол:адрес:порт `http://127.0.0.1:1337`
Нужен, чтобы ожидать приложение после рестартов. Если HTTP код возврата 200 - считается, что приложение запустилось.
По умолчанию используется системная переменная `DBP_APP_DEF_URL`.
* quietly (опциональный) - не выводить результат выполнения разных команд в stdout.
Это может быть нужно, когда используешь API из автотестов.

### Что происходит:

* Если не проставлен clean, и текущий пресет совпадает с запрашиваемым, завершаем действие без ошибок.
* Останавливается приложение.
* Если PostgreSQL работает, он останавливается.
* Делается rsync нужной директории с бинарной data в папку, указанную в `DBP_PG_DATA_DIR`.
* Запускается PostgreSQL.
* Запускается приложение.

--------------

## Блокировка пресета на запись на Amazon S3.

`db-p set-lock name=<preset-name> locker=<my-name> desc="<description>"`

### Параметры:

* name - имя пресета.
* locker - имя пользователя, блокирующего пресет.
* desc - описание с какой целью заблокировал, используйте кавычки, если описание содержит пробелы.

### Шаги / Результат:

* Проверка, не изменился ли этот пресет на Amazon S3 с момента последней синхронизации.
Если изменился - ругаемся и выходим. Просим выполнить `get`.
* Проверка, заблокирован ли пресет на запись. Если да, - выдам инфу кто когда и зачем заблокировал, и выходим.
* Генерится рандомный ключ блокировки (4 HEX цифры).
* В метаданные объекта на Amazon S3 заносится инфа, что объект заблочен: таймстемп, юзер, причина, ключ.
* Возвращается ключ, который нужно юзать при перезаписи пресета.

### Замечания

* Без лока нельзя записать файл.
* Если ты попробуешь записать файл, а он залочен другим, ты потеряешь свои изменения,
т.к. перед локом тебе нужно синхронизоваться. А если схитришь, запомнишь пресет сам,
и накатишь его после синхронизации, то перетрешь работу коллеги.
Так что важно соблюдать воркфлоу: сначала залочил пресет, потом смело редактируешь.

--------------

## Запуск приложения

`db-p start-app [url] [quietly]`

## Параметры:

* url, quietly - то же, что и для `db-p select`

## Шаги:

* Запускает приложение.
* Дожидается, что приложение запустилось.

--------------

## Обновление существующего пресета на amazon (после редактирования)

`db-p update name=<preset-name> key=<lock-key> updater=<my-name> desc="<description>"`

### Параметры:

* name - имя пресета.
* key - ключ, который выдала команда `db-p set-lock`.
* updater - юзер, который обновляет пресет.
* desc - описание, как изменился пресет, используйте кавычки, если описание содержит пробелы.

### Шаги:

* Проверка, что на amazon s3 есть такой файл. Есть нет - ругнуться и выйти.
* Проверка, что на файле стоит лок и lock-key совпадает. Если лока нет или не совпадает - ругнуться и выйти.
* Проверка, что у этого пресета есть sql, архив, и бинарный пресет. Т.е. он сделан на основе уже существующего.
* В директорию с sql дампами подкладыватся дамп от `pg_dumpall -h 127.0.0.1 -U postgres --clean`.
* К логу изменений в начало добавляется `desc`.
* xz файла (кол-во потоков и уровень сжатия задаются в `XZ_OPT`).
* приtarивание к логу изменений.
* криптование симметричным ключом.
* заливка на amazon S3.
* снятие лока на amason S3.
* обновление локальной бинарной data.
* запоминание этого пресета как выбранного, `clean` проставляется в true.

### Результат:

* Предыдущая версия сохранена в Amazon S3 за счет настроенного версионирования.
И может быть восстановлена, в случае если с пресетом накосячили.
* Новая версия пресета сохранена как current.
* Лог изменений в самом верху содержит описание изменения.
* Указанный пресет выбран как текущий и чистый.

### Замечания.

* Для Amazon S3 ведра нужно установить политику устаревания, дней в 10,
после которых считается, что пресет проверен,
и старые версии хранить не надо, чтобы экономить место и деньги.
* Если вы поняли, что не заблокировали пресет на запись, можно попробовать
заблокировать его прямо сейчас. Но если блокировка выдаст ошибку, что надо обновить
пресет, то ваши изменения нужно считать потерянными, обновить пресет,
залочить, сделать ещё раз эти изменения, и тогда уже сделать `update`.

--------------

## Посмотреть, какой пресет сейчас выбран, и какой у него статус clean.

`db-p what-selected`

### Параметры:

* Отсутствуют.

### Шаги/Результат:

* Считать внутренний JSON файл, хранящий эту инфу, и выдать пользователю как есть.

--------------

## Перезалив с другим ключом шифрования ?? (TODO)
## Удаление объектов ?? (TODO)

--------------