doc(README): add info

Author: emptybutton

README.md

@@ -21,18 +21,67 @@ docker pull n255/tgdb:0.1.0-slim
 > 
 > В противном случае ваши данные могут быть удалены, а аккаунты забанены. 
 
+## Запуск
+
+Для запуска сервера нужно передать путь yaml конфига через переменную окружения `CONFIG_PATH`.
+
+Пример конфига:
+```yaml
+conf:
+  uvicorn:
+    host: "0.0.0.0"
+    port: 8000
+
+  api:
+    id: 23598539
+    hash: "6d9d7305ffc6f148dab120d24541b127"
+
+  clients:
+    bots: "/etc/tgdb/clients/bots"
+    userbots: "/etc/tgdb/clients/userbots"
+
+  horizon:
+    max_len: 800
+    transaction:
+      max_age_seconds: 30
+
+  message_cache:
+    max_len: 100_000
+
+  heap:
+    chat: -1000000000000
+    page:
+      max_fullness: 0.8
+
+  relations:
+    chat: -1000000000000
+
+  buffer:
+    chat: -1000000000000
+    overflow:
+      len: 5000
+      timeout_seconds: 0.1
+```
+
+> [!IMPORTANT]
+> С этой конфигурацией один сервер будет потреблять максимум 200MB памяти без учёта обработки входящих запросов.
+
 ## Overview
 `tgdb` - это СУБД хранящая данные в чатах телеграмма и предоставляющая доступ к ним в виде реляционной модели и ACID транзакций.
 
-Всё взаимодействие с Telegram происходит через ботов/юзерботов, которые имеют фиксированные [лимиты](https://limits.tginfo.me/en) для отправки запросов в некотором промежутке времени и фактически являюстя арендой очень маленького кусочка инфраструктуры Telegram-а.
+Всё взаимодействие с Telegram происходит через ботов/юзерботов, которые имеют фиксированные [лимиты](https://limits.tginfo.me/en) для отправки запросов в некотором промежутке времени и фактически являюстя арендой очень маленького кусочка инфраструктуры Telegram-а, поэтому они считаются IO ресурсами, такими, как например пропусктная способность сети.
 
-Из-за специфичных лимитов, операции над сообщениями имеют слишком разную цену, чем у операций, которыми можно обращатся с памятью или дисковым пространством, что требует альтернативных решений даже над простыми вещами, которые имеют устоявшиеся подходы:
-- Все операции можно выполнять за константное время (обычно от 200мс до 400мс), но чтение гораздо дороже операций записи, из-за того что читать сообщения могут только юзерботы. 
-Для регистрации юзерботов нужен отдельный номер (а по закону РФ одно физ. лицо может иметь только 20 номеров любых провайдеров), когда для обычных ботов нужно только регестрация у BotFather.
+Из-за специфичных лимитов, операции над сообщениями имеют слишком разную цену, чем у операций, которыми можно обращатся с памятью или дисковым пространством:
+- Все операции можно выполнять за константное время (обычно от 200мс до 400мс), но чтение гораздо дороже операций записи, из-за того что читать сообщения могут только юзерботы. Для регистрации юзерботов нужен отдельный номер (а по закону РФ одно физ. лицо может иметь только 20 номеров любых провайдеров), когда для обычных ботов нужно только регестрация у BotFather.
 - Несмотря на сложность создания юзерботов, можно читать сразу много сообщений за одно обращение, а писать новые сообщения можно только по обращению на каждое новое сообщение.
 Обновления само по себе является записью, но для него первоначально необходимо найти то сообщение, которое нужно обновить.
 Удалять можно сразу много сообщений, которых также необходимо найти, но в отличии от обновления, удалять можно сразу много сообщений за одно обращение.
 
+## Отношения
+На данный момент можно только создавать отношения без возможности миграций. Они не поддерживают ограничения, кроме ограничений доменов на размер данных.
+
+Физически кортежи не хранятся сгруппированными по своим отношениям, а располгаются в едином чате - куче. Каждый кортеж хранится в ровно одном сообщении или странице, которая может вместить всего 4096 символа. Из-за этого нельзя создавать отношения с такими схемами, кортежи которых могут не вместится в одну страницу.
+
 ## Операции
 На данный момент можно читать кортежи только до записи, а сама запись возможна только одним bulk запросом вместе с коммитом. В дальнейшем возможно сделать выполнение операторов таким же, как в обычных СУБД, но пока это не сделано.
 
@@ -80,4 +129,24 @@ docker pull n255/tgdb:0.1.0-slim
 </table>
 
 > [!IMPORTANT]
-> Если паралельно выполняются несколько транзакций с разным уровнем изоляции, то у всей группы будут гарантии минимального уровня изоляции.
+> Если паралельно выполняются несколько транзакций с разным уровнем изоляции, то у всей группы будут гарантии минимального уровня изоляции из этой группы.
+
+Дополнительно можно читать кортежи из отношений без транзакций, что по уровню изоляции = **Read Uncommited**, но создаёт меньшую нагрузку на сервер.
+
+Коммиты транзакций буфферизируются и хранятся в отдельном чате, перед тем, как они будут конкурентно записаны в кучу. В случае достаточного количества ботов, это значит, что задержка для транзакции, которая посылает 10 конкурентных запросов на чтение, а после коммит с 10 операторами записи, будет равна трём обращением к телеграму, что в среднем ~= 0.75 секунд.
+
+Буффер хранится на самом сервере и только при переполнении сохранятся в своём чате. В таком случае изменения записанные в буффер переносятся в кучу только после сохранения в чате буффера, что позволяет востанавливатся серверу в консистетное состояние даже в случае любого сбоя и не ограничевает сервер пропусктной способностью в одно обращению к телеграму.
+
+В этом случае скорость выполнения одной транзакции будет ограничена следующими шагами:
+1. Старт транзакции - задержка сети с `tgdb` сервером
+2. Чтение из кучи - задержка сети с `telegram`
+3. Начало коммита - задержка сети с `tgdb` сервером
+4. Ожижание переполнения буфера - `conf.buffer.overflow.timeout_seconds` (в худшем случае)
+5. Сохранение буффера в своём чате - задержка сети с `telegram`
+6. Запись в кучу - задержка сети с `telegram`
+7. Оповещение об успешном коммите - задержка сети с `tgdb` сервером
+
+## Маштабирование
+На данный момент все данные хранятся в одной куче, которая может вмещать только 1 000 000 сообщений (после 1 000 000 Telegram будет удалять сообщения до 500 000), что даже в случае полного заполнения страниц ~= 16 ГБ (включая метаданные) и сам по себе сервер однопоточный.
+
+В таком случае нужно секционировать данные между несколькими серверами практически всегда, даже в случае одной ноды, но сейчас нет встроенных механизмов для этого.