github.com/mailru/activerecord@v1.12.2/docs/manual.md

# ActiveRecord для `Tarantool/Octopus/Postgres`

`cmd/argen/main.go` - генератор кода моделей для БД

Генерирует схему пакеты в соответствии с декларативным описанием БД. Используется паттерн `Active Record`, как подход доступа к данным в БД. Таблицы/спейсы базы данных или представление описанные в файлах оборачивается в пакеты.

Аргументы командной строки:

- --path - путь к модели (описание модели должно быть вложено внутрь этого пути), путь не может начинаться с `.`
- --fixture_path - путь к папке в которую попадут сгенерированные файлы доступа к тестовым фикстурам, путь не может начинаться с `.`
- --declaration - путь к папке где находятся файлы с декларативным описанием схемы БД, по умолчанию `declaration`
- --destination - путь к папке в которую попадут сгенерированные пакеты, по умолчанию `generated`
- --module - имя модуля(приложения) внутри которого генерируются пакеты, по умолчанию берётся из `go.mod`

!**Важно**

- Имя пакета в описании модели должно быть `repository`.
- Все файлы .go по указанному пути будут удалены при перегенерации
- Внутри папки со сгенерированными пакетами находится файл `.argen`, который нельзя удалять, его наличие проверяется при следующей перегенерации.

## Описание модели

```golang
package model

import "......./model/serializer"

//ar:serverHost:127.0.0.1;serverPort:11011;serverTimeout:500
//ar:namespace:5
//ar:backend:octopus
type FieldsFoo struct {
    Id        int32  `ar:"primary_key"`
    Name      string `ar:"serializer:Json;size:256"`
    AnotherId int32  `ar:""`
    Type      string `ar:"selector:SelectByType;size:64"`
    Product   uint64 `ar:"serializer:Product"`
    Flags     uint32 `ar:"mutators:set_bit,clear_bit"`
}

type (
    IndexesFoo struct {
        TypeId bool `ar:"fields:Type,Id;unique"`
    }
    IndexPartsFoo struct {
        TypePart bool `ar:"index:TypeId;fieldnum:1;selector:SelectByTypePart"`
    }
)

type SerializersFoo struct {
    Json    map[string]interface{} `ar:""`
    Product *serializer.Product    `ar:"pkg:......./model/serializer;object:ProductS"`
}

type TriggersFoo struct {
    RepairTuple bool `ar:"pkg:......../test/model/repair;func:RepairTuple"`
}
```

Все данные для доступа к БД хранятся в комментариях и тегах.

## Комментарии к структуре `Fields*`

Все данные для доступа к БД, а так же тип БД хранится в комментариях к структуре `Fields*`
Все комментарии должны начинаться с префикса `ar:`

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

### serverHost

IP адрес или имя хоста, где запущена БД

### serverPort

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

### serverTimeout

Таймаут при работе с БД

### namespace

Номер спейса если используется `octopus` (`tarantool 1.5`). При вызове функции/процедуры содержит имя процедуры

### backend

Тип базы данных где храниться данная модель. В будущем можно будет указать много `бекендов` для переезда с одного хранилища в другое.

### shard_by

Определят функцию выбора `шарда`. Используется для новых записей для получения если запрос делается по ключу указанному в `shard_by`

!Не реализовано

### serverConf

Вся конфигурация хранилищ построена вокруг `шардов`. У каждого `шарда` есть мастера и реплики.
Более подробно см. в разделе использование конфига

## Структуры для описания модели

### Fields* (поля модели)

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

- `primary_key` - является ли поле первичным ключом, всегда уникальный, флаг `unique` можно не указывать;
- `unique` - уникальный ли индекс (по умолчанию - неуникальный);
- `selector` - имя метода-селектора, который нужно создать для соответствующего индекса;
- `serializer` - позволяет навесить дополнительную сериализацию на поле; Формат: `Name[,params]`. Параметры необязательные, но если их указать то они будут переданы в функции `marshal`, `unmarshal`
- `size` - длина поля в байтах (для числовых полей вычисляется автоматически). Используется при десериализации и при прогнозировании потребляемого объёма.
- `mutators` - список методов-модификаторов, которые нужно создать для поля для выполнения спец-операций. Предопределены типы мутаторов: `inc`, `dec`, `and`, `or`, `xor`, `set_bit`, `clear_bit`. Но также возможно описать пользовательский тип мутатора. У каждого поля может быть несколько преопределенных мутаторов, но не более одного пользовательского
!Внимание! По умолчанию поля с сериализацией не попадают в список на обновление при изменении внутреннего состояния десериализованной структуры и как следствие не уходит в БД при Update. Но можно описать подобное поведение с помощью пользовательского типа мутатора

#### Для octopus

Порядок, в котором перечисляются поля важен и должен строго соответствовать порядку полей в тупле:

- номер поля в тупле вычисляется автоматически на основании порядка объявления полей в модуле;
- тип поля связан с типом данных полей структуры
- если в тупле оказывается полей больше, чем описано, то они попадают в специальное поле extraFields
- если в тупле полей меньше, чем описано, то вызывается `repairTrigger`

### FieldsObject*

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

- `key` - имя поля в привязываемом объекте
- `object` - имя связанного объекта
- `field` - имя поля в текущем объекте
- `shard_by` - функция, по которой можно определить в каком шарде храниться запись; Если указать `*` то поиск будет производиться по всем шардам. (!Не реализовано)

### Indexes*

Применяется для описания индексов (как правило, мульти-колоночных, так как одно-колоночные проще описывать прямо в `Fields*`). Доступны следующие опции:

- `fields` - список участвующих в индексе полей;
- `unique` - уникальный ли индекс (по умолчанию: неуникальный);
- `primary_key` - индекс является первичным ключом;
- `selector` - имя метода-селектора, который нужно создать для индекса;
- `orderdesc` - поля отсортированные в индексе в обратном направлении. Необходимо только для генерации конфига для `octopus`;
- `shard_by` - функция (или имя метода), используемая для вычисления шарда на основании данных полей индекса (!Не реализовано);

Для octopus-а:

- номер индекса, автоматически вычисляется на основании порядка объявления индексов;

Порядок в котором перечисляются индексы (в том числе неявно в `has_field`) важен и должен совпадать с порядком индексов в конфиге octopus-а.

### IndexParts*

Применяется для создания возможности делать выборки по части мульти-колоночного индекса. Допустимые параметры:

- `index` - имя мульти-колоночного индекса;
- `fieldnum` - количество используемых полей мульти-колоночного индекса (по умолчанию: 1);
- `selector` - имя метода-селектора, который нужно создать для индекса;

### ProcFields* (описание модели вызова функции/процедуры)

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

- `input` - обязательный для всех входных параметров в сигнатуре вызова;
- `output` - обязательный для всех выходных параметров в сигнатуре;  Для БД поддерживающих inout параметры возможно комбинировать с `input`. Формат: `output[:orderNum]`.
Где [orderNum] - необязательный порядковый номер параметра, по умолчанию параметры следуют в порядке перечисления 
- `serializer` - позволяет навесить дополнительную сериализацию на поле; Формат: `Name[,params]`. Параметры необязательные, но если их указать то они будут переданы в функции `marshal`, `unmarshal`
- `size` - длина поля в байтах для возможности валидации (в реализации для octopus не используется)

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

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

- входные параметры могут быть только строкового типа
- входные параметры для списка строк должны иметь сериализатор в строку
- сериализаторы для входных параметров в методе marshal должны возвращать типы string или []string 
- номер поля выходного параметра в тупле вычисляется автоматически на основании порядка объявления полей выходных параметров в модуле;
- если кол-во полей в тупле оказывается меньше чем кол-во перечисленных выходных параметров, то оставшиеся поля останутся пустыми

Для вызова процедур у octopus входные параметры могут быть только строкового типа. Поэтому в качестве типа входного параметра можно указывать только строку (включая []byte)
Но можно объединять входные параметры в структуры используя сериализатор (см. [примеры](https://github.com/mailru/activerecord-cookbook/blob/proc-example/example/model/repository/declaration/foo.go).
Или список при наличии у параметра сериализатора. В этом случае при вызове процедуры будут передаваться строковые параметры в последовательности которую вернет сериализатор

### Serializers*

Объявление дополнительных сериализаторов для полей. Когда не хватает обычных типов и необходимо работать, например, со словарями, то можно объявить сериализатор, который будет применяться для определённого поля. Тип сериализатора переопределяет тип поля внутри объекта. Допустимые параметры в тегах:

- `pkg` - указывает на пакет в котором находится определение сериализатора. По умолчанию `github.com/mailru/activerecord/pkg/serializer`. Пакет не обязательно импортировать, импорт добавиться автоматически.
- `marshaler` - функция сериализации данных, на вход функция принимает параметры указанные при объявлении сериализатора и переменную с типом поля к которому привязывается сериализатор, на выход ожидается тип указанный в сериализаторе. Имя по умолчанию `Name + "Marshal"`
- `unmarshaler` - функция десериализации данных, на вход функция принимает параметры указанные при объявлении сериализатора и переменную с типом сериализатора, на выход ожидается тип поля к которому привязывается сериализатор. Имя по умолчанию `Name + "Unmarshal"`

В пакете `go-activerecord` есть встроенные сериализаторы:

- `Json` - позволяет хранить в БД строку и десериализовывать ее в кастомный тип пользователя, под капотом использует стандартный пакет encoding/json
- `Printf` - позволяет хранить в БД строку в определённом формате подобном `printf`, обязательно указывать формат в определении поля, см. `serializer` в структуре `Fields`
- `Mapstructure` - позволяет хранить в БД строку и десериализовывать ее в кастомный тип пользователя с возможностями библиотеки mapstructure см. https://pkg.go.dev/github.com/mitchellh/mapstructure

### Mutators*

Объявление пользовательских мутаторов для полей. Когда необходима особая логика модификации полей, которую нельзя реализовать с помощью стандартных операций, например при изменении внутреннего состояния десериализованной структуры
Данная логика модификации реализуется на стороне БД с помощью функций/процедур. Сигнатура вызова процедуры следующая:

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

При указании мутатора для сериализуемого (составного) поля, для каждого поля сериализуемой структуры генерируется дополнительный метод установки значения.
Для формирования параметров вызова функций/процедур нужно реализовать функцию преобразования. Функция принимает на вход 2 параметра: значение поля до модификации и набор модифицированных значений полей составной структуры
В случае сериализуемого второй второй параметр содержит значения полей сериализуемой структуры внутри `map[string]any`

- `pkg` - Для сериализаемых(составных) полей указывает на пакет в котором находится функция преобразования в параметры. В `octopus` для простых(несериализуемых) полей не требуется.
- `update` - имя функции/процедуры БД которая будет использоваться модификации данных.
- `replace` - имя функции/процедуры БД которая будет использоваться модификации данных. В `octopus` не реализована


Пример описания мутатора для сериализуемого поля
```golang
package ds

type Bar struct {
  Name      string
}

package model

type FieldsFoo struct {
    Bar   string `ar:"serializer:Bar;mutators:BarPart;"`
}

type SerializersFoo struct {
  Bar *ds.Bar    `ar:"pkg:......./model/serializer;object:BarS"`
}

type MutatorsFoo struct {
  BarPart bool `ar:"update:updateBar;pkg:......./model/conv;"`
}

package conv

func FooBarPart(bar *ds.Bar, partBar map[string]any) ([]string, error) {
  values, err := serializer.Marshal(partBar)
  if err != nil {
    return nil, err
  }
    
  return values
}
```


### Triggers*

Триггеры срабатывают на определённые исключительные случаи при запаковке/распаковке данных и/или при ошибках работы с БД. В каждом конкретном случае в триггер приходят свой набор данных.

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

- `pkg` - имя пакета в котором находится функция обработчик
- `func` - функция обработчик, которая будет вызвана в случае наступления данного события

Доступные триггеры:

Название | Сигнатура функции | Описание
--|--|--
TupleRepair | `func(tuple *octopus.TupleData) error` | Вызывается в случае проблем с десериализацией данных полученных из БД. Например, неверное число полей в тупле по отношению к описанию или неверный формат поля.

В случае если запись была исправлена то поле `Repaired` у структуры принимает значение `true`.

## Использование конфига

Параметры конфигурации строятся относительно `serverConf`. Дерево конфигурации выглядит так:

- `max-shard` (Количество `шардов`. Автоматический решардинг не предусмотрен. Этот параметр менять с крайней осторожностью! НЕ РЕАЛИЗОВАННО!)
- `Timeout` (Таймаут по умолчанию для всех подключений в этом кластере)
- `PoolSize` (Размер пула соединений по умолчанию для этого кластера )
- `1` (Конфигурация для первого `шарда`. Аналогично указывается для всех остальных)
  - `Timeout` (Таймаут для конкретного `шарда`)
  - `PoolSize` (Размер пула соединений для этого `шарда`)
  - `master` (Список серверов являющихся мастерами (`rw`), разделённые запятой)
  - `replica` (Список серверов являющихся репликами (`ro`), разделённые запятой)

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

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

- `Timeout` (Таймаут по умолчанию для всех подключений в этом кластере)
- `PoolSize` (Размер пула соединений по умолчанию для этого кластера )
- `1` (Список серверов `rw` указывается непосредственно тут)
  - `Timeout` (Таймаут для конкретного `шарда`)
  - `PoolSize` (Размер пула соединений для этого `шарда`)

В случае если `шард` только один то можно упростить еще больше:

- `Timeout` (Таймаут по умолчанию для всех подключений в этом кластере)
- `PoolSize` (Размер пула соединений по умолчанию для этого кластера )
- `master` (Список серверов являющихся мастерами (`rw`), разделённые запятой)
- `replica` (Список серверов являющихся репликами (`ro`), разделённые запятой)

В случае когда только мастер и только для одного `шарда`, то `ip:port` складывается непосредственно в serverConf:

- `Timeout` (Таймаут по умолчанию для всех подключений в этом кластере)
- `PoolSize` (Размер пула соединений по умолчанию для этого кластера )

`Timeout` и `PoolSize` - это опциональные параметры на всех уровнях, чем больше уровень вложенности тем выше приоритет параметра.

## Хелперы для конфигурирования коробки

!Не реализовано

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

и `print_approximate_storage_size`.

### `print`

Для этого режима можно задать форматирование `-format`, поддерживается `text` (по умолчанию), `json` - подходит для `puppet`-а

```bash
storage_config -mode print
```

Печатает в `STDOUT` конфиг. Можно скопировать as is.

### `approximate_size`

Печатает в `STDOUT` примерный размер хранилища. Учитывает размер памяти под хранение туплов, их фрагментацию, индексы и их заполнение. В качестве параметра принимает прогнозируемое количество записей. Если среди полей встречаются строки, то используется параметр `size`.

```bash
storage_config -mode approximate_size
```

## Генерация пакета

Для каждого файла формируется структура со всеми полями из БД, плюс дополнительные поля:

- `UpdateOps` - список изменений в объекте, которые будут отправлены при `Update`;
- `ShardNum` - номер шарда, из которого была получена запись; (Пока не реализовано!)
- `IsReplica` - была ли запись получена из реплики
- `Exists` - `true` - когда запись получена из коробки, `false` - когда запись создана при помощи `New`
- `Repaired` - истина если тупл был скорректирован триггером `RepairTuple` влияет на поведение функции `Update`, она в этом случае будет работать как `Replace`
- `Readonly` - запрещены ли над записью операции модификации (кроме update и delete; если справедливо `replica`, то будет справедливо и `readonly`)

Для каждого индекса формируются селекторы

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

Для каждого поля формируются аксессоры `Get...` и `Set...`, доступа к полям напрямую нет.

### Accessors

Для каждого описанного поля в БД формируется пара аксессоров. Геттер с префиксом `Get`, сеттер с префиксом `Set`. Для полей которые участвуют в первичном ключе формируется защита от его изменения, такие поля менять нельзя.

### Selectors

Для каждого индекса формируется набор селекторов. Префикс у селектора - `SelectBy`. Суффикс - используется указанный при описании индекса в поле selector. Если имя селектора не указано, то он является именем индекса или поля если индекс не составной. В итоге получается SelectBy{SelectorName}.

Формируется 2 вида селекторов:

- по одному ключу
- по набору ключей (имеет дополнительный суффикс `s`)

Не путать с уникальными или неуникальными индексами.

При селекте по одному ключу, уникальный индекс возвращает `0` или `1` запись.
При селекте по набору ключей, уникальный индекс возвращает от `0` до `n` записей, где `n` - это количество переданных ключей в селектор.

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

Для всех неуникальных ключей у селектора присутствует дополнительный параметр `limiter` с интерфейсом `activerecord.SelectorLimiter` который ограничивает выборку по неуникальному ключу, и даёт возможность установить `offset`. При селекте по нескольким ключам или по неуникальному полю важно проверять достигли лимита или нет, если это используется для словарей, когда всё надо достать за один поход и важно не пропустить момент, когда лимит достигнут, то необходимо выставить FullfillWarn в true. (!Не реализовано Если селект идёт по ключу в разные шарды то лимит действует на каждый шард! Возвращено может быть limit * shardCount записей!)

```golang
type SelectorLimiter interface {
  Limit() uint32
  Offset() uint32
  FullfillWarn() bool
  fmt.Stringer
}
```

Готовая реализация под этот интерфейс:

```golang
type Limiter struct {
  limit, offset uint32
  fullfillWarn  bool
}

func NewLimiter(limit uint32) Limiter {
  return Limiter{limit: limit}
}

func NewLimitOffset(limit uint32, offset uint32) Limiter {
  return Limiter{limit: limit, offset: offset}
}

func NewThreshold(limit uint32) Limiter {
  return Limiter{limit: limit, fullfillWarn: true}
}
```

Важно! Если в момент селекта по уникальному ключу вернётся больше чем одно значение (такое может случиться при селекте из разных шардов), то будет возвращена ошибка. (!Не реализовано, будет вызван хук в который будут отданы все поднятые объекты, что бы эту ситуацию можно было поправить).

### Mutators (Мутаторы)

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

Генерируемые методы:

Название | Операция
---|---
`SetBit*` | `|= arg`
`ClearBit*` | `&= ^arg`
`Inc*`  | `+= arg`
`Dec*` | `-= arg`
`Or*` | `|= arg`
`Xor*` | `^= arg`
`And*` | `&= arg`

### Создание структуры

При генерации формируется функция `New` создающая новую структуру для модели, используется в случае когда надо создать новую запись с возможностью потом сохранить её в БД.

### Методы управления

`Update` - обновляет представление сущности в БД, важно понимать, что обновляются только поля изменённые в объекте. Нельзя обновить сущность у которой не установлен флаг Exists. (!Не реализовано! После обновления значения полей могут поменяться в зависимости от того, что есть в БД!)

`Insert` - добавление записи в БД, нельзя добавить сущность у которой стоит флаг `Exists`. Если произойдёт пересечение по первичному ключу то метод отдаст ошибку и сущность не будет сохранена в БД.

`Replace` - перезапись всех полей сущности в БД, не только изменённые. Нельзя вызвать у сущности у которой не выставлен флаг `Exists`. Возвращает ошибку если у сущности выставлен флаг ReadOnly.

`InsertOrReplace` - атомарная операция которая позволяет добавить сущность в БД или перезаписать её, если есть пересечение по первичному ключу! Если пересечение не по первичному уникальному ключу, то будет возвращена ошибка.

`Delete` - операция удаления сущности из БД, нельзя удалить сущность у которой не выставлен флаг `Exists`.

### Статистика

Сбора статистики происходит посредством использования интерфейса `activerecord.MetricInterface`.
В процессе работы сгенерированных пакетов, собирается статистика по метрикам:

- временным
  - `select_pack`
  - `select_box`
  - `select_process`
  - `select_newobj`
  - `delete_box`
  - `update_box`
  - `insertreplace_packtuple`
  - `insertreplace_pack`
  - `insertreplace_box`
  - `call_proc`
- статистическим
  - `insert_success`
  - `insertorreplace_success`
  - `replace_success`
  - `update_repaired`
  - `delete_request`
  - `delete_success`
  - `insert_request`
  - `insertorreplace_request`
  - `replace_request`
  - `select_keys`
  - `select_tuples_res`
  - `update_request`
  - `update_success`
  - `update_empty`
- ошибочным
  - `compare_packfield`
  - `delete_box`
  - `delete_pack`
  - `delete_preparebox`
  - `delete_resp`
  - `insert_exists`
  - `insertreplace_box`
  - `insertreplace_obj`
  - `insertreplace_packfield`
  - `insertreplace_preparebox`
  - `insertreplace_prespreparebox`
  - `replace_notexists`
  - `select_box`
  - `select_preparebox`
  - `select_resp`
  - `update_box`
  - `update_notexists`
  - `update_packpk`
  - `update_preparebox`
  - `update_resp`
  - `call_proc`
  - `call_proc_preparebox`

## Пример

### Файл

`model/repository/decl/foo.go`

```golang
package repository

//ar:serverHost:127.0.0.1;serverPort:11011;serverTimeout:500
//ar:namespace:6
//ar:backend:octopus
type FieldsFoo struct {
    Id       string `ar:"primary_key;size:36"`
    Code     string `ar:"size:128;selector:SelectByCode"`
    Email    string `ar:"size:256;selector:SelectByEmail"`
    Start    uint32 `ar:""`
    Finish   uint32 `ar:""`
    Action   uint32 `ar:""`
    Platform string `ar:"size:64"`
}

type (
    IndexesFoo struct {
        EmailCode   bool `ar:"fields:Email,Code;unique"`
        EmailAction bool `ar:"fields:Email,Action;unique"`
    }
    IndexPartsFoo struct {
        EmailPart bool `ar:"index:EmailCode;fieldnum:1"`
    }
)
```


### Запуск генератора

`argen --path 'model/repository' --declaration "decl" --destination 'cmpl'`

В результате его работы будет сгенерирован файл `model/repository/cmpl/foo/octopus.go`

#### Функции

Создание нового пустого объекта - `foo.New`

Пары селекторов (по набору ключей и по единичному ключу, соответственно) по всем индексам

```txt
SelectByIds          SelectById
SelectByCodes        SelectByCode
SelectByEmails       SelectByEmail
SelectByEmailCodes   SelectByEmailCode
SelectByEmailActions SelectByEmailAction
```

#### Методы

Для каждого поля пара методов

```txt
GetId       SetId
GetCode     SetCode
GetEmail    SetEmail
GetStart    SetStart
GetFinish   SetFinish
GetAction   SetAction
GetPlatform SetPlatform
```

`Delete` - удаление объекта

`Update` - обновление объекта

`Insert` - вставка объекта

`Replace` - перезапись объекта

`InsertOrReplace` - вставка или перезапись

#### Структуры

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

`EmailCodeIndexType` с полями `Email` и `Code`

`EmailActionIndexType` с полями `Email` и `Action`

## Поток преобразования данных

```txt
БД
---              []bytes
                 []tuples
                 [][]fields
                 [][]deserializedFields
Приложение       []structs
                 [][]serializedFields
                 [][]packedFields
                 []PackedTuples
---              []bytes
БД
```

## ToDo

### Описание пакета pkg/octopus

Необходимо добавить документацию к пакету!

### Запрет на поднятие связанных объектов

Есть случаи когда ходить в базу уже недопустимо, например из хелперов подготавливающих объект для АПИ. Или из слоя у которого не должно быть доступа к репозиторию.
Можно завязаться на переменную контекста.

### Описание атрибутов

Добавить атрибуты к описанию

- `sequence` - является ли поле автоинкрементным;
- `sequence_id` - номер сиквенса, по умолчанию совпадает с номером неймспейса;
- `sequence_iproto` - кластер `iproto`, используемый для хранения неймспейса с сиквенсами;
- `sequence_namespace` - номер неймспейса с сиквенсами;
(используется только для прогнозирования объема хранилища);

Поддержать `enum` поля

### Sequence для octopus

Зачастую возникает необходимость сделать поле автоинкрементным. Для этого можно завести (можно даже в отдельно) `tarantool/Octopus` с неймспейсом, в котором будут храниться текущие значения всех сиквенсов. При этом удобно, чтобы для автоинкрементных первичных ключей номер сиквенса (значение первичного ключа в этом неймсейсе) совпадал с номером неймспейса. Все прочие сиквенсы лучше нумеровать откуда-нибудь от миллиона. Для автоматического использования этой возможности достаточно указать при объявлении поля параметр `sequence => 1`. Но, разумеется, если настройки кластера `iproto` и номер неймспейса для коробочки не указаны глобально, то придется указать и их. Чтобы задать эти настройки глобально можно (но не рекомендуется) сделать примерно следующее:

Для Octopus перед первым применением сиквенс необходимо инициализировать в хранилище сиквенсов.

### Тестовая среда

//cloud-58  посмотреть и начать использовать

### Ссылочные данные и UpdateOps

Если используются сериализаторы, которые превращают данные из БД в ссылочный тип в `golang` то при изменении внутренностей этого ссылочного типа поле не будет обновлено при вызове метода `Update`. Можно всегда такие поля обновлять не думая обновляли их или нет. Можно оставить это на усмотрение разработчика. а можно в сериализатор пропихивать функцию, при вызове которой поле будет помечаться грязным и пусть каждый живёт с этим как может.

# Тестовые фикстуры для сгенерированной модели ActiveRecord
Нужны для создания объектов данных в интеграционных тестах.

`cmd/argen/main.go` при наличии ключа fixture_path генерирует в папку по этому пути в пакете `fixture` файлы доступа к фикстурам данных, 
описываемых в одноименных с именами сущностей файлах, которые должны находится в папке `{fixture_path}/fixture/data`
Доступ к фикстурам осуществляется по первичному ключу описанному в структуре модели

Если файлы не были созданы предварительно генератор создает пустые yaml файлы для всех сущностей описанной модели.
Именование полей модели в yaml файле в формате snake case. Подсмотреть на [примере](https://github.com/mailru/activerecord-cookbook/tree/main/example/testutil/fixture)

## Примеры использования фикстур
## Update

```golang
package test

import (
  "context"
  "github.com/mailru/activerecord-cookbook/example/testutil/fixture"
  "github.com/mailru/activerecord/pkg/octopus"
)

func sometest() {
  triggerFunc := func(fixtures []octopus.FixtureType) []octopus.FixtureType {
    /* any trigger logic */
    return fixtures
  }

  // 1) hand-made fixture
  updateHandMadeFixture, isUsed1 := fixture.UpdateRewardFixture("primary-code-1").
    WithUpdatedPartner("some-partner").
    /* another updated fields ... */
    OnUpdate(triggerFunc).
    Build(context.TODO())

  // 2) fixture from reward_update.yaml:
  //	  - code: primary-code-2
  //        update_options:
  //         - partner:
  //              set_value: sobakamiloru
  //         - description:
  //              set_value: null

  updateFixtureFromYaml, isUsed2 := fixture.GetUpdateRewardFixtureByCode(context.TODO(), "primary-code-2", triggerFunc)

  //... run test

  // проверка того что фистура была использована
  assertTrue(isUsed1(), "fixture must be applied")
  assertTrue(isUsed2(), "fixture must be applied")
}
```

# Insert \ InsertOrReplace \ Replace
```golang
package test

import (
  "context"
  "github.com/mailru/activerecord-cookbook/example/testutil/fixture"
  "github.com/mailru/activerecord-cookbook/example/model/repository/generated/reward"
  "github.com/mailru/activerecord/pkg/octopus"
)

func sometest() {
    triggerFunc := func(fixtures []octopus.FixtureType) []octopus.FixtureType {
      /* any trigger logic */
      return fixtures
    }
	
    // 1) hand-made fixtures
    model := reward.New(context.TODO())
    model.SetPartner("some-partner")
    /* another setFields fields ... */
	
    insertHandMadeFixture, isUsed1 := fixture.GetInsertRewardFixtureByModel(context.TODO(), model, triggerFunc)
    replaceHandMadeFixture, isUsed2 := fixture.GetReplaceRewardFixtureByModel(context.TODO(), model, triggerFunc)
    insertOrReplaceHandMadeFixture, isUsed3 := fixture.GetInsertOrReplaceRewardFixtureByModel(context.TODO(), model, triggerFunc)

    // 2) fixture from reward_insert_replace.yaml:
    //- code: 64G_android
    //  services:
    //    flags:
    //      UFLAG_PAID_ACCOUNT: true
    //      UFLAG_PAID_UPLOAD: true
    //    quota: 6.8719476736e+10
    //  partner: android
    //  extra:
    //    prepaid: true
    insertFixtureFromYaml, isUsed4 := fixture.GetInsertRewardFixtureByCode(context.TODO(), "primary-code-1", triggerFunc)
    replaceFixtureFromYaml, isUsed5 := fixture.GetReplaceRewardFixtureByCode(context.TODO(), "primary-code-1", triggerFunc)
    insertOrReplaceFixtureFromYaml, isUsed6 := fixture.GetInsertOrReplaceRewardFixtureByCode(context.TODO(), "primary-code-1", triggerFunc)
  
    //... run test
    
    // проверка того что фистура была использована
    assertTrue(isUsed1(), "fixture must be applied")
	// ...
    assertTrue(isUsed6(), "fixture must be applied")
}
```